黄墨速记

---
name: ink-yellow-notes
description: 为小团队的操作指南和经验分享做一份网页演示稿，页数不限。黑黄超大字、大块留白，配上用代码画的细线手绘小人和物件。自带翻页、总览、演讲备注、打印和编辑台，可导出可编辑的 PowerPoint 和 PDF。当有人要做指南、操作讲解、新人培训、团队手册，或点名要这种风格时使用。
version: 1.0.0
---

# 黄墨速记

你只写一个 JSON 文件。`scripts/build.mjs` 把它变成一个独立的 `deck.html`。样式都在 `assets/` 里，不要改。`scripts/check.mjs` 会像观众一样看渲染出来的页面，告诉你哪里要改。

只有需要具体数值时才读 `references/style.md`。完整的图形清单在 `references/figures.zh.md`。

## 要问清楚什么

一次问完，只问简报里没有的。

必须有：
1. 主题，以及听的人是谁。
2. 事实：这份指南到底讲什么，比如步骤、规矩、工具、名字。
3. 页数，如果对方有要求。
4. 语言：中文或英文，一份演示稿只用一种语言。
5. 团队或案例是真实的，还是虚构的？

可选：有出处的数字、照片、主题、页脚文字。

## 步骤

1. 按下面的表选页面和版式，把 `content.json` 写在输出文件旁边。
2. 选图形。运行 `node scripts/figures.mjs --find "calendar"`，或读 `references/figures.zh.md`。按“没有合适的图形时”处理。
3. 运行 `node scripts/build.mjs content.json deck.html`。
4. 用本技能里的脚本运行 `node scripts/check.mjs deck.html`。按提示改 `content.json`，重新生成，再跑，直到显示 PASS。不要为了通过去改 CSS 或引擎。
5. 自己逐页看，1280 宽和 390 宽都要看。检查通过不能代替这一步。读着别扭的句子要重写，说不清意思的图形要换掉。
6. 需要导出时，运行 `node scripts/export.mjs deck.html --pptx deck.pptx --pdf deck.pdf`。
7. PDF：运行 `node scripts/pdf-pages.mjs deck.pdf pages/ --deck deck.html`。它会核对页数和文字层有没有重复，再用 `sips` 把每页转成图片。每一页都要看。
8. PowerPoint：运行 `node scripts/verify-pptx.mjs deck.pptx --expect-slides N --deck deck.html --render thumbs/`。它会核对文件结构和数量，再用 `qlmanage` 画出每一页。每张图都要看。不要打开 PowerPoint、Keynote 或其他桌面软件。
9. 如果改过 `assets/`，或想确认控件在这台机器上确实能用，运行 `node scripts/drive.mjs deck.html`。

## 顶层字段

文件只有两个键：`meta` 和 `slides`。多写别的键，生成时就会报错。

| `meta` 字段 | 含义 | 限制 | 简报很单薄时 |
|---|---|---|---|
| `title` | 演示稿标题，用作文件名和浏览器标签 | 80 字以内，必填 | 用对方自己的说法 |
| `lang` | `"zh"` 或 `"en"`，同时决定控件的语言 | 必填 | 跟简报的语言一致 |
| `theme` | `ink`、`paper`、`sun` 或 `noir` | 必填 | `ink` |
| `displayType` | 中文标题字体。`grotesque` 粗黑体（默认），`songti` 特粗宋体，最有杂志感，`kaiti` 特粗楷体 | 可选 | 不写。给客户看的稿子用 `songti` |
| `footer` | 每页都印的一小行字，不能是免责声明 | 约 20 字。不写就用标题 | 不写 |
| `author` | 写进 PowerPoint 文件属性 | 可选 | 不写，绝不编造 |
| `fictional` | 团队或案例是编的，就写 `true` | 必填，布尔值 | 只要有编造就写 `true`。没人说得清就先问，问不到也写 `true` |
| `fictionalLabel` | 只印一次，在封面上，必须明说是虚构 | 80 字以内，`fictional` 为 true 时必填 | “虚构示例。” |
| `brief` | `"full"` 或 `"thin"` | 必填 | `"thin"` |
| `inferred` | 印在页面上、由你写而简报没有的文字。每个位置一条，或者每句一条，一字不差，不带 `*` 和 `{}`。页脚和虚构标注也算 | 数组。`brief` 为 `"thin"` 时不能为空 | 页面上印的每段文字都必须在 `inferred` 或 `given` 里，缺了 `check.mjs` 就不通过。它会打印清单，拿给对方确认 |
| `given` | 对方提供的文字，一字不差，写法同上 | 数组，可选 | 把对方的原话放在这里 |
| `sources` | `[{"claim": "...", "from": "..."}]`。`claim` 是幻灯片上带数字的原话，`from` 是出处 | 数组，可以为空 | 留空，并且不用数字 |

