Product Demo

---
name: product-demo
description: 录自己网页产品的演示：写步骤→record_web_demo 出片、每步截图和时间戳
---

# 产品演示录屏（网页）

## 适用场景
「给我的网站录一段演示」「把注册到下单的流程录成视频」「出一条竖版的产品操作视频」。
产出 = `demo.mp4`（假光标、点哪儿镜头推近哪儿、字幕）+ 每步一张截图 + `steps.json`（每步在成片里的起止秒数）。
只录自己的产品：本机起的开发服务器、工作区里的 .html、或者自己的线上站。

## 先弄清三件事（缺哪个问哪个，都清楚就别问）
1. **地址**：本机开发服务器（`http://127.0.0.1:端口/`）、工作区里的 .html（`{"goto":{"path":"site/index.html"}}`），还是线上网址。
2. **画幅**：横版 `16:9`（默认）；发抖音、视频号用 `9:16`，会按手机录（触屏 + 页面自己的手机版）。
3. **演示哪几步**：3~8 个动作最好看。超过 20 步就拆成几条录。

## 流程
1. **找元素**：是自己的项目就先 `read_file` 看源码里的 id、class；看不到源码就按页面上看得见的字找（`{"click":{"text":"开始使用"}}`）。
2. **写步骤**：第一步必须是 `goto`，每步只做一件事。先把步骤贴给用户看一眼，例：

```json
[
  {"goto": "http://127.0.0.1:3000/", "label": "首页"},
  {"caption": "三步生成一份月报"},
  {"click": {"text": "新建报表"}, "label": "新建"},
  {"type": {"selector": "#q", "text": "本月销售", "enter": true}, "label": "输入"},
  {"wait": {"selector": ".result", "timeout_ms": 8000}},
  {"zoom": {"selector": ".result", "scale": 1.6, "ms": 1500}},
  {"scroll": {"to": "bottom"}, "shot": false}
]
```

3. **试录**：第一条带 `max_sec: 30`，只为跑通选择器。出错会说第几步、为什么（找不到、被弹窗盖住、页面没打开），能截图时附一张现场截图 `steps/fail-NN.png`，用 `look_at_image` 带着具体问题去看，改那一步再录。
4. **整条**：跑通后去掉 `max_sec`（默认 120 秒）正式录。要慢一点就 `speed: 0.8`，要紧凑就 `speed: 1.5`。
5. **配音（可选）**：只有语音合成已经配好才做，没配就交字幕版，并说一句为什么没配音。
   - 旁白一步一句，用 `text_to_speech` 的 segments 一次合成，拿到每句时长；
   - 对照 `steps.json` 里每步的 `start` 和 `end`：哪句比那一步长，就在那步后面加 `wait`、或把 `caption` 的 `ms` 调长，重录一遍；
   - 每句按那一步的 `start` 摆进去，不要整轨从 0 秒铺下去。
6. **交付**：视频路径、每步截图目录、`steps.json`，再提醒一句「画布、图片、视频里的字遮不到，发出去前看一眼」。

## 参数速查
- `aspect`：16:9 / 9:16 / 1:1 / 4:3 / 3:4
- `auto_zoom`：点击、打字时镜头自动推近，默认开；某一步不想推近写 `"zoom": false`，想推多近写数字（1~2.5）
- `max_zoom`：自动推近的上限，默认 1.8
- `fps`：默认 30；`speed`：0.5~3
- `mask`：页面上还要遮的字，比如演示账号名、邮箱、公司名，每项至少 2 个字。本机路径、用户名、主机名会自动遮
- `out_dir`：工作区里的相对目录，不写就按时间起名
- `headless`：默认不弹窗口

## 硬约束
- 只用 `record_web_demo`。不要自己起 Chrome、Puppeteer 或 Playwright 录屏：它每次都开一个全新的隔离浏览器，没有登录态，用完即删，打码和自检都在里面。
- 录不了真实登录后的账号。要录登录后的页面，先在本机起一个演示账号的环境；用户让你「用我的浏览器录」，就照实说做不到、为什么。
- 打码自检没过、扫到没遮住的字，工具会拒绝出片。不要为了出片删掉步骤或关掉检查，先找出是哪里露了（通常是脚本直接写进输入框的值），在页面上改掉再录。
- `type` 要打的字里不能有要遮的内容：演示用的账号、邮箱写成假的。
- 配音只走 `text_to_speech`，不拿系统朗读凑。成片不加任何「AI 生成」水印。
- 字幕一句话说完，越短越好读（上限 40 个汉字）；中文不加字距。
- 旁白、字幕、发布文案里不写「一个人做的」这类说法。