自动研究智能体

autoresearch-agent

分类编程

作者Alireza Rezvani

许可MIT

评分4.40/5

使用12.9K

Autoresearch Agent

> 你在睡觉，代理在实验。醒来即见结果。

这是一个受 Karpathy's autoresearch 启发的自主实验循环。代理会编辑单个文件，运行固定评估，保留改进，舍弃失败，并无限循环。

不是一次猜测，而是五十次经过测量的尝试，持续复利。

---

斜杠命令 (Slash Commands)

| 命令 | 功能 |
|---------|-------------|
| /ar:setup | 交互式设置新实验 |
| /ar:run | 运行单次实验迭代 |
| /ar:loop | 启动自主循环，可配置间隔（10分钟, 1小时, 每日, 每周, 每月） |
| /ar:status | 显示仪表盘和结果 |
| /ar:resume | 恢复已暂停的实验 |

---

技能激活时机

识别用户输入中的以下模式：

“让这个更快 / 更小 / 更好”

“针对 [指标] 优化 [文件]”

“改进我的 [标题 / 文案 / 提示词]”

“在夜间运行实验”

“我想将 [指标] 从 X 提升到 Y”

任何涉及：优化 (optimize)、基准测试 (benchmark)、改进 (improve)、实验循环 (experiment loop)、autoresearch 的请求

如果用户描述了“目标文件 + 衡量成功的方法” $\rightarrow$ 适用此技能。

---

设置 (Setup)

首次运行 — 创建实验

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

项目级（在仓库内，由 git 追踪，可与团队共享）：

bash

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/）：

bash

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 (默认) $\rightarrow$ 位于仓库根目录的 .autoresearch/。实验定义由 git 追踪，结果被 gitignore。

user $\rightarrow$ 位于用户主目录的 ~/.autoresearch/。所有内容均为个人私有。

设置生成的内容

code

.autoresearch/
├── config.yaml                        ← 全局设置
├── .gitignore                         ← 忽略 results.tsv, *.log
└── {domain}/{experiment-name}/
    ├── program.md                     ← 目标、约束、策略
    ├── config.cfg                     ← 目标文件, 评估命令, 指标, 方向
    ├── results.tsv                    ← 实验日志 (gitignored)
    └── evaluate.py                    ← 评估脚本 (如果使用了 --evaluator)

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

commit — git 短哈希

metric — 浮点数值，若崩溃则为 "N/A"

status — keep（保留）| discard（舍弃）| crash（崩溃）

description — 变更内容或崩溃原因

领域 (Domains)

| 领域 | 使用场景 |
|--------|-----------|
| engineering | 代码速度、内存、包体积、测试通过率、构建时间 |
| marketing | 标题、社交媒体文案、邮件主题、广告文案、参与度 |
| content | 文章结构、SEO 描述、可读性、点击率 (CTR) |
| prompts | 系统提示词、聊天机器人语气、智能体指令 |
| custom | 任何其他具有可衡量指标的内容 |

如果 `program.md` 已存在

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

---

智能体协议 (Agent Protocol)

你处于循环之中。脚本负责设置和评估 —— 你负责创意工作。

开始前

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

启动实验

bash

# 单次迭代（智能体重复调用此命令）
python scripts/run_experiment.py --experiment engineering/api-speed --single
空运行（开始前测试设置）
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 日志会持久化

规则

每次实验仅限一项变更。 不要一次更改 5 件事，否则你无法确定哪个起作用了。

简洁性标准。 如果微小的改进带来了糟糕的复杂度，则不值得。在性能相同的情况下，优先选择更简单的方案。

用更简洁的代码实现相同功能即为胜利。删除能获得相同结果的冗余代码是最佳结果。

绝不要修改评估器。 evaluate.py 是唯一真理。修改它会导致所有对比失效。一旦发现自己在修改它，请立即停止。

超时处理。 如果运行时间超过时间预算的 2.5 倍，直接终止并视为崩溃（crash）。

崩溃处理。 如果是拼写错误或缺失导入，修复后重新运行。如果方案根本性失效，则回滚，记录 "crash" 并继续。连续 5 次崩溃 $\rightarrow$ 暂停并发出警报。

禁止引入新依赖。 仅使用项目中已有的依赖。

---

