tournament-autoresearch

锦标赛式自动化研究循环

一个机器学习自动化研究循环，其中唯一的“提出假设”步骤被替换为创意锦标赛。 产物是一份实验记录；反馈信号是赢得锦标赛的变更所带来的实际 <metric> 变化量。每次迭代 <n> 个 ResearchAgent 会提出相互竞争的架构变更，评审者会对其进行点评和排名，提案者再进行完善，随后评审者选出一项变更来执行。评审者负责协调，并会自我校准：它会根据实际结果为自己的预测打分，因此能学会哪些类型的创意确实有效。实验机制（快照 → 运行 → 强制分析 → 保留／回滚）与同级的 ml-autoresearch 循环一致。

适用场景

适用于开放式机器学习实验：在投入算力前，应先评估相互竞争的创意，并且选择器应能随时间改进。你就是评审者：采用 roles/Judge.md 中的角色设定，并使用 roles/ResearchAgent.md 中的角色设定生成提案者。默认每轮安排 <n> 个提案者进行竞争，并进行一轮完善；如果创意收敛得太快，可增加 <n> 或增加轮数。不适用于运行单个预先确定的实验，也不适用于仅针对数据集进行分析探索；如果每次迭代只需提出一个未经竞争的假设，请使用同级的 ml-autoresearch 循环。

参与者与文件（均位于此文件夹中）：

• roles/Judge.md — 你的行为准则：点评、排名、决策、自我校准。
• roles/ResearchAgent.md — 提案者角色，每轮生成 <n> 次。
• rubrics/rubric.md — 评分标准（随附的默认版本；设置时会复制到工作副本）。
• schemas/idea.schema.json — 提案者返回的内容（一项提议的变更）。
• schemas/verdict.schema.json — 评审者针对每项创意记录的内容（得分、排名、决策）。

设置

以交互方式确定各项绑定。如果工作目录中存在 loop.run.yaml，则加载该文件，用一行确认其中的值，然后跳到循环部分。否则：在 Claude Code 中（AskUserQuestion 工具可用），为每项绑定推断一个可能的值，并将其作为推荐选项展示；在其他宿主环境中，则逐项以引用的纯文本提示提问。然后写入 loop.run.yaml（格式参见： examples/run.example.yaml），并在创建其他任何文件前确认这些值。

只记录一次 <host>（claude-code 或 other）——它也决定采用生成子 Agent 还是降级处理：在 Claude Code 中，于同一轮为提案者生成真正的 Agent 子 Agent；在其他宿主环境中，则以内联方式采用 ResearchAgent 角色，每次提出一个提案。

绑定	含义	默认值	推断方式
<metric>	要优化的标量指标	—	从代码／README 推断；询问优化方向
<metric_direction>	minimize 或 maximize	—	根据指标含义推断
<run_cmd> / <entrypoint>	端到端运行一次实验的命令	—	pyproject.toml／.venv／README
<editable_files>	循环可编辑的模型／配置／训练文件；绝不包括评估框架	—	查找模型和训练脚本
<sandbox_root>	快照和记录的存放位置	./sandbox	—
<iter_strategy>	branches 或 snapshots	snapshots	存在 git 时 → 提供 branches 选项
<gate> / <budget>	time（分钟）或 epochs，以及上限	epochs / —	从脚本中推断 epoch 参数
<n>	每轮参与竞争的提案者数量	3	建议使用 3——既有竞争，又不会人太多
<refine_rounds>	评审者决策前的提出 → 点评 → 完善轮数	1	—

如果 <iter_strategy> 为 branches，则创建 git checkout -b autoresearch/<run_tag>（该分支必须尚不存在）。 如果 <gate> 为 time，则写入 <sandbox_root>/run_with_timeout.sh （timeout $(( <budget> * 60 )) <entrypoint> "$@"），并在 <budget> 的 2 倍分钟数时强制终止；如果为 epochs，则在可编辑文件中限制 epoch 数量。

初始化沙盒（确认后）：

<sandbox_root>/
├── loop.run.yaml       ← resolved bindings (written now)
├── results.tsv         ← experiment ledger, header only
├── calibration.tsv     ← Judge predicted-vs-realized ledger, header only
├── judge_lessons.md    ← append-only Judge lessons (header only)
├── rubric.active.md    ← copy of rubrics/rubric.md; the Judge self-refines THIS, never the shipped one
└── iter1/              ← created at loop start

将 rubrics/rubric.md 复制到 <sandbox_root>/rubric.active.md。写入表头（参见记录）。

循环

<run_log> = 捕获某次迭代训练输出的文件（默认路径为 <sandbox_root>/iter<N>/run.log）。<editable_files> 中的所有内容都可以修改；代码必须在 <budget> 内运行并完成。简洁性标准：指标相同但代码更简单，则判定为 keep。每次迭代的锦标赛恰好产生一项更改。迭代 1 是未经修改的基线——跳过锦标赛；只需运行并分析，为第一份分析摘要提供起始内容。

复制此清单并逐项勾选，循环执行直至中断：

• 状态。 分支：git log --oneline -5。快照：确认 iter<N>/ 是新建的。
• 锦标赛（迭代 2+）——以评审者身份运行（roles/Judge.md）：提出方案（生成 <n> 个 ResearchAgent）→ 根据 rubric.active.md 进行评议与评分 → 优化 <refine_rounds>× → 选出排名最高的单项更改。
• 先创建快照/提交，再应用更改。
• 分析计划 → iter<N>/analysis/plan.md：提供交付物表，涵盖获胜方案的 prediction 以及失败方案中的有用步骤；至少有一行涉及尚未测量的维度。
• 运行（重定向输出，绝不使用 tee）→ 读取指标。
• 分析——执行 plan.md 中的每一行 → 保存到 iter<N>/results/；检查获胜方案的 prediction；撰写 3–8 条要点的摘要，并以供下一轮参考的实证锚点结尾。
• 记录 results.tsv 行，以及实际变化量和 hit 到 calibration.tsv。
• 保留或回滚（记录 discard 前先应用简洁性标准）。
• 自我校准（roles/Judge.md）：更新 judge_lessons.md，优化 rubric.active.md，更新命中率。

