autoresearch-create

Autoresearch

自主实验循环：尝试各种想法，保留有效的，丢弃无效的，永不停歇。

工具

• init_experiment — 配置会话（名称、指标、单位、方向）。当优化目标变化时，再次调用以使用新的基线重新初始化。
• run_experiment — 运行命令、计时并捕获输出。
• log_experiment — 记录结果。keep 会自动提交。discard/crash/checks_failed 会自动还原代码更改（保留 autoresearch 文件）。始终包含次要 metrics 字典。控制面板：ctrl+shift+t。

会话文件

所有会话文件都放在工作目录根目录下的单个 .auto/ 子文件夹中。这样所有文件都集中在一处，方便在还原后保留、加入 gitignore 以及清理。

文件	用途
.auto/prompt.md	实验提示词 / 操作手册（会话的核心）
.auto/measure.sh	基准测试脚本 — 输出 METRIC name=value 行
.auto/log.jsonl	仅追加的结果日志（由工具写入）
.auto/ideas.md	想法待办列表（可选）
.auto/checks.sh	正确性检查（可选）
.auto/config.json	会话配置（可选）
.auto/hooks/{before,after}.sh	生命周期钩子（可选）

始终按照 .auto/ 的目录结构创建文件。对于正在进行的会话，仍会读取旧版扁平结构的 autoresearch.* 文件，但新会话应使用 .auto/。

设置

1. 询问（或推断）：目标、命令、指标（+ 方向）、涉及的文件、约束条件。
2. git checkout -b autoresearch/<goal>-<date>
3. 阅读源文件。动手之前，深入了解工作负载。
4. mkdir -p .auto，然后编写 .auto/prompt.md 和 .auto/measure.sh（见下文）。提交这两个文件。
5. init_experiment → 运行基线 → log_experiment → 立即开始循环。

.auto/prompt.md

这是会话的核心。没有上下文的新 Agent 应能够阅读此文件并有效地运行循环。请投入时间，将其打磨完善。

# Autoresearch: <goal>

## Objective
<Specific description of what we're optimizing and the workload.>

## Metrics
- **Primary**: <name> (<unit>, lower/higher is better) — the optimization target
- **Secondary**: <name>, <name>, ... — independent tradeoff monitors

## How to Run
`./.auto/measure.sh` — outputs `METRIC name=number` lines.

## Files in Scope
<Every file the agent may modify, with a brief note on what it does.>

## Off Limits
<What must NOT be touched.>

## Constraints
<Hard rules: tests must pass, no new deps, etc.>

## What's Been Tried
<Update this section as experiments accumulate. Note key wins, architectural
insights, and discarded ideas: why they failed and what would justify revisiting them.>

定期更新 .auto/prompt.md，尤其是“已尝试的内容”部分，以便恢复工作的 Agent 掌握完整上下文。

.auto/measure.sh

Bash 脚本（set -euo pipefail），需要快速执行预检查（在 1 秒内发现语法错误）、运行基准测试，并向标准输出输出结构化行。保持脚本快速 — 每多花一秒，数百次运行后都会被放大。

对于快速且噪声较大的基准测试（< 5s），在脚本中多次运行工作负载并报告中位数。这能生成稳定的数据点，并从一开始就确保置信度评分可靠。慢速工作负载（ML 训练、大型构建）无需这样做，单次运行即可。

结构化输出

• METRIC name=value — 主要指标（必须与 init_experiment 的 metric_name 相匹配）以及任何次要指标。由 run_experiment 自动解析。

设计脚本以辅助优化

脚本应输出有助于你在下一轮做出更好决策的任何数据。想想每次运行后需要看到什么，才能知道下一步该关注哪里：

• 工作负载包含不同阶段时，输出各阶段的耗时
• 检查可能以不同方式失败时，输出错误数量、失败类别或测试名称
• 相关时，输出内存用量、缓存命中率或其他运行时诊断数据
• 任何有助于定位回归或识别瓶颈的领域专属信息

每轮迭代都会运行相同的代码 — 但如果发现需要更多信号，可以在循环期间更新脚本。随着你逐渐了解哪些信息重要，添加相应的检测代码。

通过 log_experiment 提供由 Agent 提供的 ASI

