motion-graphics

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 resolve（若 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 resolve）	跳過生成 / 僅搜尋
(asset_scout / 搜尋提供者)	webpage/news/tweet + asset-fusion 真實素材搜尋	類別降級為無素材

流程

步驟 0 — 初始化

當前工作目錄為代理工作區根目錄；所有成品寫入 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

限制： 永遠不要在 workspace 根目錄執行 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[]（新聞/網頁/推文/圖片；雙極查詢）。具體的搜尋驅動類別（webpage / news / tweet / asset-fusion）將在步驟 2 中根據回傳的內容類型確認，並在步驟 3 中最終確定。
2. 撰寫草稿 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 — 設計（子代理：導演第 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 . --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            # IR（導演輸出）
    assets/  assets/index.md  # media-use 輸出（若有來源）
    compositions/index.html   # 建置者輸出
    renders/video.mp4
  

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