faceless-explainer

media-use: 在取得音訊/圖片前，請先呼叫 /media-use 從 HeyGen 目錄中取得背景音樂/音效/圖片。先執行 --adopt 註冊現有素材。詳見 /media-use 技能。

Faceless Explainer to HyperFrames

使用此技能將文字內容轉換為解說影片：選擇設計系統、規劃教學故事，並在 HyperFrames 中逐幀建構。無人物表示所有視覺元素皆在後續步驟中原創產生——沒有擷取步驟，也沒有真實素材庫。

在步驟0之前確認路由。 你是協調者。執行每個步驟，驗證其關卡，然後才繼續。此技能適用於從文字解說主題，沒有產品也沒有網站可擷取。其他意圖請路由至別處：產品發布/宣傳 → /product-launch-video；實際網站導覽 → /website-to-video；GitHub PR → /pr-to-video；現有影片加字幕 → /embedded-captions；短篇無旁白動畫 → /motion-graphics。如果使用者只說「製作影片」或路由不確定，請先閱讀 /hyperframes。

你是協調者。在 videos/<project>/ 中工作。依序執行步驟，並在繼續前通過每個關卡。使用者關卡為步驟0、步驟3和步驟6。除步驟5（你為每個影格分派一個子代理）外，每個步驟都親自執行。請勿在此處放置設計或動畫規則；這些規則位於影格工作者子代理、hyperframes-creative 和 hyperframes-animation 中。

工作流程：步驟0設定 → hyperframes.json；步驟1簡報 → capture/extracted/；步驟2設計系統 → frame.md；步驟3分鏡/腳本 → STORYBOARD.md 和 SCRIPT.md；步驟3.1音訊 → audio_meta.json；步驟4視覺設計 → 豐富的 STORYBOARD.md；步驟5影格 → compositions/frames/NN-*.html 和 index.html；步驟6最終渲染 → renders/video.mp4。

---

步驟0：設定與簡報

目標：鎖定核心影片簡報，並在需要時建立 HyperFrames 專案。

僅在 hyperframes.json 遺失時初始化。以 kebab-case 格式從主題命名 <project>，例如 compound-interest-explained；切勿使用工作區名稱或時間戳。

npx hyperframes init "videos/<project>" --non-interactive --skip-skills --example=blank

在簡報前顯示登入狀態——執行 npx hyperframes auth status 並逐字轉述其輸出（不要改寫或重新詮釋）。 它會報告語音/背景音樂將使用 HeyGen 或本地引擎，以及未登入時的登入方式。如果未登入，請停止並等待使用者選擇——登入，或說「go」/「offline」以繼續使用本地引擎——然後再詢問簡報或其他事項。 將其視為真正的決策點，而非隨意備註；不要將選擇摺疊進簡報問題中，也不要將金鑰寫入每個儲存庫的 .env。（在自主模式下，記錄狀態並繼續離線。）詳見 ../hyperframes-media → Preflight 以取得標準指引。

關卡： hyperframes.json 存在，且角度、長度、長寬比和語言已鎖定；已顯示登入狀態（已登入，或繼續離線）。

---

步驟1：簡報（無擷取）

目標：將使用者的文字摺疊進專案中作為資訊來源。沒有網站擷取，也沒有真實素材——這是無人物解說。

逐字儲存使用者的完整輸入，然後手動建立合成擷取套件：

• capture/extracted/visible-text.txt——完整的文章/筆記/主題/簡報，逐字記錄。這是資訊的來源，而非故事模板（步驟3會重新塑造）。
• capture/extracted/tokens.json——{ "title": "", "description": "", "colors": [], "fonts": [] }。從簡報中填入 title/description。除非使用者明確提供了品牌色或字體，否則將 colors/fonts 留空——若有的話則加入（設計預設會提供完整的色板）。

不要執行 npx hyperframes capture（沒有網址）。不要建立 asset-descriptions.md 或填入 capture/assets/——無人物視覺元素將在步驟4-5中原創，而非擷取。唯一的例外是：如果使用者提供了真實圖片，請將其置於 public/<basename> 下，並在步驟3中註明。

