autoresearch-agent

Autoresearch Agent

你入睡，Agent 开始实验。你醒来时，结果已出炉。

灵感来自 Karpathy's autoresearch 的自主实验循环。Agent 编辑一个文件，运行固定的评估，保留改进，舍弃失败，然后无限循环。

不是一次猜测，而是 50 次有测量依据的尝试，效果不断累积。

---

斜杠命令

命令	作用
/ar:setup	交互式设置新实验
/ar:ar-run	运行单次实验迭代
/ar:loop	启动自主循环，并配置间隔（10m、1h、daily、weekly、monthly）
/ar:ar-status	显示仪表板和结果
/ar:ar-resume	恢复已暂停的实验

---

此技能的触发条件

识别用户提出的以下需求：

• “让它更快／更小／更好”
• “针对 [指标] 优化 [文件]”
• “改进我的 [标题／文案／提示词]”
• “通宵运行实验”
• “我想把 [指标] 从 X 提升到 Y”
• 任何涉及以下内容的请求：优化、基准测试、改进、实验循环、autoresearch

如果用户指定了目标文件和衡量成功的方法，就适用此技能。

---

设置

首次使用 — 创建实验

运行设置脚本。实验存放位置由用户决定：

项目级（位于仓库内，由 Git 跟踪，可与团队共享）：

python scripts/setup_experiment.py \
  --domain engineering \
  --name api-speed \
  --target src/api/search.py \
  --eval "pytest bench.py --tb=no -q" \
  --metric p50_ms \
  --direction lower \
  --scope project

用户级（个人使用，位于 ~/.autoresearch/）：

python scripts/setup_experiment.py \
  --domain marketing \
  --name medium-ctr \
  --target content/titles.md \
  --eval "python evaluate.py" \
  --metric ctr_score \
  --direction higher \
  --evaluator llm_judge_content \
  --scope user

--scope 标志决定 .autoresearch/ 的存放位置：

• project（默认）→ 仓库根目录中的 .autoresearch/。实验定义由 Git 跟踪，结果则被 Git 忽略。
• user → 主目录中的 ~/.autoresearch/。所有内容均为个人数据。

设置会创建的内容

.autoresearch/
├── config.yaml                        ← Global settings
├── .gitignore                         ← Ignores results.tsv, *.log
└── {domain}/{experiment-name}/
    ├── program.md                     ← Objectives, constraints, strategy
    ├── config.cfg                     ← Target, eval cmd, metric, direction
    ├── results.tsv                    ← Experiment log (gitignored)
    └── evaluate.py                    ← Evaluation script (if --evaluator used)

results.tsv 列： commit | metric | status | description

• commit — Git 短哈希
• metric — 浮点值；崩溃时为 "N/A"
• status — keep | discard | crash
• description — 变更内容或崩溃原因

领域

领域	用例
engineering	代码速度、内存、包体积、测试通过率、构建时间
marketing	标题、社交媒体文案、邮件主题、广告文案、互动率
content	文章结构、SEO 描述、可读性、CTR
prompts	系统提示词、聊天机器人的语气、Agent 指令
custom	其他任何有可衡量指标的内容

如果 program.md 已存在

用户可能已经编写了自己的 program.md。如果在实验目录中找到该文件，请读取。它会覆盖模板。只询问缺少的信息。

---

Agent 协议

你负责循环。脚本处理设置和评估，而你负责创意工作。

开始之前

1. 读取 .autoresearch/{domain}/{name}/config.cfg，获取：
   • target — 要编辑的文件
   • evaluate_cmd — 用于衡量变更效果的命令
   • metric — 评估输出中要查找的指标名称
   • metric_direction — "lower" 或 "higher" 表示哪个方向更好
   • time_budget_minutes — 每次评估的最长时间
2. 读取 program.md，了解策略、约束以及允许或禁止更改的内容
3. 读取 results.tsv，了解实验历史（列：commit、metric、status、description）
4. 切换到实验分支：git checkout autoresearch/{domain}/{name}

每次迭代

1. 检查 results.tsv：哪些做法有效？哪些失败了？哪些还没尝试？
2. 决定对目标文件进行一项变更。每次实验只调整一个变量。
3. 编辑目标文件
4. 提交：git add {target} && git commit -m "experiment: {description}"
5. 评估：python scripts/run_experiment.py --experiment {domain}/{name} --single
6. 阅读输出 — 它会显示 KEEP、DISCARD 或 CRASH，以及指标值
7. 转到第 1 步

脚本负责处理的内容（你不必处理）

• 在超时时限内运行评估命令
• 从评估输出中解析指标
• 与此前最佳结果进行比较
• 失败时还原提交（git reset --hard HEAD~1）
• 将结果记录到 results.tsv

开始实验

# Single iteration (the agent calls this repeatedly)
python scripts/run_experiment.py --experiment engineering/api-speed --single

# Dry run (test setup before starting)
python scripts/run_experiment.py --experiment engineering/api-speed --dry-run

策略升级

• 第 1-5 次运行：低垂的果实（明显的改进、简单的优化）
• 第 6-15 次运行：系统性探索（每次只改变一个参数）
• 第 16-30 次运行：结构性改动（算法替换、架构调整）
• 第 30 次以上运行：激进实验（完全不同的方法）
• 若 20 次以上运行都没有改进：更新 program.md 中的 Strategy 部分

自我改进

每完成 10 次实验，检查 results.tsv 以寻找规律。将所学内容更新到 program.md 的 Strategy 部分（例如"缓存类改动稳定带来 5-10% 的提升"、"重构类尝试从未改善指标"）。后续迭代可以受益于这些积累的经验。

