论文复现Skill强调“仓库默认分支和论文使用的提交不是同一个版本”“论文、代码、数据、模型和评测脚本之间无法建立对应关系”——Codex在复现时到底该先建立Claim-to-artifact映射再跑，还是先跑通再说，顺序错了会埋什么雷？

摘要：论文复现中“先跑通”与“先建映射”的顺序之争，表面是工程节奏问题，实质是证据链构建与试错成本的优先级问题。本文以“仓库默认分支与论文提交不一致”“论文、代码、数据、模型、评测脚本无法建立对应关系”两类高频故障为切口，提出以 Claim-to-artifact 映射为前置约束的复现范式，系统剖析版本漂移、数据泄漏、评测错配三类“暗雷”的成因、检测路径与止损策略，并给出可落地的六阶段操作流程、映射表模板与验收清单。核心判断是：先跑通只能验证“能跑”，先建映射才能验证“跑的是不是论文那件事”。

目录

一、导语：一次“跑通”背后的三重错位

在代码智能体（coding agent）参与论文复现的场景里，最常见的开场白是“我先把仓库 clone 下来，装好依赖，跑通训练脚本再说”。这句话听起来务实，却隐含一个未经检验的假设：仓库当前默认分支上的代码，就是论文作者做实验时用的那份代码。这个假设在相当比例的公开仓库中并不成立。论文投稿到发表往往跨越六到十八个月，期间仓库可能经历重构、依赖升级、默认分支切换、实验脚本清理，甚至作者本人已经转向下一个课题。等到复现者拿到仓库时，默认分支的 HEAD 与论文附录里那句“code available at ...”所指向的提交，可能已经相隔数百个 commit。

第二重错位发生在论文与代码之间。论文正文描述的是方法，附录描述的是超参数，代码实现的是工程妥协后的版本，三者之间的差异往往不会被显式记录。第三重错位发生在数据、模型与评测脚本之间：训练集版本、预处理脚本、checkpoint 命名、评测指标实现，任何一环对不上，最终数字就无法归因。这三重错位叠加，使得“跑通”成为一个极具欺骗性的信号——进程退出码为 0，日志里有 loss 下降，甚至能复现出一个接近论文的数字，但你无法回答一个更基本的问题：你跑通的，是不是论文里那件事？

笔者认为，复现的方法论分歧可以浓缩为一个顺序问题：是先建立 Claim-to-artifact 映射（把论文中的每一条主张绑定到具体的代码提交、数据版本、模型文件与评测脚本），还是先让流水线跑起来、再回头补映射。前者慢、重、前期看不到产出；后者快、轻、能迅速给出“可运行”的正反馈。工程直觉倾向于后者，但复现的认识论要求前者。本文的任务，就是把这一直觉冲突拆解为可分析的因果结构，并给出可执行的折中路径。

二、问题定义：复现失败的四种形态与 Claim-to-artifact 映射的准确含义

2.1 复现失败的四种形态

讨论顺序之前，先把“复现失败”说清楚。文献中常把可复现性（reproducibility）与可重复性（repeatability）混用，本文采用较为通行的区分：可重复性指同一团队在同一环境下重复实验得到一致结果；可复现性指独立团队依据论文与公开材料得到与原文一致或可解释的结论。在此基础上，复现失败可细分为四种形态，它们的诊断成本依次上升：

本文评述：四种形态中，前两种是工程问题，后两种是认识论问题。工程问题可以靠“先跑通”快速暴露，认识论问题却恰恰会被“先跑通”掩盖——因为一旦流水线跑出接近的数字，复现者就获得了心理上的完成感，补映射的动力随之下降。这正是顺序问题的要害所在。

2.2 Claim-to-artifact 映射的准确定义

Claim-to-artifact 映射，指把论文中以自然语言陈述的每一条可检验主张（claim），显式绑定到支撑该主张的最小产物集合（artifact set）。这里的“主张”不是泛指，而是指带有量化断言或定性结论的句子，例如“在 ImageNet 上 top-1 准确率提升 1.2 个百分点”“消融实验表明模块 B 贡献主要增益”“在低资源设定下 F1 不低于基线”。产物集合通常包含五类：代码提交（commit hash）、数据版本（数据集名称加校验和或版本号）、模型权重（checkpoint 标识）、评测脚本（含指标实现）、运行配置（超参数与环境锁定文件）。

