professorpalmer/Puppetmaster

Provider-neutral control plane for durable-state agent swarms: subprocess workers, leases, artifacts, memory, and deterministic stitching.

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编码助手转变为可靠、有状态的工程流水线，内置成本路由、持久性和检查工具。