停止

• 持续运行，直到用户中断、达到上下文限制或 program.md 中的目标已达成
• 停止前：确保 results.tsv 为最新状态
• 达到上下文限制时：下一次会话可以继续——results.tsv 和 git log 会保留

规则

• 每次实验只改一处。 不要一次改动 5 处。你将无法知道哪项改动有效。
• 简洁性准则。 如果小幅提升需要引入难看的复杂代码，则不值得。性能相同但代码更简单就是胜利。删除代码后结果不变是最好的结果。
• 绝不修改评估器。 evaluate.py 是事实依据（ground truth）。修改它会使所有比较失效。如果你发现自己在这样做，立即停止。
• 超时。 如果一次运行超过时间预算的 2.5 倍，则终止它并视为崩溃。
• 崩溃处理。 如果是拼写错误或缺失导入，修复后重新运行。如果思路本身根本不可行，则回滚，记录"crash"，然后继续。连续 5 次崩溃 → 暂停并发出警报。
• 不引入新依赖。 只使用项目中已有的内容。

---

评估器

开箱即用的评估脚本。在设置时通过 --evaluator 复制到实验目录中。

免费评估器（无 API 费用）

评估器	指标	适用场景
benchmark_speed	p50_ms（越低越好）	函数/API 执行时间
benchmark_size	size_bytes（越低越好）	文件、打包产物、Docker 镜像大小
test_pass_rate	pass_rate（越高越好）	测试套件通过率
build_speed	build_seconds（越低越好）	构建/编译/Docker 构建时间
memory_usage	peak_mb（越低越好）	执行期间的峰值内存

LLM 评审评估器（使用你的订阅）

评估器	指标	适用场景
llm_judge_content	ctr_score 0-10（越高越好）	标题、标题文案、描述
llm_judge_prompt	quality_score 0-100（越高越好）	系统提示词、Agent 指令
llm_judge_copy	engagement_score 0-10（越高越好）	社交媒体帖子、广告文案、邮件

LLM 评审会调用用户已在运行的命令行工具（Claude、Codex、Gemini）。评估提示词锁定在 evaluate.py 内部——Agent 无法修改它。这样可以防止 Agent 操纵自己的评估器。

用户现有的订阅已涵盖费用：

• Claude Code Max → 评估时可无限调用 Claude
• Codex CLI（ChatGPT Pro）→ 可无限调用 Codex
• Gemini CLI（免费版）→ 免费的评估调用

自定义评估器

如果没有合适的内置评估器，用户可以自行编写 evaluate.py。唯一要求：它必须向标准输出打印 metric_name: value。

#!/usr/bin/env python3
# My custom evaluator — DO NOT MODIFY after experiment starts
import subprocess
result = subprocess.run(["my-benchmark", "--json"], capture_output=True, text=True)
# Parse and output
print(f"my_metric: {parse_score(result.stdout)}")

---

查看结果

# Single experiment
python scripts/log_results.py --experiment engineering/api-speed

# All experiments in a domain
python scripts/log_results.py --domain engineering

# Cross-experiment dashboard
python scripts/log_results.py --dashboard

# Export formats
python scripts/log_results.py --experiment engineering/api-speed --format csv --output results.csv
python scripts/log_results.py --experiment engineering/api-speed --format markdown --output results.md
python scripts/log_results.py --dashboard --format markdown --output dashboard.md

仪表盘输出

DOMAIN          EXPERIMENT          RUNS  KEPT  BEST         Δ FROM START  STATUS
engineering     api-speed            47    14   185ms        -76.9%        active
engineering     bundle-size          23     8   412KB        -58.3%        paused
marketing       medium-ctr           31    11   8.4/10       +68.0%        active
prompts         support-tone         15     6   82/100       +46.4%        done

导出格式

• TSV — 默认，制表符分隔（兼容电子表格）
• CSV — 逗号分隔，带有规范的引号处理
• Markdown — 格式化表格，可在 GitHub/文档中阅读

---

主动触发条件

无需用户提问，主动提示以下情况：

• 没有可用的评估命令 → 在开始循环前先测试。运行一次并验证输出。
• 目标文件不在 git 中 → 先执行 git init && git add . && git commit -m 'initial'。
• 指标方向不明确 → 询问：数值越低越好还是越高越好？开始前必须明确。
• 时间预算过短 → 如果评估耗时超过预算，每次运行都会崩溃。
• Agent 修改 evaluate.py → 立即硬性停止。这会使所有对比结果失效。
• 连续 5 次崩溃 → 暂停循环并提醒用户，不要继续浪费运行周期。
• 连续 20 次以上运行没有改进 → 建议在 program.md 中更换策略，或尝试其他方法。

---

安装

一键安装（适用于任意工具）

git clone https://github.com/alirezarezvani/claude-skills.git
cp -r claude-skills/engineering/autoresearch-agent ~/.claude/skills/

多工具安装

./scripts/convert.sh --skill autoresearch-agent --tool codex|gemini|cursor|windsurf|openclaw

OpenClaw

clawhub install cs-autoresearch-agent

---

相关技能

• self-improving-agent — 随时间改进 Agent 自身的记忆与规则。不适用于结构化实验循环。
• senior-ml-engineer — ML 架构决策。互补关系：先用它完成初始设计，再用 autoresearch 进行优化。
• tdd-guide — 测试驱动开发。互补关系：测试可以作为评估函数。
• skill-security-auditor — 发布前审计技能。不适用于优化循环。