技能效果测量仪 edonadei/caliper

Caliper

看清你的智能体技能到底管不管用。

你试的时候技能是管用的。接下来九次还管用吗？
下一次模型更新之后呢？另一个技能来抢同一段提示词的时候呢？

快速开始 • 工作原理 • 文档 • 入门套件

同样的任务，带技能和不带技能各跑一遍。裸智能体本来就有 80% 通过率；加上技能后升到 100%，token 少用 30%，耗时少 28%。

为什么选 Caliper

真实安装 技能装在智能体会去找的位置，绝不直接粘进提示词。

激活记分板 智能体到底有没有挑中你的技能？这一项单独计分，和技能是否生效分开看。

竞争环境 声明互相竞争的技能，断言每段提示词该由哪个胜出。

消融测试 --ablate 会在不带技能的情况下重跑。分数一样？那它没挣到自己的上下文。

诚实的数字 先看单次成功率。pass@k 会美化不稳定的技能。

四种智能体 Claude Code、Codex、Pi、Hermes。一份规格，运行时再挑引擎。

快速开始

🤖 在你的智能体里 ⌨️ 在你的终端里

npx skills@latest add edonadei/caliper

then, in your agent:
/grill-skill ./inbox-triage/SKILL.md

grill-skill 会来访谈你，写出 spec，然后分别在没有你的技能和带上你的技能两种情况下运行它。

pipx install caliper-eval
SPEC=inbox-triage/inbox-triage.eval.yaml

caliper run $SPEC --ablate inbox-triage
caliper run $SPEC
caliper compare \
.caliper/results/inbox-triage/RUN_ID.json \
inbox-triage

写一份 spec

spec 就是放在技能旁边的 .eval.yaml 文件。里面列出要安装的技能（你自己的，再加上可能抢同一批提示词的邻居技能），以及要跑的任务。每个任务包含一条提示词、可选的 setup:，以及至少一项检查：

- expect: 由 LLM 裁判打分。
- assert: 在本次尝试的工作目录里以 Python 本地运行，限时 30 秒。超时的检查没有判定结果，但不会让任务失败。
- activates: 断言智能体选择加载了哪些技能。它不需要裁判，所以成本只有打分任务的一小部分。

inbox-triage.eval.yaml
skills:
- ./SKILL.md # the skill under test
- ../calendar-scheduler/SKILL.md # a neighbour it might steal work from

tasks:
- name: Flags emails that need a reply
setup: >-
mkdir -p inbox
&& printf 'From: Dana\nSubject: Contract\n\nCan you confirm the start date?\n' > inbox/1.eml
&& printf 'From: Weekly Digest\nSubject: 10 links you missed\n\n...\n' > inbox/2.eml
prompt: "Triage my inbox."
expect: Only Dana's email is flagged as needing a reply, and nothing is sent.

- name: Drafts replies, never sends them
setup: >-
mkdir -p inbox drafts outbox
&& printf 'From: Dana\nSubject: Next week\n\nDoes Thursday work?\n' > inbox/1.eml
prompt: "Reply to Dana and tell her Thursday works."
assert: |
from pathlib import Path
assert any(Path("drafts").iterdir()), "no draft written"
assert not any(Path("outbox").iterdir()), "sent instead of drafting"

- name: Booking a meeting belongs to calendar-scheduler
prompt: "Dana wants to meet next week. Find us 30 minutes."
activates: [calendar-scheduler]

完整的六任务版本，带一条提示词注入和一次静默探测，见 docs/spec-reference.md。

spec 从不指定引擎。技能默认跑在 claude-code 上，除非你用 --model 另选一个；裁判默认跑在同一个后端上，除非你用 --judge-model 另选一个（见选择引擎）。

读输出

caliper run inbox-triage.eval.yaml

下面是完整的六任务示例，使用默认的 k=3：

这里技能通过了每一项任务（100%），但它也接下了 3 个会议请求中的 2 个，而这些请求本该归 calendar-scheduler 管。这是 description 的问题，不是正文的问题。每次失败的尝试都会配一个面板，显示输出和失败原因。完整结果以 JSON 保存到 .caliper/results/<spec>/ 下。

不确定 spec 里该写什么？

Eval Starter Pack 里有五个可以直接复制的模板，每个都对应一种真实的智能体故障（假成功、工具误用、失控循环、提示词回归、把过期上下文当成当前上下文）。每个模板都能原样跑通自带的示例，然后你只要改两三行带注释的配置，就能指向自己的技能。

文档

