Autoresearch

---
name: autoresearch
description: Autonomous experiment loop with evidence-driven move selection — scales from parameter tuning (directional search) to architecture innovation (structural changes), with git ledger, guard, noise-aware keep/discard, and trend-analysis stop advice. Use when the user asks to optimize a research metric, run an experiment loop, tune hyperparameters, explore architectural changes, or improve model performance iteratively.
argument-hint: <idea>
---

# Autoresearch

自主实验循环。单策略表覆盖两种尺度：**参数级微调**（改大改小/换参数）和**架构级创新**（结构性改动）。

分工：本 skill 负责**运行**循环。两种入口：
- **完整任务包**（锁定评估 + 开放文件 + program.md，可交付的自驱包）→ 缺失时
  用 `experiment-forge` 锻造；
- **最小就地契约**（主控按"裸库直接迭代"路由到本 skill 时）→ **不造包**：
  就地生成/接受最小运行契约即可开跑——评测命令 + 指标名/单位/方向 +
  循环边界（maxIterations/timeout）写进 `autoresearch.md` 即算契约成立，
  不强制 program.md 与开放文件结构。

Session files: `autoresearch.md`, `autoresearch.sh`, `autoresearch.jsonl`, `results.tsv`, `run-<N>.log`.

**契约单一来源**：results.tsv 表头、循环边界、crash/revert、Guard、min_delta、日志命名的权威定义在 `experiment-forge/references/contract.md`。本文件与契约冲突时以契约为准。

## 两种运行模式

| | 交互式（默认） | 无人值守（`claude -p` / program.md 驱动） |
|---|---|---|
| 停止建议 | 只是建议，用户决定 | 不停止；停滞 → 强制"升级"选步 |
| 硬停止 | maxIterations / 用户打断 | maxIterations / timeout |
| 问用户 | 环境选择、计划确认、停滞建议 | 不问（NEVER STOP） |

**被 research-orchestrator 调用时**：视为无人值守 —— Step 1 的续跑/新开询问与 Step 2/3 的交互闸门（AskUserQuestion 环境选择、计划确认）**全部跳过**：orchestrator 的 BOOTSTRAP 双闸门 + state 文件即上游授权，scope/预算/环境/恢复意图以 research-state.yaml 为准。环境沿用调用方已确认的选择或任务包 program.md 的约定；若没有任何已确认配置且无法交互，报 `blocked` 而不是擅自假设。orchestrator 的 Gate 已经做过确认，这里不再二次确认。交接携带 `stage / plan_version / 活跃约束 ID / eval contract 命名空间`（program.md 头部 envelope 区）：本循环服从该 envelope，不自建更苛刻的门；plan_version 变化意味着新包版本，本循环不沿用旧版本身份。

## Step 0: 前置检查

- 在 git 仓库内运行；若 `git config user.email` 为空，`git commit` 会失败 —— 先补 repo-local 身份（`git config user.name/email`，询问用户或用已有仓库的惯用身份），再进循环。
- 工作树不干净 / detached HEAD → **不再"开专支即可"**（旧规则会让实验 revert 吞掉用户未提交修改）：
  1. 记录基线 SHA：`git rev-parse HEAD`。
  2. 把用户未提交改动固化为独立 commit：`chore: wip snapshot before autoresearch (<tag>)`。实验 revert 链从此只碰 `experiment:` commit，用户工作永远在链外。
  3. **三份内容快照，各有用途、时机不同**（只存最初一份会在合法 keep 之后误判）：
     - **user-wip**：iteration 0 之前，用户原始 WIP 状态的 sha256 清单，随 wip snapshot commit 提交（如 `.autoresearch-user-wip.sha256`）。**永不作为 revert 目标**——它保护的是用户工作本身；收尾验证"用户内容未被实验污染"时对比它。
     - **iter-start**：每轮 modify 之前，对 scope 内文件做 sha256 清单（内存或 `.autoresearch/state/`，**不提交**）。它是本轮 discard 的校验对象——`git revert HEAD` 后文件内容应对齐 iter-start 快照。
     - **last-good**：最近一次 keep 之后的状态（初始 = user-wip）。真正的"安全回滚目标"：多轮 keep 后的 discard 若只 revert 一轮不够，回到 last-good 必可运行。
     清单绝不能留到实验 commit 里——revert 实验 commit 会把其中新增的文件一并删除。收尾验证用 `git show <snapshot-sha>:.autoresearch-user-wip.sha256` 对比，不只看分支名。
  4. detached HEAD → 先建工作分支再进循环。
  无人值守模式同样执行，不跳过。

## Step 1: Gather

如果 `autoresearch.md` 和 `autoresearch.jsonl` 已存在，问用户续跑还是新开。`CHANGELOG.md` 存在则先读最近条目。

否则收集（一次问完）：
- 优化目标、benchmark 命令、指标名/单位/方向
- 可改文件范围（scope）
- **改动尺度（scale）**：三选一 ——
  - `params`：只调参数（超参/配置/小 trick），锁死架构改动
  - `arch`：只做架构/方法级改动，不在参数上磨
  - `auto`（默认）：不设限，每轮由选步表按上轮结果自由决定（参数级和架构级可混用）
- **Guard 命令**（可选但推荐）：每轮必须通过的安全检查（如冒烟测试）
- **min_delta**（可选）：小于此幅度的"改进"视为噪声，触发确认跑
- maxIterations（默认 20；无人值守模式建议 50+ 或 unlimited）

未明确指定 scale 时默认 `auto` 并在确认计划时向用户说明。

## Step 2: Environment

