yama 判

先有 Benchmark，才谈得上优化

市面上的 Skill 优化工具很多——自动改写 prompt、A/B 换模型、遗传算法调 SKILL.md…… 但所有优化的前提是同一个：先明确优化目标是什么、怎么度量。 没有可重复运行的 Benchmark，「优化后更好了」只是一种感觉。 yama 不做优化本身，它提供的是优化的地基：把「这个 Plugin 应该表现成什么样」 写成可反复执行、可判定通过与否的用例集。

什么叫「更好」：四把尺子，按序落判

有了 Benchmark，「模型 A 换成 B 值不值」「Plugin 这版改完有没有变好」就变成 同一批 Case 上的四个数字——而且比较有先后次序：先比对错，再比好坏， 最后才轮到成本与速度。

yama 回答四个问题

一次 Case 执行的路径

# __evals__/cases/plan/first-directions.yaml
description: 模型应先读 DSL 再给出差异化的创意方向

model: { name: gpt-5, temperature: 0 }   # 可省略，继承 yama.toml

context:                                 # ① 模型看到什么
  system_prompt: { default: true }       # Plugin 根目录的 SYSTEM.md
  skills:
    - plan-visual-style                  # skills/plan-visual-style/SKILL.md
  tools:
    - builtin: skill                     # skills 非空时必须声明
    - file: tools/read-dsl.yaml          # 生产 Tool Schema，直接复用

mocks:                                   # ② Tool Call 如何被执行
  tools:
    read_dsl:
      respond:
        result:
          visualStyle: { name: 复古胶片 }

steps:                                   # ③ 依次发送的用户回合
  - id: request-directions
    user: 给我几个创意方向
    assert:
      hard:                              # 确定性硬检查
        - tool_called: { name: read_dsl }
        - assistant_contains: 创意方向
      judge:                             # LLM 质量评分
        dimensions:
          - name: differentiation
            criteria: 几个方向是否具有明显差异
            min_score: 4

outcome:                                 # ④ Case 级通过门槛
  require:
    judge: { overall_gte: 0.8 }

九种硬检查

Judge：把「好不好」变成可度量的维度

每个维度 1–5 打分并给出 reason 与 evidence，归一化后按权重加权得到 overall（0–1）。默认只在硬检查全过后才评分；Judge 分数永远不能抵消硬检查失败。 评分模型可以与被测模型不同（judge.model）。

judge:
  model: judge-model          # 省略则用当前 Case 的 model
  dimensions:
    - name: instruction_following
      criteria: 是否满足用户明确要求
      weight: 0.4
      min_score: 4            # 单维度硬下限
    - name: communication
      criteria: 回复是否清晰、简洁并提供可执行动作
      weight: 0.6

写 Case 前必须知道的硬规则

• context.tools 与 mocks.tools 的工具名集合必须完全相等（双向，不是单向包含）；builtin 工具未自定义 Mock 时由框架自动补齐。
• context.skills 非空时必须声明 {builtin: skill}——Skill 正文只能靠模型主动调用 skill 工具读到，System Prompt 里只有 name/description 目录。这保证每个 Case 都在测真实的「按需查阅」行为。
• 模拟命令行工具用 {builtin: bash}：mocks.cli 按命令树返回确定性输出；mocks.fs 在隔离沙箱里跑真实 shell。二者互斥，一个 Case 只能选一种。
• Mock 与断言分工明确：Mock 只回答「被调用时返回什么」；「必须 / 不能被调用」永远用 tool_called / tool_not_called 断言表达。
• respond.sequence 消费完再被调用是整条 run 立即失败（不是重复最后一条）；未 Mock 的工具被调用同样是硬失败。
• 每个 Step 必须有 Case 内唯一的 id 和 user；断言默认只看当前 Step，跨 Step 检查用 Python Checker。

# 安装为全局命令行工具
$ uv tool install python-yama          # 或 pipx / pip install python-yama

# 在 Plugin 根目录直接跑（默认收集 __evals__/cases/**/*.yaml）
$ cd dingding-simple && yama

# 在 Workspace 根目录（有 yama.toml）按名字选 Plugin，并生成 HTML 报告
$ yama --plugin dingding-simple --report

# 只跑一个文件；或按 case key 筛选（子串匹配，含 * ? [ 时按通配符）
$ yama __evals__/cases/plan/first-directions.yaml
$ yama -k smoke -k "__evals__/cases/plan/*.yaml"

