paper-ppt：AI 理解、AI 设计、AI 看图迭代

目标：产出一份准确、可讲、视觉专业、可编辑、可复核的学术汇报。

基本分工：

• AI：理解论文、选择证据、组织叙事、设计页面、看图审阅、决定如何修改；
• 代码：读取/绘制/渲染/记录/检查，不替代内容与视觉判断。

不要构建“文本 → 固定布局 → 自动填充”的模板流水线，也不要用程序规则给页面机械打分代替视觉模型。

0. 开工前访谈（必做，不得跳过）

一份汇报好不好，一半取决于开工前有没有问清楚。 在用户回答足够的问题之前，不要生成任何 PPT 页面。 问题库、追问规则与记录模板见 intake.md，本节是硬性规则。

0.1 三个确认关口

只有用户明确说“你看着办 / 不用问 / 直接做”时，才可以用默认值跳过 G1–G3，并把采用的默认值逐条写进 design-brief.md，交付时在 qa-summary.md 列出。跳过 G1 时仍要问详略（0.3）。

0.2 G1 必问清单

按下表逐项检查。用户已经说过、或能从材料可靠推断的不要再问；其余项必须问到，每一项都给出默认选项，让用户一个词就能答。

按场景追问（只问与当前场景相关的，见 intake.md §2）：

• 组会读论文：是否需要“对我们组的启发”页？要不要准备讨论问题？
• 会议 talk：有没有官方模板或页数限制？是否有动画分步需求？要准备哪些 Q&A 备份页？
• 答辩 / 开题 / 中期：学校标准色与校徽？评委关注点？要不要“攻读期间成果”页？多篇论文如何对应章节？
• 课程展示：评分标准？是否要互动或小测？
• 工作汇报：汇报对象是谁？要不要进度表和风险？

0.3 详略：一定要问

用户没说时长、页数或“详细/简略”时，必须问，并给出默认选项：

这篇要讲多细？简略版约 8–12 页、8–10 分钟，只讲主线和关键结果；详细版约 16–22 页、15–20 分钟，含方法分解和主要实验。不说的话我按详细版做。

已给时长或页数 → 直接推断，不再问；用户给的页数优先于档位页数。档位与页数以 source-sufficiency.md §1 为唯一标准，其他文件里的页数只是场景参考。

0.4 怎么问才不烦人

• 一次一条消息，最多 5–6 个问题，按上表优先级排序；每个问题后附默认值，例：“听众是？（默认：同领域不同方向）”。
• 用编号，让用户可以只回“1 组会 2 15 分钟 3 默认”。
• 第一轮没覆盖的必问项，在第二条消息补问；不要在一条消息里塞满 10 个问题。
• 用户回答含糊时追问一次具体化（“重点讲方法”→“方法里哪个模块最想讲细？”）。
• 读完论文后发现新的关键分歧（例如论文有两条贡献线、实验很多需要取舍），在 G2 一起问。
• 把所有回答原样记入 design-brief.md 的“访谈记录”，后续不要重复问已回答过的问题。

0.5 G2：主线与大纲确认

读完论文后，先给用户看大纲，再动手做页面。发给用户的内容：

1. 一句话主线（问题 → 洞察 → 方法 → 证据）；
2. 页序大纲表：页号 / 页面类型 / 标题（结论式）/ 证据来源 / 预计时长；
3. 取舍说明：哪些放进备份页、哪些不讲及原因；
4. 推荐风格与理由（如果 G1 没定）；
5. 需要用户决定的 1–3 个问题。

用户修改后更新 storyboard.md，再进入样页。

0.6 环境检查

同时确认当前环境是否具备：

• 文本/PDF 读取；
• 原始 PDF 页面或图片查看；
• PPT 创建/编辑；
• PPT 渲染；
• 真实图像输入能力；
• 所选风格的字体：运行 python scripts/check_fonts.py <preset>，缺字体时按 fonts.md 替换并记录。 每批渲染前都重跑一次：沙箱或容器重启后字体可能丢失，渲染器会静默回退到默认字体，用回退字体做出的视觉结论无效。

