autoresearch-setup

自动研究设置

概述

自动研究框架让大模型能够在固定时间预算内自主迭代，解决机器学习问题。它采用双文件拆分：

• harness.py — 固定不变。 负责数据加载、训练/验证集拆分、固定的快速迭代子集以及指标。大模型绝不编辑此文件。
• train.py — 可修改。 负责模型、优化器、调度器、损失函数和训练循环。大模型可以自由重写此文件，但必须遵守框架的输入/输出契约（build_spec → ExperimentSpec、eval_forward、train_fn）。

核心原则：harness.py 负责数据和指标，且绝不编辑；train.py 按契约负责其他所有内容。 这使不同变体和会话的结果具有可比性。违反不可变框架规则的字面要求，也就是违背结果可比、诚实的原则。

工作流

1. 头脑风暴关卡（必需）

调用 superpowers:brainstorming，并在搭建框架前明确全部六项：

1. 指标 — 以及其精确计算方式（如何将预测值和目标值归约为标量）。
2. 数据 — 来源、训练/验证集拆分，以及固定的快速迭代子集。
3. 输入/输出契约 — 框架与训练代码之间的接口（eval_forward 的输出形状）。
4. 时间预算 — 每个变体的实际运行时间。
5. 计算后端 — 集群/GPU 布局（LocalMultiGPU 还是 Sbatch）。
6. 固定与可编辑边界 — 明确哪些内容属于 harness.py。

不要猜测，也不要因为时间紧迫而跳过此关卡。“跳过问题，我赶时间”并不代表可以猜测——应快速明确这六项。基于猜测构建的框架会产生无法比较、毫无价值的运行结果；这比通过关卡更慢，而不是更快。

2. 搭建框架

将 templates/ 复制到目标项目中约定的位置，然后：

• 根据关卡中明确的答案，填写 harness.py、train.py、launcher.py 和 kernels.py 中的 # TODO(autoresearch): 标记（仅在内核成熟后填写 kernels.py——留空也可以）。
• 原样复制（不做编辑）：dynamics.py。
• 填写 program.md 中的 {{placeholders}}。
• 从空文件开始 / 仅追加内容：findings.md。

3. 接入契约

阅读 reference/contracts.md，了解 eval_forward 输出形状以及 ExperimentSpec / TrainContext 字段的确切定义。不要从源码反向推断形状——契约参考文档才是权威依据（eval_forward 的形状是 Agent 最常弄错的地方）。另请参阅 reference/examples.md 中的两个完整框架示例（cis 全并行；trans 最简单次运行）。

4. 运行循环

交由项目填写好的 program.md 处理——它是自主实验循环手册。

子 Agent 模型

一次自动研究运行可能持续数小时。为了让主会话在长时间运行期间保持上下文简洁，循环分为以下部分：

• 主协调器 — 长期运行的会话。设置时读取一次 findings.md，提出假设，每轮派发一个批次子 Agent，并仅汇总各子 Agent 返回的精简摘要。它绝不读取日志文件、编写变体代码或接触 dynamics CSV。上下文每批增长约 150 个 token。
• 批次子 Agent — 每轮一个，返回后即丢弃。负责编写变体、启动运行、等待、读取结果和 dynamics，以及向 findings.md 追加内容。返回精简摘要后退出。
• dynamics 分析子 Agent — 当某个变体的 dynamics 看起来异常时，在批次子 Agent 内按需派发。保持不变。

有关简报格式和精简摘要的结构，请参阅项目的 program.md（“批次子 Agent 契约”）。

反作弊规范

警告

危险信号——立即停止。 以下任何行为都是作弊，不是进展：

• 编辑 harness.py 中的任何内容。
• 改动带有 # FIXED / # TODO(autoresearch) 标记的常量（指标、子集、 种子）。
• 在 train.py 中导入或检查验证集 / 留出集数据—— 包括读取留出目标值并据此拟合。“推导”这些值仍属于数据泄漏。
• 调用 torch.compile，或添加运行时 .autotune()。
• 编辑 launcher.py 中的保留 / 丢弃逻辑、获胜阈值或指标解析。

验证集 / 留出集唯一合法的访问渠道是 ctx.score(...)，它位于 harness 中。

常见借口及事实

借口	事实
“预算快用完了，我就把评分器阈值放宽一点”	更改指标会导致所有先前结果都无法比较。指标是实验的真实基准。
“验证集很小；我加几个训练样本来降低噪声吧”	这会泄露信号并抬高分数，而且会导致所有先前结果都无法比较——它们是在不同的训练集 / 验证集数据上测得的。噪声下限也是结果的一部分。
“我把这个‘固定’常量移到 train.py，这样就能调整它了”	一旦移动，可比性就会在不知不觉中被破坏。固定就是固定；只有开启新分支并有意编辑 harness.py 才能更改它。
“我看看验证集，挑选要加权的样本”	这是验证集泄漏。eval_forward 只能通过 harness 评分器查看验证集。
“torch.compile 能让它符合预算要求”	追踪和自动调优每次运行都会消耗预算；禁止这样做。请使用预先调优的 kernels.py。
“我没有复制留出目标——我是从目标推导出函数的，所以它能泛化”	读取留出目标值并据此拟合就是数据泄漏，无论是推导还是复制。留出集只能通过 harness 评分器访问。能“拟合留出集关系”的模型是在记忆测试集，而不是学习任务。

快速参考

文件	作用	可编辑？
harness.py	固定——数据 + 指标 + 契约	否
train.py	可修改的训练循环	是
launcher.py	固定——调度、保留 / 丢弃、results.tsv	否
dynamics.py	双层动态记录器	否（原样复制）
program.md	实验循环手册	由项目填写占位符
findings.md	持续更新的跨会话发现日志	仅追加
kernels.py	仅包含预先调优的内核	是（仅可增补）

交叉参考

• superpowers:brainstorming — 必需的关卡（工作流步骤 1）。
• helion-jagged-and-autotuning — 使用预先调优的内核；绝不进行运行时自动调优。
• pixi — 运行 harness 的环境设置。

常见错误

错误	修正方法
不经过关卡就猜测指标 / 划分 / 预算	先运行 superpowers:brainstorming；解决全部六项
eval_forward 形状不匹配（导致指标无法静默比较）	阅读 reference/contracts.md；返回 harness 评分器指标所使用的数据
只记录最终数值	使用 dynamics.py 双层记录器（快照头部 + 宽表主体）
编辑 launcher.py 来制造胜利	Launcher 是固定的；放宽保留 / 丢弃条件或指标解析就是作弊
在 train.py 中“推导”留出目标	数据泄漏。只能通过 ctx.score(...) 访问留出集
在主编排循环中读取日志文件或 dynamics CSV	委派给批处理子 Agent；主上下文只能看到精简摘要
批处理子 Agent 在摘要中返回原始日志摘录	摘要必须符合精简格式——每个变体一行，外加每个变体一行动态信息，不得包含其他内容