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
outputTokens
cacheReadTokens
cacheCreationTokens
reasoningTokens
requests
costUSD
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 —— 委派了谁
operationId 的配对规则同上。它们保留在原始事件流和报告里。要检查它们,对 turn.events 用普通的值匹配;eventMatch(...) 的工具匹配不会把子 agent 当成工具调用。
input.requested —— 停下等人(HITL)
input.requested,同时这个 Turn 的 status 是 "waiting"。t.requireInputRequest(filter) 按字段匹配 request,所以能填的字段尽量填,否则评估用例筛选不到。接法见接入教程的 HITL 部分。
thinking / compaction / error
compaction 主要来自 coding agent CLI,上下文满了时会自动压缩。这些事件主要用于报告和诊断;需要断言时,把 turn.events 当作普通值交给 check。
映射事件的三条规则
- 按真实顺序排列:事件顺序就是发生顺序。
toolOrder和eventOrder从前往后依次匹配不同的调用,顺序错了,断言结果就不对。eventOrder只能排eventMatch支持的事件。 - 用
operationId配对:每个 started 都要有kind和 ID 都相同的 finished。配对完整,NiceEval 才能把状态和输入归到同一次工具调用上。 - 如实声明完整性:官方转换器按 Adapter 的实际能力声明事件覆盖范围(evidence coverage)。相关的输入或动作覆盖不完整时,否定式断言(例如“没有调用某个工具”)的结果是
unavailable,不会把“没看到”当成“没发生”。手写映射也要如实声明覆盖范围,见能力位参考。
一个完整的映射示例
agent 返回里带步骤记录时,映射就是一个简单的循环:相关阅读
- 接入你的 agent —— 从零跑通的教程。
- 能力位 —— 声明”事件流是完整的”意味着什么。
- 编写评估用例 —— 消费这条流的断言全集。