有独立视觉审阅 Agent 就使用；否则由具备图像输入能力的主 Agent 分阶段完成设计与自审，并明确标记 self-review。

没有视觉能力时，可以输出内容/结构草案，但不能声称视觉已经验收。

风格参考不要求提供 PPTX，也不是固定模板资产。 每套预设在 styles/<preset>/template.pptx 提供带占位说明的基础模板，可给用户参考或作为手工修改起点，但 AI 仍按论文重新设计。

1. Source：先理解论文，再选素材

1.1 获取素材：两条并列可选路径

两者可以并行：B 出正文，A 出截图与原图裁切。无论哪条路径，原 PDF 页面都是 Figure、Table 和公式的视觉真值。使用的路径写入 source-notes.md。

1.2 理解与选材

先通读论文，形成研究主线，再决定哪些内容值得进入汇报。

文本（宿主读取、pdf_snap.py text 或 MinerU Markdown）用于理解正文，每张准备进入 PPT 的图表都要实际查看页面截图或裁切图。

涉及数学公式时读取 math-equations.md：保留并核对 LaTeX 源码，用可靠渲染器生成公式；简单原生 OMML 需验证目标 PowerPoint，复杂公式使用 SVG 并保留同尺寸后备图。按实际宽高安排版面，空间不足先分行/拆页，不把源码当文本公式、不拉伸或自动压小。

视觉检查至少确认：

• Figure/Table 编号和 caption；
• 子图对应关系；
• 坐标轴、单位、图例和指标方向；
• 裁切是否完整；
• 页面缩小时文字是否还能读；
• 图能支持什么结论、不能支持什么结论。

产出 source-notes.md，记录：

• 论文版本与来源；
• 章节/页码；
• 关键图表；
• 重要数字与实验条件；
• 仍未确认的内容。

明确区分：

1. 作者原文结论；
2. 可核验计算；
3. 汇报者解释；
4. 延伸设想。

未确认数字不要进入正式页面。

1.3 内容充足性自检

进入 Design 前，由 AI 自主判断素材够不够支撑所选详略档位，按 source-sufficiency.md §2 逐项检查：图表清单覆盖、关键数字可溯源、摘要主张有证据、方法讲得通、文本层可信度。

• 不足但能自己补：回到页面截图、附录、补充材料、项目主页或代码仓库补齐；
• 补不齐：写进 source-notes.md 的“未确认”，相关页面不放该数字或改为定性表述；
• 只有用户知道的（汇报重点、听众背景、组里关心的问题）：问用户，最多一次；
• 路径 A 不够用（扫描件、公式/表格过多、视觉识别不可靠）：建议切换或叠加路径 B。

自检结论（够 / 不够、补了什么、还缺什么）写入 source-notes.md 末尾。

2. Design：先决定怎么讲，再决定怎么画

阅读：

• page-content-guide.md：每个场景的页序模板和每类页面的内容契约（从 105 套真实 deck 蒸馏），写 storyboard 前必读
• talk-structure.md
• style-guide.md
• Academic Clean 或 Academic Rich
• slide-style-gallery.md：从真实顶会/组会 deck 蒸馏的 11 条版式手法，以及海外 / 国内组会两种风格方言

下面是可选设计路线。优先遵循用户提供的参考和选定风格；颜色、字号、密度、标题句式与章节节奏只在对应风格内生效，不是公共工具的验收条件。

常见候选：

• 组会 / 精读 / 答辩 / 简洁正式 → Academic Clean
• 课程展示 / 公开分享 / 更强演示感 → Academic Rich
• 不确定 → Academic Clean

风格方言（与上面的视觉语言叠加使用，见 slide-style-gallery.md §2–§3）：

