說明影片製作技能 (Hellboy)
你將一個技術主題轉變為一部完成的 2–3 分鐘 1080×1920 MP4 影片,讓非技術背景的人在第一次觀看時就能理解。視覺風格、節奏和腳本結構皆從一個參考頻道複製而來(於 docs/01-style-bible.md 中分析)。有兩樣東西是我們刻意保有的:角色 (Hellboy) 和聲音。
你只需撰寫純文字檔案(一份腳本和一個 storyboard.json)。engine/ 中的引擎會處理聲音、字幕、動畫、角色、音樂和渲染。
當使用者只提供一個主題時
請直接完成整個工作,無需提出額外問題:
- 根據主題建立一個 slug(例如
how-dns-works),並執行python engine/make_video.py new videos/<slug>。 - 撰寫
videos/<slug>/script.md(請參考 docs/02),接著撰寫videos/<slug>/storyboard.json(請參考 docs/03 + docs/04)。從examples/upi-explained/中複製模式。 - 執行
python engine/validate_storyboard.py videos/<slug>。修正所有 ERROR,並重複此步驟,直到顯示0 error(s)為止。 - 執行
python engine/make_video.py preview videos/<slug>。如果你能看到圖片,請比對build/preview.png與 docs/06 的 B 節,並進行修正。 - 執行
python engine/make_video.py render videos/<slug>。回覆時請包含路徑output/<slug>.mp4、影片長度以及兩行摘要。
不可妥協的原則
- Hellboy 絕不能重繪。 他只能從
character/hellboy/hellboy.js中取得。你只能設定show、arm(down/point/explain)和expression,除此之外都不行。請將character/hellboy/CHARACTER_BIBLE.md閱讀一次。 - 聲音是固定的,定義在
engine/config.json中。請勿為單支影片更改。 - 長度:旁白 360–470 字,時間 2:00–2:50。 每個句子不超過 20 個字。
- 每個句子都必須讓畫面產生變化。 項目應在其口語對應的關鍵字出現時顯示(使用
"at"參數)。 - 正確比簡化更重要。 寧可省略也不要說錯。
- 驗證器必須通過(顯示
0 errors)才能進行渲染。
工作流程(請依序執行)
| # | 步驟 | 閱讀材料 | 輸出結果 |
|---|---|---|---|
| 1 | 建立骨架 | – | python engine/make_video.py new videos/<slug> |
| 2 | 規劃並撰寫腳本 | docs/02-script-writing.md | videos/<slug>/script.md(360–470 字,7 拍) |
| 3 | 規劃視覺 | docs/03-visual-planning.md | 場景列表:旁白 → 類型、標題、角色 |
| 4 | 撰寫故事板 | docs/04-storyboard-reference.md | videos/<slug>/storyboard.json(或 meta.json + scenes.jsonl → 使用 assemble 組合) |
| 5 | 驗證 | – | python engine/validate_storyboard.py videos/<slug> → 修正直到 0 錯誤 |
| 6 | 預覽 + 品質檢查 | docs/06-qa-checklist.md | make_video.py preview videos/<slug> → 檢查 build/preview.png,修正問題 |
| 7 | 渲染 | docs/05-production.md | make_video.py render videos/<slug> → output/<slug>.mp4 |
| 8 | 最終品質檢查 | docs/06-qa-checklist.md | 分數 ≥ 85,所有 MUST 項目必須通過 |
使用小型/本地模型? 請按照 docs/07-small-model-playbook.md 的步驟進行,以取代步驟 2–5。它將工作拆解為一次只處理一個場景的提示。
7 拍腳本結構(請記住)
鉤子(≤ 22 字:「X 解釋。」/ 「X 實際上如何運作?」/ 令人驚訝的宣稱 / relatable 的行為)→ 緊張(謎團)→ 路線圖(「讓我們跟著……」)→ 主體(3–6 章節:概念 → 平實的解釋 → 日常範例 → 後果;使用一個貫穿全場的範例,並有一個命名的人物)→ 轉折(「但有趣的地方是……」)→ 總結(「所以這樣記住。」每個章節一行)→ 金句(呼應鉤子的片段:「一次掃描。四個參與者。兩秒鐘。」)。
場景配方(請記住)
- 1 個場景 = 1–3 個句子(8–28 字,3–8 秒);每支影片 20–32 個場景。
- 根據
docs/03-visual-planning.md中的決策表選擇visual.type。每支影片使用 7–12 種不同的類型。 - 在 40–70% 的場景中顯示 Hellboy(總是:第一個場景、轉折、總結、最後一個場景)。對於
sequence、hub、diagram、compare類型則隱藏他。 - 使用
"continue": true搭配"shown": true的項目和相同的標題,在 2–4 個場景中逐步建立大型圖表。 - 標題 2–6 個字,包含一個帶有
*accent*標記的詞。螢幕上的標籤 1–4 個字。
指令(從儲存庫根目錄執行)
# 首先啟動虛擬環境: source .venv/bin/activate | Windows: .\.venv\Scripts\Activate.ps1
python engine/make_video.py new videos/<slug> # 範本
python engine/make_video.py assemble videos/<slug> # meta.json + scenes.jsonl -> storyboard.json
python engine/validate_storyboard.py videos/<slug> # 必須為 0 錯誤
python engine/make_video.py preview videos/<slug> # build/preview.png(每個場景一幀)
python engine/make_video.py render videos/<slug> [--fast]
首次在某台機器上使用時:./setup.sh(Linux/macOS)或 setup.ps1(Windows)。完成的影片會放置在 output/<slug>.mp4。
參考資料
examples/upi-explained/(暖紙風格)和examples/load-balancer-explained/(藍圖風格)— 完整的實作範例。請複製它們的模式。templates/—script.template.md、storyboard.template.json。docs/01-style-bible.md— 參考頻道做了什麼、如何測量(規則存在的原因)。engine/icon_names.txt— 所有 2,359 個允許的圖示名稱(Lucide)。