test-research-code

测试研究代码

将研究代码工件打磨到工件评审委员会（ACM AE、USENIX/OSDI/SOSP、SIGMOD ARI、ETAPS、NeurIPS 代码发布）所期望的状态：它能够运行，具有足够的确定性，能在容差范围内复现；其环境已记录，陌生人也能按照 README 复现论文的主要结果。这是代码侧与 PDF 的 preflight-check 相对应的步骤。

这不是通用软件 TDD。目标是打造一条可靠的端到端“能否运行并大致复现”路径，而不是穷尽式的单元测试覆盖。一个能在小型输入上运行真实流程的重点冒烟测试，胜过 100 个模拟单元测试。

适用场景

• 代码目前**“只能在我的机器上运行”**，需要让陌生人也能运行——没有固定的环境、没有随机种子、没有明显的入口点，也没有基本正确性测试。
• 作者要求添加冒烟测试／基本正确性测试、固定随机种子／确保确定性，或在打包或移交代码前记录／固定环境。
• 工件评审截止日期临近，而代码尚未达到可测试状态——先完成这项工程工作，再转交给下面的相关技能。

范围边界（避免重叠）。此技能负责的是工程步骤——测试、随机种子、环境记录。它不负责：

• 打包、徽章分类、归档 DOI、匿名化 → prepare-artifacts。
• 生成的数值是否与论文表格一致 → verify-results。
• 常规代码清理／重构 → refactor-research-code。 如果请求是“让我的代码为工件评审做好准备”，就从这里着手解决可运行性问题，然后再移交；不要重复他们已完成的工作。

输入

• 研究代码目录的路径（仓库，或包含训练／评估脚本等内容的子目录）。
• 可选：评审是否为双盲（这样记录的环境／新增的测试就不会泄露作者身份）。
• 可选：用于确定定位的 .paper-memory/profile.yml（system／dataset 类贡献更需要可复用、经过充分测试的工件；empirical 类贡献则更需要确定性地重新运行）。

流程

1. **先阅读记忆。**阅读 .paper-memory/lessons.md（如果存在，也阅读 profile.yml），避免再次指出作者已经修复的问题，并优先关注他们的 recurring 习惯。参见 paper-memory-convention.md。

2. **确认范围。**如果未说明，请询问评审是否为双盲，确保新增内容——记录的环境、测试夹具、笔记本——不会泄露身份。如果作者的目标是特定的工件评审类别，请注意，必须根据会议当前的 Call for Artifacts 重新核实徽章选项和单独的工件截止日期，因为这些内容每年都会因会议而异；但这项确认由 prepare-artifacts 负责。这里仅需让代码可测试；不要重复说明徽章分类。背景信息（徽章类别、2020 年后 Reproduced／Replicated 的调整）可参阅 references/artifact-standards.md，用于了解情况，而非作为当前规则的依据。

3. **审查仓库（确定性检查）。**运行随附脚本——不要手动使用 grep：

   python3 scripts/repro_check.py <code-dir>          # text report
   python3 scripts/repro_check.py <code-dir> --json   # machine-readable
   

   脚本会将六项要素——README、ENV（依赖项，是否固定？）、SEED、ENTRYPOINT、DATA、RESULTS_CMD——分别报告为 OK／WARN／MISSING，并说明是否存在测试。这是后续工作所依据的外部、可衡量信号；不要用自己对“看起来可复现”的判断取而代之。退出码：0 表示无问题，1 表示缺少必要项，2 表示用法错误。

4. 按以下顺序填补缺口（每项均对应一条脚本检查结果，以及 references/repro-essentials.md 中的内容）：

   • ENV — 编写或修复依赖清单，并固定精确版本。使用 pip freeze > requirements.txt、environment.yml，或固定基础镜像的 Dockerfile。未固定版本的依赖是评估人员无法重新构建的最常见原因。记录生成结果所用的操作系统、CUDA 和硬件。
   • SEED — 为所有涉及的随机数生成器设置并记录种子（random、numpy、框架——torch.manual_seed + torch.use_deterministic_algorithms(True)、PYTHONHASHSEED）。如实说明剩余的非确定性（GPU 原子操作、数据加载器工作进程），不要隐瞒。
   • ENTRYPOINT — 提供一个显而易见的命令（make reproduce、run.sh、python -m pkg、__main__ 守卫），从头到尾运行整个流水线。
   • SMOKE/SANITY TEST — 添加一个最小测试，使用极小或合成输入运行真实流水线，并断言其运行完成且输出形状或数值合理。参见 references/smoke-tests.md 中的模板。在此处，一个端到端冒烟测试胜过广泛的单元测试覆盖。
   • DATA — 提供获取输入数据的精确说明（下载脚本，或“无外部数据”），并尽可能注明来源和校验和。
   • RESULTS_CMD — 在 README 中加入一份简短的结果表，并为每项结果列出生成该结果的确切命令（ML Code Completeness 项）。注明预期运行时间，并说明数值应在容差范围内一致，而非逐位完全相同。

