jaimeparker/paper-code-audit

Paper-Code-Audit: 论文-代码-笔记三方交叉验证

对一篇研究论文进行系统性三方对比：论文原文（Zotero 全文 + annotations）→ 官方代码（Git clone 到本地精读）→ 个人笔记（Obsidian 已有笔记），找出所有偏差并输出结构化分析报告到 Obsidian。

前置依赖

此 skill 需要以下 MCP 工具可用：

• mcp__zotero-mcp__* — Zotero 文献库访问（搜索、全文提取、annotations）
• mcp__obsidian__* — Obsidian vault 笔记读写
• Git CLI — 克隆代码仓库
• Bash/Python — 辅助文本提取

工作流总览

Phase 1: Source Acquisition
  ├── Zotero: search by title → get full text + annotations
  ├── Obsidian: search by paper title/keywords → read existing notes
  └── Git: clone repo to reference/<repo-name>/

Phase 2: Deep Reading
  ├── Read all source files in the repo
  ├── Read config files and hyperparameters
  ├── Read paper full text (algorithms, equations, implementation details)
  └── Read Obsidian notes in full

Phase 3: Cross-Comparison (see detailed checklist below)

Phase 4: Documentation
  ├── Write discrepancy note to Obsidian (same dir as existing notes)
  └── Update relevant MOC(s) with link to new note

---

Phase 1: Source Acquisition

1.1 Zotero — 获取论文原文

通过论文标题在 Zotero 中搜索：

mcp__zotero-mcp__search_library(title="<exact paper title>", includeAttachments="true")

获取到 item key 后，并行拉取三个信息源：

• 全文: mcp__zotero-mcp__get_content(itemKey="<key>", mode="complete", format="text")
• 摘要: mcp__zotero-mcp__get_item_abstract(itemKey="<key>")
• Annotations: mcp__zotero-mcp__get_annotations(itemKey="<key>")

Zotero 连接可能不稳定。若 get_content 返回 socket closed，先尝试 fulltext_database(action="get", itemKeys=["<key>"]) 从缓存读取。若仍失败，降级使用 abstract + annotations。

全文文本量大时（>25K tokens），用 Python 脚本按关键词分段提取：

python3 -c "
import json
with open('<cached-fulltext.json>', encoding='utf-8') as f:
    text = json.load(f)[0]['text']
# Extract sections around keywords
for kw in ['Algorithm', 'loss', 'hyperparam', 'Implementation', 'horizon']:
    idx = text.lower().find(kw.lower())
    if idx >= 0:
        print(text[max(0,idx-80):idx+800])
        print('---')
"

1.2 Obsidian — 获取已有笔记

mcp__obsidian__search_notes(query="<paper title keywords>", limit=5, searchContent=true)

找到笔记路径后读取全文：

mcp__obsidian__read_note(path="<note-path>")

若笔记关联了 MOC（通过 search_notes 结果的 excerpt 或 MOC 文件名判断），记录 MOC 路径供后续更新。

1.3 Git — 克隆代码仓库

从论文中获取 GitHub URL（通常在 abstract 末尾或 footnote 中），Clone 到 reference 目录：

mkdir -p D:/Projects/reference && cd D:/Projects/reference && git clone <repo-url> <repo-name>

若论文未直接提供 URL，从 Zotero notes/comments 中搜索（annotations 中常见 Code: https://github.com/...）。

---

Phase 2: Deep Reading

2.1 代码精读

按以下优先级读取所有源文件：

1. 入口文件: train.py, main.py, run.py
2. 核心算法: algorithm/<name>.py, agent.py, model.py
3. 网络/工具: helper.py, utils.py, networks.py
4. 配置文件: config.yaml, cfgs/default.yaml, cfgs/**/*.yaml
5. 环境接口: env.py, environment.py

2.2 论文精读

重点关注以下章节：

• Algorithm 伪代码 (Algorithm 1/2/3)
• Implementation details 段落
• Loss functions / Objectives 公式
• Hyperparameters 表格或段落
• Architecture 描述（encoder/decoder/network layers）

2.3 笔记精读

完整阅读 Obsidian 笔记，提取：

• 对算法原理的解读
• 对超参数的记录
• 对架构的描述
• 对训练流程的说明
• 既往的批判性分析

---

Phase 3: Cross-Comparison Checklist

按此清单逐项对比，每项标注 一致 / 偏差 / 代码未实现 / 笔记有误：

Architecture