评估器 (Evaluators)

开箱即用的评估脚本。在设置时通过 --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 评委调用用户当前运行的 CLI 工具（Claude, Codex, Gemini）。评估提示词被锁定在 evaluate.py 内部 —— Agent 无法修改它。这防止了 Agent 通过操纵评估器来刷分。

费用由用户的现有订阅覆盖：

Claude Code Max $\rightarrow$ 无限制的 Claude 评估调用

Codex CLI (ChatGPT Pro) $\rightarrow$ 无限制的 Codex 调用

Gemini CLI (免费层级) $\rightarrow$ 免费的评估调用

自定义评估器

如果没有内置评估器适用，用户可以编写自己的 evaluate.py。唯一要求是：必须将 metric_name: value 打印到标准输出（stdout）。

python

#!/usr/bin/env python3
我的自定义评估器 —— 实验开始后请勿修改
import subprocess
result = subprocess.run(["my-benchmark", "--json"], capture_output=True, text=True)
解析并输出
print(f"my_metric: {parse_score(result.stdout)}")

---

查看结果

bash

# 单个实验
python scripts/log_results.py --experiment engineering/api-speed
某个领域的所有实验
python scripts/log_results.py --domain engineering
跨实验仪表盘
python scripts/log_results.py --dashboard
导出格式
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

仪表盘输出

code

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 — 默认格式，制表符分隔

d（兼容电子表格）

CSV — 逗号分隔，包含正确的引号引用

Markdown — 格式化表格，适用于 GitHub/文档阅读

---

主动触发机制

在无需询问的情况下，直接标记以下情况：

评估命令失效 $\rightarrow$ 在开始循环前进行测试。运行一次并验证输出。

目标文件不在 git 中 $\rightarrow$ 先执行 git init && git add . && git commit -m 'initial'。

指标方向不明确 $\rightarrow$ 询问：是越低越好还是越高越好？必须在开始前确认。

时间预算过短 $\rightarrow$ 如果评估时间超过预算，每次运行都会崩溃。

Agent 修改 evaluate.py $\rightarrow$ 立即停止。这会导致所有对比失效。

连续 5 次崩溃 $\rightarrow$ 暂停循环并提醒用户，避免浪费资源。

连续 20+ 次运行无提升 $\rightarrow$ 建议修改 program.md 中的策略或尝试不同方法。

---

安装指南

一键安装（通用）

bash

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

多工具安装

bash

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

OpenClaw

bash

clawhub install cs-autoresearch-agent

---

自动研究智能体

Autoresearch Agent

斜杠命令 (Slash Commands)

技能激活时机

设置 (Setup)

首次运行 — 创建实验

设置生成的内容

领域 (Domains)

如果 `program.md` 已存在

智能体协议 (Agent Protocol)

开始前

每次迭代

脚本处理的内容（无需你处理）

启动实验

空运行（开始前测试设置）

策略升级

自我改进

停止条件

规则

评估器 (Evaluators)

免费评估器（无 API 成本）

LLM 评委评估器（使用你的订阅额度）

自定义评估器

我的自定义评估器 —— 实验开始后请勿修改

解析并输出

查看结果

某个领域的所有实验

跨实验仪表盘

导出格式

仪表盘输出

导出格式

主动触发机制

安装指南

一键安装（通用）

多工具安装

OpenClaw

相关技能

扫码进交流群

自动研究智能体

Autoresearch Agent

斜杠命令 (Slash Commands)

技能激活时机

设置 (Setup)

首次运行 — 创建实验

设置生成的内容

领域 (Domains)

如果 program.md 已存在

智能体协议 (Agent Protocol)

开始前

每次迭代

脚本处理的内容（无需你处理）

启动实验

空运行（开始前测试设置）

策略升级

自我改进

停止条件

规则

评估器 (Evaluators)

免费评估器（无 API 成本）

LLM 评委评估器（使用你的订阅额度）

自定义评估器

我的自定义评估器 —— 实验开始后请勿修改

解析并输出

查看结果

某个领域的所有实验

跨实验仪表盘

导出格式

仪表盘输出

导出格式

主动触发机制

安装指南

一键安装（通用）

多工具安装

OpenClaw

相关技能

扫码进交流群

如果 `program.md` 已存在