synctake

SyncTake 編碼代理技能

此技能指導編碼代理（Claude Code、Cursor、Antigravity、OpenCode、Codex）如何自主製作精美且附帶旁白的網頁應用程式導覽影片。

---

🎯 何時啟動此技能

每當使用者提出以下要求時，啟動此工作流程：

• "為此專案/功能建立一個示範影片/導覽"
• "錄製一段展示應用程式如何運作的影片"
• "製作一段 30 秒/60 秒的此新 UI 導覽影片"
• "以旁白影片形式展示此功能"

---

🛠️ 第 0 步：環境與依賴檢查

在執行工作流程前，請確認已安裝必要的工具：

1. 確認 SyncTake CLI：

   synctake --help || pip install -e /path/to/synctake
   

2. 確認 Playwright（用於自主無頭錄製）：

   python -c "import playwright" 2>/dev/null || (pip install playwright && playwright install chromium)
   

---

📋 自主代理五步驟劇本

[1. 檢查 UI] ──> [2. 編寫 synctake.json] ──> [3. 啟動開發伺服器] ──> [4. 執行自主管線] ──> [5. 交付影片]

步驟 1：檢查程式碼與 UI 地標

1. 在工作區中搜尋路由、元件和 HTML 檢視（例如 src/、pages/、app/、public/index.html）。
2. 為影片識別關鍵視覺地標：
   • 頁首、導覽列、主視覺區（#hero、header、.brand）
   • 互動元件、表單、按鈕（#deploy-btn、button[type='submit']、select）
   • 卡片、指標、圖表（[data-testid='metrics']、.card、.recommendation-grid）
3. 或者，執行內建的 UI 檢查器：

   synctake plan ./public/index.html --prompt "<使用者指引>" --duration <秒數>
   

---

步驟 2：編寫導覽規範（synctake.json）

在專案根目錄建立 synctake.json。

節奏與腳本規則：

• 每分鐘字數： 目標為 140–150 WPM（約每秒 2.4 字）。一個 10 秒的場景應包含大約 20–24 個字。
• 場景時間戳記（at）： 必須嚴格遞增。
• 螢幕提示： 保持 title 和 callout 簡短有力（它們會以原生浮動卡片形式顯示）。
• 聚焦目標（focus）： 使用真實且有效的 CSS 選擇器（#id、.class、[data-testid='...']）。
• 旁白： 撰寫自然、對話式的語音。切勿直接朗讀原始程式碼符號、選擇器或時間戳記。

{
  "title": "功能導覽",
  "duration_seconds": 30.0,
  "voice": {
    "provider": "system"
  },
  "scenes": [
    {
      "id": "01-概覽",
      "at": 0.0,
      "title": "即時叢集概覽",
      "callout": "跨區域的即時健康度與遙測指標",
      "focus": "#metrics-card",
      "text": "歡迎！在本次導覽中，我們將探索即時叢集健康度與自動化修復。"
    },
    {
      "id": "02-操作",
      "at": 12.0,
      "title": "一鍵部署",
      "callout": "自動驗證搭配人工審核",
      "focus": "#deploy-btn",
      "text": "只需按一下，我們的管線便會驗證配置變更並套用滾動更新。"
    }
  ]
}

---

步驟 3：確保開發伺服器正在執行

檢查網頁應用程式的開發伺服器是否已在本地埠口監聽：

lsof -i :3000 -i :5173 -i :8000 || true

如果未執行，請在背景啟動它：

• 對於靜態 HTML：python3 -m http.server 5173 --bind 127.0.0.1
• 對於 Vite：npm run dev
• 對於 Next.js：npm run dev

---

步驟 4：執行自主管線

執行一體化的自主執行命令：

synctake run \
  --url http://127.0.0.1:5173 \
  --config ./synctake.json \
  --out ./demo.mp4

如果使用者提供了語音參考片段（例如 voice.wav），請傳遞 --ref-audio ./voice.wav 來克隆他們的聲音。

synctake run 自動執行的內容：

1. 無頭螢幕錄製： 透過 Playwright 啟動 Chromium，依序執行場景提示，使用主機自適應聚焦環高亮顯示元素，顯示原生提示徽章，並儲存校準後的 WebM。
2. 語音合成： 合成清晰的英語口語（或克隆使用者的聲音）。
3. 節奏與時間槽驗證： 確認沒有音訊片段超過其分配的場景時間。
4. 主畫布組裝： 將片段放置在精確的時間點，以無聲數位靜音填補間隙，並輸出校準的 48 kHz 立體聲音訊。
5. 無損混合： 將音訊標準化至廣播標準（-16 LUFS），並混合成 1080p H.264 MP4，影片無任何世代品質損失。

---

步驟 5：交付完成的影片

synctake run 完成後：

1. 確認輸出影片存在且非空（ls -lh ./demo.mp4）。
2. 將完成的影片成果連同其絕對檔案路徑連結呈現給使用者：

   "這是您完成的導覽影片：demo.mp4!"