niceeval 0.6.0 → 0.6.2

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

@@ -0,0 +1,210 @@
+---
+title: "排查失败与复盘历史运行"
+sidebarTitle: "Debug 手册"
+description: "一份按场景组织的排查手册：断言失败怎么定位、环境错误怎么进沙箱、agent 改了什么怎么看、旧的运行怎么翻出来复盘——每一步都有命令顺序和输出示例。"
+---
+
+跑完一次 `niceeval exp`，失败的 Attempt 都带一个 `@` 开头的定位符（如 `@1qrdcfq8`）。它出现在运行摘要、CI 日志和报告里，定位符本身不会过期——只要 `.niceeval/` 里对应的结果快照还在，今天的定位符下周还能用同一条命令打开同一次 Attempt。所有排查都从它开始。
+
+## 第一步永远是 `niceeval show @<定位符>`
+
+不带任何参数打开 Attempt，第一页就是为排查设计的：判定、失败的断言、耗时分布、改动概览，以及下一步可用的命令。
+
+```text
+$ niceeval show @1qrdcfq8
+@1qrdcfq8 · memory/swelancer-manager-proposals · dev-e2b/codex-e2b · failed
+snapshot 2026-07-12T10:08:29.361Z · attempt 1 · 50.0s · 58.5k tokens · $0.05
+
+assertions: 3 passed · 1 gate failed
+eval source: evals/memory/swelancer-manager-proposals.eval.ts · sha256:ee33b9c4…
+
+failures:
+  gate · Issue 15193: selected proposal matches the one maintainers accepted
+    assertion: equals(4)
+    expected: 4
+    received: 1
+    source: evals/memory/swelancer-manager-proposals.eval.ts:40:11
+
+execution: 12 events · 0 skill loads · 7 tool calls · 4 AI messages
+timing: sandbox.queue 0.2s · sandbox.create 5.6s · sandbox.setup 3.5s · agent.setup 12.1s ·
+        eval.run 26.3s · workspace.diff 0.3s · scoring.evaluate 1.4s · teardown +0.8s
+
+changes: 2 files changed by agent · M manager_decisions.json · A notes/decision-log.md
+
+available:
+  niceeval show @1qrdcfq8 --eval
+  niceeval show @1qrdcfq8 --execution
+  niceeval show @1qrdcfq8 --timing
+  niceeval show @1qrdcfq8 --diff
+```
+
+看这一页先回答一个问题：**是 agent 答错了（`failed`），还是环境根本没跑起来（`errored`）？** 两种情况的排查路线完全不同。
+
+## 场景一：断言失败（failed）——agent 跑完了，但结果不对
+
+排查顺序是「哪条断言挂了 → agent 当时做了什么 → 它到底改了什么」。
+
+**1. 把断言放回源码。** `--eval` 显示运行时保存的那份 eval 源码（不是你工作区里可能已经改过的版本），失败的断言直接标在对应行上；`t.send(...)` 的调用行标出它产生的那一轮——轮标签（`s1/t1`，与 `--execution` / `--timing` 用同一套）、这轮成没成、花了多久：
+
+```text
+$ niceeval show @1qrdcfq8 --eval
+21✓     await t.send("Review the proposals and record your decision…");
+    s1/t1 · completed · 22.4s
+38      for (const [issue, label] of Object.entries(expected)) {
+39        await t.group(`Issue ${issue}: selected proposal matches…`, async () => {
+40✗         t.check(Number(decisions[issue]?.selected_proposal_id), equals(label.selected_proposal_id));
+    gate · Issue 15193 · equals(4) · expected 4 · received 1
+41        });
+42      }
+```
+
+**2. 看 agent 当时做了什么。** `--execution` 把这次 Attempt 的对话按时间线展开——用户消息、assistant 回复、每次工具调用的入参和结果：
+
+```text
+$ niceeval show @1qrdcfq8 --execution
+TURN s1/t1 · completed · 22.4s · 12.4k tok · $0.02
+  USER
+    Review the proposals and record your decision for each issue…
+
+  ASSISTANT
+    I'll inspect the task layout and the decision format first…
+
+  TOOL · command_execution  +12.8s · 1.3s
+    input
+      /bin/bash -lc 'cat tasks/15193/proposals.md'
+    result · completed · exit 0
+      Proposal 1: …
+```
+
+对话按轮分段，每轮头行给出编号（`s1/t1`）、状态、耗时和用量——这个编号和 `--diff`、`--timing` 里的轮次标签是同一套，能互相对照。
+
+**3. 看它到底改了什么。** `--diff` 只显示 **agent 自己改动的文件**——你上传的起始文件、跑完后写入的验证材料不会混在里面，所以列表里的每一行都真的是 agent 干的：
+
+```text
+$ niceeval show @1qrdcfq8 --diff
+2 files changed by agent
+  M manager_decisions.json   +6 -2    s1/t1, s1/t2
+  A notes/decision-log.md    +18      s1/t2
+
+single file: niceeval show @1qrdcfq8 --diff=manager_decisions.json
+```
+
+行尾的 `s1/t1` 表示这个文件是在第几轮对话里被改的，能和 `--execution` 的轮次对上。要看单个文件的逐行改动，用 `=` 连写文件路径：
+
+```text
+$ niceeval show @1qrdcfq8 --diff=manager_decisions.json
+M manager_decisions.json · changed in s1/t1, s1/t2
+@@ -1,5 +1,7 @@
+ {
+-  "15193": { "selected_proposal_id": 1 },
++  "15193": { "selected_proposal_id": 4 },
+```
+
+到这里通常能下结论：是任务描述有歧义、agent 理解错了，还是断言本身写得太死。
+
+**要看文件本身，而不只是改动？** 落盘的证据刻意不保存整个工作区——`--diff` 只有 agent 改过的文件，agent 该写没写的文件、你上传的起始材料、setup 装出来的东西都不在里面。想看它们的实际内容，进活现场：重跑这一条 eval 加 `--keep-sandbox`（`failed` 的 Attempt 同样会保留，不只是环境错误），用下面场景二的方式进沙箱，workdir 里就是这次跑完时的完整文件树。
+
+## 场景二：环境错误（errored）——agent 根本没跑起来
+
+`errored` 的第一页不列断言，而是列出错误发生在哪个阶段、什么原因：
+
+```text
+$ niceeval show @12h8m4k1
+@12h8m4k1 · memory/agent-029-use-cache · compare/claude-e2b · errored
+
+error:
+  phase: sandbox.create
+  code: sandbox-rate-limit
+  message: E2B sandbox allocation failed after 5 attempts
+  cause: RateLimitError · too many concurrent sandboxes
+
+execution: unavailable (attempt failed before telemetry was configured)
+timing: sandbox.queue 1.2s · sandbox.create 2m 6s ✗ failed here
+```
+
+`phase` 直接告诉你死在哪一步，而且决定了下一步走哪条路：
+
+**`sandbox.create` 失败——沙箱根本没创建出来，没有现场可留。** 这类错误（配额、限流、凭据、镜像 / 模板不存在）在你自己的机器和账号侧排查：核对 API key 和配额、降低 `--max-concurrency`、确认镜像 / 模板名。示例里的 rate-limit 就属于这类，重跑加 `--keep-sandbox` 只会原地再死一次。
+
+**`sandbox.setup` / `agent.setup` / `eval.run` 失败——沙箱活过，值得留现场。** 装依赖失败、agent CLI 起不来、跑到一半超时，这类问题事件流往往是空的，落盘证据帮不上忙，最快的办法是留住现场进去手动重跑一遍出错的命令：
+
+```bash
+# 只重跑这一条 eval，失败时保留沙箱
+npx niceeval exp compare memory/agent-029 --keep-sandbox
+```
+
+```text
+Kept sandboxes (1)
+  @18c1m2qx  memory/agent-029-use-cache #1  errored  docker · a3f9c2d1
+             enter: niceeval sandbox enter a3f9c2d1
+Stop them with: niceeval sandbox stop --all
+```
+
+`niceeval sandbox enter a3f9c2d1` 会唤醒现场并在 workdir 打开 shell——手动执行安装命令看真实报错、翻 `$HOME` 下的配置、检查 `PATH`，这些都在 artifact 之外，只有活现场能回答；退出 shell 后现场自动回到休眠，不白烧资源。保留策略、各 provider 的差别见[保留沙箱现场](/zh/guides/debug-sandbox)。
+
+## 查看和清理留下的沙箱
+
+保留下来的沙箱不会一直烧资源：Docker 容器停驻在磁盘上，E2B 微 VM 暂停计费，进入时自动唤醒。用 `niceeval sandbox` 管理：
+
+```text
+$ niceeval sandbox list
+ID        PROVIDER  STATE            FROM
+a3f9c2d1  docker    dormant          memory/agent-029-use-cache #1 · errored · @18c1m2qx · 2026-07-14 15:02
+            enter: niceeval sandbox enter a3f9c2d1
+9f21c07b  vercel    expired          onboarding/tool-first #2 · failed  · @1x7f3q8a · 2026-07-14 14:31
+            expired 2026-07-14 14:36 — remove with: niceeval sandbox stop 9f21c07b
+```
+
+`dormant` 是「睡着但随时能进」，`expired` 是「现场已经没了，只剩记录」。排查完记得清理：
+
+```bash
+niceeval sandbox stop a3f9c2d1     # id 可以只写唯一前缀
+niceeval sandbox stop --all
+```
+
+## 场景三：复盘旧的运行
+
+每次运行都会在 `.niceeval/<实验>/<时间戳>/` 下留一份完整的结果快照，判定、断言、事件流、diff 都在里面，**不会被下一次运行覆盖**。复盘有三个入口：
+
+**用旧定位符直接打开。** 从上周的终端记录、CI 日志或报告里复制 `@` 定位符，`niceeval show @<定位符>` 照常工作，上面的 `--eval` / `--execution` / `--diff` 全部可用——包括那份运行时的 eval 源码，哪怕你后来把 eval 改了。
+
+**按实验回看当前水位。** 不记得定位符时，从实验入手：
+
+```bash
+niceeval show --experiment compare/bub        # 这个实验每道题现在的判定
+niceeval show memory/swelancer --experiment compare/bub   # 收窄到某道题
+```
+
+列表里每道题、每次 Attempt 都带定位符，接着往深处钻就回到上面的场景一 / 场景二。
+
+**在浏览器里翻。** 复盘一批失败、对比多次 Attempt 时，网页比终端顺手：
+
+```bash
+niceeval view
+```
+
+首页是成本 × 通过率总览和实验对比表；每个 Attempt 的详情页有判定、断言、完整时间树、对话、trace 和 diff，还有「Copy fix prompt」按钮——把失败整理成一段可以直接交给 coding agent 的修复提示词。报告里的 Attempt 深链和 `show` 用同一套定位符。
+
+**打开归档或别人发来的结果。** 结果目录是自包含的——从 CI 下载的、同事拷给你的、发布到静态站前生成的目录，都能直接指过去：
+
+```bash
+niceeval show --run tmp/ci-artifacts/results
+niceeval view --run site-data/run
+```
+
+一个注意点：如果本地清理过旧快照目录，之后的运行里「沿用上次结果」的条目会找不到原始证据（显示为缺失）。要长期归档某次运行，先用 [`copySnapshots`](/zh/guides/results-data) 复制出一份再删。
+
+## 速查：症状 → 命令
+
+| 症状 | 命令顺序 |
+|---|---|
+| 断言挂了，不知道为什么 | `show @loc` → `show @loc --eval` |
+| 想知道 agent 当时做了什么 | `show @loc --execution` |
+| 想确认 agent 改了哪些文件 | `show @loc --diff` → `--diff=<path>` |
+| 哪一步慢 / 超时死在哪 | `show @loc`（看 `timing:` 行）→ `show @loc --timing` |
+| 沙箱创建就失败（配额 / 凭据 / 镜像） | `show @loc` 看 error 的 code 与 cause → 查账号配额、核对凭据、降 `--max-concurrency`（没有现场可留） |
+| 装依赖失败、CLI 起不来、跑一半超时 | 重跑该 eval 加 `--keep-sandbox` → `niceeval sandbox enter <id>` |
+| 想看文件实际内容（agent 没改的、起始材料、`$HOME`） | 重跑加 `--keep-sandbox`（failed 也留）→ `sandbox enter` 进 workdir 看 |
+| 留了哪些沙箱、清理 | `sandbox list` → `sandbox stop <id>` / `--all` |
+| 复盘上周那次失败 | 翻出旧定位符 → `show @loc`；不记得就 `show --experiment <实验>` |
+| 一批失败一起看 | `niceeval view` → Attempt 详情 → Copy fix prompt |

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

