# Paper Reading

> 把学术论文（PDF/摘要/DOI/二手转述）加工成可核查的中文精读笔记：支持 PDF 导入与页码锚点，先一段话总结核心内容，再按"背景→方法→实验→贡献→局限"重建论证链，公式统一用 Markdown 数学语法，并附符号表与来源分层；产出八种互相独立的文件——精读讲解、逐篇填表、思维导图（文本大纲 + 可渲染 Mermaid 两种形态）、难点与解答、中英对照的全量专业术语表、多篇汇总综述，以及把整个笔记库管成 wiki 的合集层索引（主题清单 + 术语速查 + 跨论文对比 + 未解决问题 + 证据强度总览），每篇论文目录里另有一份可机械校验的单篇索引（全量文件登记 + 证据强度提示 + 待核入口）。当用户说"讲一下这篇论文""论文精读""导入这篇 PDF""填这个表格""生成思维导图""这篇论文的难点""可能遇到什么问题""写文献综述""整理我的论文笔记库""更新笔记库索引""这篇论文的专业术语""出个中英对照术语表"或输入 /paper-reading 时使用。

- Skill: `shen-an/paper-reading` (Agent Skill, multi-file: 161 files)
- Install (CLI): `npx skillmds@latest add shen-an/paper-reading`
- Raw SKILL.md: https://api.skillmd.com/api/skills/shen-an/paper-reading/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- License: MIT
- Author: Shen-An (https://skillmd.com/u/shen-an)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/shen-an/paper-reading

---


# Paper Reading：论文精读与文献加工

把一篇（或多篇）论文加工成**可核查的中文笔记**：不是翻译，而是把论文的**论证链**重建成"有领域基础、但缺这个子方向基础"的读者能一次读懂、且每条断言都能回溯到来源的结构。

核心主张有三条：

1. **论文笔记的价值在证据分层，不在复述完整。** 二手转述（他人摘要、博客、AI 总结）里的数字与动机必须降级标注，不能与原文/官方代码同权呈现。
2. **一种产出只讲一件事。** 精读讲解、逐篇填表、思维导图、难点与解答、专业术语表、汇总综述各自独立成文件、独立呈现；导图不得内嵌进讲解文档，否则读者要在一篇长文里再看一遍同样的内容。
3. **能渲染的形态要真能渲染。** 公式用 Markdown 数学语法；导图另出 Mermaid 形态；同时**如实告知**当前渲染器能不能渲染（DSH Web GUI 只有语法高亮、不出图），不承诺渲染器做不到的事。

只读写 Markdown，不依赖网络；PDF 导入优先用 harness 自带文档读取能力，回退到自带脚本。

## 输入与输出

- **输入**（接入规范见 `references/input-intake.md`）：工作区内 PDF 路径、对话里的上传附件、DOI/arXiv 链接、官方摘要、他人总结、官方代码仓库。缺材料时先说明"只能讲到哪一层"，不要假装读过全文。
- **输出**：默认 `./paper-notes/<论文短名>/`（用户指定路径优先）：

```
paper-notes/
├── README.md              # 模式 G：笔记库索引（合集层：主题清单 + 术语速查 + 跨论文对比 + 未解决问题 + 证据强度总览）
└── <短名>/
    ├── README.md              # 单篇索引（模式 note）：论文身份 + 一句话结论 + 文件登记 + 证据强度提示 + 待核入口；首行必须是 <!-- paper-reading: note-index --> 标记
    ├── _source/<论文名>.md     # PDF 导入产物，含 <!-- page:N --> 页锚点
    ├── 深读-<短名>.md          # 模式 A：精读讲解
    ├── 表格-<短名>.md          # 模式 B：逐篇填表（只有一张表）
    ├── 思维导图-<短名>.md      # 模式 C：四分支思维导图（文本大纲形态）
    ├── 导图-<短名>.md          # 模式 E：同一导图的 Mermaid 可渲染形态
    ├── 难点-<短名>.md          # 模式 F：难点与解答
    ├── 术语-<短名>.md          # 模式 H：中英对照全量专业术语表
    └── 综述-<主题>.md          # 模式 D：多篇汇总综述（多篇时）
```

**模式分离是硬约束**：`深读-<短名>.md` 里不得内嵌思维导图或填表；导图、填表、难点、术语表都必须独立成文件、独立呈现（机械校验 `E-DEEP-MIX` 会拦混装）。术语表里不许塞机制讲解（那是深读的活），深读里的公式符号也不进术语表（符号归符号表）。

`<短名>` 优先取论文主方法缩写（如 `MFAA`），没有方法名就取标题前 3–5 个实词。

### 跨 harness 复用（DSH / Claude Code / Codex 同一份 bundle）

同一个 `<skill名>/SKILL.md` 目录 bundle 三个 harness 通用：安装就是把整个目录拷进对应扫描目录（DSH 用户级 `~/.agents/skills/`，Claude Code `~/.claude/skills/`，Codex `~/.codex/skills/`），不需要编译。差异只在**入口**与**能力**，不在产出契约：

| 维度 | DSH | Claude Code | Codex |
|------|-----|-------------|-------|
| 触发方式 | `/paper-reading` 或自然语言 | `/paper-reading` 或自然语言 | 自然语言（不认斜杠命令） |
| 读 PDF | `read_document`（可 `offset`/`limit` 分页） | 内置 PDF 读入 | 内置读取，不可用时走脚本 |
| 回退通道 | `python scripts/pdf_extract.py`（需 `pypdf`，缺失时 exit 3 并提示安装） | 同左 | 同左 |
| 看 Mermaid 导图 | 只按代码块显示（无渲染器） | 取决于终端/编辑器渲染器 | 取决于渲染器 |
| 跑校验器 | `python scripts/check_paper_note.py <文件> --mode auto` | 同左 | 同左 |

脚本只用标准库（PDF 回退通道额外需要 `pypdf`），路径按脚本自身位置解析、不依赖当前工作目录，所以在任一 harness 里都能直接跑。

## 八种产出

| 模式 | 用户说法 | 产物 | 模板 |
|------|---------|------|------|
| A 精读讲解 | "讲一下这篇论文""精读" | `深读-<短名>.md` | `references/deep-read-template.md` |
| B 逐篇填表 | "填这个表""按模板整理" | `表格-<短名>.md` | `references/table-template.md` |
| C 思维导图（大纲） | "生成思维导图" | `思维导图-<短名>.md` | `references/mindmap-template.md` |
| D 汇总综述 | "写文献综述""多篇对比" | `综述-<主题>.md` | `references/review-template.md` |
| E 可渲染导图 | 与 C 同时产出，或"要能渲染的导图" | `导图-<短名>.md` | `references/mindmap-template.md`（Mermaid 节） |
| F 难点与解答 | "这篇论文有什么难点""可能卡在哪""常见问题" | `难点-<短名>.md` | `references/faq-template.md` |
| H 专业术语表 | "出术语表""中英术语对照""这些术语我不熟"；**默认集成员** | `术语-<短名>.md` | `references/terms-template.md` |
| G 笔记库索引 | "整理我的论文笔记库""更新笔记库索引"；每次交付后自动维护 | `paper-notes/README.md` | `references/index-template.md` |

选择规则：**默认交付集是成套的**——说"读论文""讲论文""总结""精读"，或只丢来 PDF/链接而没点名模式时，默认产出 A 深读 + B 表格 + C 思维导图 + E 导图 + F 难点 + H 术语表，**G 照旧必做**（只要往 `paper-notes/` 里落了新笔记，就按 Step 5 登记进库索引）。**C 与 E 成套产出**（大纲是主形态，Mermaid 是渲染形态），缺一不可。用户点名模式时才单出（"只讲一下""填这个表""要能渲染的导图"）。D 只在一次给多篇且要求"对比/综述/趋势"时产出，**不替代 A、不进默认集**。默认集里某一件确有理由不做（材料不足、用户上一轮刚点过同一件等），必须在交付开头写明省略项与原因，不许静默省略。要问的是"要不要 D"这类增量，**默认集本身不必问**。

> 上表八种是**产出种类**。此外每篇论文目录里还有一个**单篇索引** `README.md`（模式 `note`）——它不是第九种产出，而是把已交付的文件登记成入口页：首行标记 `<!-- paper-reading: note-index -->`，机械校验 `--mode note`（11 项，拦截漏登记、死链、缺 `（模式 X）` 标签），模板 `references/note-index-template.md`。

## 工作流

### Step 1 · 材料接入与定位

1. 按 `references/input-intake.md` 接入材料。有 PDF 就落盘成 `_source/<论文名>.md` 并保留 `<!-- page:N -->` 页锚点：
   - harness 有文档读取能力（DSH 的 `read_document`、Claude Code 的 PDF 读入、Codex 的内置读取）→ 优先用它，分页读完；
   - 否则 `python scripts/pdf_extract.py <pdf> --out paper-notes/<短名>/_source/`；
   - 扫描件走 OCR，正文标 `[OCR]`。
2. 钉死论文身份：标题、作者、年份、发表处、DOI。查不到就写"未核实"，**不要编**。
3. 建立来源分层台账（`references/grounding-rules.md`），每条证据打标：`[原文 p.N]` / `[代码]` / `[摘要]` / `[二手]` / `[OCR]` / `[推断]`（取自实验/消融章节可写定位标签 `[实验]`，引用他人工作写 `[19]`）。
4. 判定可讲深度，并在「证据与出处」首行写 `**来源类型**：……`。

### Step 2 · 抽取论证链

按四段式列草稿（不急着成文）：**问题 → 已有做法为何不够 → 本文机制 → 代价与边界**。
本文机制必须能回答：它替换了哪个组件、替换后额外付出什么（算力、超参、假设）。

### Step 3 · 符号与公式规范化

公式一律写成**可渲染、可继续编辑的 Markdown 数学**（详见 `references/formula-style.md`）：

- 行内 `$...$`；行间用 `$$` **独占一行**的三行块
- 禁止代码块装公式、禁止公式截图、禁止纯文本近似
- 范数用 `\lVert x \rVert_2`，算子用 `\operatorname{Clip}`，自适应括号用 `\left(...\right)`
- 每个符号首现即释，公式后紧跟"其中：……"；公式 ≥ 3 个行间块时必须给符号与记号表

### Step 4 · 按模式成文

- 照对应模板的结构写；模板规定的小节名、顺序、层级不得改动。
- 一次只写一种模式，**不要把导图/表格/难点塞进讲解文档**。
- 讲法基准：读者有本领域通用基础，**没有这个小方向的基础**——小方向术语首现必须用一句大白话加一句"它和相邻概念差在哪"。
- A 模式开头**先用一段话总结核心内容**（≥120 字），结尾给"一句话总结"；F 模式至少 3 条难点，每条必须有 `**难点**` 与 `**解答**`，解答带来源标记。
- 出导图时同时出两个文件：`思维导图-<短名>.md`（大纲）与 `导图-<短名>.md`（Mermaid，节点文本禁用 ASCII `( ) [ ] { } , ; : %`）。
- H 模式按 `references/terms-template.md` 的六节骨架成文：**英文原词必须保留**（英文列空缺或不含拉丁字母会被 `E-TERM-EN` 拦下——这条正是该模式存在的理由），**全量**收录全文专业术语（机械只能保下限，靠模板第 4 节的扫描法保证真全），每条给合法来源标记（`[原文 p.7]` 与裸标记同等合法），第五节至少 5 条英文原句摘录（服务"不丢英文语感"）。
- 禁止寒暄与自述：不写"好的""以下是""希望对你有帮助""如需我可以……"。

### Step 5 · 登记两级索引（单篇模式 note + 合集模式 G）

每篇论文目录里的 `README.md` 是**单篇索引**（模式 note，模板 `references/note-index-template.md`，机械校验 `--mode note`）：**首行必须是** `<!-- paper-reading: note-index -->`（`--mode auto` 靠它识别，文件名都叫 `README.md` 区分不了），正文按"论文：+ 一句话结论：+ `## 文件` + `## 证据强度提示` + `## 待核入口`"成文。**`## 文件` 是目录里全部产出的全量登记**，每行形如 `- [深读-<短名>.md](./深读-<短名>.md)：精读讲解（模式 A）`——漏登记一件就报 `E-NOTE-COVER`（真实踩过：MFAA 的索引漏登记了导图与难点两件，后来又差点漏术语表）。

落盘新笔记后维护 `paper-notes/README.md`（合集层索引，模板 `references/index-template.md`，机械校验 `--mode index`）：

1. 没有库索引就按骨架新建，**首行必须是** `<!-- paper-reading: collection-index -->`（校验器靠它识别）；
2. 已有库索引就**只追加**：在对应 `### <主题>` 下加条目、补术语表、补跨论文对比、补证据强度总览，不重排已有分组；
3. 同步 `> 最近更新：` 日期与收录篇数；同一指标数字不一致时**两列并列**并标"冲突（待核对）"，禁止只留一个；
4. 已有条目结论若因新证据改变，就地改写并在行末留痕 `（更新：YYYY-MM-DD，原因）`，不静默改写。

索引只做**汇总视图**，不复制笔记正文：每条结论必须与对应笔记里的说法同源、同证据强度；被登记的目录必须真实存在（死链由 `E-IDX-LINK` 拦住）。

### Step 6 · 校验与交付

- 先跑机械校验：`python scripts/check_paper_note.py <文件> --mode <auto|deep|table|mindmap|mmd|faq|review|index|note|terms>`（修完所有 ERROR；WARN 逐条人工判断）
- 再逐条过 `references/quality-rubric.md`（忠实性、论证链完整度、讲解密度这些机器查不了）
- **交付纪律**：
  1. **默认集全部静默落盘，正文只展开用户点名的模式**：说"读论文/讲论文/总结/精读"时 A+B+C+E+F+H 六件都要落盘（默认集见"选择规则"），正文只展开被点名的那个模式，其余不搬正文；
  2. **交付开头先给"文件清单 + 每件一句话"**：列出本次全部产物，并写明默认集里哪一件被省略及原因；再按文件分别呈现，每块以文件名开头，用分隔线隔开；
  3. **思维导图、填表、难点、术语表不得与讲解正文混排**——各自独立成块（或独立一条消息）；
  4. **如实说明渲染能力**：Mermaid 导图在 Obsidian / GitHub 能出图，在 DSH Web GUI 只能按代码块显示（只有语法高亮）；要出图就打开 `导图-<短名>.md`。不要口头承诺"已渲染成脑图"。
  5. 每条关键数字后带来源标记（`[摘要]`、`[二手]`、`[原文 p.12]`），并明确列出"未核实/未提及"项。

### Step 7 · 自迭代（证据账本 + 触发式复盘）

- 交付后，把本次失败信号追加进 `feedback/ledger.jsonl`（不存在则创建；格式见 `feedback/ledger.example.jsonl`；只追加、不删改）。必记三类：修复过的 ERROR、被判定"本应在生成时避免"的 WARN、人工核对或用户提出的任何返工。
- 仅当用户要求"复盘/迭代这个 skill"，或自上次版本 bump 后新增记录 ≥ 5 条，才按 `references/self-iteration.md` 进入迭代流程：聚类证据 → 最小 diff → `python evals/run_evals.py` 门禁 → 人工确认后落盘 → 升版本并写 `CHANGELOG.md`。
- **任何一次 Step 1–6 的生成过程中，绝不修改 skill 自身文件**。

## 不可妥协的规则

1. **来源分层与冲突并列**：任何事实断言都要能归到 `[原文 p.N]`/`[代码]`/`[摘要]`/`[二手]`/`[OCR]`/`[推断]`（或等价定位标签 `[实验]`）；二手数字必须标"待核对"；两个来源数字不一致时两个都写，不许取平均、不许沉默。
2. **可渲染优先，且只承诺渲染器做得到的**：公式必须是 Markdown 数学（行间 `$$` 独占一行）；导图必须另出 Mermaid 形态；同时如实说明目标渲染器能不能出图，禁止把"代码块"说成"已渲染的脑图"。
3. **不编造**：论文没说的动机、没做的实验、没有的数字，一律"未提及"；不得用领域常识补写成论文主张；难点文档里每条难点也必须来自材料。
4. **局限不许软化**：单列成节，论文自述与你的独立判断分开写。
5. **数字成对**：实验数字必须带设定（源模型、目标模型、基线、指标口径），禁止孤立抛点。
6. **模式纯净且分离**：填表只输出表格；导图只输出四分支树（大纲与 Mermaid 两个文件，互不内嵌）；难点文档只讲难点与解答；综述只用 `[num]` 标注且不给文献列表；讲解文档不得内嵌导图、表格或难点。
7. **读者假设**：有领域通用基础、无小方向基础——术语首现必释，且说明与相邻方法的差别。
8. **无寒暄**：输出只含论文相关内容，不写开场白、不写"如需进一步……"。
9. **全文来源必须给页锚点**：声明 `PDF 全文` 就必须出现 `[原文 p.N]`；来源类型声明不得漏。
10. **生成期不动 skill**：Step 1–6 期间绝不修改本 skill 自身文件。

## 质量下限

产出必须做到：一个没读过这篇论文、但有领域基础的人，仅凭笔记能复述"这篇论文解决了什么、怎么解决的、凭什么说解决了、代价与边界在哪、哪里最容易理解错"，并知道每句话该去哪里核（哪一页、哪个文件、哪一行代码）。达不到就重写，不要交半成品。