Sanmu Paper Reader

---
name: sanmu-paper-reader
description: 精读学术论文、补充材料（SI）和已解析的 Markdown 稿，产出带出处、单位和实验条件、能回查原文的研究笔记。适用于单篇精读和组会准备、多篇文献的结果与机理比较、跨学科方法迁移、围绕课题组织主题，以及基于个人文献库的问答；可按需生成图文对照、Mermaid 机理图、复现准备清单和性能 Benchmark 表。只要用户让你读论文、解释图表、比较文献、提炼实验参数，或者问“这篇文章到底证明了什么”，就使用本技能。材料、化学、催化、光谱、DFT 方向有专门的检查项。Evidence-grounded paper reading and comparison.
---

# 文献精读

目标是把论文读成能核查、能比较、能复用的研究知识。读论文最常见的问题不是看不懂，而是把作者的说法当成已经证实的事实，或者把不同条件下的数字直接放在一起比。所以本技能的核心只有一条：每个关键结论都要能追回原文的具体位置，并带着它成立的条件。

先弄清用户真正想知道什么，再决定读多深。简单问题直接回答并附出处；只有完整精读才需要生成笔记和证据表。默认用中文叙述，原文术语、化学式、变量、单位和必要的短引文保持原样。

## 选择场景

选一个主场景。任务跨场景时，按“精读提取 → 比较或迁移 → 综合回答”的顺序推进，证据只提取一次，后面复用，不要每一步都重新总结全文。只读本次需要的参考文件。

| 用户想做什么 | 场景 | 参考 |
| --- | --- | --- |
| 读懂一篇论文、解释图表、学方法、准备组会 | 单篇 | [single-paper](references/scenarios/single-paper.md) |
| 比较多篇的结果、条件、机理或矛盾 | 跨文献 | [cross-paper](references/scenarios/cross-paper.md) |
| 把一个学科的方法搬到另一个学科 | 跨学科 | [cross-discipline](references/scenarios/cross-discipline.md) |
| 围绕课题把不同主题串起来 | 跨主题 | [cross-topic](references/scenarios/cross-topic.md) |
| 从已有文献库里回答问题、整理主题笔记 | 知识库问答 | [knowledge-qa](references/scenarios/knowledge-qa.md) |

再按论文实际用到的方法，挑 1–3 个领域检查项（复杂任务可以多挑，说明各自用在哪）。论文属于材料领域，不代表要把五个文件全读一遍。

| 研究内容 | 参考 |
| --- | --- |
| 合成路线、组成、物相、界面、结构表征 | [合成与表征](references/domains/synthesis-characterization.md) |
| 光催化、热催化、电催化、电化学 | [催化与电化学](references/domains/catalysis-electrochemistry.md) |
| 第一性原理计算、缺陷、反应路径、计算与实验对应 | [DFT 与材料计算](references/domains/dft-computation.md) |
| 光谱峰归属、载流子过程、原位表征、机理 | [光谱与机理](references/domains/spectroscopy-mechanism.md) |
| 性能、稳定性、数据集、跨研究比较口径 | [性能比较](references/domains/performance-comparison.md) |

材料机器学习论文也用这套结构：计算稳定性看 DFT，数据划分、模型指标和验证层级看性能比较。其他学科可以走通用流程，但要告诉用户这些领域检查项是按材料和化学写的，阈值不一定适用。

## 准备材料

1. **弄清问题**。从请求里推断合理的范围；只有缺材料、或研究对象不明会实质改变结论时才追问。
2. **清点手头有什么**：主文、SI、勘误或不同版本、已有的解析笔记、原 PDF。有可靠的解析稿就直接用，不要重复 OCR。Zotero 不是必需的；有宿主 Zotero 工具时，先列分类、选条目，再读元数据和附件。
3. **只有 PDF 时**，先看有没有文字层。原生提取能得到带页码的阅读文本，但公式、双栏顺序和图表可能失真，有疑问的地方回看原页。扫描件或复杂排版需要高质量转换时可以用 `sanmu-doc2md`（没装也不影响阅读）。纯文本导出不等于完成了保留公式和高清图表的转换，别这样描述。
4. **记录实际读了什么**：哪些章节和页、哪些图表和附件。没有 SI 就写“未获取”；找到了但没读的不算核实过。只读了摘要时，只能给初步导读，没法评价完整证据链。
5. **核对文献身份**：用元数据、DOI 和原文确认。预印本和正式版、同一研究的主文和 SI 分开记录关系，综合时避免把同一份证据算两次。作者的说法、用户的批注、你自己的判断分开保存。

