剪影季报

---
name: cut-out-report
description: 用用户的真实数字，做一份可编辑的浏览器汇报演示，适合季度内容复盘、受众洞察和社交渠道报告。超大单色标题加炭灰第二个词、冷灰页面、倾斜标签、单色剪影人物，图表由数据直接绘制，每个数字都标来源，带浏览器编辑台，可导出可编辑 PPT 和 PDF。当营销人员或小团队要做季度报告、内容复盘、渠道报告、受众分析，或点名要这个风格时使用。
version: 1.0.0
---

# 剪影季报

样式全部放在 `assets/` 里。你只写一个 JSON 文件，`scripts/build.mjs` 会生成一个独立的 HTML 演示。不要改 CSS、引擎和人物图形。`scripts/check.mjs` 会和原件比对，改过就不通过。

精确的设计参数和版式见 `references/style.md`。

## 要向用户问什么

一条消息问完，只问需求里没有的内容。

1. 真实数字（CSV 或 JSON），以及每个数字的来源（来源名称会印在页面上）。
2. 组织名称和报告周期。
3. 发生了什么：哪些做对了、哪些没做好、为什么，用用户自己的话。
4. 接下来做什么：每一步的负责人和时间。
5. 可选：团队成员姓名和职责；团队照片，仅限用户主动提供。
6. 可选：配色、语言（每个版本只用一种语言）、页数。

## 步骤

1. 把 `assets/starter.json` 复制到工作目录，命名为 `content.json`。CSV 放在旁边。
2. 按下面的字段表填写。设置 `meta.lang`，所有文字只用这一种语言。
3. 生成：`node scripts/build.mjs content.json -o deck.html`
4. 检查：`node scripts/check.mjs deck.html --all-presets`。通过改文字或换页面来修复所有问题，再跑一遍，必须退出码为 0。读完 For review 开头的行，转告用户。九页大约一分钟，浏览器在后台无界面运行。
5. 每一页都要亲眼看：`deck.html?bare=1&nodraft=1#N`，1600×900。读着别扭的就改。通过检查不等于做完；哪页平淡，就换人物、换顺序或改文字。
6. 如果交互有任何改动，或用户要求，就实际操作一遍：`npm install playwright`，`npx playwright install chromium`，再运行 `NODE_PATH=$(npm root) node scripts/drive.mjs deck.html`。大约四分钟。只有这一步需要 Playwright。
7. 导出：`node scripts/export.mjs deck.html --pptx deck.pptx --pdf deck.pdf`，大约 10 秒。
8. 验证导出并查看每张图：
   - `node scripts/verify-pptx.mjs deck.pptx --deck deck.html --expect N --render ppt-pages/`（校验文件结构和数量；Mac 上用 `qlmanage` 画出每一页）
   - `node scripts/pdf-pages.mjs deck.pdf pdf-pages/ --expect N`（Mac 上用 `sips` 画出每一页，文字层重复会报错）
   - 不要打开 Keynote 或 PowerPoint。其他系统用 `pdftoppm -png deck.pdf pdf-pages/p`。

## content.json 的顶层字段

| 字段 | 含义 |
|---|---|
| `meta` | 演示的基本信息：语言、标题、组织、周期、配色、虚构标注、推断的句子。 |
| `data` | 数字的唯一来源：来源、指标、表格、趋势、受众群体、标签。 |
| `figures` | `{ "photos": {} }`：用户自己的抠图。留空就用手绘人物。 |
| `pages` | 按顺序排列的页面，每页有一个 `pattern`。 |

### meta

| 字段 | 含义 | 上限 | 信息不足时 |
|---|---|---|---|
| `lang` | `en` 或 `zh-Hans` | 每版一种 | 跟随需求的语言。 |
| `title` | 浏览器标签和文件标题 | 80 | 用组织和周期组成。 |
| `org` | 每页底部的名称 | 30 | 绝不编造，写 `待确认`。 |
| `period` | 如 `2026 年第三季度` | 24 | 绝不编造，写 `待确认`。 |
| `preset` | `cobalt`、`ultramarine`、`signal`、`bottle`、`violet`、`night` | 一个 | `cobalt`。 |
| `fictional` | 只有演示用的虚构数据才写 `true` | 布尔值 | 真实数据写 `false`。 |
| `fictionalLabel` | 虚构时每页显示的文字 | 12 | `虚构示例`。 |
| `inferred` | 所有你推断而非用户告知的句子 | 列表 | 全部列出。检查脚本和编辑台都会显示，供人核对。 |
| `words` | 不能跨行拆开的名称，如品牌或产品名。常见平台名和表格每一行的名称已自动保护。 | 列表 | 需求里出现的名称都加上。 |

