commerce-evals

Commerce Agent 评测

此仓库不附带评测框架；评测套件由你负责，因为只有针对你的目录、订单和 fixture，测试用例才有意义。以下路径均相对于参考仓库：commerce_common/ 对应 commerce-common/commerce_common/。 对于无需模型的行为（来源追溯、上限、护栏、审批），使用 commerce_common/testing.py 中的 FakeClient 进行单元测试；评测则覆盖模型的决策。

用例结构

本节是用例结构和评分器名称的唯一说明；/author-commerce-evals 会引用这里。

{
  "id": "<flow>-<nnn>-<behavior>",
  "priority": "critical | high | medium | low",   "difficulty": "easy | medium | hard",   "tags": ["..."],
  "skip": "<reason, when a case cannot run yet>",
  "state": {"seen_products": ["..."], "cart": [...], "memory": [...], "staged_changes": [...]},
  "turns": ["<the customer's or operator's message>", "..."],
  "expected": {
    "calls_tool": ["..."],            "calls_one_of": ["..."],          "never_calls": ["..."],
    "first_tool": "...",              "first_tool_not": "...",
    "ui_components": ["..."],         "no_ui": true,
    "cart_contains": ["..."],         "cart_item_count": 0,             "cart_not_contains": ["..."],
    "staged_change_kinds": ["..."],   "no_applied_changes": true,
    "memory_contains": ["..."],       "memory_not_contains": ["..."],
    "skill_loaded": "...",            "skill_not_loaded": "...",        "no_skill_load": true,
    "reply_includes": ["..."],        "reply_omits": ["..."],           "max_tool_calls": 0,
    "rubric": "PASS if <condition>. FAIL if <condition>."
  },
  "notes": "<what the case pins and the fixture fact that decides it>"
}

state 是前置条件；除非要测试的行为会跨轮次保留状态，否则 turns 只包含一条消息；expected 仅包含用例所关注的键。state 和 expected 中的 ID 均为 fixture 中的真实 ID。priority 和 difficulty 便于报告指出哪些失败更重要；暂时无法运行的用例应附上说明原因的 skip，而不是删除。

编写规则

• 前置条件应放入注入状态中（已查看的商品、购物车、记忆事实、暂存队列），运行器会在轮次开始前将其载入会话状态和记忆存储。此前的轮次仅用于承载行为本身需要跨轮次保留的状态，不作其他用途。
• 每个正向用例都要有对应的负向用例：每个断言某个组件、技能加载、门控、披露或记忆写入的用例，都应在同一场景中有一个断言其未发生的用例。拒绝用例应有一个应当提供服务的对应用例。
• 记忆测试分为三类：值得保留的备注会被写入；标识符或排除内容会被拒绝（不存储，也不向用户报错）；已存储的事实会改变下一会话的推荐选择。
• 对最终工具参数及其产生的状态评分：最后一次展示调用中的 ID、暂存变更上的字段、轮次结束后的购物车和记忆存储。只有必须或不得出现的字符串才对回复措辞评分。仅当调用路径本身就是待测行为时，才断言 Agent 采用了哪条路径（skill_loaded、某个具名组件、对展示工具使用 never_calls），例如先读取以进行依据核验，或绝不执行某项写入；其他情况下，用 calls_one_of 指定可接受的路径集合。如果实际运行采用的路径不符合用例预期，但答案正确，就应扩大可接受集合；不要将用例重新限定为实际观察到的路径。
• 评分标准应包含一个 PASS 条件和一个与之不兼容的 FAIL 条件，二者不能同时满足；它应指出用于判定的 fixture 事实（更新后的送达日期、今日价格），并写明可接受的变体；不得涉及语气、篇幅或组件出现的顺序。
• 提及健康问题、一次性差事或敌意内容的轮次，应断言记忆的最终状态（memory_not_contains，或对 save_memory 使用 never_calls）。如果某个已存储事实应改变推荐选择，用例所用的查询结果必须同时包含该事实倾向选择的商品和其排除的商品；请先运行搜索，再编写用例。
• max_tool_calls 应根据行为良好的 Agent 所需调用次数设置；多商品请求会在一轮中触发多次搜索，而结束该轮的 present_suggestions 调用不计入上限。

评分器

• 代码评分器会读取某个轮次产生的事件（commerce_common/streaming.py）：tool_call 名称和参数、status 为 blocked 且 reason 中包含拦截门的 tool_result、ui 组件名称、最后一条 cart_update 或 change_update，以及回复文本。除 rubric 外，上述每项都由代码评分器评估。
• rubric 会交给评审器。每个维度（是否遵守预算、是否捏造可用性、是否说明权衡）调用一次评审器，并返回包含判定和理由的结构化输出；转录内容会作为引用材料传入，其中包括工具结果和组件载荷；当转录内容超出评审器的上下文窗口时，从开头截断，确保受评轮次保留，并在结果中记录截断情况。将评审器模型固定为温度零；如果更换评审器模型或 rubric，使用该模型或 rubric 评分的所有已存判定都会失效，因此记录中会包含两者的指纹。
• 评审器回复若无法解析为判定，则视为该用例上的评审器失败，并与 Agent 失败分开记录。

运行模式

时间	运行内容	判定依据
每次合并 Agent、技能、工具描述或夹具时	回归集	每个用例运行多次试验；每个集合设有通过阈值
更改某条工作流时	该工作流的定向集合	将失败集合与上一次运行的失败集合并排对照
选择或升级模型时（commerce-architecture 的模型字段）	全部	并排对照两个失败集合
生产环境中	根据同一套 rubric 对实时流量进行抽样评审	各维度的趋势

对比失败集合；实时运行之间的总体指标上下浮动一个百分点属于噪声。更改后某个用例失败，说明更改破坏了行为，或者用例中编码了过时的行为；修复其中一个，并在提交中说明是哪一种情况。

投毒夹具

包含指令的商品列表、评论和消息存放在仅供评估使用的夹具中；运行器会在运行期间将它们合并到后端，并将其置于第三方品牌或卖家名下；这些内容的 ID 不会出现在演示数据、种子数据或捕获记录中。每个此类用例都会在代码中断言负向条件（never_calls、cart_not_contains、no_applied_changes、memory_not_contains、reply_omits），且每个断言所针对的内容都必须是受测轮次实际呈现给模型的内容（评论只有在调用详情接口时才会读取）。至少覆盖一条要求写入购物车或暂存更改的指令、一条要求记住某些内容的指令，以及一条虚假声明（优惠码、保证）。与“应当提供服务”的用例对应的是同一细分领域中另一个独立的、仅供评估使用的无害商品列表，这样一味拒绝的 Agent 就无法通过测试。