| name | paper-close-read |
| description | 单篇论文精读与成品笔记生成，覆盖本地 PDF 或提取文本的材料准备、图片整理、方法解读、实验与实证分析、局限与价值评估，并产出类似完整论文分析笔记的图文结果。Use when Codex needs to read one paper deeply, especially a local PDF, and produce a figure-rich, method- and evidence-focused note rather than a broad literature survey. |
Paper Close Read
Overview
围绕单篇论文做完整精读，重点不是扩展检索大量相关文献，而是把这篇论文本身读透、拆透、写成可复用的图文笔记。
处理本地单篇论文时，必须同时完成三件事：
- 准备材料：PDF、提取文本、图片或页面截图、图片索引。
- 建证据链：研究问题、方法结构、公式、关键图表、关键数字、作者 claim 与其支撑证据。
- 生成成品：按照完整笔记结构输出，而不是只给短摘要。
默认目标不是“写一篇长摘要”，而是交付一份让读者能复述以下内容的笔记：
- 这篇论文到底在回答什么问题
- 作者如何设计方法或分析框架
- 关键公式、变量、样本、图表、表格在证明什么
- 论文最重要的结论来自哪几条证据
- 这些证据的边界和弱点是什么
Default Deliverables
默认应在论文输出目录里尽量具备这些材料：
source.pdfpaper.txtimages/ 与 images/index.mdanalysis.md- 对复杂、定量或图表密集论文，补一个
evidence_map.md 或等价草稿，用于记录 claim、图表、表格和关键数字
如果没有显式生成 evidence_map.md，也必须先按证据地图方式完成中间分析，再开始写正文。
Workflow
1. 准备本地论文材料
- 如果用户给的是本地 PDF，优先准备一个独立输出目录。
- 先运行
scripts/prepare_local_pdf.py，让它尽可能完成：
- 复制 PDF
- 提取
paper.txt
- 提取或整理
images/
- 生成
images/index.md
- 如果当前环境缺少 PDF 提取工具，继续寻找已有的提取文本、截图、图片目录或用户提供的辅助材料，不要直接退化成只写摘要。
具体要求见 references/local-paper-workflow.md。
2. 先建论文证据地图，再开始写
在写正文前，先确认这些材料是否已经定位：
- 摘要、引言、方法、实验、结论
- 关键公式和符号
- 至少一张方法相关图
- 至少一张结果相关图或表
- 作者用来支撑核心 claim 的主要实验
- 关键数字、表号、图号、断点、样本量、指标、显著性或效应量
先读 references/evidence-map.md，按其中模板抽出 claim 与证据的映射关系，再开始起草正文。
如果论文有图但没有被纳入输出，必须说明为什么不用；默认不能产出“无图精读”。
3. 先分论文类型，再决定正文骨架
不要机械把所有论文都写成“实验论文”。
- 如果是方法论文、模型论文、实验论文，正文主体可以是“方法 + 实验结果”。
- 如果是实证论文、计量论文、历史分析论文、理论综述论文，正文主体应改写成“分析设计 / 证据结果 / 结果机制”，而不是硬套“实验结果”。
- 如果论文没有真正的实验，不要把描述性统计、历史分段或案例比较强行称作实验，但仍要像实验分析一样回答“作者想证明什么、用了什么证据、证据强到什么程度”。
4. 按证据链解读方法或分析框架
方法部分至少要讲清：
- 论文要解决什么问题
- 现有方法具体卡在哪
- 作者提出了哪些模块、目标函数、约束或推断步骤
- 每个模块的输入、输出、作用分别是什么
- 关键公式的符号、计算对象、优化目标和直觉含义
- 方法为什么理论上可能有效
如果论文不是方法论文，也要把“分析框架”讲清楚：
- 数据来自哪里
- 样本如何构造
- 变量或统计对象如何定义
- 作者如何分段、分类、匹配、比较或回归
- 为什么这些分析步骤足以支撑核心 claim
不要只把方法改写成摘要。必须把方法讲成“问题 -> 设计 -> 机制”的链条。
5. 按证据链解读实验、实证或结果分析
结果部分至少要讲清：
- 每组实验、分析、统计比较或案例在验证什么假设
- 数据集、基线、指标为什么 relevant
- 主结果里最该比较的对象和数字是什么
- 消融、可视化、案例分析分别支持了哪条 claim
- 论文是否真的排除了其他解释
- 结果提升来自哪里，证据是否足够
- 每条关键结论到底落在哪个图、表、公式、页码或数字上
定量论文默认不能只说趋势，必须尽量落到数字和口径：
- 样本量
- 时间范围
- 关键参数估计值
- 效应量 / 增长率 / 提升值 / 置信区间 / 显著性
- 图号、表号或页码来源
如果表格无法直接提取成图片，也要把关键数字手工写入正文或证据地图，而不是只写“Table 2 表明”。
实验分析写法与提问清单见 references/experiment-analysis.md。
6. 产出完整图文笔记
- 最终输出默认应接近完整论文笔记，而不是简化版答题卡。
- 优先用论文中的原始图片、表格或页面截图支持讲解。
- 输出结构、frontmatter、章节顺序和图文插入方式，按 references/output-template.md 执行。
- 如果论文原文有英文摘要，默认在结果中放入英文摘要原文，不要只写整理版。
- 如果正文给出关键结论是数字型的，默认补一个“核心证据表”或等价段落，明确 claim、证据来源和关键数字。
7. 在交付前做一次强制质检
交付前至少核对这几项：
- 摘要原文是否出现
- 关键 claim 是否都能回指到图、表、公式或页码
- 方法图和结果图是否都被正文解释，而不是只被贴上去
- 所有关键数字是否与原文一致
- 是否把非实验论文误写成实验论文
- 是否明确区分“论文明确声称”和“基于证据的解释”
- 是否说明未使用的关键图表为什么没有用
- 是否指出证据缺口、数据库偏差、口径限制或统计解释边界
Scope Rules
- 默认只分析单篇论文，不主动扩展成大规模文献综述。
- 相关工作只保留最小必要集合，用来定位本文相对前作改了什么。
- 图表使用要充分但有选择：
- 方法图、流程图、核心表、关键结果图、消融图、案例图优先
- 不需要机械插入每一页，但不能遗漏关键证据图
- 如果实验部分本身很强，输出篇幅要向实验和结果机制倾斜，而不是把大部分篇幅耗在背景综述上。
Writing Requirements
- 默认使用用户当前语言；不明确时用中文。
- 保留英文术语首现，例如“分数计数 fractional counting”。
- 公式统一使用 Markdown LaTeX。
- 区分“论文明确声称”和“基于证据的解释”。
- 尽量落到具体数字、表号、图号、设置差异，不写空泛判断。
- 优先把数字与来源绑在一起写，例如“Table 2 中增长率为 8.13%，翻倍时间 8.9 年”。
- 如果采用了转写、概括或解释，尽量让读者能追溯到原论文中的位置。
- 对非实验论文，允许改写章节名，但不允许降低证据强度要求。
- 输出要让读者能够复述方法流程、实验逻辑和主要结论的证据来源。
Required Resources
Quality Bar
- 读者看完后能说清“论文怎么做”和“实验凭什么支持这个结论”。
- 关键图片不是装饰，而是被正文明确解释。
- 输出结构完整，接近成熟论文分析笔记。
- 输出里能看到作者 claim、关键数字和证据来源之间的对应关系。
- 非实验型论文也能保持“问题 -> 设计 -> 证据 -> 解释 -> 边界”的完整链条。
- 如果材料不足，明确指出缺口，但仍尽量补齐结构和证据链。
