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-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 --example=blank

init 會檢查已安裝的技能是否與 GitHub 上的最新版本一致，並在必要時更新全域技能集。

限制： 永遠不要在 workspace 根目錄執行 hyperframes init；永遠不要在 PROJECT_DIR 內嵌套另一個 hyperframes/；每個 Bash 命令（主代理 + 子代理）都是一個 (cd "$PROJECT_DIR" && ...) 子 shell — 永遠不要直接使用裸 cd。

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

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

決定：這是否需要搜尋？（第一個分支）
- 否 → 選擇一個表單類別（kinetic-type / stat / charts / logo-reveal / lower-thirds）；內容由使用者提供；asset_needs: []。
- 是 → 將一個搜尋計劃輸出到 asset_needs[]（新聞 / 網頁 / 推文 / 圖片；雙極查詢）。具體的搜尋驅動類別（webpage / news / tweet / asset-fusion）將由步驟 2 回傳的內容類型確認，並在步驟 3 最終確定。
寫入一個草稿 shot-plan.json（信封 + 所選表單類別或搜尋意圖 + asset_needs + 一段鏡頭簡報）。結構：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；搜尋驅動類別使用新聞/網頁/推文/圖片搜尋）。如果 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 — 設計（子代理：Director 第 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 — 建構（子代理：Builder，重複使用優先）

調度一個子代理。提示 = 完整的 agents/builder.md + 調度上下文（shot-plan.json、catalog-map.md、該類別的 module.md、references/motion-vocabulary.md、references/builder-contract.md）。重複使用優先：npx hyperframes add <block> + 原地自訂；僅手動撰寫間隙和資產融合的支援功能。輸出符合 HF 合約的 compositions/index.html（暫停的 GSAP 時間線在 window.__timelines 上，class="clip" + 穩定的 id，tl.seek(0)，確定性）。

步驟 5 — 渲染（Bash）

(cd "$PROJECT_DIR" && npx hyperframes render . --skill=motion-graphics -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 搜尋（新聞/網頁/推文/圖片），這是 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            # 中間表示（Director 輸出）
  assets/  assets/index.md  # media-use 輸出（如果已擷取）
  compositions/index.html   # Builder 輸出
  renders/video.mp4

註冊： 在 hyperframes 路由器中 — 新增「以設計為主導的簡短動態圖形」意圖 + Workflow 描述；從 /general-video 中劃分出 motion-graphics 觸發條件；新增反向的請勿使用邊緣。請參閱 motion-graphics-genre.md 第 5-7 節。

動態圖形設計技能