synctake

SyncTake 编码代理技能

本技能指导编码代理（Claude Code、Cursor、Antigravity、OpenCode、Codex）如何自主制作精良的、带旁白的 Web 应用演示视频。

---

🎯 何时激活此技能

当用户提出以下请求时激活此工作流：

• "为该项目/功能创建一个演示视频/导览"
• "录制一个展示应用工作方式的视频"
• "制作一个该新 UI 的 30 秒/60 秒导览视频"
• "通过带旁白的视频展示此功能"

---

🛠️ 第 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 词每分钟（约每秒 2.4 词）。一个 10 秒的场景应包含大约 20–24 个词。
• 场景时间戳（at）： 必须严格递增。
• 屏幕标注： 保持 title 和 callout 简短有力（它们会显示为原生浮动卡片）。
• 焦点： 使用真实、有效的 CSS 选择器（#id、.class、[data-testid='...']）。
• 旁白： 编写自然、口语化的语言。切勿直接朗读原始代码符号、选择器或时间戳。

{
  "title": "功能导览",
  "duration_seconds": 30.0,
  "voice": {
    "provider": "system"
  },
  "scenes": [
    {
      "id": "01-overview",
      "at": 0.0,
      "title": "实时集群概览",
      "callout": "跨区域的实时健康与遥测指标",
      "focus": "#metrics-card",
      "text": "欢迎！在本导览中，我们将探索实时集群健康状态与自动修复功能。"
    },
    {
      "id": "02-actions",
      "at": 12.0,
      "title": "一键部署",
      "callout": "带人工审批的自动验证",
      "focus": "#deploy-btn",
      "text": "只需单击一次，我们的流程即可验证配置变更并执行滚动更新。"
    }
  ]
}

---

第 3 步：确保开发服务器正在运行

检查 Web 应用的开发服务器是否已在本地端口上监听：

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！"