跳转到主要内容
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

Requires every Boolean Match to hold for the same candidate. All operands must belong to the same domain.

or

Accepts a candidate when any Boolean Match holds. All operands must belong to the same domain, and unknown evidence is not a definite mismatch.

not

Negates a Boolean Match within its domain. Unavailable evidence remains unavailable rather than becoming a successful negation.

includes

Checks that text contains a substring. Comment stripping is opt-in, and an empty expected string is rejected.

excludes

Checks that text does not contain a substring. Comment stripping is opt-in, and an empty expected string is rejected.

pattern

Checks text against a regular expression. Each evaluation starts with a fresh cursor and leaves the supplied expression unchanged.

similarity

归一化 Levenshtein similarity;它是连续分数,不携带默认阈值或 verdict 策略。

includesUrl

至少含 min 个去重 http(s) URL 的纯文本 matcher。

hasSections

至少含 min 个 Markdown heading 的纯文本 matcher。

isDefined

isTrue

value === true 的 refinement matcher。

isFalse

value === false 的 refinement matcher。

commandSucceeded

CommandResult-like candidate 的 exitCode === 0 matcher;不读取 stdout / stderr。

equals

Checks deep value equality against the supplied reference. It compares structure rather than object identity.

matches

Validates a value using Standard Schema v1. Refinement preserves the original candidate and ignores schema transforms.

satisfies

Wraps a named synchronous or asynchronous Boolean predicate as a value Match. The callback must return a Boolean and remain deterministic and free of side effects.

defineValueMatch

Defines a reusable Boolean value comparison with optional refinement. Report unknown evidence explicitly as unavailable rather than returning false.

defineScoreMatch

Defines a reusable finite [0,1] measurement, optionally using managed LLM primitives. Apply thresholds through the assertion handle, not inside Match configuration.

eventMatch

Matches a supported message or operation event. Use event-specific filters; tool filters belong on operation events.

mapValue

Project a single value without replacing the original subject’s refinement.

mapEach

Project each complete item, retaining its material identity and order.

filterWhere

Select only definite matches; an unknown selector makes the aggregate unavailable.

countWhere

Compare an exact match count only after every item in a complete collection is known.

defineMaterialMatch

Defines a synchronous context collection reader and item selector. Preserve collection completeness and unique item IDs instead of silently discarding unknown items.

defineContextMatch

Defines a synchronous readonly context reader and a Match for one fact. Return an unavailable fact explicitly when evidence cannot be read.

匹配工具调用

ToolMatch 比较一条 LogicalToolOccurrence,并通过 .exactly(n)、.atLeast(n) 等方法表达 occurrence 数量。calledTool 接收名称、未量化 ToolMatch 或正向 occurrence Match;notCalledTool 使用未量化 selector 表达零匹配。
普通 JSON 用 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

布尔自定义 Match 用 defineValueMatch,连续分数用 defineScoreMatch。两者只实现单候选比较;读取文件、扫描事件、决定 coverage 或修改判定仍由 Assertion 登记入口与 Runner 负责。 根 t.toolOrder(matches) 与 t.eventOrder(matches) 在调用处冻结所有已启动会话的前缀,各会话独立检查顺序,不跨会话拼接步骤。任一会话匹配即满足;全部不匹配时不满足;否则材料不足。没有已启动会话时不满足。主会话可以跨多轮匹配,诊断保留见证会话与逐步结果。