Claude Code plugin eval：把插件行为送进 CI

Claude Code 2.1.269（2026 年 9 月 11 日）新增命令 claude plugin eval：把插件对着一套用例跑隔离会话，打出可复现分数，并给出 JSON 与 HTML 报告。官方文档写明，最低版本是 2.1.269；评测、judge 以及 claude plugin eval init 都会计入你的套餐用量或 API 账单，命令打印的费用是这些调用的标价估算。第二天的 2.1.270 只修了长时间会话里只读 git 命令误弹权限的回归，不是本文事件。

Claude Code plugin eval 官方 HTML 报告示例，展示 WITH 分数、基线差值 Δ 与 grader 结果 — 官方文档中的 plugin eval 报告示例：套件分数、Ablation Δ、阈值通过情况，以及 skill-fired 这类不计入 Δ 的指示器。来源：Claude Code「Test plugins with evals」。

插件作者以前的摩擦很具体：改了 skill 的 description，只能在自己会话里多打几句，看 Claude 会不会调用。模型一换、提示词一变，手测结论就作废。CI 里最多跑 claude plugin validate 查 schema，查不了「用户原话会不会触发技能」。本文要回答的是：这套评测怎么从输入跑到门禁，以及分数通过时人还该看什么。

AI Coding 交流群

如果你也在用 AI 写代码，或者正在研究 Cursor、Claude Code 这些工具，欢迎加入以下交流群。群里平时会聊一些 AI 编程的实际用法、开发工作流，还有各种新工具和新玩法。

发生了什么

changelog 原文是：Added claude plugin eval，对插件跑 eval suite，拿到打过分的可复现结果（JSON + HTML 报告）。配套还有 claude plugin eval init：它会读插件、问你什么叫好结果、试跑一遍，再把用例写进 evals/。也可以从已打开的会话里让 Claude 执行同一条 init。用例格式和 skill-creator 插件用的 evals/evals.json 不是同一套；查语法用 claude plugin validate，查行为才用 eval。

一次运行的机制写得很硬。每个用例默认跑 3 次（范围 1 到 50，--runs 可覆盖）；每次开一个全新的无交互会话，只加载被测插件，把 prompt 发出去，直到结束或撞上回合/时间上限。默认 max_turns 是 10、上限 200，timeout_seconds 默认 300、上限 3600。然后 grader 检查最终回复、转录或 Claude 新建的文件。默认还会再跑一轮不加载插件的基线臂，报告里出现 WITH、W/OUT 和差值 Δ。阈值默认 1.0，任一用例低于阈值则命令 exit 1。

grader 一共六种。regex、tool_used、tool_order、file_exists 从转录和文件计算，不产生模型费用；llm 和 baseline 会再调一个默认的小模型，llm 要三票里至少两票 PASS。文档特别写了：tool_used 且工具是 Skill 的检查，默认不计入两臂分数，只当「插件有没有开火」的指示器，避免把基线臂压成零、把 Δ 做虚高。没有自定义代码 grader。文档给的示例摘要是一个用例 WITH 1.00 / W/OUT 0.33 / Δ +0.67，六次运行、标价约 0.41 美元。

一次完整工作场景

输入是插件根目录，里面有 plugin.json 或 .claude-plugin/plugin.json，以及至少一个 skill。作者在根目录执行 claude plugin eval init，先回答「Trust this plugin directory?」，再在交互会话里确认哪些请求该触发技能、哪些不该。退出后执行 claude plugin eval .。一个用例就是六次运行：有插件三次、无插件三次。也可以 claude plugin eval init --bare first-case 只生成空白模板，自己写 prompt.md 和 grader。

prompt 要用用户会打的原话，而不是点名技能。官方示例是「给这次改动写 commit message」，同时用一个 llm 量结果、一个 tool_used 确认 Skill 被调用，input_match 还覆盖带命名空间的 plugin-name:skill-name。每次运行从空工作目录起步；需要夹具就写 case.yaml 的 context.scaffold_script，而且脚本只在你显式传 --scaffold 时执行。

