reproduce

复现：从零开始复现论文

复现一篇机器学习论文，往往意味着要补全作者未提供的内容，例如训练脚本、超参数表、数据增强细节和精确的数据集划分。这项技能分为七个阶段，带你从“我有一个 arxiv 链接”走到“我已完成一次复现运行，并能量化与论文数值的差异”。

每个阶段都有单独的参考文件，位于 references/ 下，让本概览更便于快速浏览。

何时运行

用户刚刚说了以下任意内容：

• “复现 / 实现 / 重现 / 重新运行论文 X”
• 粘贴了一个 arxiv URL，并表示想复现（“能重做一下吗”“我们来试试这个方法”）
• 指向一个 OpenReview / 会议论文集链接，并表达了同样的意图
• 说“这篇论文没有代码，我们能自己构建吗”

工作流

阶段	内容	参考文档
1	获取论文（arxiv HTML → 结构化提取）	references/01-paper-fetch.md
2	发现现有代码并整理清单	references/02-code-clone.md
3	差距分析（从正文中提取所有缺失的超参数）	references/03-gap-analysis.md
4	实现（uv venv、补全缺失内容、每项差距单独提交）	references/04-implement.md
5	获取数据集（优先使用 HF datasets；私有数据集则使用替代数据集）	references/05-dataset.md
6	冒烟运行（前向传播 → 1 步 → 20 次迭代）	references/06-smoke.md
7	复现运行 + 在论文报告的轮次进行比较	references/07-replicate.md

按顺序逐一完成。每个阶段都有自己的成功标准；当前阶段通过之前，不要进入下一阶段。

工作目录布局

对于每篇待复现的论文，都要设置一个专用工作区：

repro/<paper-arxiv-id>/
├── paper.md              # structured extract from stage 1
├── inventory.md          # what exists / missing from stage 2
├── gaps_filled.md        # hyperparam table with provenance from stage 3
├── code/                 # implementation from stage 4 (or cloned + extended)
├── data/                 # dataset symlinks or actual data from stage 5
├── dataset_substitution.md  # if a public dataset stood in for a private one
├── smoke_logs/           # outputs from stage 6
└── results.md            # replication outcomes from stage 7

这样可以让复现工作彼此独立，并且便于日后重新查看。

交叉引用

• 阶段 3 结束后，将差距分析交给 paper-verification 技能进行往返核查（“我是否真的捕获了论文提到的所有超参数”）。
• 阶段 4 的实现应拆分为小型、便于审核的提交：每次提交都要引用用于确定所填数值的论文章节。
• 阶段 6 的冒烟运行失败时，应转交 /phd-skills:debug 技能处理，而不是临时修补。
• 阶段 7 的启动必须先通过 /phd-skills:launch 检查清单，然后才能进行任何持续数小时的运行。
• 阶段 7 的比较应在论文报告的轮次通过 /phd-skills:compare 技能进行（绝不能拿当前结果与最终结果比较）。

输出

每次复现的最终产物都是 results.md，其中应包含绝对差值（不只是百分比），并为每项指标标注以下三个标签之一：

• [matched within 0.X pp]：差异在论文报告的方差范围内
• [gap, hypothesis: ...]：存在可量化的性能差距，并说明可能原因
• [fundamental disagreement, see X]：结果与论文主张存在不一致，需要进一步调查，而不只是增加算力

如果工作区位于公开仓库中，请在项目的主要复现跟踪文档中添加工作区 README 的链接。