niceeval 0.6.1 → 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 透传；应用接口收模型选择就转发
@@ -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` 是这些存取器之外的逃生舱，框架从不往里写数据。
 

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>

package/docs-site/zh/guides/agent-feedback-loop.mdx

@@ -38,7 +38,7 @@ AI 通常按任务选择这些入口：
 <Steps>
   <Step title="运行实验">
     ```bash
-    npx niceeval exp local
+    npx niceeval exp local --output agent
     ```
 
     先读取退出码：`0` 表示所有 Eval 通过；`1` 表示至少一个 Eval 失败或出错；`2` 表示 NiceEval 自身未能完成运行。退出码决定是否继续，控制台文本用于定位原因。
@@ -59,7 +59,7 @@ AI 通常按任务选择这些入口：
 
     `--execution` 合并 AI 输出与 trace：标准事件流提供消息、thinking、tool call/result 和 Skill load；OTel 在能够关联时给同一节点补开始时间、耗时、父子关系和错误状态。没有 OTel 时步骤仍完整，只不显示时间。
 
-    不带证据 flag 时，`show @<id>` 是失败诊断首页。它先列出失败断言的 group、matcher、expected、received、原因和源码位置，再给执行与文件变化摘要。AI 应该先读这一页；只有需要回答“为什么产生这个值”时，才继续打开对应证据。
+    不带证据 flag 时，`show @<id>` 是失败诊断首页。它先列出失败断言的 group、matcher、expected、received、原因和源码位置，再给执行、生命周期阶段耗时与文件变化摘要。AI 应该先读这一页；只有需要回答“为什么产生这个值”时，才继续打开对应证据。
 
     ```text
     $ niceeval show @1k2m9qtr
@@ -89,20 +89,16 @@ AI 通常按任务选择这些入口：
         source: evals/memory/swelancer-manager-proposals.eval.ts:40:11
 
     execution: 3 events · 0 skill loads · 0 tool calls · 1 AI messages
-    timing: OTel spans recorded for this attempt — see --execution for per-step timing.
-    agent run                     ▕████████████████████▏ 41.2s
-    ├─ inference                  ▕█████░░░░░░░░░░░░░░░▏ 10.1s · "布鲁克林今天大约 24°C，晴。"
-    ├─ inference                  ▕░░░░░█████████░░░░░░▏ 18.3s
-    └─ inference                  ▕░░░░░░░░░░░░░░██████▏ 12.4s
-    no tool calls
+    timing: eval.run 40.4s · scoring.evaluate 0.5s · teardown +0.2s
 
     changes · diff unavailable
     reason: this Attempt did not produce workspace file changes
 
-    full eval source: …/weather/brooklyn/a2/eval-source.ts
+    full eval source: …/weather/brooklyn/a2/sources.json
     available:
       niceeval show @1k2m9qtr --eval
       niceeval show @1k2m9qtr --execution
+      niceeval show @1k2m9qtr --timing
     ```
 
     `--execution` 把 AI 消息、Skill load、工具调用和工具结果排成一棵执行树。它只展示 Agent 可理解的事件；没有关联到这些事件的 SDK / runtime span 不逐行输出，只报告省略数量并保留 `trace.json` 路径。下面的 Attempt 有 OTel，所以能关联的节点同时带相对时间与耗时：
@@ -175,9 +171,10 @@ AI 通常按任务选择这些入口：
 
     | 要回答的问题 | 入口 | 输出必须包含 |
     | --- | --- | --- |
-    | 快速判断一次 Attempt 发生了什么 | `niceeval show @<id>` | Eval 断言、执行步骤、可选 OTel 时间、diff 摘要及各块可用性 |
+    | 快速判断一次 Attempt 发生了什么 | `niceeval show @<id>` | Eval 断言、执行步骤、生命周期阶段耗时摘要、diff 摘要及各块可用性 |
     | Eval 实际检查了什么，哪条 gate / soft 为什么通过或失败 | `niceeval show @<id> --eval` | 运行时 Eval 源码、源码哈希、断言所在行、严重度、分数与原因 |
-    | AI 做了什么、调用了什么、时间花在哪里 | `niceeval show @<id> --execution` | 消息、thinking、Skill load、工具调用与结果；有 OTel 时在同一节点显示时间、父子关系和错误状态 |
+    | AI 做了什么、调用了什么 | `niceeval show @<id> --execution` | 消息、thinking、Skill load、工具调用与结果；有 OTel 时在同一节点附时间、父子关系和错误状态 |
+    | 整个 Attempt 的时间花在哪里 | `niceeval show @<id> --timing` | lifecycle → hook/turn → shell → OTel 的统一时间树；出错的 Attempt 标出已知的最深失败节点 |
     | Sandbox 工作区文件变成什么 | `niceeval show @<id> --diff` | 文件摘要、增删行数、具体补丁和原始 diff 路径；无文件工作区时明确 unavailable |
   </Step>
   <Step title="提出假设并修改">
@@ -195,7 +192,7 @@ AI 通常按任务选择这些入口：
   </Step>
   <Step title="局部重跑并验证假设">
     ```bash
