scholar-slides

scholar-slides

将研究论文（或主题）转化为一套忠于原文优先的学术幻灯片。学术场景下，优先级与普通幻灯片工具相反：忠于来源 > 精美呈现，证据 > 说服力，可编辑性 > 炫目效果。公式、表格、数字、图表和引文都必须保持为真实文本／矢量内容，并可追溯至来源——绝不由图像模型栅格化，也绝不凭空编造。

设计理念及其依据的调研见 docs/；构建计划见 IMPLEMENTATION_PLAN.md。

锁定的技术栈（见 docs/03-design-proposal.md §0）

• 渲染后端： reveal.js + KaTeX → 矢量 PDF（Playwright）+ 可编辑 PPTX（已进行一致性测试）。稍后支持 Beamer。
• 默认幻灯片类型： 实验室组会／期刊俱乐部（组会）——阅读优先，信息密度高。
• 引文： 优先使用 Zotero（mcp__zotero__*），并以 Crossref/arXiv/DOI 作为备选。
• 语言： 双语，默认英语。

不可妥协的完整性关卡（始终开启——见 references/integrity.md）

在每个阶段应用；在 Checkpoint 3 强制执行：

• 绝不编造数字、引文或图表。一切内容都必须可追溯至来源摘要。
• 数学公式／表格／引文必须保持为矢量或文本——绝不能变成图像模型生成的像素。
• 复用真实图表（按边界框裁剪，并标注 Figure N [cite]）；只有标注为“redrawn, not from source”的概念示意图才可以重绘。
• **标记，不臆造：**尚未解决的图表／数字／引文问题必须显示 [MISSING: …]／[UNVERIFIED: …] 占位符，供用户查看——绝不静默补全。
• **必须注明来源：**每个复用素材都必须标明来源；每项论断都必须可追溯。

流程（7 个阶段，3 个人工检查点）

INPUT → 1.INGEST/DIGEST → [CKPT-1] → 2.DECK-TYPE → 3.OUTLINE → [CKPT-2]
      → 4.PER-SLIDE SPEC → 5.RENDER → 6.SELF-REVIEW(QA) → [CKPT-3] → 7.EXPORT

1. 摄取 → 类型化摘要 — references/ingestion.md。运行 scripts/prepare_source.py <pdf|arXiv id|arXiv URL>，构建摘要输入包 （文本、带 bbox 的图表清单、裁剪后的图），然后据此综合出类型化的 论文摘要（以该输入包为依据，绝不臆造）。 → [CKPT-1] 与用户确认摘要（贡献、核心结果、图表→幻灯片映射，以及任何标记为 FLAGGED 的素材）。
2. 演示文稿类型与参数 — references/deck-types.md。选择演示文稿类型（默认 组会）、 受众、时间预算 → 幻灯片预算、密度级别、所需的版式原型。
3. 叙事大纲 — references/narrative.md。按演讲顺序重新编排论文内容； 为每张幻灯片拟定行动标题；检查叙事张力。 → [CKPT-2] 审批故事线。
4. 逐页规格 — references/slide-spec.md。每张幻灯片各有一份独立、保存在磁盘上的规格 （布局、内容、公式、图表、引用、演讲者备注）。
5. 渲染 — references/math.md、references/figures-tables.md、references/citations.md、 references/charts.md、references/design-system.md、references/export.md。reveal.js + KaTeX； 真实表格；根据 bbox 裁剪的真实图表（去除版面元素；多面板图每张幻灯片展示一个面板）； 基于数据重新绘制图表；Zotero/BibTeX 引用。通过 meta.theme 选择视觉主题 （默认 journal-club / conference）。
6. 自检 QA — references/qa-self-review.md + references/integrity.md，然后执行 references/aesthetics-review.md 中的美学迭代。进行完整性扫描、静态验证、渲染截图及叙事/时长检查；渲染阶段还会确定性地测量几何布局 （画布空白区域、投影后字号低于 12px 可读性下限的图中文字）。然后根据 6 维评分标准对渲染后的像素评分（采用对抗性角色设定），将评分写入 <deck>/aesthetics_report.json（架构见 aesthetics-review.md），并返工任何单项得分 ≤ 2 或总分 < 18 的幻灯片，直到报告的 rework 列表为空 — QA 门禁会标记缺失的报告（P3）和未清空的返工列表（P2）。此外，还会提示项目符号占比和布局单调的问题。 → [CKPT-3] 事实确认签核：审查每一项 [MISSING] / [UNVERIFIED] 和生成的素材。
7. 导出 — references/export.md。导出矢量 PDF（投影版）+ 演讲者备注 + 可编辑的 PPTX； 使用 scripts/verify_pptx_parity.py 验证 PPTX 是否以原生方式保留规格（保障最少手动编辑的承诺）。使用 node scripts/run_benchmark.mjs 对整个语料库执行回归测试。

