niceeval/expect 只提供纯 Match factory。Match 比较一个候选值,不记录结果,也不决定判定或分数。t.check(value, match) 在调用时读取 value 并直接登记 Assertion;返回的 handle 只配置同一条 entry。
使用方式
数值单位
先用普通数值计算,再用ms、seconds、tokens、usd、ratio、count 或 bytes 包装结果。它们返回冻结的 Quantity<U>,通过 .value 读取数值,通过 .unit 读取单位。Quantity 不参与算术,也不自动换算单位。
所有构造函数只接受有限数;ratio(n) 还要求 0 ≤ n ≤ 1,否则抛出 RangeError。
measured 接受 number | null 或 Quantity<U> | null;quantile 接受普通数值数组或单位一致的 Quantity 数组,并保留单位。混合单位、混合普通数值与 Quantity 的数组会抛出 TypeError。空数组和缺失观测保留 unavailable,不补零。
atLeast、atMost、greaterThan、lessThan 的阈值必须与观测单位相同。between(minimum, maximum) 检查含端点的区间,两端也必须同单位且按大小排列。普通数值只接受普通数值阈值。
TypeScript 拒绝跨单位调用。JavaScript 绕过类型时,该检查返回 unavailable 并说明单位不符。show 和 view 按单位显示,例如 512 ms、61.2%、$0.031。
Matchers
下面每个 matcher 的签名和说明从niceeval/expect 的源码生成,和当前实现保持同步。
and
or
not
includes
excludes
pattern
similarity
includesUrl
hasSections
isDefined
isTrue
isFalse
commandSucceeded
equals
matches
satisfies
defineValueMatch
defineScoreMatch
eventMatch
mapValue
mapEach
filterWhere
countWhere
defineMaterialMatch
defineContextMatch
匹配工具调用
ToolMatch 比较一条 LogicalToolOccurrence,并通过 .exactly(n)、.atLeast(n) 等方法表达 occurrence 数量。calledTool 接收名称、未量化 ToolMatch 或正向 occurrence Match;notCalledTool 使用未量化 selector 表达零匹配。
jsonMatch,路径用 referencesAnyPath,命令 token 用 commandMatch。输出不存在、材料不完整或 HITL 尚未完成时,Match 会成为 unavailable,不会伪装成普通不匹配。
referencesAnyPath(paths, options?) 在整个 JSON 输入的任意字符串值中搜索路径,按路径组件匹配,默认区分大小写。匹配要求组件边界:agents 不匹配 agents-old。目录名就是前缀,secrets 能匹配 secrets/api.key。分隔符支持 / 和 \,忽略重复分隔符及 . 组件。
referencesAnyPath 只按字面搜索,不支持 glob,也不解析命令语义。secrets/** 不表示目录匹配,应写 secrets。例如 rg --files -g '!secrets/**' 虽然排除了目录,字符串仍提到 secrets,因此会命中。它不能据此证明读取或修改了文件;判断命令参数用 commandMatch,判断文件改动用文件改动断言。
options 只接受 ignoreCase?: boolean,默认为 false。例如 referencesAnyPath(["NiceEval/NiceEval"], { ignoreCase: true }) 可以匹配 URL 中大小写不同的 owner 与 repo。
该选项使用 Unicode 简单大小写折叠;折叠后相同的两条路径视为重复并抛出 TypeError,未知选项也会抛出。省略选项或传 false 保持默认 Match 的名称与身份;true 进入 Match 身份。
它不支持 glob。含 * 或 ? 的路径会在构造时抛出 TypeError;要覆盖目录下的路径,直接写目录名。
toolMatch 的名称、input、output 和 status 必须在同一次工具调用上同时满足。普通 selector 代表至少一次匹配;.exactly(n) 要求已知匹配数恰好为 n 且其余候选均可判定,.atLeast(n) 在已知匹配数达到 n 时成立。notCalledTool 要求全部候选可判定且匹配数为零。材料不完整、无法确定数量时保留 unavailable,不能当成零。
常见用法示例
组合与三态
and / or 里的 Match 必须属于同一 domain。布尔 Match 的内部结果是 matched、mismatched 或 unavailable:or 只有在没有子项命中且至少一项证据不完整时才返回 unavailable,不会把未知当成否定。Match 自身不持有判定、计分或控制流;continuous measurement 的 .gate(minimum)、.score(n) 与 .orStop(minimum) 都属于登记后的 AssertionHandle。
下面列出 Match 值本身的稳定字段。品牌和 evaluator 是模块私有实现,不属于作者 API。
Match
domain
name
BooleanMatch
kind
[matchRefinementBrand]
ScoreMatch
kind
集合中的先后条件
inOrder 可以把 2–64 个普通值 Match 组合成集合 Match,交给 t.check 或应用的集合断言方法。
它接受只读数组或带完整性状态的 MaterialCollection,按原位置寻找严格递增的子序列,不要求相邻。
and 约束同一事实。应用负责提供正式提交顺序;请求发出不代表操作采用或执行完成。
只要求双方都发言时,分别检查存在性即可。
不完整集合返回不可判定。完整集合有已知顺序证据时通过,没有可能的顺序时失败,只有依赖未知项才能成立时不可判定。
诊断保留原位置、材料 ID 和步骤判断。ToolMatch 与 EventMatch 的顺序组合保留各自的 Agent 范围,不能和普通值步骤混用。
自定义 matcher
defineValueMatch,连续分数用 defineScoreMatch。两者只实现单候选比较;读取文件、扫描事件、决定 coverage 或修改判定仍由 Assertion 登记入口与 Runner 负责。
根 t.toolOrder(matches) 与 t.eventOrder(matches) 在调用处冻结所有已启动会话的前缀,各会话独立检查顺序,不跨会话拼接步骤。任一会话匹配即满足;全部不匹配时不满足;否则材料不足。没有已启动会话时不满足。主会话可以跨多轮匹配,诊断保留见证会话与逐步结果。