-    npx niceeval exp local weather/brooklyn --force
+    npx niceeval exp local weather/brooklyn --output agent --force
     npx niceeval show weather/brooklyn
     ```
 
@@ -203,7 +200,7 @@ AI 通常按任务选择这些入口：
   </Step>
   <Step title="全量确认没有回归">
     ```bash
-    npx niceeval exp local --force
+    npx niceeval exp local --output agent --force
     npx niceeval show
     ```
 
@@ -213,19 +210,22 @@ AI 通常按任务选择这些入口：
 
 ## AI 应该从输出里读什么
 
-`exp` 运行结束后会给出三类信息：失败摘要、结果统计和结果快照目录。典型输出如下：
+`--output agent` 运行中只向 stderr 追加低频 checkpoint（存活信号，不是结果数据源），结束时向 stdout 打印一个有界 handoff block——这才是 AI 应该解析的部分：
 
 ```text
-Failing:
-  ✗ weather/brooklyn · @1k2m9qtr
-      gate calledTool("get_weather"): tool was never called
-
-Results: 14 passed, 1 failed, 0 errored, 0 skipped
-Structured results: .niceeval/local/2026-07-09T10-00-00-000Z-x1f2/
-  (snapshot.json + 每 attempt 的 result.json / events.json / trace.json / diff.json)
+NICEEVAL RESULT failed
+summary: 14 passed, 1 failed, 0 errored (0 reused)
+snapshots:
+  - .niceeval/local/2026-07-09T10-00-00-000Z-x1f2/
+failures:
+  - @1k2m9qtr weather/brooklyn [local]
+    gate: tool was never called
+next:
+  niceeval show @1k2m9qtr
+  niceeval show @1k2m9qtr --execution
 ```
 
-AI 应先从失败项选中 Attempt locator，再按证据位执行 `niceeval show @<id>` 或对应证据 flag，不要从头解析运行期间不断刷新的进度行。需要机器读取时，结果快照是事实来源：
+AI 应先从 `failures` 选中 Attempt locator，再按证据位执行 `next` 给出的 `niceeval show @<id>` 或对应证据 flag，不要解析运行期间 stderr 上低频追加的 checkpoint 行——那些只用于判断进程是否存活。失败条数超过上限（默认 5 条）时,handoff 只展开前几条并给出总数,完整清单读结果快照。需要机器读取时，结果快照是事实来源：
 
 ```text
 .niceeval/<experiment>/<快照>/
@@ -238,7 +238,7 @@ AI 应先从失败项选中 Attempt locator，再按证据位执行 `niceeval sh
 ```
 
 - `snapshot.json` 记录实验身份、运行配置、格式版本和时间。
-- `result.json` 记录该 Attempt 的判定、断言、错误和用量。
+- `result.json` 记录该 Attempt 的判定、断言、结构化错误、diagnostics 和用量；瞬时 progress 不落盘。
 - `events.json` 是对话与工具调用事件，`trace.json` 是调用链，`diff.json` 是 Sandbox 文件变化。
 - 某类证据不存在时，对应文件不会生成。先以 `show` 的提示为准，不要假设每个目录都有全部文件。
 
@@ -268,12 +268,14 @@ AI 应先从失败项选中 Attempt locator，再按证据位执行 `niceeval sh
 
 ```text
 读取 node_modules/niceeval/INDEX.md，再按索引读取与任务有关的文档。
-运行 npx niceeval exp local，并根据退出码和失败摘要决定下一步。
+运行 npx niceeval exp local --output agent，并根据退出码和失败 locator 决定下一步。
 对每个失败的 Eval，从报告选择一个 Attempt locator；再运行 niceeval show @<id>
-并按问题选择默认 Eval 源码面、--execution 或 --diff。写出失败原因的假设，并判断应该修改被测程序、
+并按问题选择 --eval、--execution、--timing 或 --diff；--timing 从 lifecycle 展开 setup/teardown
+hook、shell 命令、每轮 send 与可关联的 OTel model/tool，回答整个 Attempt 的时间花在哪里。
+写出失败原因的假设，并判断应该修改被测程序、
 Eval，还是实验环境。修改后用 --force 重跑对应 Eval，比较新的判定和证据。
 同一问题连续三轮没有新证据或改善时停止并汇报，不要靠放宽断言碰绿。
-全部局部失败清零后，用 npx niceeval exp local --force 全量验证；退出码 0 才完成。
+全部局部失败清零后，用 npx niceeval exp local --output agent --force 全量验证；退出码 0 才完成。
 ```
 
 真实 Agent 的运行可能产生费用。实验阶段可以加 `--budget <美元>` 限制本轮累计成本；预算只能限制单次命令，不能替代上面的停止条件。

package/docs-site/zh/guides/authoring.mdx

@@ -18,6 +18,7 @@ export default defineEval({
   reporters?: Reporter[];
   timeoutMs?: number;
   metadata?: Record<string, unknown>;
+  async setup(sandbox, ctx) { /* task fixture + progress/diagnostic */ },
   async test(t) { /* interactions + assertions */ },
 });
 ```
