video-craft
將任意主題製成影片。先依內容形態選渲染後端，再走共用的生產流水線。
前身是 anything2explainer（只做 Remotion 科普片）。本次拆分把渲染器無關的資產抽到
core/，把渲染相關的隔離到 backends/，新增 routing/ 做後端選擇。
何時用
- 使用者給出主題要求一條講解/推導/教學/宣傳影片；或給一篇文章要求改成影片。
- 不適用：複刻某條現有影片、真人口播、實拍為主的片子。
四個確認點（必須停下來等使用者回話）
- 時長與語言 + 後端推薦（階段 1 派調研的同時問）：把
routing/router.md的判定結果 和時長表一起給使用者，一問兩答。使用者否決推薦就照他的來。 - 解說詞定稿（階段 2，配音之前）：全文 + 章節劃分 + 字數/預估時長，問「這版文案可以嗎」。 章名與 HUD 小節名單獨列一行。多章片再把每個章界的兩句並排列出。定稿後幀號全變，別改詞。
- 配音（跑
tts_build.py之前）：預設中文 edge-tts 雲希、英文 kokoroam_liam。 有偏好就讓使用者自備 wav 放script/audio.wav，手填時間軸。 - 前 30 秒樣片（階段 5a，派其餘各組之前）：問「風格 / 字號 / 配音語速 / 節奏可以嗎」。 在這裡改是 1 個組的成本，等整片渲完再改是全部組。
流程（8 階段）
階段 0 建專案 → 按路由結果調對應 backend 的 new_project.sh
階段 1 調研 → core/research-brief.md（並行 1 agent） 【確認點 1】
階段 2 解說詞+時間軸 → core/narration-guidance.md + tts_build.py 【確認點 2、3】
階段 3 分鏡 → 按後端的格式寫，core/render_storyboard.py
階段 4 圖元 → 按後端補（remotion: ui.tsx / manim: figures.py）
階段 5a 打樣 → 先做第 1 組，preview.sh 出前 30 秒 【確認點 4】
階段 5b 並行構建 → 各組 1 agent，用後端的 agent-build-rules.md
階段 6 渲染 → 後端的 render.sh → mp4 + fin_frames/
階段 7 QC 與修復 → core/motion_check.py + frame_metrics.py + 後端的 qc-rules
階段 8 交付 → 交付說明.md（記錄所用後端與判定理由）
路由：先選後端
必讀 routing/router.md。 簡短版：
| 內容形態 | 後端 | 狀態 |
|---|---|---|
| 連續公式推導 / 證明 / 符號變形 | manim | ✅ V1 |
| 概念科普講解（X 是什麼 / 怎麼運作 / 為什麼） | remotion | ✅ V1 |
| 真終端操作教學（安裝 / 配置 / 命令執行） | terminal | ⏸ V2 |
| 產品宣傳 / 社交短影片 / PR walkthrough | hyperframes | ⏸ V3 |
判定不是看題材名，是看解說是否在連續操作符號： 「傅立葉變換在幹什麼」→ remotion（講直覺）；「從傅立葉級數推導傅立葉變換」→ manim（連續推導）。
未實現的後端命中時，必須告知使用者並說明降級方案，不能靜默換後端。
前置依賴（新機器必讀）
所有後端
# core/ 的 Python 腳本需要這些。用 3.13 建 venv（3.14 缺 wheel 有風險）
uv venv --python 3.13 ~/.venvs/video-craft
uv pip install --python ~/.venvs/video-craft/bin/python numpy pillow scipy edge-tts
⚠ 沒有這個 venv，
tts_build.py/motion_check.py/frame_metrics.py全都跑不起來。 這是 anything2explainer 踩過的坑：未文件化的 venv 依賴導致新機器上全流程卡死。
remotion 後端
brew install ffmpeg # 抽幀用
# Node 22+；專案由 new_project.sh 自動 npm install
manim 後端
brew install pkg-config cairo pango # pycairo 編譯必需，缺了 manim 裝不上
brew install --cask basictex # MathTex 真公式排版必需；缺了退回 ASCII 近似
不裝 basictex 也能跑（自動
MANIM_TEX=text），但公式只能用a/b這種 ASCII 近似。 推導片必須裝 basictex——公式排版品質是推導片的生命線。
目錄結構
video-craft/
├── SKILL.md ← 本檔案
├── routing/
│ └── router.md 後端判據樹 + 覆蓋機制 + 邊界案例
├── core/ 渲染器無關，所有後端共用
│ ├── research-brief.md 調研流程與事實規則
│ ├── narration-guidance.md 13 條口播文案原則
│ ├── narration-storyboard.md 解說詞/分鏡格式與令牌系統
│ ├── tts_build.py 配音 + timeline.json
│ ├── render_storyboard.py 分鏡令牌替換
│ ├── motion_check.py 節奏 QC（讀幀，跨後端）
│ ├── frame_metrics.py 構圖 QC（讀幀，跨後端）
│ ├── sheet.py 縮圖網格（讀幀）
│ └── lessons.md 踩坑與根因
└── backends/
├── remotion/ 概念科普片（原 anything2explainer）
│ ├── template/ React 工程
│ ├── scripts/ render/preview/still/test_render/new_project/selfcheck
│ ├── reference/ style-guide/motion-vocabulary/composition-and-light/
│ │ agent-build-rules/agent-qc-rules/prompts/math-physics
│ └── examples/rag/ 樣片（品質標尺）
├── manim/ 推導片
│ ├── template/ Python 工程（common/ + scenes/）
│ ├── scripts/
│ ├── reference/
│ └── README.md 環境實測結論（cairo/latex/pycairo）
├── hyperframes/ V3 預留
│ └── README.md
└── terminal/ V2 預留（使用者已確認必做）
└── README.md
核心檔案速查
| 想幹什麼 | 用哪個 |
|---|---|
| 判定該用哪個後端 | routing/router.md |
| 派調研 agent | core/research-brief.md |
| 寫解說詞 | 先讀 core/narration-guidance.md，格式看 core/narration-storyboard.md |
| 生成配音 + 時間軸 | core/tts_build.py |
| 生成分鏡表 | core/render_storyboard.py |
| 節奏 QC | core/motion_check.py |
| 構圖 QC | core/frame_metrics.py |
| 通讀成片 | core/sheet.py |
| 建專案 | backends/<後端>/scripts/new_project.sh |
| 派構建 agent | backends/<後端>/reference/agent-build-rules.md |
| 派 QC agent | backends/<後端>/reference/agent-qc-rules.md |
後端特定的分鏡格式
| 後端 | 分鏡單元 | 格式 |
|---|---|---|
| remotion | 一個鏡頭（一句解說配一個畫面） | backends/remotion/reference/narration-storyboard.md 的 {S12.from-8} 令牌 |
| manim | 一個推導步 | backends/manim/reference/storyboard.md 的 DP 格式 |
QC 閾值按後端調
core/motion_check.py 的預設閾值是為 remotion 概念片定的，其它後端要調：
# remotion（預設）
python3 core/motion_check.py --frames fin_frames
# manim 推導片：靜止上限放寬到 5s（操作後要留時間看清），關掉 hold 判據（無離場概念）
python3 core/motion_check.py --frames fin_frames --shots DP01:1-170 --still-max 5.0 --no-hold
# terminal 教學片（V2）：等命令輸出時靜止更久，預計 8-10s
硬性原則（所有後端通用）
- 原創：畫面全部程式碼繪製或真實錄製；不得使用任何現有影片的幀或片段。
- 事實有出處：畫面上每個數字、術語、年份、人名必須能在調研文件裡找到來源 URL。
- 全片一個示例語境：解說與畫面用同一個貫穿例子。
- 定稿後不改詞：幀號會被硬編碼，改一個字全片重對位。
- 後端要告知：路由判定結果、降級方案，都必須讓使用者知道，不靜默決定。
樣片與品質標尺
- remotion 後端：
backends/remotion/examples/rag/（4′35″，44 句、44 鏡頭） —— 開工前先看examples/rag/frames/overview_*.jpg建立標尺。 - manim 後端：V1 無樣片，只驗證了最小閉環。完整標尺樣片留 V2。
- 反面參照：
backends/remotion/examples/contrast/
從 anything2explainer 遷移來的專案
~/Projects/ai-video/ 下的 linear-function / transformer / a2e-fourier / py-course
都是原 skill 做的，仍用舊佈局（template/scripts/）。它們繼續可用——
原 skill 保留為 deprecated 狀態，不要刪。
新專案一律用本 skill 的新佈局。