操作中最关键的不是命令本身，而是授权边界。运行不会停下来问权限。只读工具（Read、Glob、Grep、Skill 等）可以写在用例的 allowed_tools 里；Bash、Write、Edit、WebFetch、WebSearch 必须用 --allow-tools 显式授予。默认不启动插件的真实 MCP 服务器，只吃 evals/mocks/ 里的假响应；mock 的 expect: 不满足会把该次运行判 0 分并记为 aborted。想打真实服务，要加 --allow-real-servers 或 --mocks off，而且这些进程在 agent 沙箱外、以你的身份跑。

交付物是 evals/results/<时间戳>/ 下的 aggregate-result.json 和自包含的 report.html（不发外部请求，可直接当 CI 附件）。有 claude.ai 订阅时还可能打印一条 Published: 私有制品链接；CI 里应加 --no-publish。反馈回路是看 Δ：若 Δ 接近零且 tool_used: Skill 失败，文档把这当成真实发现——skill 的 description 没对上用户原话，而不是评测坏了。

六种 grader 类型与评测隔离边界说明图 — 编辑绘制：六种 grader 的计分方式，以及 hooks、真实 MCP、Windows 无沙箱后端等人必须接管的边界。事实来自官方文档，不是产品截图。

为什么这会改变插件发布工作流

以前「插件有没有用」停在作者的聊天窗口。现在输入变成一套可提交的 evals/ 目录，输出变成 exit code 和 schemaVersion: 1 的 JSON。官方给的 CI 示例是：--trust-plugin 跳过信任提问、--json results.json 归档、--threshold 0.8 放宽满分门槛、同时钉死 --model 和 --judge-model，再加 --max-cost-usd。exit 0 表示全部达标；1 是分数不够、文件加载失败、找不到用例或未信任；2 是费用天花板或凭证失败的部分结果，JSON 里会带 partial: true；130/143 对应中断和 CI 超时。HTML 报告写失败不会改 exit code。

因果链是：模型会换、skill 文案会改、MCP 工具名会变。没有基线臂，你分不清「Claude 本来就会」和「插件把它教会了」。有了 Δ，发布门禁才能卡在「插件贡献」而不是「模型碰巧答对」。并发 -j 只允许 1 到 8，共享账号速率限制，所以它缩短墙钟时间，并不提高超过限额的吞吐。如果 evals/ 已被别的工具占用，可在 plugin.json 写 "experimental": { "evals": "quality/evals" }，或命令行传 --eval-dir；绝对路径和 .. 不被接受。

限制与人必须接管的点

文档把信任写得很直白：对目录跑 eval 等于 claude --plugin-dir 的同一信任决定，套件通过不证明插件安全。隔离只限制被测 agent：一次性 HOME 和工作目录，不加载你的 CLAUDE.md、其他插件和记忆；评测目录对 agent 隐藏。但插件自带的 hooks、你启动的真实 MCP，都在沙箱外运行，可能改动 grader 要读的文件。管理端下发的 managed settings 仍会限制评测会话，托管机器上的分数可能和管理员策略外的机器不一致。

Windows 原生没有沙箱后端。只要授予 Bash 或 PowerShell，无后端的机器会直接拒绝运行，而不是裸跑；官方要求这类套件走 WSL2，Linux 上先装 bubblewrap 和 socat。file_exists 只认本次运行新建的文件，脚手架创建或仅被 Edit 改过的文件对它不可见。费用上，每个 llm/baseline grader 每次运行大约再加三次短 judge 调用。迭代时应用 --case、--runs 1、--ablation none 降成本，改完再回到默认三轮。changelog 里的 CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS 是 Workflow 工具的并发上限（1–256），不是 plugin eval 的 -j，不要混用。

如何试用

先 claude --version，低于 2.1.269 就 claude update。在插件根目录跑 claude plugin eval init，再 claude plugin eval .。CI 模板按官方文档复制，钉模型和费用上限。如果看到 “plugin eval is currently in early access”，说明构建早于正式提供，更新后再开新会话。若提示 “plugin eval is currently unavailable”，那是服务端关闭，本机改不回来。