• 英文汇报 / 海外组会 / reading group → International：白底、标题即结论、增量构建、研究问题编号导航；
• 中文组会 / 国内学术报告 → Domestic：提纲页、“一、二、三”标题前缀、标题关键词强调、出处标签、结尾讨论问题；
• 语言用于确定字体与文字排版；中文和英文都可以使用其他预设，不以语言直接锁定风格。

场景更具体时，从另外 7 套预设中选（依据：105 套真实 deck 的蒸馏，见 slide-style-atlas.md §4 速查表）：

再从 6 套「风格包」预设中选（公开课件与 Typst 主题的单独蒸馏，逐套的色值证据见各目录 refs/）：

另有 Academic Evidence：本次论文汇报形成的可选风格说明与中英文案例，强调证据和就近解释。它不是覆盖其他十五套预设的通用规范，也不注册固定页面模板。

优先选与用户参考、场景和内容密度匹配的一套；不确定时采用可逆候选并在样页中验证。选定方言/预设或案例风格写入 design-brief.md。

三层怎么叠加（冲突时按这个顺序）：

1. 用户明确要求；
2. 预设（15 套，international / domestic 本身也是预设）：决定字体、配色、网格和页面原型，字体以预设 tokens.json 为准；
3. 方言：只叠加文案习惯，不改视觉。例如中文汇报选 systems-talk 时，仍可以用“一、二、三”标题前缀、提纲页、出处标签、结尾讨论问题；
4. Academic Clean / Rich：只决定密度和演示感，不覆盖预设的字体和配色。

每次只选一套预设，选定理由和叠加的方言规则写进 design-brief.md。

所有预设都可直接调用（styles/）：tokens.json 定义字体、字号、配色语义和网格，assets/style-presets.js、style-presets-extra.js 与 style-presets-stylekit.js（后者的原型在 styles/<preset>/prototypes.js）提供页面原型，assets/layout-kit.js 提供共用的构图原语（按宽高比放图并回传紧致矩形、引线标注、圈点与编号徽章、分栏、列头、竖直分隔线）。十五套预设都已补齐覆盖概述 / 方法 / 结果 / 对比 / 收尾五类页型的版式，每套的版式骨架各不相同，见 references/layout-atlas.md 的「预设 → 版式骨架」对照表；不要只用 head 加一张图就当作该预设的设计。没有合适原型的页型照预设 token 自由绘制，可参考 lab/annotated-v2/ 的构图。

先按内容选版式，再按风格取颜色：同一页型在十五套预设里对应不同的构图（例如「对比」页，international 是带高亮模块的流水线、systems-talk 是整宽数据表、dark-tech 是左右数值对照、defense-cn 是双案例图卡、jp-gothic 是变更前后双栏表）。换预设必须换构图，只换 tokens.json 的颜色和字体等于没换风格。

自由绘制时用画布接口，不要直接调 PptxGenJS：

• c.text(content, box)：content 是字符串或数组，数组的每一项是一个段落；文本里的 \n 也会拆成新段落。同一行里要用不同样式，写成 {runs: [{text: '结果：', bold: true, color}, {text: '…'}]}。标记 **粗**、[[强调]]、{{n:符号}} 不能嵌套，要粗体又要着色时用 runs。
• c.table(rows, box)：原生表格，按预设 token 自动选中英文字体、给表头上底色、数字列右对齐；用 highlight: [行号] 高亮本文行。
• c.equation(asset, box)：公式资产，框放不下会直接报错，不会自动缩小。
• 原生图表：slide.addChart(type, data, {...chartFonts(t), ...})，否则图表文字会写成 Arial，check_fonts --deck 会报 MISS。
• drawSlide(c, t, {type: 'head', ...})（international / domestic 叫 frame）：只画该预设的页头、页脚和出处行，正文自由绘制。

使用预设时：

• storyboard 中为每页标注原型名；没有合适原型的页面自由绘制，但仍遵守该预设的 token 与硬性约束（见对应 STYLE.md §5）；
• 先看 styles/<name>/refs/ 中的真实参考页和 samples/ 中的示例页，再动手；
• 预设是起点：渲染后按看图结论改坐标、换原型或拆页，不要为了套原型牺牲论文表达。

