paper-reading

论文阅读

将论文报告视为一份有可核查证据支撑的论证，而不是一篇更长的摘要。根据参考文档为论文类型定义的报告结构来撰写，并删去不增加机制、证据、比较、局限或启示的句子。

使用内置脚本或资源前，将 <skill-dir> 解析为包含此文件的目录。

在示例中，PYTHON_EXE 表示兼容的当前或隔离环境中实际使用的解释器，例如 python3、python、py -3 或虚拟环境的绝对路径。根据当前平台解析该解释器；不要按字面运行此占位符，也不要假设某个命令名一定存在。

1. 选择输出格式

遵循用户明确指定或明显暗示的格式。否则，询问一次用户想要 Markdown 还是 HTML，然后等待回复。简要说明：Markdown 轻量且易于编辑；HTML 增加了设计完善的阅读界面、单节大纲、静态数学公式，以及可点击放大的视觉内容。

每份报告都采用同一种深度，包括“快速看懂”之类的快速概览请求：阅读完整论证，保留所有关键技术细节，并简洁地撰写。此工作流中不要运行复现实验。

**关卡：**记录 format；如果格式确实不明确，不要擅自选择。

2. 确认来源

接受本地或远程 PDF、官方全文 HTML，或完整粘贴的文本。若有 PDF，优先使用，因为页码和图表锚点更稳定；但不要强制要求 PDF。

对于 PDF，保留源文件不变，并提取到新目录：

uv run --isolated --no-project --with pymupdf4llm==1.28.0 \
  python <skill-dir>/scripts/extract_paper.py PAPER.pdf EXTRACTED_DIR

如果无法使用 uv，则使用隔离的标准 venv。尽可能复用已兼容的环境。不得要求使用 Conda，也不得安装到基础、系统或全局环境中。

提取器会生成带页码锚点的文本、源文件哈希值，以及不可变的 assets/raw/ 清单。将选定的视觉内容复制到报告中；切勿为了“清理”而删除原始提取内容。

对于官方 HTML 或粘贴的文本，保留章节名称和稳定的 URL 作为锚点。若无法提供页级锚点，应明确说明。

**关卡：**全文及实质相关的附录均可阅读，来源记录已在内部保存，且每个保留的视觉内容都可追溯至其来源。

3. 为论文分类

阅读标题、摘要、引言、贡献说明和章节大纲。选择主要分支：

• **实证研究：**提出新方法或模型，并进行基线实验 → 阅读 empirical.md。
• **理论研究：**定理或证明是主要贡献 → 阅读 theoretical.md。
• **综述：**对某一领域进行分类或综合 → 阅读 survey.md。
• **系统研究：**系统设计、实现和基准测试 → 阅读 systems.md。

始终阅读 shared-sections.md。跨类型的论文仍只选择一个主要分支；只添加一个指定次要分支中必要的模块。向脚手架传递主要类型——hybrid 不是第五种兜底类型。不要默认将分类不明确的论文归为实证研究；应先检查其贡献和证据。

**关卡：**记录主要类型、任何次要模块，以及支持该分类的证据。

4. 阅读完整论述

阅读论文全文及附录，了解方法的适用条件、证据、假设、负面结果或局限。

明确：

• 问题、假设、最接近的对比方法，以及促成该方法的关键洞见；
• 每个关键模块、模块接口，以及实际的训练／推理循环；
• 关键公式、符号、目标函数、数据、预处理、监督方式、架构、优化方法和评估协议；
• 主要结果、基线、消融实验、失败案例，以及结果发生变化的条件；
• 作者的主张、证据所支持的结论，以及仍属推断的内容。

对于实证研究和系统工作，撰写模块级工程剖析。对每个关键模块，说明其用途、确切输入、确切输出、架构和关键参数、训练数据和监督方式、训练方法／目标函数／优化方法、推理时的作用、与相邻模块的接口，以及代码证据。在模块标题正下方、字段上方，放置一张完全基于论文内容的全宽 SVG，展示从左到右的“输入 → 核心变换 → 输出”流程。每个不同的输入和输出都必须有各自不重叠的节点。对符号输入和输出，使用显式的 LaTeX 符号，并以静态内联 MathML 呈现；已知时，还需标注形状／取值范围。并列项目使用无序列表，不要在一段文字中堆叠罗列。明确写出 not applicable、frozen 或 not reported，不要省略字段。

**关卡：**具备技术素养的读者无需猜测即可重建系统边界和数据流；不得仅为缩短报告而省略任何重要字段。

5. 只读检查权威代码

阅读 code-audit.md。检查论文／项目的官方页面，确认是否公开了代码。若存在权威代码，应固定一个修订版本并只读检查，即使用户没有要求复现，也要核实模块输入／输出、张量或数据形状、架构、默认值、损失函数、数据流水线、训练计划和推理路径。

在此工作流中，不要安装依赖、导入项目、启动演示、下载模型权重或数据集，也不要运行训练／评估。如果仅靠网页检查不足，可以进行浅层临时克隆；保持其原样，并删除它，或将其留在报告之外。

