defineEval：声明、配置并运行 NiceEval 评估用例

defineEval 是编写评估用例的主要入口。每个评估用例文件调用一次，传入描述和 test(t)，并默认导出结果。组织业务判据、证据与分值时，参照 NiceEval Taste。

import { defineEval } from "niceeval";

export default defineEval({
  description: "Brooklyn weather query",
  async test(t) {
    const turn = await t.send("What's the weather like in Brooklyn today?");
    turn.succeeded().label("Turn 完成");
  },
});

不要提供 id 或 name。NiceEval 从文件路径推导评估用例 ID。

`defineEval` 选项

`description`

description?: string;

一句话描述,展示在 niceeval list 和 view 里;纯说明,不影响调度或打分。

`tags`

tags?: string[];

标签,供 CLI --tag 过滤和 view 分类;与 id 前缀过滤是两套独立的筛选维度。

`sandbox`

sandbox?: SandboxLayer;

这道题贡献的 Sandbox 声明层。省略等价于空 command-only layer，不提供隐式 template。每个实际评估用例 × Experiment 配对必须恰好一方提供 template-bearing layer。

`plugins`

plugins?: readonly PluginInstance<"eval">[];

显式且不可变的评估用例 Plugin occurrence；不存在目录继承。

`judge`

judge?: JudgeSelection;

模型字符串只替换项目 Judge Provider 的模型；Provider 实例整体替换。Experiment 设置优先。

`reporters`

reporters?: Reporter[];

覆盖 / 追加项目级 Config.reporters,只对这一条评估用例生效。

`timeoutMs`

timeoutMs?: number;

覆盖项目级 / CLI 的单次 attempt 超时(毫秒),只对这一条评估用例生效。

`metadata`

metadata?: globalThis.Record<string, JsonValue>;

任意附加元数据,作为 Attempt Provenance 保存,不参与调度或打分;供自定义 reporter 消费。

`diff`

diff?: { include?: string[]; ignore?: string[] };

调整 agent diff 的归因排除清单(仅 Sandbox 型;见 docs/feature/eval/README.md):两个数组都是 gitignore 风格 glob(workdir 相对)。默认排除 .git/node_modules/构建产物/包管理器缓存; ignore 在默认清单上追加排除;include 优先级最高,把匹配路径显式加回。合成规则固定为「默认 ∪ ignore,再被 include 打洞」,清单在分类账锚点时冻结。

`test`

test(t: TestContext): EvalTestReturn;

Test context: `t`

t（TestContext）是评估用例作者拿到的高层上下文。每一次作者入口调用都直接登记一条 Assertion。t.check(subject, match) 比较显式事实，t.check(contextualMatch) 注入当前只读 ctx。t.judge(material, match) 把受管 ScoreMatch 交给同一个 check 接收者。 root、Session 与 Turn 的 judge 都要求显式材料。官方四个显式材料预设构造 Match 后转交该接收者。closeQA(selector, question) 选择整组材料回答验收问题。Agent 另提供 closeQA(question) 默认完整 scope 历史，以及 EventMatch、ToolMatch 简写。通过制评估的 Boolean 默认进入 Attempt Verdict；计分制的 Boolean 默认 record-only。两种评估的 measurement 都用 .gate(minimum) 进入 failed；计分制可在同一 entry 上组合 gate 与 score。Boolean .orStop() 使用自身 condition，measurement 用 .orStop(minimum) 或在 gate 后无参复用。普通公式直接用 TypeScript 计算，再用 t.score(ratio, { weight: 50 }).label("完成耗时") 登记。ratio 为 0–1 数值，权重为非负有限数；审计保留 ratio、固定 points 与实际贡献。带状态的数值材料不可判定时，贡献保持未知。 defineScoreEval 的 ScoreTestContext 额外提供 t.score(n) 直接登记 contribution；已有 Assertion 用 .score(n) 贡献分数。两者的 n 都必须 finite 且不小于零，零仍是显式 contribution。calledTool 与 notCalledTool 的完整契约见 Scoped assertions。全部成员：

`evaluationKind`

readonly evaluationKind: Kind;

`send`

send(input: string | { readonly text: string; readonly files?: readonly InputFile[] }): Promise<TurnHandle<Kind>>;

`sendFile`

sendFile(path: string, text?: string): Promise<TurnHandle<Kind>>;

`requireInputRequest`

requireInputRequest(filter?: InputRequestFilter): InputRequest;

`respond`

respond(...responses: readonly (string | InputAnswer)[]): Promise<TurnHandle<Kind>>;

`respondAll`

respondAll(optionId: string): Promise<TurnHandle<Kind>>;

`reply`

readonly reply: string;

`sessionId`

readonly sessionId: string | undefined;

`events`

readonly events: readonly StreamEvent[];

