评测与可观测：你怎么知道 agent 好使

🎒 预备知识：完成上一课「A10 常见设计模式」（零基础入口：第 0 课）

一、三层评测，各配真实断言

组件级：工具/脚本的行为，确定性断言。成本最低、最先建。

# Easel 实例：48 个脚本中 39 个带 selftest 子命令——离线自检不花 API 钱
$ python xhs_publish.py selftest          # 校验 SELECTORS 字典完整、参数解析、纯函数断言

# 你的 agent 同理：
def test_read_file_truncates():
    result = execute("read_file", {"path": "big.log"})
    assert len(result) <= 4000            # 截断契约

轨迹级：agent 走的路径合理吗。完全自由的路径没法逐字断言， 退而求其次断言检查点——该发生的步骤发生了、不该发生的不存在：

轨迹 = run_agent("帮我发一条小红书")
assert "skill-xhs-publisher" in 轨迹.加载的技能      # 路由对了
assert "content_guard" in 轨迹.调用的脚本            # 过闸门了
assert 轨迹.工具调用次数 <= 15                      # 没失控
assert "publish --exec" not in 轨迹.命令 or 轨迹.有人确认   # 真发前有确认

Easel 的 tests/ 目录就是这个思路的制度化：每个技能的 tests/ 放 test1.prompt（输入） + test1.expected（关键词）——跑完检查输出是否命中关键词。

结果级：最终产物达标吗。最贵也最硬。能机械断言的机械断言 （文件非空、字数区间、视频时长）；不能的用 LLM-as-judge。 Easel 最漂亮的结果级 eval 是 readback 对账：发布后回创作者中心查作品列表， 四档结论里 verified 才算真成功——用平台侧事实做验收，比任何模型自评都硬。

二、LLM-as-judge：有用，但要校准（流程）

让强模型按 rubric 给输出打分是规模化评测的常用手段。已知偏差：偏好长回答、偏好自家风格、 位置偏差（对比时倾向选第一个）。校准四步：

1. 人工标注 50–100 条金标（好/坏/边界各占一些）
2. 让 judge 评这批，算与人工的一致率（低于 80% 说明 rubric 或 judge 不行）
3. rubric 写可观察项不写形容词（"含至少 1 个数据来源引用"，不是"内容详实"）
4. 上线后 judge 初筛 + 分歧样本人来终审，定期把终审结果回流金标集

三、可观测：评测说"不好"，轨迹说"坏在哪步"

最低配置两件事：完整轨迹落盘（每步的消息、工具调用、结果——就是 A3 铁律②的 transcript， 留痕既是安全设计也是调试设施）+ 失败样本可重放（拿当时的确切输入重跑）。 Easel/OpenClaw 侧的三层留痕：transcript jsonl 只追加可回放（L18）、每轮事件落盘断线重放（L10）、 发布留痕 publish-log（L14）。

四、常见踩坑

坑 1：只评结果不看轨迹。结果对了但路径是"绕了 20 步碰对的"—— 下次同样输入就翻车。轨迹检查点必须建。

坑 2：eval 集过拟合。照着 20 个测试样例调 prompt 到全绿——新输入立刻退化。 eval 集要持续补真实失败案例（每上线翻车一个，回填一个 eval）。

坑 3：误以为 judge 越强越好。judge 不必用最强模型——比被评对象弱一档通常够用； 但注意 judge 与被评同源时的自偏好——换家 provider 做 judge 是便宜的解毒剂。

五、检索练习

六、出口检验

给"自动写周报的 agent"设计三层评测：每层至少 2 条具体断言（能直接变代码的程度）， 并说明失败样本怎么留痕重放；再给"周报质量"设计一个 judge rubric（≥3 个可观察项）。 发到对话里我批改。