映射的粒度需要权衡。过粗的映射（“整篇论文对应整个仓库”）等于没有映射；过细的映射（“每个张量对应一行代码”）维护成本不可承受。笔者认为，合理的粒度是“一条主张对应一个可独立重跑的评测单元”，即给定该单元声明的代码提交、数据切片、权重与脚本，应当能在无人干预下复算出该主张对应的数字。这个定义同时给出了验收标准：映射是否合格，取决于它能否支撑一次独立的、可审计的重算。

claim_id | claim_text | metric | split | commit | data_version | ckpt_id | eval_script | config_hash | expected | tolerance | status

三、原理剖析：版本漂移、数据泄漏与评测错配的因果链

3.1 版本漂移：默认分支是一个移动靶

Git 的默认分支在语义上只是“克隆时检出的分支”，并不承诺与任何论文版本对应。作者在论文接收后合并重构、升级 PyTorch 版本、把实验脚本移入 legacy 目录，都会让默认分支 HEAD 偏离论文提交。更隐蔽的情形是作者在投稿后继续在同一分支上迭代，论文数字来自某个中间提交，而该提交既没有打 tag，也没有出现在 README 的版本说明里。复现者若直接 clone 默认分支，拿到的是一份“作者现在觉得更好”的代码，而非“论文当时用的”代码。

版本漂移的后果不是简单的“跑不起来”，而是“跑起来但语义变了”。例如依赖升级可能改变默认的数值精度、优化器实现细节、数据加载的 shuffle 行为，这些变化不会报错，只会让结果缓慢偏移。本文评述：版本漂移的危险性在于它的静默性——它不产生异常，只产生偏差，而偏差又容易被归因于“随机性”或“硬件差异”，从而逃过诊断。

检测版本漂移的最低成本手段，是在 clone 之后立即执行三项检查：其一，读取论文附录或 README 中是否给出 commit hash 或 release tag；其二，用 git log --oneline 查看默认分支在论文发表时间点前后的提交记录，寻找“camera-ready”“release”“paper version”一类提交信息；其三，检查仓库是否包含 requirements.txt、environment.yml 或 lock 文件，并确认其修改时间与论文时间线的相对关系。三项检查都不通过时，应默认“当前 HEAD 不是论文版本”，转入提交考古。

3.2 数据泄漏：指标虚高的结构性来源

数据泄漏指训练阶段以任何形式接触到了评测阶段应当未见的信息。在复现语境下，泄漏往往不是复现者引入的，而是原仓库的预处理脚本、数据划分文件或评测脚本本身携带的。常见形态包括：划分文件在打乱后未固定随机种子，导致每次运行划分不同，若评测集与训练集存在重叠样本则指标虚高；预处理阶段使用了全量数据的统计量（均值、方差、词表、归一化参数）做标准化，使评测集信息渗入训练；评测脚本在计算指标前对预测做了基于全量标签的后处理。

这类问题的检测不能靠“跑通”，只能靠审读。可操作的检查点有三：其一，确认划分文件是否随仓库发布且带校验和，若划分在运行时生成，必须确认随机种子被固定并记录；其二，检查预处理脚本中是否存在对“全部数据”的 fit 操作，正确做法是仅在训练集上 fit、在评测集上 transform；其三，检查评测脚本是否读取了标签之外的元信息。本文评述：数据泄漏是四类暗雷中最难在事后补救的一类，因为一旦指标已经“好看”，复现者很难说服自己回头质疑数据管线。

3.3 评测错配：指标同名不同义

评测错配指复现者使用的指标实现与论文使用的实现不一致，导致数字不可比。典型例子包括：F1 的宏平均与微平均之别、BLEU 的 tokenization 与平滑方式之别、目标检测中 mAP 的 IoU 阈值序列与插值方式之别、生成任务中采样温度与 top-p 设置之别。这些差异在论文正文中往往只用一句“we report F1”带过，具体实现藏在代码或引用的工具库里。

评测错配的隐蔽性来自“同名”。复现者看到论文写 F1，自己也算 F1，数字差两个点，第一反应是模型或训练有问题，于是花大量时间调超参数，而真正的问题在指标实现。笔者认为，评测脚本应当被视为与模型同等重要的一等产物，在映射表中单独列字段，并在复现报告中记录其来源（自研、引用库、作者提供）与版本。