| 📐 Spec 参考 | .eval.yaml 的每个字段和判定规则 |
| 🔌 后端 | 各智能体的配置方式、--model 语法、MCP 支持 |
| 📊 结果 | 评分、caliper compare、结果 JSON schema |
| 📖 术语表 | Spec、邻域、激活、消融…… |
| 🧭 设计决策 | 架构决策记录 |

推荐工作流

1. 针对你关心的某个行为写一份 spec。
2. 迭代 spec 时用 --k 1 跑。
3. 对 LLM 评委可能猜错的事实（文件、JSON、命令输出）加上 assert:。
4. 改技能之前，先用 --ablate <skill>（或 --ablate mcp:<server>）在 --k 3 下跑一次，再用 caliper compare 和完整运行对比。不带技能也能通过的任务，说明它不需要这个技能：先把技能打磨好。消融运行只依赖任务，所以留着它，技能一变就重新对比。
5. 在 --k 3 下迭代技能，确认是进步还是退步要用 --k 5 或更高，再据此行动。
6. 把 spec 和技能一起提交，这样贡献者能跑同一套评测。

工作原理

.eval.yaml spec
│
▼
Harness ──── runs your skill in the agent (Claude Code / Codex / Pi / Hermes)
│
▼
Judge ──── LLM autorater and/or deterministic Python assertions
│
▼
success rate + saved transcript

每次尝试都在一个隔离的临时 home 里运行，没有会话历史，工作目录也是全新的空目录。默认情况下它会加载你的用户自定义配置：你的命令行工具的 MCP 服务器、账号连接器、用户技能、插件、规则和设置。声明的技能和服务器在名称冲突时胜出，即使被消融时也是如此。用户技能与声明的技能竞争，并计入激活检查。命令行工具自带的技能（Claude Code 的 claude-api）显示为内置技能，且从不评分。Hermes 保持其中立的记忆/人格策略；参见后端详情。钩子作为尝试的一部分运行，受其超时约束。结果保存为 JSON，你可以稍后检查并对比差异，包括每次运行加载了哪些用户自定义项（当后端无法列出其 MCP 服务器时为 mcp:(not listed)）。

可移植分数

默认分数取决于你的设置。当这个数字在另一台机器上必须表示相同的含义时，隔离运行，使其只看到规范声明的技能和服务器：

- caliper run spec.eval.yaml --no-user-customizations 用于单次运行；
- 在规范中设置 user_customizations: false 用于其每次运行。

每当你比较后端（--model claude-code 与 --model codex）、与别人的运行结果比较，或发布分数时，都要隔离。每个命令行工具加载不同的设置，否则差异的一部分就是设置本身。caliper compare 会在两次运行加载不同内容时发出警告。

核心概念

| 术语 | 是什么 |
| 规范 | 一个 .eval.yaml 文件，描述要运行的技能和任务 |
| 后端 | 运行技能的命令行工具智能体（claude-code、codex、pi、hermes） |
| 评判器 | 决定通过/失败的东西：读取转录的 LLM（expect:）、Python 断言（assert:），或两者兼有 |
| 成功率 | 主要分数：运行 k 次，测量单次运行成功的频率 |
| 邻域 | 规范声明的技能集合（skills:）。全部安装，无一预加载，且全部可断言。这是你的 description 必须赢得的竞争 |
| 激活 | 智能体选择加载技能。用 activates: 断言，并在自己的记分板上评分，与成功率分开 |
| 消融 | 用移除的声明技能或 mcp: 服务器（--ablate）重新运行相同的任务，以证明它在做工作 |
| 尝试 | 单个任务的一次隔离运行（全新的临时主目录，无会话历史） |

完整术语表见 docs/CONTEXT.md。

选择引擎

引擎（后端 + 模型）在运行时选择，而非在规范中。规范描述测试什么以及如何评判成功；你在调用 Caliper 时选择运行和评分它的智能体。被评估的模型（--model）默认为 claude-code，评判器默认为相同的后端：

caliper run my-skill.eval.yaml # claude-code runs and grades
caliper run my-skill.eval.yaml --model codex # codex runs and grades, default models
caliper run my-skill.eval.yaml --model codex:gpt-5.6-sol
caliper run my-skill.eval.yaml --model pi --judge-model claude-code
| 后端 | 依赖 |
| claude-code | 已安装并完成认证的 Claude Code 命令行 |
| codex | Codex 命令行（npm install -g @openai/codex），然后执行 codex login |
| pi | pi 命令行（npm install -g @earendil-works/pi-coding-agent），已完成认证 |
| hermes | Hermes Agent 命令行（Nous Research），已完成认证，并设置了默认模型 |

