| name | rhetoric-of-decks |
| description | 幻灯片设计与制作的方案。当需要做汇报、设计演示文稿、或将论文转成 slides 时使用。适用于"做个汇报""做 slides""做幻灯片""写个 deck""设计演示文稿""把论文做成 slides"。 |
Rhetoric of Decks
幻灯片设计与生成的实操指南。核心来源：Scott Cunningham 的 Rhetoric of Decks 哲学。
何时使用
- 用户要做幻灯片/slides/deck/汇报/演示
- 用户要把论文、笔记、研究内容转成幻灯片
- 用户要改进已有幻灯片的设计
- 用户要为学术研讨、教学、项目汇报准备演示材料
核心原则
三条铁律
- 美即功能：美不是装饰，是清晰的视觉化。每个元素必须证明自己存在的理由。最美的 slide 可能只是白底上的三个词。
- 认知负荷是敌人：观众的注意力是稀缺资源。每多一个无关元素，就多偷走一份理解力。每张 slide 只放一个想法——这不是建议，是铁律。
- Slide 服务于口述：slide 是视觉锚点，不是讲稿。如果你的 slides 不需要你讲解就能看懂，你做的是文档不是演示。
标题是论断，不是标签
读完所有标题的人应该能理解你的整个论点。
| ❌ 弱标题 | ✅ 强标题 |
|---|
| "结果" | "处理组平均增加 61 英里" |
| "文献综述" | "已有工作忽略了供给侧边际" |
| "方法" | "我们利用县级诊所关闭的变异进行识别" |
| "数据分析" | "用户留存在第 7 天出现断崖式下跌" |
MB/MC 均衡
最优 deck 使每张 slide 的「边际收益/边际成本」相等：
- 过载的 slide（MB/MC 太低）：文字溢出底部、多个竞争想法、图表线条太多 → 观众放弃
- 过空的 slide（MB/MC 太高）：一个词可以支撑一句话、浪费了加强论点的机会
审查方法：逐张问"再加一个元素，收益能覆盖认知成本吗？再删一个，损失大于清晰度提升吗？"
留白是自信
空白不是浪费。满屏内容暗示恐惧——怕漏掉什么。留白暗示你知道什么重要。
Bullet 通常是认输
列表往往意味着你没找到信息之间的结构。问自己：
- 是序列？→ 用流程图
- 是对比？→ 用双栏
- 是层次？→ 用大小/颜色区分
- 是因果？→ 用箭头
例外：真正平行的条目（公理列表、定理条件）适合用 bullet。
叙事结构
三幕结构
| 幕 | 作用 | 做什么 |
|---|
| 第一幕：问题 | 制造张力 | 建立现状 → 引入挑战/问题 → 让观众感受痛点 |
| 第二幕：探索 | 推进论证 | 你做了什么 → 发现了什么 → 构建逻辑链 |
| 第三幕：解答 | 释放张力 | 核心洞察 → 意义/影响 → 行动呼吁 |
金字塔原则
先说结论，再给证据。观众不是悬疑小说读者。
✅ 正确顺序：结论 → 支撑证据 → 为什么重要
❌ 错误顺序：背景 → 更多背景 → 分析 → 终于到了结论
教学例外：当教学目标是让学生理解推理过程（而非结论），可以逐步推导再揭示结果。
开场和结尾
开场（第一张内容 slide 最重要，60 秒内决定观众是否注意）：
- ✅ 一个惊人数字（大字居中）
- ✅ 一个悬念/困惑
- ✅ 一个大胆主张
- ❌ "今天我要讲..."
- ❌ 12 项的大纲
- ❌ 定义 slide
结尾（最后一张 slide 决定他们记住什么）：
- ✅ 一句明天还能记住的话
- ✅ 回到开场的困惑，现在已解答
- ❌ "Questions?"
- ❌ "Thank you!"
魔鬼辩护人 Slide
在 Q&A 之前主动展示最强反驳：
"有人会质疑：[最强反对意见]"
"这个质疑合理，因为 [为什么合理]"
"我们这样回应：[你的应对]"
效果：建立可信度（ethos）+ 预防性回答 + 展示严谨思考。
受众适配
开始制作前先确认受众类型，再选择对应风格：
学术研讨（Research Seminar）
- 极简，一个系数一张 slide
- 第 6 张 slide 前必须展示 identification strategy
- 不要展示完整回归表——高亮 1-2 个关键系数
- 在 Q&A 前主动承认局限性
- 图表：后排可读、处理日期标注、前后期区分、关键模式注释、置信区间阴影
教学（Teaching）
- 允许更多文字（学生要记笔记）
- 重复是学习手段，可以有回顾 slide
- 逐步揭示：用
\pause（Beamer）或 fragment（RevealJS）
- 定义和推导单独一张 slide
- 路标 slide（"我们在这里"）有价值
工作底稿（给合作者）
- 可以更详细
- 记录决策："我们选 A 而非 B，因为..."
- 保留不确定性标记
- 日期一切内容——假设未来的你已忘记上下文
外部汇报（非学术）
视觉规范
排版
- 正文 ≥ 24pt（绝对底线 18pt）
- 最多两种字体（标题 + 正文）
- 投影用无衬线体（衬线细节远距离消失）
- 不要两端对齐（左对齐更易读）
图表
- 每张图传达一个信息
- 标题说发现（"注册量在 2015 年后翻倍"），不说图表类型（"注册量随时间变化"）
- 直接在数据上标注，不用图例（减少眼球移动）
- 删除所有 chartjunk：3D 效果、过多网格线、装饰元素
数学内容
- 每个推导步骤单独一张 slide 或明确分块
- 用颜色/框/箭头指向关键项
- 相关公式对齐等号
- 标注符号含义（"其中 $\bar{x}$ 是样本均值"）
颜色
如需配色方案，参见 references/palettes.md。
工作流程
制作流程
- 定义一句话要点：观众必须记住的一件事是什么？
- 分析受众：他们是谁？知道什么？怀疑什么？
- 勾画三幕弧线：问题 → 探索 → 解答
- 先做丑版：把想法倒出来，不管排版
- 应用三条铁律：一张一想法、美即功能、服务口述
- 加入魔鬼辩护人：他们会在哪里反驳？提前回应
- 狠心删减：犹豫时删掉
- 出声练习：slide 支撑讲话，不是反过来
自检清单
格式选择
Beamer（LaTeX）
适合：数学密集、需要精确排版控制、传统学术场景。
详见 references/beamer-template.md。
RevealJS / Quarto
适合：HTML 交互、嵌入代码输出、在线分享。
详见 references/revealjs-template.md。
编译验证环节（硬性要求）
每次编辑 .tex 或 .qmd 后，必须执行以下验证。不通过则不算完成。
Step 1: 编译
xelatex -interaction=nonstopmode deck.tex
bash ol.sh compile "项目名" --compiler xelatex
Step 2: 检查致命错误
grep "^!" deck.log
有任何输出 → 修复后重新编译。
Step 3: 零警告（硬性要求）
grep -cE "Overfull|Underfull" deck.log
必须返回 0。对每个警告：
| 警告 | 修复方法 |
|---|
| Overfull hbox | 缩短文字、用 \adjustbox、表格加 @{} |
| Underfull hbox | 调整段落换行 |
| Overfull vbox | 拆分 slide、减少 \vspace、压缩内容 |
| Underfull vbox | 加 \vfill 或调整间距 |
即使只溢出 0.5pt 也必须修复。
Step 4: 检查字体警告
grep -i "font" deck.log | grep -i "warning"
Step 5: TikZ 视觉验证
TikZ 错误不会触发编译警告，必须手动检查。详见 references/tikz-rules.md。
按顺序执行四轮 Pass：
- Pass 0: 跨 slide 一致性——相同元素颜色/位置/字号是否一致
- Pass 1: Bézier 曲线碰撞——计算弯曲深度，检查 label 是否在安全距离外
- Pass 2: 节点间隙计算——label 宽度是否小于节点间可用空间
- Pass 3: 箭头 label 定位——每个边 label 是否有
above/below/left/right
无 TikZ 内容时跳过。
Step 6: Figure-Checker 视觉自审（默认关闭）
此步骤默认跳过，仅在用户明确要求时启用（如「帮我看看视觉效果」「用视觉检查」「开启视觉审查」）。
启用后，先将 PDF 转为图片，再为每一页 slide 调用 pi-subagent 的 figure-qa agent。
pdftoppm -jpeg -jpegopt quality=85 -r 150 deck.pdf /tmp/deck-review/slide
为什么是 150 DPI JPEG：figure-qa 会在内部压缩图片，150 DPI JPEG 已足够清晰且体积较小。
调用方式详见 pi-subagent/agents/figure-qa.md，每页使用以下参数：
Scene: slides
Intent: <slide title or content description>
Extra: This is slide N of a presentation deck. Topic: <deck topic>.
Check for: text overflow, readability at distance, layout balance, color contrast.
figure-qa 会自动检查以下问题：
| 检查项 | 具体内容 |
|---|
| 文字溢出 | 文字是否被截断、超出 slide 边界 |
| TikZ 碰撞 | 节点/箭头/label 是否重叠 |
| 布局均衡 | 内容是否居中、留白是否合理 |
| 字号一致性 | 同级元素字号是否统一 |
| 颜色一致性 | 跨 slide 相同角色颜色是否一致 |
| 可读性 | 后排观众能否读清 |
| MB/MC 均衡 | 是否有 slide 明显过载或过空 |
汇总所有 slide 的检查结果：只要任意一页返回 ❌ REGENERATE，就必须回到 .tex 源文件修复问题，并从 Step 1 重新开始完整验证。只有全部 slide 通过后，才可继续交付用户。
Step 7: 交付用户检查
验证循环
编译 → 查错 → 查警告 → 查字体 → 查 TikZ → [可选] Agent 看图自审 → 交付用户
↑ |
└───────── 有问题则修复后重新开始 ←──────────────────────────────┘
全部通过后才可交付。
常见失败模式
| 失败 | 修复 |
|---|
| 文字墙 | 提取关键短语，其余是讲稿 |
| 重点埋到第 15 张 | 第 2 张就说结论 |
| 图表垃圾（3D 柱状图等） | 删到不能再删为止 |
| 大纲 8-12 项 | 最多三节，或直接删掉大纲 |
| "Questions?" 结尾 | 用一句话要点结尾 |
| 无证据断言 | 每个主张配来源 |
| 装饰性图片 | 删掉，留白更好 |
| 焦虑性塞满 | 精简的 slide 迫使你掌握内容 |