@@ -111,6 +112,38 @@ export default defineEval({
 
 详见 [Fixtures](/zh/guides/fixtures)。
 
+## 从 Eval 报告长步骤和诊断
+
+`setup` 用于这条 Eval 的任务夹具。第二个参数绑定到 eval setup 阶段；`test(t)` 里的反馈绑定到 eval run 阶段：
+
+```ts
+export default defineEval({
+  async setup(sandbox, ctx) {
+    ctx.progress({ message: "安装 fixture 依赖" });
+    await sandbox.runCommand("npm", ["install"]);
+  },
+
+  async test(t) {
+    t.progress({ message: "上传隐藏测试", current: 1, total: 2 });
+    await t.sandbox.uploadDirectory("../fixtures/project");
+
+    const preflight = await inspectFixture();
+    if (preflight.usedFallback) {
+      t.diagnostic({
+        code: "fixture-check-degraded",
+        level: "warning",
+        message: "Fixture 预检使用了备用检查器",
+        data: { checker: preflight.checker },
+      });
+    }
+
+    await t.send("完成任务");
+  },
+});
+```
+
+`progress` 只更新运行中的短期状态，不进入结果。`diagnostic` 会写进当前 Attempt 的 `result.json`，但不会代替断言或自动改变判定：业务结论仍用 `t.check` / `t.require` / gate；基础设施无法继续时抛出异常。
+
 ## 命名约定
 
 <CardGroup cols={2}>

package/docs-site/zh/guides/ci-integration.mdx

@@ -11,9 +11,15 @@ Evals 应该和测试一样进入 CI。它们能在 PR 阶段发现 agent 行为
 默认情况下，只要存在失败的 gate，[NiceEval](https://niceeval.com/) 将以非零状态码退出。CI 中通常使用 `--strict`，让失败更明确。
 
 ```bash
-npx niceeval exp ci --strict
+NICEEVAL_LANG=en npx niceeval exp ci \
+  --output ci \
+  --strict \
+  --json .niceeval/ci-summary.json \
+  --junit .niceeval/junit.xml
 ```
 
+CI profile 不输出 ANSI、spinner 或动态表格。日志使用单一有序 stdout 流，只追加 start、低频 heartbeat、失败/错误、diagnostic 和最终 result；通过的 Attempt 不逐条打印。
+
 ## GitHub Actions 示例
 
 ```yaml
@@ -32,8 +38,12 @@ jobs:
           node-version: 22
           cache: npm
       - run: npm ci
-      - run: npx niceeval exp ci --strict
+      - run: >-
+          npx niceeval exp ci --output ci --strict
+          --json .niceeval/ci-summary.json
+          --junit .niceeval/junit.xml
         env:
+          NICEEVAL_LANG: en
           OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
           ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
 ```
@@ -52,18 +62,19 @@ jobs:
   </Step>
 </Steps>
 
-## JUnit reporter
-
-```ts
-import { defineConfig } from "niceeval";
-import { Console, JUnit } from "niceeval/reporters";
+## JSON、JUnit 和结构化错误
 
-export default defineConfig({
-  reporters: [Console(), JUnit(".niceeval/junit.xml")],
-});
+```text
+niceeval: start total=24 configs=3 concurrency=10 reused=18
+niceeval: errored locator=@12h8m4k1 eval=fixtures/button experiment=ci/codex phase=sandbox.create reason="E2B sandbox allocation failed after 5 attempts"
+niceeval: result=failed passed=23 failed=0 errored=1 reused=18 duration=128s
+niceeval: json=.niceeval/ci-summary.json
+niceeval: junit=.niceeval/junit.xml
 ```
 
-CI 可以上传 JUnit XML，让失败出现在测试报告 UI 里。想把结果同时上报到 Braintrust 这类实验平台，见 [Reporter 上报](./reporters)。
+退出码是第一层红绿信号；JSON、JUnit 和结果快照是完整机器接口，日志行只用于搜索和 annotation。`errored` 行带 locator、eval/experiment 身份、已知时的正式 phase，以及一层 `reason` 摘要。详细 cause、stack 和 diagnostics 保存在 Attempt 的 `result.json`，可在保留 artifact 后运行 `niceeval show @<locator>` 回顾。
+
+CLI 显式要求的 JSON/JUnit 和默认 results artifact 都是 required 输出：写入失败必须让 job 判红，不能只留 warning 后退出 0。想把结果同时上报到 Braintrust 这类实验平台，见 [Reporter 上报](./reporters)。
 
 ## 只检查发现
 
@@ -80,7 +91,7 @@ npx niceeval list
 ## 控制并发
 
 ```bash
-npx niceeval exp ci --max-concurrency 2
+npx niceeval exp ci --output ci --max-concurrency 2
 ```
 
 标准 GitHub-hosted runner 上，sandbox eval 并发不宜过高。远程 HTTP eval 可以按服务限流能力调高。