Auto-Loom
将任意 Web 应用转化为带有配音的、自动演示的 MP4 视频。页面会自动滚动、高亮元素并在路由间导航，AI 声音同步配音——时间精确到毫秒级。无需手动录屏，无需费时的 Loom 录制。只需编辑一行旁白，几分钟内即可重新渲染。
工作原理： ElevenLabs 为每个故事板节拍生成一个单独的音频片段。ffprobe 精确测量每个音频片段的时长。Playwright 在每个节拍的持续时间内驱动浏览器，同时录制窗口。ffmpeg 合成最终的 MP4 文件并添加字幕轨道。音频时长是基准，视觉效果与之同步，因此音画同步精确无误。
此文件夹是整个引擎。 兄弟节点是基于相同脚本的简化入口点：
- auto-loom-proof — 软件工厂的验证视频：在摄像头前逐条演示构建的验收标准
此 SKILL.md 涵盖引擎以及开发者模式：您拥有代码库，应用在 localhost 上运行，并且可以向 JSX 添加稳定的选择器。
环境搭建（一次性，约 3 分钟）
cd <此技能文件夹>
bash scripts/setup.sh # 安装 Playwright + Chromium，创建 .env.local
# 编辑 .env.local → 添加你的 ElevenLabs API 密钥
node scripts/doctor.mjs # 验证 node、ffmpeg、playwright、密钥、语音
还没有 ElevenLabs 账户？使用维护者的推荐链接注册：https://try.elevenlabs.io/atherial。
doctor.mjs 会打印任何缺失组件的精确修复方法。要求：Node 18+、ffmpeg (brew install ffmpeg)、ElevenLabs API 密钥。语音选项：references/voices.md。
冒烟测试（30 秒，录制 example.com）：
node scripts/run.mjs --beats examples/smoke-beats.json
第 0 步——先与用户沟通
不要立即开始构建。请先询问：
1. 我们要录制哪个 URL 或应用？它是本地运行的吗？
2. 收件人是谁——姓名和背景？
3. 要讲述什么故事？变更了什么内容，或者我们首次展示什么？
4. 应该重点介绍哪些具体功能、指标或部分？
5. 语气是什么？（客户更新、内部演示、潜在客户展示）
6. 应用是否需要登录？（参见 references/auth.md——切勿在聊天中索要密码）
7. 目标时长——30 秒、60 秒还是 75 秒？
如果时间紧迫：询问 1-3，其余内容从应用中推断。
第 1 步——编写故事板 (beats.json)
在触碰任何代码之前先编写旁白，并逐字获得批准。脚本规则和有效的故事板框架：references/tts-rules.md。
{
"meta": {
"title": "Acme 仪表盘演示",
"slug": "acme-walkthrough",
"cta": "请将您的反馈发送给我，我们进入下一阶段。",
"targetLengthSec": 70
},
"baseUrl": "http://localhost:3000",
"viewport": { "width": 1920, "height": 1080 },
"beats": [
{
"id": 1,
"page": "/dashboard/insights",
"text": "嗨 Jim。我们为您的人工智能可见性追踪器推送了一些更新。",
"actions": [
{ "fn": "waitFor", "sel": "[data-vn=kpi-row]" },
{ "fn": "scrollToEl", "sel": "[data-vn=kpi-row]", "opts": { "instant": true } },
{ "fn": "hl", "sel": "[data-vn=kpi-row]" }
]
}
]
}
完整模式：schema/beats.schema.json。动作表和选择器指南：references/actions.md。登录选项（脚本化步骤或已保存的会话）：references/auth.md。
在开始消耗资源之前检查：
node scripts/validate.mjs --beats <file> # 结构 + TTS + 节奏检查
node scripts/run.mjs --beats <file> --script-only # 打印旁白并停止
验证器可以捕获未知动作、缺失的选择器、TTS 问题（em 破折号、纯首字母缩写、长句）以及无法适应目标时长的节奏。
--script-only 是节省成本的审查关卡：它会打印每个节拍的旁白及其预估时长，并在任何 ElevenLabs 调用或录制之前退出。在此处获得脚本批准，然后不带该标志重新运行以消耗资源。
第 2 步——为页面添加标记（开发者模式）
Playwright 需要稳定的选择器。有权访问代码库时，向组件 JSX 添加 data-vn 属性：
<div data-vn="kpi-row" className="grid grid-cols-4 gap-4">
<Card data-vn="competitor-chart" ...>
然后引用它们：{ "fn": "hl", "sel": "[data-vn=kpi-row]" }。
录制时抑制交互式向下钻取。 带有 role="button" / tabIndex={0} 的可点击卡片可能会在高亮时自动聚焦，并在视频播放过程中打开一个抽屉。通过演示模式标志将其隐藏：{!isDemoMode() && <MetricBreakdownSheet ... />}。
如果应用需要在本地进行身份验证，则可以配置演示模式（跳过身份验证，使用与旁白数字完全匹配的固定数据），或者使用 references/auth.md 中的身份验证路径。
关于 CSP 的说明： 录制器启动 Chromium 时使用 bypassCSP: true，以便它可以向严格的 CSP 页面注入 presenter.js。如果您将其指向一个带有活跃会话的生产环境应用，请注意该自动化浏览器上下文中的内容安全策略已被禁用。
第 3 步——单个命令
node scripts/run.mjs --beats <file>
该命令会执行：验证 → 音频（按文本哈希缓存） → 预检（在录制任何内容之前，无头运行选择器检查） → 录制 → 字幕 → 合成 → 验证。输出位于 demo-video-out/<slug>/：
<slug>-demo.mp4— 最终视频（H.264/AAC，软字幕轨道）<slug>-demo-contact-sheet.png— 用于快速检查的采样帧qa/beat-NN.png— 每个节拍保持点的精确截图captions.srt、audio/、video/recording.webm
所有标志：--script-only（打印旁白脚本并在任何 ElevenLabs 调用或录制前退出——第 1 步的审查关卡）、--preflight-only（检查选择器，不消耗资源）、--skip-audio（仅视觉变更——重用音频）、--skip-preflight（跳过无头选择器检查——仅当预检刚刚通过且没有任何更改时使用）、--burn-captions（将字幕硬编码到像素中，适用于剔除音轨的平台）、--no-captions、--out <dir>、--env <envfile>。
第 4 步——发送前验证
run.mjs 会检查时长（MP4 = 音频总和在 0.5 秒内）、音频电平（静音轨道检测），并生成 QA 截图。您仍需人工检查：
- 联系表 +
qa/beat-NN.png：每个帧显示其节拍所叙述的内容——无登录页面、错误状态或意外的模态框。 - 第一个节拍命名收件人；最后一个节拍逐字呈现行动号召（CTA）。
迭代
- 旁白编辑 → 重新运行；仅重新生成已更改节拍的音频。
- 视觉/节奏编辑 →
--skip-audio。 - 选择器失效 →
--preflight-only会精确显示哪个节拍和选择器有问题。
已知问题
- 热重载会清除注入的 presenter。 已处理——在录制每个节拍之前会重新注入 presenter。但请避免在录制时编辑应用。
- 端口漂移。 如果 3000 端口被占用，
yarn dev会使用 3001 端口——更新baseUrl。 - 免费与付费语音。 在免费套餐上，克隆/库语音会抛出
payment_required错误。doctor.mjs会在渲染前捕获此问题。 - i18n 重定向。
/en/dashboard→/dashboard这样的重定向会被正确跟随；同一页面的节拍不会重新导航。 - 交付。 MP4 是自包含的——可通过电子邮件、Slack、LinkedIn 私信、Notion 嵌入发送，或导入 Descript 以在顶部添加个人介绍。