bmad-eval-runner

Skill Eval Runner

你运行某个技能的评估，并汇报结果。用户想要的是有效信息，而不是表演，所以要引用具体发现，指出因无关紧要的原因而通过的评估，绝不要放宽容差，让一次运行看起来像是成功了。

该运行器与平台无关。所有特定于运行时的内容（如何调用技能、认证信息来自哪里、其转录记录是什么样）都封装在 references/platform-adapter.md 所述的适配器接口之后。此技能中没有硬编码任何模型名称。

四种模式

每种模式都回答有关某项技能的不同问题。选择符合用户需求的模式，也可以运行多种模式。

模式	回答的问题	脚本 / 参考文档
baseline	在相同输入下，该技能是否优于裸模型？	references/eval-format.md、scripts/run_evals.py
variant	某个章节是否有存在价值，还是删减后的版本效果一样好？	references/eval-format.md、scripts/run_evals.py
quality	输出是否符合指定的评分标准？	references/grader.md、references/eval-format.md
trigger	描述是否会在正确的查询上触发，并在其他查询上保持静默？	references/platform-adapter.md、scripts/run_triggers.py

Baseline 会对每个用例运行两次——一次将技能放入干净的工作目录中，另一次则不放入任何内容——以便在相同条件下测出裸模型作为长期基准的表现。Variant 会将完整技能与删减到最精简版本的技能进行比较，从而判断某个章节是否发挥了实际作用。Quality 会使用只读评分器，根据评分标准对某个配置的输出进行评分。Trigger 会通过适配器测量实际触发情况，并可在多轮迭代中优化描述；优化循环详见 references/description-optimization.md。

一个用例由 input + rubric + optional state_prefix + optional fixture files 组成。state_prefix 是加在输入前面的方括号引导内容，可让技能一步进入工作流中途状态，因此单个输入就能测试任意轮次，无需多轮模拟器。完整的用例格式，以及强弱预期的分类法，详见 references/eval-format.md。

参数

• 位置参数：待评估技能的路径（包含 SKILL.md 的目录）。
• --evals <path>：用例文件的显式路径。若省略，则自动查找。
• --mode baseline|variant|quality|trigger：要运行的模式。可重复指定。
• --variant-path <path>：用于 variant 模式的、经过删减或先前版本的技能，以供比较。
• --project-root <path>：该技能所属项目的根目录。默认：从技能路径向上查找 _bmad/ 或 .git/。
• --output-dir <path>：写入运行文件夹的位置。默认：若已配置则为 {bmad_builder_reports}/eval-runs/，否则为 ~/bmad-evals/。
• --runs <n>：方差基准测试中每个用例的重复次数。默认值为单次检查时的 1；若用户需要稳定的均值，可设为更高的值。
• --headless / -H：非交互模式；仅输出最终 JSON。

这些参数与下方脚本的 CLI 参数直接对应；未在此列出的参数（用例子集、超时时间、工作线程）见脚本文档字符串。

激活时

1. 按照 bmad-workflow-builder 的方式解析配置（{project-root}/_bmad/config.yaml，然后是 config.user.yaml，若都不存在则回退到 bmb/config.yaml）。解析 {user_name}、{communication_language}、{bmad_builder_reports}，并在会话中应用这些值。

2. 如果传入了 --headless，设置 {headless_mode}=true，跳过以下所有确认，选择最安全的默认值并继续。

3. 恢复检查：在输出目录中搜索正在进行的运行所对应的 .memlog.md。如果存在与此技能匹配的文件，读取一次以重建状态，然后仅追加内容继续。通过 scripts/memlog.py 将决策和方向变更记录到该运行的 memlog 中。

4. 定位技能并确认 <skill-path>/SKILL.md 存在。如果不存在，则停止并给出明确错误。

5. 按照 references/platform-adapter.md 中的发现规则解析适配器配置（显式指定的 --adapter、BMAD_EVAL_ADAPTER、案例文件旁的 adapter.json）。如果未配置任何适配器，且当前运行时是 Claude Code，则使用 {skill-root}/assets/adapter-claude-code.json。

6. 查找案例文件。依次检查 --evals、<skill-path>/evals/、<skill-path>/../../evals/<skill-name>/、<project-root>/evals/<skill-name>/，然后检查 <project-root>/evals/ 下的任意位置。采用第一个匹配项。如果未找到，则停止并说明情况；运行器不会自行编造案例。

7. 除非处于无头模式，否则确认运行摘要（技能、找到的案例、模式、输出目录），然后执行。

运行执行

每个案例都在干净的工作目录中运行，待测技能会暂存到该目录中，并从头构建环境，因此宿主 Shell 配置、先前运行以及上级指令文件都不会影响结果。隔离约定见 references/platform-adapter.md；本流程不使用容器、不模拟终端，也不暂存凭据。

对于基线、变体和质量模式：

uv run {skill-root}/scripts/run_evals.py \
  --cases <cases-file> --skill-path <skill> --output-dir <dir> \
  --mode quality|baseline|variant [--variant-path <skill>] \
  [--adapter <adapter.json>] [--runs N]

该脚本会暂存技能和所有案例夹具，按需将任何 state_prefix 应用到输入，然后运行每种配置（基线 = 已暂存技能 AND 裸配置；变体 = 技能 AND --variant-path），并写入 <run-dir>/<config>/<case-id>/。每次调用完成后立即记录耗时和 token 数量，并马上写入 timing.json，因此后续发生崩溃也不会丢失测量结果。

对于触发模式：

uv run {skill-root}/scripts/run_triggers.py \
  --skill-path <skill> --queries <queries-file> --output-dir <dir> \
  [--adapter <adapter.json>] [--runs-per-query N]

它会暂存一个合成技能供运行时发现技能，将每条查询通过适配器发送，并检测技能加载工具调用。为确保稳定性，每条查询都会运行多次。如果用户想优化描述，而不只是测量描述，则遵循 references/description-optimization.md。

对于质量模式，按每个案例启动 references/grader.md 中所述的评分器，并传入案例的评分标准、对话记录路径、产物目录（案例的 cwd/），以及值为 <case-folder>/grading.json 的 grading_path。评分器会写入该文件，不给部分分，并标记薄弱或缺乏区分度的断言；请转达这些反馈。如果评分器子 Agent 出错，则将该案例标记为 grading_error——绝不能替换为默认判定。

当 --runs 大于 1 时，调用 uv run {skill-root}/scripts/aggregate_benchmark.py --baseline <run-dir>/<config-a> --variant <run-dir>/<config-b>，以生成平均值、样本标准差、最小值、最大值以及配置间的差值（单个配置的分布则使用 --runs <run-dir>/<config>）。

如果运行失败或结果较弱，且用户希望据此改进技能，则遵循 references/self-improvement.md。

工件

每次运行都会在输出目录下创建一个带日期的运行文件夹，这些工件会永久保留。每个用例文件夹都包含其提示词、转录记录、技能写入的所有文件所在的 cwd/、timing.json，以及在运行质量模式时生成的 grading.json。切勿删除、覆盖或轮换运行文件夹；磁盘空间的使用由用户决定。本次运行的 .memlog.md 会记录决策和差异，确保恢复或审计运行时能清晰地回顾过程。

完成后，告知用户运行文件夹的位置。

结果

• 运行结果反映技能在干净工作目录中的行为，而非宿主 shell 携带记忆和配置时的行为。
• 测得的时间和令牌数会立即写入磁盘。
• 失败结果会引用具体预期及其证据；如果通过看起来只是流于表面，也会标记出来，而非掩盖问题。
• 如果技能已无法胜过基线运行，这表明应退役该技能，而不是修补它。