waxa-eval

waxa-eval

基于真实迭代记录整理而成的技能提示词实证评估循环。 此技能是 waxa 的操作手册；CLI 本身位于 tools/waxa/（参数级参考请参阅其 README）。

waxa 在 microsoft/waza 的基础上， 进一步加入 empirical-prompt-tuning 语义：强制要求 Self-report、跨迭代记录台账、 四种评分器类型，以及收敛检测。

何时调用

仅在用户明确提出请求时调用：

• “用 waxa 评估此技能”
• “迭代优化 <skill>，直到收敛”
• “为 <scenario> 添加一个 waxa 场景”
• “解读这些不明确点 / Self-report”

何时不要使用：

• 一次性技能编辑（修复错别字、精简一句话）——直接编辑，不进行评估循环。
• 技能是全新的，还没有任何场景——先编写 SKILL.md；只有在目标稳定、可供衡量后才运行评估。
• 用户没有要求评估——这是元技能，不要自动调用。

四阶段迭代模式

此模式在 skill-selector、nix-setup 和 skill-finder 评估中反复出现。将其视为默认路径；如果技能的结构合理，经过 3-4 次迭代即可收敛。

阶段	修复内容	典型迭代	处于此阶段的表现
1. 结构性修复	缺少一整项行为——技能完全没有告诉执行器要做 X。	1 → 2	LLM 评分器和表层评分器均失败；编辑一次后通过率就会跃升。
2. 评分器覆盖范围	技能本身正确；表层评分器范围太窄（正则表达式只能匹配一种表述）。	2 → 3	LLM 评分器通过；表层评分器在同一方面失败。扩大正则表达式范围；不要“强迫”LLM 采用某一种表述。
3. 表层形式覆盖	LLM 使用了正则表达式未预料到的日语 / 同义词 / 缩写。	3 → 4	某次试验通过，另一次在同一评分器上失败。遗漏的是表层形式，而不是内容缺失。
4. 剩余不明确点	剩下的问题源自评估设置的结构（空白环境下的执行器无法运行真实工具），而非技能正文。	终止	Self-report 标记“执行卡住——无法运行网页抓取 / 外部命令”。在台账中记录；不要继续追查。

如果一项技能需要超过 4 次迭代，很可能存在更深层的设计问题。添加更多评分器前，请重新阅读技能正文。