@@ -35,7 +35,7 @@ export default defineExperiment({
 npx niceeval exp compare-models   # 把同组各 model 并排出报告
 ```
 
-这样每个配置独立成文件：可命名、可 diff、可单独 review，"这一组就是对照"在文件结构上就讲清楚了。
+这样每个配置独立成文件：可命名、可 diff、可单独 review，"这一组就是对照"在文件结构上就讲清楚了。默认 `niceeval show` / `view` 也沿用这条边界：只把同一文件夹下的 experiment 放进同一张成本 × 端到端成功率图和实验表，不同文件夹分别显示。
 
 某一格结果反常、需要单独复现时，用该配置的完整 id（`组/文件名`）精确只跑这一格，不用先跑完整组：
 
@@ -50,8 +50,8 @@ npx niceeval exp compare-models/gpt-5.4
 - 不同 Adapters。
 - 不同模型（Tier 1 接入即可：应用接口暴露模型选择，`model` 经 `ctx.model` 透传）。
 - 不同 prompts 或 feature flags（要求 Tier 3 接入：变体在应用内部，需要应用把它暴露成 experiment 可选的 flag，经 `flags` → `ctx.flags` 透传）。
-- 不同 sandbox 后端。
-- 不同运行环境条件（比如装不装某个记忆工具的二进制、有没有预置状态）：环境差异写在 `sandbox` spec 的 `.setup()` / `.teardown()` 钩子里，一个变体一个 experiment 文件，见 [Sandbox 后端 · 环境钩子](/zh/guides/sandbox-providers#环境钩子)。
+- 不同 sandbox provider。
+- 不同运行环境条件（比如装不装某个记忆工具的二进制、有没有预置状态）：环境差异写在 `sandbox` spec 的 `.setup()` / `.teardown()` 钩子里，一个变体一个 experiment 文件，见 [沙箱 provider · 环境钩子](/zh/guides/sandbox-providers#环境钩子)。
 - 同一任务的 pass@N。
 
 Tier 1 / Tier 2 / Tier 3 的定义见 [Tier](/zh/concepts/tier)。
@@ -67,6 +67,13 @@ api-validation   claude-code             pass@3 = 1/3 (33%)    mean 41s
 
 除了 pass rate，还应该看平均耗时、token、成本和失败类型。
 
+```bash
+npx niceeval show --experiment compare-models
+npx niceeval view
+```
+
+`show --experiment` 按路径段匹配 id 前缀，所以组名会选中组内所有配置，但不会误中名字只是在字符串上相似的另一个组。`view` 默认加载完整结果，直接在页面里选组；`--experiment` 对它只是可选的启动时收窄。
+
 ## 设计 experiment 的建议
 
 - 保持 eval 集合稳定，避免比较时混入新变量。

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

@@ -117,8 +117,10 @@ t.check(result.stdout.trim(), includes(/ok/));
 也可以运行项目自己的 test/lint/build 脚本：
 
 ```ts
+import { commandSucceeded } from "niceeval/expect";
+
 const result = await t.sandbox.runCommand("npm", ["test"]);
-t.check(result.exitCode, includes(0));
+t.check(result, commandSucceeded());
 ```
 
 ## 用 experiment 做对照组

package/docs-site/zh/guides/official-adapters.mdx

@@ -1,7 +1,7 @@
 ---
 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)。
@@ -10,14 +10,26 @@ description: "NiceEval 内置的 Sandbox 和非 Sandbox 适配器分别是什么
 
 三个内置 Sandbox agent 都用 `defineSandboxAgent` 构造，鉴权走环境变量（可用工厂参数覆盖），并且都支持在沙箱 `setup` 阶段装扩展。怎么运行内置 Sandbox agent、目录结构和自定义 Sandbox adapter，见 [Sandbox Agent](/zh/guides/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
 
 - **鉴权**：`ANTHROPIC_API_KEY`（工厂参数 `apiKey` 可覆盖），可选 `ANTHROPIC_BASE_URL`（工厂参数 `baseUrl`）。
 - **装 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` 工具，可用 `t.calledTool("Skill", { input: { skill } })` 断言，不是 `t.loadedSkill()`——那是给 `load_skill` 这个不同协议约定的语法糖）。
+- **装 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。
+- **官方配置文件**：`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/guides/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";
 import { claudeCodeAgent } from "niceeval/adapter";
@@ -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/guides/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 适配器
 

package/docs-site/zh/guides/publish-report.mdx

@@ -1,36 +1,50 @@
 ---
 title: "通过 CI 发布报告"
 sidebarTitle: "CI 发布报告"
-description: "把报告站接进 CI:.niceeval/ 提交进仓库,构建命令一行 view --out,push 即发布。发布的站和本地 niceeval view 完全一样;零可读结果时构建失败,保住上一次部署。"
+description: "把经过 copySnapshots 大小预检的结果目录提交进仓库,CI 用一行 view --run 导出报告站;超大文件在 commit 前就会得到可执行错误。"
 ---
 
-`niceeval view --out <目录>` 把查看器导出成一个纯静态目录:报告、结果快照列表、transcript、trace 瀑布,和本地 `niceeval view` 看到的完全一样(导出行为见[查看结果 · 导出与静态托管](/zh/guides/viewing-results#导出与静态托管))。CI 发布只需要让结果数据到构建机手里——把 `.niceeval/` 提交进仓库,仓库本身就是数据源。本地跑完 eval,提交并 push 就是发布,不需要任何脚本或本地构建命令。
+`niceeval view --out <目录>` 把查看器导出成一个纯静态目录:报告、结果快照列表、transcript、trace 瀑布,和本地 `niceeval view` 看到的完全一样(导出行为见[查看结果 · 导出与静态托管](/zh/guides/viewing-results#导出与静态托管))。CI 发布只需要让结果数据到构建机手里，但不要直接提交本地事实根 `.niceeval/`：逐字符串截断能防一条失控输出膨胀，不能保证整个文件小于 Git host 的限制。先用 `copySnapshots` 生成经过 50 MiB 单文件预检的发布结果根，再提交这个目录。
 
-## `.gitignore` 只排除 `diff.json`
+## 生成可提交的结果目录
 
-```gitignore
-# .niceeval/ 提交进仓库:它是线上报告的数据源,CI 构建时直接从这里生成整站。
-# 只排除 diff.json —— 单轮可达上百 MB,查看器也不读它。
-.niceeval/**/diff.json
+新建 `scripts/publish-results.ts`（项目里 eval 和配置本来就是 TypeScript，脚本也用 `.ts`，由 `tsx` 直接运行）：
+
+```javascript
+import { rm } from "node:fs/promises";
+import { copySnapshots, openResults } from "niceeval/results";
+
+const output = "report-data";
+const results = await openResults(".niceeval");
+
+await rm(output, { recursive: true, force: true });
+await copySnapshots(results.latest(), output, {
+  artifacts: ["sources", "events", "trace", "o11y", "agentSetup"],
+  redact: (text) => text.replaceAll(/sk-[A-Za-z0-9]+/g, "[redacted]"),
+});
 ```
 
+`redact` 是必填项：给一个函数改写待发布文件里的自由文本，或者确认这批数据可以原文公开、显式传 `redact: false`。要发布的站点谁都能翻到 prompt 和工具输出，这个选择必须写在脚本里。
+
+运行 `npx tsx scripts/publish-results.ts`，然后提交 `report-data/`。`copySnapshots` 在创建目录前检查所有待发布文件；任何文件超过 50 MiB 时整体失败并列出路径、大小和处理建议，不会留下半份目录。`diff` 缺省不发布；需要 diff 时显式加进 `artifacts`，它也受同一个预算约束。历史版本留下的超大 events / trace 不会被悄悄改写，预检会要求你排除这类证据或用当前版本重跑。
+
 ## 构建命令就是导出命令
 
 ```bash
-npx niceeval view --out site
+npx niceeval view --run report-data --out site
 ```
 
-`view` 对零可读结果直接报错、非零退出,不会导出一张空报告——`.niceeval/` checkout 坏掉,或所有落盘与当前 niceeval 的 schemaVersion 不兼容被整批跳过时,构建失败,Vercel / GitHub Pages 保留上一次部署。错误逐条列出被跳过的快照目录与原因,schemaVersion 场景还给出能直接查看旧落盘的 `npx niceeval@<版本> view` 命令。
+`view` 对零可读结果直接报错、非零退出,不会导出一张空报告——`report-data/` checkout 坏掉,或所有落盘与当前 niceeval 的 schemaVersion 不兼容被整批跳过时,构建失败,Vercel / GitHub Pages 保留上一次部署。错误逐条列出被跳过的快照目录与原因,schemaVersion 场景还给出能直接查看旧落盘的 `npx niceeval@<版本> view` 命令。
 
 ## 发布自定义报告
 
 不传 `--report` 时,发布出来的首页是默认报告。想让首页换成自己的报告,把 [`defineReport` 报告文件](/zh/guides/custom-reports)传给 `--report` 就行——attempt 证据页(transcript、trace、代码视图)仍在同一个站里,报告里的每个数字点进去就是对应证据,和本地 `view --report` 看到的一模一样:
 
 ```bash
-npx niceeval view --report reports/exam.tsx --out site
+npx niceeval view --run report-data --report reports/exam.tsx --out site
 ```
 
-报告文件和 `.niceeval/` 一样提交在仓库里,改完版面 push,线上就跟着更新。用下面的 `vercel.json` / workflow 时,把构建命令换成这一行即可,其余配置不用动。
+报告文件和 `report-data/` 一样提交在仓库里,改完版面 push,线上就跟着更新。用下面的 `vercel.json` / workflow 时,把构建命令换成这一行即可,其余配置不用动。
 
 ## 接托管平台
 
@@ -39,7 +53,7 @@ npx niceeval view --report reports/exam.tsx --out site
 ```json
 {
   "installCommand": "pnpm install --frozen-lockfile",
-  "buildCommand": "npx niceeval view --out site",
+  "buildCommand": "npx niceeval view --run report-data --out site",
   "outputDirectory": "site"
 }
 ```
@@ -69,7 +83,7 @@ jobs:
           node-version: 22
           cache: pnpm
       - run: pnpm install --frozen-lockfile
-      - run: npx niceeval view --out site
+      - run: npx niceeval view --run report-data --out site
       - uses: actions/upload-pages-artifact@v3
         with:
           path: site
@@ -84,8 +98,8 @@ jobs:
         uses: actions/deploy-pages@v4
 ```
 
-日常循环从此只有两步:本地跑 eval,提交 `.niceeval/` 并 push。发布出去的站带完整历史——同事打开链接,看到的和你本地 `niceeval view` 一模一样;仓库、本地查看器、线上报告三处同一个真相源。仓库体积随落盘增长(`diff.json` 已排除,增长主要来自 transcript 和 trace artifact),不想保留的旧快照直接删对应快照目录即可,查看器和报告跟着仓库走。
+日常循环是:本地跑 eval，运行 `npx tsx scripts/publish-results.ts`，提交更新后的 `report-data/` 并 push。发布目录只保留每个实验的最新结果快照；要发布其它选择策略，在脚本里替换 `results.latest()`。本地 `.niceeval/` 可以保留完整历史和 diff，不需要为了 Git 限制削掉调试证据。
 
-## 发布的是完整证据
+## 发布的是选中的证据
 
-整站导出带完整证据:transcript、源码快照、trace 原样进站点,不消毒。发布到公网前确认结果里没有密钥或敏感数据;自定义报告页的自由文本消毒见[结果数据层](/zh/guides/results-data)的 `redact` 钩子。
+整站导出会带上发布结果根里选中的 transcript、源码快照和 trace。新写入的超大 events / trace 字符串可能带结构化截断标记。`copySnapshots` 只在你给了消毒函数时改写自由文本（`redact` 是必填项，见上），其余只做选择和整文件大小预检；传 `redact: false` 的目录再导出时还要加 `--allow-sensitive-artifacts` 确认一次。发布到公网前确认结果里没有密钥或敏感数据。