`eventOccurrences`

readonly eventOccurrences: ManagedEventOccurrences<"attempt">;

`newSession`

newSession(): SessionHandle<Kind>;

`signal`

readonly signal: AbortSignal;

`model`

readonly model?: string;

`reasoningEffort`

readonly reasoningEffort?: string;

`flags`

readonly flags: ExperimentFlags;

`progress`

progress(update: import("../types.ts").ProgressUpdate): void;

`diagnostic`

diagnostic(input: import("../types.ts").DiagnosticInput): void;

`log`

log(message: string): void;

`skip`

skip(reason: string): never;

`group`

group<Value>(
  title: string,
  body: () => Value | PromiseLike<Value>,
): Promise<Awaited<Value>>;

`check`

check: import("../assertions/api.ts").AssertionCheck<Kind, AgentMatchContext<"attempt">>;

`judge`

judge: JudgeFunction<Kind>;

`toolCalls`

readonly toolCalls: ManagedToolCalls<"attempt">;

`sandbox`

readonly sandbox: Sandbox<Kind>;

`o11y`

readonly o11y: import("../o11y/types.ts").O11ySummary;

`usage`

readonly usage: EvalUsage;

`succeeded`

succeeded(): BooleanAssertionHandle<Kind, void>;

`usedNoTools`

usedNoTools(): BooleanAssertionHandle<Kind, void>;

`maxToolCalls`

maxToolCalls(max: number): BooleanAssertionHandle<Kind, void>;

`noFailedActions`

noFailedActions(): BooleanAssertionHandle<Kind, void>;

`event`

event(match: EventMatch | EventOccurrenceMatch): BooleanAssertionHandle<Kind, void>;

`notEvent`

notEvent(match: EventMatch): BooleanAssertionHandle<Kind, void>;

`elapsedMs`

readonly elapsedMs: import("../assertions/match.ts").NumericMaterial;

`maxTokens`

maxTokens(max: number): BooleanAssertionHandle<Kind, number>;

`maxCost`

maxCost(usd: number | string): BooleanAssertionHandle<Kind, string>;

`closeQA`

closeQA(question: string, options?: JudgePresetOptions): MeasurementAssertionHandle<Kind>;

`closeQA`

closeQA(selector: ToolMatch | EventMatch, question: string, options?: JudgePresetOptions): MeasurementAssertionHandle<Kind>;

`closeQA`

closeQA<T>(selector: MaterialMatch<Context, T>, question: string, options?: JudgePresetOptions): MeasurementAssertionHandle<Kind>;

Judge measurement

先用 defineJudge 声明评分标准，再直接交给 t.check 或 t.judge：

const factualSummary = defineJudge({
  name: "factual-summary",
  rubric: "根据 source 评价 summary 是否忠实保留事实，没有编造。",
});

const turn = await t.send("总结需求。");
t.judge({ source: expected, summary: turn.message }, factualSummary)
  .gate(0.8)
  .label("事实一致");

Judge 材料接受有界 JSON 值和显式 judgeImage() 值，并在登记时快照。解析从项目 judgeRuntime 开始，再应用 Eval 的 judge 和 Experiment 的 judgeRuntime；完整 Provider 整体替换服务与执行配置，模型字符串只替换已选 Provider 的模型。Eval 的 judge 为这道题选择模型或 Provider，不是 Match 允许列表。通过制与计分制都可调用 .gate(minimum)；计分制还可调用 .score(n)，并保留 gate 失败时的 contribution。

图片材料

从 niceeval/judge 导入 judgeImage。它同步复制原图字节；支持 PNG 和 JPEG，每张最多 4 MiB、16,777,216 像素。每条断言及每次模型请求最多 4 次图片引用、合计 8 MiB，重复引用也计入限制；每个 Attempt 最多留存 32 MiB 图片。输入只检查签名、头部边界和尺寸，不完整解码或转码。 OpenAIProvider、VercelProvider 和 OpenRouterProvider 必须显式设置 supportsImages: true，并选择同时支持图片与工具调用的模型。默认不启用；TypesafeProvider 不支持图片。不支持时返回 judge-capability-unavailable，不会把图片降级成文字。

`judgeImage`

export function judgeImage(input: JudgeImageInput): JudgeImage { ... }

Capture PNG or JPEG bytes for an existing Judge call without sending a request.

`JudgeImageInput`

`body`

readonly body: Uint8Array;

Original encoded image bytes; copied synchronously, at most 4 MiB.

`mediaType`

readonly mediaType: "image/png" | "image/jpeg";

Must match the encoded image. Paths, URLs and SVG are not accepted.

现成裁判与自定义 Match

defineJudge 和现成裁判都返回 ScoreMatch，可以交给 t.check。t.judge 只是同一条 check 路径的便利入口，因此登记、快照、预算、求值、审计、结果保存和 handle 都只发生一次。

