niceeval 0.6.1 → 0.7.0

package/INDEX.md

@@ -8,45 +8,45 @@
 
 | 任务 | 读取 |
 | --- | --- |
-| 初始化并跑通第一条 Eval | `docs-site/zh/quickstart.mdx` |
-| 理解 Adapter、Experiment、Eval 的分工 | `docs-site/zh/concepts/overview.mdx` |
-| 接入自己的 Agent | `docs-site/zh/guides/connect-your-agent.mdx` |
-| 选择官方 Adapter | `docs-site/zh/guides/official-adapters.mdx` |
-| 接入 coding agent CLI | `docs-site/zh/guides/sandbox-agent.mdx` |
-| 选择 Sandbox Provider | `docs-site/zh/guides/sandbox-providers.mdx` |
+| 初始化并跑通第一条 Eval | `docs-site/zh/tutorials/quickstart.mdx` |
+| 理解 Adapter、Experiment、Eval 的分工 | `docs-site/zh/explanation/overview.mdx` |
+| 接入自己的 Agent | `docs-site/zh/how-to/connect-your-agent.mdx` |
+| 选择官方 Adapter | `docs-site/zh/reference/official-adapters.mdx` |
+| 接入 coding agent CLI | `docs-site/zh/how-to/sandbox-agent.mdx` |
+| 选择 Sandbox Provider | `docs-site/zh/how-to/sandbox-providers.mdx` |
 
 ## 编写配置与 Eval
 
 | 任务 | 读取 |
 | --- | --- |
-| 编写 Adapter | `docs-site/zh/concepts/adapter.mdx`、`docs-site/zh/reference/define-agent.mdx` |
-| 映射消息、工具调用和事件流 | `docs-site/zh/guides/write-send.mdx`、`docs-site/zh/reference/events.mdx` |
-| 编写 Experiment | `docs-site/zh/guides/write-experiment.mdx` |
-| 编写 Eval | `docs-site/zh/concepts/evals.mdx`、`docs-site/zh/reference/define-eval.mdx` |
-| 编写断言和评分 | `docs-site/zh/guides/authoring.mdx`、`docs-site/zh/guides/scoring-guide.mdx`、`docs-site/zh/reference/expect.mdx` |
-| 配置 Judge | `docs-site/zh/concepts/judge.mdx`、`docs-site/zh/reference/define-config.mdx` |
-| 配置 OTel | `docs-site/zh/guides/connect-otel.mdx` |
+| 编写 Adapter | `docs-site/zh/explanation/adapter.mdx`、`docs-site/zh/reference/define-agent.mdx` |
+| 映射消息、工具调用和事件流 | `docs-site/zh/how-to/write-send.mdx`、`docs-site/zh/reference/events.mdx` |
+| 编写 Experiment | `docs-site/zh/how-to/write-experiment.mdx` |
+| 编写 Eval | `docs-site/zh/explanation/evals.mdx`、`docs-site/zh/reference/define-eval.mdx` |
+| 编写断言和评分 | `docs-site/zh/how-to/authoring.mdx`、`docs-site/zh/how-to/scoring-guide.mdx`、`docs-site/zh/reference/expect.mdx` |
+| 配置 Judge | `docs-site/zh/explanation/judge.mdx`、`docs-site/zh/reference/define-config.mdx` |
+| 配置 OTel | `docs-site/zh/how-to/connect-otel.mdx` |
 | 查 CLI 命令与 flag | `docs-site/zh/reference/cli.mdx` |
 
 ## 运行、调试与优化
 
 | 任务 | 读取 |
 | --- | --- |
-| 让 AI 自主运行、观察、修改和重跑 | `docs-site/zh/guides/agent-feedback-loop.mdx` |
-| 用 `show`、`view` 和 artifact 定位失败 | `docs-site/zh/guides/viewing-results.mdx` |
-| 组织实验和对比 | `docs-site/zh/guides/experiments.mdx` |
-| 编写自定义报告 | `docs-site/zh/guides/custom-reports.mdx`、`docs-site/zh/guides/report-components.mdx` |
-| 读取或转换结构化结果 | `docs-site/zh/guides/results-data.mdx` |
+| 让 AI 自主运行、观察、修改和重跑 | `docs-site/zh/how-to/agent-feedback-loop.mdx` |
+| 用 `show`、`view` 和 artifact 定位失败 | `docs-site/zh/how-to/viewing-results.mdx` |
+| 组织实验和对比 | `docs-site/zh/how-to/experiments.mdx` |
+| 编写自定义报告 | `docs-site/zh/how-to/custom-reports.mdx`、`docs-site/zh/reference/report-components.mdx` |
+| 读取或转换结构化结果 | `docs-site/zh/reference/results-data.mdx` |
 
 ## 专项场景
 
 | 任务 | 读取 |
 | --- | --- |
-| 评估 Claude Code / Codex Skill | `docs-site/zh/example/claude-code-codex-skill.mdx` |
-| 评估 Plugin、Hook 或 MCP server | `docs-site/zh/example/claude-code-codex-plugin.mdx` |
-| 编写多轮会话 | `docs-site/zh/concepts/adapter.mdx`、`docs-site/zh/guides/write-send.mdx` |
-| 编写人工审批流（HITL） | `docs-site/zh/concepts/hitl.mdx` |
-| 做 feature flag A/B 对比 | `docs-site/zh/concepts/tier.mdx`、`docs-site/zh/concepts/experiment.mdx` |
+| 评估 Claude Code / Codex Skill | `docs-site/zh/examples/coding-agent-extensions.mdx` |
+| 评估 Plugin、Hook 或 MCP server | `docs-site/zh/examples/coding-agent-extensions.mdx` |
+| 编写多轮会话 | `docs-site/zh/explanation/adapter.mdx`、`docs-site/zh/how-to/write-send.mdx` |
+| 编写人工审批流（HITL） | `docs-site/zh/explanation/hitl.mdx` |
+| 做 feature flag A/B 对比 | `docs-site/zh/explanation/tier.mdx`、`docs-site/zh/explanation/experiment.mdx` |
 
 ## 版本规则
 