每一页有 `layout`、`notes`（演讲备注，纯文本，可以换行）、`variant`（可选，见“构图”），以及下表里的位置。

**演讲备注**也是你写的。只能复述页面和简报，不能加新的事实、名字或细节。简报单薄时，`check.mjs` 会打印全部备注，也要拿给对方确认。

## 版式和位置

字数限制写作“英文/中文”。`*` 表示必填。超过字数，检查就不通过。

在任何位置，`*词语*` 表示高亮，`{词语}` 表示这几个字不能拆到两行。中文本来就只在整词之间换行，每种屏幕宽度都一样，所以很少需要花括号；有不能拆开的短语时再用，比如 `{先查再问}`。不要靠加空格控制换行。如果 `check.mjs` 报告拆词，先用本引擎重新生成，再用花括号。

| 版式 | 用途 | 位置 |
|---|---|---|
| `cover` | 第一页 | `title*` 52/24，`sub` 120/60，`byline` 40/24，`figure*` |
| `statement` | 撑起全场的一句话 | `kicker` 28/14，`text*` 100/48，`figure*` |
| `section` | 开启一个部分，满版色块，配大数字 | `label` 24/12，`title*` 40/20，`sub` 90/44，`figure*` |
| `island` | 一幅大图加一小块文字 | `kicker` 28/14，`title*` 52/26，`body*` 230/110，`aside` 70/36，`figure*` |
| `agenda` | 这次讲什么 | `title*` 34/16，`items` 2 到 6 条 {`text*` 46/24}，`figure*` |
| `steps` | 按顺序的两到四步 | `title*` 52/26，`items` 2 到 4 条 {`head*` 24/12，`text*` 90/44}，`figure*` |
| `timeline` | 按时间展开 | `title*` 52/26，`items` 3 到 5 条 {`when*` 14/8，`text*` 64/32，`figure*`} |
| `compare` | 两边对比。**左边是错的做法（打叉），右边是对的做法（打勾）** | `title*` 52/26，`leftHead*` 22/12，`left` 2 到 4 行 54/28，`rightHead*` 22/12，`right` 2 到 4 行 54/28，`leftMark`，`rightMark`，`figure`（可选，右侧色块上的小图） |
| `tiles` | 三到六样东西，各配一幅图 | `title*` 34/16，`items` 3 到 6 条 {`head*` 20/10，`text` 52/26，`figure*`} |
| `checklist` | 需要确认的事项 | `title*` 44/20，`items` 3 到 6 条 {`text*` 64/32}，`figure*` |
| `bigword` | 解释一个词 | `kicker` 28/14，`word*` 16/7，`gloss*` 150/72，`figure*` |
| `quote` | 真实的引语 | `text*` 120/58，`who*` 44/24，`figure*`。`who` 必须是真实来源；虚构稿里可以是明显虚构的来源 |
| `stat` | 一个有出处的数字 | `value*` 8/8，`label*` 60/30，`source*` 70/36，`note` 130/64，`figure*` |
| `image` | 对方提供的照片或截图 | `title*` 40/20，`caption*` 130/64，`image*`，`alt*` 120/60 |
| `closing` | 接下来做什么，满版色块 | `title*` 52/24，`action` 110/54，`figure*` |

