video-demo

视频演示

scripts/demo 会录制 Web 应用，并将 demo-out/ 写入该项目的工作区：每个场景都包含一个带旁白的 mp4、一个海报、静态视网膜图，以及 full-tour.mp4、manifest.json 和 index.html。全部在本地完成。引擎从此技能运行；不会向被录制的应用中安装任何内容。

不可妥协的要求

以下每项都会耗费一次运行，或考验用户的耐心。

1. 使用固定版本的构建产物，绝不使用开发服务器。 模块图属于正在编辑源代码的人。将构建产物复制到私有位置，并通过读取打包文件来验证其 API 基础地址。没有对应代码仓库的 URL 属于 site 模式；localhost 上的 URL 是开发服务器，绝不能用于录制。
2. 在 build 模式下，在进程内模拟每个请求，并固定时钟。 发布语料库会泄露数据，而真实账户会发布真实用户的地址。site 模式有意放弃这两项保护：只允许访问公开页面。
3. 自行管理端口和输出目录。 工作室不会接管它没有启动的服务器。绝不要按模式使用 pkill。
4. 视频使用 1080p60，静态图使用 2x。 这是两项独立设置。4K 视频会卡顿，因为吞吐量受固定的每秒像素预算限制。
5. 先操作，再放大结果进行讲解。 每行只讲一个对象。对象尚未出现前，绝不要开始讲解。如果应用有自己的计时器——例如撤销窗口或 toast——就要在计时器内完成操作，之后再讲解，否则影片展示的功能会无法正常工作。
6. 先拍一个场景，然后停下来询问（第 8 步）。在继续拍摄另外二十六个场景之前，它就发现了四个缺陷。
7. 每次都要查看 PNG。 构图错误的场景即使顺利录制完成，也是失败；只有亲自查看静态图才能发现问题。
8. 他们确认之前，一切都不算定稿。 任何关于措辞、构图、节奏、涵盖内容或声音的意见，都意味着要重新录制，而不是进行协商：修改后重新录制。他们看不到你能看到的内容，因此“太长了”“再放大些”和“别放大那么多”都是完整明确的指示，而且重复录制一个场景成本很低。

工作流