5. 重新运行 repro_check.py，直到所有必要项均为 OK（或有意标记为 WARN）。设定明确的停止条件——所有必要项都不为 MISSING，或最多进行约 3 轮修复——不要无限期地反复打磨。

6. 托管与匿名化（提供建议，切勿代为处理）。

   • **归档托管（Zenodo/SWHID、版本 DOI 与概念 DOI、USENIX 禁止仅提供 GitHub 链接的规则）**由 prepare-artifacts 负责。不要在此处处理；代码可测试后，标记“下一步：通过 prepare-artifacts 打包并存档”，然后停止。
   • 双盲评审：如果仓库采用双盲评审，你添加的任何内容（环境文件、测试样例、notebook）都不得重新暴露身份。匿名化本身应交由 anonymize-paper / prepare-artifacts 处理；标记此事项，不要在此处敷衍处理。

7. 将报告和检查清单写入 paper-workspace/submission/artifact-repro-checklist.md，并追加到 paper-workspace/INDEX.md。先说明已完成的工作，再列出按优先级排序的缺口；每项缺口都应对应一条 repro_check.py 检查结果和一项具体修复措施。

输出

一份便于审阅的 paper-workspace/submission/artifact-repro-checklist.md：其中包含审计表（六项必要项及其 OK/WARN/MISSING 状态）、你添加或建议的冒烟测试、运行过的环境信息采集命令、固定的随机种子，以及数据和复现说明；还应列出实际写入作者仓库的任何文件（如 tests/test_smoke.py、固定版本的 requirements.txt、Makefile/run.sh）。每项缺口都应注明其来源脚本检查结果。检查清单最后以一行说明移交给 prepare-artifacts（打包/徽章/DOI）和 verify-results（核对数值）——不得重复它们的工作。

按学科调整

本指南面向 CS 的 artifact 评审轨道（ACM/USENIX/SIGMOD/ML）。对于其他领域，请将环境信息采集替换为你所用技术栈的锁定文件（R 使用 renv.lock，Julia 使用 Manifest.toml，生物信息学使用 conda），并将随机种子和测试惯例替换为相应框架的做法。徽章与会议的对应关系由 prepare-artifacts 负责，而非本技能负责——在此处，“可测试 + 确定性 + 已采集环境信息”适用于所有领域。

防护措施

• 绝不要运行任何破坏性操作，也绝不要未经作者许可运行不受信任的实验代码来“证明”它有效。 repro_check.py 按设计是静态且只读的（不会执行代码，也不会联网）。是否端到端运行该产物由作者决定，而且可能需要沙箱/GPU。
• 清单通过是必要条件，但不是充分条件。 不要告诉作者该产物“会获得徽章”或“可复现”——这些是委员会根据当前 CFA 作出的结论；文中所有“复现”都表示在不改变论文主张的容差范围内，绝非逐位精确复现。请使用“必要但不充分”的表述。
• 不要捏造结果或命令。 复现命令必须是仓库中实际存在的命令；如果无法运行，请如实说明。
• 注意匿名化：双盲评审期间，绝不要通过仓库、提交历史或 Notebook 元数据泄露作者身份。
• 它会检查、搭建脚手架并作出说明；但不会代表作者提交产物或申请 DOI。
• references/ 文件应保持在一层目录内；此文件不得超过 500 行。

记忆

使用共享的 .paper-memory/ 约定（完整规范：paper-memory-convention.md）。

• **开始时：**阅读 lessons.md，跳过已修复的问题，并优先指出 recurring 习惯（例如“你经常提交未锁定版本的依赖——先检查这一点”）；阅读 profile.yml，了解贡献类型，以便确定正确的徽章目标。
• **结束时：**针对每个反复出现的问题，使用 reflect-and-improve 的 reflect_log.py，按规范格式追加一条带日期的记录：

  python3 ../reflect-and-improve/scripts/reflect_log.py append \
      --memory .paper-memory --skill test-research-code --scope recurring \
      --issue "experiment scripts ship without seed setting" \
      --rec "set random/numpy/framework seeds + PYTHONHASHSEED every artifact"
  

• 按需创建 .paper-memory/；询问是否将其加入 .gitignore；仅保存在本地，绝不上传。