niceeval 0.9.0 → 0.10.0

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

@@ -34,23 +34,23 @@ description: "NiceEval 内置的 claude-code、codex、bub 适配器分别做到
 
 ### claude-code
 
-- 连接方式：沙箱里 spawn `claude --print --dangerously-skip-permissions`，读回 `~/.claude/projects/**/*.jsonl` 最新一份 transcript。
+- 连接方式：Sandbox 里 spawn `claude --print --dangerously-skip-permissions`，读回 `~/.claude/projects/**/*.jsonl` 最新一份 transcript。
 - 会话续接：`ctx.session.id` 有值时追加 `--resume <id>`；transcript 解出的会话 id 经 `ctx.session.capture()` 写回。
 - 鉴权：`ANTHROPIC_API_KEY`，可选 `ANTHROPIC_BASE_URL`；配置项见下方 `ClaudeCodeConfig`。
 - `tracing` 通过 claude CLI 原生 OTLP trace spans（beta）配置，协议 `http/protobuf`：env 里设置 `CLAUDE_CODE_ENABLE_TELEMETRY` 与 `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA`（beta 开关，须显式开启）把 endpoint 交给 CLI；`EvalResult.trace` 能看到 interaction / llm_request / tool 层级的瀑布图。
 
 ### codex
 
-- 连接方式：沙箱里跑 `codex exec --json`（续接时是 `codex exec resume <id> --json`），stdout JSONL 当 transcript。命令带 `--dangerously-bypass-approvals-and-sandbox` 与 `--dangerously-bypass-hook-trust`：沙箱里没人能回答 codex 的交互确认，插件或 `postSetup` 装好的 hook 因此不需要交互授信就能生效。
+- 连接方式：Sandbox 里跑 `codex exec --json`（续接时是 `codex exec resume <id> --json`），stdout JSONL 当 transcript。命令带 `--dangerously-bypass-approvals-and-sandbox` 与 `--dangerously-bypass-hook-trust`：Sandbox 里没人能回答 codex 的交互确认，插件或 `postSetup` 装好的 hook 因此不需要交互授信就能生效。
 - 鉴权：`CODEX_API_KEY`（不是 `OPENAI_API_KEY`），可选 `CODEX_BASE_URL` 接 OpenAI 兼容代理；配置项见下方 `CodexConfig`。
 - `tracing` 通过 `~/.codex/config.toml` 的 `[otel.trace_exporter.otlp-http]` 段配置，协议 `http/json`。
 
 ### bub
 
-- 连接方式：沙箱里跑 `bub run` + `--session-id`，从 `~/.bub/tapes/<hash>.jsonl` 读 tape 当 transcript。
+- 连接方式：Sandbox 里跑 `bub run` + `--session-id`，从 `~/.bub/tapes/<hash>.jsonl` 读 tape 当 transcript。
 - 鉴权：`BUB_API_KEY` + `BUB_API_BASE`（OpenAI 兼容代理）；配置项见下方 `BubConfig`。
 - `tracing` 通过环境变量注入（`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` 等），协议 `http/protobuf`。
-- 安装走 `uv tool install`（非 npm 包），首次安装带 checkpoint 缓存以加速后续沙箱。
+- 安装走 `uv tool install`（非 npm 包），首次安装带 checkpoint 缓存以加速后续 Sandbox。
 
 ## 三个内置 sandbox agent 的配置项
 
@@ -84,7 +84,7 @@ maxTurns?: number;
 ```
 
 最多跑几个 tool-use 轮次(→ `--max-turns`)。
-控制 eval 成本上限;省略时用 CLI 原生默认(无限制)。
+控制评估用例成本上限;省略时用 CLI 原生默认(无限制)。
 
 #### `mcpServers`
 
@@ -92,7 +92,7 @@ maxTurns?: number;
 mcpServers?: McpServer[];
 ```
 
-额外 MCP server(每个沙箱 setup 时写进用户级 ~/.claude.json)。
+额外 MCP server(每个 Sandbox setup 时写进用户级 ~/.claude.json)。
 stdio 形态写 command(可带 args / env);Streamable HTTP 形态写 url(可带 headers,
 逐字进请求头),落成 &#123; "type": "http", "url": …, "headers": … &#125; 条目。
 
