explainer (解說影片) 是做什麼的？

規格檔列出所有場景；腳本負責捕捉素材、配製旁白、為每個場景建立 HyperFrames 子合成，並在發布前進行驗證。

1. understand   閱讀該疑問涉及的程式碼/文件/應用程式
2. capture      scripts/capture.py      截圖、元素框、錄影、遮蔽
3. spec         你撰寫 explainer.json（場景 + 旁白 + 附來源的主張）
4. verify facts scripts/verify.py facts  （門檻：未通過前不得配音）
5. build        scripts/build_explainer.py （配音、字幕、場景；預設無人物）
6. verify       scripts/verify.py all    （素材、建置、渲染、音訊）— 重複直到乾淨
7. render       scripts/render.py

路徑相對於此套件的根目錄：即包含 .claude-plugin/ 的資料夾，位於此檔案的上兩層（請先解析符號連結）。需要公開的 HyperFrames 技能（hyperframes、hyperframes-cli；以及選用的 hyperframes-registry 與 media-use）。在手工編輯生成的合成之前，請先閱讀 hyperframes 一次。

0. 預檢（務必優先執行）

執行 python3 scripts/setup.py doctor（加上 --json 以解析輸出）。它會列出所有相依項目、用途說明、以及適用於此機器的安裝指令；當缺少必要項目時會以退出碼 1 終止。

必要缺少（ffmpeg、Node.js 18+、HyperFrames 技能，以及 ElevenLabs 金鑰或已設定該語音時的 say）：用一句話告訴使用者每項的用途，並建議顯示的指令。僅在使用者同意後才執行該指令。切勿自行輸入或要求 API 金鑰：請使用者在其 shell 中匯出 ELEVENLABS_API_KEY。
選用缺少：向使用者提出一次，並說明每個項目可解鎖哪些功能。Playwright 可提供具元素縮放框與全頁截圖的網頁捕捉；tesseract (OCR) 可對截圖進行機密掃描；ASR（mlx-whisper / openai-whisper）則提供音訊檢查與精確的字詞時間戳記。若使用者拒絕則跳過；對應的檢查會變成手動 review 步驟。
HyperFrames 技能（hyperframes、hyperframes-cli、hyperframes-registry、media-use）：若缺少，建議執行 npx hyperframes skills。在建立或編輯任何合成之前，請先閱讀 hyperframes（如需解決渲染問題也請閱讀 hyperframes-cli）。

設定（首次執行，或使用者想變更某項設定時）

python3 scripts/setup.py show 會顯示目前啟用的設定。若無設定，則訪談使用者（一次一個簡短問題，提供預設值）並寫入設定：

問題	旗標	選項
包含哪些部分？	`--features`	`explainer` 單獨（無需人物檔案），或 `character,explainer` 以啟用主持人
旁白語言	`--language`	ISO 代碼（`en`、`es`……）：選擇清晰易懂的 `say` 語音，並告知 ASR 預期內容
旁白語音	`--narration-voice`	`voice`（設定的供應商）、`say`（免費，macOS）、`none`（僅字幕）
語音供應商	`--voice`	`elevenlabs`（從環境變數讀取 `ELEVENLABS_API_KEY` + `--voice-id`）、`say`、`none`
信用額度限制	`--max-chars`、`--max-seconds`、`--daily-credit-cap`	使用者提供的數值
渲染方式	`--render`	`local`、`cloud`、`preview`
尺寸	`--size`	`1080x1920`（預設）、`1920x1080`、`1080x1080`

python3 scripts/setup.py init --features explainer --voice say --render local --yes

init 會先執行 doctor 並提供相同的安裝選項。若已有設定檔，則會先詢問再覆寫（在非互動模式下傳遞 --force）。setup.py voices --lang <code> 可列出某語言在 macOS 與使用者 ElevenLabs 帳號中的可用語音；--say-voice "<name>" 可選擇特定語音。切勿要求、列印或寫入 API 金鑰。

1. 理解，然後撰寫腳本

先從來源取得事實：閱讀程式碼、PR、文件或應用程式。錯誤的解說影片還不如不做。先展示事物的輪廓再說明細節，用一個真實案例（真實名稱、真實數值）實際走一遍，並讓每個場景只傳達一個概念。
長度（≤ styles.explainer.max_seconds）：3-5 個場景，每個約 6-12 秒，加上片尾標題。TTS 每秒約朗讀 2.4 個字詞：將場景的旁白控制在約 25 個字詞以下。

為此影片選擇風格

此套件僅提供中性的預設值。根據主題、觀眾以及使用者的品牌或偏好，為每個影片挑選一種風格；當涉及品牌、公開頻道或系列時請詢問使用者。不要習慣性地重複前一部影片的樣式。將其放入規格檔的 style 區塊：