關卡： capture/extracted/visible-text.txt 和 capture/extracted/tokens.json 存在；你能用一句話清楚說明解說的主題和目標受眾。

---

步驟2：設計系統

目標：選擇一個已出貨的影格預設；腳本會將其轉換為此影片的 frame.md + 字幕外觀。

你需要做出一個判斷——選擇哪個預設。閱讀 ../hyperframes-creative/references/design-spec.md 並瀏覽 ../hyperframes-creative/frame-presets/；選擇外觀最符合主題、語氣和受眾的預設。然後執行：

node <SKILL_DIR>/scripts/build-frame.mjs --preset <name> --hyperframes .

腳本會確定性地完成其餘工作：將預設的 FRAME.md 複製為 frame.md，並重新混音到 capture/extracted/tokens.json 中的任何品牌代幣（品牌色按角色映射到預設的顏色鍵；預設的顯示字體+正文字體替換為品牌字體），將預設的字幕外觀複製到 .hyperframes/caption-skin.html，並自我驗證（映射錯誤時退出碼1）。一旦退出碼為0即可繼續——無需手動編輯規格。

無人物解說通常沒有品牌色/字體（tokens.json 的 colors/fonts 為空）→ 腳本會保留預設的色板，這是一個完整的可出貨設計。僅當使用者指定了品牌色/字體時，才在執行前將其加入 tokens.json，並且僅在映射確實需要時才手動調整 frame.md。

關卡： build-frame.mjs 退出碼為0——frame.md 來自指定的預設，且（當預設包含時）.hyperframes/caption-skin.html 作為字幕外觀來源存在。

---

步驟3：分鏡與腳本

目標：將文字轉換為經核准的逐幀教學計劃。

閱讀 references/story-design.md、../hyperframes-core/references/storyboard-format.md 和 ../hyperframes-core/references/script-format.md。使用它們來撰寫 STORYBOARD.md，並在需要旁白時撰寫 SCRIPT.md。

使用 story-design.md 來決定解說結構（概念/教學/清單/故事）、鉤子策略、清晰度技巧、情感節奏、類型枚舉映射和 VO_MODE。影片的順序來自敘事設計，而非輸入文字的段落順序——重新排序、合併、省略、壓縮。無人物視覺元素在後續步驟中原創，因此影格不攜帶素材清單：除非使用者提供了真實的 public/<basename> 圖片，否則將 asset_candidates 留空。使用分鏡和腳本參考中的確切必要欄位。

草稿完成後，顯示逐幀摘要。在同一則訊息中詢問使用者兩件事：(a) 核准或要求修改，以及 (b) 是否想要分鏡框架的即時預覽（npx hyperframes preview）——僅在回答「是」時開啟。迭代直到核准，並將預覽選擇帶到步驟6。

關卡： STORYBOARD.md 存在，每個影格都有必要的敘事欄位，需要旁白時 SCRIPT.md 存在，且使用者已核准逐幀計劃。

---

步驟3.1：音訊

目標：從核准的腳本生成旁白、字詞時間戳、音樂和音訊元資料。

在步驟3核准後開始音訊處理。在背景執行，然後繼續步驟4。（登入狀態已在步驟0顯示；引擎會自動回退。）

node <SKILL_DIR>/scripts/audio.mjs --script ./SCRIPT.md --storyboard ./STORYBOARD.md --hyperframes . --out ./audio_meta.json &

音訊腳本處理旁白、字詞時間戳、從 HeyGen 音樂庫查詢背景音樂以及時間元資料。背景音樂情緒來自分鏡的 music: 欄位。此處使用 HeyGen Audio API 進行檢索而非生成，並使用與 TTS 相同的 ~/.heygen 憑證。有關提供者詳情，請閱讀 ../hyperframes-media/references/tts.md。

如果沒有旁白且沒有 SCRIPT.md，則跳過語音生成。如果分鏡有音樂情緒，背景音樂仍可能執行。

關卡： 音訊工作已開始，或專案標記為無聲。

---

步驟4：影格視覺設計

目標：為每個分鏡影格加入視覺方向、佈局意圖和動畫選擇。

就地編輯 STORYBOARD.md。不要建立另一個分鏡。使用 frame.md 作為顏色、字體、佈局感覺和風格的真相來源。