裁判	输入	得分含义
`factuality()`	`{ input, output, expected }`	一致为 1，不完整为 0.5，矛盾为 0
`faithfulness()`	`{ input, output, context }`	输出中有上下文支持的事实占比
`instructionFollowing()`	`{ instructions, output }`	满足明确要求的比例
`pairwisePreference()`	`{ instructions, output, reference }`	候选更好为 1，平局为 0.5，参考更好为 0
`t.closeQA(selector, question)`	声明 ctx reader 与单项 predicate 的 MaterialMatch	满足验收为1，不满足为0，证据不足为 unavailable

例如，直接使用 instructionFollowing() 的实例：

t.check(
  { instructions: ["说明集合地点", "不要编造具体时间"], output: post.content },
  followsInstructions,
).gate(0.7).score(25);

faithfulness 先提取事实，再逐项判断，由代码计算比例；提取不完整时没有有效得分。TypeSafe 不支持 extract，因此在 TypesafeProvider 上为 unavailable，不会改为整体估分。 pairwisePreference 是一次固定顺序比较，适合一个候选与一个参考的比较。 closeQA 将全部命中项保序交给一次 Judge，只依据材料回答验收问题。 Agent 可用 turn.closeQA(question)、session.closeQA(question)、t.closeQA(question)；显式 EventMatch 取事件视图，ToolMatch 取完整工具事实。完整空集为0且零调用；partial、unknown或超限为 unavailable，不截断后评分。需要组合多个模型步骤时，使用高级 defineScoreMatch 的 score(value, context)。 context.llm 提供 score、classify、extract 和 batchClassify，返回 Effect。它们与现成裁判共用调用预算、超时和审计记录。静态配置校验不会发网络请求；Provider、模型或 key 缺失也不会发请求。聊天服务使用 forced-function 请求，TypeSafe 使用 /systemone；两者都严格校验响应。传输或超时为 unavailable，HTTP 400 或协议不兼容为 errored。完整契约见自定义 Match。

`Turn` 返回类型

t.send(...) 返回一个 TurnHandle：从事件流派生的便利字段，加上一整套本轮作用域断言。 calledTool 与 notCalledTool 也属于 Turn 的作用域断言；它们的签名和 Match 规则只在 Scoped assertions 定义。

`input`

readonly input: string;

`events`

readonly events: readonly StreamEvent[];

`toolCalls`

readonly toolCalls: ManagedToolCalls<"turn">;

`eventOccurrences`

readonly eventOccurrences: ManagedEventOccurrences<"turn">;

`status`

readonly status: "completed" | "failed" | "waiting";

`message`

readonly message: string;

`data`

readonly data?: JsonValue;

`usage`

readonly usage: EvalUsage;

`check`

check: import("../assertions/api.ts").AssertionCheck<Kind, AgentMatchContext<"turn">>;

`judge`

judge: JudgeFunction<Kind>;

`succeeded`

succeeded(): BooleanAssertionHandle<Kind, void>;

`toolOrder`

toolOrder(matches: readonly [ToolMatch, ToolMatch, ...ToolMatch[]]): BooleanAssertionHandle<Kind, void>;

`usedNoTools`

usedNoTools(): BooleanAssertionHandle<Kind, void>;

`maxToolCalls`

maxToolCalls(max: number): BooleanAssertionHandle<Kind, void>;

`noFailedActions`

noFailedActions(): BooleanAssertionHandle<Kind, void>;

`event`

event(match: EventMatch | EventOccurrenceMatch): BooleanAssertionHandle<Kind, void>;

`notEvent`

notEvent(match: EventMatch): BooleanAssertionHandle<Kind, void>;

`eventOrder`

eventOrder(matches: readonly [EventMatch, EventMatch, ...EventMatch[]]): BooleanAssertionHandle<Kind, void>;

`elapsedMs`

readonly elapsedMs: import("../assertions/match.ts").NumericMaterial;

`maxTokens`

maxTokens(max: number): BooleanAssertionHandle<Kind, number>;

`maxCost`

maxCost(usd: number | string): BooleanAssertionHandle<Kind, string>;

`closeQA`

closeQA(question: string, options?: JudgePresetOptions): MeasurementAssertionHandle<Kind>;

`closeQA`

closeQA(selector: ToolMatch | EventMatch, question: string, options?: JudgePresetOptions): MeasurementAssertionHandle<Kind>;

`closeQA`

closeQA<T>(selector: MaterialMatch<Context, T>, question: string, options?: JudgePresetOptions): MeasurementAssertionHandle<Kind>;

测试集导出

export default rows.map((row) =>
  defineEval({
    description: row.task,
    async test(t) {
      await t.send(row.prompt);
    },
  }),
);

