汇报幻灯片生成器 (ym-report-slide-gen)

把零散的周报 / 月报素材排成「结论先行」的汇报幻灯片 HTML：第一页一页纸结论，随后是带口径标注的数据表格、分项详情、风险与需要的支持、下期计划。不做图表，以表格为主；页数按时长自动限制，防止超时。

何时使用

• 用户说「汇报 PPT」「周报幻灯片」「月度总结演示」「述职幻灯片」时
• 用户攒了一堆周报要点和数字，不知道怎么组织成「领导一眼看懂」的页面时
• 用户明确汇报对象（直属领导 / 全员大会）和时长（5 / 10 / 15 分钟）时

运行前提

• 环境：Python 3.7+，仅用标准库（argparse / html / os / sys），无需联网、无需 pip 安装
• 输入文件：一份按 templates/report-outline.md 整理的素材 Markdown
• 输出文件：当前目录下生成 report-deck.html，同名会覆盖
• 不联网、不读取素材以外的本地文件、不上传任何数据
• 输出是放映用 HTML，不是可编辑的 PPT 源文件；如需二次编辑请回到素材 Markdown 改后重渲染
• 所有数字以素材为准，脚本不做四舍五入、不换算单位，避免口径漂移

输入契约

小节约定：

• # 核心数据 下的每条必须是「指标：数值（口径：xxx）」格式，口径说明数字怎么来的
• # 一页纸结论 下的要点控制在 3 条以内，每条是一个完整判断
• 其它小节标题应是完整判断句（如「交付按时完成」），不要写「交付情况」这类标签

缺失处理：

• 缺素材文件 → 用 templates/report-outline.md 模板请用户按四类填，不要替用户编造数字
• # 核心数据 为空 → 控制台警告「核心数据为空，汇报缺少支撑」，仍生成但不含数据页
• 某条数据缺口径 → 控制台逐条警告「数据 X 缺少口径标注，汇报易被追问」
• 时长非 5/10/15 → 按最接近档位取上限（5 分钟档 8 页、10 分钟档 12 页、15 分钟档 16 页）

素材示例（节选）

下面是一份可直接渲染的素材（保存为 report.md，UTF-8）：

# 封面
标题：三月月度汇报
汇报对象：直属领导
周期：2026-03

# 一页纸结论
- 交付按时完成，3 个需求全部验收
- 遗留 2 个低风险缺陷，不影响上线
- 下月聚焦性能专项

# 核心数据
- 需求完成数：12 | 口径：已开发并自测通过
- 用例通过率：96% | 口径：自动化用例执行结果

# 本周完成
- 完成 A 模块开发与联调

# 风险与需要的支持
- 测试环境不稳定，需运维协助扩容

渲染：

python scripts/render_report.py report.md --audience leader --minutes 5

生成后第 1 页是结论、第 3 页是带口径的表格，总页数不超过 8。

执行步骤

1. 整理素材 — 让用户把本周完成 / 进行中 / 风险 / 下周计划 四类要点按 templates/report-outline.md 落到 Markdown，数字统一进 # 核心数据 并标口径。

2. 渲染 — 在技能目录下执行：

   python scripts/render_report.py report.md --audience leader --minutes 5
   

   想指定封面标题加 --title "三月月度汇报"。脚本解析素材、套金字塔结构写出 report-deck.html，并打印「已生成 report-deck.html，共 N 页（上限 M）」。

3. 打开检查 — 浏览器打开 report-deck.html，确认第 1 页是结论、数据页是带口径的表格、进度条与页码正常。

4. 一页一判断自检 — 逐页看标题是否都是完整判断句；把写「XX 情况」「XX 汇报」的页改成判断句再重渲染。

输出格式

单个自包含 HTML 文件 report-deck.html，页面顺序固定为金字塔：

1. 封面页（主标题 + 汇报对象 / 周期副标题）
2. 一页纸结论页（≤ 3 条要点）
3. 核心数据页（HTML 表格：指标 / 数值 / 口径 三列）
4. 本周完成页
5. 进行中页
6. 风险与需要的支持页
7. 下周计划页
8. 结尾页（谢谢 · 欢迎提问）

翻页交互与 ym-html-deck-builder 一致：←/→、空格、PgUp/PgDn、Home/End、Esc 目录、F 全屏。底部进度条 + 页码。

页面自检清单

生成后逐项核对，任一项不满足就改素材重渲染：

