plzebo

plzebo

用于 Agent 循环的成本平价基准测试。指定两种或更多完成同一任务的方式（更便宜的模型组合、不同的配置、开启或关闭某个工具），它会测量哪种方式能以更低的成本交付结果，分别以美元和分钟计，并判断差异是真实存在还是随机噪声。可在本地运行，使用你自己的密钥或订阅。Agent 还能通过 MCP 在自身上调用它。

核心指标是每次成功结果的成本：计量总支出除以成功次数，并通过 95% 置信区间比较各组。旁边还会报告每次成功结果所需的时间。当数据不足以支持某项结论时，plzebo 会如实说明，而不是贸然下结论。

测量方式

• 每组都是完整循环。 一组是一个 shell 命令，用于让 Agent 完成某项任务；另外还包括应用于本地计量网关的模型改写规则。各组的循环代码可以完全相同，而网关会将每个 claude-* 调用映射到对应组的模型。
• 每次模型调用都经过网关。 各组会收到一个占位密钥（sk-placebo-...）和一个重定向的基础 URL；网关会在上游替换为真实密钥，并记录每次调用中由提供商报告的 token 用量。绕过网关的调用会在提供商处失败，而不会在无记录的情况下产生费用；计量调用数为零的试验会被标记，绝不参与比较。
• 试验采用配对交错方式。 K 对试验会连续运行，每对的组别顺序由预先设定的随机硬币翻转决定，使提供商状态变化落在配对之内。提示词缓存会被禁用，并且每次试验都会带有唯一随机数，确保某组不会为另一组预热缓存。
• 评分绝不信任 Agent 的工作树。 差异会根据受保护路径列表（测试、运行器配置）进行筛选，应用到干净的检出副本上，并在那里运行测试命令。修改测试会导致试验失败。
• 统计结果不会夸大结论。 成功率差异使用经 Holm 校正的精确 McNemar 检验。判断是否平价需要进行等效性检验，不能仅凭显著性检验未通过。成本和时间差异来自配对自助法。任一方成功次数少于 5 次时，不会对成本作出判断。超时会被判定为失败，且计入支出；崩溃和提供商限流（429/529）会被排除，并披露相关支出。每次拒绝下结论时，都会明确打印一行“不得作出结论”的说明。
• 收据就是产出物。 每次运行都会生成一份 JSON 收据，包含规格及其预注册哈希、每次试验的原始行（token、每次调用状态、变更路径、输出末尾内容）、统计输入、定价表版本，以及自动生成的估计目标说明。plzebo verify receipt.json 会根据原始行重新计算每个派生数值，并报告任何差异。

要求

Node 22.6 或更高版本（CLI 会通过 Node 的类型剥离功能运行 TypeScript 源文件；对于需要该标志的版本，启动器会提供该标志）。还需要 Git，以及各组和预言机所需的其他依赖（此处示例为 python3）。

快速开始

npx plzebo run spec.yaml --estimate   # prices the run from prior receipts; spends nothing
npx plzebo run spec.yaml              # runs the experiment
npx plzebo verify <receipt.json>      # recompute a receipt's claims from its raw rows

规格示例：

name: sonnet-vs-opus
fixture:
  repo: ./my-fixture-repo        # a git repo; every trial gets a fresh clone
  ref: main
task: "Make the failing tests in this repo pass. Do not edit the tests."
arms:
  sonnet:
    cmd: claude --print "$PLZEBO_TASK" --dangerously-skip-permissions --strict-mcp-config --mcp-config '{"mcpServers":{}}' --model claude-sonnet-5
    auth: passthrough            # runs on your logged-in Claude subscription
    rewrite:
      claude-*: claude-sonnet-5  # pin every call this arm makes, including auxiliary ones
  opus:
    cmd: claude --print "$PLZEBO_TASK" --dangerously-skip-permissions --strict-mcp-config --mcp-config '{"mcpServers":{}}' --model claude-opus-4-7
    auth: passthrough
    rewrite:
      claude-*: claude-opus-4-7
baseline: opus
oracle:
  cmd: [python3, -m, unittest, discover, -s, tests, -t, .]
k: 3
trialTimeoutMs: 600000
budgetUsd: 30                    # hard kill switch enforced at the gateway

每次运行都会在首次试验前打印成本估算。未设置预算时，运行会被拒绝。建议从较小的 K 开始：对于无法得出结论的运行，报告会打印解决问题所需的确切 K 值和预计成本；plzebo extend <receipt.json> --to-k K 则会复用你已付费完成的试验。每份收据只能扩展一次，扩展操作会在收据中披露。

认证模式

