niceeval 0.5.4 → 0.6.1

package/docs-site/zh/quickstart.mdx

@@ -20,8 +20,9 @@ description: "安装 NiceEval，写三个文件，10 分钟内对你自己的应
     ```
   </Step>
   <Step title="查看结果">
-    ```text
-    pnpm exec niceeval view
+    ```bash
+    pnpm exec niceeval show         # 终端摘要，适合直接交给 AI 阅读
+    pnpm exec niceeval view         # 网页查看器，适合人浏览证据
     ```
   </Step>
 </Steps>
@@ -94,7 +95,8 @@ export default defineEval({
 
 ```bash
 pnpm exec niceeval exp my-bot   # 跑起来
-pnpm exec niceeval view         # 本地查看器里看结果
+pnpm exec niceeval show         # 在终端读结果；失败项会给出继续下钻的命令
+pnpm exec niceeval view         # 需要交互浏览时打开本地查看器
 ```
 
 到这里第一条 eval 已经跑通。

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

@@ -98,12 +98,19 @@ mcpServers?: McpServer[];
 #### `skills`
 
 ```ts
-skills?: string[];
+skills?: SkillSpec[];
 ```
 
-额外安装的 skill，格式为 GitHub `"org/repo"`（如 `"Effect-TS/skills"`）。
-setup 阶段在沙箱里执行 `npx skills add <org/repo>`；
-结果写进沙箱工作区的 skills-lock.json，claude CLI 启动时自动读取。
+装进沙箱的 Skill(本地目录/文件,或 repo + 可钉 ref + 可选启用集)。
+落在 project 级 `.claude/skills/<name>/`,claude CLI 原生发现。
+
+#### `plugins`
+
+```ts
+plugins?: ClaudeCodePluginSpec[];
+```
+
+Claude Code 原生 Plugin(先连 Marketplace,再从中装指定 Plugin)。
 
 ### `CodexConfig`
 
@@ -130,16 +137,25 @@ mcpServers?: McpServer[];
 ```
 
 额外 MCP server(每个沙箱 setup 时追加进 ~/.codex/config.toml)。
-格式对应 codex config.toml 的 [mcp_server.&lt;name&gt;] 表。
+格式对应 codex config.toml 的 [mcp_servers.&lt;name&gt;] 表。
 
 #### `skills`
 
 ```ts
-skills?: string[];
+skills?: SkillSpec[];
+```
+
+装进沙箱的 Skill(本地目录/文件,或 repo + 可钉 ref + 可选启用集)。
+落在 `.agents/skills/<name>/`,并写一段发现指引进 AGENTS.md —— codex 没有 Claude Code 那种
+原生 Skill 工具,只把文件装进去它不会自己去读(见 memory/codex-no-native-skill-tool.md)。
+
+#### `plugins`
+
+```ts
+plugins?: CodexPluginSpec[];
 ```
 
-额外安装的 skill，格式为 GitHub `"org/repo"`（如 `"Effect-TS/skills"`）。
-setup 阶段执行 `npx skills add <org/repo>`，结果写进 skills-lock.json。
+Codex 原生 Plugin(先连 Marketplace,再从中装指定 Plugin)。
 
 ### `BubConfig`
 
@@ -159,15 +175,24 @@ apiBase?: string;
 
 OpenAI 兼容代理的 base URL。省略时读 BUB_API_BASE env。
 
+#### `skills`
+
+```ts
+skills?: SkillSpec[];
+```
+
+装进沙箱的 Skill(本地目录/文件,或 repo + 可钉 ref + 可选启用集)。
+落在 `.agents/skills/<name>/`,并写一段发现指引进 AGENTS.md(bub 没有原生 Skill 加载机制)。
+
 #### `pythonPlugins`
 
 ```ts
-pythonPlugins?: string[];
+pythonPlugins?: PythonPluginSpec[];
 ```
 
-额外装进 bub tool 环境的 Python 包(pip 名或 git URL)。
-每个沙箱 setup 时作为 `uv tool install --with <pkg>` 追加到 bub 环境里。
-示例:["bub-plugin-memory", "git+`https://github.com/..."`]
+额外装进 bub tool 环境的 Python Package,每个沙箱 setup 时进 `uv tool install … --with <pkg>`。
+规范化后的 package 列表进安装 checkpoint key:plugin 集合不同的两个 agent 变体不会复用同一个
+安装 checkpoint(否则第二个变体会静默拿到第一个变体的环境)。
 
 {/* GENERATED:END builtin-agent-config */}
 
@@ -189,7 +214,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` 时整轮 `status: "waiting"` + `input.requested`；`t.respond("approve" / "deny")` 翻译成 `approval-responded` 原地改写该 part、原样重发 `messages` 触发服务端续跑（和真实前端 `addToolApprovalResponse()` + `sendMessage()` 的协议行为一致，没有单独的 approve 端点）。拒绝的调用以 `rejected` 落进事件流，且默认带「不要重试」的 reason（`denyReason` 可覆盖）——不带的话模型经常原样重发同一个调用。
+- **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 只进瀑布图，不喂断言。
 
 需要在 eval 项目里安装 `ai`（可选 peer 依赖，协议 reducer 来自它）。完整可跑示例：[`examples/zh/tier1/ai-sdk-v7`](https://github.com/CorrectRoadH/niceeval/tree/main/examples/zh/tier1/ai-sdk-v7)。

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

@@ -8,7 +8,7 @@ description: "NiceEval 怎么知道你的 adapter 做到了什么：没有声明
 
 `defineAgent` / `defineSandboxAgent` 上没有 `capabilities` 字段——**没有任何东西需要你声明**。每一项能力都由构造方式或实际返回的内容证明，判定表如下。
 
-## 能力从哪来：一张判决表
+## 能力从哪来：一张对照表
 
 | 能力 | 怎么获得 | 你要写什么 |
 |---|---|---|

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

@@ -1,7 +1,7 @@
 ---
 title: "NiceEval CLI：命令、flags 和退出码参考"
 sidebarTitle: "命令行"
-description: "NiceEval CLI 参考：exp、init、list、clean 和 view 命令，以及 experiment、eval 过滤、sandbox、并发、预算和 JUnit CI 输出。"
+description: "NiceEval CLI 参考：exp、show、view、init、list 和 clean 命令，以及结果下钻、experiment、eval 过滤、并发、预算和 CI 输出。"
 ---
 
 [NiceEval](https://niceeval.com/) CLI 是发现、运行和查看 eval 的入口。实际执行 eval 时采用 experiment-first 模型：**`exp` 选择可签入的运行配置**，experiment 后的位置参数才按 eval ID 前缀过滤。agent、model 和 flags 写在 `experiments/`，不靠临时 CLI 参数。
@@ -19,10 +19,13 @@ description: "NiceEval CLI 参考：exp、init、list、clean 和 view 命令，
     发现并打印所有 eval，不运行。
   </Card>
   <Card title="npx niceeval clean" icon="trash">
-    删除 `.niceeval/` 历史运行 artifacts。
+    删除 `.niceeval/` 下历史快照 artifacts。
+  </Card>
+  <Card title="npx niceeval show [id-prefix | @locator]" icon="terminal">
+    在终端读取结果；用 `@<locator>` 或 eval ID 前缀下钻断言、Eval 源码、执行事件流、diff 和历史。
   </Card>
   <Card title="npx niceeval view" icon="eye">
-    打开结果查看器，查看最近一次运行的 artifacts。
+    打开网页结果查看器，读默认报告并交互浏览 Eval 源码、执行事件流与 diff；默认范围与 `show` 相同。跨 run 时间轴（`--history`）是 `show` 专用的终端能力。
   </Card>
 </CardGroup>
 
@@ -46,6 +49,9 @@ npx niceeval exp
 # 运行一个实验组
 npx niceeval exp compare-models
 
+# 只运行该组里的一个配置(id = 组/文件名,不带扩展名)
+npx niceeval exp compare-models/gpt-5.4
+
 # 在该组里只运行 ID 以 weather 开头的 eval
 npx niceeval exp compare-models weather
 ```
@@ -54,6 +60,8 @@ npx niceeval exp compare-models weather
   eval 过滤参数只出现在 experiment 选择之后。裸 `npx niceeval weather` 不会运行；请使用 `npx niceeval exp local weather` 或 `npx niceeval exp compare weather`。
 </Note>
 
+第一个位置参数既能填实验组名，也能填单个配置的完整 id：精确匹配到 `组/文件名` 时只跑组内那一个配置，适合逐配置验证或对比排查某一格结果，不用把其它配置文件挪出目录。
+
 ## 常用 flags
 
 下表由 CLI 的 flag 解析表生成，表外的 flag 一律按未知 flag 报错并以非零状态退出。**没有**用于选择 sandbox 后端的 CLI flag：sandbox 后端只能写在代码里——在 experiment（`defineExperiment`）里设置 `sandbox`，或者在 `niceeval.config.ts`（`defineConfig`）里设置作为项目级兜底，值来自 `niceeval/sandbox` 的 `dockerSandbox()` / `vercelSandbox()` / `e2bSandbox()`。
@@ -75,18 +83,17 @@ npx niceeval exp compare-models weather
 | `--json` | string | 额外写一份 JSON 结果(`RunSummary` 原样序列化)到指定路径,供 CI 或下游脚本消费。 |
 | `--out` | string | `view` 命令专用:把结果查看器静态导出到指定目录。 |
 | `--port` | number | `view` 命令专用:指定本地服务器监听端口。 |
-| `--transcript` | boolean | `show` 命令专用:渲染单个 eval 的完整对话与工具调用(证据切面)。 |
-| `--trace` | boolean | `show` 命令专用:渲染单个 eval 的 trace 瀑布文本版(证据切面)。 |
+| `--eval` | boolean | `show` 命令专用:该 attempt 运行时保存的 Eval 源码,gate/soft 断言标回源码行(证据切面)。 |
+| `--execution` | boolean | `show` 命令专用:该 attempt 的标准执行事件流(消息、thinking、Skill load、工具调用/结果);有 OTel 时同一节点补时间(证据切面)。 |
 | `--diff` | boolean | `show` 命令专用:sandbox 里的文件改动摘要;`--diff=<文件路径>` 看单个文件的完整改动(路径必须 `=` 连写)。 |
 | `--history` | boolean | `show` 命令专用:跨 run 时间轴,只列真实执行;与 `--report` 互斥。 |
-| `--experiment` | string | `show` / `view` 命令专用:选集只留该实验。 |
-| `--attempt` | number | `show` 命令专用:指定详情 / 证据切面看第几次 attempt(与展示一致的 1 计序号)。 |
-| `--run` | string | `show` / `view` 命令专用:钉死看某一个结果目录(历史 run 或 `copySnapshots` 产物)。 |
-| `--report` | string | `show` / `view` 命令专用:用你的报告文件替换默认报告(文件默认导出 `defineReport(...)`)。 |
+| `--experiment` | string | `show` / `view` 命令专用:Selection 只留该实验。 |
+| `--run` | string | `show` / `view` 命令专用:钉死看某一个结果目录(某次快照或 `copySnapshots` 产物)。 |
+| `--report` | string | `show` / `view` 命令专用:渲染你的报告文件(文件默认导出 `defineReport(...)`);show 用它替换 Attempt 索引,view 用它替换默认分析报告。 |
 | `--dry` | boolean | 只打印本次会匹配到的 eval × 运行配置,不实际执行。 |
-| `--quiet` | boolean | 关闭控制台 / live 进度输出(reporter 仍会写 artifacts)。 |
+| `--quiet` | boolean | 关闭控制台 / live 的逐条结果与末尾汇总(attempt 进度行仍写 stderr);errored / failed 的结果各在 stderr 补一行摘要,passed / skipped 静默;reporter 仍会写 artifacts。 |
 | `--force` | boolean | 忽略上次运行结果,不跳过已通过的 (experiment, eval) 组合,强制全部重跑。 |
-| `--strict` | boolean | CI 中推荐使用:让软阈值(`soft`)失败也计入整条 eval 的 outcome。 |
+| `--strict` | boolean | CI 中推荐使用:让软阈值(`soft`)失败也计入整条 eval 的 verdict。 |
 | `--early-exit` / `--no-early-exit` | boolean | 某个 eval 的一次 attempt 通过后,停止该 eval 剩余的 attempts。 |
 | `--open` / `--no-open` | boolean | `view` 命令专用:启动后自动打开浏览器(默认行为)。 |
 | `--help` | boolean | 打印用法说明并退出。 |
@@ -117,13 +124,29 @@ npx niceeval exp compare-models weather-tool
 npx niceeval view
 ```
 
-打开本地结果查看器。默认查看最近一次 `.niceeval/` 运行。
+打开本地结果查看器。它和 `show` 共用同一份默认报告和同一套默认选择——对每个 experiment、每个 eval，取历次运行里最新的那份判定；只补跑部分 eval 时，其余 eval 从更早的运行补齐。`show` 输出终端文本，`view` 输出网页并提供可交互的证据浏览；eval ID 前缀、`--experiment`、`--run` 对两者的收窄一致。完整说明见[查看结果](/zh/guides/viewing-results)。
+
+## `show [id-prefix...]`
+
+```bash
+npx niceeval show
+npx niceeval show weather/brooklyn
+npx niceeval show @1k2m9qrs
+npx niceeval show @1k2m9qrs --eval
+npx niceeval show @1k2m9qrs --execution
+npx niceeval show fixtures/button --diff
+npx niceeval show weather/brooklyn --history
+```
+
+`show` 是终端结果入口，适合人直接阅读，也适合 coding agent 在上下文窗口里逐级下钻。位置参数选「看哪些 eval」（ID 前缀）或直接用 `@<locator>` 精确选一个 attempt；不带位置参数时显示同一张紧凑 attempt 表，指定 eval ID 前缀只是收窄这张表的行数，不会切换成另一种视图。
+
+`@<locator>` 不带证据 flag 时给出该 attempt 的紧凑全景（断言摘要、执行摘要、可选 OTel 时间、diff 摘要）；`--eval`、`--execution`、`--diff` 是同一 attempt 的证据切面，分别展开运行时保存的 Eval 源码、标准执行事件流、工作区文件改动，因此必须搭配 `@<locator>` 精确指名一个 attempt。`--run` 钉住某次结果目录，`--history` 查看跨 run 趋势。完整的阅读顺序、输出示例和 artifact 说明见[查看结果](/zh/guides/viewing-results)。
 
 ## `--early-exit` 与 `--strict`
 
 `--early-exit` 默认就是 `true`：某个 eval 的一次 attempt 通过后，会自动停止该 eval 剩余的 attempts（省钱）。所以显式传 `--early-exit` 没有效果，真正有用的是反过来关掉它——`--no-early-exit`，让 `--runs` > 1 时把每次 attempt 都跑完（测真实通过率而非提前收尾）。
 
-`--strict` 不是"更严格地报错"，而是改变软阈值断言的判定：`.atLeast(n)` 这类软阈值（`soft` severity）平时失败不会把整条 eval 判为 `failed`（只是记一条不达标的断言），加了 `--strict` 之后，软阈值没达标也会让整条 eval 的 outcome 计为 `failed`。CI 中推荐加上，避免"断言分数不够但 eval 显示通过"的情况被放过。
+`--strict` 不是"更严格地报错"，而是改变软阈值断言的判定：`.atLeast(n)` 这类软阈值（`soft` severity）平时失败不会把整条 eval 判为 `failed`（只是记一条不达标的断言），加了 `--strict` 之后，软阈值没达标也会让整条 eval 的 verdict 计为 `failed`。CI 中推荐加上，避免"断言分数不够但 eval 显示通过"的情况被放过。
 
 ## 环境变量覆盖
 

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

@@ -245,7 +245,9 @@ experiment 跑(如脱离 CLI、直接构造 `AgentRun` 的场景)时为 undefine
 readonly sandbox: Sandbox;
 ```
 
-仅沙箱型 agent 有(运行器按 --sandbox 备好)。
+所有 agent 都有:沙箱型是运行器按项目/experiment 配置备好的真实沙箱句柄,remote 型是
+`createRemoteSandbox()` 产出的 stub(仅含 `workdir`/`sandboxId`/`otlpHost`/`stop` 等
+元信息,其余方法调用即抛错)。
 
 #### `session`
 
@@ -338,7 +340,7 @@ readFile(path: string): Promise<string>;
 fileExists(path: string): Promise<boolean>;
 ```
 
-检查沙箱内路径是否存在。跨后端语义不完全一致:仅保证对普通文件可靠,对目录路径的行为不同后端不保证一致。
+检查沙箱内路径是否存在。跨 provider 语义不完全一致:仅保证对普通文件可靠,对目录路径的行为不同 provider 不保证一致。
 
 #### `readSourceFiles`
 
@@ -379,7 +381,7 @@ uploadDirectory(localDir: string, targetDir?: string, opts?: { ignore?: string[]
 stop(): Promise<void>;
 ```
 
-销毁沙箱占用的计算资源(容器/microVM)。调用后沙箱不可再用;是否可安全重复调用因后端而异,不要依赖这一点。
+销毁沙箱占用的计算资源(容器/microVM)。调用后沙箱不可再用;是否可安全重复调用因 provider 而异,不要依赖这一点。
 
 #### `sandboxId`
 
@@ -387,7 +389,7 @@ stop(): Promise<void>;
 readonly sandboxId: string;
 ```
 
-本沙箱的稳定标识(各后端原生 ID,如 Docker 容器 ID 前缀);用于跨调用关联同一沙箱的会话状态,也用于日志展示。
+本沙箱的稳定标识(各 provider 原生 ID,如 Docker 容器 ID 前缀);用于跨调用关联同一沙箱的会话状态,也用于日志展示。
 
 #### `otlpHost`
 
@@ -407,7 +409,7 @@ appendLog?(line: string): Promise<void>;
 ```
 
 可选:把一行写进容器的「主日志」(PID1 在 tail 它)——于是 `docker logs` /
-Docker UI 的 Logs 标签页能实时看到 agent 逐轮活动。docker 后端实现,其它可省略。
+Docker UI 的 Logs 标签页能实时看到 agent 逐轮活动。docker provider 实现,其它可省略。
 
 #### `downloadFile`
 
@@ -416,7 +418,7 @@ downloadFile(path: string): Promise<Buffer>;
 ```
 
 从沙箱内任意路径读取文件,返回二进制 Buffer。
-对应各 backend:Docker getArchive / Vercel readFileToBuffer / e2b files.read(bytes) / …
+对应各 provider:Docker getArchive / Vercel readFileToBuffer / e2b files.read(bytes) / …
 
 #### `uploadFile`
 
@@ -425,7 +427,7 @@ uploadFile(path: string, content: Buffer): Promise<void>;
 ```
 
 向沙箱内任意路径写入文件(二进制)。
-对应各 backend:Docker putArchive / Vercel fs.writeFile(Buffer) / e2b files.write / …
+对应各 provider:Docker putArchive / Vercel fs.writeFile(Buffer) / e2b files.write / …
 
 ### `CommandOptions`
 
@@ -435,7 +437,7 @@ uploadFile(path: string, content: Buffer): Promise<void>;
 env?: Record<string, string>;
 ```
 
-追加/覆盖本命令的环境变量(与沙箱默认环境叠加,不清空默认值;各后端会保留自己固定的 `PATH` 等变量,不保证能被这里覆盖)。
+追加/覆盖本命令的环境变量(与沙箱默认环境叠加,不清空默认值;各 provider 会保留自己固定的 `PATH` 等变量,不保证能被这里覆盖)。
 
 #### `cwd`
 
@@ -453,8 +455,8 @@ stream?: boolean;
 
 把本命令的输出也送进沙箱的「原生日志流」(于是 `docker logs` / Docker UI 的 Logs
 标签页能实时看到它)。给 agent 命令(codex exec / bub run / claude)开它,就能在容器
-日志里看到 agent 的【原始输出】。后端各自实现(docker:tee 到 PID1 tail 的文件;
-不支持的后端忽略)—— 日志怎么浮现是 backend 的事,adapter 只声明意图。
+日志里看到 agent 的【原始输出】。provider 各自实现(docker:tee 到 PID1 tail 的文件;
+不支持的 provider 忽略)—— 日志怎么浮现是 provider 的事,adapter 只声明意图。
 
 #### `root`
 
@@ -465,10 +467,10 @@ root?: boolean;
 以 root 跑本命令。默认 `false` —— 命令以沙箱的标准**非 root** 用户跑(agent 的自然环境)。
 给 setup 阶段装系统依赖用(`apt-get install …`、`pip install --break-system-packages …`)。
 
-语义跨后端一致:"本命令以 root 跑,否则以标准非 root 用户跑"。各后端映射到自己的原生机制
+语义跨 provider 一致:"本命令以 root 跑,否则以标准非 root 用户跑"。各 provider 映射到自己的原生机制
 (docker:`exec --user root`;E2B:`{ user: "root" }`;Vercel:`{ sudo: true }`;Daytona:`{ user }`)。
-本就全程 root 的后端(如 Modal)视作 no-op;完全无法提权的后端可不支持(抛错)—— 但**默认值与
-语义保持一致**,不因后端而变。
+本就全程 root 的 provider(如 Modal)视作 no-op;完全无法提权的 provider 可不支持(抛错)—— 但**默认值与
+语义保持一致**,不因 provider 而变。
 
 {/* GENERATED:END sandbox-methods */}
 

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

@@ -37,7 +37,7 @@ name?: LocalizedText;
 sandbox?: SandboxOption;
 ```
 
-项目级默认沙箱后端(docker / vercel / e2b / custom);experiment / CLI flag 可覆盖。
+项目级默认沙箱 provider(docker / vercel / e2b / custom);experiment 可覆盖。
 
 #### `workspace`
 

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

@@ -92,7 +92,7 @@ setup?: (sandbox: Sandbox) => Promise<void | Cleanup> | void | Cleanup;
 
 eval 级预置:拿到沙箱(已上传 workspace + git 基线 + 装好依赖前)。
 默认命令以非 root 跑(agent 的自然环境);装系统依赖时给 `runCommand` 传 `{ root: true }`
-(如 `runCommand("apt-get", ["install", …], { root: true })`),跨后端语义一致。
+(如 `runCommand("apt-get", ["install", …], { root: true })`),跨 provider 语义一致。
 
 #### `test`
 
@@ -193,7 +193,7 @@ newSession(): SessionHandle;
 readonly signal: AbortSignal;
 ```
 
-本次 attempt 的中止信号;超时 / 早停 / 用户 Ctrl-C 时触发,传给 adapter 的长耗时调用做取消。
+本次 attempt 的中止信号;超时 / 首过即停 / 用户 Ctrl-C 时触发,传给 adapter 的长耗时调用做取消。
 
 #### `model`
 
@@ -233,7 +233,7 @@ log(msg: string): void;
 skip(reason: string): never;
 ```
 
-立即中止本 eval 并标记为 skipped(outcome / EvalResult.skipReason),reason 不能为空。
+立即中止本 eval 并标记为 skipped(verdict / EvalResult.skipReason),reason 不能为空。
 
 #### `check`
 

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

@@ -1,7 +1,7 @@
 ---
 title: "标准事件流参考"
 sidebarTitle: "事件流"
-description: "StreamEvent 的九种事件：每种的字段、什么时候吐、哪些断言消费它。adapter 的核心工作就是产出这条流。"
+description: "StreamEvent 的十种事件：每种的字段、什么时候吐、哪些断言消费它。adapter 的核心工作就是产出这条流。"
 ---
 
 adapter 的 `send` 返回一个 `Turn`，其中 `events: StreamEvent[]` 是**断言的唯一数据源**：`t.calledTool()`、`t.reply`、`toolOrder`、`noFailedActions`……全部从这条流上读。把你的 agent"这一轮做了什么"翻成这条流，整套断言就都能用。
@@ -79,7 +79,7 @@ token 用量或 OTel span 反推得到)。存在时优先于按价格表(`define
 
 ## StreamEvent 变体一览
 
-`StreamEvent` 的九种变体，逐字段列出（消费它们的断言 / 使用细节见下面的「事件总表」和「逐事件说明」）：
+`StreamEvent` 的十种变体，逐字段列出（消费它们的断言 / 使用细节见下面的「事件总表」和「逐事件说明」）：
 
 {/* GENERATED:BEGIN stream-events */}
 
@@ -108,6 +108,12 @@ token 用量或 OTel span 反推得到)。存在时优先于按价格表(`define
 }
 ```
 
+#### `skill.loaded`
+
+```ts
+{ type: "skill.loaded"; skill: string; callId?: string }
+```
+
 #### `subagent.called`
 
 ```ts
@@ -206,7 +212,7 @@ token 用量或 OTel span 反推得到)。存在时优先于按价格表(`define
 } }
 ```
 
-agent 停轮等人时，每个待回答的问题吐一条，同时整轮 `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/guides/connect-your-agent)。
 
 ### `thinking` / `compaction` / `error`
 

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

@@ -125,7 +125,7 @@ export function makeAssertion(spec: {
 }): ValueAssertion { ... }
 ```
 
-自定义断言工厂:直接给名字 / 严重级 / 阈值 / score,一次调用即返回可用的 ValueAssertion——
+自定义断言工厂:直接给名字 / 严重度 / 阈值 / score,一次调用即返回可用的 ValueAssertion——
 不像 gate()/atLeast() 那样需要二段链式调用来定级。severity 省略默认 gate。
 
 {/* GENERATED:END expect-matchers */}
@@ -192,21 +192,26 @@ gate(threshold?: number): ValueAssertion;
 atLeast(threshold: number): ValueAssertion;
 ```
 
-转成软阈值断言:未达 threshold 时该条记为 failed,但默认不拖累整条 eval 的 outcome;
-`--strict` 运行下,软阈值失败也会把整条 eval 的 outcome 计为 failed。返回新实例,不改原对象。
+转成软阈值断言:未达 threshold 时该条记为 failed,但默认不拖累整条 eval 的 verdict;
+`--strict` 运行下,软阈值失败也会把整条 eval 的 verdict 计为 failed。返回新实例,不改原对象。
 
 {/* GENERATED:END value-assertion */}
 
 ## 自定义 matcher
 
 ```ts
-import { makeAssertion } from "niceeval/expect";
+import { makeAssertion, type Assertion } from "niceeval/expect";
 
-const validEmail = makeAssertion("valid email", (value) => {
-  return typeof value === "string" && value.includes("@") ? 1 : 0;
-});
+function validEmail(): Assertion {
+  return makeAssertion({
+    name: "valid email",
+    score(value) {
+      return typeof value === "string" && value.includes("@") ? 1 : 0;
+    },
+  });
+}
 
 t.check(t.reply, validEmail());
 ```
 
-自定义 matcher 应返回 0 到 1 之间的分数，并给出清晰名称。
+`makeAssertion` 接受单个 spec 对象（`name`、可选 `severity`/`threshold`、`score`），直接返回一个 `Assertion`；按惯例用一个同名函数包一层再调用，而不是把 `makeAssertion` 本身当工厂调用。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "niceeval",
-  "version": "0.5.4",
+  "version": "0.6.1",
   "description": "Agent-native eval tool — eval agents, services, functions, and coding-agent fixtures",
   "type": "module",
   "license": "MIT",
@@ -49,18 +49,21 @@
       "import": "./src/results/index.ts"
     },
     "./report": {
-      "types": "./src/report/index.ts",
-      "import": "./src/report/index.ts"
+      "types": "./dist/report/index.d.ts",
+      "import": "./dist/report/index.js"
     },
     "./report/react": {
-      "types": "./src/report/react/index.tsx",
-      "import": "./src/report/react/index.tsx"
+      "types": "./dist/report/react/index.d.ts",
+      "import": "./dist/report/react/index.js"
     },
-    "./report/react/styles.css": "./src/report/react/styles.css"
+    "./report/react/styles.css": "./src/report/react/styles.css",
+    "./report/react/enhance.js": "./src/report/react/enhance.js"
   },
   "files": [
+    "INDEX.md",
     "src",
     "bin",
+    "dist",
     "docs-site/zh",
     "docs-site/images"
   ],
@@ -159,6 +162,7 @@
     "tiers:sync": "node scripts/sync-tiers.mjs sync",
     "tiers:check": "node scripts/sync-tiers.mjs check",
     "view:build": "vite build --config src/view/app/vite.config.ts",
+    "build:report": "tsc -p tsconfig.report-build.json && node scripts/prune-report-dist.mjs",
     "site:dev": "cd site && node scripts/dev.mjs",
     "site:build": "cd site && next build",
     "docs:dev": "cd docs-site && npx --yes mint@latest dev",