使用 log_experiment 的 asi 参数为每次运行添加注释，记录任何有助于下一轮做出更好决策的内容。使用自由格式的键值对——由你决定哪些内容值得记录。不要重复描述或原始输出；记录那些在上下文重置后会丢失的信息。

详细记录失败和崩溃。 被丢弃或崩溃的运行会被回滚——代码改动会消失。唯一保留下来的记录是 .auto/log.jsonl 中的描述和 ASI。如果没有记录你尝试了什么以及失败的原因，后续迭代就会浪费时间，重新探索同样的死路。

.auto/config.json（可选）

位于 pi 会话工作目录（ctx.cwd）下的 .auto/ 目录中的 JSON 配置文件。支持以下字段：

• maxIterations（数字）——自动停止前允许进行的最大实验次数。
• workingDir（字符串）——覆盖所有 autoresearch 操作所使用的目录：文件 I/O（.auto/log.jsonl、.auto/prompt.md、.auto/measure.sh、.auto/checks.sh、.auto/ideas.md）、命令执行和 git 操作。支持绝对路径或相对路径（相对于 ctx.cwd 解析）。配置文件本身始终保留在 ctx.cwd 下。如果目录不存在，则失败。

{
  "workingDir": "/path/to/project",
  "maxIterations": 50
}

.auto/checks.sh（可选）

用于反压/正确性检查的 Bash 脚本（set -euo pipefail）：测试、类型检查、lint 等。仅当用户的约束要求进行正确性验证时才创建此文件（例如，“测试必须通过”“类型检查必须通过”）。

存在此文件时：

• 每次 run_experiment 中的基准测试通过后，都会自动运行。
• 如果检查失败，run_experiment 会明确报告——记录为 checks_failed。
• 检查所花费的时间不会影响主要指标。
• 检查失败时，不能 keep 结果。
• 此脚本有单独的超时时间（默认 300s，可通过 checks_timeout_seconds 配置）。

不存在此文件时，所有行为都与之前完全相同——循环不会有任何变化。

尽量减少输出。 检查失败时，只会将最后 80 行检查输出反馈给 Agent。抑制冗长的进度/成功输出，仅输出错误信息。这样可以精简上下文，帮助 Agent 找出问题所在。

#!/bin/bash
set -euo pipefail
# Example: run tests and typecheck — suppress success output, only show errors
pnpm test --run --reporter=dot 2>&1 | tail -50
pnpm typecheck 2>&1 | grep -i error || true

循环规则

无限循环。 永远不要询问“要不要继续？”——用户期待自动执行。

• 主要指标至上。 有所改善 → keep。变差或持平 → discard。次要指标很少会影响这一判断。
• 每次运行都用 asi 添加注释。 记录你学到了什么，而不是你做了什么。哪些信息能帮助下一轮迭代，或帮助接手此会话的新 Agent？
• 关注置信度分数。 运行 3 次或更多后，log_experiment 会报告置信度分数（最佳改善幅度相对于会话噪声下限的倍数）。≥2.0× 表示改善很可能真实存在。<1.0× 表示改善处于噪声范围内——考虑重新运行以确认后再保留。此分数仅供参考——不会自动丢弃结果。
• 越简单越好。 性能相同但代码更少 = 保留。微小收益却带来丑陋的复杂性 = 很可能丢弃。
• 不要反复折腾。 如果反复回滚同一个想法，就尝试结构上不同的方案。
• 崩溃： 如果能轻松修复就修复，否则记录后继续。不要投入过多精力。
• 遇到瓶颈时多思考。 重新阅读源文件，研究性能分析数据，推理 CPU 实际在做什么。最佳方案来自深入理解，而不是随机尝试各种变体。
• 恢复会话： 如果 .auto/prompt.md 存在，读取它和 git log，然后继续循环。

永远不要停止。 用户可能几个小时都不在。持续运行，直到被中断。

想法待办列表

发现复杂但有前景、暂时不会推进的优化时，将它们作为项目追加到 .auto/ideas.md。不要让好点子丢失。

恢复会话时（上下文达到上限、发生崩溃），检查 .auto/ideas.md——清理过时或已尝试的条目，并尝试其余想法。所有方向都尝试完后，删除此文件并撰写最终总结。

实验期间的用户消息

如果用户在实验运行期间发送消息，请先完成当前的 run_experiment + log_experiment 周期，然后在下一次迭代中纳入他们的反馈。不要放弃正在运行的实验。