niceeval 0.6.1 → 0.6.2

package/dist/agents/types.d.ts

@@ -1,4 +1,4 @@
-import type { Cleanup } from "../shared/types.ts";
+import type { Cleanup, DiagnosticInput, ProgressUpdate } from "../shared/types.ts";
 import type { StreamEvent, TraceSpan, Usage } from "../o11y/types.ts";
 import type { Sandbox } from "../sandbox/types.ts";
 /**
@@ -75,11 +75,51 @@ export interface AgentSetupManifest {
         command: string;
         args?: string[];
     }>;
+    /**
+     * 官方原生配置文件(Claude Code `settings.json` / Codex `config.toml`):只记 Agent 名、
+     * 项目相对来源路径与原始字节的 SHA-256,不落正文 —— 任意官方配置都可能携带敏感字符串,
+     * 不能靠字段白名单证明适合原样落盘。
+     */
+    nativeConfigFile?: {
+        agent: "claude-code" | "codex";
+        path: string;
+        sha256: string;
+    };
     /** Bub 的 Python Plugin(规范化后的 package 串)。 */
     pythonPlugins?: Array<{
         package: string;
     }>;
 }
+/** 证据通道的覆盖状态。省略(不声明)= unknown,不是 complete——消费侧与 unavailable 同样保守。 */
+export type CoverageStatus = "complete" | "partial" | "unavailable";
+/** 单个证据通道的覆盖声明:状态 + 可选的人可读原因(如 "stream reconnected mid-turn")。 */
+export interface CoverageDeclaration {
+    status: CoverageStatus;
+    reason?: string;
+}
+/**
+ * 覆盖声明(EvidenceCoverage):完整性不是口头承诺,是随数据走的声明
+ * (见 docs/feature/adapters/architecture/evidence.md)。两层:
+ * - Agent 级默认(`defineAgent` / `defineSandboxAgent` 的 `coverage`)声明该 Adapter 的常态覆盖;
+ *   官方 SDK 适配器显式声明全通道 complete(用 `completeCoverage` 常量)。
+ * - Turn 级降级(`Turn.coverage`)只用于相对 Agent 默认值降级(这一轮流断了 / 拿不到 usage),
+ *   不能把 Agent 未声明的通道升格成 complete。
+ * 整个 Agent 不声明时全部通道视为 unknown。
+ */
+export interface EvidenceCoverage {
+    /** 完整事件流(event / notEvent / order 的依据)。 */
+    events?: CoverageDeclaration;
+    /** action 生命周期(工具正负断言、顺序、失败的依据)。 */
+    actions?: CoverageDeclaration;
+    /** assistant / user message(reply、messageIncludes 的依据)。 */
+    messages?: CoverageDeclaration;
+    /** usage(token / cost 上限断言的依据)。 */
+    usage?: CoverageDeclaration;
+    /** Turn status 的真实性(succeeded / parked 的依据)——恒 completed 的映射必须声明非 complete。 */
+    status?: CoverageDeclaration;
+    /** Turn.data(outputEquals / outputMatches 的依据)。 */
+    data?: CoverageDeclaration;
+}
 /** 随一轮消息附带的文件(图片等多模态输入)。 */
 export interface InputFile {
     /** 文件名(可选,供 adapter / 模型参考)。 */
@@ -115,6 +155,11 @@ export interface Turn {
     readonly data?: unknown;
     readonly status: "completed" | "failed" | "waiting";
     readonly usage?: Usage;
+    /**
+     * 本轮相对 Agent 默认覆盖的降级声明(这一轮流断了、拿不到 usage 等);
+     * 只能降级,不能把 Agent 未声明的通道升格成 complete(见 EvidenceCoverage)。
+     */
+    readonly coverage?: EvidenceCoverage;
 }
 /**
  * 本次运行的 OTLP traces 接收信息(仅当配置了 OTel 接入时有——agent 的 `tracing` 块 /
@@ -241,10 +286,21 @@ export interface AgentContext {
      */
     readonly telemetry?: Telemetry;
     /**
-     * 写一行进运行器自身的进度日志(落 stderr,或调用方传入的 `onProgress` 回调)。
-     * 超时失败时,最近若干行会并入结果的 error 信息,方便定位卡在哪一步。
-     * 与 `Sandbox.appendLog` 是两回事:那个是把一行写进容器自己的原生日志
-     * (`docker logs` 能看到),这里只是运行器的观测通道。
+     * 作用域反馈:报告此刻正在做什么(turn / tool / 安装进度)。短命状态——Human profile
+     * 更新 active 行,`agent`/`ci` 不逐条打印,也不进最终结果;不要每个 token/delta 都调用。
+     * runner 按当前回调所处的生命周期阶段(agent.setup / agent.run / agent.teardown)归因,
+     * 调用方不能冒充其它阶段(见 docs/feature/experiments/library.md)。
+     */
+    progress(update: ProgressUpdate): void;
+    /**
+     * 作用域反馈:报告运行结束后仍应保留的问题(协议降级、数据不完整、cleanup 问题)。
+     * 永久事件,落进 attempt 的 diagnostics 并进各 profile 的永久输出;`dedupeKey` 去重。
+     * 即使 level 为 "error" 也不改变 Turn.status / verdict——无法继续时抛异常。
+     */
+    diagnostic(input: DiagnosticInput): void;
+    /**
+     * `progress({ message: msg })` 的别名,不是第二条通道(见 docs/feature/experiments/cli.md
+     * 「Attempt 阶段」)。超时失败时最近若干行会并入结果的 error 信息,方便定位卡在哪一步。
      */
     log(msg: string): void;
 }
