reproduce

复现：从头复现论文

复现 ML 论文往往意味着要补齐作者未提供的内容，例如训练脚本、超参数表、数据增强细节和精确的数据集划分。这项技能分为七个阶段，带你从“我有一个 arXiv 链接”走到“我完成了一次复现实验，并能衡量与论文结果的差距”。

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

何时运行

用户刚刚说了以下任意一项：

• “复现／实现／重现／重新运行论文 X”
• 粘贴了 arXiv URL，并表达了复现意图（“能重做一下吗”“我们试试这个方法吧”）
• 提供了 OpenReview／会议论文集链接，并表达了同样的意图
• 说“论文没有代码，我们能自己搭建吗”

工作流

阶段	内容	参考资料
1	获取论文（命令行工具 + PDF → 结构化提取）	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 结束后，将差距分析交给 /labrat:paper-check 技能进行往返核查（“我是否真的记录了论文提到的所有超参数？”）。
• 阶段 4 的实现应拆分为小型、便于审查的提交：每个提交都要注明所填数值依据的论文章节。
• 阶段 6 的冒烟测试失败时，应转交 /labrat:debug 技能处理，而不是临时修补。
• 阶段 7 启动实验前，必须先完成 /labrat:launch 清单，再运行任何数小时的任务。
• 阶段 7 的比较应使用论文报告的轮次，并通过 /labrat:compare 技能进行（绝不能拿当前结果与最终结果比较）。

输出

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

• [matched within 0.X pp]：差异在论文报告的方差范围内
• [gap, hypothesis: ...]：性能存在可测量的差距，并注明导致差距的假设
• [fundamental disagreement, see X]：实验结果与论文的结论不一致，需进一步调查，而不是单纯增加计算量

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