openvidstudio 是做什麼的？
從專案的實際執行應用程式建立展示影片。每個畫面都來自真實產品，沒有任何內容是生成的。
事前準備
執行 preflight。它會檢查 node、ffmpeg、Playwright 的 Chromium、應用程式是否確實有回應，以及是否有旁白引擎。每個失敗項目都會指出修復方式。跳過此步驟會導致在長時間渲染後才發現缺少的依賴項。
如果工具未註冊，表示伺服器未安裝。請將使用者引導至其 MCP 設定中新增以下內容，然後重新啟動客戶端：
{ "mcpServers": { "openvidstudio": { "command": "npx", "args": ["-y", "@openvidstudio/mcp-server"] } } }
流程順序
preflight -> extract_brand -> plan_beats -> [write VO] -> validate_beats -> APPROVAL GATE
-> write_beats_file -> capture_screenshot -> scaffold_scene -> validate_scenes
-> [plan_sound_effects] -> generate_narration -> stitch_composition -> contact_sheet
-> render_video -> qc_extract_frames
1. 需求收集
在提問之前先自行釐清。 常見的要求就是「為此專案製作展示影片」而沒有其他資訊。這就是完整的摘要，而且已經足夠。
先閱讀儲存庫，而不是反過來詢問使用者：
README.md說明了產品是什麼，以及通常什麼是重要的package.json的 scripts 說明了如何啟動它，而 dev script 通常會指定連接埠- routes 或 pages 說明了有哪些內容可以拍攝
然後自行啟動應用程式並確認它有回應。不要要求使用者提供他們必須查詢的網址；找出開發指令，執行它，然後檢查。只有在啟動需要你無法知道的資訊時（例如缺少的 .env 或未啟動的資料庫）才提問。
真正值得詢問的問題（因為儲存庫無法告訴你）：
- 影片應該多長
- 如果儲存庫有很多功能，應該展示哪兩三件事
- 影片是給誰看的，是登陸頁面的訪客還是正在安裝的人
一次只問一個問題，而且只問儲存庫無法回答的問題。 一開始就列出一堆問題是讓這項工作感覺像苦差事的最快方式。如果情況不明確，docs/PLANNING.md 中有完整的決策樹。
透過顯示結果來結束工作：mp4 路徑、其長度，以及 contact_sheet 或幾張 qc_extract_frames 的靜態畫面。沒人看到的渲染結果等於沒有交付影片。
1b. 套用儲存庫的品牌
使用 extract_brand，並將 sourceRepo 設定為要拍攝的儲存庫。它會讀取 Tailwind v4 的 @theme 區塊和 :root 的自訂屬性，從 next/font 匯入中挑選字型，複製找到的最佳標誌，並寫入 src/brand.ts。
在 scaffold_scene 之前執行它。事後才套用主題的影片意味著需要重新建構場景。
檢查它回傳的 unresolved 清單，並手動填寫任何重要的項目。它只會報告它實際能找到的內容，而不是憑空捏造一個合理的顏色，因此未解析的 token 是真實的缺口，而不是失敗。
這對手寫場景施加了一條規則：在元件內部讀取 token，而不是在模組作用域。applyBrand 會變異共用的 token 物件，因此在檔案頂部使用 const MONO = \"${font.mono}"`會擷取預設值，而且永遠看不到品牌。請改用monoStack()和uiStack()`。
2. 規劃場景節拍
使用 plan_beats，指定目標時長和功能。它會回傳一個連續的骨架，包含擷取方法和每個節拍的字數預算。
依據該預算撰寫旁白。validate_beats 對每個節拍強制執行每秒 2.3 到 2.9 個字的硬性下限和上限，因此一行文字可能因為過於稀疏而被拒絕。按照指定的數字撰寫可以避免來回往返。
每個 screenshot 節拍還需要 visual.url 和 visual.interactions（一個陣列，可能為空）。沒有其他文件預先說明這一點。
3. 核准關卡
向使用者顯示完整的 beats 檔案，而不是摘要，並等待明確的同意。 在此之前，不會有任何內容寫入磁碟。這是一條協定規則，而不是建議，而且在這個時間點，錯誤的影片只會浪費一句話的時間，而不是一個小時。
然後執行 write_beats_file。
4. 擷取
對每個螢幕截圖節拍執行 capture_screenshot。它會補償每個來源（per-origin）的 Chrome 縮放不同步問題，否則會產生小而模糊或對焦錯誤的擷取畫面。
如果頁面有進入動畫，請傳遞一個 wait 互動，否則擷取畫面會捕捉到動畫進行中的狀態，看起來有問題而不是明顯錯誤。
5. 場景
對每個節拍執行 scaffold_scene。它會產生一個按原樣渲染的場景，使用該節拍自己的副本和時長。編輯內容，但不要重建結構。
然後執行 validate_scenes。它會捕捉到那種渲染成功但內容錯誤的失敗：以完整舞台寬度佈局的內容，在鏡頭推近後會被裁切，因為可見區域是舞台寬度除以攝影機縮放比例。它也會標記靜態攝影機、缺少的素材以及沒有旁白的節拍。
請閱讀 docs/API.md 了解 props。不要閱讀函式庫的原始碼。
6. 旁白
執行 generate_narration。它會為每個節拍寫入一個剪輯片段，stitch_composition 會尋找這些片段，並將時間拉伸限制在一個保持自然的範圍內，而不是不惜任何代價地將剪輯塞進節拍裡。當它指出某個節拍不適合時，請修正腳本或節拍時長，不要進一步拉伸。
6b. 音效，僅在內建音效不夠用時
合成的音效包已經包含了點擊聲、按鍵聲、鈴聲、嗶嗶聲、成功音效、呼嘯聲和背景音樂，而且因為是 ffmpeg 產生的，所以沒有第三方版權問題。優先使用它。
如果影片確實需要其他音效，詢問使用者想要什麼聲音，然後對每個聲音執行 plan_sound_effects，每個聲音一個條目。它會告訴你哪些請求已被內建音效涵蓋，並為其餘的聲音回傳一個 Pixabay 搜尋連結和確切的儲存路徑。
它不會從 Pixabay 下載，你也不應該下載。Pixabay 的條款禁止自動化收集，並說明 API 僅供真實的人類請求使用，而且他們沒有發布任何音效端點。由使用者下載；你負責驗證。之後再次呼叫該工具並帶上 verify: true，以確認每個檔案是真實的音訊並正規化格式。
使用 provider: "freesound" 則會自動擷取，但僅限於使用使用者自己的 API token，而且它取得的每個剪輯片段都會記錄在 ATTRIBUTION.md 中。該檔案中的任何內容都必須出現在影片描述中，否則即違反授權條款。
音樂是所有這些規則的例外。find_music_bed 會搜尋兩個 CC0 公共領域目錄（約 9,400 首曲目），而 import_music_bed 會修剪、淡出並將使用者選中的曲目調整到與 public/audio/music-bed.mp3 相符的音量。那裡沒有任何內容需要署名。bgmusic 技能有詳細資訊；當合成的背景音樂對於發布或宣傳片來說過於平淡時，可以使用它。
7. 組裝與檢查
執行 stitch_composition，然後在渲染前執行 contact_sheet。聯絡頁是每個節拍兩幀畫面組成一張圖片，只需要完整渲染的一小部分時間，這點很重要，因為五分鐘的影片有 9000 幀。
先使用 draft: true 執行 render_video。只有在草稿看起來正確後，才進行完整品質渲染。
然後執行 qc_extract_frames 並檢查 docs/PIPELINE.md 的檢查清單。
導致 QC 失敗的規則
來自 docs/STYLE.md，因為它們是最常被違反的規則，所以在此重申：
- 不要使用線性緩動。 請使用
E.*預設值。 - 每個場景都放在
CinematicScene內部。 - 動畫永不停止。 靜止畫面就是失敗。
- 螢幕上或旁白中不要使用 em dash。
- 字幕放在
overlay中，而不是children，否則它們會隨著攝影機移動而偏離畫面。 - 螢幕截圖只放在
BrowserFrame內部。 錄影和 AI 剪輯不能放在裡面，否則生成的素材會具有真實擷取畫面的視覺特徵。
不能宣稱的內容
真實的產品 UI，無論是 DOM 渲染的、螢幕截圖的還是錄影的，都是事實依據。AI 生成的剪輯僅作為氛圍用途，絕對不能包含產品文字。如果旁白斷言了某事，視覺內容必須顯示它；如果無法顯示，則必須改寫該行旁白。