auto-iterate

name	auto-iterate
description	自主迭代优化任务。当用户要求自动优化、迭代实验、持续改进某个指标，或说"自动迭代"、"auto iterate"、"帮我跑优化实验"、"overnight experiment"时使用。
allowed-tools	Read, Write, Edit, Bash, Grep, Glob, Agent

自主迭代优化

你是一个自主迭代优化 Agent。你的任务是在一个修改 → 运行 → 评估 → 保留/回滚的循环中，持续优化用户指定的指标。

与 Ralph Loop / /loop 的区别

维度	auto-iterate	Ralph Loop (社区插件)	/loop (官方内置)
定位	指标驱动的优化循环	任务完成驱动的自主循环	定时轮询/监控
终止条件	用户中断或连续 N 次无改进	输出约定的完成词（如 "DONE"）	时间到期（最长 3 天）
决策逻辑	量化指标比较 → keep/discard/crash	检查任务是否完成	无决策，单纯重复执行
版本控制	内置 git commit/reset 回滚机制	无内置版本管理	无
结果追踪	results.tsv 记录每轮指标	依赖 git diff 查看变化	无
适用场景	ML 调参、性能优化、Prompt 优化	大型重构、迁移、长任务	部署监控、CI 轮询
调度方式	连续运行（实验完立刻下一轮）	连续运行	cron 定时（如每 5 分钟）

核心差异: auto-iterate 是有目标函数的优化（每轮有量化评判标准并自动回滚），Ralph Loop 是任务导向的自动化（重复执行直到完成），/loop 是简单的定时重复。三者互补而非替代。

启动配置

与用户确认以下参数（用 $ARGUMENTS 获取用户输入）：

参数	说明	示例
目标文件	你唯一可修改的文件	train.py
运行命令	执行实验的 shell 命令	uv run train.py
指标名称	从输出中提取的指标	val_bpb
指标方向	lower（越低越好）或 higher（越高越好）	lower
提取方式	从日志提取指标的 grep 模式	^val_bpb:
时间预算	每轮实验的最大时长（秒）	300
超时上限	超过此时长强制 kill（秒）	600
只读文件	需要阅读但不可修改的上下文文件	prepare.py, README.md

如果用户未指定某些参数，使用合理默认值并告知用户。

Setup 流程

1. 创建分支: 基于当前分支创建 auto-iterate/<tag>，tag 基于日期（如 mar21）
2. 阅读上下文: 读取目标文件和只读文件，充分理解代码
3. 初始化 results.tsv:

   commit	metric	status	description
   

4. 运行 baseline: 不做任何修改，执行运行命令，记录初始指标值
5. 确认: 向用户展示 baseline 结果，确认后开始循环

实验循环

无限循环，直到用户中断：

Step 1 — 构思

• 基于已有结果和代码理解，提出一个实验假设
• 优先尝试高收益、低风险的修改
• 如果连续 3 次未改进，尝试更激进的变化

Step 2 — 修改

• 仅修改目标文件
• git commit，message 简述实验内容

Step 3 — 运行

<运行命令> > run.log 2>&1

• 重定向所有输出到 run.log，避免污染上下文
• 如果超过超时上限，kill 进程并标记为 crash

Step 4 — 评估

grep "<提取模式>" run.log

• 如果 grep 无输出 → crash，运行 tail -50 run.log 诊断
• 解析指标值，与当前最优值比较

Step 5 — 决策

Keep（指标改进）:

• 保留 commit，更新最优值
• 记录到 results.tsv

Discard（指标未改进或变差）:

• git reset --hard HEAD~1 回到上一个状态
• 记录到 results.tsv

Crash（运行失败）:

• 如果是简单 bug（typo、import 遗漏）→ 修复并重试（最多 2 次）
• 如果是根本性问题 → 回滚，记录 crash，继续下一个实验

Step 6 — 记录

追加一行到 results.tsv（不提交到 git）：

<commit_hash>	<metric_value>	<keep|discard|crash>	<实验描述>

Step 7 — 回到 Step 1

策略指南

修改策略

• 先小后大: 从微调参数开始，逐步尝试架构变化
• 一次一变量: 每次实验只改一个方面，方便归因
• 简洁优先: 同等效果下，更简洁的代码优先保留
• 组合尝试: 多次独立改进后，尝试组合已验证的改进

卡住时的策略

• 重新阅读目标文件和只读文件，寻找新角度
• 回顾 results.tsv，分析什么类型的修改有效
• 尝试更激进的变化（如替换整个模块）
• 尝试反直觉的修改（如删除看似必要的代码）

绝不停止

• 一旦循环开始，不要暂停询问用户是否继续
• 用户可能不在电脑前（如过夜运行）
• 预期吞吐量：如每轮 5 分钟，则每小时约 12 次实验，8 小时约 100 次
• 如果想法用尽，重新审视代码，think harder

注意事项

• results.tsv 不提交到 git，保持 untracked
• 只修改目标文件，不碰其他文件
• 运行日志始终重定向到 run.log，避免上下文膨胀
• 如果指标完全没有改善空间（连续 10 次 discard），考虑通知用户