示範影片 (Demo Video)
在全新的無頭瀏覽器中錄製真實的應用程式（絕不使用模擬或舊影片），使用 Edge TTS 進行旁白解說、嵌入字幕，並渲染為 MP4 檔案。一個示範包含兩個針對其流程編寫的檔案：narration.json 和 flow.cjs；所有其他功能都由本資料夾中的 demo-video-kit 命令提供。可參考的範例位於 examples/todomvc/。
以下 <kit> 代表 node <本資料夾>/bin/demo-video-kit.js（本資料夾例如是 ~/.claude/skills/demo-video）；當用戶的專案已安裝此工具時，使用 npx demo-video-kit 效果相同。執行 <kit> help 可列出所有命令。
請求決定任務
| 請求 | 執行內容 |
|---|---|
| "為 <流程> 建立示範" | 執行下方完整流程，產出放在用戶專案的 demos/<流程>/ 資料夾 |
| "<流程> 的畫面變了，重新製作示範" | 預演新畫面（步驟 2），修正 flow.cjs，若文字不再合適則修正 narration.json；然後執行步驟 4 到 8 |
| "在現有 <流程> 影片中加入高亮框"（不重新錄製） | 在執行中的應用程式內測量框的位置，寫入 annotations.json，執行 <kit> annotate <示範資料夾>（參見高亮框小節） |
| "... 不要高亮" | 省略所有 highlight 選項；其餘不變 |
| "更換語音 / 語速 / 用詞" | 編輯 narration.json（voice、rate、片段 text），然後執行步驟 4 到 8：因為片段長度決定了螢幕上的時間點，所以影片必須重新錄製 |
規則（永遠遵守）
- 真實且全新。 一個新的瀏覽器工作階段；真實的應用程式；真實的資料。絕不偽造結果、數字或狀態；只有在應用程式顯示成功後才能宣告成功。
- 安全。 僅限於本機或測試環境：每次執行都會真實建立該流程所建立的任何內容。絕不列印或儲存憑證：憑證必須來自環境變數（例如
DEMO_EMAIL、DEMO_PASSWORD）；密碼僅顯示為點。如果不知道測試帳號，請詢問一個。 - 畫面。 1920x1080，16:9，30 fps，H.264 + AAC MP4，以無頭模式錄製以確保無畫面裁切。游標可見，會滑動到每個目標並帶有輕微的點擊環；無縮放、無鏡頭移動、無華麗轉場。在對任何元素採取動作之前，先將其完全捲動至畫面內；從上到下緩慢閱讀長頁面，速度要足夠慢以便閱讀。
- 音效。 Edge TTS，預設語音為
en-IN-NeerjaNeural（使用<kit> voices en-或其他過濾條件列出其他語音）。每個旁白片段對應一個音訊片段；音訊片段絕不重疊；旁白僅描述該場景中螢幕上顯示的內容或即將發生的事情。 - 無間隔超過 7 秒。 沒有旁白的時間段不得達到 7 秒。當錄製器發出警告，或
verify.py失敗時，請加長或分割該片段的旁白，或加快其操作速度，然後重新錄製。 - 節奏。 不匆忙：輸入的每個值都必須在可見後才能繼續進行。
- 遵循應用程式。 從執行中的應用程式（預演模式）推導出路徑、標籤和按鈕，絕不依賴記憶。按應用程式顯示的名稱來命名按鈕。
- 輸出檔案不加入 Git。 除非被要求，否則產生的音訊、建構檔案和 MP4 都不提交。
- 高亮。 每個示範都應標記旁白所指的元素，使用紅色框，除非請求明確說「不要高亮」。
高亮框
一個紅色框（4 像素，#E11D48，與元素間距 6 像素）會在影片錄製時即時繪製在頁面上，因此它會跟隨捲動並成為畫面的一部分。預設會加上框的項目包括：導航到該畫面途中點擊的每個選單項目、啟動流程的按鈕、檢閱頁面上的每組已輸入資料，以及最後的提交按鈕。不需要為每個正在輸入的欄位都加框：游標和輸入過程已經顯示了它。
flow.cjs 中的 API：
goto / click / type / pick (loc, ..., { highlight })：highlight: true會為游標將移動到的元素加框；highlight: <定位器>則改為為另一個元素加框（例如其整個行或區塊）。- 一個框會一直保留，直到游標移動到下一個目標。
{ keep: true }會同時保留目前的框；k.clearHighlights()會移除它們；k.highlight(loc)則會新增一個框而不移動游標。 - 每個框都會在
build/timeline-raw.json的marks中新增一個highlight項目。
對於已經錄製好但沒有框的影片，可以使用 <kit> annotate <示範資料夾> 從 annotations.json 事後繪製框。這是一種備用方案；重新錄製更容易且更準確。
工作流程
- 設定。 執行
<kit> doctor（參見設定小節）並確認應用程式在其網址上可以回應。 - 預演。 使用 Playwright 瀏覽器工具，在不錄製且不進行最終提交的情況下走一遍真實流程：記錄每個畫面的路徑、標籤和
getByRole名稱、下拉選項、對話框、最終按鈕，以及按下按鈕後發生的事情。 - 撰寫示範：執行
<kit> init <示範資料夾> --url <應用程式網址>會產生一個可立即執行的起始範本；或複製examples/todomvc/。然後編輯：narration.json：標題、語音、語速、pronounce（書寫文字 → 朗讀發音），以及片段{id, scene, text}。如果一個場景中的動作耗時較長，請將其分割成數個片段，使每個片段的旁白長度大致等於其動作所需的時間。flow.cjs：使用runDemo(__dirname, async (k) => { ... })，每個旁白片段對應一個k.segment(id, async (at, clip) => { ... })。使用k.click / k.type / k.pick / k.goto / k.scrollBy；at(seconds)用於等待片段中的某個時間點（例如clip.cues[0].end）。應等待元素，絕不等待 "network idle"。回傳已驗證的內容。保留require(process.env.DEMO_KIT || 'demo-video-kit')：命令會設定DEMO_KIT環境變數。
- 執行製作。 執行
<kit> run <示範資料夾>（需在環境中設定DEMO_BASE_URL及任何憑證）會依序執行音訊、錄製、渲染和驗證。來自錄製器的每行WARNING，以及來自 verify 的每行FAIL，都違反了規則 5：請修正後重新執行。若僅修改flow.cjs，可使用--from record跳過音訊步驟；若僅修改字幕或編碼，可使用--from render跳過錄製步驟。 - 檢視結果。
build/check/contact-sheet.png：每個影格都應顯示完整畫面、游標、正確的步驟、可讀的字幕，以及旁白所指元素上的框。影片檔案為<示範資料夾>/<資料夾名稱>.mp4。 - 移交。 回報 MP4 的路徑、時長、格式、最長無旁白間隔、此執行建立了什麼，以及任何因應用程式實際運作方式而與請求不符之處。
設定
需要 Node 18+ 和 Google Chrome（或 Microsoft Edge：錄製器會自動改用 Edge，或設定 DEMO_BROWSER=msedge）。在本資料夾中執行一次 npm install；語音（msedge-tts）、ffmpeg（ffmpeg-static）和 playwright-core 會一併安裝，錄製器會在首次執行時下載 Playwright 自帶的小型 ffmpeg。執行 <kit> doctor 會檢查所有項目，包括網路連線（語音功能需要）。
已知陷阱
| 陷阱 | 避免方法 |
|---|---|
| 灰色邊條，頁面底部被裁切 | 絕不在可見瀏覽器視窗中錄製；demo-kit.cjs 會以 1920x1080 的無頭模式錄製 |
waitForLoadState('networkidle') 在輪詢的應用程式上會卡住 | 改為等待某個元素 |
| 無頭 UI 對話框回報為隱藏狀態 | 等待對話框內部的一個欄位，而不是對話框本身 |
| 下拉選單中的 Escape 按鍵會關閉整個對話框 | 選擇一個選項，而不是按下 Escape 鍵 |
| 輸入多個欄位時產生的無聲空白期 | 分割該片段的旁白；type() 接受 { delay } 參數（預設 32 毫秒） |
| 標籤因 CSS 而以全大寫顯示 | 比對真實文字，而非顯示的大小寫 |
| 只對標籤本身加框，而不是其區塊 | 對標籤的父層（xpath=..）或祖父層（xpath=../..）加框 |