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 – 免費使用、修改和重新分發。