claude plugin eval 针对一套测试用例运行您的插件并对结果进行评分。每个用例都是一个现实的提示加上一个或多个评分器。评分器是对 Claude 生成的内容的通过/失败检查，例如对回复的正则表达式、是否调用了特定工具，或者由第二个模型判断回复的评分标准。
您不必手动编写该套件；claude plugin eval init 会询问您关于您的插件的问题，提议用例和评分器，尝试它们，并编写文件。您也可以要求 Claude 从您已经打开的会话中执行相同操作。
使用 evals 来衡量您的插件可靠地引导 Claude 达到正确结果的程度，在您更改插件或发布新模型时捕捉回归，以及查看与无插件相比插件的贡献。
本页面适用于拥有可工作插件并想要测试其行为的插件和技能作者，以及在 CI 中对插件更改进行门控的团队。其用例格式与技能创建者插件使用的 evals/evals.json 文件分开。要创建插件，请参阅创建插件；要检查插件文件的语法和架构错误而不是其行为，请使用 claude plugin validate。
每次 eval 运行和每个评分器都是对您账户的真实模型调用，计入您计划的使用量或您的 API 账单，因此请先检查要求。然后创建您的第一个 eval 套件，或者如果您已经有一个，请转到在 CI 中运行 evals。
要求
要运行插件 evals，你需要：- Claude Code v2.1.269 或更高版本。运行
claude --version检查，运行claude update升级。 - 一个包含
plugin.json或.claude-plugin/plugin.json清单的插件目录，或一个技能目录插件。 - 与你的常规 Claude Code 会话相同的身份验证和模型提供商。Eval 运行、评判评分器和
claude plugin eval init使用你的凭证调用模型，因此它们计入你的计划使用限制或 API 账单。当命令报告成本时，该数字是这些调用的列表价格估计。
eval 运行如何工作
一个 eval 套件位于插件内名为evals/ 的目录中，布局如编写和完善用例所示。每个用例都是其自己的子目录，包含一个提示和一个或多个评分器。提示是使用你的插件的人可能输入的内容，例如其中一个技能应该处理的请求。
运行中发生的情况
对于每次用例运行，Claude Code 启动一个新的、隔离的非交互式会话，仅加载你的插件，发送提示，并让 Claude 工作直到完成或达到用例的轮次或时间限制。然后每个评分器检查最终回复、完整记录或 Claude 创建的文件，并通过或失败。用例如何评分
一次非确定性代理的运行告诉你很少，所以每个用例默认运行三次。运行的分数是其通过的评分器的比例，如果你设置了权重则加权，用例的分数是其运行的平均值。当用例的分数达到--threshold（默认为 1.0）时，用例通过。在模型调用中，一个套件大约进行 cases × runs 个代理运行，加上无插件基线的相同数量，再加上每个 llm 或 baseline 评分器每次运行三个短评判调用。
无插件基线
仅凭高分不能告诉你插件是否有帮助，因为 Claude 可能在没有插件的情况下也能做得很好。为了区分两者，默认情况下每个用例的运行会重复进行，不加载任何插件，你会得到两个分数，WITH 和 W/OUT。它们的差异 Δ 是插件贡献的内容。如果一个用例在有插件和没有插件的情况下都得分 1.0，那么插件不是使其通过的原因。这两组运行称为 with-arm 和 without-arm；与无插件基线比较涵盖了评分器如何在它们之间评分以及如何关闭基线。
创建你的第一个 eval 套件
本演练为你自己的插件编写一个用例，运行它，并读取结果。在开始之前，请确保你有：- Claude Code v2.1.269 或更高版本和其他要求
- 在你的插件根目录打开的终端，即包含
plugin.json或.claude-plugin/plugin.json的目录 - 插件中你想测试的一个技能，以及用户会输入的应该触发它的请求
1
创建用例
从插件根目录运行：如果 Claude Code 还不信任此目录，它首先会询问
Trust this plugin directory?；回答 y。然后打开一个交互式 Claude Code 会话。Claude 读取你的插件并询问你好的结果是什么样的，提议应该和不应该触发插件的提示，为每个设计评分器，试运行一次以检查它们的行为，并在 evals/ 下为每个提示写一个用例目录，每个都以其提示命名。当 Claude 告诉你套件已准备好时，使用 /exit 或 Ctrl+D 退出该会话以返回到你的 shell。如果你已经在插件根目录打开了 Claude Code 会话，你可以改为要求 Claude 在那里运行 claude plugin eval init。Claude 运行命令，然后在该对话中询问你相同的问题。如果你宁愿自己编写一个用例以准确查看文件包含的内容，请按照手动编写用例进行，然后回到这里运行它。2
运行套件
回到你的 shell 中的插件根目录，运行 你已经在第 1 步中信任了此目录，所以运行立即开始。如果你改为手动编写了用例，运行首先会询问
evals/ 下的每个用例：Trust this plugin directory? [y/N]；回答 y。运行可以访问什么解释了你同意的内容。每个用例使用你的插件运行三次，不使用插件运行三次，所以一个用例是六次运行。当每次运行完成时，会打印一条进度线，显示该运行的分数和每个评分器的判决。3
读取摘要
当套件完成时，你会看到一个摘要表，然后是报告的位置：
WITH 是加载你的插件的用例分数，W/OUT 是不加载插件的分数，正的 Δ 意味着插件提高了分数。COST 是模型调用的列表价格估计，NOTES 显示最高权重失败评分器的解释，或来自 with-arm 的运行错误。4
打开报告并迭代
打开 将
Published: URL，或当没有 Published: 行出现时打开 Report: 路径，以查看每个评分器对每次运行的判决和解释，以及对于 llm 评分器的评判的投票和它评判的摘录。Published: 行仅在你的账户可以发布报告时出现。最常见的第一个发现是 Δ 接近零，用例的 tool_used: Skill 评分器失败，这意味着 Claude 在自然措辞上没有选择你的技能。调整技能的 description，再次运行 claude plugin eval .，并进行比较。要廉价地迭代单个用例，运行单个 arm 一次。单次运行噪声很大，所以在信任任何更改之前，在默认三次运行时确认它。使用一个 arm，表格显示 SCORE 和 PASS% 列而不是 WITH、W/OUT 和 Δ：<case-name> 替换为 evals/ 下的目录名之一。编写和完善用例
claude plugin eval init 编写的用例是你可以打开、更改和添加的纯文件。用例是插件 eval 目录下的一个目录，包含 prompt.md、case.yaml 或两者。要对用例进行分组，将它们嵌套在不是用例本身的目录下；用例目录内的任何内容，例如 graders/ 和 fixture 文件，都属于该用例。
这是 claude plugin eval init 编写的布局，也是新套件要使用的布局。eval 套件参考有完整的树，包括 mocks 和结果：
手动编写用例
让 Claude 使用claude plugin eval init 编写用例是推荐的路径。要自己编写一个，请从空白模板开始。以下命令编写一个名为 first-case 的用例，带有占位符 prompt.md 和一个占位符评分器，并且不运行任何内容：
prompt.md 中，你编写 Claude 在每次运行中接收的消息，并在其 frontmatter 中设置运行的限制和用例可能使用的工具。打开 evals/first-case/prompt.md 并用你的请求替换占位符正文，措辞方式应该是用户会输入的方式而不是命名技能。这个例子是针对起草提交消息的技能；使用你自己的请求：
graders/ 下的每个文件都是运行后应用的一个检查。打开 evals/first-case/graders/criteria.md 并用评判模型的评分标准替换占位符，写成具体的 PASS 和 FAIL 条件：
evals/first-case/graders/skill-fired.md，将 your-skill-name 替换为你的技能 SKILL.md 中的 name：
plugin-name:skill-name 形式。评分器类型列出了其他可用的检查，例如匹配正则表达式或确认文件已创建。
保存两个文件后，按照快速入门的方式运行用例，使用 claude plugin eval . 从插件根目录。
在 prompt.md 中设置运行限制和工具
在prompt.md frontmatter 中设置用例的 max_turns、timeout_seconds、model、tags 和它可能使用的 allowed_tools；prompt.md frontmatter 参考列出了每个字段及其默认值。Claude 接收正文完全按照你编写的方式。其中的 @path 提及不会扩展为文件附件，所以如果 Claude 需要读取文件，请在 allowed_tools 中为其授予工具。
选择和加权评分器
评分器的 frontmatter 设置其type，以及可选的 weight 使其在运行分数中计数更多，以及一个arm来控制它如何针对基线评分。在六种类型中，regex、tool_used、tool_order 和 file_exists 从记录和文件计算，成本为零，而 llm 和 baseline 调用评判模型并增加运行成本。
没有自定义代码评分器。评分器类型列出了每种类型的选项和通过条件，评分器可以查看什么列出了 target 和 focus 接受的值。
llm 和 baseline 评分器的评判默认是一个小型快速模型。传递 --judge-model sonnet 或完整模型 ID 以对细致的评分标准使用更强大的模型。
选择提供稳定信号的评分器
llm 评分器要求模型做出判决，所以其答案可能在运行之间不同，并且它读取的文本越长差异越大。这些习惯使套件的分数足够稳定以信任：
- 对于长输出（例如生成的文件），使用
regex评分器对文件内容进行评分，它以相同的方式每次检查整个文件。为短输出保留llm评分器，使用具体的 PASS 和 FAIL 条件编写评分标准。 - 为每个用例提供一个关于结果的评分器，例如最终消息或生成的文件，以及一个关于 Claude 如何到达那里的评分器，例如
tool_used或tool_order。它们一起告诉你答案是否正确以及你的插件是否产生了它。 - 如果用例的
tool_used: Skill评分器通过但Δ为负，怀疑评判而不是插件。小型评判模型可能会因为格式与评分标准描述的不同而将正确答案标记为错误。使用--judge-model sonnet重新运行，并收紧评分标准，使格式不会决定判决。 - 要检查构建或测试在运行内通过，让提示要求 Claude 运行它并将结果写入文件，评分该文件，并使用
tool_used评分器断言命令运行，其input_match命名该命令。
针对无插件基线评分
当插件处于测试中时，默认情况下每个用例在两个 arm 中运行。with-arm 是其加载插件的运行，without-arm 是相同数量的不加载任何插件的运行。摘要和报告显示两个分数和Δ，即 with-arm 分数减去 without-arm 分数。传递 --ablation none 以仅运行 with-arm，当你不需要比较时（例如在迭代评分器时）将成本减半。
在两个 arm 运行中，某些评分器报告为 scored: false。像”技能被调用”这样的检查在没有插件的情况下永远无法通过，所以计数会将 without-arm 推向零并夸大 Δ。为了保持两个 arm 可比较，Claude Code 在两个 arm 中排除此类评分器的分数，并在 with-arm 中仅将其报告为通过/失败指示器。这包括：
- 每个
tool_used评分器，其tool是Skill - 任何你标记为
arm: with-only的评分器
arm: both 以在两个 arm 中评分它，无论如何，这是你想要的”不得调用技能”检查，带有 min: 0 和 max: 0。在 --ablation none 下，没有任何内容被排除，所以相同的套件在两种模式中可能产生不同的绝对分数。
使用不同的 eval 目录
如果evals/ 已被另一个工具占用，请将套件保留在不同的目录中。你可以在插件的 plugin.json 中记录该目录，以便每次运行和每个协作者都使用它，或在命令行上为单次运行传递它：
- 在
plugin.json中：添加"experimental": { "evals": "quality/evals" }。 - 在命令行上：将
--eval-dir quality/evals传递给claude plugin eval和claude plugin eval init。
qa 或 quality/evals；包含 .. 的绝对路径或路径被拒绝：作为标志值时是错误，而不可用的清单值会打印 Warning: 行，运行使用 evals/ 代替。用例、结果和 init 输出都移动到该目录。
设置 fixtures 和 mocks
用例可能需要的不仅仅是提示：工作区中的文件或 git 存储库、要继续的早期对话，或来自你的插件与之通信的 MCP 服务器的答案。每个都在用例旁边设置，以便运行保持可重复。播种工作区或对话
每次运行都在空工作目录中开始。当用例需要的不仅仅是提示时，在prompt.md 旁边添加一个 case.yaml，带有 context 块。
要首先创建 fixture 文件或 git 存储库，在用例目录中编写 Bash 脚本并在 context.scaffold_script 中命名它。脚本作为你在代理沙箱外运行，仅当你传递 --scaffold 时，所以仅对你或你的组织编写的套件传递该标志。要继续早期对话，将记录保存为 .jsonl 文件并在 context.history_file 中命名它，用例的提示成为下一个用户轮次。要让 Claude 在运行期间读取用例中的 fixture 目录，在 context.add_dirs 中列出它们。
case.yaml 也需要 schema_version: "1.1" 和 name；case.yaml 字段参考有完整列表。
这个 case.yaml 从脚本播种工作区并让 Claude 从 resources/ 目录读取 fixtures：
Mock MCP 服务器
你可以评估一个插件，其技能调用 MCP 工具，而不需要它们后面的真实服务。在evals/mocks/<server>/<tool>.md 下为整个套件放置一个 Markdown 文件，或在用例自己的 mocks/ 目录下为一个用例，其中 <server> 是你的插件MCP 配置中服务器的名称。
运行永远不会启动你的插件的真实 MCP 服务器，除非你要求。Claude Code 在每个服务器自己的名称下注册一个替代品。带有 mock 文件的工具从它回答，并且无需 --allow-tools 授予即可允许，没有 mock 文件的工具对 Claude 不可用。完全没有 mocks 的服务器在用例的 mocked: 进度线中显示为 plugin_<plugin>_<server>[not started: no mock]。
文件的正文是工具返回给 Claude 的内容。这个 mock 代替了名为 tracker 的服务器上的 create_issue 工具，检查 Claude 发送的输入，并回显标题。将其保存为 evals/mocks/tracker/create_issue.md：
{{input.<field>}} 从调用的输入插入字段，使用 {{file:fixtures/{input.<field>}.json}} 插入 mock 旁边的 fixture 文件的内容。expect: 块保护输入。如果调用违反它，运行以分数 0 中止并记录原因，以便用例可以断言你的插件要求服务器执行的操作。设置 error: true 以将正文作为工具错误返回，或 type: agent 以让小型模型从正文中的指令作为服务器回答。mock 文件参考列出了每个键和 _server.md 和 _tools.json 文件。
要评分调用本身，将评分器指向 target: mock_calls。
要改为针对插件的真实 MCP 服务器运行，传递这些标志之一。无论哪种方式，这些进程都作为你在代理沙箱外运行，它们的工具需要 --allow-tools 授予：
--allow-real-servers：为你没有 mock 的每个服务器启动真实进程，并继续从它们的文件回答 mocked 工具--mocks off：完全忽略mocks/并启动插件声明的每个服务器
重放代理 mock 答案
type: agent mock 使用对 --judge-model 的调用回答，所以其输出在运行之间变化并在你更改评判模型时改变。当运行完成而没有错误或中止时，Claude Code 在结果目录中的 mock-recordings/ 下保存代理 mock 给出的每个答案。
打开那里的 ADOPT.txt 以查看每个记录和 .replay/<server>/ 目录以复制到，在产生它的 mock 旁边。在你复制记录后，后续运行从它回答相同的调用，没有模型调用。将 mocks/.replay/ 与 mocks/ 的其余部分一起提交，以便 CI 运行是可重复的。
运行 evals
一旦套件存在，claude plugin eval 就会运行它。你可以使用 target 参数选择运行哪个插件和哪些用例，使用 --allow-tools 授予用例所需的任何工具（超出只读集合），并使用其他选项控制运行次数、模型、成本和输出。
选择要评估的内容
大多数时候，你从插件根目录运行claude plugin eval .，这会运行套件中的每个用例，并加载你所在的插件。要运行单个用例文件，或评估你安装的插件而不是你正在开发的插件，请传递不同的 target：
添加
--case <glob> 按用例名称过滤，添加 --tag <tag> 保留具有任何给定标签的用例。将 target 放在 --tag、--allow-tools 和 --json 之前。前两个接受列表，--json 接受可选路径，所以它们每个都读取后面的 target 作为自己的值。
授予工具
运行永远不会停下来请求权限。需要授予但你没有授予的内置工具，例如Bash、Write、Edit、WebFetch 和 WebSearch，会从会话中移除，所以 Claude 根本无法调用它们。允许列表是用例在 allowed_tools 中列出的只读工具，来自 Read、Glob、Grep、NotebookRead、Skill、Agent、TodoWrite 和任务工具 TaskCreate、TaskGet、TaskList、TaskUpdate、TaskStop 和 TaskOutput，加上你使用 --allow-tools 授予的任何工具，这适用于运行中的每个用例。要让用例使用 Bash、Write、Edit、WebFetch 或 WebSearch，请自己授予它们：
not granted。模拟 MCP 服务器上的工具不需要授予。真实插件 MCP 服务器上的工具需要服务器启动（使用 --allow-real-servers 或 --mocks off）和按名称授予，例如 --allow-tools "mcp__plugin_my-plugin_github__*"；插件的 MCP 工具命名为 mcp__plugin_<plugin>_<server>__<tool>。
当你以任何形式授予 Bash 时，每个命令都在 Claude Code 的 OS 级沙箱 下运行。写入被限制在运行的工作区，你的主目录和 Claude Code 配置不可读，网络访问限制为你使用 --allow-tools "WebFetch(domain:example.com)" 授予的域。如果你在没有沙箱后端的机器上授予 Bash 或 PowerShell，Claude Code 会拒绝每次运行而不是无限制地运行它，用例会显示运行错误，通常得分为 0。原生 Windows 没有后端，所以在 WSL2 下运行授予 shell 的套件；在 Linux 上，首先安装 bubblewrap 和 socat。请参阅 沙箱先决条件。
命令选项
此表涵盖运行次数、模型、评分、成本、工具授予、模拟和输出的选项。运行claude plugin eval --help 获取完整列表，其中还包括 --case、--tag、--eval-dir、--no-scaffold、--report 和 --verbose。
在 CI 中运行 evals
在你的 CI 作业中，使用--json 运行套件以写入结果以供存档，并根据退出代码使构建失败。传递 --trust-plugin 以便作业永远不会在 首次运行信任提示 处等待，固定两个模型以便得分在一段时间内可比较，保持报告本地，并设置成本上限作为上限：
写入或发布 HTML 报告的问题永远不会改变退出代码。要查看用例得分低的原因，请在本地运行它而不使用
--json 以便打印每次运行的进度和评分器行。
CI 运行程序需要 Claude Code 安装和 环境中的凭证，例如 ANTHROPIC_API_KEY。没有 --trust-plugin，其检出目录 Claude Code 还不信任的作业在没有终端时被拒绝，退出 1，或在运行程序分配一个时在提示处等待。claude plugin eval init 需要终端来提出问题；在 CI 中，运行 claude plugin eval init --bare <name> 以获取空白模板。
要保持成本可预测，给快速的每次更改套件仅使用不调用评判者的评分器，在你不需要 Δ 的地方使用 --ablation none，并将 partial: true 文档和具有 skippedPaidGraders 的运行排除在你绘制的任何趋势之外。
读取结果
每次至少有一个用例的运行都在 eval 目录内写入results/<timestamp>/ 目录，包含 aggregate-result.json 和 report.html。对于在插件下的路径目标；对于你命名的插件，它在你的当前目录下，如目标表所示。摘要表、JSON 和报告都呈现相同的结果数据。
HTML 报告
report.html 是一个单一的自包含文件，不进行外部请求，所以你可以将其附加到 CI 作业或从磁盘打开它。这个例子是使用 --threshold 0.8 运行的三用例套件报告的顶部；显示的成本是列表价格估计，随模型和用例数量而变化：
- 判决行和瓷砖回答插件是否在整个套件中有帮助。套件分数是每个用例 with-plugin 分数的平均值，Ablation Δ 是该分数高于或低于基线分数的程度，Cases 计数有多少个达到了阈值。Perfect runs 是 with-plugin 运行中每个评分器都通过的比例。
- 每个用例卡显示用例自己的
Δ和 with-plugin 分数，在阈值处有一个刻度。Δ为负的用例在左边缘获得红色，所以当你滚动时回归会突出显示。 - 在用例内，with-plugin 运行首先出现，基线运行之后。每次运行都列出其评分器及通过或失败芯片。失败的评分器已经展开并显示其解释，
llm评分器也显示评判的投票和它被显示的证据，这是你发现运行分数低的原因的地方。不计入分数的评分器，例如tool_used: Skill，带有plugin-fired indicator徽章。 - Prompt 和 Graders，在运行下方，显示用例的提示和每个评分器的评分标准或模式，所以没有套件的人阅读报告时可以看到被问了什么以及什么被认为是好的。
Published: <url>。传递 --no-publish 以保持本地。如果没有 Published: 行出现，例如使用 API 密钥身份验证，本地文件是报告。
Claude Code 会话启动的运行，例如当你要求 Claude 为你运行套件时，也保持本地，其 Report: 行说 kept local。将 --publish-report 添加到该命令以发布它。
JSON 结果
aggregate-result.json 和 --json 输出是一个版本化文档，带有 schemaVersion: 1 供 CI 脚本解析。字段名称是 camelCase，新字段在不重命名现有字段的情况下添加，所以编写你的脚本以忽略它不识别的字段。
这些是门控脚本通常读取的字段。文档还包含套件配置、每个评分器定义和每次运行的评分器结果及解释和证据：
一次运行可以访问什么
claude plugin eval 加载目标插件的 skills 和 hooks，并在你的机器上以你的身份运行其 eval 套件。指向一个插件与 claude --plugin-dir 的信任决定相同，所以只评估你信任的插件。本节描述的隔离限制了被测试的代理可以到达的内容；它不是针对插件自己代码的保护，通过的套件对插件是否安全没有任何说明。
信任插件目录
第一次针对一个目录运行claude plugin eval 时，Claude Code 会在加载任何内容之前询问 Trust this plugin directory?，除非你已经在交互式 claude 会话中接受了那里的信任提示。在 git 仓库内，回答是会信任整个仓库，对交互式会话也是如此。当 stdin 或 stdout 不是终端时，或在 --json 下，运行无法询问并被拒绝，退出代码为 1；传递 --trust-plugin 来自己声明信任，仅限于你会在自己机器上运行的插件。你命名而不是作为路径给出的目标，即已安装的插件或 skills 目录插件，会跳过提示。
插件和套件的某些部分仅在你为该运行传递其标志时才运行：一个案例的 scaffold_script 带有 --scaffold、超出只读集合的工具 带有 --allow-tools，以及插件的真实 MCP 服务器 带有 --allow-real-servers 或 --mocks off。一个案例的 allowed_tools 和一个 skill 自己的 allowed-tools frontmatter 无法扩展其中任何一个。当插件附带你没有编写的 hooks，或你启动其真实 MCP 服务器时，除非你在隔离环境（如容器或 CI 运行器）中运行它，否则将其分数视为建议性的，因为 hooks 和服务器在代理的沙箱外运行，可能会接触评分器读取的文件。
运行如何被隔离
每次运行都获得一个临时主目录、工作目录和 Claude Code 配置，被测试的代理在那里作为claude -p 子进程运行，仅加载你的插件。在编写案例时，请记住这些后果：
- 不加载任何个人或项目级内容。 你的用户设置、hooks、
CLAUDE.md文件、MCP 服务器、其他已安装的插件、memory 和 skills 都不存在，沙箱上方没有项目范围的.claude/或.mcp.json被读取。你的大部分 shell 环境也被隐瞒；只有允许列表和EVAL_*变量到达运行。如果插件需要设置，在插件中提供它，在scaffold_script中创建它，或传递EVAL_*变量。 - 托管策略仍然可以限制运行。 管理员部署到机器的托管设置中的限制适用于运行内部，所以托管机器上的结果可能因该策略而与非托管机器不同。
- Artifact 工具已关闭。 发布artifact的 skill 只能根据在该步骤之前产生的内容进行评分。
- 案例定义对代理隐藏。 运行无法读取 eval 目录，所以 Claude 看不到案例的提示、其评分器或兄弟案例。
- shell 命令外没有网络沙箱。 你授予的 shell 命令在沙箱的网络规则下运行。一个
WebFetch(domain:…)授予直接到达该域，插件自己的 hooks 和你启动的任何真实 MCP 服务器可以到达任何主机。
Eval 套件参考
eval 套件可以包含的所有内容都位于插件的 eval 目录下，evals/ 除非你配置了另一个。此树显示 claude plugin eval 在那里读取或写入的每个文件；仅 prompt.md 或 case.yaml 是用例存在所需的：
prompt.md frontmatter
prompt.md frontmatter 接受这些字段。未知键是错误：
case.yaml 字段
case.yaml 在 YAML 中描述相同的用例并添加指向其他文件的字段。它需要 schema_version: "1.1" 和 name。prompt.md 字段 description、tags、plugins、runs 和 expected_outcome 在顶级；model、max_turns、timeout_seconds、allowed_tools、append_system_prompt 和 env 在 execution: 下。当两个文件都存在时，prompt.md frontmatter 覆盖匹配的 case.yaml 字段，prompt.md 正文是提示，graders/*.md 在 case.yaml 中列出的任何评分器之后添加。
这些字段仅存在于 case.yaml 中：
评分器 frontmatter
graders/ 下的每个评分器文件在 frontmatter 中采用这些键，加上其类型的选项。评分器的名称是不带 .md 的文件名：
评分器可以查看什么
regex 评分器采用 target，llm 评分器采用 focus。两者接受相同的值：
评分器类型
下面的每个评分器类型列出其选项和何时通过：Mock 文件
mocks/<server>/ 下的 <tool>.md 文件回答一个工具。其正文是工具结果，带有 {{input.<field>}} 和 {{file:fixtures/<name>}} 替换。其 frontmatter 接受这些键：
两个可选文件位于服务器目录中的工具文件旁边：
_server.md：单个type: agentmock，在其tools:frontmatter 键中列出的几个工具回答。相同工具的<tool>.md优先。在单个<tool>.md上放置expect:保护，不在这里_tools.json：来自真实服务器的保存tools/list响应，所以 mocked 工具携带其真实描述和输入架构，而不是宽松的占位符
mocks/ 目录使用相同的布局并逐文件覆盖套件的 mocks。
故障排除
这些是作者最常遇到的问题，按你看到的内容键入。“plugin eval is currently in early access”
你的构建早于命令的普遍可用性。运行claude update，然后在新会话中再次运行命令。
“plugin eval is currently unavailable”
Anthropic 已在服务器端关闭命令。你的机器上没有任何内容将其打开；运行claude update 并稍后在新会话中重试。
“is not a trusted plugin directory, and this run cannot stop to ask you about it”
这是针对 Claude Code 还不信任的目录的第一次运行，它无法询问因为 stdin 或 stdout 不是终端或你传递了--json。在终端中运行 claude plugin eval <dir> 一次并回答提示，或如果你信任插件的代码和套件，传递 --trust-plugin。参见运行可以访问什么。
“No eval cases found”
eval 目录下没有<case>/prompt.md 或 <case>/case.yaml 存在，或你的 --case 和 --tag 过滤器没有匹配任何用例。从插件根目录运行，或运行 claude plugin eval init 以创建套件。
基线 arm 显示无插件，或 delta 为零
如果摘要没有W/OUT 列，或用例失败，显示”ablation requested but no plugin resolved”，没有为用例找到插件。将 plugins: ["../.."] 添加到用例，给出从用例目录到插件目录的路径。
如果插件确实加载，Δ 仍然接近零，你的 tool_used: Skill 评分器失败，这通常是真实发现，意味着技能的 description 不会在提示的措辞上触发。调整描述并重新运行相同的套件。
尽管生成了正确的文件，但一切都得分为零
你的评分器目标files（创建的路径列表），当你意思是文件的内容时。使用 { source: file, path: <path> } 作为 target 或 focus。另外，file_exists 仅计数在运行期间创建的文件，所以 scaffold 创建或 Claude 仅编辑的文件对它不可见；评分其内容，或在 Edit 上使用 tool_used。
对记录的正则表达式不匹配我能看到的文本
默认target 是 last_message，不是记录。当你确实目标 trace 时，它是每行 JSON，所以引号显示为 \"。正则表达式使用 JavaScript 语法，所以在 flags 中放置 i 而不是写 (?i)。
工具被拒绝，MCP 工具丢失，或 Bash 不会运行
超过只读集的任何内容都需要你的授予，例如--allow-tools Bash Write。你的个人 MCP 服务器永远不会在运行中加载。插件自己的服务器不启动，除非你选择加入，它们的工具然后也需要 --allow-tools "mcp__plugin_<plugin>_<server>__*" 授予；mocked 工具两者都不需要。
运行退出 1 但结果看起来很好
默认--threshold 是 1.0，所以当任何用例分数低于完美时命令退出 1。设置与你的标准匹配的阈值。退出 1 也涵盖加载失败的用例文件，在表上方的 stderr 上报告。
“—json output path must end in .json”
你在--json 后放置了目标，所以它被读作输出路径。首先放置目标，如 claude plugin eval . --json，或给 --json 一个显式的 .json 路径。
评分器在得分 1.0 的运行下显示 passed: false
该评分器在两个 arm 运行中按设计从分数中排除，其scored 字段是 false。参见与无插件基线比较。
运行在中途失败，出现使用限制或速率限制错误
如果你的账户在套件运行时达到其计划的使用限制或 API 速率限制，每个后续运行以该错误结束，在它生成的内容上评分，通常分数为 0。套件仍然完成，不标记为partial，所以结果可能看起来像回归。在信任分数之前检查 NOTES 列或 JSON 中的 cases[].arms.with[].error 以获取限制消息，然后在限制重置后重新运行，如果你需要保持在它下面，使用 --runs 1 或 --case 过滤器。
运行超时或达到轮次上限
默认值是 10 轮和 300 秒。为需要更多的任务在用例中提高max_turns 和 timeout_seconds，并使用 --max-cost-usd 作为成本上限而不是紧的每次运行限制。