| # | 检查项 | 论文 | 代码 | 笔记 | |---|--------|------|------|------| | A1 | Encoder 结构 (layers, dims, activations) | | | | | A2 | Dynamics/Transition model | | | | | A3 | Reward predictor | | | | | A4 | Value/Critic network(s) | | | | | A5 | Policy/Actor network | | | | | A6 | Target network 更新机制 | | | |

Hyperparameters

| # | 检查项 | 论文值 | 代码值 | 笔记值 | |---|--------|--------|--------|--------| | H1 | Learning rate | | | | | H2 | Batch size | | | | | H3 | Discount factor γ | | | | | H4 | Planning/rollout horizon | | | | | H5 | Loss coefficients | | | | | H6 | Network dimensions | | | | | H7 | EMA τ / update frequency | | | | | H8 | Exploration parameters | | | | | H9 | Gradient clip norm | | | |

Loss Functions

| # | 检查项 | 论文公式 | 代码实现 | 笔记描述 | |---|--------|---------|---------|---------| | L1 | Reward loss 形式 | | | | | L2 | Value/TD loss 形式 | | | | | L3 | Consistency/regularization loss | | | | | L4 | Policy/Actor loss | | | | | L5 | 额外 loss terms | | | |

Algorithm Flow

| # | 检查项 | 论文 | 代码 | 笔记 | |---|--------|------|------|------| | F1 | Planning 流程 (采样→rollout→打分→更新) | | | | | F2 | Training 流程 (采样→encode→unroll→loss→backprop) | | | | | F3 | 数据流 (buffer 采样方式、序列长度) | | | | | F4 | Exploration 策略 | | | | | F5 | Warm-start / momentum 细节 | | | |

Engineering Details

| # | 检查项 | 代码实际 | 笔记是否覆盖 | |---|--------|---------|-------------| | E1 | Loss clamping / gradient protection | | | | E2 | Device placement (GPU/CPU buffer) | | | | E3 | Frame stacking / preprocessing | | | | E4 | Action repeat / episode length 计算 | | | | E5 | Per-task config overrides | | |

---

Phase 4: Documentation

4.1 编写偏差分析笔记

在 Obsidian 中已有笔记的同目录下创建新笔记，命名格式：<PaperName> Code vs Note 偏差分析.md

报告结构：

# <PaperName> Code vs Note 偏差分析

对比对象：
- **论文**: <citation>
- **官方代码**: <repo-url> (reference/<repo-name>/)
- **已有笔记**: [[<existing-note>]]

总体结论：<一句话总结一致性>

---

## 1. <偏差类别 1>

**笔记说法**：...
**代码实际**：...
**结论**：...

---

## 2. <偏差类别 2>
...

---

## 总结

| 偏差类型 | 严重程度 | 说明 |
|----------|---------|------|
| ... | 高/中/低 | ... |

严重程度判断标准：

• 高: 笔记对算法的核心理解有误，影响对方法本质的把握
• 中: 概念层面混淆或重要工程细节遗漏
• 低: 数值精确度差异、off-by-one、注释级细节

4.2 更新 MOC

在相关 MOC 中将新笔记添加为已有论文笔记的子链接：

mcp__obsidian__patch_note(
    path="<MOC-path>",
    oldString="- [[<existing-note>]] <原有描述>",
    newString="- [[<existing-note>]] <原有描述>\n\t- [[<new-note>]] 代码、论文、笔记的三方对比与偏差记录"
)

若原笔记隶属多个 MOC，选择最相关的（通常是与论文领域直接对应的 MOC 章节）。

---

容错与降级策略

| 场景 | 处理方式 | |------|---------| | Zotero 全文获取失败 | 使用 abstract + annotations + fulltext_database cache | | 论文无公开代码 | 跳过 Phase 2.1 代码部分，仅做论文 vs 笔记对比，报告中注明 | | Obsidian 无相关笔记 | 跳过笔记对比，仅做论文 vs 代码对比 | | Git clone 失败 (SSH/网络) | 尝试 https URL 替代 git@ URL | | 代码语言非 Python | 仍按 Phase 2 流程推进，可能需关注不同文件约定 | | MOC 结构不明确 | 将新笔记放在原笔记同目录，用户手动链接 |

---

注意事项

• Phase 3 的 checklist 是最小检查集——根据论文具体内容扩展（如多任务/多模态论文需额外检查 task embedding、action masking 等）
• 偏差分析笔记应保持客观、精确：每条偏差引用具体的文件路径和行号
• 如果三方完全一致（罕见但可能），仍然输出笔记，确认"无偏差"，这对学术记录同样有价值
• Zotero 全文提取可能因 PDF 格式而异（公式可能显示为乱码），此时以代码和笔记为主进行交叉验证