autoresearch-fleet

Autoresearch Fleet

受 karpathy/autoresearch 启发的自主研究循环。一个可变文件、一个不可变的评估框架、Git 作为状态机，以及一条“永不停止”指令。Agent 会修改代码、评估结果、保留改进、舍弃退步，并无限重复。

开放世界扩展：当 Agent 陷入停滞（连续舍弃 N 次）时，编排器会注入网络搜索提示词，突破大模型无法独自跨越的知识上限。

适用场景

• 优化单一指标（延迟、准确率、损失、分数）
• 问题有快速、确定性的评估框架
• 希望在夜间自主运行（趁你睡觉时完成 100+ 次实验）
• 搜索空间太大，无法手动探索

工作原理

┌─────────────────────────────────────────────────┐
│                 orchestrator.sh                  │
│                                                  │
│  for each iteration:                             │
│    1. Count trailing discards in results.tsv     │
│    2. If >= plateau_threshold → search prompt    │
│    3. Spawn agent (claude -p, codex exec, or pi -p)      │
│    4. Agent reads program.md, edits file, evals  │
│    5. Agent updates results.tsv, keeps/reverts   │
│    6. Check stop conditions (iter/cost/plateau)  │
│    7. Loop                                       │
└─────────────────────────────────────────────────┘

Agent 负责一切：读取文件、编辑代码、运行评估、提交、更新 results.tsv，以及在失败时还原。编排器只需循环运行、在陷入停滞时切换提示词，并强制执行停止条件。

目录结构

$FLEET_ROOT/                    # The problem directory
  fleet.json                    # Fleet config
  program.md                    # Agent instructions (you write this)
  eval.py                       # Immutable eval harness (you write this)
  solution.py                   # Mutable file (agent edits this)
  results.tsv                   # Experiment log (agent updates, git-untracked)
  orchestrator.sh               # Generated by launch.sh
  .orch-state.json              # Iteration state
  .paused                       # Sentinel (touch to pause)
  logs/
    session-iter-1.jsonl         # Per-iteration session logs
    session-iter-2.jsonl
    ...

fleet.json 架构

{
  "fleet_name": "optimize-api-latency",
  "type": "autoresearch",
  "config": {
    "model": "sonnet",
    "fallback_model": "haiku",
    "provider": "claude",
    "budget_per_iter": 2.00,
    "max_turns": 0
  },
  "problem": {
    "workdir": "/home/user/my-project",
    "eval_command": "make benchmark",
    "metric_regex": "^p99_latency_ms:\\s*([0-9.]+)",
    "metric_direction": "minimize",
    "results_file": "results.tsv",
    "program_md": "program.md"
  },
  "stop_when": {
    "max_iterations": 30,
    "cost_cap_usd": 15.0
  },
  "search": {
    "enabled": true,
    "plateau_threshold": 3
  }
}

配置字段

字段	默认值	说明
config.model	sonnet	Agent 模型
config.fallback_model	haiku	备用模型（必须与 model 不同）
config.provider	claude	claude、codex 或 pi
config.budget_per_iter	1.00	每次迭代的最高费用（美元）
config.max_turns	0	Agent 的最大轮数（0 = 不限）
problem.workdir	fleet 根目录	工作目录 — Agent 操作的仓库/目录。Fleet 根目录仅存储配置和日志。
problem.eval_command	必填	运行评估的命令（python3 eval.py、make benchmark、pytest --tb=short 等）
problem.metric_regex	（可选）	从评估输出中提取指标的正则表达式。必须有一个捕获组。如果评估只输出一个数字，则省略。
problem.metric_direction	minimize	minimize 或 maximize
problem.results_file	results.tsv	TSV 日志文件（位于工作目录中）
problem.program_md	program.md	Agent 指令文件（先在工作目录中查找，再在 Fleet 根目录中查找）
stop_when.max_iterations	50	迭代次数硬性上限
stop_when.cost_cap_usd	0	总费用上限（0 = 不限）
search.enabled	true	启用由停滞触发的网络搜索
search.plateau_threshold	3	触发搜索前连续舍弃的次数

必需输入

你需要在 Fleet 根目录中准备 3 项内容：

1. fleet.json — 将 problem.workdir 指向目标仓库，并设置 eval_command
2. program.md — Agent 指令。必须包含“永不停止”。
3. 评估命令 — 能输出指标的任意命令

fleet-root/              ← fleet.json + program.md + logs
  fleet.json
  program.md
  logs/                  ← created automatically
your-repo/               ← workdir (agent operates here)
  src/...
  results.tsv            ← created automatically

用户未指定基准测试时

如果用户提供了仓库和目标，但没有提供评估命令：