只阅读当前阶段对应的参考文件（渐进式披露 — 绝不对 references/ 使用 glob）。 每个阶段都读取上一阶段已确认的产物 — 摘要（阶段 1，由用户在 CKPT-1 确认），然后是 deck.json — 而不是重新从论文推导。

脚本（scripts/）

摄取 — 流水线第 1 阶段（Python，通过 ./.venv/bin/python；依赖项在 requirements.txt 中）：

• prepare_source.py — 第 1 阶段入口：PDF/arXiv → 摘要输入包。
• ingest_pdf.py — 使用 PyMuPDF 提取文本和版式；检测 arXiv ID。
• detect_figures.py — 图表/表格标题清单 + 边界框定位。
• crop_figure.py — 裁剪干净的单图边界框（不包含相邻栏）。

演示文稿构建与渲染 — 流水线第 5 阶段（Node，通过 node；依赖项在 package.json 中，执行 npm install + npx playwright install chromium）：

• build_deck.mjs — 渲染入口：deck.json → 独立的 reveal.js 演示文稿。
• render_deck.mjs — 演示文稿 → 每张幻灯片一页的矢量 PDF（以及用于 QA 的逐页 PNG）。
• lib/ — layouts（已注册版式锁定）、math（KaTeX）、table、figure、escape、qa。

引用与 QA — 流水线第 5–6 阶段（引用 = Python；QA = Node）：

• fetch_bib.py — 引用解析器（arXiv/DOI/Crossref），按顺序验证标题。
• qa_report.mjs — CKPT-3 门禁：完整性扫描 + validate_deck.mjs + verify_slides.mjs + 计时。

演讲者备注（Node）：

• speaker_notes.mjs — deck.json → notes.md 讲义 + 双语演讲时长估算。
• lib/notes.mjs — 计时 + 讲义纯逻辑；设计系统位于 assets/templates/themes/。

导出与图表 — 流水线第 7 阶段（导出 = Node；图表 = Python）：

• export_pptx.mjs — deck.json → 可编辑的 PPTX（原生文本/表格/备注；图和公式以图像形式呈现）。
• make_chart.py — 图表规格 → 数据绑定的 Okabe–Ito 图表（按原值绘制）。

测试：./.venv/bin/python -m pytest（Python）以及 node --test tests/*.test.mjs（Node — 逐个点名会静默漏跑新测试文件，请使用 glob）。

经验总结：更改流水线行为前请先阅读

learnings/ 存放事后复盘记录，其中包含实测数据（图尺寸的纵向预算、工艺规则与外观）。更改渲染、尺寸或 QA 行为前，请先查阅；每当遇到值得返工的意外情况后，请追加一则带日期的记录。

构建状态

整个流水线已实现，并已在真实论文上验证。尚未构建：Beamer 导出、扫描 PDF 的 OCR、草稿演示文稿摄取；会议/答辩演示文稿类型仅在 references/deck-types.md 中提供创作指南（没有专用代码）。只有通过 CKPT-3 人工事实核验签字后，演示文稿才算“完成”——门禁可以发现缺陷，但无法认证内容真实。