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/），不需要编译。差异只在入口与能力，不在产出契约：

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

八种产出

选择规则：默认交付集是成套的——说"读论文""讲论文""总结""精读"，或只丢来 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 自身文件。

质量下限

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