MatheusEdson/RepoSkillLaxtro

motion-graphics — 調度入口

在步驟0之前先確認路線。 此技能製作一個簡短、設計主導、無旁白的動態圖形（動態即訊息；約少於10秒，無配音）。較長、多場景或帶旁白的製作 → /general-video；網站的旁白影片 → /website-to-video；主題解說 → /faceless-explainer；產品宣傳 → /product-launch-video；在現有影片上加字幕 → /embedded-captions。不包含：即時/渲染時的資料，或無法捕捉的畫面。不確定是動態優先還是旁白？先閱讀 /hyperframes。

一個簡短、設計主導的動態圖形。資產優先：在設計鏡頭之前，先決定資產策略並取得真實素材，然後根據已有的資產設計鏡頭，最後透過重複使用目錄功能來合成。所有成果檔案都放在 PROJECT_DIR = videos/<project-name>/（在步驟0建立）；以下所有路徑都是相對於該目錄。

階段	執行方式	主要成品	詳細流程
init	Bash	hyperframes.json	步驟0
plan	子代理 — 決定是否搜尋？ + 分類 + 資產策略	shot-plan.json（草稿：類別、asset_needs查詢、簡報）	agents/director.md（第1部分）
source ◇	Bash — media-use解析（若 asset_needs 為空則跳過）	assets/ + assets/index.md	phases/source/guide.md
design	子代理 — 根據已解析的資產設計鏡頭	shot-plan.json（最終版：區塊+佈局+動態+位置）	agents/director.md（第2部分）
build	子代理 — 重複使用優先的合成	compositions/index.html	agents/builder.md
render	Bash — hyperframes render（MP4，或 --format webm/mov 用於透明背景）	renders/video.mp4	步驟5
verify	Bash — lint / inspect -> 失敗時由修復子代理處理	（就地修復）	agents/finalize.md

◇ source 僅在選定的類別宣告有資產時執行。純程式碼/文字類別（例如 kinetic-type、大多數 charts/stat）的 asset_needs: []，會直接從規劃跳到設計。

類別 — 根據搜尋決策拆分

plan 的第一個決策是：是否需要搜尋？ 這個分支將類別分為兩組；然後選擇特定的類別 — 對於搜尋驅動的類別，根據搜尋返回的內容類型來選擇。每個類別是一個 categories/<id>/module.md（其規劃與建構規則）；共享的動態詞彙存在 references/motion-vocabulary.md（→ hyperframes-animation 規則/藍圖 + 註冊區塊）。

表單類別 — 無需搜尋；使用者提供內容：

類別	意圖	依賴於
kinetic-type	有衝擊力的句子/引言/標題，動態優先的文字	caption-* 區塊 + 動畫規則
stat	單一英雄數字 / 計數 + 環圈	apple-money-count / rules/{counting-dynamic-scale, stat-bars-and-fills}
charts	長條圖/折線圖/圓餅圖/賽跑圖/百分比資料	data-chart 區塊
logo-reveal	Logo 動畫 / 品牌鎖定（使用者 Logo）	logo-outro / rules/svg-path-draw
lower-thirds	姓名/職稱列、呼叫框、社群覆蓋	caption-* + 註冊覆蓋區塊

搜尋驅動類別 — 先搜尋，然後根據內容類型進行動畫處理（RWA 路徑）：

返回內容	類別	動畫
網頁 / 連結	webpage	網頁 / UI 動畫（滾動、揭示、游標、呼叫框）
新聞文章	news	標題揭示 + 來源卡片 + 關鍵事實呼叫框
推文	tweet	動畫推文卡片
圖片 / 實體	asset-fusion	資產的幾何形狀_變成_圖表（RWA 敘事融合）

建構順序：一次一個，以覆蓋率優先（粗糙也可以）。kinetic-type 從原型移植；其餘依此類推。

先決條件

macOS Apple Silicon 或 Linux x64。系統工具：brew install node ffmpeg。執行一次 npx hyperframes doctor。macOS GPU 渲染：export PRODUCER_BROWSER_GPU_MODE=hardware。

選擇性金鑰（若未設定則使用本地後備）— 僅在透過 media-use 來源/生成資產的類別需要：

金鑰	用途	後備
GEMINI_API_KEY / GOOGLE_API_KEY	圖片生成（media-use 解析）	跳過生成 / 僅搜尋
(asset_scout / 搜尋提供商)	webpage/news/tweet + asset-fusion 真實資產搜尋	類別降級為無資產

流程

步驟 0 — 初始化

cwd 是代理工作區根目錄；所有成果檔案寫入 PROJECT_DIR = videos/<project-name>/。<project-name>：使用使用者給定的目錄名稱，否則根據意圖使用簡短的 kebab-case 名稱（<subject>-motion）。不要使用工作區基名或時間戳。

僅當 $PROJECT_DIR/hyperframes.json 不存在時：

PROJECT_DIR="${MOTION_GRAPHICS_DIR:-videos/<project-name>}"
mkdir -p "$(dirname "$PROJECT_DIR")"
npx hyperframes init "$PROJECT_DIR" --non-interactive --skip-skills --example=blank

限制： 永遠不要在根工作區執行 hyperframes init；永遠不要在 PROJECT_DIR 內巢狀另一個 hyperframes/ 目錄；每個 Bash 指令（主代理 + 子代理）都必須在 (cd "$PROJECT_DIR" && ...) 的子 shell 中執行 — 絕不能直接使用裸 cd。

步驟 1 — 規劃（子代理：導演第1部分）

執行一個子代理。提示詞 = 完整的 agents/director.md + ## Dispatch context（SKILL_DIR / PROJECT_DIR / 使用者的請求 / Schema: <SKILL_DIR>/references/shot-plan-ir.md）。它必須：

