Repo 展示影片
使用此技能將儲存庫轉換為精美的產品展示計畫，並在具備足夠執行時期資訊時，轉換為瀏覽器錄製的展示影片。
核心原則
優先使用儲存庫證據而非使用者完美設定：
- 當存在
demo.config.json或demo.config.yaml時使用它們。 - 當存在
DEMO_GUIDE.md時使用它。 - 使用
README.md。 - 使用
package.json、框架檔案、路由資料夾、元件名稱、頁面標題與原始碼結構。 - 當存在安全 URL 時，在瀏覽器中探索已部署或本地應用程式。
- 產生帶有置信度分數的備用假設。
將 README.md 加上原始碼視為主要來源，DEMO_GUIDE.md 視為建議的人性化指南，而 demo.config.* 則視為可選的機器友善覆寫。
工作流程
-
解析目標儲存庫路徑或 URL。對於 MVP CLI，使用本地儲存庫路徑；如果提供 GitHub URL，請要求使用者提供本地克隆，除非未來有明確的克隆工作流程可用。
-
執行分析器：
npm run demo -- --repo ./path-to-repo可選輸入：
npm run demo -- --repo ./path-to-repo --config ./demo.config.json npm run demo -- --repo ./path-to-repo --url https://example.com npm run demo -- --repo ./path-to-repo --mode draft npm run demo -- --repo ./path-to-repo --mode full -
在帶有時間戳記的輸出資料夾中檢閱生成的成品，例如
demoOutput-2026-05-10-143012/：project_summary.mddemo_plan.draft.jsondemo_plan.json（當置信度足夠高時）narration_script.draft.mdnarration_script.mdscript_quality_report.jsontiming_plan.jsondemo_storyboard.mdmanual_recording_guide.mdrecordings/（當瀏覽器擷取成功時）screenshots/（當瀏覽器探索成功時）voiceover.mp3（當設定了TTS_PROVIDER=openai且OPENAI_API_KEY可用時）demo_video.html（當 MP4 合成不完整時作為本地預覽備用方案）demo_video.mp4（僅當錄製、真實音訊及ffmpeg可用時）
置信度規則
- 將明確的文件與組態聲明標記為
high。 - 當專案名稱、摘要與至少一個功能清楚時，將 README 功能列表視為足夠的證據以產出最終計畫。
- 將路由名稱、元件名稱、套件元資料與清晰的程式碼結構標記為
medium。 - 將推測性的產品聲明與猜測的操作標記為
low。 - 如果重要的聲明置信度較低，則產生
demo_plan.draft.json，解釋缺少的內容，並避免將最終影片計畫視為確定。
README 解析
- 在提取產品摘要時，忽略徽章、盾牌圖片、裝飾性圖片行、原始 URL 以及授權/狀態元資料。
- 優先使用
DEMO_GUIDE.md的宣傳語、README 的引用區塊摘要、README 的概覽/關於/描述章節，然後是套件描述。 - 藉由在匹配前正規化標題，來識別帶有表情符號或符號的裝飾性標題（例如
## Features）。 - 將功能/能力/亮點標題下的項目符號列表提取為高置信度功能。
- 將用法/如何操作/展示/快速入門標題下的編號工作流程提取為中等置信度的展示流程提示。
- 在撰寫腳本前清理旁白輸入；不要將 Markdown 徽章、圖片語法或原始 URL 帶入語音文字中。
安全
- 將儲存庫分析保持為唯讀。
- 僅將生成的成品寫入目標儲存庫中一個新的帶有時間戳記的
demoOutput-YYYY-MM-DD-HHMMSS/資料夾。 - 不要遞迴刪除檔案或執行破壞性命令。
- 不要執行部署命令。
- 當使用者要求旁白輸出或設定了提供者環境變數時，允許外部 LLM/TTS 呼叫。僅傳送清理後的專案摘要、展示計畫、瀏覽器觀察結果與旁白腳本文字。
- 不要將原始的
.env檔案、API 金鑰、私有令牌、私有使用者資料、真實憑證或不必要的原始碼檔案傳送給外部 LLM/TTS 提供者。 - 不要將機密、API 金鑰、私有令牌、
.env值、私有使用者資料或真實憑證暴露在旁白、螢幕截圖、影片、日誌或生成的成品中。 - 如果有記錄測試帳號，除非使用者明確要求，否則僅提及使用了展示帳號。
瀏覽器與影片行為
- 優先使用來自組態、
DEMO_GUIDE.md、README 或--url參數的已部署demoUrl。 - 在可用時使用 Playwright 來檢查可見標題、按鈕、連結、表單，並擷取螢幕截圖或錄製。
- 使用保守的 DOM 啟發式方法填入安全的範例輸入，選擇非空白的選擇選項，並點擊常見的展示控制項，例如 Add、Calculate、Method、Resources、New 或 Create。
- 讓每個預定場景在螢幕上停留足夠長的時間以配合旁白節奏，並在啟發式操作後短暫暫停，這樣錄製就不只是快速點擊。
- 將規範的
.webm錄製路徑註冊在run_report.json中。 - 當執行說明不確定時，不要強制啟動本地專案。
- 如果 Playwright、TTS、
ffmpeg或應用程式執行時期不可用，仍然產出書面成品、部分交付物、demo_video.html以及手動錄製指南。 - 根據語音旁白持續時間合成最終 MP4。不要使用最短串流截斷。如果瀏覽器錄製長度短於語音旁白，則使用
ffmpeg的tpad延伸最終影片影格，並報告延伸持續時間。
專業腳本撰寫
- 將確定性草稿用作備用方案，但當設定了
SCRIPT_PROVIDER=openai且OPENAI_API_KEY時，優先使用 OpenAI 腳本撰寫器。 - 在撰寫最終腳本前產生
timing_plan.json。根據可用功能、瀏覽器場景、設定的影片持續時間與節奏警告來產生。 - 腳本撰寫與 OpenAI TTS 使用同一個
OPENAI_API_KEY。 - 在
src/prompts/demoNarrationPrompt.ts中控制產品展示撰寫提示。 - 使用
OPENAI_SCRIPT_MODEL控制 OpenAI Responses API 模型；如果未設定，則回退到OPENAI_MODEL，然後是gpt-5.4-mini。 - 將
narration_script.draft.md用於範本草稿，將narration_script.md用於最終的 LLM 或備用腳本。 - 產生
script_quality_report.json，其中包含提供者、模型、備用原因與品質門檻警告。 - 提示應讓腳本撰寫器先理解產品，避免徽章與原始 README 元資料，專注於受眾/問題/價值，對不確定的聲明使用保守措辭，並尊重時間規劃的場景數量與字數預算。
展示視覺指引
為了獲得精美的瀏覽器錄製效果，透過 Playwright 注入暫時性、非持續的視覺指引疊加層，而不是編輯應用程式原始碼。
使用：
- 一個微妙的標題說明，用於當前的旁白節拍。
- 一個圍繞活躍 UI 元素或結果區域的高亮環。
- 高
z-index、pointer-events: none以及固定定位。 - 不會遮蔽產品 UI 的中性樣式。
不要使用疊加層來偽造功能。僅使用它們來引導觀看者注意真實的 UI 狀態變化。疊加層僅存在於錄製的瀏覽器會話中，並在會話關閉時消失。
語音旁白
- 在完整模式下，當設定了
OPENAI_API_KEY時，預設使用 OpenAI TTS。 - 若要明確產生真實音訊，請設定
TTS_PROVIDER=openai與OPENAI_API_KEY。 - 如果未設定
TTS_PROVIDER但存在OPENAI_API_KEY，則使用 OpenAI TTS。 - 若要強制使用本地模擬模式，請設定
TTS_PROVIDER=mock。 OPENAI_API_KEY可能與專業腳本撰寫器使用的金鑰相同。- 可選變數：
OPENAI_TTS_MODEL、OPENAI_TTS_VOICE、OPENAI_TTS_INSTRUCTIONS、TTS_VOICE。 - 將真實音訊寫入當前執行資料夾，例如
demoOutput-2026-05-10-143012/voiceover.mp3。 - 將清理後的
voiceover_script.txt文字傳送給設定的 TTS 提供者是建立語音旁白音訊的必要步驟。 - 切勿將 API 金鑰寫入生成的檔案中。
- 發布展示時，請揭露生成的語音旁白是 AI 生成的。
擴充此技能
保持架構模組化。透過擴充對應的 src/*.ts 模組來新增對 GitHub URL 克隆、更深層的 UI 互動、真實 TTS 提供者、字幕、影片樣式、本地啟動以及人工審閱的支援，而不是將 CLI 變成一個龐大的腳本。