閱讀 references/visual-design.md、references/composition.md、references/motion-language.md 和 ../hyperframes-animation/。使用 visual-design.md 來了解必要的影格欄位和必要的 ## Video direction 區塊。使用 composition.md 來了解佈局、層級、焦點和原創視覺處理。使用 motion-language.md 和 ../hyperframes-animation/ 來了解有效的效果和藍圖 ID。不要發明效果名稱或藍圖 ID。

對於每個影格，加入必要的視覺和動畫欄位，包括 effects 和 focal 及/或 roles。由於解說是無人物的，focal/roles 描述的是原創視覺元素（一個重點詞、一個圖表節點、一個數據視覺化系列），而非擷取的素材。加入一個全影片適用的 ## Video direction 區塊，用於整體視覺方向、動畫風格、節奏和設計規則。

不要更改故事、腳本、transition_in 或原始文字。不要在此步驟撰寫 HTML。沒有素材準備步驟——無人物視覺元素由步驟5的工作者建構。如果使用者提供了真實的 public/<basename> 圖片，請在相關影格的 focal/roles 中透過路徑引用；否則無需準備。

關卡： 每個影格都有 effects 加上 focal 及/或 roles；## Video direction 存在。

---

步驟5：建構影格

目標：將每個分鏡影格建構為 HTML 合成，並組裝可播放的影片。

如果音訊已啟動，請等待步驟3.1的音訊完成。然後同步持續時間並取得音效；若為無聲則跳過。

node <SKILL_DIR>/scripts/audio.mjs sync-durations --audio-meta ./audio_meta.json --storyboard ./STORYBOARD.md

node <SKILL_DIR>/scripts/audio.mjs fetch-sfx --storyboard ./STORYBOARD.md --hyperframes .

持續時間同步是機械性的：真實語音持續時間優先；無聲影格保留估計值；切勿手動編輯同步後的持續時間。

在分派前，閱讀 sub-agents/frame-worker.md 和 ../hyperframes-core/references/subagent-dispatch.md。為每個影格分派一個子代理，盡可能並行；否則以批次方式執行工作者。每個工作者只處理一個影格。

每個工作者的上下文必須包含 PROJECT_DIR、frame_id、畫布大小、字幕狀態和啟用字幕時的保留區域，以及 ANIM_DIR 作為 ../hyperframes-animation/ 的絕對路徑。每個工作者讀取 frame.md、STORYBOARD.md 中自己的 ## Frame N 區塊，以及每個引用的效果或藍圖 ID 的配方主體。每個工作者只寫入 compositions/frames/NN-*.html。工作者不得編輯 STORYBOARD.md。

當每個工作者返回時，協調者在 STORYBOARD.md 中將該影格標記為 animated。

在音訊時間存在後，在背景建構字幕並組裝索引：

node <SKILL_DIR>/scripts/captions.mjs build --storyboard ./STORYBOARD.md --audio-meta ./audio_meta.json --hyperframes . --out ./caption_groups.json &

node <SKILL_DIR>/scripts/assemble-index.mjs --storyboard ./STORYBOARD.md --hyperframes .

captions.mjs 使用專案的 .hyperframes/caption-skin.html（在步驟2中複製）作為字幕外觀，並從 frame.md 注入品牌代幣；若無外觀則渲染內建預設藥丸形狀。captions: skipped (<reason>) 是有效的。當明確跳過時，繼續進行而無字幕。

關卡： 每個影格都標記為 animated，index.html 存在，且字幕已建構或明確跳過。

---

步驟6：最終化

目標：驗證組裝後的影片，取得使用者核准，並渲染最終的 MP4。

注入轉場、執行檢查、暫停供審查，然後渲染。

node <SKILL_DIR>/scripts/transitions.mjs inject --storyboard ./STORYBOARD.md --hyperframes .

node <SKILL_DIR>/scripts/transitions.mjs verify --storyboard ./STORYBOARD.md --index ./index.html

npx hyperframes lint

npx hyperframes validate

npx hyperframes inspect

npx hyperframes snapshot --at <frame-midpoints>