`image` 必须是 `data:` 地址：`node scripts/image-to-data.mjs photo.jpg`。没有真实图片，就不要用这个版式。

`leftMark` 和 `rightMark` 可以写 `cross`、`check` 或 `arrow`，默认左 `cross`、右 `check`。不好的做法写在左边。如果两边都不算错，都写 `arrow`。小标题或句子和标记意思相反时，`check.mjs` 不通过；但它只读得懂直白的说法，页面还是要自己看。

## 构图

每个版式有两到三种构图，这样一份稿子不会像同一个模板重复。引擎会自动选：每个版式轮换，起点取决于标题，所以不同的稿子长得不一样，也不会让两张满版色块页挨在一起。一般不用管；某一页看着不对时，再写 `"variant": "a"`、`"b"` 或 `"c"`。`cover`、`statement`、`island`、`bigword` 有 a、b、c，其他版式有 a、b。相邻两页不能版式和构图都相同。编辑台里在“构图”下选择。

几个名字看不出意思的位置：`kicker` 是标题上方的小标签。`aside` 是正文后的一行粗体。`gloss` 解释大字。`action` 是希望听众接下来做的那一件事。`note` 给数字补一句背景。

## 图形系统

一共 81 个有名字的图形：一组有性格的工作人物（21 种姿势）、灯泡、火箭、箭头、星星、图表、工具和桌面物件。名字必须一字不差。你不需要读 `assets/figures.js`。最好用的清单是 `references/figures.zh.md`。

```
node scripts/figures.mjs --list --zh         列出全部名称和中文说明
node scripts/figures.mjs --find "日历"       在中文说明和标签里查找
```

`figure` 有三种写法：

```json
"figure": "person-laptop"
"figure": null
"figure": [
  { "name": "person-thinking", "at": "c", "size": "l" },
  { "name": "bulb", "at": "ne", "size": "s", "rot": 8 },
  { "name": "arrow-curly", "at": "sw", "size": "s", "flip": true }
]
```

| 字段 | 含义 | 取值 |
|---|---|---|
| `name` | 图形的准确名称 | 必填 |
| `at` | 放在版式图形区的哪个位置 | `c`、`n`、`s`、`e`、`w`、`ne`、`nw`、`se`、`sw`，默认 `c` |
| `size` | 占图形区的比例 | `s` 36%，`m` 62%，`l` 100%，默认 `l` |
| `rot` | 倾斜角度 | -15 到 15 |
| `flip` | 左右翻转，让人物朝向文字 | true 或 false |

组合时，先放一个大图形，再在空角放最多三个小图形，后写的盖在上面。一个人加一件道具通常最好读。`timeline` 和 `tiles` 每条只能写一个名称或 `null`，不能写列表。`image` 没有图形。

### 没有合适的图形时

图形要画的就是这一页说的那件东西，一眼能看懂。火箭可以表示上线，不能表示送货车。图表画不能代表真实结果。

没有合适的，就写 `"figure": null`，那里会放一块纯黄色块。交付时说明是哪几页，方便对方补图。不要拿最接近的凑数，也不要临时画一个。`build.mjs` 和 `check.mjs` 都会拒绝不存在的名称，也不会推荐替代品。

## 缺东西时怎么办

- **简报很单薄。** 复述对方给的事实，什么都不要编。写 `"brief": "thin"`。把你推断出来的每一句一字不差地列进 `meta.inferred`，再把检查打印的清单拿给对方确认。宁可页数少，也不要灌水。
- **某个事实不知道。** 写句子时绕开它。如果必须露出空缺，这些说法能通过检查：“负责人待和团队确认”“链接稍后补充”。不要用方括号、`TBD`、`TODO`。
- **没人能回答。** 继续做，把假设写进 `meta.inferred` 和交付说明。
- **页数不同。** 多少页都行。一页就是 `cover`。六页以内，用 `cover`、内容页和 `closing`。大约 15 页起，每个部分用 `section` 开头。事实不够就不要硬凑页数：说明这些事实撑得起几页，给对方这个选择。
- **没有真实链接。** 不写，或写“链接稍后补充”。绝不编网址。
- **数字。** 页面和备注一视同仁：每个数字都要有 `meta.sources` 条目，而且来自对方。“三周”“三成”这样写成汉字的数量也算。只有一个例外：汉字写的数量正好等于这一页列出的条数，比如三条清单上方的“这三件事”。序数、星期和“一”不算。要数页面上别的东西，比如口号有几个字，就加一条出处说明，或者改写。绝不编造客户、成果、评价或资历。
- **虚构内容。** `fictional` 写 true。标注只在封面印一次，其他地方都不要重复，页脚也不行。

