bmad-eval

Skill Eval Runner

你运行技能的评估并报告它们的结果。引用具体发现，标记那些因琐碎原因而通过的评估，绝不为了让一次运行看起来成功而放宽容差。本技能不指定任何模型或 harness：项目评估所经过的 harness 会在首次运行时记录在本技能的定制配置中。

四种模式

模式	它回答的问题	脚本 / 参考
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/harness.md、scripts/run_triggers.py

Baseline 会分别针对已暂存技能和未暂存任何内容的两种情况运行每个用例。Variant 会将技能与 --variant-path 处的版本进行对比。Quality 会依据其评分标准为一个配置打分。Trigger 衡量实际触发情况；references/description-optimization.md 会在多轮中改进描述。

用例格式

一个用例是 input + rubric + 可选 state_prefix + 可选 fixture 文件；state_prefix 是一个加括号的前置内容，会附加到输入之前，一次性将技能置于工作流中间。用例位于 <skill>/evals/cases.json，触发查询以 {query, should_trigger} 形式位于 <skill>/evals/triggers.json。完整的结构以及强期望与弱期望的分类法在 references/eval-format.md 中。skill-creator 的 evals.json 可通过 uv run {skill-root}/scripts/convert_cases.py <evals.json> --output <cases.json> 转换（--to skill-creator 可反向转换）。

激活时

1. 使用 uv run {project-root}/_bmad/scripts/resolve_config.py --project-root {project-root} --key core.output_folder 读取配置，并使用 uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow 读取定制配置。缺少键没关系。{reports_folder} 是填入 {output_folder} 后的 {workflow.reports_folder}。
2. 验证 <skill-path>/SKILL.md 存在；若不存在，则清晰地报错并停止。
3. 当 workflow.harness.command 返回为空时，按照 references/harness.md 推断你当前所运行 CLI 的 harness 事实，在一个用例上验证它们，并通过调用 bmad-customize 技能来记录它们（安装：npx skills add bmad-code-org/BMAD-METHOD --skill bmad-customize）；runner 会从那里读取它们。当没有人在键盘前时，停下来并展示要记录的表。
4. 找到用例文件：先是用户指定的那个，然后是 <skill-path>/evals/，再然后是 <project-root>/evals/<skill-name>/，最后是 <project-root>/evals/ 下的任意位置。如果什么都没找到，则停止并说明；runner 不会凭空编造用例。
5. 除非用户要求非交互式运行，否则确认运行摘要，然后执行。摘要会指明技能、用例、模式和输出目录，展示 harness 命令，并说明它在权限提示关闭的情况下运行，且除非该命令将其包裹在沙箱中，否则不受隔离。非交互式运行需要已记录 harness。

运行执行

用户在 <mode> 模式下对 <skill>（存放 SKILL.md 的目录）请求一次运行，variant 模式则使用该 skill 的 variant 版本。项目根目录是 skill 持有 _bmad/ 或 .git/ 的第一个祖先目录；当 BMad 已配置时输出目录为 {reports_folder}，否则为 ~/bmad-evals/。每次运行都会在那里生成以时间戳命名的独立文件夹，因此运行之间绝不会冲突。每个用例都在一个 clean room 中运行，即项目之外的临时文件夹，其中将 skill 的副本置于其工作区，并从零构建环境，因此宿主机配置、此前的运行、项目的指令文件及其已安装的 skill 都无法影响结果。运行器自行从 customization 读取 harness；在没有 BMad 的项目中，传入 --harness <json> 并携带相同的键。

Baseline、variant 与 quality：

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

--runs 默认为 1，用于快速查看；只有达到 3 次或以上，结果才算作已确定。用例子集、超时和 worker 数量都在脚本的 docstring 中。退出码 0 表示完整运行；1 表示某个用例出错、超时或找不到命令，3 表示未记录任何 harness；触发查询未达到其阈值属于结果，而非错误。

Trigger：

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

对于 quality，按每个用例按照 references/grader.md 启动 grader，并传入其 rubric、transcript 路径、artifacts 目录（该用例的 cwd/）以及 <case-folder>/grading.json 的 grading_path。转达其 rubric 反馈。如果 grader 出错，将该用例标记为 grading_error，绝不能给出默认判定。

当 --runs 大于 1 时，uv run {skill-root}/scripts/aggregate_benchmark.py --baseline <run-dir>/<config-a> --variant <run-dir>/<config-b> 会给出均值、样本标准差、最小值、最大值和 delta（单个配置使用 --runs <run-dir>/<config>）。

当某次运行结果表现较弱，而用户希望据此改进 skill 时，请遵循 references/self-improvement.md。

产物

每次运行都是输出目录下一个以日期命名的文件夹，其中的 run.json 记录 harness 命令；每个用例文件夹以及每次触发尝试都保存其 prompt、transcript（harness 打印的内容）、stderr.txt、cwd/（运行后的工作区）、timing.json（在调用结束的那一刻写入），以及 quality 运行时的 grading.json。绝不要删除、覆盖或轮换运行文件夹。完成后告诉用户它在哪里。

结果

• 该运行反映的是干净工作目录中的 skill，而非宿主机 shell。
• 失败会引用具体的预期并提供证据；表面上的通过会被标记出来。
• 每个用例（或每个触发查询）少于 3 次运行的结果会被报告为快速查看，绝不能当作已确定。
• 若 skill 不再胜过的 baseline，意味着应淘汰该 skill，而非修补它。