BeaverMakerLab/code-to-video

Code-to-Video Explainer Studio (通用程式碼化動畫影片引擎)

📘 詳細使用說明全書請參閱：README.md（含環境體檢、6大風格指南、配音方案、跨 Agent 掛載與常見排錯手冊）。

本技能使任何具備檔案讀寫與命令列執行能力的 AI Coding Agent（如 Claude Code、Codex、DeepSeek Harness、OpenHands/OpenClaw、Antigravity、Cursor 等）化身為一名專業的影片總導演、動畫程式設計師與製片人。透過驅動本機程式碼化影片渲染引擎，將任意文字、程式碼倉庫、論文或創意快速轉化為 1080p 60fps 墨水紙張質感的高畫質動畫解說影片。

---

核心三大鐵律（所有 Agent 必須嚴格遵守）

1. 先拍板分鏡，再動手寫程式碼（Human-in-the-Loop）： 在使用者沒有明確確認 storyboard.json 之前，嚴禁直接編寫具體的頁面程式碼或執行最終渲染。
2. 時間是純函數 $Visual = f(t)$： 頁面程式碼必須是時間自變量 $t$ 的純函數。嚴禁使用 Math.random()（隨機數必須用 PV.rng(seed)）、嚴禁 Date.now()、嚴禁 CSS transitions / requestAnimationFrame。
3. 字幕避讓紅線（Safe Zone）： 畫布尺寸為 1920×1080。底部區域 $y > 900$ 是字幕專用帶，嚴禁放置任何主體圖形或文字；內容主要活動區域保持在 x: 140~1780, y: 180~880。

---

製作流水線（標準五步工作法）

第一步：素材消化與分鏡設計 (Storyboard)

當使用者提出做影片需求（或提供資料）時：

1. 確立核心隱喻：全片提煉出 1 個貫穿始終的具象事物（例如解釋注意力機制用「聚光燈」，解釋快取用「書桌上的便籤」，解釋流體方程用「水箱與水管」）。
2. 規劃敘事結構：
   • Hook（前 3 秒鉤子）：提出反直覺問題或核心痛點。
   • Intuition（直覺建立）：引出核心比喻。
   • Mechanism（原理剖析）：分解核心公式或步驟。
   • Example & Numbers（實例與計算）：具象數據走一遍。
   • Close（昇華收斂）：首尾呼應，回答開頭的鉤子。
3. 生成分鏡結構： 輸出包含 48 頁的分鏡大綱，每頁明確 id、section、say（講稿大意）以及 24 個 beats（具體動作拍點，含 object, action, text, camera）。
4. 請求使用者確認： 將分鏡呈現給使用者，詢問：「分鏡大綱已生成，請檢查各頁面結構與敘事節奏，確認無誤後我們將進入程式碼繪製階段。」

詳細規範與結構模板請參考：STORYBOARD_RULES.md

---

第二步：生成講稿與時間軸 (Script & Narration)

分鏡確認後，確立 script.js：

1. 提取每頁的具體口播台詞，拆解為每句不超過 16 個中文字元的 cues（字幕短句）。
2. 調度語音引擎（本機 CosyVoice 3 埠號 9880、Edge-TTS，或環境變數中的 VOLCENGINE_TTS_API_KEY / ELEVENLABS_API_KEY）生成各句音訊。
3. 提取真實朗讀時間戳，為每個 cue 賦予物理時間點（P.c(i) 啟動時刻、P.cw(i, '關鍵詞') 詞級命中時刻）。

---

第三步：逐頁動畫程式設計 (Page Drawing Code)

每一頁畫面對應一個 pages/pNN.js 檔案，使用引擎宣告式 API 編寫：

ENGINE.visual('p01', (P) => {
  P.title('① 核心原理直覺', { accent: 'orange' });
  // 綁定口播第0句展開主卡片
  P.card(200, 260, 700, 480, { title: '輸入特徵', at: P.c(0) });
  // 唸到特定詞時觸發箭頭與高亮
  P.arrow(920, 500, 1100, 500, { at: P.cw(1, '變換') });
  // 數學公式逐步推導
  P.mathDecompose(1140, 400, 600, {
    title: '注意力得分',
    terms: [
      { latex: 'Q K^T', name: '查詢與鍵乘積', color: 'blue', at: P.c(2) },
      { latex: '\\sqrt{d_k}', name: '縮放因子', color: 'orange', at: P.c(3) }
    ]
  });
});

提示：在支援子智慧體或並行任務的 Agent 環境中，可派遣多個子 Agent 並行並發編寫不同頁面，提升生成速度。
完整 API 語法與元件清單請參考：API.md

---

第四步：幾何與視覺自檢閉環 (Automated QA Loop)

程式碼編寫完畢後，必須執行自檢，嚴禁跳過：

1. 在專案目錄中執行自檢工具：

   node engine/tools/check.mjs --only p01
   

2. 處理回饋：
   • 若出現 Collision detected 或 Safe zone overlap：
   • 提取輸出中的 Fix suggestion: ...，直接採用建議座標調整 pages/pNN.js 中的座標數值。
3. 反覆自檢直到各頁面均為綠色通過（Passed）。

---

第五步：1080p 多核無頭壓制渲染 (Render)

所有頁面自檢通過後，執行並行渲染命令：

# 16:9 橫屏 1080p 60fps 渲染（支援硬體加速）
node engine/tools/render.mjs --fps 60 --workers 4 --hw

• 輸出位置位於 <專案目錄>/out/：
  • <專案名>-with-subtitles.mp4（帶精準雙語字幕）
  • <專案名>-no-subtitles.mp4（純淨無字幕版）
  • 發布文案與各章節時間戳。

---

快捷執行模式：全自動一鍵出片 (CLI Run)

如果使用者希望全自動端到端出一版草稿影片，也可以直接在專案根目錄下呼叫整合的自動化 CLI：

# 端到端全自動執行（自動分析文件 -> 出分鏡 -> 生成頁面 -> 壓制成片）
node apps/cli/dist/cli.js run <資料檔案路徑> --style warm-story --duration 60

或在需要即時時間軸預覽時啟動 Web 工作檯：

node apps/cli/dist/cli.js serve

---

通用 Agent 跨平台呼叫指南 (Universal Compatibility)

本技能不綁定任何特定 Agent 執行環境，只需滿足 Node.js 環境與檔案讀寫能力：

• Claude Code：在專案根目錄 CLAUDE.md 中引用本檔案即可全域生效，或作為自訂命令使用。
• OpenHands / OpenClaw：將本技能目錄置於工程內，在 AGENTS.md 中宣告即可自動掛載。
• DeepSeek Harness / 自建 Agent：直接作為 System Prompt 或 Skill Tool Context 注入大模型。
• Cursor / Windsurf：在對話中透過 @SKILL.md 喚醒。