四、顺序之争：先跑通与先建映射的收益—风险对照

把两种顺序放到同一张表里对照，可以更清楚地看到它们各自优化的目标不同。先跑通优化的是“最短时间获得可运行信号”，先建映射优化的是“最短时间获得可归因证据”。两者并非绝对对立，但在资源有限时确实存在优先级冲突。

本文评述：这张表容易被误读为“先建映射全面占优”，其实不然。先建映射在环境问题上的暴露速度明显更慢，而环境问题恰恰是复现者最容易在早期获得确定收益的地方。更合理的读法是：两种顺序优化的是不同阶段的成本，先跑通把成本推迟到归因阶段，先建映射把成本提前到准备阶段。选择哪一种，取决于复现的目标是“快速验证可行性”还是“产出可引用的复现结论”。

由此可以给出一个折中判据：如果复现的目的是判断“这篇论文的方法是否值得跟进”，先跑通是合理的，因为此时容忍模糊性；如果复现的目的是“在自有数据上复用该方法”或“对外报告复现结果”，则必须先建映射，因为任何未归因的数字都会在后续被反复质疑。顺序错了埋下的雷，本质上都是“把准备阶段的成本转移到了归因阶段，而后者更贵”。

五、操作路径：六阶段复现流程与映射表模板

5.1 六阶段流程

下面给出一条把“先建映射”落到工程节奏里的路径。它并不要求复现者在第一天就完成全部映射，而是要求映射的骨架先于第一次完整训练建立。这样既保留了先跑通的正反馈，又避免了归因阶段的返工。

这六个阶段的关键约束是：阶段二与阶段三的产物（候选提交清单、产物盘点表）必须在阶段四之前完成初稿。阶段四允许粗糙，但不允许在没有映射骨架的情况下直接进入全量训练。本文评述：这一约束把“先建映射”从一种理想化的要求，转化为一个有时限的、可交付的工程动作，从而与“先跑通”的节奏兼容。

5.2 映射表模板与字段说明

映射表是整条流程的载体。下表给出一个可直接使用的模板，字段含义在表后说明。实际使用时建议以 CSV 或 YAML 维护，便于版本控制与脚本校验。

字段设计上有两个细节值得强调。其一，config_hash 应覆盖超参数文件与依赖锁定文件，任何一项变动都应导致哈希变化，从而在映射表层面暴露“配置漂移”。其二，status 的取值应区分 gap（产物缺失）与 drift（产物存在但版本不符），二者的处理路径不同：gap 需要向作者或社区索取，drift 需要提交考古。

5.3 自动化辅助：让映射可校验

映射表若只靠人工维护，很快会与仓库状态脱节。可行的做法是写一个轻量校验脚本，在每次运行前检查：commit 是否与映射表一致、数据校验和是否匹配、评测脚本哈希是否变化、依赖锁定文件是否被修改。任一项不一致即中止运行并输出差异报告。这类脚本的复杂度不高，但能把“静默漂移”转化为“显式失败”，是整条流程中性价比最高的工程投入。

对于希望进一步自动化的团队，可以把映射表接入持续集成：每次提交触发一次最小可跑单元的复算，把实测值与 expected 的差距写入报告。这样映射表就从静态文档变成了活的验收标准。相关工具链的搭建思路可参考 Pro Git 中文版 中关于标签与提交引用的章节，以及 DVC 官方文档 中数据版本管理的部分。

六、案例与数据：从公开复现报告看暗雷的分布

公开的复现研究为暗雷分布提供了可引用的经验证据。机器学习复现性领域的一项系统性工作（Pineau 等，2021，发表于 JMLR）组织了多组独立团队对同一批论文进行复现，报告显示相当比例的论文在独立复现下无法达到原文报告的性能区间，且失败原因中数据划分与评测实现差异占据显著位置。本文评述：该研究的价值不在于给出一个精确的失败率，而在于证明“原文数字”与“可复现数字”之间存在系统性间隙，而这一间隙恰恰是映射缺失的产物。

在自然语言处理方向，复现性挑战赛（ReproNLP）的系列报告提供了更细粒度的观察。其共享任务要求参与团队在限定资源下复现指定论文，并提交复现报告。多届报告的共同发现是：代码仓库的可用性与论文版本的一致性，是决定复现成败的首要因素；其次是评测脚本的可获得性。这与本文强调的“版本漂移”与“评测错配”两条因果链相互印证。

