电台汇报

---
name: radio-report
description: 把长报告变成可以自己听的旁白幻灯片，一个能离线打开的 HTML 文件，外观是复古电子管收音机。每页都有可修改的口播讲稿，自带播放器：播放暂停、拖动定位、0.75 到 2 倍速、自动换台。旁白免费，不需要任何密钥，用浏览器语音或可选的 Mac 预录音频；设备没有语音时显示讲稿。支持中文和英文。当用户想让别人“听”报告而不是开会、想要带旁白的幻灯片、不想自己录音，或点名要这个风格时使用。
version: 1.0.0
---

# 电台汇报

外观和播放器都在模板里：`assets/template.zh.html`（中文）和 `assets/template.html`（英文）。你负责写内容：复制对应语言的模板，填好标记的位置，样式和引擎一律不动。`scripts/check.mjs` 会逐字节比对，还会打开页面实际检查。

准确的样式数值和每条规则的理由见 `references/style.md`。

## 需要问用户什么

简报里没有的，一次问完，只发一条消息。

必须有：
1. 报告本身：文件或文字。
2. 谁来听，听完要做什么。没人回答时，默认听众是这份报告的普通读者，不要编造行动号召。

可选：
3. 幻灯片语言。默认跟报告一致。一份幻灯片只用一种语言。
4. 封面上的汇报人和日期。
5. 时长上限（如果有）。默认时长由报告决定，没有下限，也没有目标时长。
6. 内容是否真实。如果是虚构的，必须写声明。
7. 要不要预录音频（只限 Mac，见第 7 步）。

## 信息不全时怎么办

- **简报太单薄：** 复述用户给的事实，绝不编造，交付时列出所有推断出来的句子。下表每个位置都有对应规则。不要添加客户、数字、引语、来源或资历。你自己在两件事之间建立的联系（比如“这项计划针对那个问题”），如果报告没有写明，也算推断。
- **没有人能回答：** 按默认值继续，交付时列出你的假设。
- **时长由报告决定，绝不凑数。** 报告短，幻灯片就短，一台配一句讲稿也可以。用户要的时长超出报告能支撑的内容时，按实际内容做，并告诉他原因。要更短就合并、删讲稿；超过 14 台就做成两份。
- **没有真实链接：** 这份幻灯片不需要链接，也没有按钮要填。来源写成文字。有真实网址可以写成文字，绝不编造。

## 步骤

1. 读完整份报告。用一句话写出它的论点，再列出支撑论点的论断，最多 14 个。每个论断一台。记下你舍弃了什么，交付时要说明。
2. 把对应语言的模板复制到输出路径，比如 `deck.html`。不要凭记忆重写。其他语言用英文模板，改 `<html>` 的 `lang`，只翻译 `radio-ui` 里的值。
3. 在 `STATIONS:BEGIN` 和 `STATIONS:END` 之间，每台保留一个 `<section>`。按论断复制版式，删掉用不到的示例。只改 `data-slot` 元素里的文字，以及 `data-label`、`data-value` 属性。属性和各部分的顺序不要动。模板里的注释可以删。
4. 按下表填写。讲稿最后写，这样它是在补充幻灯片，而不是把幻灯片念一遍。
5. 运行 `node scripts/check.mjs deck.html`，内容是虚构的就加 `--fictional`。大约需要 10 到 25 秒。按提示改文字，再运行，直到通过。
6. 亲自打开看。每一台都要在 1280 宽和手机宽度下看过、读过。按播放，拖动指针，改语速，条件允许就听一台。
7. 可选录音，只限 Mac：`node scripts/render-audio.mjs deck.html`。每台大约 2 到 5 秒，每分钟音频增加约 0.4 MB。用 `--list` 查看语音，用 `--voice Tingting` 指定。讲稿改过就要重新运行，然后重新检查。不做这一步，浏览器自带语音也能免费朗读。
8. 可选讲义：用户要 PDF 时，运行 `node scripts/export-pdf.mjs deck.html out.pdf pages/`，然后查看 `pages/` 里的每张图。这些图由苹果的渲染器（`sips`）生成，结果可能和 Chromium 不同。

## 要填的位置

**单位**：一个西文字符算 1 单位，一个汉字算 2 单位，所以“28 单位”就是 14 个汉字。检查脚本会强制执行所有上限。

| 位置 | 含义 | 上限 | 简报单薄时 |
|---|---|---|---|
| `<head>` 里的 `title` | 浏览器标签页上的名称 | 70 | 用报告原名 |
| `deck-name` | 机身上的短名称 | 56 | 把报告名缩短 |
| `notice` | 全片唯一的一条声明，比如虚构或草稿 | 80 | 真实报告留空。虚构内容必填：“虚构案例：名称和数字都是编出来的。”不要在幻灯片或讲稿里重复 |
| `data-label` | 刻度上的台名 | 10（5 字），不含数字 | 一个说明主题的词，比如“开支” |
| `kicker` | 标题上方的小字，说明这一页是什么 | 28（14 字） | 一个朴实的主题词，比如“头条”“开支” |
| `title` | 论断，是一句可以被反驳的话。封面上写报告的主要结论 | 72（36 字），封面 64（32 字） | 用报告自己对结论的说法。报告没有结论时，写中性描述，并列为推断 |
| `lede` | 仅封面：报告讲什么 | 120（60 字） | 复述报告的范围，也可以留空 |
| `byline` | 仅封面：谁在何时汇报 | 70（35 字） | 留空。绝不编造姓名或日期 |
| `figure` | figure 版式的那个数字 | 10（5 字） | 只用报告写明的数字。没有数字就改用 points 版式 |
| `meaning` | 数字的含义和对比 | 180（90 字） | 只说报告说过的。报告没给对比就不写对比。可以留空 |
| trio 里的 `figure`、`label`、`source` | 正好 3 个数字，各自统计什么，各自的来源 | 8、60、80（4、30、40 字） | 必须正好 3 个，不足就换版式。三个数字会一起缩小以放进各自的栏，大小始终一致 |
| bars 里的 `name`、`val`、`data-value` | 2 到 6 行：行名、显示的数字、决定长度的纯数字 | 24、12（12、6 字）、数字 | 超过 6 行就留最大的，并说明其余在哪里。`data-value` 必须等于 `val` 里的数字 |
| points 里的 `head`、`text` | 1 到 4 条：要点和解释 | 40、110（20、55 字） | 宁可少写，不要凑数 |
| `source` | 这一页所有数字的来源 | 130（65 字） | 见“来源” |
| `script` | 语音念的内容，用幻灯片的语言。它同时是讲稿和可编辑的备注 | 最多 1100（550 字，约两分钟）。至少 8（4 字）：一句短话就够 | 只讲报告说过的。见“怎么写讲稿” |