1. 根据收到的信息选择模式。不要提问。 公共主机上的 http(s) URL 属于 site，工作区为 ~/.video-demo/<host>/。localhost 或私有地址上的 URL 属于开发服务器：找到其背后的仓库，并将请求视为针对该仓库。没有 URL 就使用当前所在的仓库，因此向上查找 Web 应用（旁边有 Vite、React Router、Next、Astro、SvelteKit 或 Remix 配置，且 package.json 中包含构建脚本）。恰好一个则使用 build；多个则询问要选哪一个；没有则询问 URL 或路径。若工作区的 .origin 已指向此仓库，则复用，不要再次搭建。用一行说明模式和工作区路径，然后继续。
2. 运行 scripts/doctor.sh，然后先做好准备，再向用户询问任何其他事情。 用户安装的是一项技能，不是来帮你运行三个脚本的。用一行说明缺少什么，再说明你提议安装什么以及大致大小，并在他们同意后运行。scripts/install.sh 会安装引擎和 Chromium（约 250MB），并在包管理器支持时一并安装 ffmpeg；scripts/install-voice.sh 用于安装语音（约 350MB），如果他们不介意无声拍摄，也可以不装。未经询问，绝不安装任何东西；也绝不要把 doctor 报告交给用户让他们自行解读。脚本不会、也不应该做两件事：升级他们的 Node，因为由哪个工具管理 Node 应由他们决定；运行 sudo，因为没人看着的脚本弹出密码提示后只会卡住。这两种情况下，脚本都会打印一条命令，你把它转告用户即可。
3. 仅做探索，不写入任何内容。 site：打开 URL 并阅读页面，了解页面用途、值得展示的三项内容，以及哪些内容足够稳定、适合指向。如果打开的是登录页面，就停止：已登录的应用应从其仓库拍摄，因此请用户提供该仓库或一个公开 URL。build：从 package.json 原样复制构建命令；从框架配置中找出输出目录；检查 .env* 中任何绝对 API 主机（将其加入 build.forbid）；主题引导脚本读取的键；现有的 fixture API 或 MSW 处理器；data-testid 的密集程度；以及无需凭据即可访问的路由。
4. 运行 scripts/scaffold.mjs <appRoot>，或 scripts/scaffold.mjs --site <url>。这两种方式都不会向应用中写入任何内容。
5. 填写工作区的 demo.config.ts。 任何必填字段仍未知，就说明探索尚未完成。参阅 config.md
6. 仅限 build：编写 mock.ts 和 seed/。 如果仓库有自己的数据 fixture，就复用，但绝不要使用导入 @playwright/test 的文件：一次运行中出现两份会导致 Playwright 拒绝运行，并使整个语料失败，而不只是出问题的那个场景。然后运行 DEMO_VOICE=0 scripts/demo --grep smoke。如果仓库有 fixture API，就复用（参阅 mocking.md）。阅读静帧：确认已登录、已填充种子数据、主题正确，且没有登录页面。阅读捕获日志。修正这两项，直到都正确，然后编写 demo/ui.ts，只包含 smoke 测试已验证的内容。
7. 按照用户要求的范围拍摄。 用户指定的功能就是一个场景：编写、拍摄并交付。用户要求“录制主页上的搜索”时，不要给出十个场景的提案；也不要因为产品还有更多功能，就悄悄扩大范围。只有当用户要求展示整个产品时，才提议 6 到 10 个场景，每个场景包含一个标题和一行简介，按导览顺序排列，并询问先拍哪一个。
8. 停止。 为这一个场景配音拍摄。确认朗读次数与 say 调用次数一致、没有超时、语速稳定。阅读每一张静帧。提供用户 mp4 的路径，并询问文案的语体、缩放比例、节奏和语音。在他们回答之前，不要写入任何其他内容。
9. 然后用 --grep 每批处理三到四个场景；清单会合并。每批处理后都阅读静帧。迭代场景时，DEMO_BUILD=0 scripts/demo 可以跳过重新构建——耗时约二十秒，而不是四分钟；生成语料的那次运行则不要设置它。
10. 使用 DEMO_TRACE_FRAMES=1 完整运行，然后运行 scripts/gaps.mjs 并打开 demo-out/index.html。报告捕获表格和任何较慢的片段。

一个场景

scene('tasks', { title: 'Your to-dos, beside your calendar', blurb: '...' },
  async ({ actor, page, shot }) => {
    await actor.click(page.getByRole('radio', { name: 'Today' }));
    await actor.settle();
    await actor.spotlight(
      row('Send Sam the feedback'),
      'And this one is from yesterday that I never got to, so it is flagged.',
      { scale: 1.8, stay: true }
    );
    await shot('overdue');
    await actor.unfocus();
  });

spotlight 接收旁白标记，然后将摄像机和光标移至该行开头的文字上。缩放比例取决于主体：面板约为 1.4，行约为 1.7，单个控件约为 2。描述整个屏幕的一行使用普通的 say，不进行缩放。unfocus 是一个提示，而非移动指令：只有在需要展示更大范围时，摄像机才会拉远，因此连续讲述同一区域的节拍会流畅衔接，而不会来回跳动。scenes.md · narration.md

绝不

字幕（语音就是传达信息的渠道）。云端 TTS（影片涉及私人数据）。Playwright 的 recordVideo（无法控制帧率、尺寸或起始时间；录制器会取代它）。默认使用 4K。音乐、片头卡或交叉淡化。根据路由爬取生成场景：场景是有明确重点的编排。重试：重试后的场景就成了另一部影片。

另外

更改任何捕获参数前，请先查看 capture.md。 关于构建、隔离和清单，请查看 runs.md。 运行失败或镜头看起来不对时，请查看 troubleshooting.md。引擎从此技能运行，因此修复 engine/ 后，机器上的所有项目都会立即受益：直接在此处编辑，无需传播更改。