在代码智能体评测方向，近年出现的若干基准（如 SWE-bench 系列）把“在真实仓库上完成指定修改并通过测试”作为任务形式。这类基准的设计本身就在回应本文的问题：任务描述必须绑定到特定提交，测试必须绑定到特定环境，否则评分不可比。本文评述：基准设计的这一转向说明，工业界已经认识到“可运行”不等于“可归因”，而映射正是把二者连接起来的桥梁。相关任务形式与评测协议可参考 SWE-bench 项目主页 与 Papers with Code 的复现条目。

需要说明的是，上述研究的具体数值随任务与论文集合而变化，本文不引用未经核实的精确百分比，只引用其定性结论。若读者需要定量数据，应以原始报告为准，并注意不同届次的任务设定不可直接比较。

七、对比与局限：映射优先范式的边界条件

映射优先范式并非普适。它的第一个边界是论文未公开足够产物。当作者只发布论文不发布代码，或只发布推理代码不发布训练代码时，映射表的大量字段只能填 gap，此时强行推进映射会陷入无休止的考古。合理的做法是降级为“部分映射”：只对可获得的产物建立映射，并在报告中显式声明不可复现的主张清单。这比假装复现更诚实，也更有用。

第二个边界是复现目标本身是探索性的。如果复现者的目的只是快速判断某个方法是否值得借鉴，那么建立完整映射的投入产出比不高。此时可以采用“轻量映射”：只记录 commit、数据版本与评测脚本三项，足以支撑初步判断，待方法确认值得跟进后再补全。本文评述：范式的适用性取决于决策的可逆性——可逆决策用轻量映射，不可逆决策用完整映射。

第三个边界是计算资源的约束。完整映射要求逐条主张重算，在大模型场景下成本可能高到不可承受。折中方案是分层重算：对核心主张做全量重算，对次要主张做小样本近似重算，并在映射表中标注重算方式与置信度。这样既控制了成本，又保留了可审计性。

与“先跑通”相比，映射优先范式的局限在于前期反馈慢、对复现者的文献阅读能力要求高、对仓库质量敏感。与“先跑通”相比，它的优势在于归因清晰、返工少、结论可对外引用。两者不是替代关系，而是适用于不同决策场景的工具。笔者认为，成熟的做法是把二者编排进同一流程：用先跑通获取环境可行性信号，用映射骨架约束后续所有重算，二者在时间上交错而非对立。

八、结论与展望：把复现从“跑通”升级为“可审计”

回到开头的问题：Codex 在复现时到底该先建立 Claim-to-artifact 映射再跑，还是先跑通再说？本文的结论是分层的。若复现的目的是快速筛选，先跑通可以接受，但必须同时记录 commit、数据版本与评测脚本三项最小映射，否则后续无法归因。若复现的目的是产出可引用的结论或在自有数据上复用方法，则必须先建立映射骨架再进入全量训练，因为顺序错了埋下的雷——版本漂移、数据泄漏、评测错配——都会在归因阶段以数倍成本爆发。

顺序错了埋什么雷，可以概括为三类：其一，归因雷，数字对不上时无法定位是配置、数据、脚本还是代码的问题，只能全链路重查；其二，复用雷，把在错误版本上跑出的结论迁移到自有数据，错误被放大；其三，信誉雷，对外报告的复现结果在第三方重算时无法成立，损害个人或团队的技术信誉。三类雷的共同特征是延迟爆发，而延迟正是“先跑通”最擅长的伪装。

展望未来，随着代码智能体在科研工作流中的渗透，复现的自动化程度会提高，但自动化的前提是结构化。映射表正是把论文的非结构化叙述转化为结构化约束的中间层。没有这一层，智能体只能做“能跑”的验证；有了这一层，智能体才能做“跑的是不是论文那件事”的验证。本文评述：复现的终局不是让机器替人跑实验，而是让机器替人维护证据链，人则专注于判断证据是否充分。

主要参考文献

文章声明

本文内容仅为作者学习、思考、经验、笔记的总结，仅供技术交流与参考。文中观点仅代表笔者个人思辨，不构成任何学术建议、商业建议或专业建议。所有数据来源已标注，引用时请以原始文献为准。