Zotero 操作走宿主提供的工具或验证过的只读导出接口，不遍历 storage，也不直接读写数据库（会和运行中的 Zotero 冲突）。阅读和本地分析不需要改库；写笔记、标签或批注只在用户授权的范围内做，写之前核对库身份和现有内容，写完回读确认。

## 阅读与记录证据

先读摘要和结论，了解论文想证明什么；再按问题去读相关的结果、方法、图题和 SI。摘要只用来定位，关键数字、比较和机理要回到结果和方法部分核对。

对同一批解析稿反复提问时，可以按 [主题路由与分层读取](references/topic-reading.md) 建一个检索入口，依次定位主题、读取候选片段、再核对完整原文块。导读和解读笔记只是索引，不能代替原文。

每个关键论断记下四样东西：

- **原文报告了什么**：样品或模型、变量、对照、结果、误差，以及测量或计算条件。
- **在哪里**：哪篇文献、主文还是 SI、核实过的章节/页码、图表和面板。没有页码映射就用章节加短引文定位，不要估页码。
- **能说明到什么程度**：作者怎么解释的；证据是直接的还是间接的；有没有别的解释；哪些是你的解读，哪些还只是假设。
- **还缺什么**：区分“未报告（已读范围：…）”“未获取”“尚未阅读”“无法辨认”“适用性待确认”“不适用”。只读了一部分，就不能说全文没有报告。

**看图表**时核对坐标轴、单位、图例、面板、归一化基准、样本数和误差条。如果只看到了图题和正文描述、没看到图本身，要说清楚，不要描述自己没看到的曲线趋势、拟合质量或结构图。

**处理数值**时保留定义和条件。需要换算就写出原值、公式、假设和结果；负载量、面积、参比电极、能量基准不明时不要擅自换算。比较性能前先判断能不能比。原文内部数字打架时，把两处位置都列出来，不要替作者悄悄改掉。

## 容易读错的地方

这些是材料和化学文献里最常见的过度解读：

- DFT 算出来稳定 ≠ 实验上能合成出来。
- PL 猝灭 ≠ 载流子有效分离（也可能是非辐射复合增强）。
- 加牺牲剂产氢 ≠ 无牺牲剂的全解水。
- 机理示意图是作者的解释，不是独立的验证实验。
- 新材料和性能提升同时出现，只说明相关，不自动说明因果。
- 最佳样品、单次测试和平均性能是三回事，别互相替代。

精读时可以写“对本课题的启发”和下一步验证建议，但措辞上要让读者分得清：哪些是文献已经证实的，哪些是研究假设，哪些是你建议做的实验。

## 交付

先回答用户的问题，再给足够的证据和限制。不要每次都套一整组空模板。

- **单篇**：核心结论、关键证据、方法与复现缺口、局限、对课题的启发。图文对照、Mermaid 机理图、复现准备 SOP 草案、Benchmark 比较按需启用（做法见 single-paper）。SOP 要标出缺项和原文出处，它只是给实验人员审阅的草案，不是可以直接照做的规程。
- **跨文献**：共同问题、带条件的横向对比表、一致与分歧之处、能下和不能下的结论。
- **跨学科**：原学科概念、目标学科中的对应物、对不上的地方、验证计划。类比只是候选假设。
- **跨主题**：问题驱动的主题结构、每条联系的依据、证据缺口、建议的阅读顺序。
- **问答**：直接答案、出处、反例或限制、检索覆盖了哪些范围。没找到不等于不存在；个人文献库问答也不是系统综述。

需要落成文件时，默认放在一个新目录里，原文解析稿和用户批注保持独立。阅读笔记建议命名为“作者 - 年份 - 标题 - 解读.md”，综合笔记用具体的研究问题命名，并链接到原文和 SI。任务需要且用户同意时，可以把带单位、条件和出处的指标写进 `benchmarks.csv`，或给 Zotero 条目加学术标签。

