Puppetmaster
为多智能体工作流提供供应商中立的控制平面：持久化任务状态、模型路由、SQLite 工件存储与确定性结果拼接，让已有的编码智能体变成可审查的持久工作节点。
最低权限：setup按平台可选启用、remote MCP默认`--scope supervise`省略写权限、卸载保留状态需显式`--purge-state`，符合常规；扣分：setup会写入宿主工具的MCP配置、hooks与规则文件（系统级外部修改），权限边界仅靠文档声明，未见代码级校验。用户确认：quickstart示例含"先review/plan再请求批准"的模式，hooks可用环境变量关闭，`--dry-run`存在；扣分：自动委派hooks默认开启，关闭需用户主动发现环境变量。数据流：SQLite artifacts、`puppetmaster artifacts`、dashboard可检查；良好。敏感数据：hermetic_env显示对凭据环境变量有系统处理意识，remote MCP使用Bearer token；扣分：token存储与TLS依赖用户自行处理（"Use a TLS tunnel if the bot is off-box"）。依赖安全：核心零依赖，可选依赖锁定下限并注明用途，Package.Json仅可选@cursor/sdk；充分。外部影响：会修改宿主IDE/CLI配置并启动子进程worker，安装/卸载说明覆盖；扣分：对宿主配置的修改备份机制未展示。回滚：uninstall带`--dry-run`/`--purge-state`、crash-demo与recovery测试存在；良好。来源归属：作者仅"Cary"，发布者未验证，benchmark"独立"结果发布在同一作者的GitHub Pages，独立性存疑。
自洽性：README/PyPI/CLI命名关系（puppetmaster-ai vs puppetmaster）显式说明，版本号在README（1.27.1）与pyproject（1.27.2）之间存在轻微滞后，扣1分；schema v5迁移说明与attempt ledger文档互相呼应，整体一致。依赖可用性：零运行时依赖+可选extra惰性导入并给出可操作提示，CI覆盖3 OS×2 Python；良好，但Windows 3.9被排除仅靠注释解释。失败信息：doctor命令、adapter失败分类、crash-proof doctor声明存在；hermetic_env中的错误消息详尽；静态审查无法验证质量，给2分。
受众：面向"开发者做仓库调查/审计/重构"，定位明确；场景：audit/review/implement/CI等示例丰富。能力边界：自述"daily-driver beta...supervised local engineering"，benchmark免责声明明确"single-seed study...does not establish quality parity"；良好。触发精度：hooks委派建议针对"较大任务"且可禁用；机制在源文件中仅见声明，未见实现，扣分。环境适配：macOS/Linux/Windows三平台CI，Python 3.9–3.12，PyPI/pipx安装；充分。
信息架构：README带目录，docs index链接SECURITY/ADAPTERS/CLAIMS等且CI校验README本地链接存在；优秀。安装说明：install/uninstall/setup/verify-first-run齐全，含幂等与CI模式；优秀。命名稳定性：PyPI名与导入名不一致的原因已解释（2019年占名），但`0.1.0`的package.版本与Python侧1.27.x不齐；扣分。示例与FAQ：quickstart、DAILY_DRIVER、MODEL_ROUTING、CLI_REFERENCE链接充分。已知限制：Status章节、CLAIMS caveats、budget overrun披露、schema迁移停机提示，诚实度高；优秀。许可：MIT完整文本，README/pyproject一致；满分。版本与变更：changelog链接存在、每版说明具体（v1.27.0/1.27.1），但文件本身未在证据中；Development Status分类为Alpha与"daily-driver beta v1.27"略有张力，扣分。维护责任：单人署名"Cary"，无治理/贡献/安全披露策略文件出现在证据中；扣2分。
输出可用性：typed artifacts、evidence字段、content hash、stitched summary、dashboard，可检查性设计良好；静态无法验证实际输出质量，给2分。边际价值：相对于直接用Cursor/Claude Code，提供持久状态、成本路由、重试，差异化清晰（WHY/COMPARISON文档）；给2分，因声称的收益依赖未独立验证的benchmark。成本收益：成本路由与47-48% token节省为主打卖点，single-seed且自承无质量平价证据，收益真实但证据强度中等。
声明可追溯：benchmark链接到专门repo与文档，CLAIMS.md承诺reproducible scripts与caveats，CI中doctor/demo冒烟测试可查；给2分，关键性能声明无法在本仓库源码内复现。
- 安装`puppetmaster setup`会修改宿主工具（Cursor/Claude Code/Codex等）的MCP配置、hooks和规则文件；执行前应备份这些配置，并通过`--dry-run`类手段预览变更。
- 自动委派hooks默认开启，仅能通过`PUPPETMASTER_AUTO_INVOKE_DISABLED=1`关闭；不希望代理自动接管任务的团队应在部署前显式禁用。
- 远程MCP端点默认需自行保证传输安全（README提示off-box需TLS隧道）；不要在不受信网络中暴露该端点，并妥善保管Bearer token。
- README中的SWE-bench与NL2Repo-Bench结果均由同一作者渠道发布，所谓'independent' benchmark并非第三方复现；不应据此做采购决策。
- README声称版本v1.27.1而pyproject为1.27.2，package.为0.1.0；引用版本号时以pyproject为准并注意文档滞后。
- 项目由单人维护，无可见的治理或安全披露渠道；生产使用前评估关键人风险。
- SQLite schema v5迁移要求停止长期运行进程；升级前阅读迁移说明并备份`~/.puppetmaster/`状态目录。
这个 Agent 能做什么，适合哪些场景？
Puppetmaster 是一个本地持久化智能体控制平面，通过 MCP 工具协调 Cursor Agent、Grok Bot、Claude Code、Codex、Hermes、Antigravity 等已有智能体工具，把它们当作可租用的子进程工作节点。它启动独立的工作进程，按成本和可用性路由任务，并把带类型的工件和证据写入 SQLite，使任务可检查、可恢复、可复用。代码库的 README 明确其当前状态为 v1.24.0 的日常可用 beta，面向仓库调查、审计、重构与实现等受监督的工程任务。安装通过 PyPI 包 puppetmaster-ai 完成，以命令行 puppetmaster 和 MCP 服务器两种接口暴露能力。仓库还附带可复现的基准脚本与范围声明（CLAIMS.md），报告 SWE-bench Lite 成本节约与 NL2Repo-Bench 通过率等结果，但注明这些是单一条件下的测量而非普遍保证。
安装后运行 puppetmaster setup 会为已安装的平台注册 puppetmaster_* MCP 工具、规则和钩子。架构上分为 pilots（通过 MCP 调用工具的 Cursor Agent、Grok Bot、Claude Desktop、Pi、OMP）和 adapters（实际干活的 cursor、claude-code、codex、hermes、antigravity、agentic 等工作节点）。supervisor 接收任务，经 model router 分发给独立工作进程，工作进程认领任务、写工件（含载荷与证据）而不共享一个不断增长的历史记录，最后由 supervisor 生成拼接摘要。用户可通过 puppetmaster doctor、puppetmaster route、puppetmaster review、puppetmaster claude 等 CLI 命令操作，用 puppetmaster artifacts <job_id> 检查工件，用 python -m puppetmaster dashboard 打开实时看板。Grok Bot 走远程 MCP（streamable HTTP），通过 puppetmaster mcp serve-remote 提供，带 Bearer token 认证。可选安装 CodeGraph 以在调用工作节点前注入代码结构上下文。
- 希望在 Cursor Agent 或 Codex 中把大型审计、重构任务委托给后台持久工作节点而不是阻塞单个会话的开发者
- 团队审查者需要在仓库中运行发布阻断项评审（puppetmaster review），保留工件与证据供后续检查
- 已配置多个模型/平台的用户希望按成本路由任务，以降低实际花费（README 报告 SWE-bench Lite 上约 29% 实际支出降低）
- 使用 Grok Bot 的用户想通过远程 MCP 连接器在远程机器上启动并监控持久任务
- 没有安装外部智能体 CLI、仅有 OpenAI/OpenRouter 等 API key 的用户使用内置 agentic 适配器驱动工作节点
- 需要长时间运行的多步实现任务可在中断后恢复、且结果带类型化工件和证据哈希的工程师
这个 Agent 有哪些优点和局限？
- 持久化 SQLite 状态使任务可检查、可恢复，后续检查是零成本读取而非重复推理
- 供应商中立：同一控制平面可驱动 Cursor、Claude Code、Codex、Hermes、Antigravity 及纯 API 的 agentic 适配器
- 成本路由与持久化重试在 README 报告的 SWE-bench Lite 单种子研究中降低约 29% 实际支出（附研究链接）
- 工件含载荷、证据字段与内容哈希，输出可审查，并有可复现基准脚本和 CLAIMS.md 范围声明
- 幂等的 puppetmaster setup 提供一键 MCP/钩子接入，并提供 --verify-first-run 等运维工具与完整卸载命令
- 基准结果为单一条件测量：SWE-bench Lite 研究是单种子且不证明质量对等，NL2Repo-Bench 是作者自建的独立基准
- 依赖至少一个已安装的外部智能体 CLI 或供应商 API key，纯本地离线不可用
- 状态属于本地 SQLite（~/.puppetmaster/），升级到 schema v5 需停止长期运行进程并在新版本上重启各组件，存在迁移协调成本
- 预算预留无法约束不透明的供应商超支，可能超出配额
- Grok Bot 需要单独的远程 MCP 部署和 token 认证，与 stdio 安装路径不同，增加配置复杂度
如何安装或部署这个 Agent？
通过 pipx 或 pip 安装 PyPI 包 puppetmaster-ai：
pipx install puppetmaster-ai
puppetmaster setupsetup 命令幂等，会安装 MCP 工具、规则与钩子，并提示至少启用一个适配器，例如 puppetmaster setup --platforms cursor。Grok Bot 不使用该 stdio 安装，而是运行远程 MCP：export PUPPETMASTER_MCP_TOKEN=$(...) 后执行 python -m puppetmaster mcp serve-remote --scope supervise。内置 agentic 适配器只需一个供应商 API key（如 OPENROUTER_API_KEY、OPENAI_API_KEY）。要求 Python 3.9+。
如何使用这个 Agent？
在 Cursor Agent、Grok Bot 或 Codex 内可直接说："Use Puppetmaster to run doctor in this repo and summarize what is missing."。命令行方式：先运行 puppetmaster doctor 检查环境；用 puppetmaster route "Security audit every endpoint" --role audit 分发任务；用 puppetmaster review "..." 或 puppetmaster claude "Implement the approved change..." 启动带监督的评审/实现任务；用 puppetmaster last 和 puppetmaster show 查看最近任务；用 puppetmaster artifacts <job_id> 读取工件；用 python -m puppetmaster dashboard 打开实时看板。可用 puppetmaster platform reviewer codex 指定平台角色；可用 PUPPETMASTER_AUTO_INVOKE_DISABLED=1 关闭自动委派钩子。首次运行路由可用 puppetmaster setup --verify-first-run codex/<model> 验证。
这个 Agent 与同类方案有什么区别？
README 明确将 Puppetmaster 与 LangGraph 和 CrewAI 定位区分：后者帮助构建智能体本身，而 Puppetmaster 是协调已有智能体 CLI 和适配器的上层控制平面，详见仓库的 WHY.md 和 COMPARISON.md。