编写场景（tasks/*.yaml）

两种角色，均为必需：

• 典型（中位数）——最常见的用户请求形式。收敛时应当通过；门槛在于“技能是否真正发挥作用？”
• 边缘情况——技能应能处理的已知失败模式。例如：技能应拒绝的范围外请求，或应转交给相邻技能处理的请求。

陷阱：空白环境下的执行器无法运行外部工具

waxa 会使用 claude -p --no-session-persistence --disable-slash-commands 调用执行器，并提供明确禁止使用外部工具的系统提示词。执行器无法运行 apm view、获取网页 URL 或列出文件。如果工作流原本需要这些操作，请在场景提示词中说明此限制：

inputs:
  prompt: |
    <task description>
    Real network fetches and `apm view` calls are not available;
    narrate the workflow you would run and the candidates you would
    expect, with rubric application and waxa eval / pinning notes.

如果不作此澄清，执行器会在 Self-report 中将无法运行的阶段标记为“执行：卡住”。这是错误信号；问题不在技能本身。

陷阱：提示词未明确预期输出形式

如果提示词说“给我列出一些技能”，但评分器正则表达式需要字面标记 playwright-test，执行器可能会给出满足用户需求、却无法通过正则表达式的同义表述。可以：

• 在提示词中列出答案必须包含的内容（不那么自然），或
• 为每个表层评分器搭配一个语义 LLM 评分器（推荐——见下文）。

Grader 选择

共有四种类型。成对使用。

类型	适用于	成本	失败模式
text（正则表达式）	检查表层字面标记是否存在	~免费	范围太窄；漏掉同义词／日语／缩写。默认使用范围较广的备选项。
code（JS 表达式）	对输出进行结构断言（行数、JSON 形状）	~免费	对格式漂移很敏感；仅用于检查形状，不用于检查内容。
self-report	阶段跟踪／不明确点规范	~免费	LLM 可能总是自报“OK”；应与另一个 grader 配对。
llm（LLM-as-Judge）	语义等价性和评分标准检查	成本高	结果不确定；应通过 trials_per_task ≥ 2 检查通过率。

标准配对模式

每个行为维度都编写两个 grader：

1. 一个表层 text grader，使用有意设置得较宽泛的备选项。目标：确定、快速，能捕捉明显遗漏。
2. 一个 llm grader，使用包含多个子句的评分标准。目标：捕捉语义等价内容并判断细微差异。

当 LLM grader 通过，而同一维度的表层 grader 未通过时，扩大表层正则表达式的覆盖范围（阶段 2）。不要强迫提示词采用特定措辞——这会扭曲技能的自然输出。

实际中容易踩坑的正则覆盖范围

• 日语与英语：スクレイプ vs scrape、非互換 vs incompatible、信頼 vs trust。始终包含两者。
• 锁定版本的词汇：pin to a tag、pinned via SHA、resolved with apm view、tag-pinned。使用单个宽泛的备选项。
• “停止”的同义表达：stop、do not adopt、refuse、reject、defer、redirect。

一个实用模板：

- name: pinning_vocab
  type: text
  config:
    regex_match:
      - "(?i)(pin(ned|ning)?\\s*(to|via|with)?\\s*(a\\s+)?(tag|sha|ref|version))|(apm\\s+view)|(adopt.*after.*eval)"

Self-report — 阅读要点

每次试验都会附加一个结构化的 Self-report 区块。请阅读以下字段：

• Phase trace — Understanding / Planning / Execution / Formatting。“stuck”条目是分流信号：是提示词不清楚，还是技能缺少该阶段的指引？
• Unclear points — 最有用的诊断信息。每项都包含 Issue / Cause / General Fix Rule。将 Rule 记录到台账中。
• Discretionary fill-ins — 执行者自行发挥之处。每一项都可以作为“技能应明确说明此内容”的候选项。
• Retries — 健康运行时应为 0。> 0 = 技能在任务中途需要澄清。

一次干净的运行应当所有阶段均为 OK、unclear=0、fill-ins=(none)、retries=0。unclear=0 之后下一个合理目标仍是 unclear=0——连续两次运行都处于此状态才算收敛。

台账模式（evals/<skill>/ledger.yaml）

每次迭代一条记录。架构（仅包含工作字段）：

iterations:
  - id: iter-N
    date: YYYY-MM-DD
    scope: <full or per-task>
    overall_pass_rate: <number>
    per_task: [...]
    unclear_points:
      - issue: ...
        cause: ...
        general_fix_rule: ...        # this is the durable artifact
    actions:
      - <one-line summary of the change made>

convergence:
  status: <converging | near_convergence | converged>
  rationale: |
    <why you stopped — be specific about what residuals remain>

提取通用修正规则

看到一个 unclear-point 时，问问自己：是什么类别的错误导致了这个问题？ 不要只问“这一次具体哪里出了问题”——而要问什么形式的错误总会导致此类失败？ 类别层面的规则才具有泛化性；跟踪记录只是一个示例。

Issue:    "skill never told executor to stop when catalog has a fit"
Cause:    "When NOT to use" stated alternative but didn't enforce halt
General Fix Rule:
  Meta-skills that delegate to a sibling must add a mandatory
  pre-flight check that explicitly halts the workflow (not merely
  advises an alternative).

这条规则可在不同技能间复用。未来评估遇到类似情况时，应引用已有规则，而不是重新发现它。

收敛

empirical-prompt-tuning 将收敛定义为连续两次运行均没有 unclear-points。实际操作中：

• 如果剩余的 unclear-point 是评估设置本身的结构性问题（例如“无法获取 URL”），则不会阻碍收敛。在台账中注明，并在收敛计数中排除。
• 如果剩余问题具有非确定性（一轮试验报告了问题，下一轮没有），则属于弱信号。如果技能总体稳定，且该 unclear 低于行动阈值，则可宣布收敛。
• 如果剩余问题是确定性的且与内容相关，则必须在宣布收敛前解决——这属于阶段 1 的工作，而非收尾工作。

标记台账：

convergence:
  status: converged
  rationale: |
    Iter 1 (X%) → Iter 2 (Y%) → ... → Iter N (Z%).
    Residual <name> is <reason it does not block adoption>.

测试布局约定

从 waxa 0.2.0 开始，评估文件位于技能目录内，与 agentskills.io 的技能评估布局保持一致。这样，单个技能仓库就能包含自己的评估套件，并作为独立单元发布：

<skill>/                                # the target skill (distribution unit)
├── SKILL.md
└── evals/
    ├── eval.yaml                       # config + top-level graders + task glob
    ├── ledger.yaml                     # iter history (created on first `iterate` run)
    └── tasks/
        ├── scenario-typical.yaml       # median — passes at convergence
        └── scenario-edge.yaml          # known failure mode — exercises the rule

工作区（每轮迭代的运行结果）位于技能目录之外，路径为 <workspace-root>/results/<skill>/iteration-N/<task-id>/<with_skill|without_skill>/{output-trial-*.txt, timing.json, grading.json}，另有 benchmark.json。如果存在 .waxa.yaml / .waza.yaml，则 <workspace-root> 是其所在目录；否则为技能目录的父目录。将 results/ 添加到 .gitignore。

waxa init 会生成 eval.yaml 和两个带有 TODO 标记的任务模板；迭代开始时会生成 ledger.yaml。

迭代前的 0.2.0 单体仓库布局（<repo-root>/evals/<skill>/eval.yaml + <repo-root>/<skill>/SKILL.md）仍会自动检测，因此旧评估仍可正常运行；新评估应使用技能本地布局。

运行循环

最低要求：

# Scaffold the eval skeleton (run inside the skill's own dir).
npx @mizchi/waxa init [--skill <name>] [--force]

# Single eval pass.
npx @mizchi/waxa <skill>/evals/eval.yaml

# Single task.
npx @mizchi/waxa <skill>/evals/eval.yaml --task <task-id>

# Single eval with baseline (with_skill vs without_skill, reports Delta).
npx @mizchi/waxa <skill>/evals/eval.yaml --baseline

# Iteration loop (auto re-runs while pass rate improves; writes ledger.yaml).
npx @mizchi/waxa iterate <skill>/evals/eval.yaml --max 4

# Audit a skill directory (apm audit hidden-Unicode scan + waxa native
# quality checks: frontmatter, body length, When-NOT-to-use, suspicious
# scripts, LICENSE).
npx @mizchi/waxa audit <skill>/ [--no-apm] [--json]

npm 包会附带 references/empirical-prompt-tuning.md，因此无论 waxa 安装在哪里，该方法文档都保存在本地。首次运行 npx @mizchi/waxa 后，该文件位于 <node_modules>/@mizchi/waxa/references/empirical-prompt-tuning.md。

--baseline——技能是否发挥了作用？

--baseline 会在每个试验中对每项任务运行两次（with_skill 和 without_skill），然后打印一行 Delta，并将两种配置写入 iteration-N/<task-id>/。这是 agentskills.io 风格的检查，用于判断“技能正文是否确实比空白起点的模型表现更好？”在单配置运行中不易察觉的情况，例如技能增加了 token 数量或延迟，却没有提高通过率，都能在这里显现出来。

每次迭代的耗时（claude-opus-4-8，3 个场景 × 2 次试验）：实际运行时间约为 3-5 分钟。请按顺序运行各轮迭代；不要针对同一评估并行启动多个 waxa 进程（它们会争抢 API 和锁文件）。单任务运行（--task <id>）适合用于确认小改动，而无需重新运行整个套件。

trials_per_task: 2 是最低要求——单次试验无法区分“技能不稳定”和“大模型抽样结果不佳”。只有在怀疑某个关键维度存在非确定性时，才增加到 3。

常见问题

错误	修正方法
未编辑技能就重新运行迭代	如果技能正文没有变化，结果就只是换了一个大模型样本。重新运行前先编辑。
只使用大模型评分器	它们具有非确定性且速度慢。请搭配表面评分器使用。
每次失败后都添加评分器	评分器不是安全网，技能本身才是。只有在某种重要行为尚未衡量时，才添加评分器。
将 executor: mock 当作真实执行器	当前的 tools/waxa/src/cli.ts 会忽略该字段；所有运行都会通过 claude -p 执行。请据此规划预算。
迭代超过 4 次后仍不重新阅读技能	如果超过第 4 次迭代仍在追查失败，说明技能正文存在结构性缺陷。停止迭代，重写该部分。
不提交账本	账本是持久化的成果。未来的评估会基于以往的 General Fix Rules。丢失账本，就会丢失组织经验。

与 empirical-prompt-tuning 的范围对比

此技能是实现指南；empirical-prompt-tuning 是方法论。二者相辅相成——谁也不能取代另一方，因为调度机制不同（Task 工具子 Agent 与外部 CLI 进程）。

关注事项	waxa-eval	empirical-prompt-tuning
方法论／第一性原理（无偏执行器、自我报告理由）	（引用）	负责
CLI 操作（waxa run / iterate / variant / compare）	负责	不适用
场景 YAML 编写	负责	不适用
评分器选择（text / code / self-report / llm）	负责	不适用
根据真实迭代循环得出的 Iter 模式（4 阶段特征）	负责	不适用
Ledger 架构（ledger.yaml）和通用修复规则提取	负责	共担
收敛定义（连续 2 次 unclear 为零）	共担	负责规范版本
Iter 0 描述／正文一致性检查（静态，不进行调度）	不适用	负责
tool_uses 相对值分析（只能通过 Task 工具子 Agent 实现）	不适用	负责
需求清单中的 [critical] 标签	不适用	负责
修复传播模式（保守／过度修正／零命中）	不适用	负责
成对比较注意事项（平衡顺序）	（引用）	负责
结构审查模式（仅检查文本一致性，不执行）	不适用	负责
环境限制（当前会话中无法使用 Task 工具）	不适用	负责
红旗表（自我重读后合理化等）	不适用	负责

**在以下情况下使用 empirical-prompt-tuning：**通过 Task 工具子 Agent 调度，在 Claude Code 会话内进行评估；需要测量执行器的 tool_uses；运行 Iter 0 静态一致性检查；编写带 [critical] 标签的需求清单。

**在以下情况下使用 waxa-eval（此技能）：**将评估作为外部 CLI 进程运行；将迭代历史保存为 YAML，以便重复执行或用于 CI；编写在每次技能编辑后重新运行的场景；在采用外部技能候选项之前进行准入检查（参见 skill-finder）。

实际工作流通常会同时使用二者：先用 empirical 在会话内完成 Iter 0 和首次调度，以确认方向；然后用 waxa-eval 执行迭代循环并维护持久化 Ledger。

相关内容

• empirical-prompt-tuning — 此技能所落实的方法论；职责划分请参见上方的范围表
• superpowers:writing-skills — 面向技能的 TDD 框架；与此技能配合使用（编写技能 → 评估 → 迭代）
• skill-finder — 使用 waxa-eval 作为跨来源候选项的准入关卡
• tools/waxa/README.md — CLI 参数参考
• tools/waxa/RFC-waza.md — 上游 waza 兼容性说明