professorpalmer/Puppetmaster

Puppetmaster – 基於LLM的開發代理的持久化編排層

它是什麼 – puppetmaster（從PyPI安裝為puppetmaster‑ai）是一個基於Python的監督器，可讓您透過已使用的LLM驅動工具（Cursor、Claude‑Code、Codex、Gemini Antigravity、Hermes、OpenAI相容API等）執行多步驟工程任務。它啟動獨立的worker程序，將每個子任務路由到最合適的模型，並將每個型別化結果持久化到本機SQLite資料庫中。儲存的工件使整個工作流程可檢查、可恢復且可稽核。

為什麼重要 – 典型的LLM「代理」保持單一不斷增長的記錄，這使得從故障中恢復、比較模型輸出或證明已完成的工作變得困難。Puppetmaster將工作分解為持久的型別化工件，為開發人員提供可靠的程式碼庫稽核、重構或任何儲存庫範圍自動化的狀態層。

---

核心概念

概念	作用
Pilots (MCP)	呼叫Puppetmaster的前端（Cursor Agent、Grok Bot、Claude Desktop、Pi、OMP）。
Adapters / Workers	具體的模型後端（cursor、claude‑code、codex、hermes、antigravity、通用agentic API）。
Supervisor	協調路由，啟動worker，寫入SQLite工件，並提供拼接摘要。
SQLite store	每個步驟的持久化日誌（負載、證據、內容雜湊），可稍後查詢。
Dashboard	用於即時作業檢查的小型Web UI（http://127.0.0.1:<port>/?job=<id>&embed=1），也可從手機使用。

---

快速開始（shell）

# 安裝（建議使用pipx）
pipx install puppetmaster-ai
# 設定您擁有的適配器，例如Cursor
puppetmaster setup --platforms cursor

# 在目前儲存庫上執行簡單的「doctor」檢查
puppetmaster doctor

# 啟動受監督的變更
puppetmaster start "Review this repo for release blockers" \
    --review --dry-run

# 檢查最新作業
puppetmaster show $(puppetmaster last)

在支援的UI（Cursor、Grok Bot等）中，您只需輸入：

Use Puppetmaster to run doctor in this repo and summarize what is missing.

UI將請求轉發到本機監督器，監督器啟動適當的worker並傳回可輪詢的作業ID。

---

主要功能

• 多模型路由 – 為每個子任務選擇最便宜或最強大的模型；成本路由已顯示在SWE‑bench Lite上可減少約30%的支出。
• 持久化狀態 – 每個worker將型別化工件寫入SQLite；作業在崩潰後仍可存活並可恢復。
• 扇出與拼接 – 可以啟動並行worker，然後由最終模型產生簡潔摘要。
• 適配器無關 – 適用於任何遵循MCP契約的CLI（Cursor、Claude‑Code、Codex、Gemini Antigravity、Hermes或通用API金鑰）。
• Grok Bot的遠端MCP – 透過HTTP/SSE公開相同的工具處理程序，以便Cursor的Grok Bot可以從另一台機器驅動作業。
• 可選的CodeGraph上下文 – 如果存在codegraph索引，worker會自動接收結構化程式碼資訊。
• 儀表板與CLI檢查 – puppetmaster artifacts <job_id>或python -m puppetmaster dashboard檢視原始結果。
• 安全鉤子 – 內建請求層級驗證（puppetmaster setup --verify-first-run …）和SECURITY.md中記錄的安全模型。

---

證據與基準

• SWE‑bench Lite – 與單一模型基線相比，實際支出降低29%，令牌匹配節省約48%（單一種子研究）。
• NL2Repo‑Bench – 平均通過率91.1%，約為已發布約40%基線的2.3倍。詳細方法在連結的基準儲存庫和公開部落格文章中。
• 可重現的基準指令碼隨儲存庫提供（CLAIMS.md），涵蓋路由、工件完整性和故障分類。

---

成熟度與授權

• 版本 v1.27.8（測試版，日常驅動）。最近的版本增加了持久性修復、持續規劃和無邊框嵌入式儀表板。
• 安裝 – pipx或pip；puppetmaster setup處理適配器和MCP鉤子的冪等安裝。
• 解除安裝 – puppetmaster uninstall刪除所有MCP條目；狀態可透過--purge‑state清除。
• 授權 – MIT。

---

何時使用

• 您已經使用一個或多個LLM驅動的編碼助手，並希望在單一位置協調它們。
• 您需要模型所做工作的可稽核日誌（例如安全稽核、合規檢查）。
• 您的工作流程受益於並行模型呼叫和最終拼接摘要。
• 您希望透過為簡單步驟路由廉價模型並為關鍵編輯保留昂貴模型來降低成本。

---

了解更多

• 完整文件：docs/README.md
• 適配器設定詳情：docs/ADAPTERS.md
• 功能矩陣：docs/FEATURES.md
• 基準聲明：docs/CLAIMS.md
• 儀表板用法：docs/DASHBOARD.md

---

底線 – Puppetmaster是一個實用的開源層，將臨時的LLM編碼助手轉變為可靠、有狀態的工程流水線，內建成本路由、持久性和檢查工具。