niceeval 0.6.0 → 0.6.2

package/dist/scoring/types.d.ts

@@ -1,10 +1,16 @@
 import type { Severity, SourceLoc } from "../shared/types.ts";
 import type { DerivedFacts, StreamEvent, Usage } from "../o11y/types.ts";
-/** 值断言(expect 匹配器)。纯函数 score + 可链式改严重度 / 阈值。 */
+import type { ResolvedCoverage } from "./coverage.ts";
+export type { CoverageChannel, ResolvedCoverage, ResolvedCoverageChannel, ResolvedCoverageStatus, } from "./coverage.ts";
+/** 值断言(expect 匹配器)。纯函数 score + 可链式改严重度 / 阈值 / optional。 */
 export interface ValueAssertion {
     readonly name: string;
     readonly severity: Severity;
     readonly threshold?: number;
+    /** `.optional()` 链过的标记:评不了只记 unavailable,不把 attempt 拖成 errored。 */
+    readonly isOptional?: boolean;
+    /** 期望条件的有界文本描述(如 `contains "Brooklyn"`),失败时进 AssertionResult.expected。 */
+    readonly expected?: string;
     score(value: unknown): number | Promise<number>;
     /** 转成硬门槛断言:未达阈值(省略 threshold 则按 score > 0 判定)整条 eval 判为 failed。返回新实例,不改原对象。 */
     gate(threshold?: number): ValueAssertion;
@@ -13,34 +19,76 @@ export interface ValueAssertion {
      * `--strict` 运行下,软阈值失败也会把整条 eval 的 verdict 计为 failed。返回新实例,不改原对象。
      */
     atLeast(threshold: number): ValueAssertion;
+    /**
+     * 允许这条断言证据缺席:评不了时只记录 `outcome: "unavailable"`,不影响判定。
+     * 与 severity 正交(severity 说影不影响质量判定,optional 说证据允不允许缺席)。返回新实例,不改原对象。
+     */
+    optional(): ValueAssertion;
 }
-/** 收集到 collector 里的一条断言记录(评估前)。 */
-export interface AssertionSpec {
+/**
+ * 断言记录的公共字段(见 docs/feature/scoring/architecture.md「断言记录」——字段契约的单点定义)。
+ */
+export interface AssertionBase {
+    /** 断言标题:t.group 内是该断言自己的摘要,组外是 matcher 摘要或 judge 问题;show/view 失败行的标题。 */
     name: string;
+    /** 所属分组路径:外层在前的 t.group 标题数组;无分组省略。纯报告用,不影响判定。 */
+    groupPath?: string[];
     severity: Severity;
-    threshold?: number;
-    /** 延迟评估:final 时拿到完整运行结果再算分。 */
-    evaluate(ctx: ScoringContext): Promise<number> | number;
+    /** 作者用 .optional() 显式允许该断言缺席;只改变 unavailable 的折叠方式(见 Severity 与 Verdict),不改变 severity 语义。 */
+    optional?: true;
+    /** matcher / judge 摘要,如 `equals(4)`、`closedQA("…")`;与 name 分开,供 show/view 同时展示分组标题与检查方式。 */
+    detail?: string;
+    /** 断言在 eval 源码中的调用点,`--eval` 把结果标回源码行的锚。 */
+    loc?: SourceLoc;
 }
-/** 断言评估完的结果(进判定 / 报告)。 */
-export interface AssertionResult {
-    name: string;
-    severity: Severity;
-    threshold?: number;
+/**
+ * 断言评估完的结果(进判定 / 报告)。判别键是 `outcome`——`unavailable` 是没有分数的独立态,
+ * 普通聚合代码按 `outcome` 分支就不可能把证据缺口算成零分。判定只消费
+ * `severity` / `outcome` / `optional` / `score` / `threshold`。
+ */
+export type AssertionResult = (AssertionBase & {
+    outcome: "passed" | "failed";
+    /** 归一化得分:值断言 0/1,judge 等打分断言 0..1。 */
     score: number;
-    passed: boolean;
-    detail?: string;
-    /** 这条分数是看着什么材料算出来的(judge 收到的输入,或 t.check 失败时实际被检查的值)。view 展开排查「为什么是这个分」,默认不展示。 */
+    /** soft 断言的 .atLeast(x) 阈值;没有设阈值则省略。 */
+    threshold?: number;
+    /** 失败证据摘要:期望值的有界文本预览,供 show/view 直接展示。 */
+    expected?: string;
+    /** 失败证据摘要:实际值的有界文本预览。 */
+    received?: string;
+    /** 这条分数看着什么材料算出(judge 输入或被检查值预览);view 展开排查用,默认不展示。 */
     evidence?: string;
-    /** 所属分组(t.group 标题)。纯报告用,不影响 passed/score。 */
-    group?: string;
-    /** 断言在 eval 源码里的调用点(栈回溯抠出);view 把判定叠回这一行。 */
-    loc?: SourceLoc;
+}) | (AssertionBase & {
+    outcome: "unavailable";
+    /** 机器可读原因,如 "judge-model-unresolved"、"coverage:actions=partial"。 */
+    reason: string;
+});
+/**
+ * 摘要面从完整 `AssertionResult[]` 选出的一条主失败断言。它只负责展示，不参与 verdict；
+ * `show @locator` / view Attempt 详情仍读取完整断言数组。字段保持结构化，使 CI 不必解析
+ * Human 的 `gate: …` 文案。
+ */
+export interface PrimaryAssertionSummary {
+    severity: Severity;
+    /** `groupPath.join(" > ")`，无 group 时回退到断言 name。 */
+    assertion: string;
+    /** `detail ?? name`；与 assertion 相同时省略，避免重复。 */
+    matcher?: string;
+    expected?: string;
+    received?: string;
+    score?: number;
+    threshold?: number;
+    /** unavailable 断言的结构化原因。 */
+    reason?: string;
+    /** 同类因果失败中除主失败外的条数。 */
+    additionalFailures: number;
 }
 /** eval 作者拿到的可链式句柄(t.judge.autoevals.closedQA(...).atLeast(0.7))。 */
 export interface AssertionHandle {
     atLeast(threshold: number): AssertionHandle;
     gate(threshold?: number): AssertionHandle;
+    /** 允许这条断言证据缺席:unavailable 只保留在记录里,不影响判定(见 Severity 与 Verdict)。 */
+    optional(): AssertionHandle;
 }
 /** scoped / judge 断言在 final 评估时拿到的运行结果。 */
 export interface ScoringContext {
@@ -50,6 +98,8 @@ export interface ScoringContext {
     readonly scripts: Record<string, ScriptResult>;
     readonly usage: Usage;
     readonly status: "completed" | "failed" | "waiting";
+    /** 当前作用域(turn / session / attempt)解析后的证据覆盖;断言按它做三值折叠(见 scoped.ts)。 */
+    readonly coverage: ResolvedCoverage;
     /** 读沙箱里某文件的最终内容(judge / file 断言用)。 */
     readFile(path: string): Promise<string | undefined>;
 }
@@ -57,9 +107,42 @@ export interface ScriptResult {
     success: boolean;
     output: string;
 }
+/** diff.json 的落盘形状:按时序的窗口数组(逐窗口 delta 序列,不做跨窗口压缩)。 */
+export type DiffArtifact = DiffWindow[];
+export interface DiffWindow {
+    /** send 窗口标签,与时间树 turn 节点、--execution 轮次同源(如 "s1/t2")。 */
+    window: string;
+    /** 该窗口内 agent 改动的文件;窗口内没有 workspace 变化时窗口仍落一条、changes 为空对象。 */
+    changes: Record<string, WindowChange>;
+}
+export interface WindowChange {
+    status: "added" | "modified" | "deleted";
+    /** 窗口开始时的内容;added 无此字段。 */
+    before?: string;
+    /** 窗口结束时的内容;deleted 无此字段。 */
+    after?: string;
+    /** 二进制文件不内联内容,只记字节数。 */
+    binary?: {
+        beforeBytes?: number;
+        afterBytes?: number;
+    };
+}
+/** 读取面在窗口序列之上派生的文件级视图(派生物可随时重算,不落盘)。 */
+export interface DiffFileSummary {
+    /** 净效果:首个触及窗口的起点 vs 最后触及窗口的终点;"none" = 动过但净无变化(创建又删除、改回原样)。 */
+    net: "added" | "modified" | "deleted" | "none";
+    /** 触及该文件的窗口标签,按时序。 */
+    windows: string[];
+    binary?: true;
+}
+/** agent 归因 diff 的消费视图:窗口序列(落盘事实)+ 派生的文件级摘要与终态读取。 */
 export interface DiffData {
-    generatedFiles: Record<string, string>;
-    deletedFiles: string[];
+    /** 落盘事实,原样。 */
+    windows: DiffWindow[];
+    /** 派生:每个被 agent 触及的文件一条。 */
+    files: Record<string, DiffFileSummary>;
+    /** 该文件最后一个触及窗口结束时的内容;净删除或从未触及返回 undefined。t.sandbox.diff.get 同一语义。 */
+    get(path: string): string | undefined;
 }
 export type Verdict = "passed" | "failed" | "errored" | "skipped";
 export interface JudgeConfig {

package/dist/shared/aggregate.d.ts

@@ -22,6 +22,7 @@ export declare function experimentGroupOf(experimentId: string): string | undefi
 export declare function evalPrefixPredicate(evals?: string | string[]): (id: string) => boolean;
 /** 无 experimentId 时的兜底标签。 */
 export declare function fallbackExperimentLabel(result: {
+    experimentId?: string;
     experiment?: ExperimentRunInfo;
     agent: string;
     model?: string;

package/dist/shared/aggregate.js

@@ -1,4 +1,4 @@
-// CLI 表格(runner/reporters/table.ts)与 view 榜单(view/aggregate.ts)共用的聚合小工具。
+// report 聚合(report/aggregate.ts)与 view 榜单(view/app/lib/rows.ts)共用的聚合小工具。
 // 实验标签推导、token/成本求和、verdict 排序各只有一份 —— 否则同一个实验在终端和网页上
 // 会显示成两个名字 / 两组数。保持环境无关(纯函数,只 type import)。
 /** 明细行排序:失败最靠前(failed > errored > skipped > passed 的紧急程度)。 */
@@ -47,8 +47,8 @@ export function evalPrefixPredicate(evals) {
 }
 /** 无 experimentId 时的兜底标签。 */
 export function fallbackExperimentLabel(result) {
-    if (result.experiment?.id)
-        return displayExperimentName(result.experiment.id) ?? result.experiment.id;
+    if (result.experimentId)
+        return displayExperimentName(result.experimentId) ?? result.experimentId;
     if (result.model)
         return `${result.agent}/${result.model}`;
     return result.agent || "ad hoc run";

package/dist/shared/types.d.ts

@@ -20,6 +20,34 @@ export interface SourceArtifact {
 }
 /** 通用清理闭包(setup 返回值 / teardown 的形状),异步同步皆可,统一在 finally 里执行。 */
 export type Cleanup = () => Promise<void> | void;
+/** `ScopedFeedback.progress` 的入参:此刻正在做什么(短命状态,可被后续更新覆盖)。 */
+export interface ProgressUpdate {
+    message: string;
+    current?: number;
+    total?: number;
+}
+/** `ScopedFeedback.diagnostic` 的入参:运行结束后仍应保留的问题(永久事件)。 */
+export interface DiagnosticInput {
+    code: string;
+    level: "warning" | "error";
+    message: string;
+    data?: Readonly<Record<string, JsonValue>>;
+    /** 并发 attempt 产生同一问题时的去重键;相同 key 折叠成一条并累计次数。 */
+    dedupeKey?: string;
+}
+/**
+ * 作用域反馈 API(见 docs/feature/experiments/library.md「生命周期代码怎样向这次运行反馈」):
+ * sandbox provider、sandbox hook、eval 与 Agent Adapter 从 runner 注入的上下文获得同一套入口。
+ * - `progress` 是短命状态:Human profile 更新 active 行,Agent/CI 不逐条打印,不进最终结果;
+ * - `diagnostic` 是永久事件:进 Human/Agent/CI 的永久输出流并落进 attempt 的 diagnostics;
+ *   即使 level 为 "error" 也不自动改变 verdict(要 errored 抛异常,要 failed 用断言)。
+ * 两个方法都不接受 phase / scope / 颜色 / 输出流——runner 知道当前回调属于哪个生命周期阶段,
+ * 调用方不能冒充其它阶段。
+ */
+export interface ScopedFeedback {
+    progress(update: ProgressUpdate): void;
+    diagnostic(input: DiagnosticInput): void;
+}
 /**
  * 可本地化文案:纯字符串,或按 locale 代码(如 "en"、"zh-CN")映射多语言。
  * view 按当前界面语言挑一条,挑不到回退到 en / 第一条。

package/dist/tty-line.d.ts

@@ -1,6 +1,2 @@
-/** live.ts 用来订阅"即将有一行独立诊断消息落地"。返回取消订阅函数。 */
-export declare function onBeforeExternalTerminalWrite(fn: () => void): () => void;
-/** 任何要绕开 Reporter 直接往终端打一行独立诊断消息的地方,写之前都先调用这个。 */
-export declare function beforeExternalTerminalWrite(): void;
 /** process.stderr.write 的替代:文本需自带换行(沿用现有 i18n 字符串的约定)。 */
 export declare function writeStderrLine(text: string): void;

package/dist/util.d.ts

@@ -10,6 +10,29 @@ export declare function stripComments(code: string): string;
  * `e instanceof Error ? e.message : String(e)`——那样用户永远看不出错误发生在哪一行。
  */
 export declare function formatThrown(e: unknown): string;
+/**
+ * 截到第一个换行为止。`formatThrown()` 优先带完整 `.stack`(含本地绝对文件路径的多行调用栈)
+ * 给需要按 file:line 定位问题的落盘产物(`EvalResult.error`、`niceeval show`);但机器消费的
+ * 单行 envelope(`FailureNotice.reason`、reporter 失败诊断的 `message`……)只要「一层可行动摘要」
+ * ——`Error.stack` 的第一行恒为 `name: message`,不含栈帧,直接满足这个要求。完整栈仍然原样
+ * 留在调用方各自的落盘字段里,这个函数只负责第二次、更短的那份表达,不是唯一出口。
+ */
+export declare function firstLine(text: string): string;
+/**
+ * 把 catch 到的 e 拆成 `AttemptError` 的三段:`message`(一层原因,Error.message,不带 name 前缀、
+ * 不拼 stack)、`stack`(完整多行栈,供 `niceeval show` 展开)、`cause`(沿 `e.cause` 取一层结构化
+ * 摘要 `{ name?, code?, message }`)。Node 的 `Error.stack` 不展开 cause 链,所以 cause 只能从
+ * `e.cause` 单独取。非 Error 值只给 message。
+ */
+export declare function describeError(e: unknown): {
+    message: string;
+    stack?: string;
+    cause?: {
+        name?: string;
+        code?: string;
+        message: string;
+    };
+};
 /** 零填充到 4 位(数据集扇出的 id:sql/0000)。 */
 export declare function pad4(n: number): string;
 /**

package/docs-site/zh/concepts/adapter.mdx

@@ -37,6 +37,7 @@ export function webAgent(options: WebAgentOptions): Agent {
   return defineAgent({
     name: "web-agent",
     async send(input, ctx) {
+      ctx.progress({ message: "等待 Web Agent" });
       const response = await fetch(`${baseUrl}/api/turn`, {
         method: "POST",
         headers: {
@@ -54,6 +55,12 @@ export function webAgent(options: WebAgentOptions): Agent {
       });
 
       if (!response.ok) {
+        ctx.diagnostic({
+          code: "agent-http-error",
+          level: "error",
+          message: `Web Agent 返回 HTTP ${response.status}`,
+          data: { status: response.status },
+        });
         return {
           status: "failed",
           events: [{ type: "error", message: `HTTP ${response.status}` }],
@@ -107,10 +114,12 @@ interface Agent {
 }
 ```
 
+`progress` 是运行中的短期状态，不落盘；`diagnostic` 是需要运行后回顾的有界 warning/error，会随 Attempt 保存。它们都不能指定 lifecycle phase，也不会自动改变 `Turn.status`。连接失败或响应无法解析时抛出异常；runner 会把它记录为 `errored`，并在终端给出可下钻的 locator。
+
 `send` 是唯一要实现的函数。它的签名里只有三个类型，分开看。
 
 <Note>
-  这里的 `setup` / `teardown` 是 Agent 自己"怎么连自己"的私事（装 CLI、写鉴权配置）。按实验变化的环境准备（装某个实验专属的二进制、预热、跨 attempt 保存状态）不写在 Agent 上，挂在 `sandbox` 字段那个 Sandbox spec 自己的 `.setup()` / `.teardown()` 链式方法上，见 [Sandbox 后端 · 环境钩子](/zh/guides/sandbox-providers#环境钩子)。
+  这里的 `setup` / `teardown` 是 Agent 自己"怎么连自己"的私事（装 CLI、写鉴权配置）。按实验变化的环境准备（装某个实验专属的二进制、预热、跨 attempt 保存状态）不写在 Agent 上，挂在 `sandbox` 字段那个 Sandbox spec 自己的 `.setup()` / `.teardown()` 链式方法上，见 [沙箱 provider · 环境钩子](/zh/guides/sandbox-providers#环境钩子)。
 </Note>
 
 ### 传入：`TurnInput`
@@ -182,10 +191,17 @@ Adapter 侧的对应义务：按 `requestId` 把裁决交回应用（不要按
 
 ```ts
 interface AgentContext {
-  // 每轮都在的三个
+  // 每轮都在的反馈与运行上下文
   readonly signal: AbortSignal;    // 运行器的超时与取消：透传给你发出的每个请求
   readonly session: AgentSession;  // 本条会话线的状态槽
-  log(msg: string): void;          // 写进本轮日志，niceeval view 里可见
+  progress(update: { message: string; current?: number; total?: number }): void;
+  diagnostic(input: {
+    code: string;
+    level: "warning" | "error";
+    message: string;
+    data?: Readonly<Record<string, JsonValue>>;
+    dedupeKey?: string;
+  }): void;
 
   // 按接入档位出现的三个（见「接入分三个 Tier」）
   readonly model?: string;         // Tier 1 的模型对比：experiment.model 透传；应用接口收模型选择就转发
@@ -194,7 +210,7 @@ interface AgentContext {
   readonly flags: Readonly<Record<string, unknown>>;  // Tier 3 的 feature A/B：experiment.flags 透传；没配时是 {}
   readonly experimentId?: string;  // 路径推导的实验 id，与结果里的 experimentId 同源；不经 experiment 跑时是 undefined
 
-  readonly sandbox?: Sandbox;      // 仅 defineSandboxAgent 构造的 Agent 会拿到
+  readonly sandbox: Sandbox;       // 非 sandbox 型 Agent 也会拿到一个 Sandbox（remote agent 是无操作的 stub）
 }
 
 interface AgentSession {
@@ -214,7 +230,9 @@ interface AgentSession {
 }
 ```
 
-`ctx` 里没有要你检查的标志位。三个档位字段都是"透传"语义：`model`、`flags` 由 experiment 声明、运行器原样递过来，Adapter 只负责随请求转发给应用，不解释它们的含义；`telemetry` 仅在配置了 OTel 接入时出现，`send` 里只需要把 `headers` spread 进请求头——接收端点在 `defineConfig` 里固定、由应用启动时指向，不从这里传，见[OTel 接入](/zh/guides/connect-otel)。`experimentId` 是路径推导出的稳定标识，典型用途是在 Sandbox 的环境钩子里按实验隔离跨 attempt 的状态（缓存目录名、沙箱快照 tag 按它分区），见 [Sandbox 后端 · 环境钩子](/zh/guides/sandbox-providers#环境钩子)。
+Runner 为 Agent 的 `setup`、每次 `send` 和 `teardown` 分别绑定 lifecycle scope。Adapter 只报告当前回调内部的 progress/diagnostic，不能传 phase、颜色或输出流。`progress` 不落盘；diagnostic 会进入 Attempt 的 `result.json`。无法继续时抛错，由 runner 保存结构化 error 并把 Attempt 标为 `errored`。
+
+`ctx` 里没有要你检查的标志位。三个档位字段都是"透传"语义：`model`、`flags` 由 experiment 声明、运行器原样递过来，Adapter 只负责随请求转发给应用，不解释它们的含义；`telemetry` 仅在配置了 OTel 接入时出现，`send` 里只需要把 `headers` spread 进请求头——接收端点在 `defineConfig` 里固定、由应用启动时指向，不从这里传，见[OTel 接入](/zh/guides/connect-otel)。`experimentId` 是路径推导出的稳定标识，典型用途是在 Sandbox 的环境钩子里按实验隔离跨 attempt 的状态（缓存目录名、沙箱快照 tag 按它分区），见 [沙箱 provider · 环境钩子](/zh/guides/sandbox-providers#环境钩子)。
 
 `session` 是本条会话线的自有状态，[NiceEval](https://niceeval.com/) 对它只承诺一件事：**同一条会话线的每次 `send` 拿到同一个 `ctx.session`，新会话线（eval 的第一轮，或 `t.newSession()` 之后）拿到一个全新的。** 会话续接（`id`/`capture`、`history`）和 HITL 停轮现场（`hold`/`take`）的存取器都在它上面，"第一轮"就是新会话线的自然形态——`id` 是 `undefined`、`history.get()` 是空数组，没有要判断的分支；`state` 是这些存取器之外的逃生舱，框架从不往里写数据。
 
@@ -239,7 +257,7 @@ interface Turn {
 ]
 ```
 
-对象统共九种类型（`message`、`action.*`、`input.requested`……完整清单见[事件流参考](/zh/reference/events)）。断言读的就是这个数组：`t.calledTool("get_weather")` 数 `action.called`，`t.reply` 取最后一条 assistant `message`。注意 `send` 每次只返回**本轮**的数组——跨轮拼成整条会话线是运行器的事，见下一节。多数情况下你也不手写这些对象：官方转换器的返回值就是一个填好 `events`、`usage`、`status` 的完整 `Turn`，怎么选转换器见[写 send](/zh/guides/write-send)。
+对象统共十种类型（`message`、`action.*`、`input.requested`……完整清单见[事件流参考](/zh/reference/events)）。断言读的就是这个数组：`t.calledTool("get_weather")` 数 `action.called`，`t.reply` 取最后一条 assistant `message`。注意 `send` 每次只返回**本轮**的数组——跨轮拼成整条会话线是运行器的事，见下一节。多数情况下你也不手写这些对象：官方转换器的返回值就是一个填好 `events`、`usage`、`status` 的完整 `Turn`，怎么选转换器见[写 send](/zh/guides/write-send)。
 
 `data` 不是"随便放点什么"的口袋，它只有一条规则：**要什么，由 eval 在 send 上用 schema 声明；声明了才有 data，拿到手就是声明的类型。**
 

package/docs-site/zh/concepts/assert.mdx

@@ -52,25 +52,26 @@ t.maxTokens(80_000).atLeast(0.7);                 // 降为 soft 并带阈值
 
 ## 判定规则
 
-所有断言收齐后，运行器按这个顺序折叠成一个结果：
+所有断言收齐后，运行器按固定优先级取第一个成立项，折叠成一个结果：
 
 ```
-执行出错(超时 / 异常 / 作者错误)                  → failed
-显式调用了 t.skip(reason)                        → skipped
-任一 gate 断言失败                                → failed
-所有 gate 都过，但至少一个 soft 低于阈值           → passed(--strict 下标红)
-否则                                              → passed
+执行异常、超时或作者错误                           → errored
+任一 gate 断言失败，或 --strict 下 soft 低于阈值    → failed
+显式调用了 t.skip(reason)                          → skipped
+否则                                               → passed
 ```
 
+`errored` 压过一切，因为执行证据已经不可信；`failed` 压过 `skipped`，避免 `t.skip()` 掩盖此前记录的硬失败。
+
 <CardGroup cols={2}>
   <Card title="passed" icon="circle-check" color="#22c55e">
-    没有错误，所有 gate 断言通过，所有 soft 断言都达到阈值。
+    没有错误，所有 gate 断言通过，所有 soft 断言都达到阈值（或未开 `--strict`）。
   </Card>
   <Card title="failed" icon="circle-xmark" color="#ef4444">
-    执行出错，或至少一个 gate 断言没通过。硬失败。
+    至少一个 gate 断言没通过，或 `--strict` 下有 soft 断言低于阈值。硬失败。
   </Card>
-  <Card title="passed（计分）" icon="chart-bar" color="#f59e0b">
-    所有 gate 都过，但至少一个 soft 低于阈值。质量回归——默认不报红，`--strict` 下才报红。
+  <Card title="errored" icon="triangle-exclamation" color="#f59e0b">
+    执行异常、超时或作者错误，本次执行无法形成可信结论——不伪装成断言失败。
   </Card>
   <Card title="skipped" icon="forward" color="#6b7280">
     调用了 `t.skip("reason")`。完全排除在通过率统计之外。

package/docs-site/zh/concepts/evals.mdx

@@ -1,7 +1,7 @@
 ---
 title: "NiceEval 中的 eval：生命周期、verdict 与文件"
 sidebarTitle: "评估"
-description: "eval 是一个测试用例：描述、agent 引用和 test 函数。了解 eval 如何被发现、调度、评分和报告。"
+description: "eval 是一个测试用例：描述和 test 函数，agent-neutral。了解 eval 如何被发现、调度、评分和报告。"
 ---
 
 一个 eval 是一个可运行的测试用例。它通常由一个 `*.eval.ts` 文件导出，通过 `defineEval` 声明。
@@ -28,9 +28,10 @@ export default defineEval({
 | 字段 | 说明 |
 |---|---|
 | `description` | 给人看的描述，出现在报告里 |
-| `agent` | 使用哪个 Adapter，可由配置或 CLI 覆盖 |
 | `test(t)` | 交互和断言逻辑 |
 
+eval 本身不声明用哪个 Agent——它默认保持 agent-neutral，同一个 eval 可以在不同 experiment 下跑不同 Agent。选哪个 Agent 是 experiment 的字段，不由 CLI 临时覆盖。
+
 <Note>
   不要手写 `id` 或 `name`。[NiceEval](https://niceeval.com/) 从文件路径推导 ID。
 </Note>
@@ -73,13 +74,13 @@ npx niceeval exp local weather/brooklyn
 
 <CardGroup cols={2}>
   <Card title="passed" icon="circle-check" color="#22c55e">
-    所有 gate 断言通过，并且没有未满足的硬失败。
+    所有 gate 断言通过（`--strict` 下 soft 断言也都达到阈值），并且没有执行错误。
   </Card>
   <Card title="failed" icon="circle-xmark" color="#ef4444">
-    至少一个 gate 断言失败，或运行本身失败。
+    至少一个 gate 断言失败，或 `--strict` 下有 soft 断言低于阈值。
   </Card>
-  <Card title="passed" icon="chart-bar" color="#f59e0b">
-    没有 gate 失败，但 soft 分数需要保留为分值。
+  <Card title="errored" icon="triangle-exclamation" color="#f59e0b">
+    执行异常、超时或作者错误，本次执行无法形成可信结论。
   </Card>
   <Card title="skipped" icon="forward" color="#6b7280">
     eval 主动跳过，通常通过 `t.skip(reason)`。

package/docs-site/zh/concepts/experiment.mdx

@@ -25,7 +25,7 @@ export default defineExperiment({
 - `model` / `flags`：透传语义。[NiceEval](https://niceeval.com/) 不解释它们的含义，原样经 `ctx` 递给 Adapter，由 Adapter 随请求转发、应用按需切换——这正是 [Tier](/zh/concepts/tier) 里模型对比（Tier 1）和 feature A/B（Tier 3）的通道。
 - `runs`、`budget`、并发、`sandbox` 等运行参数：怎么跑、跑多少。完整字段见[写实验](/zh/guides/write-experiment)。
 
-Experiment 是纯配置数据，没有 `setup` / `teardown` 这类生命周期字段。要按实验准备环境（装二进制、预热、跨 attempt 存取状态），挂在 `sandbox` 字段的 spec 上——`dockerSandbox()` 等工厂返回的对象可以链 `.setup()` / `.teardown()`，见 [Sandbox 后端 · 环境钩子](/zh/guides/sandbox-providers#环境钩子)。
+Experiment 是纯配置数据，没有 `setup` / `teardown` 这类生命周期字段。要按实验准备环境（装二进制、预热、跨 attempt 存取状态），挂在 `sandbox` 字段的 spec 上——`dockerSandbox()` 等工厂返回的对象可以链 `.setup()` / `.teardown()`，见 [沙箱 provider · 环境钩子](/zh/guides/sandbox-providers#环境钩子)。
 
 ## 矩阵对比
 

package/docs-site/zh/concepts/overview.mdx

@@ -1,10 +1,10 @@
 ---
 title: "NiceEval 架构：evals、agents 与 sandboxes"
 sidebarTitle: "概览"
-description: "理解 NiceEval、Adapter 和 Sandbox backend 如何配合，用统一 API 评估任意 AI agent。"
+description: "理解 NiceEval、Adapter 和 Sandbox Provider 如何配合，用统一 API 评估任意 AI Agent。"
 ---
 
-[NiceEval](https://niceeval.com/) 的核心设计是把“评测逻辑”与“如何连接被测对象”分开。[NiceEval](https://niceeval.com/) 负责发现、调度、评分和报告；Adapter 负责调用被测系统；Sandbox backend 负责隔离文件系统。
+[NiceEval](https://niceeval.com/) 的核心设计是把“评测逻辑”与“如何连接被测对象”分开。[NiceEval](https://niceeval.com/) 负责发现、调度、评分和报告；Adapter 负责调用被测系统；Sandbox Provider 负责隔离文件系统。
 
 ## 四层架构
 
@@ -15,7 +15,7 @@ NiceEval
         ↓
 Adapter
         ↓
-Subject under test / Sandbox backend
+Subject under test / Sandbox Provider
 ```
 
 ## NiceEval 负责什么
@@ -53,12 +53,12 @@ Subject under test / Sandbox backend
 
 <Tabs>
   <Tab title="Docker">
-    本地容器后端，适合开发和 CI 中的 coding-agent eval。
+    本地容器 Provider，适合开发和 CI 中的 coding-agent eval。
   </Tab>
   <Tab title="Vercel Sandbox">
-    云端 sandbox 后端，适合更强隔离或更大的运行资源。
+    云端 Sandbox Provider，适合更强隔离或更大的运行资源。
   </Tab>
-  <Tab title="第三方后端">
+  <Tab title="第三方 Provider">
     只要实现 `Sandbox` 接口，就可以接入其他沙箱服务。
   </Tab>
 </Tabs>
@@ -67,7 +67,7 @@ Subject under test / Sandbox backend
 
 <AccordionGroup>
   <Accordion title="Eval">
-    一个测试用例：描述、agent 引用和 `test(t)` 函数。
+    一个测试用例：描述和 `test(t)` 函数，agent-neutral——用哪个 Agent 由 experiment 决定。
   </Accordion>
   <Accordion title="Agent">
     [NiceEval](https://niceeval.com/) 通过名字调用的一条连接，负责返回标准 `Turn`。