# 不调 LLM，只解析 Case 生成用例预览（写 Case / Review 时的回路）
$ yama --preview

# 本地 dashboard：首页列历史报告，/preview 每次刷新重新解析 Case
$ yama dashboard                        # http://127.0.0.1:8765/

常用参数

每次 run 的全部证据都在产物目录

<plugin_root>/.yama/runs/<case_key>/run-001/
├── result.json                  # run 是否通过、error / traceback ← 先看这个
├── hard-checks.json             # 每条断言的 expected / actual / reason（不短路，全记录）
├── mock-events.json             # 每次工具调用的实参 / 返回 / match_failed / state 变化
├── requests/request-00N.json    # 每次真实发给 LLM 的完整请求（messages + tools）
├── transcript.json              # 每个 Step 结束后的完整对话快照
├── rendered-system-prompt.txt   # 模型实际看到的 System Prompt
└── case.resolved.yaml           # 展开后的 Case（所有默认值、Skill、Schema 落定）

1. 盘点 Plugin 的行为面

   读 SYSTEM.md 和每个 SKILL.md，列出它承诺的关键行为：什么时候必须查 Skill、什么时候必须调哪个工具、什么动作必须先向用户确认。每一条承诺就是一个候选 Case。

2. 准备 Tool Schema 与 Mock

   把生产 Tool Schema 原样存成 __evals__/tools/*.yaml 供多个 Case 复用；为每个工具写最简单的 respond.result。需要按参数分支或维护状态时再上 match / Python Handler。

3. 先写最关键的 Case：happy path + 高频翻车点

   不求覆盖率，先把「必须对」的两三条路径和线上出过事故的场景写下来。断言从最硬的开始：该调的工具（tool_called）、不该调的工具（tool_not_called）、关键实参（tool_arguments）。

4. 用 preview 校对，再真跑

   yama --preview（或 dashboard 的 /preview，改 YAML 刷新即生效）零成本确认模型将看到的消息、Mock 与断言都符合预期，然后 yama --report 真跑。

5. repeat 多次，看的是通过率不是单次结果

   概率性系统里跑一次过了不算过。execution.repeat 让同一 Case 跑 N 次统计稳定性；写成运行矩阵还能同 Case 对比多个模型——比的正是「壹」里那四把尺子：通过率、Judge 均值、tokens，报告自动按 label 分组、给最优 run 标 🏆。

   # yama.toml — 同一批 Case，两个模型各跑 2 次对比
   [[defaults.execution.repeat]]
   model = { name = "gpt-5" }
   times = 2
   
   [[defaults.execution.repeat]]
   label = "sonnet"
   model = { name = "anthropic/claude-sonnet-5" }
   times = 2

6. 失败了：先分层，再读产物

   按下表定位失败层级，再进产物目录或 HTML 报告逐 Step 看证据。

失败分层速查

高频误判：先分清「模型错了」还是「用例错了」

• mock-events.json 里 match_failed: true → 实参没匹配上 Mock 的 match.arguments，模型收到统一的 UNKNOWN_ERROR，后续行为全被带偏。先判断是匹配条件写太死，还是模型真传错了参数。
• tool_called 失败但 transcript 里明明调用了 → 断言只作用于当前 Step，调用发生在别的 Step 不算。
• bash 返回 command not found（exit 127）→ 命令没在 mocks.cli 里声明、用绝对路径绕过了 PATH shadow、或模型拼错了命令名。
• 模型「看不到」命令失败 → 发给模型的只有 stdout + stderr 拼接文本，exit code 不在模型可见内容里。

迭代旧 Plugin：先锁行为，再动手

1. 给现状写「表征用例」

   不改任何 prompt，先把当前实际行为——包括你想改掉的行为——写成能通过的 Case。这是重构前的安全网：改动之后哪些行为变了，一目了然。

2. 把线上翻车对话提炼成 Case

   每次 badcase 复盘的产出不是一段结论，而是一个新 Case：复现当时的 Context 与用户输入，断言正确行为。修复后它永远守着这个场景。

3. 大改动用运行矩阵对比

   换模型、重写 SKILL.md 这类大动作，用 repeat 矩阵让新旧配置在同一批 Case 上对跑，报告按 label 分组对比通过率、Judge 分与 token 消耗——用数据说话，不靠对话框里的感觉。