研究实验框架 是做什么的？
在长期实验工作中，出问题的很少是模型本身。真正出问题的是模型周围的空间：某个数据划分悄悄改变了、一个手动输入的数值、测试集泄漏到了训练集中、某个已失败想法的第六个变体、一个锁住了账户的轮询循环。本技能将这些规则从文本描述转移到文件、代码和钩子中，遵循工程化框架/循环/图结构。
映射到实验的三个层级
框架（空间）。
contract.json：声明、协议、门控、计算规则。冻结。CLAUDE.md：项目的简短地图，而非手册。frozen/：数据划分列表、eval.py、复制过来的基线数值。哈希锁定且只读。harness/launch.py：启动运行的唯一方式。它强制执行GPU白名单和空闲规则，并以分离模式启动作业。traces.jsonl：每个事件一行。state.json：门控的决策。lessons.md：曾付出两次修复代价的错误记录。
循环（时间）。
-
L1验证循环：
frozen/eval.py对每次运行评分。它是唯一的指标来源。 -
由代码决策的退出（
harness/gate.py）：- PASS： 候选方案以指定margin超过参考方案。
- BUDGET_EXIT： 达到最大变体数量。
- STALL_EXIT： 连续N轮无改进。
- REPRO_FAIL： 我们的基线复现与论文差距过大。
模型自身永远不会声明“完成”。
-
L4等待变化： 每个作业最后写入
runs/<id>/DONE。通过一个后台监视器等待该文件，而非重复轮询。
路径（路线）。 刻意保持小巧：
数据划分 → 冻结 → 特征 → 参考运行（基线复现） → 候选变体 → 门控 → 论文撰写。
每个箭头是一个文件合约（划分TSV文件、特征的DONE.json、运行的scores/目录）。
设置项目
- 将
template/复制到服务器上的项目中。将任务代码复制到src/下（examples/aigi/是一个完整的AI生成图像检测工作示例）。 - 根据
template/contract.example.json编写contract.json：- claim： 一句话加一个数字；
- protocol： 严格按照源论文定义；在
open_questions中列出所有未指定的细节及其选择； - gate： 参考标签、论文数值、margin、预算；
- compute： Python路径、节点/GPU白名单、空闲规则。
- 编写
paths.json（数据集根目录），并将基线数值复制到frozen/baselines.json中。通过一个脚本从PDF中解析并重新检查平均值；绝不要手动输入。 - 冻结：
python harness/freeze.py add contract.json frozen/eval.py frozen/baselines.json。 - 通过
launch.py生成数据划分，读取清单计数，然后冻结数据划分。 - 在运行Claude Code的机器上安装保护钩子：
- 将
hooks/research_guard.py复制到<project>/.claude/hooks/； - 编写
<project>/.claude/research_guard.json，将远程项目目录名称作为project_markers条目； - 将
hooks/settings.snippet.json合并到<project>/.claude/settings.json中。
- 将
操作规则
- 数值仅来自
result.json或门控输出行。 引用它们；绝不要在聊天中计算或手动输入指标。如果某个数值不在eval.py写入的文件中，那它就不存在。 - 仅通过
launch.py启动运行。 它会拒绝重复的运行ID、已更改的冻结文件以及忙碌的GPU，并记录每次运行的代码哈希。 - 一次运行，一个问题。 使用运行ID和标签说明它测试什么（
gfre_repro_s0、ml_l12-24_k256）。候选想法的变体共享门控的candidate_tag。其他任何操作，如调试或冒烟测试，使用不同的标签以免消耗预算。 - 尊重门控。
- CONTINUE意味着你可以尝试另一个变体。
- BUDGET_EXIT、STALL_EXIT和REPRO_FAIL意味着停止并向人类提供证据。不要第六次修补同一个想法。
- 冻结的协议在项目中途永不更改。 如果必须更改（数据划分中的错误、从作者处获知的协议细节），由人类编辑
FROZEN.sha256并开始新的冻结。早期结果保留在results.jsonl中，带有自己的历史记录。 - 通过单个后台监视器等待
DONE文件。 循环中的每次ssh调用都使用-o BatchMode=yes，并在退出码为255时停止。 - 每次运行后，读取
status.py输出，而非原始日志。仅在失败时打开log.txt。 - 当错误重复出现时， 在
lessons.md中添加一行，并尽可能将其转化为检查（src/中的断言、钩子规则、清单检查）。
审查者通行（在信任PASS之前）
为每个视角生成一个审查子代理。给每个子代理代码和文件，而不是你的结论：
- 数据泄漏： 训练、验证和测试文件是否有重叠？排除的模式是否真的被排除？测试标签是否到达了训练代码？
- 协议： 数据划分、测试集、阈值和指标是否与源论文和
contract.json一致？open_questions中的选择是否已披露？ - 公平比较： 参考复现是否在容忍范围内？复制的基线数值是否来自同一协议？任何重新运行的基线是否已标记？
一个审查者的价值完全取决于它改变了多少决策。每个视角返回具体的文件/行证据，或者什么都不返回。
文件
template/ 复制到新项目中
CLAUDE.md 地图（编辑标题）
contract.example.json 声明/协议/门控/计算
lessons.md
harness/ launch.py job.sh gate.py status.py freeze.py check_frozen.py trace.py common.py
frozen/eval.py 二分类检测评估器（每个测试集的阈值ACC + AP）
hooks/ research_guard.py + 示例配置 + 设置片段
examples/aigi/ AI生成图像检测：GenImage + CNNDetection数据划分，CLIP特征
缓存，GFRE风格重建检测器，GFRE表格解析器
致谢：框架/循环/图结构遵循@0xwhrrari的“Harness, Loop and Graph”（2026年11月）。