1. 決定：是否需要搜尋？（第一個分支）
   • 否 → 選擇一個表單類別（kinetic-type / stat / charts / logo-reveal / lower-thirds）；內容由使用者提供；asset_needs: []。
   • 是 → 將搜尋計劃輸出到 asset_needs[]（news / web / tweet / image；雙極查詢）。特定的搜尋驅動類別（webpage / news / tweet / asset-fusion）將由步驟2返回的內容類型確認，並在步驟3最終確定。
2. 撰寫一個草稿 shot-plan.json（信封 + 選定的表單類別_或_搜尋意圖 + asset_needs + 一段簡短的鏡頭摘要）。Schema：references/shot-plan-ir.md。

驗證：[ -s "$PROJECT_DIR/shot-plan.json" ] && echo ok || echo missing。

步驟 2 — 來源 ◇（Bash: media-use，條件執行）

如果 shot-plan.json.asset_needs 不為空，則解析資產（搜尋 / 生成 / 擷取 → 凍結的專案本地路徑 + 分類帳）。請參閱 phases/source/guide.md（包裝了 media-use resolve；搜尋驅動類別使用 news/web/tweet/image 搜尋）。如果 asset_needs 為空，則跳至步驟 3。

# 說明性 — 請參閱 phases/source/guide.md
(cd "$PROJECT_DIR" && node <SKILL_DIR>/phases/source/resolve.mjs --plan ./shot-plan.json --out ./assets)

優雅降級：如果某個搜尋/提供商不可用，則類別降級為無資產（在 context.log 中記錄）。

步驟 3 — 設計（子代理：導演第2部分）

執行一個子代理（提示詞 = agents/director.md 第2部分 + 包含已解析的 assets/index.md（若步驟2執行）的調度上下文 + catalog-map.md）。它設計鏡頭圍繞可用的資產：選擇目錄區塊 + hyperframes-animation 規則/藍圖、佈局、動態、節拍，以及（對於 asset-fusion）element_positions + 滴管調色盤。最終確定 shot-plan.json（content.block + content.customize + 按類別分類的內容）。

步驟 4 — 建構（子代理：建構者，重複使用優先）

執行一個子代理。提示詞 = 完整的 agents/builder.md + 調度上下文（shot-plan.json、catalog-map.md、類別的 module.md、references/motion-vocabulary.md、references/builder-contract.md）。重複使用優先：npx hyperframes add <block> + 就地自訂；僅手動撰寫空缺部分 + asset-fusion 支援。輸出 compositions/index.html，遵循 HF 合約（暫停的 GSAP 時間軸掛在 window.__timelines、class="clip" + 穩定的 id、tl.seek(0)、確定性）。

步驟 5 — 渲染（Bash）

(cd "$PROJECT_DIR" && npx hyperframes render . -q draft -o ./renders/video.mp4)
# 透明背景變體：--format webm  (或 mov)

步驟 6 — 驗證（Bash → 失敗時由修復子代理處理）

(cd "$PROJECT_DIR" && npx hyperframes lint . && npx hyperframes inspect .)

exit 0 → 完成。若 lint/inspect 出錯，則執行修復子代理（agents/finalize.md：快照 QA + 一次就地修復 + 重新渲染）。修復期間不得更改固定持續時間。

報告 + 可選預覽

報告最終輸出（renders/video.mp4，或 .webm / .mov 透明背景變體）+ 持續時間。執行期間不要開啟預覽。 僅在請求時提供，且在渲染之後啟動，以便提供最終檔案：

(cd "$PROJECT_DIR" && npx hyperframes preview)   # Studio UI；或 `npx hyperframes play` 取得可分享連結

標誌存在於 hyperframes-cli 技能（references/preview-render.md）。

繼續表

狀態	從哪裡繼續
沒有 shot-plan.json	步驟 1（規劃）
shot-plan.json 有 asset_needs，但沒有 assets/	步驟 2（來源）
shot-plan.json 為最終版，但沒有 compositions/index.html	步驟 3/4（設計+建構）
compositions/index.html 存在，但沒有 renders/video.mp4	步驟 5（渲染）+ 步驟 6
renders/video.mp4 存在	報告 + 停止

設計說明（維護者 — 執行時不會讀取此部分）

• 資產優先的邏輯： 來源工作被前置，並為鏡頭設計提供資訊（RWA 流程：分析 → 搜尋 → 檢閱 → 組合）。搜尋驅動類別（webpage/news/tweet）和 asset-fusion 都依賴於 media-use 搜尋（news/web/tweet/image），這是 media-use 已記載的 RWA 傳承。
• 重複使用優先： 生態系統內對應於 LLM 生成模板的做法是「組合目錄區塊 + hyperframes-animation 規則」。HF 的暫停 GSAP 時間軸 ≙ Remotion 的 useCurrentFrame。
• 類別模組合約： 一個 categories/<id>/module.md（規劃 + 建構），共享 references/motion-vocabulary.md（+ 可選評估）。新增一個類別 = 放下資料夾 + 在 agents/director.md 中註冊其分類器行 + 在 catalog-map.md 中註冊其行；階段管道保持不變。
• 目錄結構：

  videos/<project-name>/
    hyperframes.json  context.log
    shot-plan.json            # IR（導演輸出）
    assets/  assets/index.md  # media-use 輸出（若有來源）
    compositions/index.html   # 建構者輸出
    renders/video.mp4
  

• 註冊： 在 hyperframes 路由中 — 新增「設計主導的短動態圖形」意圖 + 工作流程描述；將 motion-graphics 觸發條件從 /general-video 中分離出來；新增反向禁止使用邊。請參閱 motion-graphics-genre.md §5-7。