• auth: placebo（默认）：导出 ANTHROPIC_API_KEY 或 OPENAI_API_KEY；各 arm 只能看到安慰剂密钥。计量保障最强：绕过网关的调用会明确报错。
• auth: passthrough：arm 使用自己的登录账号。不消耗 API 额度；根据计量的令牌数按公开定价推算美元费用，并在收据中说明这一点。无论哪种模式，令牌数都是事实依据。已验证适用于 Claude Code；它在订阅认证下会遵循 ANTHROPIC_BASE_URL。使用 ChatGPT 认证的 Codex 会路由到自己的后端并忽略 OPENAI_BASE_URL，因此无法计量使用订阅认证的 Codex；请改用 codex-cli 模板，以 API 密钥模式运行 Codex arm。

passthrough arm 有两点注意事项。绕过计量器的试验会被排除，不会被错误计入，但它在上游消耗的令牌是真实的，收据无法看到这些令牌。此外，个人登录账号会携带个人 Agent 配置：指令、钩子和记忆文件都会随账号一起生效，这可能会增加成本；对于会依据常驻指令采取行动的 Agent，还可能导致在试验工作区之外写入内容。比较工作循环时，优先使用隔离配置模板，而不是自己的配置。

混合模型 arm（编排器和工作器使用不同模型）

收据中的每个成本节点都会记录两个模型：role 是工作循环请求使用的模型，model 是 arm 的重写规则将其解析到的模型。因此，如果工作循环为不同任务请求不同模型（主会话使用一个模型，子 Agent 使用另一个模型），收据就会记录其角色结构；而使用相同命令的 arm 可以仅通过重写规则为这些角色绑定不同模型：

arms:
  mixed:
    cmd: sh scripts/arms/subagent-mix.sh   # opus main session + a worker agent definition requesting sonnet
    auth: passthrough
    rewrite:
      claude-opus-*: claude-opus-4-7       # orchestrator stays opus
      claude-sonnet-*: claude-sonnet-5     # workers stay sonnet
      claude-*: claude-opus-4-7            # catch-all LAST: wildcard rules match in order after exact keys
  all_opus:
    cmd: sh scripts/arms/subagent-mix.sh   # byte-identical loop; only the mapping differs
    auth: passthrough
    rewrite:
      claude-*: claude-opus-4-7

打包的 scripts/arms/subagent-mix.sh 展示了 Claude Code 的用法：运行无头会话，并通过内联的 --agents 定义，让工作器请求与主会话不同的模型。请根据任务调整 Agent 提示词和模型。

只有在工作循环确实进行了委派时，混合模型比较才有效：如果某次试验的成本树中没有工作器角色调用，测量到的就是单独运行，而非混合运行。

npx plzebo fidelity <receipt.json|run-dir>        # per-trial requested -> resolved counts
npx plzebo fidelity <run-dir> --worker "claude-haiku-*"

如果任何已完成的试验都没有进行工作器角色调用，fidelity 会以状态码 1 退出；它还会按请求模型和解析模型分组，打印每次试验的调用数、令牌数和推算支出，因此可以通过收据核验 arm 声称的模型组合。

提供方

网关支持两种线协议格式：Anthropic 和兼容 OpenAI 的格式，后者覆盖大多数开放权重模型服务（Ollama、vLLM、OpenRouter、Together 等）。各 arm 可单独覆盖提供方：

arms:
  local-qwen:
    cmd: my-loop --task "$PLZEBO_TASK"
    upstreams:
      openai: http://127.0.0.1:11434   # any OpenAI-compatible server
  gpt:
    cmd: my-loop --task "$PLZEBO_TASK"
    keysFrom:
      openai: OPENAI_API_KEY           # env var NAME; specs never contain key values

限制：plzebo 只能计量使用密钥或令牌进行认证，且遵循可重定向基础 URL（ANTHROPIC_BASE_URL / OPENAI_BASE_URL）的工作循环。

MCP

npx plzebo-mcp 通过 stdio 提供四种工具：measure_start、measure_extend、measure_status 和 measure_result。启动测量分为两个阶段：第一次调用会验证请求，并返回费用估算和一次性确认令牌，不会产生任何费用；只有第二次调用提供该令牌后，才会运行试验。预算为必填项，MCP arm 只能使用具名模板（claude-cli、claude-subscription、codex-cli），不能使用原始 shell。作业状态和收据会保存在 .plzebo/ 下，因此即使生成它们的会话结束，评估结论仍会保留。

收据能说明什么，不能说明什么

收据是在指定模型映射下针对单项任务得出的结果。它不是模型能力排名，也不能推广到其测试样例之外；收据中的估计目标文本会对此作出明确说明。passthrough arm 的美元金额是根据计量的令牌数和定价表费率推算得出的，并非实际账单支出；定价表版本也会随收据一并记录，以便价格变更后仍可重新计算这些数字。

许可证

MIT