Walkthrough video
將正在執行的網路應用轉換為完整的旁白影片，並能在應用更新時重新產生。所有處理都在本地完成：無需影片編輯器，也無需付費服務。
narration text -> local voice -> one WAV per scene + caption timings
real app -> Playwright scenes -> clips + marker times -> assemble.py -> walkthrough.mp4 + .srt
為什麼這樣設計：影片畫面來自真實應用，永遠與實際情況一致；錄製時會自動剪掉緩慢的步驟（如 AI 回覆、頁面載入）；每個場景記錄的「標記」能讓組裝程式在正確的語詞位置對應到關鍵畫面。
開始之前
- 只詢問缺少的資訊：應用程式是什麼、影片必須呈現什麼內容、觀看對象是誰、目標長度（2 到 4 分鐘效果最佳）以及語氣風格。
- 檢查工具（詳見
references/setup.md）：Node 20+、含 Chromium 的 Playwright、含xfade、zoompan、loudnorm、libx264的 FFmpeg，以及 Python 3.11 或 3.12 並安裝kokoro-onnx。將語音模型（約 350 MB）安裝在倉庫外部，例如~/video-tools。 - 將工作檔案複製到使用者的專案中，並將產生的輸出檔排除在 git 版本控制之外：
mkdir -p e2e/video-kit && cp -R <this skill>/scripts/. e2e/video-kit/ && cp <this skill>/templates/*.mjs e2e/video-kit/ printf '\ne2e/video-kit/clips/\ne2e/video-kit/vo/\ne2e/video-kit/build/\ne2e/video-kit/*.mp4\ne2e/video-kit/*.srt\ne2e/video-kit/spec.json\ne2e/video-kit/.*.json\n' >> .gitignore - 閱讀
references/toolkit-api.md一次。它說明了錄製輔助工具以及PLAN語法。不要改寫rec.mjs、speak.py、overlays.mjs或assemble.py；只編輯指南中指定的部分。
工作流程：三道關卡
請在每個關卡停止並等待使用者。在錄製前修改用詞和結構成本較低，錄製後則會變得昂貴。
關卡 1：故事板。 檢視專案（其文件、路由、現有的 Playwright 測試），並建議 8 到 12 個場景。對於每個場景：畫面上要顯示什麼、旁白（20 到 35 個字，用語平實）、以及如何錄製。如果使用者需要背景說明，可以加入開場投影片：問題、已完成或審查的內容、解決方案與技術棧。不要描述任何應用程式實際上做不到的事情；不確定時請提問。
關卡 2：用詞與語音。 將 chunks.txt 寫成 scene|text 行，每行約 12 個字以內（每個行變成一行字幕）。在 speak.py 的 PRONOUNCE 中加入產品名稱與縮寫。執行 python speak.py 並報告每個場景的長度。使用者聽過並核准後再進行錄製。
關卡 3：錄製、組裝、檢查。
- 在
scenes.mjs中撰寫場景（從scenes.template.mjs開始），每個場景一個片段，命名為scene-N以符合預設計劃。在背景中一次錄製一個場景：node scenes.mjs <name>。只重新錄製失敗的場景。 - 如果需要投影片，則渲染投影片（
slides.template.mjs），然後在assemble.py中填入PLAN和LABEL：哪個片段對應哪個場景，以及哪個標記對應哪一行旁白。 - 執行
python assemble.py all。它會產生walkthrough.mp4和walkthrough.srt。 - 透過一張聯絡表（每個場景一兩幀，拼貼排列）來檢查結果，而不是檢查多張獨立的圖片：名稱、日期、字幕、無任何內容被切掉、無任何私人資訊。修正後重新組裝，然後交付。
重要規則
- 隱私。 使用示範或測試帳號。模糊或遮蓋任何顯示真實人物、電子郵件、電話號碼、帳戶名稱、金鑰、ID、令牌或帳單資訊的內容（使用
opts.cover、opts.init）。永遠不要處理密碼：當場景需要登入時，請使用者在可見的瀏覽器中手動登入一次（templates/auth.template.mjs），然後重複使用儲存的 session。永遠不要在鏡頭上輸入或顯示密碼或 2FA 驗證碼。將.env、儲存的登入資訊和瀏覽器設定檔排除在 git 之外。 - 不要在真實帳號上操作。 永遠不要點選任何會在真實帳號上發送、發布、排程或刪除的按鈕。將滑鼠游標停留在按鈕上，然後說明它的功能。
- 不要發明不存在功能。 只描述程式碼和正在執行的應用程式實際能做到的事。
- 語音和麥克風音訊無法由瀏覽器擷取。 只需顯示介面並說明發生了什麼事。
- 啟動伺服器前檢查連接埠；停止任何你啟動的服務。 將耗時超過一分鐘的任務（錄製、語音、組裝）放在背景執行並等待其完成，而不是在迴圈中輪詢。
- 保持回覆簡短。 報告你做了什麼、檔案路徑，以及任何你無法驗證的事項。
實際使用經驗
在撰寫場景前先閱讀 references/lessons.md。簡短摘要：確認預先建立的資料確實存在（隨機測試資料可能與舊資料衝突）；等待能夠證明緩慢頁面已繪製完成的定位器；在輸入文字前清除記住的搜尋篩選條件；關閉彈出視窗；直接連結到記錄；將非必要的點綴效果包裝起來，以免一個失敗導致整個場景停擺；保持投影片底部 200 像素的區域空白，以便顯示字幕。
檔案
scripts/rec.mjs錄製器：滑動游標、點擊漣漪效果、縮放、標記、think()用來剪除等待時間。scripts/speak.py將旁白轉為 WAV 檔和字幕時間戳記。scripts/overlays.mjs將字幕、標籤和標題卡製作為圖片。scripts/assemble.py根據語音重新調整片段時間、串接、疊加、混合音訊、產生 MP4 和 SRT 檔案。templates/場景、已儲存的登入、投影片以及旁白檔案的起點範本。references/工具組指南、安裝設定和經驗教訓。
當遇到問題時
- 語音失敗並出現
espeakng_loader/phontab: No such file：請參閱references/setup.md。 - 場景因等待文字而超時：頁面可能尚未完成繪製，或者記住的篩選條件隱藏了該項目。在失敗時截取螢幕截圖並檢視。
- 影片顯示等待中：將緩慢的步驟包裝在
think()中。 - 畫面與語音不同步：重新錄製該場景，因為任何腳本變更都會導致標記時間改變。