评判器默认使用被测模型所在的后端（--model），跑在该命令行的默认模型上；除非用 --judge-model 指定了模型。所以你可以用 Claude 评判器去测 Codex 技能。对比不同引擎时，每次运行都要传同一个 --judge-model：否则每个引擎都给自己打分，caliper compare 会警告评判器不一致（ADR 0034）。没有直连 API 的后端：想用 API 计费，就给这些命令行之一配置 API key。

各后端的安装细节、--model 的完整语法、以及各后端对 MCP 的支持，都在 docs/backends.md。

规格格式

快速上手已经覆盖了基础用法。规格还可以：

- 从 git 仓库拉取邻近技能，并固定到某个提交（skills: - {repo: owner/name, ref: …, path: …}）
- 给智能体配上 MCP 服务器，本地或远程都行（mcp:）
- 固定你自己的定制是否加载：user_customizations: false 得到任何人都能复现的可移植分数，true 则用于依赖你自己连接器的技能
- 在每次尝试的工作目录里运行 setup: 和 cleanup: shell 钩子（各自超过 600 秒即被终止）
- 扩展 PATH，或禁止智能体读取某些文件（sandbox:）
- 断言静默（activates: []）或委派链（activates: [mine, helper]）

完整格式和所有字段都在 docs/spec-reference.md。想生成规格骨架，用 grill-skill 或 evaluate-skill。

要升级已有的规格？ skill: 在 v0.10 变成了 skills:。见 docs/MIGRATING-to-skills.md。

命令行参考

| 命令 | 说明 |
| caliper run <spec> | 运行一份评估规格 |
| caliper validate <spec> | 校验规格文件 |
| caliper list [spec] | 列出规格和已保存的运行。每份规格的每一行显示它的 Run ID，以及那次运行消融了什么，方便你找到要对比的运行 |
| caliper report <spec-or-result> | 重新渲染已保存的结果 |
| caliper compare | 逐任务对比同一评估的两次已保存运行。每一侧可以是规格名（该规格的最新运行），也可以是结果 JSON 路径；两者必须是两次不同的运行 |
| caliper update-cli [backend] | 检查或更新已安装的智能体命令行版本 |

结果保存在 git 仓库内、你运行 Caliper 的位置或其上层最近的 .caliper/ 目录下。见结果保存在哪里。

caliper run 参数

| 参数 | 默认值 | 说明 |
| --k INT | 3 | 每个任务的尝试次数 |
| --ablate NAME | 无 | 去掉这个已声明的技能或 mcp: 服务器再跑（可重复；要跑裸智能体，就把每个技能和 mcp: 服务器都点名，并加上 --no-user-customizations）。当技能和 mcp: 服务器同名时，用 skill:/mcp: 限定 |
| --workers INT | 4 | 并行运行的尝试数，跨所有任务 |
| --timeout INT | 120 | 每次尝试的秒数 |
| --fail-fast INT | 0 | 连续 N 次 infra_error/timeout 尝试后停掉任务（0 表示关闭；数的是尝试次数，不是调用次数） |
| --model TARGET | claude-code | 被评估的模型：backend、model 或 backend:model（语法） |
| --judge-model TARGET | --model 的服务商 | 评判引擎，语法相同 |
| --user-customizations / --no-user-customizations | 取 spec 里的 user_customizations，否则开启 | 把你的用户技能、插件、规则、设置和连接器加载进尝试，或者隔离。见 Portable scores |
| --verbose | 关闭 | 显示每个任务及其 expect，以及每次尝试的评判理由和评判脚本 |
| --output PATH | 无 | 同时把结果 JSON 存到指定路径 |

退出码

| 码 | 含义 |
| 0 | 跑完了，且没有任何要求裁决的地方给出否定 |
| 1 | 输入有误：找不到 spec、spec 无效、技能无法解析、两个引用指向同一次运行 |
| 2 | 无法干净地运行：服务商配置错误、模型不可用、setup/cleanup 钩子失败，或每次尝试都是 infra_error/timeout/judge_error |
| 3 | 保留：干净地跑完了，但没达到声明的门槛 |
| 130 | 被 Ctrl-C 中断；部分运行结果已保存 |

2 和 3 正是 CI 需要的区分：评估跑不起来是流水线坏了，而技能没达到门槛才是你要的答案。

如果一次运行里每次尝试都是 infra_error、timeout 或 judge_error，退出码为 2，并打印各自的计数：结果会保存下来供检查，但它什么都没测到。有一次可用尝试就够 0 了，而全是 not_checked 的触发探测也退出 0，因为它没要求任何裁决，也没出问题。

如果一次运行在任何尝试完成之前就停了，就不会写结果文件，除非某个生命周期钩子失败、它的诊断信息需要保存。所以退出码 2 和 130 可能什么都不留在磁盘上。

