汇报幻灯片生成器 (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 改后重渲染
- 所有数字以素材为准，脚本不做四舍五入、不换算单位，避免口径漂移
输入契约
| 项 | 必需 | 说明 |
|---|---|---|
| 素材文件 | 必需 | Markdown，含封面信息 + 一页纸结论 + 核心数据 + 本周完成 + 进行中 + 风险与需要的支持 + 下周计划 等小节 |
| 汇报对象 | 可选 | --audience leader（默认）或 all；影响封面副标题措辞 |
| 时长 | 可选 | --minutes 5（默认）/ 10 / 15；决定页数上限 |
| 封面标题 | 可选 | --title 覆盖封面主标题；缺省取素材里的「标题：」 |
小节约定：
# 核心数据下的每条必须是「指标：数值（口径：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。
执行步骤
-
整理素材 — 让用户把本周完成 / 进行中 / 风险 / 下周计划 四类要点按
templates/report-outline.md落到 Markdown，数字统一进# 核心数据并标口径。 -
渲染 — 在技能目录下执行：
bash
python scripts/render_report.py report.md --audience leader --minutes 5
想指定封面标题加 --title "三月月度汇报"。脚本解析素材、套金字塔结构写出 report-deck.html，并打印「已生成 report-deck.html，共 N 页（上限 M）」。
-
打开检查 — 浏览器打开
report-deck.html，确认第 1 页是结论、数据页是带口径的表格、进度条与页码正常。 -
一页一判断自检 — 逐页看标题是否都是完整判断句；把写「XX 情况」「XX 汇报」的页改成判断句再重渲染。
输出格式
单个自包含 HTML 文件 report-deck.html，页面顺序固定为金字塔：
- 封面页（主标题 + 汇报对象 / 周期副标题）
- 一页纸结论页（≤ 3 条要点）
- 核心数据页（HTML 表格：指标 / 数值 / 口径 三列）
- 本周完成页
- 进行中页
- 风险与需要的支持页
- 下周计划页
- 结尾页（谢谢 · 欢迎提问）
翻页交互与 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输入是自由大纲，不强制结构，适合通用分享/宣讲。- 两者翻页交互一致（同一套键盘/进度条/目录实现），区别在内容组织方式与输入契约。
常见坑
- 投屏后中文变宋体或方块 — 现象：在自己电脑上正常、会议室电脑上整体掉成衬线宋体甚至方块。原因：报告 HTML 的字体依赖演示机，单一字体名缺失时浏览器回退到默认衬线体。规避：模板已内置回退栈
Microsoft YaHei → PingFang SC → Hiragino Sans GB → Heiti SC → WenQuanYi Micro Hei → sans-serif（Windows/macOS/Linux 各有命中，必须以 sans-serif 收尾）；缺字体的表现是样式变宋体而不是报错，正式汇报前在演示机上先开一次确认。 -
数字无口径被领导追问 — 现象：汇报时对方问「这 96% 是怎么算的」，答不上来。原因：素材只写了数字没标统计口径。规避：
# 核心数据每条必须带「口径：xxx」，脚本会逐条检查缺口径并警告。 -
标题写「XX 情况」没信息量 — 现象：一页大标题「交付情况」，听众不知结论。原因：把标签当标题。规避：标题写完整判断句，如「交付按时完成，3 个需求全部验收」；脚本对「情况 / 汇报 / 说明」结尾的页标题给警告。
-
风险页写「一切顺利」没价值 — 现象：风险页只写「暂无风险」，领导觉得没思考。原因：回避真实阻碍。规避：风险页写具体阻塞与需要的支持（如「测试环境不稳，需运维协助扩容」），没风险也要写明「已识别风险 0 项，依据 XX」。
-
页数超时 — 现象：5 分钟汇报做了 15 页，讲不完。原因：没按时长限页。规避：脚本按分钟数限上限（5→8、10→12、15→16），超限时控制台警告并提示可削减「本周完成 / 进行中」等详情页。
-
结论页塞太多条 — 现象：一页纸结论列了 8 条，等于没结论。原因：把详情全堆首页。规避：结论页只留 ≤ 3 条最关键判断，其余下沉到分项详情页；脚本超过 3 条会截前 3 并警告。
-
素材与数据页数字对不上 — 现象：结论写「增长 18%」，数据页写「增长 12%」。原因：两处各写各的。规避：结论里的数字必须能在
# 核心数据找到同口径来源，生成前人工核对一致。
验收用例
- 正常：含数字的周报素材（leader / 5 分钟）→ 第 1 页是结论、数据页有「指标 / 数值 / 口径」三列表格、总页数 ≤ 8。
- 边界 1：素材 12 页内容 + 5 分钟 → 控制台警告超 8 页上限，并建议削减详情页类。
- 边界 2：核心数据某条缺口径 → 控制台逐条警告「缺少口径标注」。
- 失败：空素材文件 → 脚本退出并报错，不生成空
report-deck.html。
目录说明
scripts/render_report.py— 主脚本，读素材渲染成report-deck.htmltemplates/report-outline.md— 素材整理模板（四类要点 + 口径标注示例）