用户明确指定风格时优先遵循用户要求。

风格参考可以只有文字；如果用户提供截图、图片或网页 slide，视觉 AI 必须实际查看，只提炼：

• 层级；
• 网格；
• 留白；
• 密度；
• 配色；
• 图文关系；
• 页面节奏。

不要复制具体坐标、占位符、品牌标识或整页结构。

填写 design-brief.md，再生成 storyboard.md。每页至少明确：

• 本页要回答的问题；
• 听众应记住的结论；
• 证据来源；
• 不得改错的术语/数字；
• 视觉焦点与阅读顺序；
• 哪些内容不放这页；
• 演讲备注目标；
• 预计时长；
• 可读性风险。

storyboard 是创作说明，不是程序布局输入。每页的标题、主图、主数字和实验条件应指向同一项证据；记录图间关系（步骤 / 分支 / 对照），避免添加错误的流程箭头。

页序从 page-content-guide.md §1 中对应场景的模板起步，按论文与访谈结果增删，并对照 §2 的内容契约检查每页“必须有 / 不要”。写完后进入 G2 主线与大纲确认（§0.5），用户确认后再做样页。

3. Pilot：先验证方法页和实验页

不要先做完整 deck。

优先制作：

1. 一页方法/机制页；
2. 一页实验/结果页；
3. 篇幅足够时再加封面。

这两类页面最能暴露设计是否真的适合论文。

AI 自主构图，可以使用宿主演示工具，也可以编写当次 PptxGenJS 绘制代码。低层 helper 只减少重复劳动，不决定页面长什么样。

制作后立即：

生成 → 渲染 → 看图 → 指出具体问题 → 修改 → 再渲染

需要让用户在多种风格之间挑选时：

• 每种风格的同一页讲同一份内容、同一份证据，差异只来自风格；不要这套讲表 3、那套讲图 5。
• 每种风格要用自己的招牌构图（例如引文对决、终端日志、哑铃图、斜率图、Bento、瑞士网格、booktabs 表），而不是同一骨架换配色和字体。
• 出跨风格总览（每行一种风格，每列一种页型），逐列检查：同一页型若超过三分之一的风格共用一种骨架，判为不通过并重做这些页。
• 原始证据只有一张图（例如长条形原图）时，至少让图下的解释部分换构图，并在审阅记录里说明同构原因。

样页自审通过后，把渲染图发给用户做 G3 样页确认：问风格、文字密度、字体、配色是否满意，有无要改的地方。用户确认后再扩展到全稿。样页确认的是视觉语言，不是要求后续页面复制同一布局。是否比较多种构图取决于当前设计的不确定性和所选风格，不规定所有任务固定比较两版。

4. Slides：1–3 页一批生成与复审

每批 1–3 页。

要求：

• 标题、正文、来源和必要标注保持可编辑；
• 论文原图优先用 pdf_snap.py figure 自动取框（见下），只有它失败时才手量 crop 坐标；
• 自绘解释图：先用 HTML/CSS/SVG 渲染成 PNG（scripts/diagram.py），再放回页面； 只有在改一两个箭头、加一个色块这种一处两处的标注时，才用 pptx 原生形状；
• 论文原图可以作为图片；
• 生成式图片只能用于非证据性的概念/气氛素材；
• 禁止生成论文没有的实验结果、伪造系统截图，或凭像素估算补画数据；
• 重绘图表只用论文明确写出的数值（正文、表格、图上的数值标注）。没有标注的序列（例如只画了圆点、没写数）保留原图裁切，不要重绘成精确值。判定细则见 style-guide.md §8。

每页写正式口语演讲备注。复杂 Figure 先告诉听众“怎么看”，再解释机制或结果。

原图裁切：先 figure，再 crop

python ../paper-extract/scripts/pdf_snap.py figure paper.pdf \
  --page 5 --region 0.04,0.05,0.49,0.30 --out figs/fig2.png [--dpi 300] [--json figs/fig2.json]

