示範腳本技能 (Demo Script Skill)
透過探索即時產品並與使用者共同創作，建立結構化的示範影片腳本。
為何存在
好的示範影片需要好的腳本。糟糕的示範會東拉西扯、跳過重要內容或節奏太快。此技能可產出精確且可審查的腳本，讓 /record-demo 能自動執行。
工作流程
階段 1：簡報
向使用者收集背景資訊：
必要資訊：
- 要示範的產品/功能
- 目標網址（暫存/正式）
- 觀眾是誰？（潛在客戶、現有用戶、開發人員、內部團隊）
選填資訊（如未提供則詢問）：
- 要展示的具體流程（例如「建立一個包含步驟和預期結果的測試案例」）
- 語氣（專業、輕鬆、技術、行銷）
- 目標時長（30 秒、1 分鐘、3 分鐘、5 分鐘）
- 要強調的重點
- 要避免/跳過的內容
未指定時預設值：
- 觀眾：正在評估產品的潛在客戶
- 語氣：專業但平易近人
- 時長：1-2 分鐘
- 解析度：1920x1080
階段 2：產品探索
使用 Playwright 瀏覽器工具實際探索產品 UI。
這一步至關重要 — 不要憑空猜測 UI 的樣子。實際進行導覽：
- 在瀏覽器中打開目標網址
- 擷取每個相關頁面/畫面的螢幕截圖
- 記下實際的按鈕標籤、選單項目、表單欄位
- 了解導覽流程
- 透過真實的選擇器辨識 UI 元素
範例探索流程：
→ 導覽至應用程式網址
→ 擷取儀表板截圖
→ 點擊目標功能
→ 擷取每個狀態變化的截圖
→ 記錄所有互動元素的確切選擇器
→ 檢查載入狀態、動畫、模態框
為什麼要先探索？
- 真實的選擇器名稱（而非錄製時會失敗的猜測名稱）
- 準確的旁白能與畫面上的內容完全對應
- 發現自然的流程（或許使用者忘了提到某個步驟）
- 找出潛在問題（驗證牆、載入緩慢、空狀態）
驗證：
- 如果應用程式需要登入，請向使用者索取憑證或預先驗證的工作階段
- 或者使用具有測試資料的暫存環境
- 注意：為錄製階段保存 Cookie/工作階段
階段 3：腳本草稿
以 JSON 格式產生結構化腳本，包含 metadata 和 scenes 陣列。
完整的 JSON 結構、動作參考和醒目提示樣式，請查閱 references/script-format.md。
階段 4：審閱與迭代
以便於閱讀的格式（非原始 JSON）向使用者呈現腳本。格式如下：
🎬 示範腳本：「建立你的第一個測試案例」
時長：約 90 秒 | 觀眾：潛在客戶
━━━ 場景 1：開場 — 儀表板概覽 ━━━
→ 導覽至 /dashboard
🎙️「歡迎使用 OneTest。讓我們來建立你的第一個測試案例。」
⏸️ 暫停 2 秒
━━━ 場景 2：導覽至測試案例 ━━━
→ 點擊：側邊欄「測試案例」
🎙️「從側邊欄開啟測試案例區段。」
✨ 醒目提示：側邊欄項目（脈衝動畫）
⏸️ 暫停 1.5 秒
━━━ 場景 3：建立新的測試案例 ━━━
→ 點擊：「建立」按鈕
🎙️「點擊『建立』來開始一個新的測試案例。」
✨ 醒目提示：建立按鈕（發光效果）
⏸️ 暫停 2 秒
→ 在標題欄位輸入：「使用有效憑證登入」
🎙️「給它一個描述性的標題。」
⏸️ 暫停 1 秒
→ 在描述欄位輸入：「驗證使用者能否成功登入...」
🎙️「加入清晰的描述來說明這個測試案例要驗證什麼。」
⏸️ 暫停 1.5 秒
━━━ 場景 4：結尾 ━━━
→ 等待 2 秒（停留在最終畫面）
🎙️「就這樣 — 你的第一個測試案例準備好了。」
⏸️ 暫停 1.5 秒
總計預計：約 90 秒
與使用者迭代：
- 「想要新增/移除任何場景嗎？」
- 「節奏應該要更快還是更慢？」
- 「有任何旁白文字你想修改嗎？」
- 「想要重新排序嗎？」
階段 5：儲存與交接
一旦獲得批准：
- 將腳本 JSON 儲存至
workspace/<日期>/demo-script-<名稱>.json - 將可讀版本儲存至
workspace/<日期>/demo-script-<名稱>.md - 告知使用者：「腳本已就緒！執行
/record-demo來錄製，或我現在就可以開始錄製。」
腳本動作參考
10 種支援的動作：navigate、click、type、select、scroll、hover、wait、screenshot、drag、keyboard。
5 種醒目提示樣式：pulse、glow、arrow、dim-others、zoom（透過 CSS/JS 注入）。
完整的欄位與範例參考請見 references/script-format.md。
旁白指南
良好的旁白：
- 使用短句（少於 15 個字）
- 現在式、主動語態（「點擊建立」而非「我們將會點擊建立按鈕」）
- 描述正在發生的事以及「為什麼」（「加入描述讓你的團隊知道要測試什麼」）
- 不要敘述顯而易見的事（「我現在要移動滑鼠到...」— 不需要）
- 讓暫停時間與旁白長度匹配（旁白越長，暫停越長）
節奏規則：
- 第一個場景：較長的暫停（讓觀眾定位）
- 中間場景：適度暫停
- 最後場景：在最終狀態停留 2-3 秒
- 輸入文字後：短暫暫停讓觀眾閱讀
- 頁面導覽後：等待載入完成 + 額外 1 秒讓觀眾瀏覽
依觀眾調整語氣：
- 潛在客戶：著重好處，保持簡單，避免行話
- 開發人員：可使用技術術語，展示設定，提及 API
- 內部團隊：可以更輕鬆，參考團隊慣例
打造精彩示範的技巧
- 從資料開始 — 不要在空白的應用程式上示範。確保有測試資料存在。
- 展示快樂路徑 — 將邊界案例留給文件，而非示範。
- 一個功能一支影片 — 90 秒的聚焦影片勝過 10 分鐘的導覽。
- 以結果結尾 — 展示已建立/完成的東西，而非一個選單。
- 用實際名稱命名 — 「使用有效憑證登入」勝過「測試 1」。
- 清理 UI — 關閉不必要的分頁，隱藏開發者工具，使用乾淨的瀏覽器設定檔。