蓝图讲解

---
name: blueprint-explainer
description: 制作 60 秒以内的无声讲解视频，画面像一张活的工程图纸：蓝图底纸、自动绘出的线条、尺寸箭头、唯一的琥珀色重点，全片一个镜头连续运动。当用户想用屏幕文字（不配音）把一个概念、流程或一组数字讲清楚时使用，支持 16:9 和 9:16。
version: 1.0.0
---

# 蓝图讲解

你只填一个 JSON 文件，画面由引擎画出来。视觉都写在 `assets/engine.html` 和 `references/style.md` 里，所以不管什么主题，成片都和 `example/explainer.mp4` 是同一个样子。

不要改 `assets/engine.html`，不要自己写样式或动画，也不要新增场景类型。内容放不进现有场景，就调整内容。

## 运行环境

- Node.js 22 或更高版本
- Playwright 和 Chromium：`npm install playwright && npx playwright install chromium`
- FFmpeg（在 PATH 里，或设置 `FFMPEG=/path/to/ffmpeg`）

## 先问清楚

1. **核心观点。** 观众看完能复述的一句话。
2. **观众。** 给谁看，他们原本不知道什么。
3. **数字和来源。** 要出现哪些数字，分别从哪里来。如果用户没有数字，先问能否用示意数字，用了就要在画面上标明是示意。
4. **画幅和语言。** 16:9（默认）或 9:16；英文或简体中文。
5. **是否需要免责说明。** 涉及钱、健康、法律的主题都需要。

用户答不上来时，你先做一个合理的选择，并在交付说明里写清楚。

## 步骤

1. 读 `references/style.md`。
2. 把故事写成每个场景一句话：一个标题，3 到 6 个各讲一点的场景，最后是总图。时长由阅读时间决定，要先删字，而不是加秒数。
3. 每个数字都用代码算出来，或者取自有名字的来源。不要心算估计。
4. 把 `assets/scenes.template.json` 复制到工作目录，命名为 `scenes.json`。删掉用不上的场景类型，`title` 保持在最前，`sheet` 保持在最后。替换所有 `{{SLOT}}`。
5. 把屏幕上出现的每个数字记入 `meta.numbers`，写上检查脚本能运行的 `formula`，或能展示的 `source`。详见下面的“数字”。
6. 检查：`node scripts/check.mjs scenes.json`，把报告的问题全部修掉。
7. 打印时间线：`node scripts/render.mjs scenes.json --timeline`。
8. 渲染：`node scripts/render.mjs scenes.json out/explainer.mp4`。竖屏加 `--portrait`。
9. 逐项完成“交付前检查”。

## 场景类型

| 类型 | 用途 | 主要字段 |
|---|---|---|
| `title` | 开场的问题或论断，写在制图辅助线上 | `title`、`dim`、`subtitle` |
| `dimension` | 一个数量拆成几部分，按比例绘制 | `heading`、`parts`、`total`、`caption` |
| `calc` | 一行一行列出的算式 | `heading`、`rows`、`callout`、`caption` |
| `curve` | 由公式画出的变化曲线 | `heading`、`x`、`y`、`series`、`zone`、`gaps`、`caption` |
| `bars` | 比较 2 到 6 个数量 | `heading`、`bars`、`caption` |
| `flow` | 2 到 4 步的流程或循环 | `heading`、`nodes`、`loop`、`caption` |
| `detail` | 核心观点，放在带刻度的详图圆内 | `statement`、`label`、`callouts` |
| `sheet` | 必须是最后一个场景：镜头拉远露出整张图纸，结论写在图框标题栏里 | `takeaway`、`notes` |

## 写文字

- 拉丁字母由引擎统一画成大写，数字也由引擎绘制；你照常书写即可。
- `[[双方括号]]` 里的文字显示为琥珀色。每个场景只能有一处琥珀色，`highlight: true` 也算一处。
- `\n` 强制换行。中文一定要用它控制断行，别让一个词被拆到两行。
- `seconds` 是镜头在该场景停留的时间。时间不够读完，检查脚本会报错。
- 中文场景把 `meta.lang` 设为 `zh`，图纸上的固定标签会切换成中文。整条视频不要中英混杂，单位写“元”或用户指定的货币。

## 数字

屏幕文字里的每个数字，都必须在 `meta.numbers` 里有一条记录：

```json
{ "value": "1,967", "formula": "1000*1.07^10" }
{ "value": "7", "source": "输入：示意年化收益率" }
{ "value": "31", "source": "澳大利亚统计局 6401.0，2026 年 9 月季度" }
```

检查脚本会运行每个公式，结果四舍五入后与 `value` 不符就报错。柱子、分段、算式结果、曲线差值的图形与标注不一致，也会报错。坐标轴刻度本身就是尺度，不需要记录。没有亲眼看过的来源，不要写进 `source`。

## 交付内容

- `explainer.mp4`：1280x720（或 720x1280），30 fps，H.264，yuv420p，无声，不超过 60 秒
- `scenes.json`：源文件，用于重新渲染
- 一份简短说明：列出每个数字的来源，以及你做过的假设

## 交付前检查

- [ ] `node scripts/check.mjs scenes.json` 退出码为 0。
- [ ] `ffprobe -v error -show_entries format=duration -of csv=p=0 explainer.mp4` 输出不超过 60。
- [ ] `ffprobe -v error -select_streams v -show_entries stream=codec_name,pix_fmt,width,height,r_frame_rate -of csv=p=0 explainer.mp4` 输出 `h264`、正确的尺寸、`yuv420p` 和 `30/1`。
- [ ] `ffprobe -v error -select_streams a -show_entries stream=index -of csv=p=0 explainer.mp4` 没有输出（无音轨）。
- [ ] 对 `--timeline` 列出的每个场景，都用 `ffmpeg -ss <时间> -i explainer.mp4 -frames:v 1 scene-<序号>.png` 抽了一帧，并亲眼看过图片。
- [ ] 每张抽帧里，文字都没有被裁切、压线，也没有和其他标注相交。
- [ ] 每张抽帧里，琥珀色最多只标一个重点。
- [ ] 最重要的三个数字已脱离 `scenes.json` 重新算过，结果一致。
- [ ] 示意数字在画面上写明了是示意；主题需要时已设置 `meta.disclaimer`。
- [ ] 中文内容确认用真实的中文字体显示，没有出现方框。中文依赖系统字体，拉丁字母和数字不依赖。
- [ ] 临时帧已删除。

## 不适合的情况

- 故事依赖真实影像、人脸、产品或地点。
- 需要配音、音乐或口型同步。这个风格是无声的。
- 主题需要温度和情感，比如悼念或个人故事。技术图纸会显得冷。
- 必须遵循他人品牌视觉的品牌片。
- 只有观点，没有可画的结构。没有数量、部件或步骤，图纸就只是装饰。
- 视频必须超过 60 秒。

## 渲染之前

- 在运行脚本的位置安装 Playwright（npm install playwright）。如果还是找不到，把 NODE_PATH 设为那个 node_modules 文件夹。
- 30 秒的视频可能要渲染好几分钟，请放到后台运行，并为任何时间上限留出余量。
- check.mjs 计算阅读时间时会把标题和副标题都算进去。场景被拒绝时，延长时长或删字。
- 流程标签控制在一两个短词，16:9 最多四个节点。换行是自动的，所以全量渲染前先给每个场景渲染一张测试帧。
- 这个技能画的是图解和图表，没有实物设备这种场景类型。题目需要时请说明。
- 没人能回答问题时，继续做，并在回复里列出所有假设。