• 第 1 页是「一页纸结论」，且要点 ≤ 3 条、每条是完整判断句
• 第 3 页「核心数据」是表格，三列齐全（指标 / 数值 / 口径），无缺口径行
• 结论里的每个数字都能在「核心数据」找到同口径来源，两处不矛盾
• 每页标题都是判断句，没有「XX 情况」「XX 汇报」这类标签
• 风险页写的是具体阻塞与需要的支持，不是「一切顺利」
• 总页数不超过当前时长的上限（5→8 / 10→12 / 15→16）
• 浏览器打开后 ←/→ 翻页有效、进度条随页推进、页码显示正确

能力边界

• 不做图表渲染（折线 / 柱状图等），数据以 HTML 表格呈现为主
• 不改写、不推算事实数字；素材里没有的数字不会凭空补，避免汇报失真
• 不做动画与转场特效，切页为瞬时显隐
• 不导出 .pptx / PDF，不做多人协作编辑
• 页数超限只在控制台警告并建议删减页类，不自动删内容（防止误删结论）
• 不管理汇报日程、不发送消息，仅产出本地 HTML 文件

与 ym-html-deck-builder 的区别

• 本技能强制「结论先行 + 数据表格 + 页数限时」，输入是结构化四类素材，适合向领导汇报。
• ym-html-deck-builder 输入是自由大纲，不强制结构，适合通用分享/宣讲。
• 两者翻页交互一致（同一套键盘/进度条/目录实现），区别在内容组织方式与输入契约。

常见坑

0. 投屏后中文变宋体或方块 — 现象：在自己电脑上正常、会议室电脑上整体掉成衬线宋体甚至方块。原因：报告 HTML 的字体依赖演示机，单一字体名缺失时浏览器回退到默认衬线体。规避：模板已内置回退栈 Microsoft YaHei → PingFang SC → Hiragino Sans GB → Heiti SC → WenQuanYi Micro Hei → sans-serif（Windows/macOS/Linux 各有命中，必须以 sans-serif 收尾）；缺字体的表现是样式变宋体而不是报错，正式汇报前在演示机上先开一次确认。

1. 数字无口径被领导追问 — 现象：汇报时对方问「这 96% 是怎么算的」，答不上来。原因：素材只写了数字没标统计口径。规避：# 核心数据 每条必须带「口径：xxx」，脚本会逐条检查缺口径并警告。

2. 标题写「XX 情况」没信息量 — 现象：一页大标题「交付情况」，听众不知结论。原因：把标签当标题。规避：标题写完整判断句，如「交付按时完成，3 个需求全部验收」；脚本对「情况 / 汇报 / 说明」结尾的页标题给警告。

3. 风险页写「一切顺利」没价值 — 现象：风险页只写「暂无风险」，领导觉得没思考。原因：回避真实阻碍。规避：风险页写具体阻塞与需要的支持（如「测试环境不稳，需运维协助扩容」），没风险也要写明「已识别风险 0 项，依据 XX」。

4. 页数超时 — 现象：5 分钟汇报做了 15 页，讲不完。原因：没按时长限页。规避：脚本按分钟数限上限（5→8、10→12、15→16），超限时控制台警告并提示可削减「本周完成 / 进行中」等详情页。

5. 结论页塞太多条 — 现象：一页纸结论列了 8 条，等于没结论。原因：把详情全堆首页。规避：结论页只留 ≤ 3 条最关键判断，其余下沉到分项详情页；脚本超过 3 条会截前 3 并警告。

6. 素材与数据页数字对不上 — 现象：结论写「增长 18%」，数据页写「增长 12%」。原因：两处各写各的。规避：结论里的数字必须能在 # 核心数据 找到同口径来源，生成前人工核对一致。

验收用例

• 正常：含数字的周报素材（leader / 5 分钟）→ 第 1 页是结论、数据页有「指标 / 数值 / 口径」三列表格、总页数 ≤ 8。
• 边界 1：素材 12 页内容 + 5 分钟 → 控制台警告超 8 页上限，并建议削减详情页类。
• 边界 2：核心数据某条缺口径 → 控制台逐条警告「缺少口径标注」。
• 失败：空素材文件 → 脚本退出并报错，不生成空 report-deck.html。

目录说明

• scripts/render_report.py — 主脚本，读素材渲染成 report-deck.html
• templates/report-outline.md — 素材整理模板（四类要点 + 口径标注示例）