@@ -272,6 +328,8 @@ export interface Agent {
      * `t.sandbox`/`t.sandbox.fileChanged()` 等文件系统断言,见 docs-site「能力从哪来」一节。
      */
     readonly kind: "sandbox" | "remote";
+    /** 该 Adapter 的常态证据覆盖声明;省略 = 全通道 unknown(见 EvidenceCoverage)。 */
+    coverage?: EvidenceCoverage;
     setup?: AgentSetup;
     /** OTLP 导出配置(仅当此字段存在时运行器才为该 agent 开 OTLP 接收);与 setup 分开,见 AgentTracing。 */
     tracing?: AgentTracing;
@@ -284,6 +342,8 @@ export interface Agent {
 export interface SandboxAgentDef {
     /** agent 的显示名/标识,原样进入 `Agent.name`——不是注册表查找 key,只用于展示、结果归属与去重指纹。 */
     name: string;
+    /** 该 Adapter 的常态证据覆盖声明(完整采集的用 `completeCoverage` 常量);省略 = 全通道 unknown。 */
+    coverage?: EvidenceCoverage;
     /**
      * 每个沙箱一次(不是每轮一次):装 CLI、写 config.toml / 鉴权配置(model/base/auth 等
      * 本轮内不变的东西)。运行器在沙箱备好(上传/基线/eval.setup 之后)、第一次 send 前
@@ -303,6 +363,8 @@ export interface SandboxAgentDef {
 export interface RemoteAgentDef {
     /** agent 的显示名/标识,原样进入 `Agent.name`——不是注册表查找 key,只用于展示、结果归属与去重指纹。 */
     name: string;
+    /** 该 Adapter 的常态证据覆盖声明(完整采集的用 `completeCoverage` 常量);省略 = 全通道 unknown。 */
+    coverage?: EvidenceCoverage;
     /**
      * 每个 attempt 一次(remote agent 没有真实沙箱,运行器会传入一个仅含 `workdir`/`sandboxId`/
      * `otlpHost`/`stop` 等元信息的 stub `Sandbox`,其余方法调用即抛错——不要在这里调用

package/dist/context/types.d.ts

@@ -1,6 +1,12 @@
 import type { InputRequest, StreamEvent, ToolCall, Usage } from "../o11y/types.ts";
+import type { DiagnosticInput, ProgressUpdate } from "../shared/types.ts";
 import type { AssertionHandle, ValueAssertion } from "../scoring/types.ts";
 import type { CommandOptions, CommandResult, ReadSourceFilesOptions, SandboxFile, SourceFiles } from "../sandbox/types.ts";
+/** `t.send()` / `session.send()` 的入参:字符串,或带附件的结构化消息。 */
+export type SendInput = string | {
+    text: string;
+    files?: readonly import("../agents/types.ts").InputFile[];
+};
 /** t.send() 返回的句柄:从事件流派生便利字段 + expectOk。 */
 export interface TurnHandle {
     /** 本轮的原始事件流(工具调用、消息增量等);下面的派生字段都算自它。 */
@@ -51,8 +57,8 @@ export interface TurnHandle {
     calledSubagent(name: string, match?: SubagentMatch): AssertionHandle;
     /** 断言本轮事件按给定类型顺序出现(允许中间夹杂其它事件)。 */
     eventOrder(types: StreamEvent["type"][]): AssertionHandle;
-    /** 用自定义谓词对本轮整段事件流断言;失败时用 label 说明原因。 */
-    eventsSatisfy(predicate: (events: readonly StreamEvent[]) => boolean, label?: string): AssertionHandle;
+    /** 用自定义谓词对本轮整段事件流断言;label 必填、进断言标题(谓词不透明,解释责任在 label)。 */
+    eventsSatisfy(label: string, predicate: (events: readonly StreamEvent[]) => boolean): AssertionHandle;
     /** 断言本轮 token 用量不超过 max。 */
     maxTokens(max: number): AssertionHandle;
     /** 断言本轮花费(USD)不超过 usd。 */
@@ -90,7 +96,11 @@ export interface DiffView {
 }
 /** 工具匹配小语言。 */
 export interface ToolMatch {
-    /** 只匹配入参包含这些键值的调用(浅层包含,非深度相等)。 */
+    /**
+     * 只匹配入参包含这些键值的调用:**深度部分匹配**——嵌套对象逐键下钻,数组按值比较;
+     * 值可以是 RegExp(对字符串字段测试,不命中时再对整个 input 的序列化串兜底测一次)
+     * 或谓词函数。不要求深度相等,多余的入参键不影响命中。
+     */
     input?: Record<string, unknown>;
     /** 精确匹配调用次数,省略则只要求「至少一次」。 */
     count?: number;
@@ -173,8 +183,8 @@ export interface SandboxHandle {
  * 只看最后一轮要用 `send()` 返回的 TurnHandle。
  */
 export interface SessionHandle {
-    /** 在这个会话里发一条消息,返回该轮的 TurnHandle。 */
-    send(text: string): Promise<TurnHandle>;
+    /** 在这个会话里发一条消息(字符串或结构化消息),返回该轮的 TurnHandle。 */
+    send(input: SendInput): Promise<TurnHandle>;
     /** 在这个会话里发一条带文件的消息,语义同 TestContext.sendFile。 */
     sendFile(path: string, text?: string): Promise<TurnHandle>;
     /** 取这个会话里等待中的 HITL 输入请求;拿不到就抛,语义同 TestContext.requireInputRequest。 */
@@ -219,8 +229,8 @@ export interface SessionHandle {
     calledSubagent(name: string, match?: SubagentMatch): AssertionHandle;
     /** 断言这个会话累计事件按给定类型顺序出现。 */
     eventOrder(types: StreamEvent["type"][]): AssertionHandle;
-    /** 用自定义谓词对这个会话累计的整段事件流断言。 */
-    eventsSatisfy(predicate: (events: readonly StreamEvent[]) => boolean, label?: string): AssertionHandle;
+    /** 用自定义谓词对这个会话累计的整段事件流断言;label 必填、进断言标题。 */
+    eventsSatisfy(label: string, predicate: (events: readonly StreamEvent[]) => boolean): AssertionHandle;
     /** 断言这个会话累计 token 用量不超过 max。 */
     maxTokens(max: number): AssertionHandle;
     /** 断言这个会话累计花费(USD)不超过 usd。 */
@@ -235,8 +245,8 @@ export interface SessionHandle {
  * 用一个宽接口承载全部动作(运行时按 capability 守卫)。
  */
 export interface TestContext {
-    /** 向默认会话发一条消息,返回该轮的 TurnHandle。事件同时累加进默认会话的累计事件流,供下面的作用域断言使用。 */
-    send(text: string): Promise<TurnHandle>;
+    /** 向默认会话发一条消息(字符串或结构化消息),返回该轮的 TurnHandle。事件同时累加进默认会话的累计事件流,供下面的作用域断言使用。 */
+    send(input: SendInput): Promise<TurnHandle>;
     /** 发一条带文件(图片等多模态输入)的消息。`path` 相对项目根;读出后 base64 随 TurnInput.files 交给 adapter。 */
     sendFile(path: string, text?: string): Promise<TurnHandle>;
     /** 取默认会话里等待中的 HITL 输入请求;不传 filter 要求恰好一条,拿不到就抛。 */
@@ -268,7 +278,17 @@ export interface TestContext {
     readonly reasoningEffort?: string;
     /** 本次 attempt 生效的实验 flags(experiment.flags 的只读视图;实验条件,非命令行开关)。 */
     readonly flags: Readonly<Record<string, unknown>>;
-    /** 打一行调试日志;有 live 进度回调时走该回调,否则落到 stderr,不出现在最终结果里。 */
+    /**
+     * 作用域反馈:报告 eval 自己执行的长步骤(上传 fixture、跑构建……)。短命状态,scope 固定
+     * 为 `eval.run`;只报告不断言(见 docs/feature/eval/library/context.md「向运行反馈长步骤」)。
+     */
+    progress(update: ProgressUpdate): void;
+    /**
+     * 作用域反馈:报告运行结束后仍需保留的问题(永久事件,落 attempt diagnostics)。
+     * 即使 level 为 "error" 也不自动改变 verdict——测试结论仍由断言决定。
+     */
+    diagnostic(input: DiagnosticInput): void;
+    /** `progress({ message: msg })` 的别名(调试日志),不出现在最终结果里。 */
     log(msg: string): void;
     /** 立即中止本 eval 并标记为 skipped(verdict / EvalResult.skipReason),reason 不能为空。 */
     skip(reason: string): never;
@@ -320,8 +340,8 @@ export interface TestContext {
     calledSubagent(name: string, match?: SubagentMatch): AssertionHandle;
     /** 断言默认会话累计事件按给定类型顺序出现(允许中间夹杂其它事件)。 */
     eventOrder(types: StreamEvent["type"][]): AssertionHandle;
-    /** 用自定义谓词对默认会话累计的整段事件流断言;失败时用 label 说明原因。 */
-    eventsSatisfy(predicate: (events: readonly StreamEvent[]) => boolean, label?: string): AssertionHandle;
+    /** 用自定义谓词对默认会话累计的整段事件流断言;label 必填、进断言标题。 */
+    eventsSatisfy(label: string, predicate: (events: readonly StreamEvent[]) => boolean): AssertionHandle;
     /** 受限沙箱视图:能执行命令 / 读写文件 / 看最终 diff,不能 stop 沙箱本身(见 SandboxHandle)。 */
     readonly sandbox: SandboxHandle;
     /** 默认会话累计的 token 用量与估算成本。 */

package/dist/i18n/en.d.ts

@@ -12,6 +12,8 @@ export declare const en: {
     "bub.installFailed": string;
     "bub.setupNotRun": string;
     "checkpoint.emptyTar": string;
+    "checkpoint.archiveFailed": string;
+    "checkpoint.restoreFailed": string;
     "skill.localMissing": string;
     "skill.localDirNoSkillFile": string;
     "skill.localUnsupportedShape": string;
@@ -21,7 +23,16 @@ export declare const en: {
     "skill.repoUnknownSkill": string;
     "skill.copyFailed": string;
     "plugin.marketplaceFailed": string;
+    "plugin.marketplaceVerifyFailed": string;
+    "plugin.marketplaceNameMismatch": string;
     "plugin.installFailed": string;
+    "nativeConfig.pathNotProjectRelative": string;
+    "nativeConfig.missing": string;
+    "nativeConfig.escapesRoot": string;
+    "nativeConfig.notFile": string;
+    "nativeConfig.invalidSyntax": string;
+    "nativeConfig.reservedKeys": string;
+    "nativeConfig.uploadFailed": string;
     "cli.all": string;
     "cli.browserOpenFailed": string;
     "cli.clean.done": string;
@@ -32,6 +43,7 @@ export declare const en: {
     "cli.dry.row": string;
     "cli.error": string;
     "cli.flag.invalidNumber": string;
+    "cli.flag.invalidOutput": string;
     "runner.budgetUnenforceable": string;
     "judge.modelMissing": string;
     "loaders.yamlMissing": string;
@@ -50,7 +62,10 @@ export declare const en: {
     "cli.eval.noMatchHintExperiment": string;
     "cli.eval.noMatchKnown": string;
     "cli.exp.agentModelFlagUnsupported": string;
+    "cli.exp.viewerFlagUnsupported": string;
     "cli.experiment.noMatch": string;
+    "cli.experiment.viewerCommandHint": string;
+    "cli.experiment.noEvalsSelected": string;
     "cli.experimentGroup": string;
     "cli.fallbackCleanupTimeout": string;
     "cli.forceCleanupExit": string;
@@ -78,6 +93,7 @@ export declare const en: {
     "define.evalIdRejected": string;
     "define.evalTestRequired": string;
     "define.experimentAgentRequired": string;
+    "define.experimentFlagNotJson": string;
     "define.experimentIdRejected": string;
     "define.sandboxAgentNameRequired": string;
     "define.sandboxCreateRequired": string;
@@ -88,6 +104,41 @@ export declare const en: {
     "docker.imagePullStart": string;
     "docker.readFileFailed": string;
     "docker.unsupportedRuntime": string;
+    "feedback.human.active": string;
+    "feedback.human.budgetExhausted": string;
+    "feedback.human.compare": string;
+    "feedback.human.counts": string;
+    "feedback.human.diffHint": string;
+    "feedback.human.evalHint": string;
+    "feedback.human.failuresHeader": string;
+    "feedback.human.heartbeat": string;
+    "feedback.human.inspect": string;
+    "feedback.human.moreActive": string;
+    "feedback.human.plan": string;
+    "feedback.human.resultFailed": string;
+    "feedback.human.resultIncomplete": string;
+    "feedback.human.resultInterrupted": string;
+    "feedback.human.resultPassed": string;
+    "feedback.human.resultsHeader": string;
+    "feedback.human.resultsMore": string;
+    "feedback.human.reuse": string;
+    "feedback.human.summaryLine": string;
+    "feedback.human.summaryAllReusedLine": string;
+    "feedback.human.suppressedFailures": string;
+    "feedback.human.trace": string;
+    "feedback.phase.agentSetup": string;
+    "feedback.phase.evalRun": string;
+    "feedback.phase.evalSetup": string;
+    "feedback.phase.sandboxCreate": string;
+    "feedback.phase.sandboxQueue": string;
+    "feedback.phase.sandboxSetup": string;
+    "feedback.phase.scoring": string;
+    "feedback.phase.teardown": string;
+    "feedback.phase.telemetryCollect": string;
+    "feedback.phase.telemetryConfigure": string;
+    "feedback.phase.workspaceBaseline": string;
+    "feedback.phase.workspaceDiff": string;
+    "feedback.rendererError": string;
     "hitl.answerNeedsOptionOrText": string;
     "hitl.invalidOption": string;
     "hitl.noOptions": string;
@@ -139,6 +190,7 @@ export declare const en: {
     "otel.portInUse": string;
     "otel.windowAttribution": string;
     "runner.diffProgress": string;
+    "runner.failFast": string;
     "runner.driveAgent": string;
     "runner.evalSetup": string;
     "runner.interrupted": string;
@@ -167,6 +219,8 @@ export declare const en: {
     "sandbox.dependencyMissing.e2b": string;
     "sandbox.dependencyMissing.vercel": string;
     "sandbox.forceCleanup": string;
+    "sandbox.provisionReconcileFailed": string;
+    "sandbox.provisionRetry": string;
     "sandbox.stopFailed": string;
     "sandbox.stopTimeout": string;
     "scoring.evalError": string;

package/dist/i18n/zh-CN.d.ts

@@ -12,6 +12,8 @@ export declare const zhCN: {
     readonly "bub.installFailed": "bub 安装失败(重试 {{attempts}} 次):\n{{tail}}";
     readonly "bub.setupNotRun": "bub adapter 的 setup() 尚未在该沙箱运行(缺 home/workspace 信息);运行器应先调 setup 再 send。";
     readonly "checkpoint.emptyTar": "checkpoint: tar 为空(paths: {{paths}})";
+    readonly "checkpoint.archiveFailed": "checkpoint 归档失败(exit {{exitCode}}): {{detail}}";
+    readonly "checkpoint.restoreFailed": "checkpoint 恢复失败(exit {{exitCode}}): {{detail}}";
     readonly "skill.localMissing": "本地 skill 路径不存在:\"{{path}}\"(解析到 {{resolved}})。path 相对跑 niceeval 的项目根解析。";
     readonly "skill.localDirNoSkillFile": "本地 skill 目录 \"{{path}}\" 里没有 SKILL.md。目录形态的 skill 必须在根下带一个 SKILL.md。";
     readonly "skill.localUnsupportedShape": "本地 skill 路径 \"{{path}}\" 形态不支持。只接受:含 SKILL.md 的目录,或单个 .md 文件。";
@@ -21,7 +23,16 @@ export declare const zhCN: {
     readonly "skill.repoUnknownSkill": "repo skill {{source}}(ref: {{ref}})里没有名为 \"{{skill}}\" 的 skill。可选:{{available}}。";
     readonly "skill.copyFailed": "skill \"{{name}}\" 装进 {{dest}} 失败:\n{{tail}}";
     readonly "plugin.marketplaceFailed": "{{agent}} marketplace \"{{name}}\" 连接失败(source: {{source}}, ref: {{ref}}):\n{{tail}}";
+    readonly "plugin.marketplaceVerifyFailed": "{{agent}} marketplace \"{{name}}\" add 后回读注册列表失败({{command}}):\n{{tail}}";
+    readonly "plugin.marketplaceNameMismatch": string;
     readonly "plugin.installFailed": "{{agent}} plugin \"{{name}}\"(marketplace: {{marketplace}})安装失败:\n{{tail}}";
+    readonly "nativeConfig.pathNotProjectRelative": "{{agent}} {{field}} 只接受项目根内的相对路径,收到 \"{{path}}\"。绝对路径、包含 `..` 的路径和 `~` 路径都不行;项目根外的配置先复制进项目再引用。";
+    readonly "nativeConfig.missing": "{{agent}} {{field}} 指向的文件不存在:\"{{path}}\"(解析到 {{resolved}})。路径相对运行 niceeval 的项目根(含 niceeval.config.ts 的目录)解析,不相对 eval / experiment 源码文件。";
+    readonly "nativeConfig.escapesRoot": "{{agent}} {{field}} \"{{path}}\" 经符号链接解析到项目根之外({{resolved}})。配置文件必须真实位于项目根内。";
+    readonly "nativeConfig.notFile": "{{agent}} {{field}} \"{{path}}\" 不是普通文件。指向一份完整的官方配置文件。";
+    readonly "nativeConfig.invalidSyntax": "{{agent}} {{field}} \"{{path}}\" 不是合法的 {{format}}:{{detail}}";
+    readonly "nativeConfig.reservedKeys": "{{agent}} {{field}} \"{{path}}\" 含保留键:{{keys}}。这些键由 experiment 与 Adapter 拥有(model、鉴权、MCP、OTel 经独立配置层叠加),从文件里删掉再跑。";
+    readonly "nativeConfig.uploadFailed": "原生配置文件 \"{{path}}\" 上传沙箱失败({{dest}}):\n{{tail}}";
     readonly "cli.all": "(全部)";
     readonly "cli.browserOpenFailed": "无法自动打开浏览器,请手动访问:{{url}}\n";
     readonly "cli.clean.done": "已删除 .niceeval/ 历史运行 artifact。\n";
@@ -32,6 +43,7 @@ export declare const zhCN: {
     readonly "cli.dry.row": "  {{who}}{{experiment}}: {{evals}}  ×{{runs}}\n";
     readonly "cli.error": "niceeval 出错:{{error}}\n";
     readonly "cli.flag.invalidNumber": "标志 --{{flag}} 需要数字,收到 \"{{value}}\"。\n";
+    readonly "cli.flag.invalidOutput": "标志 --output 需要 auto|human|agent|ci 之一,收到 \"{{value}}\"。\n";
     readonly "runner.budgetUnenforceable": "{{budgetKey}} 的 budget:连续多个 attempt 完成后都拿不到成本数据(agent 不上报用量且模型不在价格表)——该 agent 的 budget 无法执行,取消护栏继续跑。\n";
     readonly "judge.modelMissing": string;
     readonly "loaders.yamlMissing": "loadYaml(\"{{path}}\") 需要 YAML 解析器:请先 `pnpm add yaml`(或改用 loadJson + JSON 数据集)。";
@@ -49,8 +61,11 @@ export declare const zhCN: {
     readonly "cli.eval.noMatch": "没有匹配的 eval:{{patterns}}。\n";
     readonly "cli.eval.noMatchHintExperiment": "提示:\"{{pattern}}\" 是实验{{kind}},你大概想跑:niceeval exp {{pattern}}\n";
     readonly "cli.eval.noMatchKnown": "已发现 {{count}} 个 eval:{{evals}}\n";
-    readonly "cli.exp.agentModelFlagUnsupported": "`--agent` / `--model` 不能覆盖 experiment。请在 experiments/ 里新增或复制一个配置文件。\n";
+    readonly "cli.exp.agentModelFlagUnsupported": "experiment 运行不支持 --agent / --model。请新增或复制一个 experiment 文件并修改 model。\n";
+    readonly "cli.exp.viewerFlagUnsupported": "`{{flag}}` 只适用于 niceeval {{command}},不能用于 niceeval exp。\n";
     readonly "cli.experiment.noMatch": "没有匹配的实验:{{arg}}。已发现:{{experiments}}\n";
+    readonly "cli.experiment.viewerCommandHint": "你可能想运行:niceeval {{command}}{{args}}\n";
+    readonly "cli.experiment.noEvalsSelected": "未选择任何 eval:{{selection}} 匹配到 0 个 eval。可用实验:{{experiments}}。\n";
     readonly "cli.experimentGroup": "组";
     readonly "cli.fallbackCleanupTimeout": "\ngraceful 清理超时,强制清理沙箱…\n";
     readonly "cli.forceCleanupExit": "\n强制清理沙箱并退出…\n";
@@ -78,6 +93,7 @@ export declare const zhCN: {
     readonly "define.evalIdRejected": "defineEval 不接受 id —— id 由文件路径推导。";
     readonly "define.evalTestRequired": "defineEval 需要一个 async test(t) 函数。";
     readonly "define.experimentAgentRequired": "defineExperiment 需要 agent。";
+    readonly "define.experimentFlagNotJson": "experiment.flags.{{key}} 不是可 JSON 序列化的值(函数 / undefined / 循环引用 / bigint 不允许);flags 会原样进入结果快照,必须是纯 JSON。";
     readonly "define.experimentIdRejected": "defineExperiment 不接受 id —— id 由文件路径推导。";
     readonly "define.sandboxAgentNameRequired": "defineSandboxAgent 需要 name。";
     readonly "define.sandboxCreateRequired": "defineSandbox 需要一个 create() 函数。";
@@ -88,6 +104,41 @@ export declare const zhCN: {
     readonly "docker.imagePullStart": "Pulling Docker image: {{image}}...";
     readonly "docker.readFileFailed": "Failed to read file {{path}}: {{stderr}}";
     readonly "docker.unsupportedRuntime": "Unsupported runtime: {{runtime}}";
+    readonly "feedback.human.active": "ACTIVE";
+    readonly "feedback.human.budgetExhausted": "{{experimentId}} 预算已耗尽(已花 {{spent}},未跑 {{unstarted}})";
+    readonly "feedback.human.compare": "Compare: niceeval view {{group}}";
+    readonly "feedback.human.counts": "共 {{total}} · 复用 {{reused}} · 运行中 {{running}} · 排队 {{queued}} · 已完成 {{completed}}";
+    readonly "feedback.human.diffHint": "Diff:    niceeval show {{locator}} --diff";
+    readonly "feedback.human.evalHint": "Eval:    niceeval show {{locator}} --eval";
+    readonly "feedback.human.failuresHeader": "FAILURES";
+    readonly "feedback.human.heartbeat": "已运行 {{elapsed}} · {{counts}}";
+    readonly "feedback.human.inspect": "Inspect: niceeval show {{locator}}";
+    readonly "feedback.human.moreActive": "… 还有 {{count}} 项运行中";
+    readonly "feedback.human.plan": "计划:{{total}} 个 attempt · {{evals}} 个 eval × {{configs}} 个配置 · 并发 {{concurrency}}";
+    readonly "feedback.human.resultFailed": "FAILED";
+    readonly "feedback.human.resultIncomplete": "INCOMPLETE";
+    readonly "feedback.human.resultInterrupted": "INTERRUPTED";
+    readonly "feedback.human.resultPassed": "PASSED";
+    readonly "feedback.human.resultsHeader": "Results:";
+    readonly "feedback.human.resultsMore": "… 还有 {{count}} 个";
+    readonly "feedback.human.reuse": "复用:{{total}} 中 {{reused}} 条来自缓存 · {{toRun}} 待跑";
+    readonly "feedback.human.summaryLine": "{{passed}} 通过 · {{failed}} 失败 · {{errored}} 出错  (复用 {{reused}})";
+    readonly "feedback.human.summaryAllReusedLine": "{{passed}} 通过 · {{failed}} 失败 · {{errored}} 出错  (全部 {{reused}} 条复用)";
+    readonly "feedback.human.suppressedFailures": "… 还有 {{count}} 条失败被折叠";
+    readonly "feedback.human.trace": "Trace:   niceeval show {{locator}} --execution";
+    readonly "feedback.phase.agentSetup": "agent 预置";
+    readonly "feedback.phase.evalRun": "运行 eval";
+    readonly "feedback.phase.evalSetup": "eval 预置";
+    readonly "feedback.phase.sandboxCreate": "创建沙箱";
+    readonly "feedback.phase.sandboxQueue": "排队等沙箱";
+    readonly "feedback.phase.sandboxSetup": "沙箱预置";
+    readonly "feedback.phase.scoring": "评分";
+    readonly "feedback.phase.teardown": "清理中";
+    readonly "feedback.phase.telemetryCollect": "收集 trace";
+    readonly "feedback.phase.telemetryConfigure": "配置 telemetry";
+    readonly "feedback.phase.workspaceBaseline": "准备工作区";
+    readonly "feedback.phase.workspaceDiff": "采集 diff";
+    readonly "feedback.rendererError": "  · [feedback] renderer 处理 {{context}} 失败(已忽略):{{message}}\n";
     readonly "hitl.answerNeedsOptionOrText": "t.respond 的对象形式需要 optionId 或 text 二选一(两者都没给)。";
     readonly "hitl.invalidOption": "回答 \"{{optionId}}\" 不是请求 {{requestId}} 的可选项({{options}})。";
     readonly "hitl.noOptions": "该请求没有可选项";
@@ -139,6 +190,7 @@ export declare const zhCN: {
     readonly "otel.portInUse": "OTLP 接收端口 {{port}} 已被占用(另一个进程占着这个端口)。在 defineConfig({ telemetry: { port } }) 里换一个空闲端口,或者停掉占用 {{port}} 的进程后重试。";
     readonly "otel.windowAttribution": "otel:span 未带本轮 traceparent,按时间窗口归属(该 agent 的轮次已串行;应用支持 W3C 传播后自动并发)";
     readonly "runner.diffProgress": "采 diff:{{changed}} 改 / {{deleted}} 删";
+    readonly "runner.failFast": "{{evalId}} 的错误 {{code}} 连续复现,判定为确定性错误;停止派发该配置剩余的 attempt(fail-fast)。";
     readonly "runner.driveAgent": "驱动 agent…";
     readonly "runner.evalSetup": "eval setup(装依赖)…";
     readonly "runner.interrupted": "  · 已中断:沙箱容器已清理,输出本次已完成的部分结果。\n";
@@ -167,6 +219,8 @@ export declare const zhCN: {
     readonly "sandbox.dependencyMissing.e2b": "E2B sandbox requires 'e2b'. Install it with: pnpm add e2b";
     readonly "sandbox.dependencyMissing.vercel": "Vercel sandbox requires '@vercel/sandbox'. Install it with: pnpm add @vercel/sandbox";
     readonly "sandbox.forceCleanup": "  · [sandbox] 强制清理 {{count}} 个沙箱…\n";
+    readonly "sandbox.provisionReconcileFailed": "  · [sandbox] 创建重试前对账失败,放弃重试(可能已创建的实例无法核实/销毁):{{error}}\n";
+    readonly "sandbox.provisionRetry": "  · [sandbox] 创建被限流,{{delayMs}}ms 后重试(第 {{attempt}}/{{maxAttempts}} 次)…\n";
     readonly "sandbox.stopFailed": "  · [sandbox] 停沙箱 {{id}} 失败(已忽略,靠 provider 过期兜底):{{message}}\n";
     readonly "sandbox.stopTimeout": "stop 超时({{timeoutMs}}ms)";
     readonly "scoring.evalError": "评估出错: {{error}}";

package/dist/o11y/types.d.ts

@@ -38,11 +38,23 @@ export interface InputRequest {
         label?: string;
     }[];
 }
+/**
+ * 落盘截断的结构化标记(见 docs/feature/results/architecture.md「大值截断」):
+ * `path` 是被截断的位置(事件里是字段名,如 "output";span 里是 attribute key,如 "output.value"),
+ * `originalBytes` 是截断前的 UTF-8 字节数。view 显示「输出过大,已截断」靠它,不正则匹配 marker。
+ */
+export interface Truncation {
+    path: string;
+    originalBytes: number;
+}
 /**
  * 标准事件流的词汇(对标 docs/feature/adapters/architecture/events.md)。adapter 唯一的硬活就是把
  * 各 agent 五花八门的原始 transcript 映射成 StreamEvent[];映射完,整套断言免费。
+ * `truncated` 只由 results writer 在落盘时刻写入(运行时全量,落盘截断);adapter 不产出它。
  */
-export type StreamEvent = 
+export type StreamEvent = {
+    truncated?: Truncation[];
+} & (
 /** 一条文本消息(assistant 回复或 user 输入);`loc` 是可选的源码位置,用于把消息叠回 eval 源码。 */
 {
     type: "message";
@@ -107,7 +119,7 @@ export type StreamEvent =
  | {
     type: "error";
     message: string;
-};
+});
 /** core 从事件流折叠出的结构化事实(deriveRunFacts)。 */
 export interface ToolCall {
     callId: string;
@@ -162,6 +174,8 @@ export interface TraceSpan {
     kind?: SpanKind;
     /** OTLP span 属性(gen_ai.* / tool 名 / token 等),按 key 摊平。raw 属性始终保留供下钻。 */
     attributes?: Record<string, JsonValue>;
+    /** 落盘截断标记(只由 results writer 在序列化时写入,运行时全量;见 Truncation)。 */
+    truncated?: Truncation[];
 }
 /** 给人 / 给 EVAL.ts 看的 o11y 摘要(注入沙箱 __niceeval__/results.json)。 */
 export interface O11ySummary {

package/dist/report/aggregate.d.ts

@@ -1,6 +1,6 @@
 import type { AttemptHandle, Selection, SelectionWarning, Snapshot } from "../results/types.ts";
 import { type AttemptLocator } from "../results/locator.ts";
-import type { Aggregator, DimensionInput, Metric, MetricCell, MetricColumn, FlagRef } from "./types.ts";
+import type { Aggregator, AxisInput, ConfigRef, DimensionInput, Metric, MetricCell, MetricColumn, FlagRef } from "./types.ts";
 import { evalPrefixPredicate } from "../shared/aggregate.ts";
 /** flag 未声明时的组名:不猜,如实归一组。 */
 export declare const FLAG_UNSET = "(unset)";
@@ -39,8 +39,10 @@ export declare function dimensionName(dimension: DimensionInput): string;
 export declare function evalGroupOf(id: string): string;
 /** flag 声明值 → 组标签:label 函数优先,其余 String();未声明 → FLAG_UNSET。 */
 export declare function flagGroupKey(ref: FlagRef, item: Item): string;
-/** flag 作轴:要求数值;未声明或非数值 → null(点不画,注脚报数)。 */
-export declare function flagAxisValue(ref: FlagRef, item: Item): number | null;
+/** config 投影值 → 组标签,规则与 flagGroupKey 一致;未投影 → FLAG_UNSET。 */
+export declare function configGroupKey(ref: ConfigRef, item: Item): string;
+/** flag / config 作轴:要求数值;未声明、未投影或非数值 → null(点不画,注脚报数)。 */
+export declare function axisValue(ref: AxisInput, item: Item): number | null;
 export declare function dimensionKey(dimension: DimensionInput, item: Item): string;
 /** 按维度分组,保持首次出现顺序(无 sort 时表格行序即此序)。 */
 export declare function groupItems(items: Item[], dimension: DimensionInput): Map<string, Item[]>;

package/dist/report/aggregate.js

@@ -79,29 +79,56 @@ export function evalGroupOf(id) {
 function isFlagRef(dimension) {
     return typeof dimension === "object" && "kind" in dimension && dimension.kind === "flag";
 }
+function isConfigRef(dimension) {
+    return typeof dimension === "object" && "kind" in dimension && dimension.kind === "config";
+}
 /** experiment 声明的 flags(经 runner 原样透传进持久化字段 ExperimentRunInfo.flags)。 */
 function flagsOf(attempt) {
     return attempt.result.experiment?.flags;
 }
+/**
+ * config() 的取值:读快照的 `ExperimentRunInfo` 投影(快照优先;第三方落盘只把投影拼在
+ * 条目上时回退 result.experiment),外加桥接到快照顶层权威字段的 `model` / `agent` 两个键
+ * (与 "model" / "agent" 内置维度同一读法,不另造第二套口径)。未投影 → undefined。
+ */
+function configValueOf(ref, item) {
+    if (ref.name === "model")
+        return item.attempt.result.model ?? item.snapshot.model;
+    if (ref.name === "agent")
+        return item.attempt.result.agent || item.snapshot.agent;
+    const info = item.snapshot.experiment ?? item.attempt.result.experiment;
+    // ExperimentRunInfo 是穷尽可序列化投影;按字段名取值,新增投影字段无需改这里
+    return info?.[ref.name];
+}
 /** flag 声明值 → 组标签:label 函数优先,其余 String();未声明 → FLAG_UNSET。 */
 export function flagGroupKey(ref, item) {
-    const value = flagsOf(item.attempt)?.[ref.name];
+    return refGroupKey(ref, flagsOf(item.attempt)?.[ref.name]);
+}
+/** config 投影值 → 组标签,规则与 flagGroupKey 一致;未投影 → FLAG_UNSET。 */
+export function configGroupKey(ref, item) {
+    return refGroupKey(ref, configValueOf(ref, item));
+}
+function refGroupKey(ref, value) {
     if (value === undefined)
         return FLAG_UNSET;
-    // 持久化字段是 Record<string, unknown>;声明侧的合法值就是这三种标量
+    // 声明侧的合法标量就是这三种;非标量投影(sandbox / selectedEvalIds…)如实 JSON 化,不猜
     if (typeof ref.label === "function")
         return ref.label(value);
+    if (typeof value === "object" && value !== null)
+        return JSON.stringify(value);
     return String(value);
 }
-/** flag 作轴:要求数值;未声明或非数值 → null(点不画,注脚报数)。 */
-export function flagAxisValue(ref, item) {
-    const value = flagsOf(item.attempt)?.[ref.name];
+/** flag / config 作轴:要求数值;未声明、未投影或非数值 → null(点不画,注脚报数)。 */
+export function axisValue(ref, item) {
+    const value = ref.kind === "flag" ? flagsOf(item.attempt)?.[ref.name] : configValueOf(ref, item);
     return typeof value === "number" ? value : null;
 }
 export function dimensionKey(dimension, item) {
     if (typeof dimension !== "string") {
         if (isFlagRef(dimension))
             return flagGroupKey(dimension, item);
+        if (isConfigRef(dimension))
+            return configGroupKey(dimension, item);
         return dimension.of(item.attempt);
     }
     const result = item.attempt.result;

package/dist/report/built-ins/experiment-comparison.d.ts

@@ -1 +1,39 @@
-export declare const ExperimentComparison: import("../report.ts").ReportDefinition;
+import { type ReportDefinition } from "../report.ts";
+import { type ReportComponent } from "../tree.ts";
+import { type ReportLocale } from "../locale.ts";
+import type { ExperimentListItem, GroupSummaryData, ScatterData } from "../types.ts";
+import { type SnapshotsInput } from "../aggregate.ts";
+/**
+ * 一个可比组的数据。三个子块都只消费本组快照，不能含其它父目录的引用。
+ */
+export interface ExperimentComparisonGroupData {
+    /** experiment id 的完整父路径；根目录 experiment 使用自己的完整 id。 */
+    key: string;
+    summary: GroupSummaryData;
+    /** 成本 × 端到端成功率散点(`MetricScatter.data` 的口径:points=experiment、series=agent)。 */
+    scatter: ScatterData;
+    /** 固定列 experiment 比较表(`ExperimentList.data` 的口径,已按端到端成功率排序)。 */
+    experiments: ExperimentListItem[];
+}
+/** `ExperimentComparison.data(selection)` 的穷尽产物：按 key 排序的独立可比组。 */
+export interface ExperimentComparisonData {
+    groups: ExperimentComparisonGroupData[];
+}
+/** 完整父路径是组键；没有父路径的 experiment 不能互相比，自己形成单例组。 */
+export declare function experimentComparisonGroupKey(experimentId: string): string;
+/** 组合件的数据计算：先分区，再让三个官方子块在各组内并行计算。 */
+declare function experimentComparisonData(input: SnapshotsInput): Promise<ExperimentComparisonData>;
+export interface ExperimentComparisonProps {
+    data: ExperimentComparisonData;
+    /** chrome 文案 locale;省略时随宿主上下文(宿主外默认 "en")。 */
+    locale?: ReportLocale;
+    className?: string;
+}
+/**
+ * 内置默认报告兼官方组合件:作为组件时收 `data`(`.data()` 的产物),两个渲染面直接摆
+ * 数据形态的子组件;作为默认报告时经 build 面走与用户 `--report` 完全相同的管线。
+ */
+export declare const ExperimentComparison: ReportComponent<ExperimentComparisonProps> & ReportDefinition & {
+    data: typeof experimentComparisonData;
+};
+export {};