niceeval 0.6.1 → 0.7.0

package/docs-site/zh/reference/builtin-agents.mdx

@@ -112,6 +112,19 @@ plugins?: ClaudeCodePluginSpec[];
 
 Claude Code 原生 Plugin(先连 Marketplace,再从中装指定 Plugin)。
 
+#### `settingsFile`
+
+```ts
+settingsFile?: string;
+```
+
+一份完整的 Claude Code `settings.json`(官方格式)在本地项目里的路径 —— 相对运行
+niceeval 的项目根(含 `niceeval.config.ts` 的目录)解析,不是 Sandbox 内路径;只接受
+项目根内的相对路径,包含 `..` 的路径、绝对路径、`~` 路径和解析后逃出项目根的符号链接
+都在 setup 阶段报错。原始字节原样上传为沙箱里原本为空的用户级 `~/.claude/settings.json`
+(不继承宿主机配置、不拼接、不重新序列化);保留键 `model` 与 `env` 出现在文件里
+setup 报错。manifest 只记项目相对路径与字节 SHA-256,不落正文。
+
 ### `CodexConfig`
 
 #### `apiKey`
@@ -157,6 +170,20 @@ plugins?: CodexPluginSpec[];
 
 Codex 原生 Plugin(先连 Marketplace,再从中装指定 Plugin)。
 
+#### `configFile`
+
+```ts
+configFile?: string;
+```
+
+一份完整的 Codex `config.toml`(官方 TOML 格式)在本地项目里的路径 —— 相对运行
+niceeval 的项目根(含 `niceeval.config.ts` 的目录)解析,不是 Sandbox 内路径;只接受
+项目根内的相对路径,包含 `..` 的路径、绝对路径、`~` 路径和解析后逃出项目根的符号链接
+都在 setup 阶段报错。原始字节原样并入沙箱里原本为空的用户级 `~/.codex/config.toml`
+(不继承宿主机配置、不解析后重写);保留键 `model`、`model_provider`、`model_providers`、
+`model_reasoning_effort`、`mcp_servers`、`otel` 出现在文件里 setup 报错。manifest 只记
+项目相对路径与字节 SHA-256,不落正文。
+
 ### `BubConfig`
 
 #### `apiKey`
