---
name: sanmu-paper-reader
description: 解读论文、补充材料与解析稿，用于单篇精读、跨文献比较、方法迁移和知识库问答。保留证据来源、单位工况及事实与假设边界，按需提供图文对照、复现准备草案和性能比较。
---

# 文献解读（sanmu-paper-reader）

把文献读成可以核查、比较与复用的研究知识。先理解用户的研究问题，再决定阅读深度和产物；简短问题可直接回答，完整精读才生成笔记与证据表。默认中文叙述，保留原文术语、化学式、变量、单位和必要短引文。

## 1. 按场景与研究类型路由

选择一个主场景。跨场景任务按“精读提取 → 对比或迁移 → 综合回答”顺序执行，共用证据，不重复全文总结。只读取本次需要的参考文件。

| 用户目的 | 主场景 | 必读参考 |
| --- | --- | --- |
| 读懂一篇论文、解释图表、学习方法或准备组会 | 单篇 | [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，数据划分、模型指标与验证层级看性能比较。其他学科可用通用流程，但声明目前领域检查项主要针对材料与化学，不机械套用这些阈值。

## 2. 确定材料、问题与阅读边界

1. 明确用户希望弄懂、比较或决策的问题。从请求推断合理范围；仅在缺失材料或研究对象会实质改变结论时询问。
2. 清点主文、SI、勘误/版本、已有解析笔记与原 PDF。优先复用可靠解析产物，避免重复 OCR。Zotero 不是必需依赖；有宿主 Zotero 工具时先列分类、选条目，再读元数据和附件。
3. 只有 PDF 时先检查文字层。原生提取可以做带物理页标记的阅读文本，但公式、双栏顺序和图表可能失真；有问题的部分回看原页。扫描件或复杂排版需要 OCR 时，可用可用的转换工具；可选 `sanmu-doc2md`，未安装也不阻断通用解读。不能把纯文本导出称为完成高清图表与公式保真的转换。
4. 记录确实读过的章节/页、图表和附件。没有 SI 就标“未获取”；定位到但没读的内容不算已核验。仅读摘要时只能给初步导读，不能评价完整证据链。
5. 以元数据、DOI和原文核对文献身份；预印本与正式版、同研究的主文与SI分别记录关系，综合时避免重复计数。作者宣称、用户批注和助手判断分别保存。

Zotero 操作使用宿主支持的工具或已验证的只读导出接口，不遍历 storage、不直接读写数据库。读取与本地分析不需要修改文献库。写笔记、标签或批注仅在用户授权的范围内执行，按库身份与现有内容核对并回读。

## 3. 从问题组织阅读与证据

先读摘要和结论建立路线，随后读相关结果、方法、图题及SI。摘要只作索引；关键数字、比较和机理回到结果与方法核对。

反复查询已有解析稿时，按 [主题路由与分层读取](references/topic-reading.md) 建立可选入口，依次定位主题、读取候选、核对完整原文块。支持独立 Markdown 或复用 doc2md `agent/` 索引；来源改变即失效，导读与解读笔记保留其身份，不能替代论文原文。

对每个关键论断记录：

- **原文报告**：样品/模型、变量、对照、结果、误差和测量或计算条件。
- **证据位置**：来源文献、主文或SI、已核实的章节/物理页或印刷页、图表及面板。没有页映射就引用可核查章节和短引文，不猜 PDF 页码。
- **解释边界**：作者如何解释；证据是否直接、是否存在其他解释；哪些是本次解读，哪些仍是假设。
- **待补信息**：区分“未报告（已读范围：…）”“未获取”“尚未阅读”“无法辨认”“适用性待确认”“不适用”；只读局部不能断言全文未报告。

解读图表时核对坐标、单位、图例、面板、归一化基准、样本数和误差条。只看到文字/图题时明确标注，不能声称看过曲线趋势、拟合质量或原子结构图。机理示意图本身不是独立的验证实验。

数值必须保留定义和条件。换算给出原值、公式、假设和结果；不要擅自换算未知负载量、面积、电位参照或能量基准。性能比较先判断可比性，再评价差异。发现原文内部冲突时并列记录位置，避免替作者静默修正。

精读可提出“对本课题的启发”和下一步验证，但研究假设、建议实验与文献已证实结果要有明确措辞。不能把 DFT 稳定性等同可合成性、PL 猝灭等同有效载流子分离、产氢等同无牺牲剂整体水分解。

## 4. 按任务交付与知识积累

交付优先回答用户的问题，再提供足够的证据与限制。不要无条件生成一组空模板。

- 单篇：核心结论、关键证据、方法与复现缺口、局限及研究启发。根据任务需要启用图文对照、Mermaid 机制图、复现准备 SOP 草案或 Benchmark 比较，不要求每次全部生成。SOP 需注明缺项及原文出处，不作为可直接执行的实验规程。
- 跨文献：共同问题、带条件的横向比较表、一致与分歧、可以与不可以作出的结论。
- 跨学科：原学科概念、目标学科对应、失配点、验证计划；类比只作为候选假设。
- 跨主题：问题驱动的主题结构、每条主题联系的依据、证据缺口与优先阅读顺序。
- 问答：直接答案、出处、反例/限制和检索覆盖范围。未找到不等于不存在，不把个人库问答称为完整系统综述。

完整文件产物默认放在新独立目录；原文解析稿、用户批注保持独立。阅读笔记推荐“作者 - 年份 - 标题 - 解读.md”，综合笔记使用具体研究问题命名，建立指向原文和SI的可用链接。任务需要且获授权时，可将带单位、工况与来源的指标写入 `benchmarks.csv`，或更新 Zotero 学术标签。更新已有解读先读取并比较，只更新自己生成且未被人工修改的部分；冲突时写新版本，不清空目录或重写用户见解。

证据较多、需要长期更新或跨文献对比时，按 [证据契约](references/evidence-contract.md) 保存 `evidence.json`；简单回答可使用同等信息的行内出处。来源清单与机械质检文件放工作目录，不混入正式阅读正文。

## 5. 工具与验收

无需额外科研 Skill、向量库或云端账号。核心阅读由当前助手完成；可选离线工具仅需 Python 3.10+ 标准库与可选 PyMuPDF。从本技能目录运行：

```bash
# 1. 证据核验与清单生成
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

# 2. 有文字层的 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

# 3. 大图子面板精准切片 (Sub-figure Crop)
python scripts/crop_subfigures.py ./images/master_fig.png --out-dir ./images/subfigures --spec-json ./crops.json

# 4. 性能 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"}'

```

开发测试从源码仓库根目录运行 `python -m unittest discover -s tests/sanmu-paper-reader -v`；安装技能不要求运行开发测试。图像清单的 `extraction_mode` 区分嵌入位图与整页渲染，同页图号可共用页面，不等于独立图已全部分离；扫描题注需先 OCR，提取结果需回页核对。Benchmark 用 `record_id` 或 DOI/引用键 + `condition_id` 定位记录；只更新显式提供字段，空字符串或 JSON null 显式清空。无标识旧记录仅在论文唯一匹配时可更新；含糊匹配先按报错候选核对，不自动合并历史数据。

清单记录相对路径和文件哈希；证据表还需要助手在阅读后填写，工具不自动生成科学结论。文件改变后回看证据并重新核对，不只替换哈希。

完成前检查：

1. 问题是否得到回答，实际阅读范围、未获得的材料与局限是否明确。
2. 重要论断能否定位到已读证据；片段是否真正支持该论断，而非仅包含同一关键词。
3. 数值、单位、条件、样品/模型和不同验证层级是否被正确区分。
4. 学科检查项是否适用，比较是否保留无法对齐的差异。
5. 输出链接可用；长任务证据表机械检查通过，并完成关键论断的人工/助手回源核对。

机械检查只验证文件、哈希、字段和引文匹配，不验证页码/图号真实性、语义支持、图表视觉内容或科学正确性。分别报告自动检查与阅读核验结果，不能用一个“通过”替代两者。

严格固定证据与数值来源、文件保护和事实/假设边界；阅读顺序、分析深度、主题组织与研究建议保留判断空间。