跳转到主要内容
Adapter 的 send 返回一个 Turn,其中 events: StreamEvent[] 是本轮的标准事件流,事件断言都从这里读取事实。turn.calledTool(...)、turn.toolOrder(...)、turn.event(...) 和 turn.succeeded() 都根据本轮事件和其中的工具调用来判断,调用时直接登记一条断言。把 agent 这一轮做了什么如实翻译成这条流,事件断言就都能用。

Turn:send 的返回值

data 放本轮的结构化产物。只有应用的回答本身是结构化对象时才填,例如抽取、分类和表单填充,评估作者可以用 t.check(turn.data, ...) 比较它。只返回文本的应用不填 data。不要把原始响应 body 或 message 文本复制进去,也不要把结构化输出序列化后写进 events。usage 拿得到就填,拿不到就留空,不要估一个数字填进去。 usage 的完整字段(Usage 类型):

inputTokens

未命中缓存、按全价计费的输入 token;与两个 cache 桶互斥。

outputTokens

输出(completion)token 数。

cacheReadTokens

从提示缓存命中的输入 token;独立计价桶,不包含在 inputTokens 里(省略表示该 agent 不上报此项)。

cacheCreationTokens

写入提示缓存的输入 token;独立计价桶,不包含在 inputTokens 里(省略表示该 agent 不上报此项)。

reasoningTokens

推理(thinking)token 数,outputTokens 的已含明细,单列展示用;只在协议真实提供时存在。

requests

真实发生的模型请求数。协议不提供请求计数就省略,绝不写 1 凑数。

costUSD

网关/adapter 实测的真实美元成本(只能由 Turn.usage.costUSD 显式带回,从不从 token 用量或 OTel span 反推得到)。与顶层 estimatedCostUSD(价目表估算)是两个 相互独立的事实,单向字段契约:本字段只存 observed 值;estimatedCostUSD 恒等于 estimateCost(model, usage, pricing) 的估算,即使 observed 存在也照常独立计算—— 两者互不覆盖、互不兜底;observed 值从不替代或触发 estimate。
成本怎么算:Usage.costUSD 只记录 Provider 或 Adapter 实际返回的美元成本,不会由 token 数、模型目录或本地价目表推算。无论有没有这个值,Runner 都会根据 model、上报的 token 用量和配置里的价目表另算一份估算成本 estimatedCostUSD。 Experiment 的预算和 t.maxCost() 看的是这份估算,不看 Usage.costUSD。报告里的成本只按你显式指定的 PricingProfile 和已记录的用量计算,也不读 Runner 的估算。

StreamEvent 变体一览

StreamEvent 有十种变体,下面逐个列出字段。哪些断言读取它们、使用时要注意什么,见后面的「事件总表」和「逐事件说明」。

message

message

operation.started

operation.finished

operation.finished

skill.loaded

input.requested

thinking

context.injected

compaction

error

事件总表

事件断言有三个入口:event(match)、notEvent(match) 和 eventOrder(matches),都接收 eventMatch(...) 构造的匹配条件。eventMatch 支持 message、工具 operation.started 和工具 operation.finished 三种事件。要求出现几次,用匹配条件自己的 .atLeast()、.exactly() 等方法指定。其它事件可以把 turn.events 当作普通值,用 check(turn.events, valueMatch) 检查。

逐事件说明

message —— 说了什么

每段助手文本产出一条 role: "assistant" 的 message。工具结果不是助手消息,不要把工具输出包成 message,否则 t.reply 会读到错误的内容。用户输入的 message 由 NiceEval 自动记录,Adapter 不用产出。

工具 operation.started / operation.finished —— 调了什么工具、结果如何

  • 每个工具 operation.started 都要配一个 operationId 相同的工具 operation.finished,并发调用靠这个 ID 对上号。agent 返回里有现成的 ID 就直接用,例如 AI SDK 的 toolCallId、Anthropic 的 tool_use.id;没有时再按顺序生成。
  • status 按实际情况填:工具执行失败填 "failed",被人否决填 "rejected"。评估作者会用 ToolMatch 的状态条件区分这两种情况,不要混用。
  • name 填工具的原始名字。
  • 只有 started、还没有 finished 时,这次调用的状态是 pending,输出记为拿不到。finished 不带 output 也表示输出拿不到。缺失的输出不要写成空 JSON,也不要让它看起来像一次普通的不匹配。

将工具事件交给 ToolMatch

同一个 shell 工具可能先运行 git status,再运行 pnpm test。工具名只能说明是哪类工具。要分辨具体命令,评估作者用整理好的命令信息(command projection)来匹配:
ToolMatch 每次比较一次工具调用,名称、输入、输出和状态必须在同一次调用上满足。JSON、路径、输出材料和计数规则见 匹配工具调用。 原生协议直接给出一条命令的结构化 argv 时,用 niceeval/adapter 导出的构造器生成命令信息:
commandProjection() 保留 Adapter 确认过的原始参数,并按 NiceEval 统一的规则整理成 logical-command/v1 格式。例如 pnpm exec niceeval view 能被 commandMatch("niceeval", { argsStart: ["view"] }) 精确匹配。 只有原生协议本身给出了 argv,或者能按协议语法明确拆出唯一一条命令时,才能把原始命令标为可用(state: "available")。 协议只给出 shell 源码,或者内容被截断、脱敏时,用 opaqueCommandProjection(reason)。能确定这次调用不是命令时,用 notCommandProjection()。判断不了是不是命令时,降低 actions coverage,不要从工具名、输入或 shell 文本去猜。

子 agent operation.started / operation.finished —— 委派了谁

被测系统把任务委派给子 agent 并等它返回时,产出这一对事件,operationId 的配对规则同上。它们保留在原始事件流和报告里。要检查它们,对 turn.events 用普通的值匹配;eventMatch(...) 的工具匹配不会把子 agent 当成工具调用。

input.requested —— 停下等人(HITL)

agent 停下来等人时,每个待回答的问题产出一条 input.requested,同时这个 Turn 的 status 是 "waiting"。t.requireInputRequest(filter) 按字段匹配 request,所以能填的字段尽量填,否则评估用例筛选不到。接法见接入教程的 HITL 部分。

thinking / compaction / error

有就产出,没有不要编造。compaction 主要来自 coding agent CLI,上下文满了时会自动压缩。这些事件主要用于报告和诊断;需要断言时,把 turn.events 当作普通值交给 check。

映射事件的三条规则

  1. 按真实顺序排列:事件顺序就是发生顺序。toolOrder 和 eventOrder 从前往后依次匹配不同的调用,顺序错了,断言结果就不对。eventOrder 只能排 eventMatch 支持的事件。
  2. 用 operationId 配对:每个 started 都要有 kind 和 ID 都相同的 finished。配对完整,NiceEval 才能把状态和输入归到同一次工具调用上。
  3. 如实声明完整性:官方转换器按 Adapter 的实际能力声明事件覆盖范围(evidence coverage)。相关的输入或动作覆盖不完整时,否定式断言(例如“没有调用某个工具”)的结果是 unavailable,不会把“没看到”当成“没发生”。手写映射也要如实声明覆盖范围,见能力位参考。

一个完整的映射示例

agent 返回里带步骤记录时,映射就是一个简单的循环:

相关阅读