## 来源

每个数字都要带着来源一起显示。有数字却没有来源的页面，检查不会通过。

- 写清文件和具体位置：“来源：2025 年度申报表，表 3”。报告只说了出处、没说具体位置时，就写它给的：“来源：馆内闸机统计”。
- 报告给了数字却没说出处时，一字不差地写 `来源：报告原文，未注明出处`（英文写 `Source: as stated in the report; no document cited`）。检查脚本接受这个写法并打印提醒，你要把这些页列给用户。
- 只有这一页没有数字时，来源才可以留空。
- 封面没有来源行，所以只能出现年份。

## 怎么写讲稿

- 这是说出来的话。句子要短，一次一个意思。中文每分钟约 250 字，英文每分钟约 150 词。
- 补充幻灯片表达不了的：报告给出的原因、保留意见、接下来做什么。报告没有给，就说明它没有写，或者把讲稿写短。不要照着幻灯片念。报告没写的常识也算推断，要列出来。
- 数字写成阿拉伯数字，写“18%”，不写“百分之十八”。语音能读对，脚本也能核对。讲稿里说到的每个数字都要出现在这一页上，单独的年份除外。报告原文用汉字数字时（比如“两小时”）可以保留，但这一页上也要写同样的字，并带来源。
- 不要用语音容易读错的缩写。只用纯文本。
- 只用一种语言。中文版可以保留不超过 5 个大写字母的缩写，比如 AI、KPI，其他西文一律不要。
- 听众可以在页面里点“修改讲稿”，点“另存一份”会生成包含修改的新文件。预录过的一台改了讲稿后，会改由本机语音朗读。

## 旁白怎么工作

播放器按这个顺序选择：有内嵌录音就用录音；否则用浏览器里与幻灯片语言相同的语音；再没有就进入跟读模式，指针按阅读速度移动，讲稿高亮当前句子，并显示一行字说明为什么没有声音。绝不会用英文语音读中文，反过来也一样。要告诉用户：音质取决于他们的设备。

## 交付物

- 一个能离线打开的 `.html` 文件，不依赖其他文件。
- 可选：用户要求时提供 PDF 讲义。
- 一段简短说明：舍弃了报告的哪些内容、哪些句子是推断、有什么假设、哪些页的来源只是简报本身。

## 交付前检查

- [ ] `node scripts/check.mjs` 通过，除 `--fictional` 外没有加别的参数，并且确实跑了页面检查。
- [ ] 每一台都在 1280 宽和手机宽度下看过、读过。
- [ ] 按过播放，拖过指针，改过语速，看过自动换台。
- [ ] 页面上每个数字都来自报告，并显示了来源。
- [ ] 没有编造，也没有凑数。推断和假设都已列给用户。
- [ ] 内容是虚构的话，声明只说一次，任何画面都没有重复。
- [ ] 界面和文字只有一种语言。
- [ ] 如果录了音，最后一次修改后重新录过，并告知用户苹果的许可限制。
- [ ] 如果做了 PDF，每一页都看过 `sips` 渲染的结果。

## 什么时候不要用

- 有人在场的现场演讲：语音和自动换台只会碍事。
- 价值在于大量表格、必须完整阅读的报告：直接发文档。
- 用浏览器语音读敏感内容：有些设备会把文字发给在线语音服务。请选择本机语音、在 Mac 上预录，或用跟读模式。
- 必须听起来像真人的场合：这些都是合成语音。
- 没有数字的观点文章：写成文章更好。

## 查不出来的事

自动检查没有人耳参与。事件和音量只能证明确实发声了，不能证明 48,200 这样的数字读得好。有人能听的话，请他听一遍数字。没人听过就在交付时说明。

## 运行要求

- Node 18 或更新版本。检查需要 Playwright：`npm install playwright`，再运行 `npx playwright install chromium`。如果装在别处，把 `NODE_PATH` 设为那个 `node_modules` 文件夹。只有确实装不了才用 `--static`，并在交付时说明。
- 用现代浏览器打开。Chrome、Edge、Safari 自带语音；Firefox 取决于系统。
- `render-audio.mjs` 需要 macOS，系统自带 `say` 和 `afconvert`。苹果只许可个人、非商业使用其语音，商业发布录音前请先查看条款。
- `export-pdf.mjs` 需要 Playwright，生成页面图片还需要 macOS。