@@ -215,7 +242,7 @@ export default uiMessageStreamAgent({
 - **收发 + 事件流**：SSE 帧经 `ai` 包官方的框架无关 reducer `readUIMessageStream`（`useChat` 内部同款）归约，工具调用/结果/消息文本从消息 parts 直构——**不要求应用接 OTel**。
 - **会话续接**：协议是服务端零状态、「客户端带全量历史」——工厂用 `ctx.session.history()` 存整份 `UIMessage[]`，每轮原样重放；新会话线（`t.newSession()` 之后）拿到的是空历史。
 - **HITL**：AI SDK v7 tool approval（工具带 `needsApproval: true`）原生映射——part 停在 `approval-requested` 时该 Turn 的 `status: "waiting"` + `input.requested`；`t.respond("approve" / "deny")` 翻译成 `approval-responded` 原地改写该 part、原样重发 `messages` 触发服务端续跑（和真实前端 `addToolApprovalResponse()` + `sendMessage()` 的协议行为一致，没有单独的 approve 端点）。拒绝的调用以 `rejected` 落进事件流，且默认带「不要重试」的 reason（`denyReason` 可覆盖）——不带的话模型经常原样重发同一个调用。
-- **usage / 瀑布图**：UI Message Stream 协议帧里没有 usage，所以 `t.maxTokens` 这类用量断言在这个内置件上默认没有数据（应用把 usage 放进 message metadata 属于应用自己的协议扩展）。瀑布图是另一回事：应用有 OTel 埋点（如官方 `@ai-sdk/otel`）时，按 [OTel 接入](/zh/guides/connect-otel)把 span 发给 [NiceEval](https://niceeval.com/)，`niceeval view` 就有完整瀑布图——span 只进瀑布图，不喂断言。
+- **usage / 瀑布图**：UI Message Stream 协议帧里没有 usage，所以 `t.maxTokens` 这类用量断言在这个内置件上默认没有数据（应用把 usage 放进 message metadata 属于应用自己的协议扩展）。瀑布图是另一回事：应用有 OTel 埋点（如官方 `@ai-sdk/otel`）时，按 [OTel 接入](/zh/how-to/connect-otel)把 span 发给 [NiceEval](https://niceeval.com/)，`niceeval view` 就有完整瀑布图——span 只进瀑布图，不喂断言。
 
 需要在 eval 项目里安装 `ai`（可选 peer 依赖，协议 reducer 来自它）。完整可跑示例：[`examples/zh/tier1/ai-sdk-v7`](https://github.com/CorrectRoadH/niceeval/tree/main/examples/zh/tier1/ai-sdk-v7)。
 
@@ -330,7 +357,7 @@ return driveFrameStream(frames, stream, ctx);         // 逐帧喂 stream.add()
 
 ## 通用「拼装方式」件：`driveFrameStream` / `deltaStream` + `ctx.session`
 
-一个手写 send 里真正互不相干的只有三段：transport（怎么发）、reduce（原始数据 → 事件，上一节的转换器管这个）、编排（会话续接 + HITL 暂停恢复）。第三段和任何具体协议无关，纯粹是控制流模式——会话续接（`id`/`capture`、`history`）和 HITL 停轮现场（`hold`/`take`）的存取器直接挂在 `ctx.session` 上（`AgentSession`，见 [Adapter 概念](/zh/concepts/adapter#上下文：agentcontext)），不需要单独导入什么件、也不需要声明；剩下真正跨协议复用的只有两个官方件：
+一个手写 send 里真正互不相干的只有三段：transport（怎么发）、reduce（原始数据 → 事件，上一节的转换器管这个）、编排（会话续接 + HITL 暂停恢复）。第三段和任何具体协议无关，纯粹是控制流模式——会话续接（`id`/`capture`、`history`）和 HITL 停轮现场（`hold`/`take`）的存取器直接挂在 `ctx.session` 上（`AgentSession`，见 [Adapter 概念](/zh/explanation/adapter#上下文：agentcontext)），不需要单独导入什么件、也不需要声明；剩下真正跨协议复用的只有两个官方件：
 
 | 件 | 解决什么 |
 |---|---|
@@ -387,7 +414,7 @@ export default defineAgent({
 
 ## 相关阅读
 
-- [接入你的 agent](/zh/guides/connect-your-agent) — 自己写 adapter 时每个能力怎么做、对应什么断言。
-- [Sandbox Agent](/zh/guides/sandbox-agent) — 怎么运行内置 sandbox agent，以及怎么写自己的。
+- [接入你的 agent](/zh/how-to/connect-your-agent) — 自己写 adapter 时每个能力怎么做、对应什么断言。
+- [Sandbox Agent](/zh/how-to/sandbox-agent) — 怎么运行内置 sandbox agent，以及怎么写自己的。
 - [defineAgent 参考](/zh/reference/define-agent) — `defineAgent` / `defineSandboxAgent` 完整参数。
-- [OTel 接入](/zh/guides/connect-otel) — 把应用的 span 发给 [NiceEval](https://niceeval.com/)，换 `niceeval view` 的调用瀑布图。
+- [OTel 接入](/zh/how-to/connect-otel) — 把应用的 span 发给 [NiceEval](https://niceeval.com/)，换 `niceeval view` 的调用瀑布图。

package/docs-site/zh/reference/capabilities.mdx

@@ -22,13 +22,13 @@ description: "NiceEval 怎么知道你的 adapter 做到了什么：没有声明
 
 ## 为什么没有声明这一层
 
-上一版设计里有 `capabilities: { conversation, toolObservability }` 这类布尔声明，用来补"代码证明不了的部分"。这一层已经被拿掉，原因是它承诺的事情本身就不该由声明来担保：
+NiceEval 不设 `capabilities: { conversation, toolObservability }` 这类布尔声明层来补"代码证明不了的部分"，因为这类声明承诺的事情本身就不该由声明来担保：
 
 - **构造即证明**：用了 `defineSandboxAgent`，说明被测对象在沙箱里改文件——不需要再声明一遍 `workspace: true`。
 - **字段即证明**：写了 `tracing`（怎么把 OTLP 端点交给 CLI），tracing 就成立。字段本身就是使用凭证，不需要旁边再放一个布尔值重复一遍。
 - **来源即证明**：`fromAiSdk(result)` 消费的 `result.steps` 是 AI SDK 契约保证的**全量**工具循环记录，返回值自带"事件流完整"的证明；内置 CLI 的 parser 同理。手工映射时，事件完不完整取决于你的映射代码写没写全——这不是一个可以靠声明担保的东西，声明了也不会让代码更完整。
 - **行为即证明**：HITL 没有能力位——`send` 返回 `status: "waiting"` + `input.requested` 事件，行为本身可见。
-- **接了就续得上**：会话续接不再是"声明了才有"的开关。`ctx.session` 一直都在；用了 `id`/`capture` 或 `history` 存取器就会续接上下文，不用就每轮都是全新会话——两种都是正常状态，都不会报错，区别只在你的 adapter 实际怎么写。
+- **接了就续得上**：会话续接没有"声明了才有"的开关。`ctx.session` 一直都在；用了 `id`/`capture` 或 `history` 存取器就会续接上下文，不用就每轮都是全新会话——两种都是正常状态，都不会报错，区别只在你的 adapter 实际怎么写。
 
 ```ts
 export default defineAgent({
@@ -49,15 +49,15 @@ export default defineAgent({
 
 ### 工具/动作事件完整性
 
-含义：这一轮的每次工具调用是否都以 `action.called` + `action.result` 出现在 events 里（[事件流参考](/zh/reference/events)）。来源只有两个：官方转换器按被测协议的契约保证；手工映射由你的代码决定。OTel span 不是来源——span 只进瀑布图，不进事件流（见 [OTel 接入](/zh/guides/connect-otel)）。
+含义：这一轮的每次工具调用是否都以 `action.called` + `action.result` 出现在 events 里（[事件流参考](/zh/reference/events)）。来源只有两个：官方转换器按被测协议的契约保证；手工映射由你的代码决定。OTel span 不是来源——span 只进瀑布图，不进事件流（见 [OTel 接入](/zh/how-to/connect-otel)）。
 
 ### 会话续接
 
-含义：用 `ctx.session.id` / `capture` 或 `ctx.session.history` 把请求连到同一个后端会话/累计历史上。有它，跨轮记忆断言、`t.newSession()` 隔离断言才有意义。两种实现写法见[写 send](/zh/guides/write-send)。
+含义：用 `ctx.session.id` / `capture` 或 `ctx.session.history` 把请求连到同一个后端会话/累计历史上。有它，跨轮记忆断言、`t.newSession()` 隔离断言才有意义。两种实现写法见[写 send](/zh/how-to/write-send)。
 
 ### `tracing` —— 发 OTLP trace
 
-runner 消费：运行时起一个本机 OTLP 接收器，把本轮 trace context 经 `ctx.telemetry.headers` 交给你；span 归一后在 `niceeval view` 画瀑布图——只画图，不喂断言。来源：CLI 型写 `tracing` 字段（env / configure 把端点交给被测进程）；长驻应用在 `niceeval.config.ts` 配 `telemetry: { port }` 固定端口（见 [OTel 接入](/zh/guides/connect-otel)）。
+runner 消费：运行时起一个本机 OTLP 接收器，把本轮 trace context 经 `ctx.telemetry.headers` 交给你；span 归一后在 `niceeval view` 画瀑布图——只画图，不喂断言。来源：CLI 型写 `tracing` 字段（env / configure 把端点交给被测进程）；长驻应用在 `niceeval.config.ts` 配 `telemetry: { port }` 固定端口（见 [OTel 接入](/zh/how-to/connect-otel)）。
 
 ### `kind: "sandbox"` —— 沙箱与改文件
 
@@ -70,7 +70,7 @@ runner 消费：为每次 attempt 准备沙箱（Docker / Vercel / E2B），经
 ## 相关阅读
 
 - [事件流参考](/zh/reference/events) —— 事件流承诺的具体内容。
-- [Adapter 概念](/zh/concepts/adapter) —— `ctx`/`Turn` 的完整契约、能力从哪来。
-- [接入你的 agent](/zh/guides/connect-your-agent) —— 每种接入路径怎么做。
-- [OTel 接入](/zh/guides/connect-otel) —— span 只进瀑布图、不喂断言的完整走法。
+- [Adapter 概念](/zh/explanation/adapter) —— `ctx`/`Turn` 的完整契约、能力从哪来。
+- [接入你的 agent](/zh/how-to/connect-your-agent) —— 每种接入路径怎么做。
+- [OTel 接入](/zh/how-to/connect-otel) —— span 只进瀑布图、不喂断言的完整走法。
 - [内置 Agent 能力](/zh/reference/builtin-agents) —— 内置 adapter 各自做到什么。

package/docs-site/zh/reference/cli.mdx

@@ -13,7 +13,7 @@ description: "NiceEval CLI 参考：exp、show、view、init、list 和 clean
     运行命名实验组或配置。可选尾随位置参数按 eval ID 前缀过滤。
   </Card>
   <Card title="npx niceeval init" icon="wand-magic-sparkles">
-    创建空的 `evals/` 目录和最小的 `niceeval.config.ts`；不生成示例 eval 文件。同时写入/刷新 niceeval 指引区块——项目已有 `AGENTS.md` 就写那份，只有 `CLAUDE.md` 就写进 `CLAUDE.md`，都没有则新建 `AGENTS.md`（见[Agent 反馈闭环](/zh/guides/agent-feedback-loop)）。
+    创建空的 `evals/` 目录和最小的 `niceeval.config.ts`；不生成示例 eval 文件。同时写入/刷新 niceeval 指引区块——项目已有 `AGENTS.md` 就写那份，只有 `CLAUDE.md` 就写进 `CLAUDE.md`，都没有则新建 `AGENTS.md`（见[Agent 反馈闭环](/zh/how-to/agent-feedback-loop)）。
   </Card>
   <Card title="npx niceeval list" icon="list">
     发现并打印所有 eval，不运行。
@@ -64,7 +64,7 @@ npx niceeval exp compare-models weather
 
 ## 常用 flags
 
-下表由 CLI 的 flag 解析表生成，表外的 flag 一律按未知 flag 报错并以非零状态退出。**没有**用于选择 sandbox 后端的 CLI flag：sandbox 后端只能写在代码里——在 experiment（`defineExperiment`）里设置 `sandbox`，或者在 `niceeval.config.ts`（`defineConfig`）里设置作为项目级兜底，值来自 `niceeval/sandbox` 的 `dockerSandbox()` / `vercelSandbox()` / `e2bSandbox()`。
+下表由 CLI 的 flag 解析表生成，表外的 flag 一律按未知 flag 报错并以非零状态退出。**没有**用于选择 sandbox provider 的 CLI flag：sandbox provider 只能写在代码里——在 experiment（`defineExperiment`）里设置 `sandbox`，或者在 `niceeval.config.ts`（`defineConfig`）里设置作为项目级兜底，值来自 `niceeval/sandbox` 的 `dockerSandbox()` / `vercelSandbox()` / `e2bSandbox()`。
 
 {/* GENERATED:BEGIN cli-flags */}
 
@@ -78,20 +78,29 @@ npx niceeval exp compare-models weather
 | `--max-concurrency` | number | 设置同时运行的 eval 数量。 |
 | `--timeout` | number | 单个 attempt 的超时时间,单位毫秒。 |
 | `--budget` | number | 整次运行的预算上限(美元)。 |
+| `--keep-sandbox` | boolean | `exp` 命令专用:跑完留下 failed/errored attempt 的沙箱现场(= `--keep-sandbox=failed`);`--keep-sandbox=all` 连 passed 也留。事后用 `niceeval sandbox list/enter/stop` 查看与销毁。 |
+| `--all` | boolean | `sandbox stop` 专用:销毁全部留存沙箱。 |
+| `--window` | string | `sandbox diff` 专用:只看某个 send 窗口(如 `--window s1/t2`);省略输出全部窗口的串联视图。 |
+| `--path` | string | `sandbox diff` 专用:只看某个文件的 patch;省略输出该窗口的全部文件。 |
+| `--leave-running` | boolean | `sandbox enter` 专用:shell 退出后让现场保持运行,不送回休眠。 |
 | `--tag` | string | 只运行带有该 tag 的 eval(见 `defineEval` 的 `tags`)。 |
 | `--junit` | string | 额外写一份 JUnit XML 报告到指定路径,供 CI 消费。 |
 | `--json` | string | 额外写一份 JSON 结果(`RunSummary` 原样序列化)到指定路径,供 CI 或下游脚本消费。 |
 | `--out` | string | `view` 命令专用:把结果查看器静态导出到指定目录。 |
 | `--port` | number | `view` 命令专用:指定本地服务器监听端口。 |
-| `--eval` | boolean | `show` 命令专用:该 attempt 运行时保存的 Eval 源码,gate/soft 断言标回源码行(证据切面)。 |
+| `--allow-sensitive-artifacts` | boolean | `view --out` 专用:对非发布根(快照没有 publish:&#123;redaction:"applied"&#125; 标记)导出时的显式确认——静态站会原样携带未消毒的证据文件。 |
+| `--source` | boolean | `show` 命令专用:该 attempt 运行时保存的 Eval 源码,gate/soft 断言标回源码行(证据切面)。 |
 | `--execution` | boolean | `show` 命令专用:该 attempt 的标准执行事件流(消息、thinking、Skill load、工具调用/结果);有 OTel 时同一节点补时间(证据切面)。 |
+| `--timing` | boolean | `show` 命令专用:整个 Attempt 的统一时间树;裸 `--timing` 给有界诊断投影,`--timing=full` 逐节点展开全部 runner/已关联 OTel 节点。 |
 | `--diff` | boolean | `show` 命令专用:sandbox 里的文件改动摘要;`--diff=<文件路径>` 看单个文件的完整改动(路径必须 `=` 连写)。 |
-| `--history` | boolean | `show` 命令专用:跨 run 时间轴,只列真实执行;与 `--report` 互斥。 |
-| `--experiment` | string | `show` / `view` 命令专用:Selection 只留该实验。 |
-| `--run` | string | `show` / `view` 命令专用:钉死看某一个结果目录(某次快照或 `copySnapshots` 产物)。 |
-| `--report` | string | `show` / `view` 命令专用:渲染你的报告文件(文件默认导出 `defineReport(...)`);show 用它替换 Attempt 索引,view 用它替换默认分析报告。 |
-| `--dry` | boolean | 只打印本次会匹配到的 eval × 运行配置,不实际执行。 |
-| `--quiet` | boolean | 关闭控制台 / live 的逐条结果与末尾汇总(attempt 进度行仍写 stderr);errored / failed 的结果各在 stderr 补一行摘要,passed / skipped 静默;reporter 仍会写 artifacts。 |
+| `--history` | boolean | `show` 命令专用:执行时间轴——对匹配的每个 experiment × eval 分节,逐 attempt 列时间 / verdict / 摘要 / 耗时 / 成本 / locator;与 `--report` 互斥。 |
+| `--experiment` | string | `show` / `view` 命令专用:按路径段前缀收窄 experiment;组名会选中组内全部配置。 |
+| `--results` | string | `show` / `view` / `sandbox enter\|list\|stop` 共用:结果根目录(`.niceeval` 之外的另一个根,如 `copySnapshots` 产出的发布根)。 |
+| `--snapshot` | string | `view` 命令专用:只打开这一份快照文件(`snapshot.json`);文件不可读时命令失败(扫描模式只跳过)。 |
+| `--report` | string | `show` / `view` 命令专用:用文件默认导出的 `defineReport(...)` 替换两者共用的默认报告。 |
+| `--page` | string | `show` / `view` 命令专用:选择多页报告的页(页 id 见 `show --report` 的页索引);`view` 里定初始页。 |
+| `--dry` | boolean | 只打印本次会匹配到的 eval × 运行配置,不实际执行(按下面 `--output` 选中的 profile 给出预览)。 |
+| `--output` | string | 反馈 profile:`auto`(默认)按环境自动选择,`human` / `agent` / `ci` 强制指定;只改变终端展示,不改变选择、调度、判定、artifact 或退出码。`auto` 依次判定:stderr 是 TTY → human;否则 `CI`(或其它常见 CI 平台环境变量)存在 → ci;否则 → agent。 |
 | `--force` | boolean | 忽略上次运行结果,不跳过已通过的 (experiment, eval) 组合,强制全部重跑。 |
 | `--strict` | boolean | CI 中推荐使用:让软阈值(`soft`)失败也计入整条 eval 的 verdict。 |
 | `--early-exit` / `--no-early-exit` | boolean | 某个 eval 的一次 attempt 通过后,停止该 eval 剩余的 attempts。 |
@@ -118,13 +127,32 @@ npx niceeval exp compare-models weather-tool
 
 运行命名 experiment，用矩阵比较 agents、models 或 flags。第二个参数开始是 eval ID 前缀过滤。
 
+`show` 与 `view` 是顶层命令，应写成 `npx niceeval show`、`npx niceeval view`。误写成 `npx niceeval exp show` / `exp view` 且没有同名 experiment 时，CLI 会在“不存在的实验”错误后提示正确命令；仓库确实存在同名 experiment 时仍按合法 id 执行。
+
+## `--output`：human / agent / ci
+
+`--output` 选一种终端反馈模型，只改变展示，不改变选择、调度、判定、artifact 或退出码；省略时的默认值 `auto` 按环境自动选择。三种消费者各有推荐命令：
+
+```bash
+# 人在 TTY 前：动态 dashboard + 永久失败/诊断行
+npx niceeval exp compare --output human
+
+# coding agent / 自动修复循环：低频 checkpoint + 有界 handoff block
+npx niceeval exp compare --output agent
+
+# CI job：单一有序 stdout 事件流 + 退出码 + JSON/JUnit
+npx niceeval exp compare --output ci --strict --json .niceeval/ci-summary.json --junit .niceeval/junit.xml
+```
+
+三种 profile 的完整对比见[运行器 · Reporter](/zh/explanation/runner#reporter)；人在终端里怎么读 dashboard 与结束摘要见上面的[常用 flags](#常用-flags)与本页各命令示例；AI 反馈闭环的完整用法（读输出、按 locator 下钻、局部重跑）见 [AI 反馈闭环](/zh/how-to/agent-feedback-loop)；CI 集成（GitHub Actions、退出码、JSON/JUnit）见 [CI 集成](/zh/how-to/ci-integration)。
+
 ## `view`
 
 ```bash
 npx niceeval view
 ```
 
-打开本地结果查看器。它和 `show` 共用同一份默认报告和同一套默认选择——对每个 experiment、每个 eval，取历次运行里最新的那份判定；只补跑部分 eval 时，其余 eval 从更早的运行补齐。`show` 输出终端文本，`view` 输出网页并提供可交互的证据浏览；eval ID 前缀、`--experiment`、`--run` 对两者的收窄一致。完整说明见[查看结果](/zh/guides/viewing-results)。
+打开本地结果查看器。它和 `show` 共用同一份默认报告和同一套默认选择——对每个 experiment、每个 eval，取历次运行里最新的那份判定；只补跑部分 eval 时，其余 eval 从更早的运行补齐。默认报告按 experiment id 的父目录分组，只在同组内比较。`show` 输出终端文本，`view` 输出网页并提供可交互的证据浏览；eval ID 前缀、`--experiment`、`--run` 对两者的收窄一致。完整说明见[查看结果](/zh/how-to/viewing-results)。
 
 ## `show [id-prefix...]`
 
@@ -138,9 +166,9 @@ npx niceeval show fixtures/button --diff
 npx niceeval show weather/brooklyn --history
 ```
 
-`show` 是终端结果入口，适合人直接阅读，也适合 coding agent 在上下文窗口里逐级下钻。位置参数选「看哪些 eval」（ID 前缀）或直接用 `@<locator>` 精确选一个 attempt；不带位置参数时显示同一张紧凑 attempt 表，指定 eval ID 前缀只是收窄这张表的行数，不会切换成另一种视图。
+`show` 是终端结果入口，适合人直接阅读，也适合 coding agent 在上下文窗口里逐级下钻。位置参数选「看哪些 eval」（ID 前缀）或直接用 `@<locator>` 精确选一个 attempt；不带位置参数时显示按实验组分区的默认比较报告，指定 eval ID 前缀只收窄报告覆盖的 Eval，不改变组边界。
 
-`@<locator>` 不带证据 flag 时给出该 attempt 的紧凑全景（断言摘要、执行摘要、可选 OTel 时间、diff 摘要）；`--eval`、`--execution`、`--diff` 是同一 attempt 的证据切面，分别展开运行时保存的 Eval 源码、标准执行事件流、工作区文件改动，因此必须搭配 `@<locator>` 精确指名一个 attempt。`--run` 钉住某次结果目录，`--history` 查看跨 run 趋势。完整的阅读顺序、输出示例和 artifact 说明见[查看结果](/zh/guides/viewing-results)。
+`@<locator>` 不带证据 flag 时给出该 attempt 的紧凑全景（断言摘要、执行摘要、可选 OTel 时间、diff 摘要）；`--eval`、`--execution`、`--diff` 是同一 attempt 的证据切面，分别展开运行时保存的 Eval 源码、标准执行事件流、工作区文件改动，因此必须搭配 `@<locator>` 精确指名一个 attempt。`--run` 钉住某次结果目录，`--history` 查看跨 run 趋势。完整的阅读顺序、输出示例和 artifact 说明见[查看结果](/zh/how-to/viewing-results)。
 
 ## `--early-exit` 与 `--strict`
 

package/docs-site/zh/reference/define-agent.mdx

@@ -92,6 +92,14 @@ name: string;
 
 agent 的显示名/标识,原样进入 `Agent.name`——不是注册表查找 key,只用于展示、结果归属与去重指纹。
 
+#### `coverage`
+
+```ts
+coverage?: EvidenceCoverage;
+```
+
+该 Adapter 的常态证据覆盖声明(完整采集的用 `completeCoverage` 常量);省略 = 全通道 unknown。
+
 #### `setup`
 
 ```ts
@@ -145,6 +153,14 @@ name: string;
 
 agent 的显示名/标识,原样进入 `Agent.name`——不是注册表查找 key,只用于展示、结果归属与去重指纹。
 
+#### `coverage`
+
+```ts
+coverage?: EvidenceCoverage;
+```
+
+该 Adapter 的常态证据覆盖声明(完整采集的用 `completeCoverage` 常量);省略 = 全通道 unknown。
+
 #### `setup`
 
 ```ts
@@ -268,16 +284,35 @@ spread 进 send;file-based 的在 tracing.configure 里写配置。远程 HTTP
 只需要把 headers spread 进请求头(每轮一个新 traceparent);端点是启动期配置
 (defineConfig({ telemetry: { port } }))固定的,不从这里传。
 
+#### `progress`
+
+```ts
+progress(update: ProgressUpdate): void;
+```
+
+作用域反馈:报告此刻正在做什么(turn / tool / 安装进度)。短命状态——Human profile
+更新 active 行,`agent`/`ci` 不逐条打印,也不进最终结果;不要每个 token/delta 都调用。
+runner 按当前回调所处的生命周期阶段(agent.setup / agent.run / agent.teardown)归因,
+调用方不能冒充其它阶段(见 docs/feature/experiments/library.md)。
+
+#### `diagnostic`
+
+```ts
+diagnostic(input: DiagnosticInput): void;
+```
+
+作用域反馈:报告运行结束后仍应保留的问题(协议降级、数据不完整、cleanup 问题)。
+永久事件,落进 attempt 的 diagnostics 并进各 profile 的永久输出;`dedupeKey` 去重。
+即使 level 为 "error" 也不改变 Turn.status / verdict——无法继续时抛异常。
+
 #### `log`
 
 ```ts
 log(msg: string): void;
 ```
 
-写一行进运行器自身的进度日志(落 stderr,或调用方传入的 `onProgress` 回调)。
-超时失败时,最近若干行会并入结果的 error 信息,方便定位卡在哪一步。
-与 `Sandbox.appendLog` 是两回事:那个是把一行写进容器自己的原生日志
-(`docker logs` 能看到),这里只是运行器的观测通道。
+`progress({ message: msg })` 的别名,不是第二条通道(见 docs/feature/experiments/cli.md
+「Attempt 阶段」)。超时失败时最近若干行会并入结果的 error 信息,方便定位卡在哪一步。
 
 {/* GENERATED:END agent-def */}
 
@@ -288,7 +323,7 @@ log(msg: string): void;
 - `hold<T>(state: T): void` / `take<T>(): T | undefined` —— HITL 停轮现场的存取,`take` 取到即清除(一次消费)。
 - `state: Record<string, unknown>` —— 逃生舱,起始 `{}`,框架从不写入。
 
-完整契约见[Adapter 概念](/zh/concepts/adapter#上下文：agentcontext)。
+完整契约见[Adapter 概念](/zh/explanation/adapter#上下文：agentcontext)。
 
 ## Sandbox 接口
 
@@ -458,6 +493,24 @@ stream?: boolean;
 日志里看到 agent 的【原始输出】。provider 各自实现(docker:tee 到 PID1 tail 的文件;
 不支持的 provider 忽略)—— 日志怎么浮现是 provider 的事,adapter 只声明意图。
 
+#### `onStdout`
+
+```ts
+onStdout?: (chunk: string) => void | Promise<void>;
+```
+
+命令 stdout 每到一块就调用一次。回调只用于运行中的短命反馈；完整 stdout 仍会原样
+出现在返回的 `CommandResult` 里。provider 不支持真流时，至少会在命令结束后按完整
+stdout 调用一次，不能静默丢掉。
+
+#### `onStderr`
+
+```ts
+onStderr?: (chunk: string) => void | Promise<void>;
+```
+
+`onStdout` 的 stderr 对应物；完整 stderr 仍保留在 `CommandResult`。
+
 #### `root`
 
 ```ts

package/docs-site/zh/reference/define-config.mdx

@@ -106,4 +106,4 @@ pricing?: Record<string, PriceOverride>;
 
 {/* GENERATED:END config-fields */}
 
-[NiceEval](https://niceeval.com/) 把环境准备放在普通代码里：eval 自己需要的文件写在 `test(t)`，agent 自己的准备写在 adapter 的 `setup`。sandbox 后端不再从环境变量自动探测，也没有对应的 CLI flag——用 `niceeval/sandbox` 里的 `dockerSandbox()` / `vercelSandbox()` / `e2bSandbox()` 构造后填进 `sandbox` 字段（可以直接写在 experiment 上，也可以只写在这里作为项目级兜底：`exp.sandbox ?? config.sandbox`）。
+[NiceEval](https://niceeval.com/) 把环境准备放在普通代码里：eval 自己需要的文件写在 `test(t)`，agent 自己的准备写在 adapter 的 `setup`。sandbox provider 只来自代码里的 `sandbox` 字段，不做环境变量自动探测，也没有对应的 CLI flag——用 `niceeval/sandbox` 里的 `dockerSandbox()` / `vercelSandbox()` / `e2bSandbox()` 构造后填进 `sandbox` 字段（可以直接写在 experiment 上，也可以只写在这里作为项目级兜底：`exp.sandbox ?? config.sandbox`）。

package/docs-site/zh/reference/define-eval.mdx

@@ -1,7 +1,7 @@
 ---
 title: "defineEval：声明、配置并运行 NiceEval eval"
 sidebarTitle: "defineEval"
-description: "defineEval 参考：选项、test context t、Turn 返回值、sandbox helper 和数据集数组导出。"
+description: "defineEval 参考：选项、test context t、Turn 返回值、sandbox helper，以及数组和 keyed record 数据集导出。"
 ---
 
 `defineEval` 是编写 eval 的主要入口。每个 eval 文件调用一次，传入描述和 `test(t)`，并默认导出结果。
@@ -84,15 +84,28 @@ metadata?: Record<string, unknown>;
 
 任意附加元数据,原样透传进 EvalResult,不参与调度或打分;供自定义 reporter 消费。
 
+#### `diff`
+
+```ts
+diff?: { include?: string[]; ignore?: string[] };
+```
+
+调整 agent diff 的归因排除清单(仅沙箱型;见 docs/feature/eval/README.md):两个数组都是
+gitignore 风格 glob(workdir 相对)。默认排除 .git/node_modules/构建产物/包管理器缓存;
+`ignore` 在默认清单上追加排除;`include` 优先级最高,把匹配路径显式加回。
+合成规则固定为「默认 ∪ ignore,再被 include 打洞」,清单在分类账锚点时冻结。
+
 #### `setup`
 
 ```ts
-setup?: (sandbox: Sandbox) => Promise<void | Cleanup> | void | Cleanup;
+setup?: (sandbox: Sandbox, ctx: SandboxHookContext) => Promise<void | Cleanup> | void | Cleanup;
 ```
 
 eval 级预置:拿到沙箱(已上传 workspace + git 基线 + 装好依赖前)。
 默认命令以非 root 跑(agent 的自然环境);装系统依赖时给 `runCommand` 传 `{ root: true }`
 (如 `runCommand("apt-get", ["install", …], { root: true })`),跨 provider 语义一致。
+第二个参数是绑定到 `eval.setup` 的窄上下文(`ctx.progress` / `ctx.diagnostic`,
+见 docs/feature/eval/README.md);可返回 cleanup 闭包,归因到 `eval.teardown`。
 
 #### `test`
 
@@ -115,10 +128,10 @@ eval 主体:拿到 TestContext,驱动对话 / 沙箱操作并就地断言。
 #### `send`
 
 ```ts
-send(text: string): Promise<TurnHandle>;
+send(input: SendInput): Promise<TurnHandle>;
 ```
 
-向默认会话发一条消息,返回该轮的 TurnHandle。事件同时累加进默认会话的累计事件流,供下面的作用域断言使用。
+向默认会话发一条消息(字符串或结构化消息),返回该轮的 TurnHandle。事件同时累加进默认会话的累计事件流,供下面的作用域断言使用。
 
 #### `sendFile`
 
@@ -219,13 +232,31 @@ readonly flags: Readonly<Record<string, unknown>>;
 
 本次 attempt 生效的实验 flags(experiment.flags 的只读视图;实验条件,非命令行开关)。
 
+#### `progress`
+
+```ts
+progress(update: ProgressUpdate): void;
+```
+
+作用域反馈:报告 eval 自己执行的长步骤(上传 fixture、跑构建……)。短命状态,scope 固定
+为 `eval.run`;只报告不断言(见 docs/feature/eval/library/context.md「向运行反馈长步骤」)。
+
+#### `diagnostic`
+
+```ts
+diagnostic(input: DiagnosticInput): void;
+```
+
+作用域反馈:报告运行结束后仍需保留的问题(永久事件,落 attempt diagnostics)。
+即使 level 为 "error" 也不自动改变 verdict——测试结论仍由断言决定。
+
 #### `log`
 
 ```ts
 log(msg: string): void;
 ```
 
-打一行调试日志;有 live 进度回调时走该回调,否则落到 stderr,不出现在最终结果里。
+`progress({ message: msg })` 的别名(调试日志),不出现在最终结果里。
 
 #### `skip`
 
@@ -380,10 +411,10 @@ eventOrder(types: StreamEvent["type"][]): AssertionHandle;
 #### `eventsSatisfy`
 
 ```ts
-eventsSatisfy(predicate: (events: readonly StreamEvent[]) => boolean, label?: string): AssertionHandle;
+eventsSatisfy(label: string, predicate: (events: readonly StreamEvent[]) => boolean): AssertionHandle;
 ```
 
-用自定义谓词对默认会话累计的整段事件流断言;失败时用 label 说明原因。
+用自定义谓词对默认会话累计的整段事件流断言;label 必填、进断言标题。
 
 #### `sandbox`
 
@@ -633,10 +664,10 @@ eventOrder(types: StreamEvent["type"][]): AssertionHandle;
 #### `eventsSatisfy`
 
 ```ts
-eventsSatisfy(predicate: (events: readonly StreamEvent[]) => boolean, label?: string): AssertionHandle;
+eventsSatisfy(label: string, predicate: (events: readonly StreamEvent[]) => boolean): AssertionHandle;
 ```
 
-用自定义谓词对本轮整段事件流断言;失败时用 label 说明原因。
+用自定义谓词对本轮整段事件流断言;label 必填、进断言标题(谓词不透明,解释责任在 label)。
 
 #### `maxTokens`
 
@@ -678,3 +709,5 @@ export default rows.map((row) =>
 ```
 
 数组导出会生成稳定 ID：`file/0000`、`file/0001` 等。
+
+已有稳定业务 key 时也可以默认导出 `Record<string, EvalDef>`。例如 key `15193` 在 `swelancer.eval.ts` 中生成 `swelancer/15193`。key 必须是非空单一路径片段，不能是 `.` / `..`，不能含 `/`、`\\` 或控制字符；发现顺序按 key 字典序固定。

package/docs-site/zh/reference/events.mdx

@@ -212,7 +212,7 @@ token 用量或 OTel span 反推得到)。存在时优先于按价格表(`define
 } }
 ```
 
-agent 停轮等人时，每个待回答的问题吐一条，同时该 Turn 的 `status` 返回 `"waiting"`。`t.requireInputRequest(filter)` 的 filter 逐字段匹配这个 `request`——**能填的字段尽量填**，否则 eval 侧筛选不到。接法见[接入教程的 HITL 部分](/zh/guides/connect-your-agent)。
+agent 停轮等人时，每个待回答的问题吐一条，同时该 Turn 的 `status` 返回 `"waiting"`。`t.requireInputRequest(filter)` 的 filter 逐字段匹配这个 `request`——**能填的字段尽量填**，否则 eval 侧筛选不到。接法见[接入教程的 HITL 部分](/zh/how-to/connect-your-agent)。
 
 ### `thinking` / `compaction` / `error`
 
@@ -257,6 +257,6 @@ function toStreamEvents(body: MyBotResponse): StreamEvent[] {
 
 ## 相关阅读
 
-- [接入你的 agent](/zh/guides/connect-your-agent) —— 从零跑通的教程。
+- [接入你的 agent](/zh/how-to/connect-your-agent) —— 从零跑通的教程。
 - [能力位](/zh/reference/capabilities) —— 声明"事件流是完整的"意味着什么。
-- [编写 eval](/zh/guides/authoring) —— 消费这条流的断言全集。
+- [编写 eval](/zh/how-to/authoring) —— 消费这条流的断言全集。

package/docs-site/zh/reference/expect.mdx

@@ -136,7 +136,7 @@ export function makeAssertion(spec: {
 t.check(t.reply, includes("Paris"));
 t.check(t.reply, includes(/order #\d+/i));
 t.check(turn.data, equals({ intent: "refund" }));
-t.check(t.reply, matches(/#[A-Z0-9]{8}/));
+t.check(turn.data, matches(OrderSchema)); // Standard Schema / Zod 结构校验;正则匹配用 includes
 t.check(t.reply, similarity("The answer explains the refund window").atLeast(0.8));
 t.check(turn.data, satisfies((value) => Array.isArray(value)));
 ```
@@ -172,6 +172,22 @@ readonly severity: Severity;
 readonly threshold?: number;
 ```
 
+#### `isOptional`
+
+```ts
+readonly isOptional?: boolean;
+```
+
+`.optional()` 链过的标记:评不了只记 unavailable,不把 attempt 拖成 errored。
+
+#### `expected`
+
+```ts
+readonly expected?: string;
+```
+
+期望条件的有界文本描述(如 `contains "Brooklyn"`),失败时进 AssertionResult.expected。
+
 #### `score`
 
 ```ts
@@ -195,6 +211,15 @@ atLeast(threshold: number): ValueAssertion;
 转成软阈值断言:未达 threshold 时该条记为 failed,但默认不拖累整条 eval 的 verdict;
 `--strict` 运行下,软阈值失败也会把整条 eval 的 verdict 计为 failed。返回新实例,不改原对象。
 
+#### `optional`
+
+```ts
+optional(): ValueAssertion;
+```
+
+允许这条断言证据缺席:评不了时只记录 `outcome: "unavailable"`,不影响判定。
+与 severity 正交(severity 说影不影响质量判定,optional 说证据允不允许缺席)。返回新实例,不改原对象。
+
 {/* GENERATED:END value-assertion */}
 
 ## 自定义 matcher

package/docs-site/zh/{guides → reference}/official-adapters.mdx

@@ -1,14 +1,16 @@
 ---
 title: "官方适配器一览"
 sidebarTitle: "官方适配器"
-description: "NiceEval 内置的 Sandbox 和非 Sandbox 适配器分别是什么、怎么鉴权，Sandbox 型里怎么装 MCP server、Skill 和插件。"
+description: "NiceEval 内置的 Sandbox 和非 Sandbox 适配器分别是什么、怎么鉴权，Sandbox 型里怎么装 MCP server、Skill、插件，怎么使用 Agent 官方配置文件。"
 ---
 
-[NiceEval](https://niceeval.com/) 随包带几个官方 Adapter（`niceeval/adapter` 导出的工厂函数），按被测对象要不要隔离工作区分两类：**Sandbox 型**（`claude-code` / `codex` / `bub`）在 Docker 或云端沙箱里跑 coding-agent CLI，能装 MCP server、Skill、Python 插件；**非 Sandbox 型**无侵入连一个已经在跑的 HTTP 服务，或者帮你手写 adapter 时省掉事件流映射。这篇按类型和具体 Adapter 分节，重点是每个 Adapter 的配置项——怎么选、怎么跑通第一条 eval，见[接入你的 Agent](/zh/guides/connect-your-agent)。
+[NiceEval](https://niceeval.com/) 随包带几个官方 Adapter（`niceeval/adapter` 导出的工厂函数），按被测对象要不要隔离工作区分两类：**Sandbox 型**（`claude-code` / `codex` / `bub`）在 Docker 或云端沙箱里跑 coding-agent CLI，能装 MCP server、Skill、Python 插件；**非 Sandbox 型**无侵入连一个已经在跑的 HTTP 服务，或者帮你手写 adapter 时省掉事件流映射。这篇按类型和具体 Adapter 分节，重点是每个 Adapter 的配置项——怎么选、怎么跑通第一条 eval，见[接入你的 Agent](/zh/how-to/connect-your-agent)。
 
 ## Sandbox 适配器
 
-三个内置 Sandbox agent 都用 `defineSandboxAgent` 构造，鉴权走环境变量（可用工厂参数覆盖），并且都支持在沙箱 `setup` 阶段装扩展。怎么运行内置 Sandbox agent、目录结构和自定义 Sandbox adapter，见 [Sandbox Agent](/zh/guides/sandbox-agent)；这里只讲每个 Adapter 能装什么、配置项怎么写。
+三个内置 Sandbox agent 都用 `defineSandboxAgent` 构造，鉴权走环境变量（可用工厂参数覆盖），并且都支持在沙箱 `setup` 阶段装扩展。怎么运行内置 Sandbox agent、目录结构和自定义 Sandbox adapter，见 [Sandbox Agent](/zh/how-to/sandbox-agent)；这里只讲每个 Adapter 能装什么、配置项怎么写。
+
+本页的 `settingsFile` / `configFile` 都相对 NiceEval 项目根解析。项目根是执行 `niceeval` 时的当前工作目录，也就是包含 `niceeval.config.ts` 的目录，不是 Eval 或 Experiment 文件所在目录。例如 Experiment 在 `experiments/web/no-search.ts`、配置在 `configs/codex/no-web.toml` 时，仍写 `configFile: "configs/codex/no-web.toml"`。
 
 ### claude-code
 
@@ -16,7 +18,17 @@ description: "NiceEval 内置的 Sandbox 和非 Sandbox 适配器分别是什么
 - **装 MCP server**：`mcpServers` 配置项，`setup` 阶段写进沙箱里用户级的 `~/.claude.json`（顶层 `mcpServers` 字段）。
 - **装 Skill**：`skills: SkillSpec[]`——本地 Skill（`{ kind: "local", path }`，从项目根读文件或目录）或 Repo Skill（`{ kind: "repo", source, ref, skills }`，可钉 commit/tag、可只启用多 Skill 仓库里的一部分）。装进沙箱的 project 级 `.claude/skills/<name>/`，claude CLI 原生发现（原生 `Skill` 工具调用被 adapter 归一为 `skill.loaded` 事件，不重复记成工具调用；用 `t.loadedSkill()` 断言，不是 `t.calledTool("Skill", ...)`）。
 - **装原生 Plugin**：`plugins: ClaudeCodePluginSpec[]`，每一项声明 Marketplace 连接（`name` / `source` / 可选 `ref`）和其中的 Plugin 名。这个类型只属于 claude-code，传不进 codex。
-- **tracing**：claude CLI 的 beta 原生遥测（`CLAUDE_CODE_ENHANCED_TELEMETRY_BETA`），span 只有结构和计时，细节见 [OTel 接入](/zh/guides/connect-otel)。
+- **官方配置文件**：`settingsFile` 是运行 NiceEval 的机器上的本地项目路径，不是 Sandbox 内路径；它指向一份完整的 Claude Code `settings.json`。路径相对项目根，只允许普通相对路径或 `./` 前缀；`..`、绝对路径、`~` 和解析后逃出项目根的符号链接都会报错。Adapter 从本地读取后上传文件，原样替换 Sandbox 中原本为空的用户级 `~/.claude/settings.json`；不继承宿主机配置，也不 deep merge 或重新序列化。`model` 和 `env` 归 Experiment 和 Adapter 管，出现在文件里会在 `setup` 阶段报错并点名冲突键。Secret 走环境变量，别写进配置文件。
+- **tracing**：claude CLI 的 beta 原生遥测（`CLAUDE_CODE_ENHANCED_TELEMETRY_BETA`），span 只有结构和计时，细节见 [OTel 接入](/zh/how-to/connect-otel)。
+
+例如，用 `configs/claude-code/no-web.json` 关闭内置联网检索：
+
+```json
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "permissions": { "deny": ["WebSearch", "WebFetch"] }
+}
+```
 
 ```ts
 import { defineExperiment } from "niceeval";
@@ -38,6 +50,7 @@ export default defineExperiment({
         name: "safe-shell",
       },
     ],
+    settingsFile: "configs/claude-code/no-web.json",
   }),
   model: "claude-sonnet-4-6",
   sandbox: dockerSandbox(),
@@ -55,8 +68,16 @@ export default defineExperiment({
 
 - **装 Skill**：`skills: SkillSpec[]`，与 claude-code 同一个类型。装进 `.agents/skills/<name>/`，并把发现指引写进 AGENTS.md——codex 没有 claude-code 那种原生 Skill 工具，只把文件装进去它不会主动去读；断言"用没用到"看它是否真的执行过读那个文件的 shell 命令，没有工具调用可以直接认。
 - **装原生 Plugin**：`plugins: CodexPluginSpec[]`，声明 Marketplace 连接（`name` / `source` / 可选 `ref`）和其中的 Plugin 名。这个类型只属于 codex，传不进 claude-code。
+- **官方配置文件**：`configFile` 是运行 NiceEval 的机器上的本地项目路径，不是 Sandbox 内路径；它指向一份完整的 Codex `config.toml`。路径相对项目根，只允许普通相对路径或 `./` 前缀；`..`、绝对路径、`~` 和解析后逃出项目根的符号链接都会报错。Adapter 从本地读取后上传文件，原样替换 Sandbox 中原本为空的用户级 `~/.codex/config.toml`；不继承宿主机配置，也不拼接、deep merge 或解析后重写。`model`、`model_provider`、`model_providers`、`model_reasoning_effort`、`mcp_servers`、`otel` 归 Experiment 和 Adapter 管，出现在文件里会在 `setup` 阶段报错并点名冲突键。Secret 走环境变量，别写进配置文件。
 - **tracing**：内置，通过 `config.toml` 的 `[otel.trace_exporter.otlp-http]` 段配置，协议 `http/json`。
 
+例如，用 `configs/codex/no-web.toml` 关闭内置联网检索：
+
+```toml
+#:schema https://developers.openai.com/codex/config-schema.json
+web_search = "disabled"
+```
+
 ```ts
 import { defineExperiment } from "niceeval";
 import { codexAgent } from "niceeval/adapter";
@@ -74,6 +95,7 @@ export default defineExperiment({
         name: "repo-map",
       },
     ],
+    configFile: "configs/codex/no-web.toml",
   }),
   model: "gpt-5.4",
   sandbox: dockerSandbox(),
@@ -85,6 +107,7 @@ export default defineExperiment({
 - **鉴权**：`BUB_API_KEY` + `BUB_API_BASE`（OpenAI 兼容代理），工厂参数 `apiKey` / `apiBase` 可覆盖。
 - **装 Skill**：`skills: SkillSpec[]`，与另外两个 Adapter 同一个类型。装进 `.agents/skills/<name>/`，发现指引写进 AGENTS.md。
 - **装插件**：`pythonPlugins: PythonPluginSpec[]`（`{ package }`：PyPI 包、版本约束或 git URL），`setup` 阶段进 `uv tool install … --with <package>`。这个类型只属于 bub；package 集合进安装 checkpoint key，插件不同的两个变体不会复用同一份安装缓存。
+- **预制 Bub**：NiceEval 的 E2B 配方会把 Bub、OTel 插件和 Python 插件集合算成安装指纹。Adapter 只复用指纹完全一致的环境；仅在 PATH 里放一个 `bub` 不足以证明兼容。构建入口见 [沙箱 provider · 从官方基线继续构建以提速](/zh/how-to/sandbox-providers#从官方基线继续构建以提速)。
 - bub 没有 `mcpServers`——MCP 只属于支持它的 Adapter，Config 上压根没有这个字段。
 - **安装方式**：走 `uv tool install`（PyPI 包，不是 npm 包），首次安装会建 checkpoint 缓存加速后续沙箱。
 - **tracing**：内置，通过环境变量注入，协议 `http/protobuf`。
@@ -112,11 +135,12 @@ export default defineExperiment({
 | MCP server | ✅ `mcpServers` | ✅ `mcpServers` | ❌ |
 | Skill | ✅ `skills: SkillSpec[]`（原生发现） | ✅ `skills: SkillSpec[]`（+ 发现指引） | ✅ `skills: SkillSpec[]`（+ 发现指引） |
 | 原生 Plugin | ✅ `plugins: ClaudeCodePluginSpec[]` | ✅ `plugins: CodexPluginSpec[]` | ❌ |
+| 官方配置文件 | ✅ `settingsFile`（完整 settings.json） | ✅ `configFile`（完整 config.toml） | ❌ |
 | Python Plugin | ❌ | ❌ | ✅ `pythonPlugins: PythonPluginSpec[]` |
 | tracing | ✅（beta，仅结构与计时） | ✅ | ✅ |
 | 安装方式 | npm 全局包 | npm 全局包 | `uv tool install`（PyPI） |
 
-装了什么有据可查：Adapter 在 `setup` 收尾把安装清单写进沙箱的 `__niceeval__/agent-setup.json`，运行器把它存成 Attempt Artifact `agent-setup.json`（库里读 `attempt.agentSetup()`）。清单只记来源、ref、Skill/Plugin 名和解析出的版本，不记 API key 或环境变量值。
+装了什么有据可查：Adapter 在 `setup` 收尾把安装清单写进沙箱的 `__niceeval__/agent-setup.json`，运行器把它存成 Attempt Artifact `agent-setup.json`（库里读 `attempt.agentSetup()`）。清单只记来源、ref、Skill/Plugin 名、解析出的版本，以及官方配置文件的项目相对路径和 SHA-256；不保存配置正文、API Key 或环境变量值。
 
 ## 非 Sandbox 适配器
 
@@ -147,8 +171,8 @@ export default defineExperiment({
 
 ## 相关阅读
 
-- [接入你的 Agent](/zh/guides/connect-your-agent) — 全景：experiment 怎么配、eval 怎么写。
-- [Sandbox Agent](/zh/guides/sandbox-agent) — 怎么运行内置 Sandbox agent，以及怎么写自己的。
+- [接入你的 Agent](/zh/how-to/connect-your-agent) — 全景：experiment 怎么配、eval 怎么写。
+- [Sandbox Agent](/zh/how-to/sandbox-agent) — 怎么运行内置 Sandbox agent，以及怎么写自己的。
 - [内置 Agent 能力参考](/zh/reference/builtin-agents) — 每个适配器逐能力盘点、非 Sandbox 适配器的完整代码示例。
-- [OTel 接入](/zh/guides/connect-otel) — 把 span 发给 [NiceEval](https://niceeval.com/)，换 `niceeval view` 的调用瀑布图。
+- [OTel 接入](/zh/how-to/connect-otel) — 把 span 发给 [NiceEval](https://niceeval.com/)，换 `niceeval view` 的调用瀑布图。
 - [defineAgent 参考](/zh/reference/define-agent) — `defineAgent` / `defineSandboxAgent` 完整参数。