davebcn87/pi-autoresearch

pi‑autoresearch – pi 代码代理的自主优化循环

是什么 – 一个开源终端式 AI 代码助手 pi (https://pi.dev) 的扩展（以及几个“技能”）。它赋予 pi 执行 autoresearch 循环的能力：提出变更、进行基准测试、决定保留或回滚，并自动重复，直到满足停止条件。

为何重要 – autoresearch 的核心思想（最初由 Andrej Karpathy 展示）是让 LLM 作为自我改进的工程师。pi‑autoresearch 将这一工作流打包为可重用、与领域无关的工具链，因此你可以优化任何能通过命令行指标衡量的东西——测试速度、包大小、构建时间、Lighthouse 分数，甚至 LLM 训练损失。

主要组件

组件	作用
扩展（通过 `pi install npm:pi-autoresearch` 安装）	提供三个低级工具（`init_experiment`、`run_experiment`、`log_experiment`）和一个位于编辑器上方的实时仪表板小部件。
技能 `autoresearch-create`	交互式向导，询问（或推断）优化目标，创建 Git 分支，编写会话文件（`.auto/prompt.md`、`.auto/measure.sh` 等）并启动循环。
技能 `autoresearch-finalize`	循环结束后，读取日志，将成功运行分组为独立的、可审查的 Git 分支。
技能 `autoresearch-hooks`（可选）	允许你放置 `before.sh` / `after.sh` 脚本，在每次迭代前后运行，接收 JSON 上下文并返回自由格式消息给代理。

会话工作流程

创建 – 运行 /skill:autoresearch-create。pi 询问一个目标（例如“减少测试运行时间”）、一个 测量命令 和指标（秒、KB、分数等）。它会生成：
- .auto/prompt.md – 实验的动态描述。
- .auto/measure.sh – 运行命令并打印 METRIC name=number 行的脚本。
- （可选）.auto/checks.sh – 每次成功基准测试后运行的正确性检查。
循环 – 代理反复：
- 编辑代码，
- run_experiment → 执行 measure.sh 并记录墙钟时间，
- log_experiment → 将 JSON 行追加到 .auto/log.jsonl，自动提交，更新小部件。
- 根据指标和可选的置信度评分决定保留（保留提交）或回滚（恢复到之前状态）。
- 循环在你中断或达到 maxIterations 限制前持续运行。
监控 – 使用内置小部件、/autoresearch dashboard（全屏终端视图）或 /autoresearch export（实时浏览器仪表板）查看运行记录表、置信度评分和当前实验的旋转指示器。
最终化 – 满意后，运行 /skill:autoresearch-finalize。pi 将保留的运行分组为独立分支，每个分支包含单一逻辑变更，准备进行代码审查。

置信度评分（可选）

三次运行后，扩展计算一个 置信度 值 = |best_improvement| / MAD（指标值的中位数绝对偏差）。它以绿色（≥ 2×，很可能为真实改善）、黄色（1–2×，边缘）、红色（< 1×，在噪声范围内）显示。该评分仅作参考——代理仍决定是否保留变更。

可扩展性

与领域无关的核心 – 扩展仅知道如何运行命令、记录结果和管理 Git。所有领域知识都存在于你编写的（或使用的提供的 autoresearch-create 向导）技能中。
钩子 – 在 .auto/hooks/ 中放置脚本，以获取外部数据、发送桌面通知、轮换想法等。钩子从 stdin 接收 JSON 负载，并可返回短消息，pi 会将其视为引导线索。
配置 – .auto/config.json 可设置 workingDir（覆盖文件读写位置）和 maxIterations（实验硬上限）。

安装与快速入门

# 在 pi 会话中
pi install npm:pi-autoresearch   # 拉取扩展 + 技能
# 然后开始新循环
/skill:autoresearch-create

你也可以通过将 extensions/ 和 skills/ 文件夹手动复制到 ~/.pi/agent/ 并重新加载 pi 来安装。

安全与成本注意事项

扩展运行任意 shell 脚本（measure.sh、checks.sh、钩子）并进行 Git 提交——请在专用分支或工作树中运行。
由于循环可能在每次迭代中调用 LLM，令牌使用量可能迅速增长。通过提供商的 API 密钥限制或设置 maxIterations 控制成本。

许可证

MIT – 免费使用、修改和重新分发。