1. 检查现有基准测试：查找 Makefile 目标（make benchmark、make perf）、package.json 脚本（npm run bench、yarn test）、pytest 标记（pytest -m benchmark）或 bench/ 目录。
2. 如果找到：将其用作 eval_command。如果它没有只输出一个数字，则设置 metric_regex。
3. 如果没有找到：在工作目录中编写基准测试脚本（bench.sh 或 bench.py），该脚本应：
   • 运行相关操作（API 调用、函数调用、构建、测试套件）
   • 测量用户关心的指标（延迟、通过率、包体积等）
   • 向 stdout 输出一个数字
   • 成功时退出码为 0，崩溃时退出码非 0
4. 将 eval_command 设置为运行此脚本。

示例：用户说“优化我的 Express 应用中的 API 延迟”：

#!/usr/bin/env bash
# bench.sh — measure p99 latency
npm start &>/dev/null &
PID=$!
sleep 3
RESULT=$(curl -s -o /dev/null -w '%{time_total}' http://localhost:3000/api/health)
kill $PID 2>/dev/null
echo "$RESULT"

然后在 fleet.json 中设置 "eval_command": "bash bench.sh"。

设置

1. 创建 Fleet 根目录，其中包含 fleet.json + program.md（如果编写了 bench.sh，也一并放入）
2. bash ${AGENTS_SKILLS_DIR}/scripts/launch.sh <fleet-root>（自动执行 git init 并创建 results.tsv）
3. bash ${AGENTS_SKILLS_DIR}/scripts/status.sh <fleet-root> 以监控运行状态

可用脚本

脚本	用途
launch.sh <fleet-root> [--dry-run]	生成 orchestrator.sh，并在 tmux 中启动，同时运行监控程序
status.sh <fleet-root> [--watch]	显示迭代次数、最佳指标、results.tsv、成本和平台期
view.sh <fleet-root> <iter|latest> [--follow]	查看指定迭代的已解析会话事件
report.sh <fleet-root> [--output file.md]	运行完成后生成 Markdown 摘要
pause.sh <fleet-root>	在下一次迭代边界暂停
resume.sh <fleet-root>	恢复已暂停的 fleet
kill.sh <fleet-root>	强制停止：终止 tmux，清理孤儿进程

program.md 模板

你的 program.md 应遵循以下结构（根据你的问题调整）：

# autoresearch: <problem description>

## Setup
1. Explore the codebase to understand the architecture.
2. Read `results.tsv` for prior experiment history.
3. Run `<eval_command>` to establish a baseline.

## Rules
- Goal: <minimize|maximize> the metric.
- Make ONE change per experiment. Keep changes focused.
- <any constraints: don't touch tests, don't modify config, etc.>

## The experiment loop
LOOP FOREVER:
1. Read results.tsv for context on what's been tried.
2. Make ONE change to the codebase.
3. `git add -A && git commit -m "short description"`
4. Run: `<eval_command>`
5. Record in results.tsv (tab-separated): `commit  metric  status  description`
6. If metric improved: keep the commit.
7. If worse or crash: `git reset --hard HEAD~1` and log as discard/crash.
8. Go to step 1.

**NEVER STOP.** Run until manually interrupted.

核心设计原则（来自 Karpathy）

1. 将 Git 作为状态机 — 改进 = 前进分支；退步 = 重置
2. 固定评估 — 让所有实验具有可比性
3. 将 results.tsv 作为共享内存 — Agent 读取历史记录，避免重复失败
4. 绝不停止 — Agent 自主运行，直到被终止
5. 简洁性标准 — 微小的收益若伴随着糟糕的复杂性，就不值得

开放世界搜索（扩展功能）

当 search.enabled 为 true 时，编排器会统计 results.tsv 中连续丢弃的次数。如果该次数超过 search.plateau_threshold，下一次迭代会收到一条增强了搜索内容的提示词，要求 Agent 在编写代码前使用 WebSearch。

此方法已得到验证：在实验 009 中，搜索找到了 Winograd 的 Strassen 变体（15 次加法，而非 18 次）——这是一种不在大模型训练数据中的技术——突破了原生 autoresearch 陷入的平台期。

重要：平台期由 bash 检测（确定性），而非由大模型检测。在早期实验中，Agent 错误统计了连续丢弃次数，臆造出平台期。必须进行外部计数。

应予驳斥的合理化说辞

Agent 的说法	反驳
“Agent 应该在每次迭代中都搜索，以获得最佳结果”	达到平台期后再搜索，优于始终搜索。早期的大多数搜索都是重复的，只会增加延迟。只有在陷入停滞时（丢弃 3 次以上）才搜索。
“我应该在编排器中管理 git”	git 由 Agent 处理。它可以修正提交说明、处理边缘情况并智能地还原更改。编排器只需循环执行。
“评估框架可以重复使用相同的输入”	重复使用输入容易被钻空子。Agent 会发现基于身份的记忆化，并针对基准进行优化，而非解决问题。每次计时运行都应使用全新的带种子的输入。
“我应该用 iterative-fleet 来做这件事”	iterative-fleet 有审查器。Autoresearch 没有审查器——评估脚本本身就是质量关卡。这是不同的模式，需要不同的技能。

$ARGUMENTS