autoresearch

Autoresearch：自主迭代实验

面向任意编程任务的自主实验循环。你定义目标及其衡量方式；Agent 自主迭代——修改代码、运行实验、测量结果，并保留或丢弃变更——直到被中断。

本技能受 Karpathy 的 autoresearch 启发，将应用范围从 ML 训练推广到任何具有可衡量结果的编程任务。

---

Agent 行为规则

1. 务必在开始循环前，以交互方式引导用户完成 Setup 阶段。
2. 务必在做出任何变更前建立基线测量。
3. 务必在运行每次实验尝试前先提交（以便能够干净地回滚）。
4. 务必维护一份结果日志（TSV），记录每一次实验。
5. 务必回滚未能改善指标的变更（git reset 到上一个已知良好状态）。
6. 务必在循环开始后自主运行——绝不要暂停询问“我应该继续吗？”。
7. 切勿修改用户标记为范围之外的文件。
8. 切勿跳过测量步骤——每次实验都必须测量。
9. 切勿保留导致指标回退的变更，除非用户明确允许权衡取舍。
10. 切勿安装新依赖或更改环境，除非用户已批准。

---

阶段 1：Setup（交互式）

在开始任何实验之前，与用户一起确定以下参数。 逐项直接询问用户。不要假设或跳过任何一项。

1.1 定义目标

询问用户：

你想改进或优化什么？

示例：执行时间、内存占用、二进制文件大小、测试通过率、代码覆盖率、 API 响应延迟、吞吐量、错误率、基准分数、构建时间、打包体积、 代码行数、圈复杂度等。

将用户的回答记录为 goal。

1.2 定义指标

询问用户：

我们如何衡量成功？由哪个确切命令产生该指标？

我需要：

1. 要运行的命令（例如 dotnet test、npm run benchmark、time ./build.sh、pytest --tb=short）
2. 如何从输出中提取指标（例如正则表达式模式、特定行、JSON 字段）
3. 方向：越低越好还是越高越好？

示例：“运行 dotnet test --logger trx，统计通过的测试数。越高越好。” 示例：“运行 hyperfine './my-program'，提取平均时间。越低越好。”

记录：

• METRIC_COMMAND：要运行的命令
• METRIC_EXTRACTION：如何从输出中提取数值指标
• METRIC_DIRECTION：lower_is_better 或 higher_is_better

1.3 定义范围

询问用户：

我允许修改哪些文件或目录？

以及哪些文件是禁止修改的（只读）？

记录：

• IN_SCOPE_FILES：Agent 可以编辑的文件/目录
• OUT_OF_SCOPE_FILES：不得修改的文件/目录

1.4 定义约束

询问用户：

是否有任何我应该遵守的约束？

示例：

• 每次实验的时间预算（例如“每次运行应少于 2 分钟”）
• 不新增依赖
• 必须保持所有现有测试通过
• 不得更改公共 API
• 必须保持向后兼容
• VRAM/内存限制
• 代码复杂度限制（倾向于更简单的解决方案）

记录为 CONSTRAINTS。

1.5 定义实验预算（可选）

询问用户：

我应运行多少次实验，还是就一直运行直到你让我停止？

你可以给出一个数字（例如“尝试 20 次实验”）或“unlimited”（我会一直运行直到你中断）。

记录为 MAX_EXPERIMENTS（数字或 unlimited）。

1.6 简洁性准则

向用户告知默认的简洁性策略：

简洁性策略（默认）： 在其他条件相同的情况下，越简单越好。一个会带来丑陋复杂性的小改进并不值得。 在保持或改进指标的同时删除代码，是一个很好的结果。我会权衡复杂性成本与改进幅度。 这个策略对你适用吗，还是你想调整它？

将任何调整记录为 SIMPLICITY_POLICY。

1.7 确认设置

用一个清晰的表格向用户汇总所有参数：

参数	值
目标	...
指标命令	...
指标提取	...
方向	越低越好 / 越高 ...
范围内文件	...
范围外文件	...
约束	...
最大实验数	...
简洁性策略	...

请用户确认。在确认之前不要继续。

---

阶段 2：分支与基线

一旦用户确认：

1. 创建分支：根据今天的日期提议一个标签（例如 autoresearch/mar17）。 创建分支：git checkout -b autoresearch/<tag>。

2. 读取范围内文件：读取所有范围内的文件，以构建当前状态的完整上下文。

3. 初始化 results.tsv：在仓库根目录创建 results.tsv，包含表头行：

   experiment	commit	metric	status	description
   

   将 results.tsv 和 run.log 添加到 .git/info/exclude（如果尚未存在则追加），这样它们就保持未被跟踪，而无需修改任何已跟踪的文件。

