計畫轉影片
將書面計畫轉換為附旁白的解說影片（社群貼文約 60 到 90 秒，含多項決策的真實計畫約 2 到 2.5 分鐘）：鉤子、問題、提案、運作機制、然後每項待決問題占一個獨立幀（問題加上 2 到 4 個選項），最後是結尾行動呼籲。
此技能並未重新實作 HyperFrames。它決定簡報、故事結構與設定，然後逐步執行已安裝的 /faceless-explainer 工作流程，並在預設流程容易失敗的地方加入修正。請依照 /hyperframes 與 /faceless-explainer 的指示閱讀；本檔案告訴您該回答什麼以及該修補何處。
首次在機器上執行： 閱讀 references/setup.md 並執行其預檢。它會安裝 HyperFrames 技能與本地語音（若缺少）。
設定
在開始時解析下列變數一次，並在每個指令中重複使用。僅在找不到值時詢問使用者。
| 名稱 | 解析方式 | 預設值 |
|---|---|---|
VIDEOS_DIR | 若設定了 $PLAN_TO_VIDEO_DIR 則使用該值 | 目前工作目錄下的 ./videos（faceless-explainer 慣例） |
FE_DIR | 已安裝的 faceless-explainer/SKILL.md 所在資料夾 | 請參閱 references/setup.md 進行查找 |
MEDIA_DIR | 已安裝的 media-use/SKILL.md 所在資料夾 | 同上查找 |
HYPERFRAMES_PYTHON | 環境變數（若設定），否則使用 references/setup.md 的虛擬環境 | ~/.hyperframes-venv/bin/python |
VOICE | 使用者要求，否則記住的語音，否則 | Kokoro am_michael（離線） |
1. 簡報（快速確認，不審問）
先閱讀來源（計畫文件、研究筆記、對話）。然後在一則簡短訊息中提出下列預設值，並僅詢問來源無法回答的項目。快速同意遠勝於一堆問卷。
| 欄位 | 預設值 | 原因 |
|---|---|---|
angle | listicle（路線的值之一：concept, how-to, listicle, narrative） | 一個計畫就是「為何重要、如何運作、N 項決策」 |
故事板 arc | concept-explainer with listicle | 在 STORYBOARD.md 中為自由文字，非簡報列舉 |
aspect | 1920x1080 | 在筆電或通話中觀看；選項卡片需要寬度 |
length | 真實計畫約 2 到 2.5 分鐘；社群貼文約 60 到 90 秒。硬上限 180 秒 | faceless-explainer 的最佳區間為 30 到 90 秒；含多項決策的計畫時間更長。每項決策約 10 秒加上開頭與結尾 |
language / voice | 來源的語言；英文使用 Kokoro am_michael | 本地且免費。非英文 Kokoro 語音需要 espeak-ng |
flow / storyboard | automation / no（自動） | 當計畫事關重大時，提供故事板審查 |
| 視覺風格 | 若影片關於某個儲存庫，則使用該專案自有品牌；否則使用合適的預設主題 | 影片應看起來像它所說明的東西 |
music | none | 本地 MusicGen 需要 torch；HeyGen 音樂需要登入 |
| 專案 | $VIDEOS_DIR/<kebab-topic>/ | 每支影片一個資料夾 |
最多詢問：誰會觀看（決定內容的技術深度），以及是否應在每項決策上標記推薦選項（強調「傾向」邊框）。
推薦選項規則：標記來源推薦的選項。當沒有單一選項勝出時，不標記任何東西；當決策是「支援多個」時，標記屬於該答案的每個選項。當來源未說明時，改為推薦此技能自己的預設值（上表中的值），而不是發明偏好。
BRIEF.md 在第 0 步之後撰寫（在 npx hyperframes init 之後，因為 init 會拒絕非空資料夾），格式如 /hyperframes references/brief-format.md 所述，並將使用者所說與您推論的內容分開。
2. 故事結構
預設弧線，根據來源調整：
- 使用來源的真實數字作為鉤子（「N 個項目中有 M 個是 X」）。每個數字必須可追溯至來源的某一行；切勿虛構統計數據、價格或計數。若來源沒有數字，則以具體痛點開場。
- 2 到 3 個指名原因的問題，附上來源的真實案例。
- 在第 3 幀之前提出論點或提案（先給價值，再給證據）。
- 用一個圖表幀說明運作機制。
- 一個路標（「開始建造前有五項決策」）作為簡短喘息。
- 每個未決問題或步驟一個獨立幀，全部使用相同的問題舞台（
references/question-stage.md）。每幀顯示問題及其 2 到 4 個選項；選項在語音念出時出現。 - 呼應路標的結尾行動呼籲（「回答這五項，第一步本週就能出貨」）。
將旁白寫成簡短的提示短語（每幀 6 到 25 個字詞），使每個選項都有一個詞可以揭示。若決策已在來源中獲得解答，則在強調邊框中顯示已選答案，而非提問。
3. 執行工作流程（含以下修補）
依序遵循 /faceless-explainer 的第 0 到 6 步。在每一步套用 references/gotchas.md 中對應的修補。跳過時會出問題的關鍵項目：
- 第 0 步： 在
$VIDEOS_DIR的父目錄內執行 init，使專案位於$VIDEOS_DIR/<topic>，然後撰寫BRIEF.md。登出 HeyGen 沒關係：語音在本地使用 Kokoro 執行。 - 第 2 步設計： 對於儲存庫，將其顏色和字型放入
capture/extracted/tokens.json，並在**build-frame.mjs之前**將真實的.woff2檔案放入assets/fonts/（它之後會自行撰寫@font-face區塊）。從品牌自己的網站檔案、Google Fonts 下載或node_modules中的字型套件取得字型。若品牌為深色而預設主題為淺色，請在frame.md中反轉角色，替換嵌入字型可能缺少的預設字形，並將屬於其他品牌的預設強調色換成使用者自己的顏色（references/gotchas.md，第 2 步）。 - 第 3.1 步音訊： 除非預設的
python3已能匯入kokoro_onnx，否則在每個音訊指令上傳遞HYPERFRAMES_PYTHON。 - 時間校準： 讓音訊完成並執行
audio.mjs sync-durations之後，再撰寫第 4 步的場景視窗，然後根據audio_meta.json中的真實字詞時間調整每個揭示的節奏。（faceless-explainer 在第 5 步執行 sync-durations；刻意將其提前。） - 喘息空間： sync-durations 將每幀設為其精確語音長度，因此最後一幀與路標會突兀結束。緊接在 sync 之後，編輯
STORYBOARD.md中的- duration:：最終幀 +2 到 3 秒，路標與其他喘息幀 +1 秒。在建立封包之前執行，以便工作人員能根據加寬的視窗製作動畫。 - 字幕文字： 字幕來自音訊的逐字稿，而非
SCRIPT.md，因此產品名稱常被聽錯。在建立字幕之前，比對audio_meta.json（voices[].words[].text）中的單詞列表與SCRIPT.md，並就地修正聽錯的單詞，保留其時間。 - 在第 5 步分派之前： 為每個工作人員提供在第 2 步中暫存的確切字型檔案名稱。封包會省略故事板的
## Video direction區塊與完整的單詞時間，因此將兩者貼入每個工作人員的分派上下文。將問題舞台的共享規格逐字提供給這些幀。禁止使用表情符號。 - 第 5 步： 每幀一個工作人員，當您的代理程式支援子代理程式時可並行（工作人員可使用較快的模型），每個工作人員附上
_role.md、其封包與分派上下文。 - 工作人員完成後： 正規化素材路徑，修正實為錯誤的 lint 警告，執行
check，拍攝快照，檢查連絡表。
4. 品質關卡（全部在渲染前）
npx hyperframes lint報 0 個錯誤。studio_missing_editable_id警告為裝飾性；gsap_repeated_fromto_without_baseline是真實錯誤，請修正它（references/gotchas.md，第 6 步）。npx hyperframes check通過。npx hyperframes snapshot --at <每幀的中點>並實際查看連絡表：深色背景上的深色文字、缺少字型（襯線字體後備）、裁剪的卡片與表情符號 tofu 都會顯示出來。- 若使用者有自家風格（例如「不使用破折號」），檢查每個字串：
- voiceover:行、SCRIPT.md 行、compositions/frames/*.html中的文字，以及標題。使用冒號撰寫標題（## Frame 1: Hook、## Line 1: Hook (Frame 1)）；故事板與腳本解析器都接受此格式，因此永遠不需要破折號。
5. 審查、渲染、交付
faceless-explainer 的第 6 步即使在自動模式也保留一個問題：開啟 npx hyperframes preview --background 並詢問「立即渲染，還是做哪些修改？」。當使用者要求一次性渲染時，跳過該問題。接著：
npx hyperframes render --skill=faceless-explainer --quality high --output renders/video.mp4（--skill 僅標記匿名渲染遙測；high 是 delivery 的別名）
僅在使用者要求時才開啟 MP4（macOS 使用 open，Linux 使用 xdg-open，Windows 使用 start）。報告：MP4 路徑、其實際長度（ffprobe -v error -show_entries format=duration -of csv=p=0 renders/video.mp4）、含 ID 的幀列表（compositions/frames/NN-*.html）以便可單獨修訂某幀、連絡表路徑，以及任何跳過的項目（無音樂、發音錯誤的單詞、因來源缺少而未包含的事實）。
參考檔案
references/setup.md：全新機器安裝與預檢（HyperFrames 技能、Kokoro 虛擬環境、ffmpeg、Chrome）。references/question-stage.md：決策與步驟幀的共享版面規格。將其逐字貼入每個工作人員的分派上下文。references/gotchas.md：環境與流程修正，按工作流程步驟區分，包含指令。