caliper compare 故意不会因为回归而失败。任何下降它都会标出来，而在 k 很小时，噪声触发它的频率和真实变化差不多。设门槛应该放在运行前你定好的标准上，这正是退出码 3 保留的用途。

评分

主分数是原始成功率：单次运行能成功的频率，统计范围是那些得到公平机会的尝试。速率限制、超时和评判错误都记为不可用并排除在外，所以基础设施噪声永远不会算作技能失败。

| 你想问的问题 | 指标 | 对一个 1/3 的技能（k=3） |
| 单次运行有多可靠？（默认） | 成功率 | 33% |
| 如果重试最多 k 次，只要赢一次就算成功吗？ | pass@k | 70% |
| 每次运行都能成功，没有例外吗？ | pass^k | 4% |

pass@k 和 pass^k 在 --verbose 下显示。每次运行还会记录每次尝试的 token 和实际耗时，这样你既能看到技能是否有效，也能看到它的开销。不跟踪美元成本，因为不同后端之间不一致。

尝试结果、重试、Ctrl-C 行为、caliper compare 深入用法，以及结果 JSON schema 都在 docs/results.md。

故障排查

codex judge failed: model ... is not supported
你的 Codex 账号无法使用该模型。换一个 codex exec --model <name> 能接受的模型。

hermes could not run the requested model
服务商拒绝了 --model hermes:<provider>/<model> 中的模型。这种情况下 Hermes 会正常退出，所以 Caliper 从它的输出里读到拒绝信息，直接停止运行，而不是去给一个空答案打分。用 hermes -z 'Reply OK' --model <model> 检查模型 ID。

Judge model ... is unavailable / Judge authentication failed / Judge rate limited
评审 CLI 连上了服务商，但调用被拒绝。Caliper 建议传入 --judge-model <backend[:model]> 来选一个可用的评审。例如：caliper run my-skill.eval.yaml --judge-model claude-code:claude-haiku-4-5-20251001。

- 评审模型不可用会让每次尝试都以同样方式失败，所以在第一次到达评审的尝试就停止运行（退出码 2），而不是给每次尝试都记一个 judge_error。claude-code 技能模型不可用（--model claude-code:<model>）时同样会停止运行。
- 认证失败或触发限流，仍然按每次尝试记 judge_error。
- --model 或 --judge-model 里出现未知后端名，会在任何尝试运行之前就被拒绝。

--judge-model ... but the ... CLI isn't installed
带 expect: 的 spec 需要评审的 CLI，所以运行会在任何尝试之前停止（退出码 2），而不是给每次尝试都记一个 judge_error：

$ caliper run hello.eval.yaml --model codex --judge-model hermes
┌──────────────────────────────── No judge ─────────────────────────────────┐
│ --judge-model hermes asks hermes to grade the expect: checks, but the │
│ hermes CLI isn't installed. │
│ │
│ Install and sign in to the hermes CLI, or remove --judge-model and codex │
│ (your --model) will grade too. │
└───────────────────────────────────────────────────────────────────────────┘

安装那个 CLI，或者去掉 --judge-model，让 --model 后端也来打分。

任务只靠 assert: 就通过了 任务只有 assert: 时，不会运行 LLM 评审。如果你还想要用 LLM 来评估对话记录。

Hermes 报错：没有选择模型 运行 hermes model，选一个默认模型和服务商，确保账号里有额度。

智能体技能

evaluate-skill：运行和管理评估

在智能体内部创建、校验、运行、汇总评估，不用再开一个终端。在 Claude Code 里：

/evaluate-skill run inbox-triage.eval.yaml --k 3
/evaluate-skill validate inbox-triage.eval.yaml

在 Codex 里：

Use the evaluate-skill skill to run inbox-triage.eval.yaml with k=3 and summarize the result.

grill-skill：交互式创建评估

grill-skill 会读取你的 SKILL.md，就「什么样的表现算好」向你提问，然后写出一份规格：正常路径、边界情况、对抗性任务，再加上针对 description 的邻近探针和静默探针。接着它运行评估：先用 k=1 把规格里的错误抖出来，再做一次消融运行，检查这些任务是否真的需要该技能，然后循环跑 k=3，与那次消融运行做 diff，把每个失败追溯到 description、正文或任务本身。

/grill-skill ./inbox-triage/SKILL.md

如果你已经在技能所在目录里，可以省略路径。如果技能旁边已经有 .eval.yaml，grill-skill 会针对缺口向你提问，而不是从头开始。

贡献

欢迎贡献。适合上手的领域、提 PR 前的检查清单、ruff 格式化约定与锁定版本，以及一次性的 pre-commit install 步骤，都见 CONTRIBUTING.md。

许可证

MIT © Emrick Donadei