figure 会在 --region 里取「矢量图形 ∪ 位图 ∪ 文字」的真实范围：用页面渲染的像素做最终判定 （旋转的刻度标签、贴在白底上的截图都不会漏），用 caption 的 y 作为下界（caption 永远在图下方）， 并打印 bbox / aspect / pixels。宽高比直接抄进 img() 的 AR 表，不要再目测。

什么时候退回 crop：图与正文混排在同一区域、figure 报 no drawings、或图本身没有 caption 兜底。 无论哪种，裁完都要打开 PNG 确认坐标轴标签、图例、子图编号完整。

自绘示意图：HTML/CSS/SVG → PNG

python scripts/diagram.py assets/diagram-example.html \
  --out figs/p07.png --width 1213 --height 250 --scale 2

给 AI 自己画的解释图（层级树、对拍结构、时间轴、泳道）不要用 pptx 原生线条拼： 线段端点要手写坐标，框一挪线就偏，最后就是"线头在框外飘着"。 HTML + inline SVG 把坐标算出来再截图，连线永远落在盒边上，中文字体也走系统字体栈。

• 页面尺寸 = 幻灯片上的实际尺寸（1 px = 0.01 in，1213×250 px ↔ 12.13×2.5 in）；
• --scale 2 出 2 倍图，投影不糊；--selector 可只截某个分栏；
• 默认会裁图：视口高度几乎总比画面高，留白贴进页面后会让图显得很小， 所以默认裁到内容边界 + --pad（默认 8 CSS px）。需要严格等于视口尺寸时加 --no-trim， JSON 报告里的 trim.dead_band_pct 告诉你裁掉了几成空白；
• 视觉语言对齐当前预设：颜色用 token、1.2px 细线、4px 圆角、不加阴影；
• 只有"改一两个箭头、加一个高亮框"这种一处两处的标注，才回到 pptx 原生形状。

每批都走：

制作
→ 渲染
→ 视觉模型实际看每一页
→ 对照论文证据与设计简报
→ 局部修改
→ 重新渲染
→ 复审

本地工具链的一轮：

set -euo pipefail                  # 任何一步失败就停，避免后面的检查和渲染在旧文件上照常 pass
R=r05                              # 每轮换一个编号；中间文件都带轮次，后处理脚本不覆盖已有文件
python scripts/check_fonts.py <preset> --track open      # MISS 先 get_fonts.py --install
PAPER_PPT_FONTS=open node build.js build/deck.$R.raw.pptx  # 生成脚本用 writeDeck() 保存到这个路径
IN=build/deck.$R.raw.pptx
# 有公式：
#   python scripts/math_assets.py finalize $IN --manifest build/math.json --out build/deck.$R.math.pptx; IN=build/deck.$R.math.pptx
python scripts/check_deck.py $IN || true                 # 只看是否提示 blank zero
# 提示 blank zero 且 0 是论文原值：
#   python scripts/restore_chart_zeros.py $IN --out build/deck.$R.zeros.pptx; IN=build/deck.$R.zeros.pptx
cp $IN deck.$R.pptx                                     # 本轮最终文件
python scripts/check_deck.py deck.$R.pptx               # 结构检查，必须 pass
python scripts/lint_style.py deck.$R.pptx --json build/lint.$R.json   # 文字溢出/红词/中文标点/图号
python scripts/check_fonts.py --deck deck.$R.pptx       # PPTX 实际写入的字体本机都有，否则渲染无效
python scripts/bridge.py render deck.$R.pptx --out renders/$R
#   渲染后端自动选择：LibreOffice → Windows 上的 PowerPoint COM；
#   PDF→PNG 自动选择 pdftoppm → PyMuPDF。三者都不报错就说明闭环可用。
# 用视觉模型逐页看 renders/$R/slide-*.png 和 contact-sheet.png，在 review-log.json 末尾追加记录
python scripts/check_review.py renders/$R/render.json review-log.json

