autoresearch · diff
git:20260930.9b33ccf to git:20261003.0767d99
12 added, 5 removed. Audit A to A.
---
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` 锻造。
- Session files: `autoresearch.md`, `autoresearch.sh`, `autoresearch.jsonl`, `results.tsv`.
+ 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 2/3 的交互闸门（AskUserQuestion 环境选择、计划确认）**跳过**。环境沿用调用方已确认的选择或任务包 program.md 的约定；若没有任何已确认配置且无法交互，报 `blocked` 而不是擅自假设。orchestrator 的 Gate 已经做过确认，这里不再二次确认。
## Step 0: 前置检查
- 在 git 仓库内运行；若 `git config user.email` 为空，`git commit` 会失败 —— 先补 repo-local 身份（`git config user.name/email`，询问用户或用已有仓库的惯用身份），再进循环。
- - 工作树不干净 / detached HEAD → 提示用户后再继续（无人值守模式：开专支即可，不阻塞）。
+ - 工作树不干净 / detached HEAD → **不再"开专支即可"**（旧规则会让实验 revert 吞掉用户未提交修改）：
+ 1. 记录基线 SHA：`git rev-parse HEAD`。
+ 2. 把用户未提交改动固化为独立 commit：`chore: wip snapshot before autoresearch (<tag>)`。实验 revert 链从此只碰 `experiment:` commit，用户工作永远在链外。
+ 3. 内容级快照：对 scope 内文件做 `sha256sum` 清单，**作为 wip snapshot commit 的一部分提交**（如 `.autoresearch-baseline.sha256`）。清单绝不能留到实验 commit 里——revert 实验 commit 会把其中新增的文件一并删除。收尾/回滚后用 `git show <snapshot-sha>:.autoresearch-baseline.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.log 2>&1 # 禁止 tee / 直接输出
- grep "^<metric_name>:" run.log # 只提取指标行
+ <benchmark 命令> > run-<N>.log 2>&1 # 每迭代独立日志，禁止覆盖 / tee / 直接输出
+ grep "^<metric_name>:" run-<N>.log # 只提取指标行
```
- grep 为空 = 崩溃，`tail -n 50 run.log` 看栈。
+ grep 为空 = 崩溃，`tail -n 50 run-<N>.log` 看栈。results.tsv 的 iteration 列与日志文件号一一对应，可对账。
### 4.5 Verify（噪声防护）
- 改进幅度 < min_delta → **确认跑**：重跑 1-2 次取中位数再判定
- 指标非数字/提取失败 → 记 `metric-error`，revert
### 4.6 Guard（如配置）
Guard 失败 → 无论指标如何都 revert，记 `guard-fail`。可重试一次不同实现，仍失败则换方向。
### 4.7 Decide（六态）
- **keep**：指标改进（超 min_delta）且 Guard 过 → 分支前进
- **discard**：指标变差 → `git revert HEAD --no-edit`（**不用 reset —— 失败保留在历史里供学习**）
- **crash**：运行崩溃 → 语法/导包错误立即免费修复重跑；运行时错误最多自动修 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
## Step 5: 收尾
循环结束（达成/停滞/上限/打断）时输出：
- 总迭代数、keep/discard/crash 分布、baseline → 最终指标、提升 %
- Top 3 最有效改动 + 最大失败教训
- 最优 commit 指针（`git log` 定位）
- CHANGELOG 追加条目；关键结论按全局约定写 provenance
## Subcommands
- `autoresearch <text>` — 启动/续跑
- `autoresearch off` — 停止，保留数据
- `autoresearch clear` — 清除状态重来