更新已有的解读时先读旧版本并比较，只改自己生成且没被人动过的部分；有冲突就另存新版本。不要清空目录，也不要改写用户自己写的见解。

证据多、要长期更新或做跨文献对比时，按 [证据契约](references/evidence-contract.md) 维护 `evidence.json`；简单回答用行内出处就够了。来源清单和机械检查结果放在工作目录，不要混进阅读笔记正文。

## 工具

完整插件安装时，三个技能和辅助脚本全部随包提供。包根目录的 `node scripts/sanmu.mjs reader <evidence|topic|si-probe|extract-si|crop|benchmark> ...` 对应下方六个脚本，自动使用私有 Python 环境并在图像操作首次使用时准备依赖；先确认本技能目录上两级存在 `scripts/sanmu.mjs`。文献检索、文件和 Zotero 操作可使用随包 `sanmu` MCP，`open_panel` 可打开工作台。

核心阅读由你自己完成，不需要额外的科研技能、向量库或云端账号。单独安装技能时，辅助脚本只依赖 Python 3.10+ 标准库，图像相关功能另需 PyMuPDF 和 Pillow（`pip install -r requirements.txt`）。不必提前装：等到真用到 SI 检索、附图提取或子图裁切，脚本报缺少 `fitz` 或 `PIL` 时，再告诉用户缺什么、用来做什么，征得同意后装进虚拟环境。从本技能目录运行：

```bash
# 证据：建立来源清单，检查证据表
python scripts/evidence_tools.py inventory ./sources --out ./work/sources.json
python scripts/evidence_tools.py check ./work/evidence.json --root ./sources --out ./work/check.json

# SI：在有文字层的 SI 里定向搜索参数，提取附图或整页预览
python scripts/si_probe.py ./sources/paper-SI.pdf --search "TEOA,xenon,Hubbard"
python scripts/extract_si_figures.py ./sources/paper-SI.pdf --out-dir ./images/SI

# 把复合大图按面板切开
python scripts/crop_subfigures.py ./images/master_fig.png --out-dir ./images/subfigures --spec-json ./crops.json

# 把性能数据写进 Benchmark 表
python scripts/benchmark_collector.py add ./benchmarks.csv --json-entry '{"doi":"...","condition_id":"420nm","activity_rate":"10.7","activity_unit":"mmol g-1 h-1","source":"SI p.4 Table S1"}'
```

使用时注意：

- `extract_si_figures.py` 的输出清单里，`extraction_mode` 区分 `embedded_image`（嵌入位图）和 `page_render`（整页渲染）。同页的几个图号可能共用一张整页图，不代表每张图都单独分离出来了。扫描件的题注要先 OCR，提取结果都要回原页核对。
- `benchmark_collector.py` 用 `record_id` 或“DOI/引用键 + `condition_id`”定位记录，只更新显式给出的字段；传空字符串或 JSON `null` 表示清空该字段。没有标识的旧记录只有在论文唯一匹配时才会更新；匹配含糊时脚本会报错并列出候选，按候选补上标识即可，它不会自动合并历史数据。
- 来源清单记录相对路径和文件哈希；证据表要你读完后自己填，脚本不会生成科学结论。源文件变了，要回去重读相关证据，而不是只更新哈希。

开发测试在源码仓库根目录运行 `python -m unittest discover -s tests/sanmu-paper-reader -v`，安装后的技能不需要跑。

## 完成前检查

1. 用户的问题回答了吗？实际读了哪些、哪些材料没拿到、有什么局限，都说清楚了吗？
2. 每个重要论断都能定位到读过的证据吗？那段原文真的支持这个论断，而不只是出现了同一个关键词？
3. 数值、单位、条件、样品或模型、不同层级的验证有没有混在一起？
4. 用到的领域检查项是否适用？比较时有没有保留那些对不齐的差异？
5. 链接能打开吗？长任务的证据表通过机械检查了吗？关键论断回原文核对过了吗？

`evidence_tools.py check` 只验证文件、哈希、字段和引文能否匹配，不验证页码图号对不对、语义是否支持、图表内容或科学正确性。所以报告时把“机械检查”和“阅读核验”分开写，不要用一个“通过”概括两者。

证据来源、数值条件、文件保护和事实与假设的界线要守住；阅读顺序、分析深度、主题怎么组织、给什么研究建议，由你根据任务判断。