### data

每一页上的每个数字都必须来自这里。空缺写 `null`（CSV 留空），显示为「无数据」，绝不当作零，也绝不补数。

每个数字还要说清它是什么。`label` 是指标名称，`unitName` 是用文字写的单位（`次阅读`、`人`）；`unit` 为 `%` 或货币符号时不需要 `unitName`。两者都会印在页面上。需求没说时，一字不差写 `待确认`：页面印出「单位待确认」，检查脚本列出待核对。字段缺失则不通过。

| 字段 | 含义 | 规则 |
|---|---|---|
| `sources` | `{ "key": { "name": "..." } }`，印成「来源：...」 | 用用户的说法。没有来源就没有数字，要问。 |
| `metrics` | `[{ id, label, value, unit, unitName, prior, priorLabel, source, derived }]`。`prior` 可选。`unit` 是 `%` 或货币前缀（如 `¥`）。 | 只有 `prior` 是真实且非零的数字才显示变化。也可以用 `metricsCsv`：列名与字段相同的 CSV。 |
| `channels` | `[{ id, source, label, unitName, columns: [{ key, label, unit, unitName, derivedFrom }], rows: [{ name, 列 key: 数字或 null }], total, time }]`，或用 `csv`：相对于 content.json 的文件路径，带表头，第一列是名称，其余按 key 对应 `columns`。优先用 `csv`，数字只存一份。列保持数据里的顺序。列是时间段但名称不是月份时，写 `time: true` | 最多 10 行、4 列，名称 14 字。`total` 可选，写了就必须等于合计。 |
| `trends` | `[{ id, source, label, unit, unitName, entity, points: [{ label, value }] }]`，或用 `csv`（`entity`：它描述的渠道） | 最多 16 个点，不能有负值。缺失的月份保持 `null`。 |
| `audience` | `[{ id, source, label, unit, unitName, segments: [{ label, value }], total, derivedFrom }]`，或用 `csv`（`derivedFrom`：`表格id:列`，分组来自表格时写） | 最多 6 组，标签 12 字。 |
| `derived` | `[{ value, label, op, from }]`：所有你算出来的数。`op` 是 `sum`、`diff`、`share` 或 `change`。`from` 列出引用：`table:id:col`（整列合计）、`table:id:col:行名`、`trend:id`、`trend:id:标签`、`audience:id`、`audience:id:标签`、`metric:id`。 | 检查脚本逐个重算，算错不通过。页面标注为计算值。每项都列出待核对。 |
| `claims` | `[{ text, series }]`：用户的说法和数据不一致时写。 | 见「说法和数据矛盾」。 |
| `labels` | 带数字但不是度量的名称或日期，一字不差，如 `11 月前` | 每一项都会列出供核对。度量不能放这里。 |

句子里只能引用数据里给出的值，或写进 `data.derived` 的值。其他一律不通过，并指出页码和数字。图表自带的合计、占比和变化标签由系统计算并标明；要在句子里引用，先声明。整列由其他列算出时写 `derivedFrom: ["jul", "aug"]`，表头会标「计算」。指标由数据算出时写 `derived: { op, from }`。

### pages

每页都有 `pattern`、`name`（可选：总览和页面列表里的名称，当版式名称说得比用户多时使用，比如 `worked` 页写 `发生了什么`）、`title`（`["蓝色的词", "炭灰的词"]`，每个不超过 8 个汉字，第二个可省略）和 `notes`（演讲备注，用说话的句子，只复述用户的事实）。下表上限为中文字数。句子里引用数字的页面还要写 `source`：`data.sources` 里的一个或多个 key。

