paper2code-arxiv-implementation

用途

paper2code 是一个 Claude Code 智能体技能，用于把任意 arXiv 论文转换为可运行的 Python 实现。其核心价值在于可追溯性：每一处非平凡的代码决策都会标注对应的论文出处，所有论文未说明或含糊的地方都会被显式标记，而不是被静默填补。

主要能力

将 arXiv 论文 URL 或裸编号转换为 Python 实现。
引用锚定：每个代码决策引用其实现的论文章节与公式。
歧义审计：对论文未说明、部分说明或需要推断的地方进行标记。
支持框架覆盖：PyTorch（默认）、JAX、TensorFlow。
支持三种模式：minimal（仅架构，默认）、full（含训练循环与数据管线）、educational（额外注释与教学 notebook）。

使用方式

安装命令：

npx skills add PrathamLearnsToCode/paper2code/skills/paper2code

安装过程中需选择：

Agents：哪些编码智能体获得该技能（例如 Claude Code）
Scope：全局（推荐）或项目级
Method：符号链接（推荐）或复制

随后启动智能体：

claude

核心命令示例：

/paper2code https://arxiv.org/abs/1706.03762
/paper2code https://arxiv.org/abs/2006.11239 --framework jax
/paper2code https://arxiv.org/abs/2006.11239 --framework pytorch   # default
/paper2code https://arxiv.org/abs/2006.11239 --framework tensorflow
/paper2code 1706.03762 --mode minimal       # architecture only (default)
/paper2code 1706.03762 --mode full          # includes training loop + data pipeline
/paper2code 1706.03762 --mode educational   # extra comments + pedagogical notebook
/paper2code 1706.03762
/paper2code 2106.09685

输出结构

每次运行会生成以论文 slug 命名的目录，例如：

attention_is_all_you_need/
├── README.md                  # Paper summary + quick-start
├── REPRODUCTION_NOTES.md      # Ambiguity audit, unspecified choices, known deviations
├── requirements.txt           # Pinned dependencies
├── src/
│   ├── model.py               # Architecture — every layer cited to paper section
│   ├── loss.py                # Loss functions with equation references
│   ├── data.py                # Dataset skeleton with preprocessing TODOs
│   ├── train.py               # Training loop (full/educational mode)
│   ├── evaluate.py            # Metric computation
│   └── utils.py               # Shared utilities
├── configs/
│   └── base.yaml              # All hyperparams — each cited or flagged [UNSPECIFIED]
└── notebooks/
    └── walkthrough.ipynb      # Paper section → code → shape checks

引用锚定约定

每个非平凡决策会被打上标签：

§X.Y：论文第 X.Y 节直接说明
§X.Y, Eq. N：实现第 X.Y 节的公式 N
[UNSPECIFIED]：论文未说明，已列出替代选项
[PARTIALLY_SPECIFIED]：论文提及但含糊，附有原文引用
[ASSUMPTION]：合理推断，附有推理说明
[FROM_OFFICIAL_CODE]：取自作者官方实现

适用场景

实现新的架构论文（minimal 模式，重点查看 src/model.py 与 REPRODUCTION_NOTES.md）。
复现训练方法（full 模式，重点查看 src/train.py 与 configs/base.yaml）。
教学式深入研读（educational 模式，notebooks/walkthrough.ipynb 逐节讲解并运行 CPU 安全的形状检查）。
快速架构原型（生成后安装依赖并运行形状检查）。

限制

paper2code 明确不会做以下事情：

不保证正确性：只匹配论文描述，若论文有误则代码也有误。
不静默编造细节：缺口始终标记为 [UNSPECIFIED]。
不下载数据集：data.py 仅提供带说明的 Dataset 骨架。
不搭建训练基础设施：无分布式训练、无实验跟踪。
不实现基线：只实现论文的核心贡献。
不重新实现标准组件：通过导入或注明依赖。

常见问题排查

技能未触发：确认安装完成（npx skills list 应显示 paper2code-arxiv-implementation），使用显式触发 /paper2code <url>，或尝试裸 arXiv ID 格式。
生成代码有导入错误：先运行 pip install -r requirements.txt，检查 REPRODUCTION_NOTES.md 中注明的依赖；标准组件（如 HuggingFace transformers）是导入而非重实现，需单独安装。
“Paper not found”或抓取错误：确认 arXiv ID 存在，尝试完整 URL；部分极新论文可能尚未被索引。
生成代码中的静默假设：按设计不应发生，若发现则为 bug；先检查 REPRODUCTION_NOTES.md，若确实被静默填补可通过仓库 issues 报告。
框架相关问题：默认框架为 PyTorch；JAX 输出需要 jax、flax、optax；TensorFlow 输出需要 tensorflow>=2.x。

资源

仓库：https://github.com/PrathamLearnsToCode/paper2code
示例：仓库中的 skills/paper2code/worked/
问题反馈：https://github.com/PrathamLearnsToCode/paper2code/issues
许可证：MIT