@@ -102,7 +102,7 @@ stdio 形态写 command(可带 args / env);Streamable HTTP 形态写 url(可带
 skills?: SkillSpec[];
 ```
 
-装进沙箱的 Skill(本地目录/文件,或 repo + 可钉 ref + 可选启用集)。
+装进 Sandbox 的 Skill(本地目录/文件,或 repo + 可钉 ref + 可选启用集)。
 落在 project 级 `.claude/skills/<name>/`,claude CLI 原生发现。
 
 #### `plugins`
@@ -122,7 +122,7 @@ settingsFile?: string;
 一份完整的 Claude Code `settings.json`(官方格式)在本地项目里的路径 —— 相对运行
 niceeval 的项目根(含 `niceeval.config.ts` 的目录)解析,不是 Sandbox 内路径;只接受
 项目根内的相对路径,包含 `..` 的路径、绝对路径、`~` 路径和解析后逃出项目根的符号链接
-都在 setup 阶段报错。原始字节原样上传为沙箱里原本为空的用户级 `~/.claude/settings.json`
+都在 setup 阶段报错。原始字节原样上传为 Sandbox 里原本为空的用户级 `~/.claude/settings.json`
 (不继承宿主机配置、不拼接、不重新序列化);保留键 `model` 与 `env` 出现在文件里
 setup 报错。manifest 只记项目相对路径与字节 SHA-256,不落正文。
 
@@ -132,10 +132,21 @@ setup 报错。manifest 只记项目相对路径与字节 SHA-256,不落正文
 postSetup?: SandboxHook[];
 ```
 
-安装后按数组顺序运行的用户钩子(复用 SandboxHook 的窄上下文):在写 settings、挂 MCP、
+安装后按数组顺序运行的用户 Hook(复用 SandboxHook 的窄上下文):在写 settings、挂 MCP、
 装 Skills / Plugin、写 manifest 全部完成后执行,适合跑插件自带的 setup 脚本这类
-「安装产物就位后才能跑」的过程动作。钩子返回的 cleanup 按 LIFO 与 teardown 一起收尾;
-抛错按基础设施错误计(attempt errored)。
+「安装产物就位后才能跑」的过程动作。抛错按基础设施错误计(attempt errored)。
+见 docs/feature/adapters/library/coding-agent-extensions.md「安装后运行脚本」。
+
+#### `preTeardown`
+
+```ts
+preTeardown?: SandboxHook[];
+```
+
+与 `postSetup` 成对的收尾 Hook:按 `postSetup` 的逆序语义,在 agent 自己的 teardown 步骤
+之前执行(LIFO 镜像 —— `postSetup` 跑在 agent 安装之后,`preTeardown` 就跑在 agent 收尾
+之前),当且仅当 `postSetup` 的时点走到过才触发。抛错按基础设施错误计,由 teardown 段
+按 teardown-failed 诊断收束。
 见 docs/feature/adapters/library/coding-agent-extensions.md「安装后运行脚本」。
 
 ### `CodexConfig`
@@ -162,7 +173,7 @@ OpenAI 兼容代理 base URL(如 `https://s2a.example.com/v1`)。省略时读 CO
 mcpServers?: McpServer[];
 ```
 
-额外 MCP server(每个沙箱 setup 时追加进 ~/.codex/config.toml)。
+额外 MCP server(每个 Sandbox setup 时追加进 ~/.codex/config.toml)。
 stdio 形态(command/args/env)写 [mcp_servers.&lt;name&gt;] 的 command 行;
 Streamable HTTP 形态(url/headers)写 url 行,headers 进 [mcp_servers.&lt;name&gt;.http_headers] 子表。
 
@@ -172,7 +183,7 @@ Streamable HTTP 形态(url/headers)写 url 行,headers 进 [mcp_servers.&lt;name
 skills?: SkillSpec[];
 ```
 
-装进沙箱的 Skill(本地目录/文件,或 repo + 可钉 ref + 可选启用集)。
+装进 Sandbox 的 Skill(本地目录/文件,或 repo + 可钉 ref + 可选启用集)。
 落在 `.agents/skills/<name>/`,并写一段发现指引进 AGENTS.md —— codex 没有 Claude Code 那种
 原生 Skill 工具,只把文件装进去它不会自己去读(见 memory/codex-no-native-skill-tool.md)。
 
@@ -193,7 +204,7 @@ configFile?: string;
 一份完整的 Codex `config.toml`(官方 TOML 格式)在本地项目里的路径 —— 相对运行
 niceeval 的项目根(含 `niceeval.config.ts` 的目录)解析,不是 Sandbox 内路径;只接受
 项目根内的相对路径,包含 `..` 的路径、绝对路径、`~` 路径和解析后逃出项目根的符号链接
-都在 setup 阶段报错。原始字节原样并入沙箱里原本为空的用户级 `~/.codex/config.toml`
+都在 setup 阶段报错。原始字节原样并入 Sandbox 里原本为空的用户级 `~/.codex/config.toml`
 (不继承宿主机配置、不解析后重写);保留键 `model`、`model_provider`、`model_providers`、
 `model_reasoning_effort`、`mcp_servers`、`otel` 出现在文件里 setup 报错。manifest 只记
 项目相对路径与字节 SHA-256,不落正文。
@@ -204,10 +215,21 @@ niceeval 的项目根(含 `niceeval.config.ts` 的目录)解析,不是 Sandbox
 postSetup?: SandboxHook[];
 ```
 
-安装后按数组顺序运行的用户钩子(复用 SandboxHook 的窄上下文):在写主配置、挂 MCP、
+安装后按数组顺序运行的用户 Hook(复用 SandboxHook 的窄上下文):在写主配置、挂 MCP、
 装 Skills / Plugin、写 manifest 全部完成后执行,适合跑插件自带的 setup 脚本这类
-「安装产物就位后才能跑」的过程动作。钩子返回的 cleanup 按 LIFO 与 teardown 一起收尾;
-抛错按基础设施错误计(attempt errored)。
+「安装产物就位后才能跑」的过程动作。抛错按基础设施错误计(attempt errored)。
+见 docs/feature/adapters/library/coding-agent-extensions.md「安装后运行脚本」。
+
+#### `preTeardown`
+
+```ts
+preTeardown?: SandboxHook[];
+```
+
+与 `postSetup` 成对的收尾 Hook:按 `postSetup` 的逆序语义,在 agent 自己的 teardown 步骤
+之前执行(LIFO 镜像 —— `postSetup` 跑在 agent 安装之后,`preTeardown` 就跑在 agent 收尾
+之前),当且仅当 `postSetup` 的时点走到过才触发。抛错按基础设施错误计,由 teardown 段
+按 teardown-failed 诊断收束。
 见 docs/feature/adapters/library/coding-agent-extensions.md「安装后运行脚本」。
 
 ### `BubConfig`
@@ -234,7 +256,7 @@ OpenAI 兼容代理的 base URL。省略时读 BUB_API_BASE env。
 skills?: SkillSpec[];
 ```
 
-装进沙箱的 Skill(本地目录/文件,或 repo + 可钉 ref + 可选启用集)。
+装进 Sandbox 的 Skill(本地目录/文件,或 repo + 可钉 ref + 可选启用集)。
 落在 `.agents/skills/<name>/`,并写一段发现指引进 AGENTS.md(bub 没有原生 Skill 加载机制)。
 
 #### `pythonPlugins`
@@ -243,7 +265,7 @@ skills?: SkillSpec[];
 pythonPlugins?: PythonPluginSpec[];
 ```
 
-额外装进 bub tool 环境的 Python Package,每个沙箱 setup 时进 `uv tool install … --with <pkg>`。
+额外装进 bub tool 环境的 Python Package,每个 Sandbox setup 时进 `uv tool install … --with <pkg>`。
 规范化后的 package 列表进安装 checkpoint key:plugin 集合不同的两个 agent 变体不会复用同一个
 安装 checkpoint(否则第二个变体会静默拿到第一个变体的环境)。
 
@@ -253,9 +275,20 @@ pythonPlugins?: PythonPluginSpec[];
 postSetup?: SandboxHook[];
 ```
 
-安装后按数组顺序运行的用户钩子(复用 SandboxHook 的窄上下文):在装 bub、装 Skills /
-Python package、写 manifest 全部完成后执行。钩子返回的 cleanup 按 LIFO 与 teardown 一起
-收尾;抛错按基础设施错误计(attempt errored)。
+安装后按数组顺序运行的用户 Hook(复用 SandboxHook 的窄上下文):在装 bub、装 Skills /
+Python package、写 manifest 全部完成后执行。抛错按基础设施错误计(attempt errored)。
+见 docs/feature/adapters/library/coding-agent-extensions.md「安装后运行脚本」。
+
+#### `preTeardown`
+
+```ts
+preTeardown?: SandboxHook[];
+```
+
+与 `postSetup` 成对的收尾 Hook:按 `postSetup` 的逆序语义,在 agent 自己的 teardown 步骤
+之前执行(LIFO 镜像 —— `postSetup` 跑在 agent 安装之后,`preTeardown` 就跑在 agent 收尾
+之前),当且仅当 `postSetup` 的时点走到过才触发。抛错按基础设施错误计,由 teardown 段
+按 teardown-failed 诊断收束。
 见 docs/feature/adapters/library/coding-agent-extensions.md「安装后运行脚本」。
 
 {/* GENERATED:END builtin-agent-config */}
@@ -279,9 +312,9 @@ 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/how-to/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/tutorials/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)。
+需要在评估用例项目里安装 `ai`（可选 peer 依赖，协议 reducer 来自它）。完整可跑示例：[`examples/zh/tier1/ai-sdk-v7`](https://github.com/CorrectRoadH/niceeval/tree/main/examples/zh/tier1/ai-sdk-v7)。
 
 `uiMessageStreamAgent(options)` 完整参数（`UiMessageStreamAgentOptions`）：
 
@@ -445,13 +478,13 @@ export default defineAgent({
 - 被测对象是 AI SDK 应用（`useChat` 后端）：内置 `uiMessageStreamAgent` 无侵入接入，零映射（含 HITL）。
 - 被测对象是其它 agent 系统（HTTP / gRPC 服务）：无侵入接入，手写事件映射（官方转换器能覆盖大半）——[`examples/zh/tier1`](https://github.com/CorrectRoadH/niceeval/tree/main/examples/zh/tier1) 下五个示例全是这条路；应用已埋 OTel 的话顺手接上，多一张瀑布图。
 - 需要调用瀑布图（`niceeval view` 的 trace）：`claude-code` / `codex` / `bub` 三个都自发 OTLP（claude-code 走 CLI 的 beta 遥测，span 只有结构与计时）；自己写的 adapter 声明 `tracing` 即可（见 OTel 指南）。
-- 需要人工审批 / 多步确认（HITL）：`uiMessageStreamAgent` 原生支持（AI SDK v7 tool approval）；沙箱型三个都不支持，其它被测对象自己写 adapter，拿 `driveFrameStream` + `ctx.session.hold`/`take` 拼（Tier 1 示例里 pi-sdk / claude-sdk 有现成写法）。
+- 需要人工审批 / 多步确认（HITL）：`uiMessageStreamAgent` 原生支持（AI SDK v7 tool approval）；Sandbox 型三个都不支持，其它被测对象自己写 adapter，拿 `driveFrameStream` + `ctx.session.hold`/`take` 拼（Tier 1 示例里 pi-sdk / claude-sdk 有现成写法）。
 - 想跑一个 coding agent 改代码、看 diff、判断工具调用：`claude-code` / `codex` / `bub`（收发 + 事件流 + 会话续接 + workspace + sandbox）。
 - 后端协议是自己发明的、没有官方 SDK 转换器可用：别从零手写 send——挑一种 reduce 形状（整段落地写小映射，逐 token 增量用 `deltaStream`），会话续接直接取用 `ctx.session.id`/`capture` 或 `ctx.session.history`，有 HITL 再加 `ctx.session.hold`/`take`，拼起来就是 send。
 
 ## 相关阅读
 
-- [接入你的 agent](/zh/how-to/connect-your-agent) — 自己写 adapter 时每个能力怎么做、对应什么断言。
-- [Sandbox Agent](/zh/how-to/sandbox-agent) — 怎么运行内置 sandbox agent，以及怎么写自己的。
+- [接入你的 agent](/zh/tutorials/connect-your-agent) — 自己写 adapter 时每个能力怎么做、对应什么断言。
+- [Sandbox Agent](/zh/tutorials/sandbox-agent) — 怎么运行内置 sandbox agent，以及怎么写自己的。
 - [defineAgent 参考](/zh/reference/define-agent) — `defineAgent` / `defineSandboxAgent` 完整参数。
-- [OTel 接入](/zh/how-to/connect-otel) — 把应用的 span 发给 [NiceEval](https://niceeval.com/)，换 `niceeval view` 的调用瀑布图。
+- [OTel 接入](/zh/tutorials/connect-otel) — 把应用的 span 发给 [NiceEval](https://niceeval.com/)，换 `niceeval view` 的调用瀑布图。

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

@@ -20,26 +20,6 @@ description: "NiceEval 怎么知道你的 adapter 做到了什么：没有声明
 
 没做到的能力 = 没有对应的事件/字段出现，相关断言组不可用（不是"报错"，是断言本身没有可判断的依据）；基础断言（文本、结构化、judge）永远可用。
 
-## 为什么没有声明这一层
-
-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 实际怎么写。
-
-```ts
-export default defineAgent({
-  name: "my-ai-sdk-agent",
-  async send(input, ctx) {
-    const result = await generateText({ model, tools, prompt: input.text });
-    return { ...fromAiSdk(result), data: result.text };
-    // ↑ 返回值自带完整的工具事件，不需要任何能力声明
-  },
-});
-```
 
 ## 手工映射时事件不全，会怎样
 
@@ -49,19 +29,19 @@ export default defineAgent({
 
 ### 工具/动作事件完整性
 
-含义：这一轮的每次工具调用是否都以 `action.called` + `action.result` 出现在 events 里（[事件流参考](/zh/reference/events)）。来源只有两个：官方转换器按被测协议的契约保证；手工映射由你的代码决定。OTel span 不是来源——span 只进瀑布图，不进事件流（见 [OTel 接入](/zh/how-to/connect-otel)）。
+含义：这一轮的每次工具调用是否都以 `action.called` + `action.result` 出现在 events 里（[事件流参考](/zh/reference/events)）。来源只有两个：官方转换器按被测协议的契约保证；手工映射由你的代码决定。OTel span 不是来源——span 只进瀑布图，不进事件流（见 [OTel 接入](/zh/tutorials/connect-otel)）。
 
 ### 会话续接
 
-含义：用 `ctx.session.id` / `capture` 或 `ctx.session.history` 把请求连到同一个后端会话/累计历史上。有它，跨轮记忆断言、`t.newSession()` 隔离断言才有意义。两种实现写法见[写 send](/zh/how-to/write-send)。
+含义：用 `ctx.session.id` / `capture` 或 `ctx.session.history` 把请求连到同一个后端会话/累计历史上。有它，跨轮记忆断言、`t.newSession()` 隔离断言才有意义。两种实现写法见[写 send](/zh/tutorials/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/how-to/connect-otel)）。
+runner 消费：运行时起一个本机 OTLP 接收器，把本轮 trace context 经 `ctx.telemetry.headers` 交给你；span 归一后在 `niceeval view` 画瀑布图——只画图，不喂断言。来源：CLI 型写 `tracing` 字段（env / configure 把端点交给被测进程）；长驻应用在 `niceeval.config.ts` 配 `telemetry: { port }` 固定端口（见 [OTel 接入](/zh/tutorials/connect-otel)）。
 
-### `kind: "sandbox"` —— 沙箱与改文件
+### `kind: "sandbox"` —— Sandbox 与改文件
 
-runner 消费：为每次 attempt 准备沙箱（Docker / Vercel / E2B），经 `ctx.sandbox` 交给 adapter；解锁 `t.sandbox.fileChanged()` 等 diff 断言。来源：`defineSandboxAgent` 构造，内部判别字段，不用你写。
+runner 消费：为每次 attempt 准备 Sandbox（Docker / Vercel / E2B），经 `ctx.sandbox` 交给 adapter；解锁 `t.sandbox.fileChanged()` 等 diff 断言。来源：`defineSandboxAgent` 构造，内部判别字段，不用你写。
 
 ### 压缩可见（compaction）
 
@@ -71,6 +51,6 @@ runner 消费：为每次 attempt 准备沙箱（Docker / Vercel / E2B），经
 
 - [事件流参考](/zh/reference/events) —— 事件流承诺的具体内容。
 - [Adapter 概念](/zh/explanation/adapter) —— `ctx`/`Turn` 的完整契约、能力从哪来。
-- [接入你的 agent](/zh/how-to/connect-your-agent) —— 每种接入路径怎么做。
-- [OTel 接入](/zh/how-to/connect-otel) —— span 只进瀑布图、不喂断言的完整走法。
+- [接入你的 agent](/zh/tutorials/connect-your-agent) —— 每种接入路径怎么做。
+- [OTel 接入](/zh/tutorials/connect-otel) —— span 只进瀑布图、不喂断言的完整走法。
 - [内置 Agent 能力](/zh/reference/builtin-agents) —— 内置 adapter 各自做到什么。

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

@@ -1,31 +1,31 @@
 ---
 title: "NiceEval CLI：命令、flags 和退出码参考"
 sidebarTitle: "命令行"
-description: "NiceEval CLI 参考：exp、show、view、init、list 和 clean 命令，以及结果下钻、experiment、eval 过滤、并发、预算和 CI 输出。"
+description: "NiceEval CLI 参考：exp、show、view、init、list 和 clean 命令，以及结果下钻、experiment、评估用例过滤、并发、预算和 CI 输出。"
 ---
 
-[NiceEval](https://niceeval.com/) CLI 是发现、运行和查看 eval 的入口。实际执行 eval 时采用 experiment-first 模型：**`exp` 选择可签入的运行配置**，experiment 后的位置参数才按 eval ID 前缀过滤。agent、model 和 flags 写在 `experiments/`，不靠临时 CLI 参数。
+[NiceEval](https://niceeval.com/) CLI 是发现、运行和查看评估用例的入口。实际执行评估用例时采用 experiment-first 模型：**`exp` 选择可签入的运行配置**，experiment 后的位置参数才按评估用例 ID 前缀过滤。agent、model 和 flags 写在 `experiments/`，不靠临时 CLI 参数。
 
 ## 命令
 
 <CardGroup cols={2}>
-  <Card title="npx niceeval exp &lt;group&gt; [id-prefix]" icon="flask">
-    运行命名实验组或配置。可选尾随位置参数按 eval ID 前缀过滤。
+  <Card title="npx niceeval exp [path] [id-prefix]" icon="flask">
+    按 experiment id 路径运行；每个配置的 `evals` 决定覆盖哪些评估用例。
   </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/how-to/agent-feedback-loop)）。
+    创建空的 `evals/` 目录和最小的 `niceeval.config.ts`；不生成示例评估用例文件。同时写入/刷新 niceeval 指引区块——项目已有 `AGENTS.md` 就写那份，只有 `CLAUDE.md` 就写进 `CLAUDE.md`，都没有则新建 `AGENTS.md`（见[Agent 反馈闭环](/zh/tutorials/agent-feedback-loop)）。
   </Card>
   <Card title="npx niceeval list" icon="list">
-    发现并打印所有 eval，不运行。
+    发现并打印所有评估用例，不运行。
   </Card>
   <Card title="npx niceeval clean" icon="trash">
     删除 `.niceeval/` 下历史快照 artifacts。
   </Card>
   <Card title="npx niceeval show [id-prefix | @locator]" icon="terminal">
-    在终端读取结果；用 `@<locator>` 或 eval ID 前缀下钻断言、Eval 源码、执行事件流、diff 和历史。
+    在终端读取结果；用 `@<locator>` 或评估用例 ID 前缀下钻断言、评估用例源码、执行事件流、diff 和历史。
   </Card>
   <Card title="npx niceeval view" icon="eye">
-    打开网页结果查看器，读默认报告并交互浏览 Eval 源码、执行事件流与 diff；默认范围与 `show` 相同。跨 run 时间轴（`--history`）是 `show` 专用的终端能力。
+    打开网页结果查看器，读默认报告并交互浏览评估用例源码、执行事件流与 diff；默认范围与 `show` 相同。跨 run 时间轴（`--history`）是 `show` 专用的终端能力。
   </Card>
 </CardGroup>
 
@@ -40,31 +40,34 @@ NICEEVAL_LANG=zh-CN npx niceeval list
 
 检测顺序是 `NICEEVAL_LANG`、`NICEEVAL_LOCALE`、`LC_ALL`、`LC_MESSAGES`、`LANG`。以 `zh` 开头的值使用 `zh-CN`,其它语言使用 `en`;都没有时默认 `zh-CN`。这只影响终端/runtime 文案,不改变结果 JSON 里的机器字段,也不翻译 LLM judge prompt。
 
-## `npx niceeval exp [group|config] [id-prefix...]`
+## `npx niceeval exp [path|config] [id-prefix...]`
 
 ```bash
 # 运行 experiments/ 下全部实验
 npx niceeval exp
 
-# 运行一个实验组
-npx niceeval exp compare-models
+# 按多层目录运行一批 experiment
+npx niceeval exp models
+
+# 只运行一个配置
+npx niceeval exp models/openai/gpt-5.4
 
-# 只运行该组里的一个配置(id = 组/文件名,不带扩展名)
-npx niceeval exp compare-models/gpt-5.4
+# 运行一个多层目录下全部配置
+npx niceeval exp models/openai
 
-# 在该组里只运行 ID 以 weather 开头的 eval
-npx niceeval exp compare-models weather
+# 在这一批里只运行 ID 以 weather 开头的 eval
+npx niceeval exp models weather
 ```
 
 <Note>
-  eval 过滤参数只出现在 experiment 选择之后。裸 `npx niceeval weather` 不会运行；请使用 `npx niceeval exp local weather` 或 `npx niceeval exp compare weather`。
+  评估用例过滤参数只出现在 experiment 选择之后。裸 `npx niceeval weather` 不会运行；请使用 `npx niceeval exp local weather` 或 `npx niceeval exp compare weather`。
 </Note>
 
-第一个位置参数既能填实验组名，也能填单个配置的完整 id：精确匹配到 `组/文件名` 时只跑组内那一个配置，适合逐配置验证或对比排查某一格结果，不用把其它配置文件挪出目录。
+第一个位置参数只解释为 experiment id、目录路径或文件名前缀；尾随位置参数按评估用例 id 前缀继续收窄。
 
 ## 常用 flags
 
-下表由 CLI 的 flag 解析表生成，表外的 flag 一律按未知 flag 报错并以非零状态退出。**没有**用于选择 sandbox provider 的 CLI flag：sandbox provider 只能写在代码里——在 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,8 +81,8 @@ 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` 专用:销毁全部留存沙箱。 |
+| `--keep-sandbox` | boolean | `exp` 命令专用:跑完留下 failed/errored attempt 的 Sandbox 现场(= `--keep-sandbox=failed`);`--keep-sandbox=all` 连 passed 也留。事后用 `niceeval sandbox list/enter/stop` 查看与销毁。 |
+| `--all` | boolean | `sandbox stop` 专用:销毁全部留存 Sandbox。 |
 | `--window` | string | `sandbox diff` 专用:只看某个 send 窗口(如 `--window s1/t2`);省略输出全部窗口的串联视图。 |
 | `--path` | string | `sandbox diff` 专用:只看某个文件的 patch;省略输出该窗口的全部文件。 |
 | `--leave-running` | boolean | `sandbox enter` 专用:shell 退出后让现场保持运行,不送回休眠。 |
@@ -93,7 +96,7 @@ npx niceeval exp compare-models weather
 | `--timing` | boolean | `show` 命令专用:整个 Attempt 的统一时间树;裸 `--timing` 给有界诊断投影,`--timing=full` 逐节点展开全部 runner/已关联 OTel 节点。 |
 | `--diff` | boolean | `show` 命令专用:sandbox 里的文件改动摘要;`--diff=<文件路径>` 看单个文件的完整改动(路径必须 `=` 连写)。 |
 | `--history` | boolean | `show` 命令专用:执行时间轴——对匹配的每个 experiment × eval 分节,逐 attempt 列时间 / verdict / 摘要 / 耗时 / 成本 / locator;与 `--report` 互斥。 |
-| `--experiment` | string | `show` / `view` 命令专用:按路径段前缀收窄 experiment;组名会选中组内全部配置。 |
+| `--exp` | string | `show` / `view` 命令专用:按路径段前缀收窄 experiment(与 `niceeval exp` 位置参数同一套匹配);目录路径会选中其下全部配置。`view --out` 时同一收窄决定出站内容。 |
 | `--results` | string | `show` / `view` / `sandbox enter\|list\|stop` 共用:结果根目录(`.niceeval` 之外的另一个根,如 `copySnapshots` 产出的发布根)。 |
 | `--snapshot` | string | `view` 命令专用:只打开这一份快照文件(`snapshot.json`);文件不可读时命令失败(扫描模式只跳过)。 |
 | `--report` | string | `show` / `view` 命令专用:用文件默认导出的 `defineReport(...)` 替换两者共用的默认报告。 |
@@ -115,7 +118,7 @@ npx niceeval exp compare-models weather
 npx niceeval list
 ```
 
-用于检查 eval 发现、ID 和配置加载是否正常。
+用于检查评估用例发现、ID 和配置加载是否正常。
 
 ## `exp`
 
@@ -124,7 +127,7 @@ npx niceeval exp compare-models
 npx niceeval exp compare-models weather-tool
 ```
 
-运行命名 experiment，用矩阵比较 agents、models 或 flags。第二个参数开始是 eval ID 前缀过滤。
+运行命名 experiment，用矩阵比较 agents、models 或 flags。第二个参数开始是评估用例 ID 前缀过滤。
 
 `show` 与 `view` 是顶层命令，应写成 `npx niceeval show`、`npx niceeval view`。误写成 `npx niceeval exp show` / `exp view` 且没有同名 experiment 时，CLI 会在“不存在的实验”错误后提示正确命令；仓库确实存在同名 experiment 时仍按合法 id 执行。
 
@@ -143,7 +146,7 @@ npx niceeval exp compare --output agent
 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)。
+三种 profile 的完整对比见[运行器 · Reporter](/zh/explanation/runner#reporter)；人在终端里怎么读 dashboard 与结束摘要见上面的[常用 flags](#常用-flags)与本页各命令示例；AI 反馈闭环的完整用法（读输出、按 locator 下钻、局部重跑）见 [AI 反馈闭环](/zh/tutorials/agent-feedback-loop)；CI 集成（GitHub Actions、退出码、JSON/JUnit）见 [CI 集成](/zh/tutorials/ci-integration)。
 
 ## `view`
 
@@ -151,7 +154,7 @@ npx niceeval exp compare --output ci --strict --json .niceeval/ci-summary.json -
 npx niceeval view
 ```
 
-打开本地结果查看器。它和 `show` 共用同一份默认报告和同一套默认选择——对每个 experiment、每个 eval，取历次运行里最新的那份判定；只补跑部分 eval 时，其余 eval 从更早的运行补齐。默认报告按 experiment id 的父目录分组，只在同组内比较。`show` 输出终端文本，`view` 输出网页并提供可交互的证据浏览；eval ID 前缀、`--experiment`、`--results` 对两者的收窄一致。完整说明见[查看结果](/zh/how-to/viewing-results)。
+打开本地结果查看器。它和 `show` 共用同一份默认报告和同一套默认选择——对每个 experiment、每个评估用例，取历次运行里最新的判定；每个 experiment 的集合来自快照 `selectedEvalIds`。默认报告直接比较当前 Scope。评估用例 ID 前缀、`--exp`、`--results` 对两者的收窄一致。
 
 ## `show [id-prefix...]`
 
@@ -159,21 +162,21 @@ npx niceeval view
 npx niceeval show
 npx niceeval show weather/brooklyn
 npx niceeval show @1k2m9qrs
-npx niceeval show @1k2m9qrs --eval
+npx niceeval show @1k2m9qrs --source
 npx niceeval show @1k2m9qrs --execution
 npx niceeval show fixtures/button --diff
 npx niceeval show weather/brooklyn --history
 ```
 
-`show` 是终端结果入口，适合人直接阅读，也适合 coding agent 在上下文窗口里逐级下钻。位置参数选「看哪些 eval」（ID 前缀）或直接用 `@<locator>` 精确选一个 attempt；不带位置参数时显示按实验组分区的默认比较报告，指定 eval ID 前缀只收窄报告覆盖的 Eval，不改变组边界。
+`show` 是终端结果入口，适合人直接阅读，也适合 coding agent 在上下文窗口里逐级下钻。位置参数选「看哪些评估用例」（ID 前缀）或直接用 `@<locator>` 精确选一个 attempt；不带位置参数时直接比较当前 Scope，`--exp` 按 experiment id 路径收窄。
 
-`@<locator>` 不带证据 flag 时给出该 attempt 的紧凑全景（断言摘要、执行摘要、可选 OTel 时间、diff 摘要）；`--eval`、`--execution`、`--diff` 是同一 attempt 的证据切面，分别展开运行时保存的 Eval 源码、标准执行事件流、工作区文件改动，因此必须搭配 `@<locator>` 精确指名一个 attempt。`--results <目录>` 指定结果根，`--history` 查看跨 run 趋势。完整的阅读顺序、输出示例和 artifact 说明见[查看结果](/zh/how-to/viewing-results)。
+`@<locator>` 不带证据 flag 时给出该 attempt 的紧凑全景（断言摘要、执行摘要、可选 OTel 时间、diff 摘要）；`--source`、`--execution`、`--diff` 是同一 attempt 的证据切面，分别展开运行时保存的评估用例源码、标准执行事件流、工作区文件改动，因此必须搭配 `@<locator>` 精确指名一个 attempt。`--results <目录>` 指定结果根，`--history` 查看跨 run 趋势。完整的阅读顺序、输出示例和 artifact 说明见[查看结果](/zh/tutorials/viewing-results)。
 
 ## `--early-exit` 与 `--strict`
 
-`--early-exit` 默认就是 `true`：某个 eval 的一次 attempt 通过后，会自动停止该 eval 剩余的 attempts（省钱）。所以显式传 `--early-exit` 没有效果，真正有用的是反过来关掉它——`--no-early-exit`，让 `--runs` > 1 时把每次 attempt 都跑完（测真实通过率而非提前收尾）。
+`--early-exit` 默认就是 `true`：某个评估用例的一次 attempt 通过后，会自动停止该评估用例剩余的 attempts（省钱）。所以显式传 `--early-exit` 没有效果，真正有用的是反过来关掉它——`--no-early-exit`，让 `--runs` > 1 时把每次 attempt 都跑完（测真实通过率而非提前收尾）。
 
-`--strict` 不是"更严格地报错"，而是改变软阈值断言的判定：`.atLeast(n)` 这类软阈值（`soft` severity）平时失败不会把整条 eval 判为 `failed`（只是记一条不达标的断言），加了 `--strict` 之后，软阈值没达标也会让整条 eval 的 verdict 计为 `failed`。CI 中推荐加上，避免"断言分数不够但 eval 显示通过"的情况被放过。
+`--strict` 不是"更严格地报错"，而是改变软阈值断言的判定：`.atLeast(n)` 这类软阈值（`soft` severity）平时失败不会把整条评估用例判为 `failed`（只是记一条不达标的断言），加了 `--strict` 之后，软阈值没达标也会让整条评估用例的 verdict 计为 `failed`。CI 中推荐加上，避免"断言分数不够但评估用例显示通过"的情况被放过。
 
 ## 环境变量覆盖
 
@@ -194,8 +197,8 @@ npx niceeval show weather/brooklyn --history
 
 | 退出码 | 含义 |
 |---|---|
-| `0` | 全部 eval 通过（或 `list`、`init`、`clean` 等命令正常完成）。 |
-| `1` | 存在 `failed` / `errored` 的 eval；或命令用法错误（如 `exp` 没匹配到任何实验、传了不支持的 flag 组合）。 |
+| `0` | 全部评估用例通过（或 `list`、`init`、`clean` 等命令正常完成）。 |
+| `1` | 存在 `failed` / `errored` 的评估用例；或命令用法错误（如 `exp` 没匹配到任何实验、传了不支持的 flag 组合）。 |
 | `2` | 运行时崩溃（未捕获异常），CLI 顶层兜底捕获后退出。 |
 | `130` | 收到中断信号（Ctrl-C / SIGTERM）后退出。 |