| `pattern` | 字段 | 信息不足时 |
|---|---|---|
| `cover` 封面 | `subtitle` 40，`pill` 14，`figures` 最多 2 个 | 副标题复述需求。 |
| `one` 一个数字 | `metric`（指标 id），`say` 70，`figure` | 必须有真实指标，否则去掉这页。 |
| `channels` 渠道表 | `table`，`barColumn`（哪一列画柱，位置不变），`barFirst`（用户要求才用：移到最前），`say` 56，`figure` | 必须有真实表格，否则去掉这页。 |
| `trend` 趋势 | `trend`，`highlight`（`last` 或 `peak`），`say` 60，`figure` | 只描述看得到的形状。至少两个真实数据点才能叫趋势。 |
| `worked` 做对了什么 | `items`：1 到 3 组 `{ pill 14, head 20, say 62 }`，`figure` | 只写用户说过的。宁少勿凑。 |
| `missed` 没做好什么 | `items`：1 到 3 组 `{ head 20, say 62 }`，`figure` | 绝不编造失败或原因。 |
| `audience` 受众 | `audience`，`say` 60，`figure` | 必须有真实的人群，否则去掉这页。 |
| `share` 占比 | 同 `audience` | 明确的替代页：不是受众、但确实是合计的组成部分，比如各渠道。在 `meta.inferred` 里说明。 |
| `team` 团队 | `people`：1 到 6 组 `{ name 8, role 14, figure }`，`pill` | 只用用户给的名字，否则去掉这页。 |
| `next` 下一步 | `steps`：1 到 4 组 `{ head 28, who 20 }`，`figure` | 只写用户的承诺。绝不编造负责人或目标。没有负责人或时间时，`who` 一字不差写 `待确认`。 |

`figure` 可省略，系统会自动选择，相邻页不重复。也可以指定，或写 `photo:id`：

| 人物 | 动作 | 适合 |
|---|---|---|
| `announcer` | 举喇叭喊话 | 封面、受众 |
| `pointer` | 长臂指向斜上方 | 一个数字 |
| `carrier` | 肩扛长板 | 渠道表（很宽，要留位置） |
| `leaper` | 跳起张开四肢 | 只用于做对了什么；又高又宽 |
| `tumbler` | 绊倒，纸张飞散 | 只用于没做好什么；很宽 |
| `shrugger` | 摊手 | 没做好什么，或如实的零；很宽，容易盖住旁边的字 |
| `spotter` | 举望远镜 | 受众、占比 |
| `reader` | 看一大张纸 | 封面、渠道表、占比 |
| `flagger` | 插旗 | 下一步的最高台阶 |
| `strider` | 夹着信封走路 | 做对了什么、下一步 |
| `waver` | 挥手，拿杯子 | 团队、一个数字 |
| `folded` | 抱臂，窄 | 趋势、团队、难看的数字；空间紧时最稳 |
| `writer` | 坐在箱子上写字 | 趋势、团队 |

## 遇到这些情况

- **信息不足：** 复述用户的事实，绝不编造，把每一句推断写进 `meta.inferred`。需要文字又不知道时，一律写 `待确认`（英文版写 `To be confirmed`）。它能通过检查，并被列出待核对。数字没有占位写法：缺数字就去掉那一页。
- **没人能回答：** 用现有事实能支撑的页面继续做，把假设写进 `meta.inferred`，并在回复里列出。
- **某个版式没有真实内容：** 去掉它。绝不拿别的东西充数。演示变短，或者用明确的替代页：合计的组成部分是真实的，就用 `share` 代替 `audience`；或者对另一个真实数字再用一次 `one`、`channels`、`trend`。每个替代都写进 `meta.inferred`。
- **要别的页数：** 一页通常用 `one`。五页：`cover, one, channels, worked, next`。九页是九种版式都有内容时的完整版，不是目标。更多页：用不同数据重复版式，重复时会自动镜像；相邻两页长得一样，检查不通过。每页只讲一件事。
- **要求的页数无法如实填满：** 直说，给出事实能支撑的页数，并说明还缺什么才能补齐。不要凑。
- **说法和数据矛盾：** 用户说「邮件没有增长」，数据是 1,800 到 1,900。不要默默照抄，也不要替他改。保留原话，旁边摆出数字，在 `data.claims` 加 `{ "text": "邮件没有增长", "series": "table:channels:邮件" }`，并在回复里提出来。检查脚本发现未声明的矛盾时不通过，已声明的列出待核对。它只读同时出现表格行名或趋势 `entity` 和增减词的分句，且只看按时间排列的列。其他说法要你自己核对。
- **留白：** 内容本来就少的页面（一项、一步、一个零）出现留白提示是正常的。不要为了消除提示而凑内容，看一眼是否像有意为之即可。
- **没有真实链接：** 这个演示没有链接，不要加。
- **数据很难看：** 一个巨大的值也按真实比例画，小柱子就是小，数字标在旁边。不要截断坐标轴、删行或用四舍五入掩盖。零就是零，空缺就是「无数据」。