用 `AskUserQuestion` 让用户选：Local / 新 git 分支 / venv / Docker / Modal / RunPod（详见 `docker`、`modal-compute`、`runpod-compute` skills）。没有明确答案不继续。

## Step 3: Confirm

展示完整计划（目标、命令、范围、环境、Guard、min_delta、迭代数、模式），用户确认后才启动。

## Step 4: 循环

初始化：建专支 `autoresearch/<tag>`，创建 session files，**先跑 baseline（不改任何代码）并记录为 iteration 0**。

每一轮：

### 4.1 Review（读历史，别凭记忆）
- 读 `results.tsv` 最近 10-20 行 + `git log --oneline -20`
- 上轮是 keep → `git diff HEAD~1` 看具体改动
- 明确：什么worked、什么failed、什么没试过

### 4.2 选步（策略表，证据驱动）

| 选步 | 触发 | 动作 |
|---|---|---|
| 跟进 follow | 上轮改进 | 同杠杆同方向再进一步 |
| 反转 reverse | 上轮变差 | 同杠杆反方向 |
| 换杆 switch | 上轮无变化 | 换参数/换模块 |
| 升级 escalate | plateau（连续 5 轮无 keep） | 合并历次 near-miss / 结构性改动 / 读参考文献找角度 |
| 简化 simplify | 指标持平但代码更少 | 保留，记 keep（简洁性胜利） |

这是策略指导不是状态机 —— 每轮在 jsonl 里记 `move` 类型和理由。

**尺度约束（scale）对选步表的裁剪**：
- `params`：**禁用 escalate**（不做架构改动）。plateau 时不升级，而是换杆到未试过的参数/重新扫范围；真没参数可动了就向用户报告并建议是否解除限制。
- `arch`：**跳过参数微调**，follow/reverse/switch 都作用于模块/结构层面；参数只作为新架构的配套调整。
- `auto`：全表可用，尺度切换由证据驱动。

### 4.3 Modify + Commit
- 原子改动（一个逻辑单元），只在 scope 内
- commit message 前缀 `experiment: {描述}`，记录 SHA

### 4.4 Run（防上下文爆炸）
```bash
<benchmark 命令> > run-<N>.log 2>&1   # 每迭代独立日志，禁止覆盖 / tee / 直接输出
grep "^<metric_name>:" run-<N>.log    # 只提取指标行
```
grep 为空 = 崩溃，`tail -n 50 run-<N>.log` 看栈。results.tsv 的 iteration 列与日志文件号一一对应，可对账。
**同迭代内的每次执行各用各的文件**：确认跑 `run-<N>-confirm<K>.log`（K=1,2，各自留档），第 K 次修复跑 `run-<N>-fix<K>.log`——同文件覆盖会让崩溃证据链断掉。

### 4.5 Verify（噪声防护）
- 改进幅度 < min_delta → **确认跑**：重跑 1-2 次取中位数再判定（日志写 `run-<N>-confirm.log`）
- 指标非数字/提取失败 → 记 `metric-error`，revert

### 4.6 Guard（如配置）
Guard 失败 → 无论指标如何都 revert，记 `guard-fail`。可重试一次不同实现，仍失败则换方向。

### 4.7 Decide（六态）
- **keep**：指标改进（超 min_delta）且 Guard 过 → 分支前进
- **discard**：指标变差 → `git revert HEAD --no-edit`（**不用 reset —— 失败保留在历史里供学习**）；revert 后按本轮 iter-start 快照校验文件内容确已还原
- **crash**：运行崩溃 → 语法/导包错误立即免费修复重跑（日志 `run-<N>-fix<K>.log`）；运行时错误最多自动修 3 次；修不好 revert 记 crash
- **no-op**：本轮无有效改动
- **blocked**：外部依赖失效（数据集/服务/权限）

### 4.8 Log
`results.tsv`（TAB 分隔）：`iteration timestamp commit metric delta guard status move description`
`autoresearch.jsonl`：完整 JSON 行（hypothesis、files changed、wall time、evidence pointer）

### 4.9 Checkpoint（每 5 轮）
趋势分析：keep 率、连续 discard 数、delta 递减、最大单次飞跃。
输出建议：**continue / change-strategy / stop**（交互式=建议；无人值守=change-strategy 时强制 escalate）。

### 4.10 停滞规则
连续 10 轮无 keep：
- 交互式 → 停下来向用户汇报趋势和建议
- 无人值守 → 自动执行升级选步（合并 near-miss / 激进重构 / 换 hypothesis 空间），记入 jsonl

停滞升级选步**只能在当前 envelope（约束清单、预算、eval contract）内**进行。
升级选步后仍停滞、或判断需要改动 envelope 本身（换评估命名空间、放宽局部
预算、修订代理自拟的配方默认）→ **交回外循环**：在 results/jsonl 与交接状态
中写明停滞事实、已尝试的升级、建议的修订点，结束本局部循环，由 orchestrator
走约束复审产生新版本。局部循环不得自行扩大 envelope 或无限续跑；局部 discard
只否当前候选，不否整个方向（裁决标签见 orchestrator 裁决语义分层）。

## Step 5: 收尾

循环结束（达成/停滞/上限/打断）时输出：
- 总迭代数、keep/discard/crash 分布、baseline → 最终指标、提升 %
- Top 3 最有效改动 + 最大失败教训
- 最优 commit 指针（`git log` 定位）
- CHANGELOG 追加条目；关键结论按全局约定写 provenance

## Subcommands

- `autoresearch <text>` — 启动/续跑
- `autoresearch off` — 停止，保留数据
- `autoresearch clear` — 清除状态重来