package/README.zh.md

@@ -80,7 +80,7 @@ NiceEval 支持两种接入方式，取决于被测 agent 是否需要隔离的
 | Sandbox | 需要隔离工作区的 coding agent 才用得到；直连 Web Agent 不需要。 |
 | Tier | 接入 Adapter 的三档投入：Tier 1 只接 send，Tier 2 加 OTel 换调用瀑布图，Tier 3 侵入改造做 feature A/B。 |
 
-完整术语表见[架构概览](https://niceeval.com/docs/zh/concepts/overview)。
+完整术语表见[架构概览](https://niceeval.com/docs/zh/explanation/overview)。
 
 ## 示例
 
@@ -134,9 +134,9 @@ READ https://niceeval.com/INIT.md and install niceeval for this repo.
 
 从你的场景开始：
 
-- [如果你需要 eval 你的 Claude Code / Codex 插件](https://niceeval.com/docs/zh/example/claude-code-codex-plugin)
-- [如果你需要 eval 你的 Claude Code / Codex Skill](https://niceeval.com/docs/zh/example/claude-code-codex-skill)
-- [如果你需要 eval 你的 AI Agent 应用](https://niceeval.com/docs/zh/example/ai-agent-application)
+- [浏览可运行示例](https://niceeval.com/docs/zh/examples)
+- [评估 Coding Agent 扩展](https://niceeval.com/docs/zh/examples/coding-agent-extensions)
+- [自写 Adapter 评估 AI Agent 应用](https://niceeval.com/docs/zh/examples/ai-agent-application)
 
 
 ## Roadmap
@@ -161,7 +161,7 @@ READ https://niceeval.com/INIT.md and install niceeval for this repo.
 
 ## 文档
 
-- [快速开始](https://www.niceeval.com/docs/zh/quickstart)
+- [快速开始](https://www.niceeval.com/docs/zh/tutorials/quickstart)
 
 # 感谢
 该项目受下面项目所启发或者是由AI从下面项目中学习代码所写
@@ -170,4 +170,4 @@ READ https://niceeval.com/INIT.md and install niceeval for this repo.
 - [ponytail](https://github.com/DietrichGebert/ponytail)
 
 感谢下列社区
-- WIP
+- WIP

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 / 模型参考)。 */
@@ -91,7 +131,7 @@ export interface InputFile {
 }
 /**
  * HITL 回答轮里,人的裁决以结构化形式随 `input.responses` 到达——adapter 不需要解析
- * `text` 去猜哪句回答对应哪个请求、算不算批准。见 docs-site/zh/concepts/adapter.mdx
+ * `text` 去猜哪句回答对应哪个请求、算不算批准。见 docs-site/zh/explanation/adapter.mdx
  * 「不同回答的入参」一节的四种典型形态。
  */
 export interface InputResponse {
@@ -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` 块 /
@@ -178,7 +223,7 @@ export interface AgentTracing {
  * 新会话线(eval 第一轮 / t.newSession() 之后)拿到一个全新的。**
  * 会话续接(`id`/`capture`、`history`)和 HITL 停轮现场(`hold`/`take`)的存取器都在它上面,
  * "第一轮"是新会话线的自然形态,没有要判断的分支;`state` 是这些存取器之外的逃生舱,
- * 框架从不往里写数据。见 docs-site/zh/concepts/adapter.mdx「AgentContext」一节。
+ * 框架从不往里写数据。见 docs-site/zh/explanation/adapter.mdx「AgentContext」一节。
  */
 export interface AgentSession {
     /** 会话续接:服务端记历史。本线记过的会话 id;新会话线是 undefined。 */
@@ -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 数据集)。";
@@ -42,15 +54,18 @@ export declare const zhCN: {
     readonly "cli.show.runDirMissing": "Results directory not found: {{dir}}\n";
     readonly "cli.show.noEvalMatch": "No results matched: {{patterns}}. Evals with results: {{evals}}\n";
     readonly "cli.show.noExperimentMatch": "No experiment matched --experiment {{arg}}. Experiments with results: {{experiments}}\n";
-    readonly "cli.show.historyReportConflict": "`--history` and `--report` are mutually exclusive: --history is the built-in trend view. For a custom trend, compose exp.snapshots inside your report file instead.\n";
-    readonly "cli.show.evidenceNeedsEval": "--eval / --execution / --diff show one attempt's evidence, but the selection matched {{matched}} evals. Pick an attempt locator from the index below:\n{{index}}\n";
+    readonly "cli.show.historyReportConflict": "`--history` and `--report` are mutually exclusive: both take over the main output. --history is the host's per-attempt execution timeline; for snapshot-level trends, compose exp.snapshots inside your report file instead.\n";
+    readonly "cli.show.evidenceNeedsEval": "--source / --execution / --diff show one attempt's evidence, but the selection matched {{matched}} evals. Pick an attempt locator from the index below:\n{{index}}\n";
     readonly "cli.show.locatorMalformed": "{{message}}\n";
     readonly "cli.show.locatorNotFound": "{{message}}\n";
     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}} --source";
+    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 {