详细而言，每次迭代：

1. 状态。 分支：git log --oneline -5。快照：确认 iter<N>/ 是新建的。
2. 锦标赛（迭代 2+）。 以评审者身份（roles/Judge.md）：生成 <n> 个 ResearchAgent （由 <host> 决定生成或降级运行），并提供 roles/ResearchAgent.md、最新的分析摘要以及 schemas/idea.schema.json。根据 rubric.active.md 评议并为每个方案评分——先设门槛（拒绝没有可测试 prediction 的方案，不予评分）→ 按各维度逐项打 0–5 分，作为学习信号 → 通过去偏的两两比较进行排名（按两种顺序比较每一对，只保留一致的判断）。 优化 <refine_rounds>×，重新评分，然后选择唯一的 rank == 1 更改（不合并）。 将方案写入 iter<N>/ideas/，每个方案的评审结论分别写入 iter<N>/verdicts/，并将评审者 对获胜方案结果的预测记录到 calibration.tsv。
3. 创建快照/提交，再应用获胜的更改。 快照：将 <editable_files> 复制到 iter<N>/code_snapshot/，将 loop.run.yaml 复制到 iter<N>/，然后应用更改。分支：应用更改， 执行 git commit -am "<idea_id>: <short description>"。
4. 分析计划 → iter<N>/analysis/plan.md：提供交付物表，包含获胜方案的 prediction 以及失败方案中的任何有用分析步骤。至少一行必须涉及尚未测量的维度。
5. 运行（重定向到 <run_log>，绝不使用 tee）→ 读取指标（执行 grep '^<metric>:' <run_log>； 若结果为空，则执行 tail -n 50，进行一次简单修复，否则记录为 crash）。
6. 分析——必须生成真实产物。 执行 plan.md 中的每一行 → 将文件保存到 iter<N>/results/； 确认没有遗漏文件；进行解读；检查获胜方案的 prediction；撰写 3–8 条要点的分析 摘要，并以供下一轮参考的实证锚点结尾。
7. 记录。 追加 results.tsv 行（若崩溃则记为 0.000000）。根据预测，将实际变化量和 hit 追加到 calibration.tsv。
8. 保留或回滚。 指标提升 → keep，更新最佳结果。持平/变差/崩溃 → discard/crash （分支：git reset --hard HEAD~1；快照：从 code_snapshot/ 恢复）。记录 discard 前应用 简洁性标准。
9. 自我校准（roles/Judge.md）：更新 judge_lessons.md，优化 rubric.active.md （根据实际结果调整权重和锚点，并设定界限），更新选择命中率。
10. 转到第 1 步。 永不停歇。 启动后，不要暂停下来询问“要继续吗？”——除非手动中断，否则循环会一直运行。如果一时想不出新点子：扩大提案的多样性，从 results.tsv/calibration.tsv 中挖掘尚未充分探索的方向，并深入分析。

台账

<sandbox_root> 下的三个仅追加文件，均使用制表符分隔，自由文本中不得出现逗号。

results.tsv——实验台账（格式与 ml-autoresearch 相同）。表头：

iter	<metric>	status	analysis_summary	description

status ∈ {keep、discard、crash}。示例：

iter	val_acc	status	analysis_summary	description
1	0.6320	keep	baseline; grad norms even, no pathologies	baseline
2	0.6890	keep	layer-2 activations near-saturated; BN helped	iter2-a1: add BatchNorm after conv2

calibration.tsv——评审者的过往记录（预测值与实际结果对照）。表头：

iter	idea_id	grounding	impact	feasibility	pred_direction	pred_magnitude	confidence	realized_delta	hit

示例：

iter	idea_id	grounding	impact	feasibility	pred_direction	pred_magnitude	confidence	realized_delta	hit
2	iter2-a1	5	4	4	improve	+2%	high	+0.057	1

judge_lessons.md——仅追加文本，每轮迭代写 1–3 条要点：哪个维度与收益相关，哪类想法被高估或低估，以及每次完善 rubric.active.md 的原因。示例：

## iter 2
- grounding tracked the gain (BN tied to the dead-unit finding hit +0.057, as predicted).
- bumped grounding weight 0.40 → 0.45; tightened the impact anchor (impact=5 picks over-promised).

报告最佳迭代（keep 指标最高），不一定是最后一次迭代，并报告当前的选择命中率。不要跟踪 results.tsv、calibration.tsv、judge_lessons.md、rubric.active.md 和 iter*/。

约束

• 只编辑 <editable_files> 中的文件——每次编辑前都要确认，因为其他所有内容（尤其是评测框架）都是定义 <metric> 的只读真实依据。
• 每轮迭代只能做一项更改（锦标赛胜出的方案）——不得合并想法，以确保每项指标变化都能归因于单一更改。
• 没有可测试的 prediction 的想法会在评分前被拒绝；排名由去偏后的成对比较决定，绝不依据逐点评分（逐点评分仅用于校准）。
• 评审者只能编辑 rubric.active.md（工作副本），不能编辑已发布的 rubrics/rubric.md。
• 始终将训练输出重定向到 <run_log>；绝不要使用 tee（这会塞满上下文）。
• 不要安装项目中没有的包或添加依赖；辅助代码只能使用标准库。
• 不要修改评测框架，也不要暂停循环来询问接下来的方向。
• 沙盒必须自包含——不得通过 ../ 路径越界。