lint_style.py 有两条例外要知道：等宽字体的代码框、[N] 开头的参考文献框都不算要点列表；目录页把当前章 标成强调色时，那几个文本框要命名成 nav:<名字>（PptxGenJS 的 objectName，PowerPoint 选择窗格里可见）， lint 才把它当状态色而不是「红色连续 ≤ 6 字」。没命名的目录就是正文，九字章名照样报错。

不需要的步骤跳过，但顺序不变。交付时把最后一轮的 deck.rNN.pptx 复制为 deck.pptx。审阅记录引用的参考图（例如风格样例图）要先复制到工作目录再引用，不要直接引用仓库里会被重新生成的文件。

check_review.py 要求五个阶段（source / design / pilot / slides / deck）都有通过记录，并且每条记录的 inputs 都带当前 sha256：

• source 阶段：提交实际看过的页面截图或裁切图；
• design 阶段：提交 design-brief.md 和参考图；
• pilot / slides 阶段：提交逐页 PNG；
• deck 阶段：提交最终 contact sheet。

审阅问题要具体到：页码 / 区域 / 严重程度 / 为什么影响理解 / 应如何修改。

同一页连续多轮小修仍没有改善时，优先改变表达方式，例如：

• 拆页；
• 放大局部；
• 删除次要信息；
• 改用流程/对比/逐步聚焦。

不要无限微调几像素。

5. Review：内容与视觉分开终审

内容终审

核对页面和演讲备注中的：

• 关键结论；
• 数字；
• baseline；
• 实验条件；
• 指标方向；
• 因果表述；
• 数量与图中项目是否一致、主数字是否来自当前实验；
• 结论的任务 / 模型 / 样本范围、会改变理解的限制是否就近呈现；
• 专有名词；
• 指标名称：照抄论文（pass@1、准确率、F1、EM……），不同任务的指标不要笼统合称为“精度”；
• 论文中的算例与“正确答案”：自己验算一遍；答案依赖某个约定（定义域、是否允许负数、取整方式）时就近注明；论文自己的判定写成“论文标为正确”，不替论文下无条件断言；
• 局限与推测。

页面克制不代表口播可以夸大。

视觉终审

查看：

1. 最终版本所有全尺寸页面；
2. contact sheet / 缩略图总览。

全尺寸页面用于看文字、图例、裁切和标注；总览用于看整套节奏、密度和一致性。两者不能互相替代。

任何影响页面像素的修改都会使旧视觉结论失效。全局字体、主题或页码改动后，应重新渲染受影响范围。

视觉审阅记录遵循 visual-review.md。

使用本地工具链时，在真实渲染前运行 python scripts/check_deck.py deck.pptx，修复图片比例、非预期越界和图表数据问题。无文字、无图片的装饰形状越界会报 warning：逐页确认是否为风格有意设计的出血，并记录判断；不能仅凭检查通过跳过这些警告。它只做结构检查，不替代上述四类视觉与事实判断。

6. 交付

建议交付：

• deck.pptx
• speaker-notes.md
• contact-sheet.png
• qa-summary.md

工作目录中保留：

• 原始论文；
• Markdown / 图片素材；
• source-notes.md
• design-brief.md
• storyboard.md
• 生成源；
• 每轮渲染结果；
• review-log.json

这样后续可以做增量修改，而不是从头重做。

qa-summary.md 应明确写出：

• 事实检查情况；
• 视觉审阅方式；
• 最终审阅版本；
• 使用的渲染器；
• 是否在目标 PowerPoint 环境实际打开；
• 仍未解决的问题。

没有验证过的项目就写“未验证”，不要用“全部通过”掩盖缺口。

7. 增量修改原则

用户说“不要重做”时：

• 锁定未涉及页面；
• 只修改指定范围；
• 重新渲染修改页及受影响邻页；
• 重新做对应视觉检查；
• 不把一次小改动扩展成整套重构。