demo-video
您需要一個應用程式的精美設計影片。這項技能是經過測試、隨插即用的完整管線。它基於 HyperFrames（HTML→影片），但加入了那些重新摸索會很痛苦的部分：如何自行錄製應用程式、這台機器的 ffmpeg 替代方案、精確的編輯配方、有品牌的設計系統，以及那些浪費時間的陷阱。
這裡沒有任何東西是已套用品牌的。 外觀是一種設計，搭配可替換的權杖；影片屬於哪個品牌是一個步驟，而非假設——請參閱第 0B 階段。
🚦 階段按主題分組，而非工作順序
在依序執行以下任何步驟前，請先閱讀此部分。錄製機制會先被記錄，因為它們屬於同類，但錄製不是您要做的第一件事：
概念優先：這個影片是為了什麼？→ 故事大綱 → PLAN.md（+ SCRIPT.md）→ 核准
（這是 `video-plan` 技能，不是這個） │
│
↓ 直到此時才開始有素材 ──────────────────────────────────────────────────────┘
第 0 階段 環境 → 第 0B 階段 品牌 → 第 1A 階段 錄製 / 第 1B 階段 匯入 → 第 3 階段 準備 → 第 4 階段 合成
→ 第 5 階段 驗證 → 第 6 階段 渲染
搶先錄製看起來比較快，但事實並非如此：故事大綱是審核時會變動的部分，而每個針對未同意故事大綱所錄製的鏡頭都必須重錄。第 0 和第 0B 階段是您可以提前執行的兩件事——它們安裝工具並確定配色方案。第 1 階段的所有內容都需等待核准的計劃。
🚀 快速試用——捷徑
🚨 由呼叫者選擇此模式。您永遠不應自行決定。 您可以提問一次來提供此選項。您不能根據情況推斷，尤其以下情況不代表同意：
- 他們附加或解壓縮了技能套件——這只是安裝工具的方式，並非聲明他們想要製作什麼；
- 請求聽起來像是探索性的，或者沒有簡報；
- 這是他們第一次提出要求；
- 您覺得捷徑更方便。
如果有人說「幫我做一個 example.com 的影片」，他們要求的是 example.com 的影片。擅自決定他們真正想要的是拋棄式成品，只會讓他們在期望得到完成品時，收到一個無聲、無品牌、1080p 的草稿——而您跳過的部分（故事大綱、文字、品牌）正是事後無法補救的部分。
如果不確定，請詢問。「這是快速測試，還是您會實際展示給別人看的影片？」一句話，就能確定您處於哪種模式。
以下存在核准關卡，是因為一部會被人看到的影片，出錯的代價很高。拋棄式執行則不然，為了確認錄製是否正常而讓審核者經歷概念審查，正是讓一個好工具在最初十分鐘內被放棄的原因。兩種失敗都是真實的；只有呼叫者知道哪一種適用。
一旦呼叫者選擇了捷徑：
- 複述確認——一句話：「我將此視為快速測試，因此跳過核准關卡和品牌；若需要完整流程，請告知。」確認比宣布好：這給了可能處於另一種模式的呼叫者最後一次低成本糾正的機會。
- 兩行的
PLAN.md——將故事大綱濃縮成一句話，三到四個要點。沒有SCRIPT.md，沒有簽核關卡。 - 中性色調。 不進行品牌提取，無需預覽核准。
- 無聲。 無旁白，無 ElevenLabs 金鑰，無腳本檢查。
- 僅 1080p。 無 4K，無發布步驟。
- 僅限內部使用——不會向客戶展示，也不會發布到任何公開場所。如果後來有人想展示，那是不同的影片：請正確執行，而不是事後對草稿進行核准。
本文件中的其他所有內容仍然適用——錄製路徑、驗證、模糊同意中止。這些並非形式；它們是防止有問題的影片看起來沒問題的關鍵。
🛑 概念關卡
此技能並非從請求開始，而是從已核准的 PLAN.md 開始（對於任何對外展示的內容，還需附上逐字的 SCRIPT.md）。上述的捷徑是唯一的例外，且僅在結果不會被會議室外的人看到時才可使用。
如果沒有核准的計劃，那是 video-plan 技能的工作，它需要一次執行：影片的目的、示範或指南、語言、故事大綱、要點列表、文案。先執行那個，然後再回來。為了撰寫計劃而閱讀應用程式是可以的——錄製它則不行。
無論計劃是誰寫的，您都必須做兩件事，而且都是問題，而非宣告：
詢問是否需要先分析。「我應該查看應用程式並建議要展示什麼，還是您已經知道了？」正確地閱讀產品需要花費實際時間，而且呼叫者可能已經有不同的起始畫面或完整想法。不要浪費他們的時間在您的假設上。
在拍攝前獲得要點列表的點頭同意。 不是重新核准整個 PLAN.md——計劃已經核准——而是您即將錄製的具體鏡頭列表：這四個要點，按此順序，聚焦於這些內容。這只需要一條訊息，而且這是最後一次低成本調整的機會。錄製完成後，更改順序意味著重拍，因為針對不同故事大綱拍攝的要點無法插入現有的剪輯中。
在聊天中確認錄製來源。 要錄製哪個環境，以及因此要使用哪個版本的產品，是由使用者決定，且目標是會變動的。
🚦 第一個決定：素材從哪裡來？
如果主題是您能訪問的網頁 → 自行錄製。不要要求螢幕錄影。
可訪問的 URL？── 是 ──┬── 它是您的（或您的客戶的，附有簡報）
│ │ └─▶ 第 1A 階段 · 錄製 (references/playwright-capture.md)
│ │
│ └── 它是其他人的網站
│ └─▶ 第 1A 階段 · 錄製，加上 references/foreign-sites.md
│ （許可關卡、同意牆、固定頁首、
│ 惰性載入的矩形偏移——先閱讀，
│ 錄製原始碼在陌生 DOM 上不安全）
否 （桌面應用程式、Figma、原生工具、行動裝置、
或使用者已提供 .mov）
▼
第 1B 階段 · 匯入螢幕錄影
自有應用程式和第三方網站是同一條管線，只是錄製方式不同。 合成、設計系統、驗證層和旁白不變；品牌提取已經可以讀取任何線上網站。改變的是您預設只能訪問公開內容，無法預設狀態，不得寫入任何內容，並且是在一個會移動的 DOM 上進行測量。（經過驗證的第三方錄製是可能的但不建議：需要每個域名的明確許可、啟用瀏覽器沙箱，並在結束時銷毀會話檔案——references/foreign-sites.md §0。）
這不是風格偏好——錄製路徑不僅能提供更好的素材，工作量也大約減半。手動螢幕錄影會迫使您從像素逆向推斷時間軸、尋找並剪除作者的重新嘗試、手動測量每個聚光燈、裁剪瀏覽器邊框，並檢查隱私問題。腳本化的錄製從結構上就沒有這些問題，沒有瀏覽器邊框，讓您選擇文字大小，並且可以在 UI 改變時重新執行。以相同的流程測量：71 秒的螢幕錄影需要密集的幀掃描，而 28 秒的錄製則可提供每個來源時間和元素矩形，記錄在 beats.json 中——並且在最終畫面上文字大小為 1.5 倍。
即使如此，如果使用者已經錄製了某些內容，請在錄製前先觀看。 它編碼了他們對自己產品的理解——要展示哪些功能、順序為何、重點是什麼。這個編輯判斷是錄製路徑無法免費提供的。
按需閱讀參考文件——不要預先載入：
| 需要 | 閱讀 |
|---|---|
| 這個影片屬於哪個品牌？（權杖、標誌、字型——網站也可以） | references/brand-style.md |
| 自行驅動並錄製應用程式；2 倍速；游標；驗證；beats.json | references/playwright-capture.md |
| 目標是您不擁有的網站（許可關卡、同意牆、固定頁首、惰性載入的矩形偏移、即時媒體） | references/foreign-sites.md——在錄製前閱讀 |
| 在容器或 CI 中無頭執行（缺少 CJK/表情符號字型、Chromium 在首次錄製時崩潰、安裝後「執行檔不存在」） | references/container-capture.md |
在 capture-lib.js 中更改任何內容後 | node <skill>/scripts/test-foreign-sites.mjs——本地測試資料，無需網路；每個案例都是已發布的缺陷 |
| 聚光燈框錯了像素，但座標是正確的 | references/foreign-sites.md §4——使用 stableRect 而非 boundingBox 測量 |
| 以另一種語言重新錄製；重新調整現有剪輯的時間，無需重建時間軸 | references/playwright-capture.md §9-10 |
提供了一個充滿重試片段的 .mov——挑選並剪出乾淨的片段 | references/multiple-takes.md |
| ffmpeg/CLI 無法執行、「0 GB 可用空間」、bunx、權限問題 | references/pitfalls.md §6 + 執行 scripts/setup-render-env.sh |
| 精確的剪輯/裁切/速度/凍結畫面/移除幀命令 | references/ffmpeg-recipes.md |
| 外觀：視窗、聚光燈、卡片、淡入淡出、凍結畫面 | references/design-system.md (+ assets/template.html) |
| 建立兩部分的功能指南（概念面板、操作要點、編排） | references/guide-track-build.md |
| 旁白 / ElevenLabs 配音，額度 + 語音陷阱 | references/voiceover.md |
| 語音是否真的說出了腳本？（品牌名稱、縮寫） | scripts/verify-narration.mjs——退出碼 1 = 修正 |
| 應用程式在您錄製前顯示空白、500 錯誤或「離線」 | references/pitfalls.md §17 |
| TIMELINE.md 合約；針對「在 0:12 拖動」的反饋採取行動 | references/timeline-and-review.md |
| 我把聚光燈放在哪裡？（絕不要憑目測） | references/design-system.md → 「絕不要憑目測座標」 |
| 無論使用何種內邊距，聚光燈邊緣總是會切到某些東西 | scripts/measure-spots.mjs——改為測量版面配置的空白區域 |
| 控制項真的無法被框住（在某個邊緣沒有 6px 的頻帶） | references/design-system.md → 「有時沒有盒子」 |
| 應用程式的瀏覽器邊框佔據了字幕卡的位置 | references/design-system.md → 每個鏡頭的卡片放置 + 在剪輯處分割卡片 |
| 靜止畫面顯示的是點擊後的狀態（聚光燈落在空白處） | references/playwright-capture.md §16——在 _hover 標記處凍結 |
| 腳本化的聊天訊息消失了；代理程式「完成」但實際上尚未完成 | references/playwright-capture.md §17-18 |
| 「為什麼我的素材凍結/錯位/錯誤」 | references/pitfalls.md |
| 點擊時出現奇怪的黑色環；某個修復程式靜默地沒有生效 | references/pitfalls.md §11-13 |
| 某個檢查顯示 PASS 但實際上是錯的 | references/pitfalls.md §15 |
| 每次渲染前（機械式稽核，退出碼 1 = 修正） | scripts/audit-composition.mjs |
| 主題是否實際可見？（聚光燈清除 + 卡片遮擋；退出碼 1 = 修正，退出碼 2 = 無法檢查） | scripts/verify-material.mjs |
| 快照後：按聚光燈縮放裁切（全幀讀取會漏掉被裁剪的文字） | scripts/crop-spots.mjs |
| 畫面是否顯示了旁白正在講述的內容？（有旁白的指南，按主題） | scripts/verify-topics.mjs |
| 應用程式會記錄您的操作——快照前，還原後 | scripts/app-state.mjs |
| 影片旁的獨立訓練文件（僅在要求時） | references/companion-docs.md |
在快照上進行迭代，而非渲染。 snapshot --at t1,t2,… 只需幾秒鐘；渲染需要幾分鐘。先在靜止畫面上搞定構圖、聚光燈座標、文案和隱私問題，然後渲染一次並驗證動態效果。
第 0 階段 —— 環境（每台機器/工作階段一次）
一個指令即可處理所有情況——macOS 或 Linux、健康的機器、缺少或精簡的 ffmpeg、缺少 HyperFrames、或是虛假的「0 GB 可用空間」statfs 錯誤。無需手動診斷：
render_env="$(bash <skill>/scripts/setup-render-env.sh)" && eval "$render_env"
不要使用 source <(…)。 Bash 報告的是 source 的狀態，而非提供輸入的程序替換的狀態，因此一個中途失敗的引導程序——沒有網路、安裝失敗——會報告成功，並讓您只設定了一半的環境變數。先錄製會首先暴露失敗，並在其失敗時不應用任何內容。
它會安裝 hyperframes（固定版本，如果缺少的話）、解析完整的 ffmpeg、僅在該作業系統確實有此錯誤時修補磁碟檢查，並匯出 HYPERFRAMES_FFMPEG_PATH、HYPERFRAMES_FFPROBE_PATH、PRODUCER_BROWSER_GPU_MODE 和 HYPERFRAMES_CLI。
它會探測濾鏡，而非名為 ffmpeg 的二進位檔。 此管線需要 fps/pad（第 3 階段的幀固定）、crop（第 1B 階段的瀏覽器邊框移除）和 freezedetect（audit-composition.mjs + 第 6 階段的靜音檢測）。兩個精簡的建置版本通常已經存在於 PATH 上，並能在通過簡單檢查後，於管線中途失敗：Playwright 隨附的 ffmpeg 和 Remotion 的合成器套件。解析順序：完整的系統 ffmpeg → brew（macOS）→ ~/.hyperframes-cli 中的 ffmpeg-static/ffprobe-static 套件（所有平台，無需 sudo——Linux 上的正常路徑）→ 封裝的 Remotion 合成器套件作為最後手段，它會發出警告，因為沒有 freezedetect，所以那兩個凍結檢查會靜默通過，您必須手動驗證（陷阱 #1, #16）。
然後透過它指向的本地 CLI（$HYPERFRAMES_CLI）進行渲染，絕對不要使用 bunx/npx hyperframes——那些會每次重新生成一份全新的副本
…
[為翻譯而截斷]