解說影片（Vox 風格）→ HyperFrames
一部約 60 秒的解說影片由 N 個區塊 × 10 秒 組成（60 秒 = 6 個區塊）。區塊 k 的旁白台詞會與區塊 k 的畫面同時播放。工具：.claude/skills/explainer/tools/（$T）。風格指南：references/styles.md。附有來源的完整範例：examples/explainer-eiffel/。
應有的使用感受
就像使用一個精心設計的應用程式，而不是與終端機對話：
- 每次只處理一個階段，然後停下來等待。一個粗體的階段標題，搭配一個合適的表情符號。
- 設定與選項以表格呈現；各區段之間用
---分隔；行文簡短，留有呼吸空間。 - 無內部對話： 絕對不要敘述檔案寫入、工具檢查、時間計算等細節。只在用戶需要操作或有資訊缺失時才發言。
- 任何需要用戶貼上的內容都應放在一個僅包含提示詞的程式碼區塊中；標籤與說明留在區塊外。
第 0 階段 — 靜默檢查（不敘述）
執行 setup/doctor.sh --quiet。如果 videos/ 目錄中已有解說專案（內含 pack.json 檔案），則以「歡迎回來 — 要製作新影片，還是繼續 <最新專案>？」取代第 1 階段的問候。
第 1 階段 — 歡迎 🎬
簡短的歡迎問候，一個 5 列的表格說明運作方式（點子 → 外觀 → 配音 → 場景 → 最終剪輯），然後問一個問題：影片的主題是什麼？。任何粗略的想法都可以，或者輸入 find one 來搜尋本週最佳主題。然後停止。
第 2 階段 — 主題與設定 ⚙️
- 輸入
find one→ 網路搜尋當前熱門話題；提供前 3 名，每個搭配一句話的引子（一個「為什麼/如何」的問題 + 一個令人驚訝的數字 + 為什麼它看起來會很棒）。跳過悲劇與八卦話題。由用戶挑選；切勿替他們做決定。 - 否則，將想法提煉成一句話的角度：一個答案會令人驚訝的問題。
接著顯示一個包含預設值的設定表格；輸入 go 接受所有設定：
| 設定 | 預設值 | 選項 |
|---|---|---|
| 外觀 | collage | collage（大膽的編輯拼貼風格） · diorama（懷舊紙雕紀錄片風格） |
| 圖片 | code | code（自由建構，內建於 HyperFrames） · ai（Higgsfield 或任何生成器） · mixed |
| 長度 | 60 秒 | 30 秒 – 10 分鐘，以 10 秒為一個單位 |
| 長寬比 | 16:9 | 16:9 · 9:16 · 兩者皆產生 |
停止。
第 3 階段 — 研究與腳本（靜默）
建立目錄 videos/<slug>/。為每個論點進行研究： 網路搜尋，並針對兩個獨立來源交叉比對每個數字，保存其 URL。如果來源不一致，則採用安全數值或直接刪除該數據。一個模糊的真實敘述勝過一個精確的虛假敘述，因此絕對不要捏造數字、引言或預測。
為每個區塊撰寫一行旁白台詞，數字要拼寫出來，使用平實的語言：
- Kokoro 語音：每行 22–26 個字。edge-tts 語音：每行 18–20 個字。後續的配音步驟會自動校正偏差。
- 結構：冷開場（最令人驚訝的事實，沒有問候語）→ 利害關係 → 證據（每個區塊一個想法，每個想法都具體明確：一個數字、日期或地點，層層遞進）→ 轉折點 → 結局，並有一個與第 1 區塊呼應的震撼結尾。
- 語調：充滿探究精神、精確、略帶機智。它解釋；它從不推銷。
- 跨區塊的設計：一個反覆出現且會改變的主角物件（塔、貨櫃、硬幣）；一個早期提出、最後回答的問題；一個讓觀眾記住這部影片的揭示時刻。
同時為每個區塊選擇一個標註（螢幕上顯示的數字或兩個字的摘要，長度 ≤ 9 個字元，例如 +15 公分、250 萬、7 年）和一個視覺元素。在程式碼模式下，視覺元素的 kind 可以是 tower 風格的剪影（需改編 SVG）、dots、bars、lean、calendar 或 stat。撰寫 pack.json 檔案（格式見下方）。此時不顯示任何內容。
第 4 階段 — 配音 🎙
| 語音 | 聲音特色 | 引擎 |
|---|---|---|
am_michael | 美式男聲，冷靜紀錄片風格 | Kokoro（離線，預設） |
bm_george | 英式男聲，沉穩有條理 | Kokoro |
af_heart | 美式女聲，溫暖清晰 | Kokoro |
en-US-ChristopherNeural / en-GB-RyanNeural / en-US-JennyNeural | Microsoft 神經網路語音 | edge-tts（免費，線上） |
輸入 samples → 用三種 Kokoro 語音分別為第 1 區塊配音，並傳送音檔。然後停止。
第 5 階段 — 簡報 📋（閘門）
一個訊息包含：
- 一個表格，內容包含：切入角度、主線、外觀、圖片類型、長度/區塊數、長寬比與語音
- 腳本，格式為「區塊 1 … 區塊 N」
- 來源列表
結尾提問：「一切都沒問題嗎？— 或者需要修改任何地方？」 迴圈直到獲得批准。用戶可以改寫任何行。
第 6 階段 — 圖片
code 模式： 直接跳到第 8 階段。每個區塊會變成一個拼貼場景：一個色塊區、紙張紋理、動態增加的標註數字、自行繪製的標記圓圈，以及視覺元素。
ai / mixed 模式：
- 風格設定 🎨： 提供 3 個命名的變體選項，每個搭配一句話說明（相同視覺系統，不同的色調或構圖，參考
references/styles.md）。選定後，提供可貼上的圖片提示詞。 Higgsfield：nano_banana_pro，長寬比與影片相同。在生成前需報價並等待用戶同意。一張圖片鎖定整體風格；它會被附加到每個場景中。 - 場景 🎬： 每個區塊一個訊息（如果用戶要求，也可以一次處理所有區塊）。每個場景會獲得其旁白台詞作為上下文，以及一個基於
references/styles.md中範本建構的可貼上提示詞：STYLE / SCENE / MOTION / AUDIO / AVOID。設定表格：參考圖片 = 風格關鍵幀，10 秒，720p 以上，環境音開啟，儲存為blockNN.mp4。 直接使用 Higgsfield： 使用kling3_0專業版圖生影片功能，搭配風格關鍵幀。需先報價總費用（區塊數 × 點數）。或者，用戶可以在他們喜歡的任何生成器（Veo、Kling、Runway…）中執行提示詞。 - 片段歸檔 📥： 用戶將檔案放入
videos/<slug>/clips/目錄。自動重新命名明顯的變體（Block 1.mp4→block01.mp4）；只有在配對確實模糊時才詢問。沒有片段的區塊會自動回退使用程式碼生成的場景。
第 7 階段 — 檢查片段（靜默）
從每個片段中擷取一個影格並進行檢視。如果風格不符或過於寫實：收緊 STYLE 和 AVOID 的指示，並僅重新生成該區塊。連續兩次失敗表示需要重寫提示詞，而不僅僅是更換隨機種子。在 collage 模式下，AI 片段中出現可讀文字視為失敗（文字應存在於我們的標註與字幕中）。
第 8 階段 — 配音與剪輯（靜默）
~/.local/share/hf-kokoro/bin/python $T/voice.py videos/<slug> # 或使用 --engine edge --voice en-GB-RyanNeural
每次錄製的音檔長度必須落在 7.5 到 9.7 秒 之間。工具會列出不符合的片段：重新撰寫這些行的台詞（更短或更長），使用 --only 3,5 參數重新配音，並重複直到所有片段都符合要求。禁止使用時間拉伸。
.venv/bin/python $T/build.py videos/<slug> [--aspect 9:16] # 生成 index.html + assets/mix.wav
cd videos/<slug> && npx --yes [email protected] lint && npx --yes [email protected] render -o raw.mp4
ffmpeg -y -i raw.mp4 -af loudnorm=I=-14:TP=-1:LRA=11 -c:v copy -c:a aac -b:a 192k "../../out/<Title> (16x9).mp4"
lint 指令會警告巢狀結構與密集的軌道。這些是關於 Studio 時間軸檢視的警告，與最終渲染無關，因此可以忽略。但錯誤必須修復。為每個區塊擷取一個影格（snapshot . --at 2.5,12.5,…）並檢查：數字在一行內顯示、標記圓圈圈住數字、字幕不會遮擋畫面。
第 9 階段 — 交付 ✅
傳送 MP4 檔案。接著是一個小表格：主題、長度與長寬比、外觀與語音、來源（連結）。提供選項：生成另一種長寬比的版本、修改任何區塊，或是開始製作一部新影片。
pack.json
{ "title": "…", "angle": "…", "through_line": "…", "look": "collage", "aspect": "16:9",
"voice": { "engine": "kokoro", "name": "am_michael" },
"blocks": [ { "line": "…", "callout": { "big": "+15 cm", "label": "在最熱的日子裡長得更高" },
"visual": { "kind": "bars", "values": [10, 30, 60, 100], "highlight": 3 },
"prompt": "(ai 模式)完整場景提示詞" } ],
"sources": [ "出版社 — 標題: https://…" ] }
同時建立一個人類可讀的 pack.md 檔案（包含摘要、腳本、提示詞、來源）。這是專案的記錄。
規則
- 事實：每個數字至少兩個來源；來源必須隨每部影片一起提供。不允許捏造數據、引言或預測。
- 付費生成必須在報價（模型 × 數量 × 點數）並獲得用戶同意後才能進行（PLAYBOOK #1）。
- 不得生成真實人物的特寫正面臉部；使用中景、剪影或馬賽克條，這樣也能避免被內容審核系統拒絕。
- Vox 風格是致敬。影片中絕對不能使用 Vox 的標誌、名稱或品牌。