## 人物和照片

没有照片时使用手绘人物。它们是一眼能看出的风格化图形，这个演示绝不生成写实人物。

只有用户主动提供时才用照片：

1. macOS 14 及以上：`node scripts/cutout.mjs photo.jpg person.png`。它通过 `scripts/cutout.swift` 调用苹果 Vision 框架，全程在本机运行。首次运行要编译几秒钟。
2. 如果识别到多个主体，它什么也不写。请用户确认图中每个人都同意出现，确认后才加 `--group-agreed` 重跑。
3. 其他系统上，脚本会说明原因并停止。哪里都能走的路：用用户信任的工具做透明底 PNG，再运行 `node scripts/cutout.mjs --check-png their.png`。
4. 加入演示：`"figures": { "photos": { "ada": { "file": "person.png", "people": 1, "alt": "主编方予安" } } }`，然后用 `"figure": "photo:ada"`。多人合影写 `"people": 3, "consent": true`，没有确认就拒绝生成。演示会把它转成单色并加上纸边。

## 交付物

- `deck.html`：单个文件，没有任何外部请求。手机上，幻灯片下方的阅读层用易读的字号显示本页文字，图表显示成真正的表格。方向键、空格、Home、End、滑动翻页；O 总览，N 备注，F 放映，E 编辑，P 打印。
- 编辑台（点「编辑」）：直接在页面或面板里改文字；换手绘人物或透明底 PNG；调整页面顺序；换配色；改备注。出现不在数据里的数字会提醒。浏览器里保留草稿，**保存**会写出新的 HTML 文件，重新打开修改都在。
- `deck.pptx`：文字、备注、色块和柱条可编辑。人物和装饰图形（圆盘、斜切色块）是图片。倾斜标签会摆正，因为导出器不能旋转可编辑文字，卡片也是正的。要明确告诉用户。换行取决于查看软件的字体，可能和 HTML 不同，词也可能在那里被拆开，因为 PowerPoint 和快速查看会自己换行。`qlmanage` 只是预览，不等于 PowerPoint。
- `deck.pdf`：每页一张矢量页面。

## 交付前检查

- [ ] `check.mjs --all-presets` 退出码为 0，所有 For review 的内容都已转告。
- [ ] 每个数字都能追到用户的数据，每张图和每个数字都标了来源。
- [ ] 推断的句子都写进了 `meta.inferred`，也列在回复里。
- [ ] 每个数字都说明了指标和单位，不知道的页面上写明了。
- [ ] 算出来的数都在 `data.derived`。和数据不一致的说法都在 `data.claims`，并已向用户提出。
- [ ] 没有真实内容的版式已去掉或换成明确的替代页。页数填不满时我说了。
- [ ] 我看过每一页的原尺寸，也看过 PPTX 和 PDF 的图。
- [ ] 我告诉了用户 PPTX 里哪些可编辑、哪些是图片。
- [ ] 任何多人合影都有用户确认这些人已同意。
- [ ] 每个版本只用一种语言。虚构示例每页都有标注。

## 不适合的情况

- 严肃的董事会或财务报告：这个风格很张扬。
- 既没有数字也没有故事：先问清楚，不要做一份全是占位内容的演示。
- 品牌有严格模板：这里的样式是固定的。
- 有负值（如损益）：从零开始的柱子表现不了。

## 环境要求

Node 18 及以上。`check.mjs` 和 `export.mjs` 需要本机任意 Chrome、Chromium 或 Edge（无界面运行；找不到时设置 `CHROME_PATH`）。`drive.mjs` 需要 Playwright：`npm install playwright`，必要时设置 `NODE_PATH`。`cutout.mjs` 需要 macOS 14 及以上和 Swift 命令行工具；查看导出结果在 Mac 上用 `qlmanage` 和 `sips`。只用系统字体，不内嵌：中文 PingFang SC，后备 Noto Sans CJK、微软雅黑；西文 Helvetica Neue Condensed Black，后备 Impact。