鍵	值
palette	`background`、`panel`、`ink`、`muted`、`accent`、`highlight`（CSS 顏色；文字對比度 ≥ 4.5:1）
typography	`font`、`mono`（HyperFrames 內建字型）、`title_scale`（0.6-1.6）
layout	`align`（`left`、`center`）、`radius`（0-60）、`background_style`（`solid`、`gradient`）
motion	`motion`（`calm`、`normal`、`lively`）：每個動作的持續時間與緩動曲線
captions	`caption_style`（`box`、`outline`、`plain`、`none`）、`caption_position`（`bottom`、`top`）

設定檔中的 brand 套件（相同的鍵）會逐鍵覆蓋你的選擇。主持人的設定會沿用影片的背景，除非其區塊有自己的 style（請參閱 talking-clip）。

2. 捕捉素材

python3 scripts/capture.py url http://localhost:3000/login --name login
python3 scripts/capture.py url http://localhost:3000/login --name login --box "#submit"   # 需要 Playwright
python3 scripts/capture.py screen --name settings --interactive
python3 scripts/capture.py record --name signup --seconds 12          # macOS
python3 scripts/capture.py add --name diagram --file ./docs/arch.png
python3 scripts/capture.py redact --name login --box 820,410,360,48   # 或使用 --blur
python3 scripts/capture.py list

url 會在安裝 Playwright 時使用它（--box 與 --full-page 需要），否則使用無頭 Chrome。若無 Playwright，請以像素矩形 [x, y, w, h] 的形式提供焦點框，並從 PNG 讀取（預設縮放比例下為 CSS 像素的兩倍）。若 Playwright 位於虛擬環境中，請透過該直譯器執行腳本（.venv/bin/python scripts/capture.py ...）。--box 會以影像像素記錄元素框，以便場景能直接放大到該位置。預設 --scale 2 可在縮放時保持文字清晰。
捕捉能說明故事的最小區域；將整個桌面縮小放入手機畫面會導致無法閱讀。使用焦點框進行放大。
將整個網站作為一個專案而非單張截圖：npx hyperframes capture <url>（hyperframes-cli）。

3. 撰寫規格

examples/explainer/explainer.json 是一個完整的可運作範例。將規格檔放在素材的根目錄：它參照的程式碼檔案與捕捉結果必須位於規格檔所在的資料夾內。場景類型：

類型	需要	顯示內容
`screen`	`capture`，可選 `focus: [{"box": "#sel" 或 [x,y,w,h], "label": "...", "at": s}]`	螢幕截圖，然後攝影機移動到每個方框，加上重點標示與標籤
`recording`	`capture`（一個影片），可選 `focus`	螢幕錄影（靜音），相同的攝影機移動與標籤
`code`	`file`，`lines: "a-b"`（≤ 24 行，每行 ≤ ~49 字元左右），`highlight: [{"lines": [a, b], "at": s}]`	程式碼顯示在卡片上，逐行出現，關鍵行加註色帶
`diagram`	`nodes: [{"id","label","sub"?,"highlight"?}]`，`edges: [[a, b]]`，可選 `flow: [ids]`	框與箭頭逐步建立，一個 token 沿著 `flow` 移動
`title`	`text`，可選 `sub`、`dur`	片尾或章節卡片

動作效果，適用於任何場景（可選；顏色與時間來自風格，因此請像調整其他外觀元素一樣，根據影片進行調整）：

鍵	說明
`callouts: [{"type": "circle" 或 "arrow", "box": [x,y,w,h] 或 "#sel", "at": s, "note": "..."}]`	手繪風格的圓圈或箭頭，逐漸畫出；在螢幕/錄影場景中為影像像素，其他場景中為畫面像素
`kinetic: [{"text", "at", "dur", "y"?, "from"?}]`	強調效果的彈入文字；謹慎使用（每部影片一或兩次）
`counter: {"to", "from"?, "at", "dur", "prefix"?, "suffix"?, "label"?}`	數字計數動畫，最終停在準確數值
頂層 `transition: "wipe" 或 "fade"`	每次切場的轉場效果（預設 `none`）

它們遵循 registry 中的項目 count-up、caption-kinetic-slam、hw-callout-circle 與 hw-arrow（請見 /hyperframes-registry）。style.hand_font: "Caveat" 會透過 npx hyperframes add 取得該手寫字型。不要讓每部影片都使用所有功能；選擇故事所需要的。

