repo-cinema 導演技能
直接從程式碼庫建立 Screen Studio 等級的 60fps 產品展示影片。與其進行臨時的螢幕錄製或漫無目的的游標移動，repo-cinema 執行一個五階段的確定性流程：analyze -> plan -> stage -> render -> verify。
核心架構原則
- 人物優先使用案例 (
analyze)：絕不展示內部的除錯統計資料或原始設定畫面。讀取進入點、CLI 指令、路由、元件和測試，以合成具體的人物 -> 痛點 -> 使用者操作 -> 持久成果場景。 - 因果共框 (
plan)：框選 聯集邊界框bbox(觸發 ∪ 結果)，而非追蹤滑鼠指標。每當內容寬度佔舞台 >= 70% 時，鎖定水平焦點fx = viewport.width / 2，以免軸線、標題和右側欄位被裁剪到畫面外。 - 靜止閱讀停留：在動作之前讓鏡頭縮放平順靠近，然後在互動和理解的期間保持
(zoom, fx, fy)100% 凍結，讓觀眾可以實際閱讀圖表和通知更新。 - 確定性虛擬時鐘 60fps (
render)：在頁面載入前注入虛擬時鐘墊片 (Date、performance.now、requestAnimationFrame)，使 CSS 轉場、ECharts 動畫、C2 最小急動度游標軌跡 (sin^3(pi * u)弧線，速度膨脹 <=12%，傾斜 +/-6 度，箭頭 <-> 指向手掌變形) 以及雙擊漣漪效果，都能逐影格確定性地進入 FFmpeg。 - 連拍式自我檢查 (
verify)：生成3x3的contact-sheet.png+verify-report.json(ffprobe串流驗證 + 零次畫面外點擊)，並在發佈前目視檢查每個面板。
工具 CLI 指令 (repo-cinema)
當全域安裝或從儲存庫執行時 (npx repo-cinema ... 或 node dist/cli.js ...)，每個階段都會輸出結構化檔案：
# 1. 讀取任何儲存庫並提取使用案例場景（可先執行 repomix）
repo-cinema analyze --repo ./my-project --output ./out/dossier.json [--repomix]
# 2. 建立因果鏡頭/游標腳本 JSON + 視覺 HTML 預覽
repo-cinema plan --dossier ./out/dossier.json --output ./out/storyboard.json --html ./out/storyboard.html --theme aurora-indigo
# 3. 建立 4 合 1 舞台（web-url | plugin-or-component | cli-terminal | hybrid）
repo-cinema stage --dossier ./out/dossier.json --plan ./out/storyboard.json --output ./out/stage.html [--url http://localhost:3000]
# 4. 確定性 60fps CDP 擷取 + 48kHz 立體聲 SFX（或可選 TTS）
repo-cinema render --plan ./out/storyboard.json --stage ./out/stage.html --output ./out/demo.mp4 --gif ./out/demo.gif --audio sfx
# 5. 驗證串流、遙測邊界並建立 3x3 視覺連拍檢查表
repo-cinema verify --video ./out/demo.mp4 --telemetry ./out/demo.telemetry.json --contact-sheet ./out/contact-sheet.png --output ./out/verify.json
# 或者一次執行完整的五階段流程：
repo-cinema run --repo ./my-project --out-dir ./out --theme aurora-indigo
導演工作流程
步驟 1：分析儲存庫與觀眾
執行 repo-cinema analyze --repo <path> --output <dossier.json>。閱讀生成的 useCases：
- 驗證偵測到的
archetype(web-app、desktop-or-ide-plugin、cli-tool、ui-library、hybrid)。 - 如果儲存庫有專業工作流程，請完善標題或新增領域真實的範例檔案（切記：零個人資料、零僅限開發人員的計數器）。
步驟 2：規劃腳本並批准取景
執行 repo-cinema plan 並加上 --html，然後檢查 storyboard.html（或審閱 beats、captionWarnings 和 cameraKeyframes）：
- 修正來自反廢話標題檢查器的任何警告（沒有 "unprecedented"、"next-gen"、"seamlessly" 或長度超過 96 個字元的標題）。
- 確保開場影格 (
t=0) 和結束影格 (t=durationMs) 在zoom: 1.0時乾淨放置，以實現無縫的 README GIF 循環。
步驟 3：選擇舞台轉接器
web-url：應用程式已在本地執行 (http://localhost:PORT)。錄製器直接將虛擬時鐘墊片 + 非侵入式游標/鏡頭/標題疊加層注入到即時頁面上。plugin-or-component：桌面外掛程式 (Obsidian、VS Code、Raycast) 或 UI 元件套件，在深色 macOS Studio 鉻合金框架內渲染，並透過esbuild捆綁真實核心模組。cli-terminal：終端機工具在玻璃 macOS 終端機中展示，附帶同步的命令輸出、KPI 磁磚和成果影響卡片。hybrid：多分頁 macOS Studio，將 CLI 執行與即時視覺輸出和架構圖並列配對。
步驟 4：渲染 60fps 主檔 + GIF + 音訊
執行 repo-cinema render：
- 預設的
--audio sfx會合成零依賴的 48kHz 立體聲微音效（與游標x對齊的立體聲平移點擊、溫和的鏡頭縮放氣流聲、確認提示音）— 不需要外部 API 金鑰。 - 可選的
--audio tts --tts-provider <macos-say|edge-tts|openai|elevenlabs>會將旁白與微音效乾淨地混合。
步驟 5：驗證並目視檢查
執行 repo-cinema verify，並直接用你的檔案/圖片檢視器檢查 contact-sheet.png：
- 確認
passed: true、offscreenClicks: 0，並且所有 9 個關鍵影格縮圖的文字都可讀。 - 如果有任何元素靠近視口邊緣被裁剪，請在
computeCausalFraming中增加marginPx，或將zoom減少0.06並重新渲染。
參考指南
應避免的常見錯誤
- 在打字/拖曳期間逐影格跟隨指標：會導致暈動病。請務必在停留期間鎖定每個節拍的鏡頭取景。
- 使用真實時鐘的
setTimeout/ 即時螢幕擷取：每當 CPU 飆升時就會掉幀，並產生斷斷續續的 24–40fps 錄製。請務必透過__rcStep(dtMs)驅動動畫。 - 對寬圖表或表格過度縮放 (
> 1.35x)：會裁剪 Y 軸標籤或最右側的摘要欄位。請將wideLockRatio保持在0.70，這樣fx = width / 2。 - 將大型原始
.mp4二進位檔提交到 GitHub 儲存庫：請在docs/assets/中追蹤輕量級調色板最佳化的.gif+contact-sheet.png，並將.mp4附加到 GitHub Releases，或在本地忽略*.mp4。