4. 运行基线：在当前未修改的代码上执行指标命令。 将结果记录为实验 0，状态为 baseline，写入 results.tsv。

5. 向用户报告基线：

   基线已建立：[metric_name] = [value] 开始自主实验循环。

---

阶段 3：实验循环

持续运行此循环。不要停下来询问用户。一直运行直到：

• 达到 MAX_EXPERIMENTS，或者
• 用户手动中断

对于每个实验：

LOOP:
  1. THINK   - Analyze previous results and the current code.
               Generate an experiment hypothesis.
               Consider: what worked, what didn't, what hasn't been tried.

  2. EDIT    - Modify the in-scope file(s) to implement the idea.
               Keep changes focused and minimal per experiment.

  3. COMMIT  - git add + git commit with a short descriptive message.
               Format: "experiment: <short description of what changed>"

  4. RUN     - Execute the metric command.
               Redirect output to run.log so it does not flood the context window.
               Use shell-appropriate redirection:
               - Bash/Zsh: `<command> > run.log 2>&1`
               - PowerShell: `<command> *> run.log`

  5. MEASURE - Extract the metric from run.log.
               If extraction fails (crash/error), read the last 50 lines
               of run.log for the error.

  6. DECIDE  - Compare metric to the current best:
               - IMPROVED: Keep the commit. Update the "best" baseline.
                 Log status = "keep".
               - SAME OR WORSE: Revert. `git reset --hard HEAD~1`.
                 Log status = "discard".
               - CRASH: Attempt a quick fix (typo, import, simple error).
                 Amend the experiment commit (`git commit --amend`) with the fix
                 and rerun. The experiment keeps its original number.
                 If unfixable after 2 attempts, revert the entire experiment
                 (`git reset --hard HEAD~1`) and log status = "crash".

  7. LOG     - Append a row to results.tsv:
               experiment_number  commit_hash  metric_value  status  description

  8. CONTINUE - Go to step 1.

实验策略

在生成实验想法时，遵循以下优先级顺序：

1. 先摘低垂的果实：简单的参数调整、明显的低效之处。
2. 依据结果行事：如果某个方向显示出希望，就在该方向上进一步探索。
3. 平台期后转向多样化：如果最近 3-5 个实验都失败了，就尝试完全不同的方法。
4. 组合成功者：如果实验 A 和 B 各自独立地带来了改进，就尝试将它们组合起来。
5. 简化遍历：定期尝试删除代码/复杂性，看看指标是否保持。
6. 激进变更：在穷尽渐进式想法后，尝试更大的架构变更。

处理约束

• 时间预算：如果一次运行超过预期时长的 2 倍，就终止它并按崩溃处理。
• 现有测试：如果约束要求测试通过，就在之前/之后运行它们，如果测试被破坏则回滚。
• 内存/资源：监控资源使用情况，如果超过所述限制则回滚。

---

阶段 4：报告

当循环结束时（达到预算或用户中断）：

1. 打印完整的 results.tsv 作为格式化表格。
2. 汇总：
   • 运行的实验总数
   • 保留 / 丢弃 / 崩溃的实验数
   • 起始指标（基线）对比最终指标
   • 改进百分比
   • 影响最大的前 3 项变更
3. 显示保留实验的累积 git 日志： git log --oneline <start_commit>..HEAD
4. 推荐下一步：基于结果，建议人类研究者接下来可以尝试什么（对于自动化实验来说风险太高/太复杂的想法）。

---

快速参考

Results TSV 格式

制表符分隔，5 列：

experiment	commit	metric	status	description
0	a1b2c3d	0.997900	baseline	unmodified code
1	b2c3d4e	0.993200	keep	increase learning rate to 0.04
2	c3d4e5f	1.005000	discard	switch to GeLU activation
3	d4e5f6g	0.000000	crash	double model width (OOM)

Git 工作流

• 所有实验都在 autoresearch/<tag> 分支上进行
• 每个实验在运行前先提交
• 失败的实验通过 git reset --hard HEAD~1 回滚
• 成功的实验推进分支
• results.tsv 和 run.log 保持不被跟踪（加入 .git/info/exclude）

核心原则

1. 衡量一切：没有衡量就没有实验。
2. 回滚失败：分支只在有改进时推进。
3. 保持自主：绝不停下来询问。遇到困难就再深入思考。
4. 保持简单：复杂性是一种成本。要权衡它与收益。
5. 记录一切：TSV 就是研究日志。