每個含有 narration 的場景都必須附帶 claims：它做出的每個技術陳述，都需要 source（相對於規格檔的 path:lines、capture:<name>、https://...、doc:<name>）以及 status: "supported"（在你根據該來源檢查過後）。"claims": [] 代表該旁白沒有做出任何技術陳述。未經驗證的主張必須修正或刪除，並且不得配音。

預設不包含人物。 解說影片由旁白、字幕與視覺元素構成。僅在使用者要求時，或當你判斷加入主持人能增加價值時（例如有主持人的系列影片、親切的入門引導），才加入主持人，並向使用者說明原因。然後加入 presenter 區塊（intro / outro，每個包含 {"text", "plan"?, "mood"?, "style"?, "claims"}；plan 遵循 talking-clip 格式）並加上 --presenter 參數建置。也需要 features.character。主持人場景也會有字幕（除非規格檔設定 "captions": false）。examples/explainer/explainer-with-presenter.json 是範例。

4-5. 事實驗證關卡，然後建置

python3 scripts/verify.py facts --spec explainer.json
python3 scripts/build_explainer.py --spec explainer.json --project out/explainer --estimate
python3 scripts/build_explainer.py --spec explainer.json --project out/explainer [--confirm] [--presenter]

--estimate 會顯示影片長度與 ElevenLabs 信用額度消耗；在耗費額度之前告知使用者，然後使用 --confirm 建置。建置器也會執行事實驗證關卡，若失敗則停止。字幕會顯示腳本中的原始文字（大小寫、標點、數字），並根據 ElevenLabs 的對齊結果、ASR 或估計值進行時間校準。

6. 驗證（必要的迴圈）

python3 scripts/render.py out/explainer --out out/explainer.mp4 --quality draft
python3 scripts/verify.py all --project out/explainer --spec explainer.json --video out/explainer.mp4

階段	通過條件	若失敗則
facts	每個有旁白的主張都有存在的來源且狀態為 `supported`	檢查來源；修正或刪除該主張
assets	捕捉結果與程式碼在輸出尺寸下清晰可讀；OCR (tesseract) / 文字掃描未發現電子郵件、金鑰、令牌或卡號	加入焦點框或重新捕捉較小區域；`capture.py redact`；將程式碼中的機密替換為佔位符
build	`npx hyperframes check --json` 無錯誤或警告（`verify.ignore_rules` 設定的項目除外）	修正規格檔或產生的合成
render	你已檢視聯絡表（開頭、每個場景切換、場景中間、結尾）：無溢出、重疊、裁切或無法閱讀的文字；視覺效果與旁白相符	修正、重建、重新渲染
audio	對渲染後音訊進行的 ASR 結果與腳本相符（`verify.min_asr_similarity`），且持續時間在限制內	重新生成語音或縮短內容

如何驅動此迴圈：

執行 verify.py all。每次執行算一次迭代（記錄在 <project>/.verify/state.json）。
render 總是先回傳 review：開啟它列出的聯絡表，檢查每個畫面，然後記錄你看到的結果：python3 scripts/verify.py mark render pass --project out/explainer --note "<你檢查的內容>"（或 fail，然後修正）。該標記與那些確切檔案綁定；任何重建都會使其失效。
若未安裝 OCR 或 ASR，則 assets / audio 也會變成 review：用眼睛或耳朵檢查，並在報告中說明。
修正失敗的項目，重建或重新渲染，然後再次執行 verify.py all。退出碼 0 = 可發布。
當迭代次數達到 verify.max_iterations（預設 3）時，會以退出碼 2 終止：停止並告知使用者仍有什麼失敗。切勿在未解決問題的情況下悄悄發布。 刪除 .verify/state.json 以在重大變更後重新計算次數。

VERIFY.md 會顯示數字：掃描的 OCR 影像數量與命中次數、ASR 相似度（含聽到的字詞與預期字詞）、相對於限制的持續時間。請在報告中引用這些數字。場景會自動延長，以便最後一個字幕保持可讀；如果仍有 line_unread 警告，請為該場景增加 min_dur。

在執行腳本時保留使用者的一般 HOME 目錄：使用暫存的 HOME 會導致 npx、Playwright 與 whisper 重新下載所有內容，並破壞 gh/npx 的認證。

數字、縮寫或外語詞彙的音訊不符：在設定中設定 language，並在旁白中以正確發音寫出這些詞彙（例如 "fifteen"、"A P I"）。專案中的 VERIFY.md 即為檢查清單報告；在交付影片時請一併提供其摘要。

7. 渲染

python3 scripts/render.py out/explainer --out out/explainer.mp4 使用 render.backend（local、cloud 或 preview）；render.max_mb 會重新編碼以符合上傳限制。切勿提交 mp4 或 wav 檔案。

explainer (解說影片)