数组导出会生成稳定 ID：file/0000、file/0001 等。已有稳定业务 key 时也可以默认导出 Record<string, EvalDef>。例如 key 15193 在 swelancer.eval.ts 中生成 swelancer/15193。key 必须是非空单一路径片段，不能是 . / ..，不能含 /、\\ 或控制字符。发现顺序按 key 字典序固定。

ctx 材料与官方统计

defineMaterialMatch<C,T>({ name, read, match, capture? }) 从 niceeval 和 niceeval/expect 导出。 Adapter 的 create 提供应用 ctx；框架在 check 或 closeQA 登记时向 reader 注入当前只读 ctx。 reader 返回 { state: "complete", items: [{ id, value }] }，或带 reason 的 partial/unavailable。 ID 集合内唯一且最多128 UTF-8 bytes。capture 默认256项、48 KiB，可显式提高至16384项、4 MiB。 check(materialMatch) 返回 Boolean handle，默认至少命中一项；closeQA(materialMatch, question, options?) 返回 measurement handle。 Agent reader 从 AgentMatchContext<Scope> 读取 managed toolCalls 或 eventOccurrences，使用对应 ToolMatch 或 EventMatch。 question 非空且最多8 KiB。options 为 JudgePresetOptions；全部命中材料按原顺序进入一次 Judge，完整空集为0且零调用。 defineContextMatch<C,T>({ name, read, match, capture? }) 读取单个小事实。 reader 返回 { state: "available", value } 或 { state: "unavailable", reason }。配 BooleanMatch 得 Boolean handle，配 ScoreMatch 得 measurement handle；未知事实不调用评分器。 t.usage 读取官方账本的冻结值，保留失败、重试、缓存桶与费用依据。 Adapter 的 basis 为 recorded-calls；Agent 的 basis 为 reported-sends，并保留 Turn、Session、Attempt 范围。 usage.totalTokens 等字段为 NumericMaterial，未知不补0。 t.maxTokens(max) 约束完整 token 总量；t.maxCost(usd) 精确约束 USD 有效成本，实扣0优先于显式 pricing 估算。 t.elapsedMs 是 runtime Attempt 起点到读取处的墙钟毫秒，可交给 t.check(..., atMost(limit))。业务内首次完成时间仍由业务 Match 判断。

​defineEval 选项

​description

​tags

​sandbox

​plugins

​judge

​reporters

​timeoutMs

​metadata

​diff

​test

​Test context: t

​evaluationKind

​send

​sendFile

​requireInputRequest

​respond

​respondAll

​reply

​sessionId

​events

​eventOccurrences

​newSession

​signal

​model

​reasoningEffort

​flags

​progress

​diagnostic

​log

​skip

​group

​check

​judge

​toolCalls

​sandbox

​o11y

​usage

​succeeded

​usedNoTools

​maxToolCalls

​noFailedActions

​event

​notEvent

​elapsedMs

​maxTokens

​maxCost

​closeQA

​closeQA

​closeQA

​Judge measurement

​图片材料

​judgeImage

​JudgeImageInput

​body

​mediaType

​现成裁判与自定义 Match

​Turn 返回类型

​input

​events

​toolCalls

​eventOccurrences

​status

​message

​data

​usage

​check

​judge

​succeeded

​toolOrder

​usedNoTools

​maxToolCalls

​noFailedActions

​event

​notEvent

​eventOrder

​elapsedMs

​maxTokens

​maxCost

​closeQA

`defineEval` 选项

`description`

`tags`

`sandbox`

`plugins`

`judge`

`reporters`

`timeoutMs`

`metadata`

`diff`

`test`

Test context: `t`

`evaluationKind`

`send`

`sendFile`

`requireInputRequest`

`respond`

`respondAll`

`reply`

`sessionId`

`events`

`eventOccurrences`

`newSession`

`signal`

`model`

`reasoningEffort`

`flags`

`progress`

`diagnostic`

`log`

`skip`

`group`

`check`

`judge`

`toolCalls`

`sandbox`

`o11y`

`usage`

`succeeded`

`usedNoTools`

`maxToolCalls`

`noFailedActions`

`event`

`notEvent`

`elapsedMs`

`maxTokens`

`maxCost`

`closeQA`

`closeQA`

`closeQA`

Judge measurement

图片材料

`judgeImage`

`JudgeImageInput`

`body`

`mediaType`

现成裁判与自定义 Match

`Turn` 返回类型

`input`

`events`

`toolCalls`

`eventOccurrences`

`status`

`message`

`data`

`usage`

`check`

`judge`

`succeeded`

`toolOrder`

`usedNoTools`

`maxToolCalls`

`noFailedActions`

`event`

`notEvent`

`eventOrder`

`elapsedMs`

`maxTokens`

`maxCost`

`closeQA`