記錄產品示範
將使用者的產品和動作描述轉換為已存檔的錄製情境，針對真實應用程式執行該情境，並將產生的素材套用到要求的預覽中。
選擇工作流程
- 對於產品的首次示範，請閱讀 references/new-product-workflow.md 和 references/scenario-schema.md。
- 對於現有情境，請閱讀 references/scenario-schema.md，僅更新要求的行為，並重新錄製到相同的套用路徑，除非使用者另有要求。
工作流程
-
找到產品的路由、穩定的互動選擇器，以及消費其預覽的元件。保留要求的內容、順序、畫面構圖、持續時間和輸出位置。
-
建立或更新
scripts/demo-video-scenarios/<product-slug>.json。對於首次示範，先使用npm run init:demo -- --product "<name>" --route <route> --consumer <file>初始化，然後將起始動作替換為要求的序列。將產品特定的行為保留在情境中，而不是硬編碼在錄製器中。 -
使用真實的瀏覽器動作。在觀眾必須看到防抖更新、完成動畫或中間狀態時，加入刻意等待。保持總動作時間低於錄製持續時間；未使用的時間將成為最終的停頓。對於連續動畫，規劃其完整執行時間加上可讀的暫停，並加入
quality.motionChecks窗口。 -
將產生的媒體放在
public/previews/下，除非現有產品使用其他公開資產位置。設定application.consumerFiles和公開路徑，以便執行器驗證這些資產已套用。在新增預覽時，先修補消費者；覆蓋已引用的輸出即視為套用更新。 -
執行：
npm run record:demo -- --scenario scripts/demo-video-scenarios/<product-slug>.json -
驗證結果，而不僅僅是命令的退出碼：
- 錄製器會執行
verify:demo，並且必須通過精確的持續時間、尺寸、方形像素、平均幀率、影格數、H.264 編碼以及已設定的連續動作檢查。 - 使用
view_image開啟每個列印的整體和動作連絡表。確認輸入的值、產品的中間變更、均勻分佈的動作、轉場的兩端以及最終狀態。 - 執行
npm run lint；針對套用預覽時所做的任何應用程式UI變更，執行AGENTS.md所需的檢查。
- 錄製器會執行
平滑動作合約
- 對於動畫示範，優先使用真正的 60 fps。尊重來源捕捉的報告幀率上限；切勿透過複製影格或對 WebGL 動作進行插值來宣稱更流暢的輸出。
- 為主要轉場提供足夠的情境時間，使其清晰可讀。使用產品預期的持續時間；當沒有預期時間且流暢性至關重要時，從每個方向約 2-3 秒開始，並延長整體影片，而不是趕著進行後續動作。
- 在
quality.motionChecks中標記每個應連續移動的區間。預設閘門不允許連續的完全相同的影格。僅當產品在該區間內刻意保持靜止時，才放寬該閘門，並在情境描述中記錄原因。 - 根據密集的動作連絡表以視覺方式判斷節奏。有效的影格數無法檢測到前置載入或突然的緩動曲線。
- 如果真實產品動畫本身不流暢，且使用者要求改善平滑度，請修正其影格節奏或緩動，並在重新錄製前執行相關的 UI 檢查。否則，保留產品行為並解釋限制，而不是在後製中掩蓋它。
捕捉不變量
- 透過 Chrome 的原生分頁合成器串流記錄真實的 Vite 應用程式。Puppeteer 可以提供鍵盤、指標和時序，但產品必須執行自己的狀態更新和渲染。
- 請勿使用 DevTools 螢幕截圖取樣來代替 WebGL 動作的原生分頁捕捉；這可能會遺漏中間影格並產生虛假的轉場效果。
- 請勿編碼高於真實捕捉速率，或使用動作插值來通過平滑度要求。
- 切勿捕捉使用者的完整桌面或現有顯示器。本機擴充功能只能捕捉選定的 localhost 產品分頁。
- 僅使用
recordingCss來構圖示範。除非使用者同時要求該 UI 變更，否則請勿更改真實產品 UI 以使錄製更容易。 - 請勿在情境中添加任意的 JavaScript 評估動作。當互動確實不受支援時，請在執行器中添加一個名稱狹義的真實輸入動作。
- 如果無法執行原生分頁捕捉，請報告具體的先決條件，而不是默默地產生模擬影片。
解讀請求
從儲存庫推斷路由、選擇器和現有資產消費者。僅在檢查後仍存在多個產品或實質上不同的輸出位置時，才提出疑問。
當使用者說「為 <product> 建立/初始化並套用示範」但沒有技術細節時，推斷已實現的路由、目錄消費者、選擇器和現有預覽慣例。僅當儲存庫和請求未提供更好的慣例時，才預設為 8 秒、60 fps 和縱向構圖。示範請求不授權實現缺失的產品。
一個合適的請求可以像這樣簡單：
對 Design QR 使用
$record-product-demo：分兩部分輸入網址，暫停等待樹狀更新，將 3D 變換為 2D 再變回來，然後將其套用到目錄卡片上。
使用者面向的初始化和提示範例記錄在 demo-video 工作流程 中。