将每条实现相关陈述标注为论文所述、代码确认、论文／代码不一致或报告推断。如果找不到权威实现，请说明检查过的页面，并明确写出 public code not found；绝不可悄悄以非官方仓库替代。

**关卡：**每张模块卡都包含代码定位依据，或明确注明无代码／未报告结果；论文与代码的差异必须清晰可见。

6. 建立主张—证据链

阅读 evidence.md。维护 C（主张）、E（证据）和 L（局限）坐标。为每项重要结果和批评提供依据。没有指出具体假设、对比、失败案例或缺失测试的批评，尚不完整。

区分作者的主张、代码确认的内容、报告推断的内容，以及外部一手证据显示的内容。除非明确要求，否则更广泛的新颖性或先前工作检索应作为单独任务处理。

**关卡：**每项重要陈述都能定位到确切的论文、代码或一手来源依据，推断内容须明确标注。

7. 选择并呈现视觉内容

对于 HTML，请同时阅读 visuals.md 和 html-report.md。

除模块结构图外，SVG 没有数量限制。根据讲解效果，使用 prose、对齐列表、表格、原创图示、HTML/CSS 或 SVG。模块结构图是明确的例外：每个承载关键信息的模块都要在其字段上方放置一张简洁、全宽的水平接口 SVG，让读者在阅读细节前先了解局部数据流。切勿将其压缩成狭窄的侧边栏，也不要为了节省空间而合并不同的接口值。让这些图保持简单且具体，然后逐一渲染检查每张 SVG。HTML 中的每张图片和 SVG 都必须能在灯箱中打开。

对于实证论文，应将论文中承载关键信息的结果图放在其所支持的结论旁边。至少要包含承载核心实证主张的原始图表、定性分析面板或结果可视化，并在 HTML 中标记为 data-original-result。重制的表格、指标卡片和说明性 SVG 可以帮助阐明证据，但绝不能替代原始结果图。如果论文确实没有结果图，应将结果部分标记为 data-original-result-unavailable="paper-has-no-result-figure"，并保留原始结果表格。不要裁掉阅读结果所需的坐标轴、图例、基线、失败案例或限定说明。

将重要公式保留为 LaTeX 源码，并按照 HTML 参考文档的说明，使用 scripts/render_math.py 将其渲染为静态 MathML。在每个独立成行的公式下方立即放置自然语言说明：定义该公式中的每个字母、运算符、索引和不明显的符号，然后解释整个关系式的作用及其重要性。不要在说明前加上“直观解释”之类的固定标签。行内符号必须保持为不可拆分、不可滚动的整体；较长的因果链应移至独立成行的公式块。可执行代码、路径和标识符应保留代码样式。

对于 Markdown，使用相同的内容和证据模型，并将精选的原始图放在其所支持的论断旁边。

**关卡：**每个理解难点都采用最清晰可用的呈现方式；每个视觉内容都忠实且注明来源；如果存在原始论文视觉内容，核心实证结果就必须保留该内容；不得虚构装饰性的科学内容。

8. 编写并验证交付内容

使用用户的语言；保留技术术语、方程、命令和标识符，避免因翻译而降低精确性。

• Markdown：编写 summary.md，并在需要时添加本地 assets/。
• HTML：搭建框架，替换所有占位符，然后进行验证：

PYTHON_EXE <skill-dir>/scripts/scaffold_report.py REPORT_DIR \
  --title "..." --title-focus "..." --authors "..." \
  --paper-type empirical --thesis "..."
PYTHON_EXE <skill-dir>/scripts/validate_report.py REPORT_DIR/summary.html

将 HTML、CSS 和 JavaScript 保持为内联内容；将高分辨率论文素材放在 assets/ 中，并使用相对路径。

交付前：

1. 删除框架标记，以及所有不提供机制、证据、比较、局限或推论的句子。
2. 检查本地链接、坐标、图注、方程、代码锚点和素材路径。将可见的基本信息部分保持为简洁的纵向列表：标题、带链接的作者／联系人／实验室或研究组、出版信息、链接、论文类型和一句话摘要。将哈希值、页面约定、提取目录和素材数量保留为内部信息。
3. 对实证／系统报告，验证每个承载关键信息的模块是否包含全部九个解剖字段；其上方是否有一个全宽水平输入→变换→输出 SVG；是否为每个不同的输入／输出单独设置节点；对真正的枚举是否使用无序列表；以及符号输入／输出是否使用由 LaTeX 派生的内联 MathML；概述仍需说明模块之间的流程。
4. 对 HTML，在桌面和窄屏移动设备宽度下渲染；验证单一大纲导航、标题层级、MathML、符号完整的说明、原子化内联数学、所有视觉元素、滚轮／捏合缩放、键盘关闭、打印和减少动态效果行为。
5. 反复运行验证器，直至通过，然后说明来源边界和代码检查状态，不要夸大确定性。

**完成标准：**完整论证得到简洁呈现，技术模块可重建，证据可追溯；在有公开代码时，已对其进行只读检查；输出可在其目录中离线运行；局限性与核心主张一样易于检查。