## 怎么使用这份演示稿

方向键、空格、Page Up、Page Down、Home、End 翻页；手机上左右滑动。`O` 总览，`N` 备注，`S` 演讲者窗口（备注加计时），`P` 打印或存 PDF，`E` 编辑台，`F` 全屏，`?` 帮助。

编辑台可以直接改文字、高亮选中的词、换图片、拖动或用按钮调整页序、增加、复制和删除页面、换版式和主题、摆放图形、改备注。**保存**会下载一个带修改的完整 HTML 文件，之后打开这个新文件继续改。没保存的修改也会留在浏览器里。再次打开同一个文件时会自动恢复，并显示一个“丢弃”按钮。

## 交付物

- `deck.html`：一个独立文件，没有任何外部请求。
- `content.json`：它的源文件。
- `deck.pptx` 和 `deck.pdf`：需要时提供。

**中文字体：** `songti` 和 `kaiti` 用的是 Mac 自带字体，其他系统会换成最接近的衬线字体。

**中文 PDF：** 在 Mac 上，浏览器可能把 PDF 文字层里的个别汉字写成部首形式（比如把“口”写成“⼝”）。页面看着没问题，但搜索或复制这些字可能对不上。如果对方在意搜索，要说明；HTML 和 PPTX 没有这个问题。

**交付 PowerPoint 时要明确告知：** 文字和演讲备注可以编辑；色块、高亮和线条是可编辑的形状；图形和照片是图片。标题和带高亮的行用了固定换行，这样才和页面一致；重写时把换行删掉即可。

## 交付前检查

- [ ] `check.mjs` 显示 PASS，而且是完整运行，不是 `--static`。
- [ ] 我在 1280 宽和 390 宽都逐页看过。
- [ ] 每个图形画的都是这一页说的东西。写了 `null` 的页面都在交付说明里点名了。
- [ ] 没有编造。每个数字都有出处。单薄简报的推断句子都给对方确认了。
- [ ] 虚构稿只在封面说明一次。
- [ ] 每一页都写了演讲备注。
- [ ] 如果导出了：`pdf-pages.mjs` 和 `verify-pptx.mjs` 通过，每页 PDF 和每张幻灯片图片都看过，并告诉了对方哪些可编辑、哪些是图片。

## 什么时候不用

- 正式的董事会、法律或财务材料，卡通小人会削弱分量。
- 数据密集的汇报。每个 `stat` 页只有一个有出处的数字，也没有真正的图表。
- 严肃沉重的主题，比如疾病、离世、安全事故。
- 必须使用自家品牌色的场合。

## 环境要求

Node 22 或更高版本。生成、检查和导出都不需要 npm 包。`check.mjs` 和 `export.mjs` 会自动找一个 Chromium 系列的无界面浏览器，Chrome 也可以。它只启动一个隐藏的浏览器进程，用完就关。找不到时：`npm install playwright && npx playwright install chromium`，或把 `IYN_BROWSER` 设成浏览器程序的路径。`drive.mjs` 本身需要 Playwright：`npm install playwright`，必要时用 `NODE_PATH` 指向它的 `node_modules`。

`pdf-pages.mjs` 出图需要 `sips`，`verify-pptx.mjs --render` 需要 `qlmanage`，Mac 都自带。其他系统上检查照常运行，只是没有图片。

笔记本上的耗时：生成不到一秒；`check.mjs` 每页约一秒；导出几秒钟；`drive.mjs` 不到一分钟。