snapshot 將擷取的影格拼接成一張聯絡表（snapshots/contact-sheet.jpg）。快速瀏覽；如果沒有明顯問題，就繼續——不要在此停留。

如果某個命令失敗，顯示 stderr 並停止——不要堆疊恢復命令。自行修復：對 compositions/frames/NN-*.html 進行最便宜的安全編輯，然後重新執行失敗的檢查。

已知的誤報——不要追查。 inspect 可能會報告少數 text_box_overflow 錯誤，約 1–4px，出現在字幕高亮詞（選擇器 #caption-word-* / .caption-line）上。字幕藥丸使用刻意緊湊的 line-height（在 scripts/captions.mjs 中設定一次），且沒有 overflow:hidden，因此一個粗體顯示字形的墨水會溢出幾像素到藥丸自己的內邊距中——實際上沒有任何內容被裁剪。將這些視為預期行為並繼續。不要放大字幕的 line-height（這會使藥丸膨脹，更糟）。僅當 text_box_overflow 指向一個影格元素（#el-NN-*）而非字幕詞時才採取行動。

檢查通過後，暫停供使用者審查。影片已組裝完成，可在 Studio 中檢視和編輯。在步驟3和步驟6之間只管理一次預覽：如果使用者之前要求過則開啟，如果之前拒絕則提供，如果他們已在 Studio 中審查則不再詢問。

預覽：npx hyperframes preview

僅在使用者核准後渲染：

npx hyperframes render --skill=faceless-explainer --quality high --output renders/video.mp4

除非使用者要求，否則不要在渲染後重新執行 lint、validate、inspect 或 snapshot。

關卡： lint、validate 和 inspect 在渲染前通過；使用者在審查暫停時核准；renders/video.mp4 存在。最終回覆說明 MP4 路徑和最終時長。

---

快速參考

格式： 預設橫向 1920x1080；直向 1080x1920；方形 1080x1080。在分鏡 frontmatter 中設定一次格式。

無人物與擷取素材工作流程的差異： 無步驟1擷取（合成 tokens.json + visible-text.txt）；無 asset-descriptions.md 和 capture/assets/；步驟4無素材準備；asset_candidates 預設為空；所有視覺元素由步驟5的工作者原創（字體排版/抽象圖形/圖表/數據視覺化）。使用者提供的 public/<basename> 圖片是唯一的真實素材路徑。

背景腳本： 工作流程僅提供以下 scripts/ 下的腳本：build-frame 用於採用並重新混音品牌到影格預設中成為 frame.md（+ 字幕外觀）；audio 用於 TTS、轉錄、背景音樂、音效和持續時間同步；captions；transitions 用於注入和驗證；以及 assemble-index。其他一切都是 hyperframes CLI。

閱讀	時機
[../hyperframes-creative/frame-presets/](../hyperframes-creative/frame-presets/)	步驟2：選擇並採用影格預設。
[../hyperframes-creative/references/design-spec.md](../hyperframes-creative/references/design-spec.md)	步驟2：正確應用品牌代幣。
[references/story-design.md](references/story-design.md)	步驟3：規劃解說故事。
[../hyperframes-core/references/storyboard-format.md](../hyperframes-core/references/storyboard-format.md)	步驟3：撰寫 STORYBOARD.md。
[../hyperframes-core/references/script-format.md](../hyperframes-core/references/script-format.md)	步驟3：撰寫 SCRIPT.md。
[../hyperframes-media/references/tts.md](../hyperframes-media/references/tts.md)	步驟3.1：選擇或了解 TTS 提供者。
[references/visual-design.md](references/visual-design.md)	步驟4：豐富分鏡的視覺內容。
[references/composition.md](references/composition.md)	步驟4：判斷構圖。
[references/motion-language.md](references/motion-language.md)	步驟4：判斷動畫語言。
[../hyperframes-animation/](../hyperframes-animation/)	步驟4：引用效果和藍圖 ID。
[sub-agents/frame-worker.md](sub-agents/frame-worker.md)	步驟5：分派每個影格的工作者。
[../hyperframes-core/references/subagent-dispatch.md](../hyperframes-core/references/subagent-dispatch.md)	步驟5：安全地分派子代理。