niceeval 0.2.1 → 0.4.0

package/README.md

@@ -12,13 +12,17 @@
 
 </div>
 
-NiceEval is an agent-native eval tool inspired by [eve](https://eve.dev). It has an excellent DX design — anyone can get started and configured in about 10 minutes. It's also versatile: it can eval plugins, Hooks, and Skills written for Claude Code/Codex coding agents, and can directly eval your own AI agent application or framework (AI SDK, LangGraph, Pi, or any custom agent loop).
+NiceEval is an Agent-Native eval tool inspired by [eve](https://eve.dev), built for the best possible DX.
 
-After the eval completes, it generates readable reports and lets you view agent behavior details. Convenient for debugging and optimization.
+Thanks to its universal design, NiceEval can evaluate almost any agent application.
+Whether you need to evaluate coding agent plugins, Hooks, and Skills written for Claude Code / Codex, or your own AI agent application — both plug in easily.
+
+After the eval completes, it generates readable reports and lets you view agent behavior details. Convenient for debugging and understanding agent behavior.
 
 ## Why NiceEval when DeepEval, LangFuse, and BrainTrust already exist
 
-NiceEval is an AI-native eval tool. In tools built around Dataset/golden-style Input vs. Expected Output, that shape doesn't fit real agent evaluation well. NiceEval is built for evaluating agents at a finer grain — multi-turn conversations, multi-agent setups, tool calls, skill loading, and more.
+NiceEval is an Agent-Native eval tool. The Dataset / golden pattern of building an Input and an Expected Output doesn't fit real agent evaluation.
+Agents today need to be evaluated at a finer grain — multi-turn conversations, multi-agent collaboration, tool calls, skill loading — and NiceEval does this better.
 
 It also coexists with LangFuse and BrainTrust: use them for tracing, or upload eval results to both (in progress).
 
@@ -32,19 +36,19 @@ NiceEval supports two integration modes, depending on whether the agent under te
    evals/*.eval.ts
         │
         ▼
-   ┌─────────────────────┐
-   │     NiceEval        │
-   └─────────────────────┘
+   ┌────────────┐
+   │  NiceEval  │
+   └────────────┘
         │
         │ Agent adapter (official)
         ▼
-   ┌──────────────────────────────┐
-   │        Docker Sandbox         │
-   │   ┌────────────────────────┐  │
-   │   │ Codex / Claude Code /  │  │
-   │   │ apps needing isolation │  │
-   │   └────────────────────────┘  │
-   └──────────────────────────────┘
+   ┌────────────────────────────────┐
+   │         Docker Sandbox         │
+   │    ┌────────────────────────┐  │
+   │    │ Codex / Claude Code    │  │
+   │    │ apps needing isolation │  │
+   │    └────────────────────────┘  │
+   └────────────────────────────────┘
 ```
 
 **Mode 2: Direct — connect straight to your own AI Agent**
@@ -53,18 +57,16 @@ NiceEval supports two integration modes, depending on whether the agent under te
    evals/*.eval.ts
         │
         ▼
-   ┌─────────────────────┐
-   │     NiceEval        │
-   └─────────────────────┘
+   ┌────────────┐
+   │  NiceEval  │
+   └────────────┘
         │
         │ Agent adapter (official, or your own implementation)
         ▼
-   ┌──────────────────────────────┐
-   │       your own AI Agent       │
-   │   (AI SDK·LangGraph·Pi and    │
-   │    other agent frameworks —   │
-   │         no Docker needed)     │
-   └──────────────────────────────┘
+   ┌──────────────────────────┐
+   │    your own AI Agent     │
+   │   (AI SDK·LangGraph·Pi)  │
+   └──────────────────────────┘
 ```
 
 - **NiceEval core** owns discovery, scheduling, scoring, reporting, and artifacts.
@@ -74,8 +76,6 @@ NiceEval supports two integration modes, depending on whether the agent under te
 
 ## Example
 
-Running an eval takes two files: the eval itself (what to check) and an experiment (which agent to run it against). The CLI won't run a bare eval id — the experiment in `niceeval exp <experiment> <eval prefix>` is what picks the system under test. Here's a real eval against a directly-connected web agent (full project in [`examples/zh/ai-sdk/`](examples/zh/ai-sdk/)), checking that the agent calls a tool for live weather questions and answers from the tool result instead of making it up:
-
 ```ts
 // evals/eval-tool-call.eval.ts
 import { defineEval } from "niceeval";
@@ -109,16 +109,15 @@ import { webAgent } from "./adapter"; // your agent adapter, pointed at the syst
 
 export default defineExperiment({
   agent: webAgent({ baseUrl: "http://127.0.0.1:5188" }),
+  model: "gpt-5.5"
 });
 ```
 
 ```sh
-npx niceeval exp local eval-tool-call  // run only eval-tool-call under the local experiment
-npx niceeval view
+pnpm exec niceeval exp local eval-tool-call  // run only eval-tool-call under the local experiment
+pnpm exec niceeval view // view eval results
 ```
 
-For coding agents that need an isolated workspace (Codex, Claude Code plugins/skills), see [`examples/zh/coding-agent-skill/`](examples/zh/coding-agent-skill/): evals there use `t.sandbox.uploadDirectory()` to seed the workspace, `t.fileChanged()` / `t.file()` to check what changed, and `t.sandbox.runCommand()` to run tests.
-
 ## Quick Start
 
 ```text
@@ -135,19 +134,20 @@ Start from the scenario that matches what you need to evaluate:
 ## Roadmap
 Official Adapters
 - [ ] Agent Software
-  - [ ] Claude Code
-  - [ ] Codex
-  - [ ] Bub
+  - [x] Claude Code
+  - [x] Codex
+  - [x] Bub
   - [ ] OpenClaw
   - [ ] Hermess Agent
   - [ ] Alma
   - [ ] ...
 
 - [ ] Agent Frameworks
-  - [ ] AI SDK
+  - [x] AI SDK
+  - [x] Claude SDK
+  - [x] Codex SDK
+  - [x] Pi Agent SDK
   - [ ] LangGraph
-  - [ ] Claude SDK
-  - [ ] Codex SDK
   - [ ] vm0
   - [ ] Cursor Agent SDK
 

package/README.zh.md

@@ -12,12 +12,16 @@
 
 </div>
 
-NiceEval 是一个受 [eve](https://eve.dev) 启发的 agent-native eval 工具，追求足够好的开发体验：大多数项目可以在 10 分钟左右接入并配置。它的设计也足够通用——既可以用来 eval 给 Claude Code / Codex 写的 coding agent 插件、Hook 和 Skill，也可以直接 eval 你自己的 AI Agent 应用或框架（无论基于 AI SDK、LangGraph、Pi 还是自研 agent loop，都能轻松接入）。
+NiceEval 是一个受 [eve](https://eve.dev) 启发的 Agent-Native eval 工具，追求极致的DX。
+
+通过通用式的设计，使 NiceEval 可以为几乎所有 Agent 应用进行评估。
+无论你是需要评估为 Claude Code / Codex 写的 coding agent 插件、Hook 和 Skill，还是可以评估你自己的 AI Agent 应用都能轻松接入。
 
 在 eval 完成之后可以生成易读的报告与查看 Agent 的行为细节。方便 Debug 与理解 Agent 行为。
 
 ## 为什么有了 DeepEval、LangFuse、BrainTrust 还需要 NiceEval
-NiceEval 是一个 AI-native 的评估工具。Dataset / golden 那一套「构建 Input 与 Expected Output」的模式，并不适合真实的 agent 评估；当 agent 需要在多轮对话、多 agent 协作、工具调用、Skill 加载等细粒度场景下被评估时，NiceEval 能做得更好。
+NiceEval 是一个 Agent-Native 的评估工具。Dataset / golden 那一套「构建 Input 与 Expected Output」的模式，并不适合真实的 Agent 评估。
+现在 Agent 需要在多轮对话、多 agent 协作、工具调用、Skill 加载等细粒度场景下进行评估，NiceEval 能做得更好。
 
 同时，NiceEval 也能与 LangFuse、BrainTrust 共存：可以用它们做 tracing，或者把评估结果上传到两者（这部分功能还在开发中）。
 
@@ -40,8 +44,8 @@ NiceEval 支持两种接入方式，取决于被测 agent 是否需要隔离的
    ┌──────────────────────────────┐
    │        Docker Sandbox        │
    │   ┌────────────────────────┐ │
-   │   │ Codex / Claude Code /  │ │
-   │   │ 需要隔离文件系统的应用   │ │
+   │   │ Codex / Claude Code    │ │
+   │   │ 需要隔离文件系统的应用     │ │
    │   └────────────────────────┘ │
    └──────────────────────────────┘
 ```
@@ -59,9 +63,8 @@ NiceEval 支持两种接入方式，取决于被测 agent 是否需要隔离的
         │ Agent 适配器(官方，或者自己实现)
         ▼
    ┌──────────────────────────────┐
-   │       你自己的 AI Agent      │
-   │   (AI SDK·LangGraph·Pi 等     │
-   │     agent 框架，无需 Docker)  │
+   │       你自己的 AI Agent        │
+   │   (AI SDK·LangGraph·Pi )     │ 
    └──────────────────────────────┘
 ```
 
@@ -69,10 +72,19 @@ NiceEval 支持两种接入方式，取决于被测 agent 是否需要隔离的
 - **Agent 适配器** 是开放的边界：你来决定如何调用被测系统。
 - 需要文件系统隔离的 coding agent 走 **Docker Sandbox**；自有的 AI Agent 可以直连，无需 Docker。
 
+## 核心概念一览
 
-## 示例
+| 概念 | 一句话 |
+|---|---|
+| Eval | 一个测试用例：写在 `evals/*.eval.ts` 里，描述测什么。 |
+| Experiment | 可签入的运行配置：决定连哪个 Adapter、什么 model、什么 flags。 |
+| Adapter | 连接被测系统的适配层：实现一个 `send`，把返回翻译成标准事件流。 |
+| Sandbox | 需要隔离工作区的 coding agent 才用得到；直连 Web Agent 不需要。 |
+| Tier | 接入 Adapter 的三档投入：Tier 1 只接 send，Tier 2 加 OTel 换调用瀑布图，Tier 3 侵入改造做 feature A/B。 |
 
-跑一条 eval 需要两个文件：eval 本身（测什么）和 experiment（跑哪个 agent）。CLI 不接受裸 eval id——`niceeval exp <experiment> <eval 前缀>` 里的 experiment 才是决定「连哪个被测对象」的地方。下面是一个直连 AI Agent 的真实场景（完整项目见 [`examples/zh/ai-sdk/`](examples/zh/ai-sdk/)），验证 agent 遇到实时天气问题时会调用工具、并基于工具结果作答，而不是凭空编造：
+完整术语表见[架构概览](https://niceeval.com/docs/zh/concepts/overview)。
+
+## 示例
 
 ```ts
 // evals/eval-tool-call.eval.ts
@@ -107,6 +119,7 @@ import { webAgent } from "./adapter"; // 你自己写的 agent adapter，接被
 
 export default defineExperiment({
   agent: webAgent({ baseUrl: "http://127.0.0.1:5188" }),
+  model: "gpt-5.5"
 });
 ```
 
@@ -131,19 +144,20 @@ READ https://niceeval.com/INIT.md and install niceeval for this repo.
 ## Roadmap
 官方适配器
 - [ ] Agent 软件
-  - [ ] Claude Code
-  - [ ] Codex
-  - [ ] Bub
+  - [x] Claude Code
+  - [x] Codex
+  - [x] Bub
   - [ ] OpenClaw
   - [ ] Hermess Agent
   - [ ] Alma
   - [ ] ...
 
 - [ ] Agent 框架
-  - [ ] AI SDK
+  - [x] AI SDK
+  - [x] Claude SDK
+  - [x] Codex SDK
+  - [x] Pi Agent SDK
   - [ ] LangGraph
-  - [ ] Claude SDK
-  - [ ] Codex SDK
   - [ ] vm0
   - [ ] Cursor Agent SDK
 

package/docs/README.md

@@ -110,7 +110,8 @@ npx niceeval exp local fixtures/button
 - **建立心智模型:** [Vision](vision.md)、[Concepts(术语表)](concepts.md)、[Architecture](architecture.md)。
 - **写 eval:** [Eval Authoring(编写 eval)](eval-authoring.md)、[Assertions(断言参考:作用域 + 来源)](assertions.md)、[Scoring(评分器)](scoring.md)。
 - **连 AI / 接 agent:** [Agents 与 Adapters(定位与导航)](adapters/README.md)、[Origin 应用接入手册(五个应用的接入记录)](origin-integration.md)、[Tier Sync(examples origin→tier 同步维护工具)](tier-sync.md)、[Adapter 契约(逐 API 适配义务)](adapters/contract.md)、[Adapter 写法(递进式写法)](adapters/authoring.md)、[Capabilities by Construction(能力由构造证明)](capabilities-by-construction.md)、[采集设计(三条外部路线对比)](adapters/collection.md)、[接入目标矩阵(12 个被测对象调研)](adapters/targets.md)、[Coding Agent Skills / Plugins DX](adapters/coding-agent-skills-plugins.md)、[Sandbox](sandbox.md)、[Observability(含 OTel trace 瀑布图)](observability.md)。
-- **设计提案(未实现):** [Multi-Agent(多 agent eval 的三种场景)](multi-agent.md)、[E2E CI(全链路 CI 测试方案)](e2e-ci.md)。
+- **设计提案(未实现):** [Multi-Agent(多 agent eval 的三种场景)](multi-agent.md)、[Reports(自己搭报告页:React 组件 × 查询模型两档积木)](reports.md)、[Results Lib(结果数据的读写库,Reports 的数据层)](results-lib.md)。
+- **框架自测:** [E2E CI(全链路 e2e 测试方案;`e2e/` 的 tier1 矩阵已落地,workflow 未建)](e2e-ci.md)。
 - **跑与看:** [Experiments(实验/运行矩阵)](experiments.md)、[Runner(执行引擎)](runner.md)、[CLI 参考](cli.md)、[Observability(可观测性)](observability.md)、[Results Format(结果保存格式)](results-format.md)、[View(本地查看器)](view.md)。
 - **背景调研:** [References(从其它项目学到什么)](references.md)、[agent-eval 是怎么做适配的](adapters/reference/agent-eval.md)、[OTel GenAI 等「行为怎么记」标准](adapters/reference/otel-genai.md)、[四个主流 agent loop 接入面调研](adapters/reference/agent-loop-apis.md)、[应用侧 OTel 埋点生态调研](adapters/reference/otel-instrumentation.md)、[eve 的协议机制](adapters/reference/eve-protocol.md)、[Claude Code 自带 OTel 遥测能不能提前拿结果](adapters/reference/claude-code-otel-telemetry.md)。
 

package/docs/adapters/collection.md

@@ -46,7 +46,7 @@
 | **usage** | assistant 行 `message.usage`(含 cache read) | 防御式多路径:`data/payload/item/turn/response.usage`,兼容 `input/output_tokens` 与 `prompt/completion_tokens` 两套命名 | `event(name=="run")` 的 `data.usage`(`prompt/completion_tokens`,**`cost` 直接有**) |
 | **session id(resume 用)** | transcript 首个 `sessionId` 字段(`shared.sessionIdFromClaudeTranscript`) | `thread.started.thread_id`(`shared.codexThreadId`) | tape 文件名含 session hash;adapter 自管 |
 | **实际模型** | transcript 行内有 | 网关场景要第二通道读 `~/.codex/sessions` 的 `turn_context.payload.model`(agent-eval 的做法;niceeval 未接,记为已知缺口) | tape 内 run 事件 |
-| **时间轨** | 稳定态无 OTel;有 beta 版原生 OTLP trace 导出(`CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1` 等一串 env,内容默认脱敏,详见 [reference/claude-code-otel-telemetry.md](reference/claude-code-otel-telemetry.md))→ 目前仍用 transcript 时间戳合成 span | 原生 OTLP/JSON(`config.toml [otel]`,走 `tracing.configure`) | 原生 OTLP/protobuf(env-based `OTEL_*`,走 `tracing.env`) |
+| **时间轨** | beta 版原生 OTLP trace 导出,已接进 adapter 的 `tracing.env`(`CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1` 等一串 env;span 只有结构与计时、内容默认脱敏,内容仍由 transcript 旁读补全,详见 [reference/claude-code-otel-telemetry.md](reference/claude-code-otel-telemetry.md)) | 原生 OTLP/JSON(`config.toml [otel]`,走 `tracing.configure`) | 原生 OTLP/protobuf(env-based `OTEL_*`,走 `tracing.env`) |
 
 remote agent(通道 0)不在表里——它没有"采集",字段来源就是你自己代码里的返回值,见下节示例。
 

package/docs/adapters/contract.md

@@ -72,10 +72,10 @@ interface AgentSession {
 | `t.respond()` / `t.parked()` 等 HITL | send 返回过 `"waiting"` + `input.requested` 事件——做到了就是有 |
 | `t.calledTool()` / `t.toolOrder()` 等正断言 | events 里有 `action.*` |
 | `t.notCalledTool()` / `t.usedNoTools()` 等负断言**可信** | 事件来自带完整性证明的官方转换器(SDK 原生事件流透传、`fromAiSdk` 的 `result.steps`、Responses 的 `output`);手写映射没有这份证明,负断言可信度按来源判断,不按作者的自觉 |
-| `t.sandbox`、`t.fileChanged()` 等 | `defineSandboxAgent` 构造(`kind: "sandbox"`) |
+| `t.sandbox`、`t.sandbox.fileChanged()` 等 | `defineSandboxAgent` 构造(`kind: "sandbox"`) |
 | `EvalResult.trace`、`niceeval view` 瀑布图 | 配置了 OTel 接入(agent 的 `tracing` 块,或 remote agent + `defineConfig({ telemetry })`)——只画瀑布图,不影响任何断言,详见[观测性](../observability.md#otlp-traces--统一瀑布图) |
 
-唯一仍然存在的运行时守卫是**沙箱能力**:`t.sandbox` / `t.file` / `t.fileChanged()` 等直接读沙箱文件系统,非沙箱型 agent(`kind !== "sandbox"`)调用这些方法会立即得到清晰报错(`src/context/context.ts` 的 `capabilityGuard`)——没有沙箱就没有东西可读,不报错会静默返回空结果。其余能力(多轮对话、工具观测……)不设运行时守卫:没接会话存取器的 agent 每轮各是新对话(不报错,只是断言看不到历史);没吐 `action.*` 事件的 agent 上正断言自然不命中;负断言的可信度靠事件来源判断,不靠拦截调用。
+唯一仍然存在的运行时守卫是**沙箱能力**:`t.sandbox` / `t.sandbox.file()` / `t.sandbox.fileChanged()` 等直接读沙箱文件系统,非沙箱型 agent(`kind !== "sandbox"`)调用这些方法会立即得到清晰报错(`src/context/context.ts` 的 `capabilityGuard`)——没有沙箱就没有东西可读,不报错会静默返回空结果。其余能力(多轮对话、工具观测……)不设运行时守卫:没接会话存取器的 agent 每轮各是新对话(不报错,只是断言看不到历史);没吐 `action.*` 事件的 agent 上正断言自然不命中;负断言的可信度靠事件来源判断,不靠拦截调用。
 
 ## 标准事件流
 
@@ -182,7 +182,7 @@ interface InputRequest {
 
 | 断言族 | 读什么 | adapter 义务 | 数据缺失时 |
 |---|---|---|---|
-| `succeeded()` / `parked()` / `turn.expectOk()` | `Turn.status` + 事件流(`parked` 看最后有意义事件是否 `input.requested`) | `status` 如实;HITL 停留吐 `input.requested` | `status` 恒 completed → `succeeded` **假通过(静默)** |
+| `succeeded()` / `parked()` | `Turn.status` + 事件流(`parked` 看最后有意义事件是否 `input.requested`) | `status` 如实;HITL 停留吐 `input.requested` | `status` 恒 completed → `succeeded` **假通过(静默)** |
 | `messageIncludes()` / `t.reply` / `turn.message` | `message` 且 `role: "assistant"` 的事件文本 | 每段助手文本吐一条 `message`(工具结果**不是**助手消息,别混,见[参考笔记的踩坑记录](reference/agent-eval.md#claude-code-怎么转换)) | 断言 fail(响) |
 | `outputEquals()` / `outputMatches()` | `turn.data` | 结构化输出放 `data`,不要序列化塞进 `events` | fail(响) |
 | `calledTool()` / `toolOrder()` / `loadedSkill()` / `calledSubagent()` | 派生 `toolCalls` / `subagentCalls` | 每次调用吐 `called` + `result`(callId 配对);`name` 原始名 + `tool` 规范名;result `status` 如实 | fail(响) |
@@ -230,10 +230,11 @@ t.succeeded()                        ✓
 | 鉴权(API key / token / base url) | **agent 本地** —— 它怎么连自己,是私事 | 在定义里读 env / 闭包,不经 ctx |
 | CLI 细节(装什么包、参数形状、transcript 在哪) | **agent 本地** | 写死在 `send` / `setup` 里 |
 | **model** | **实验决定(留空)** | `ctx.model`(省略 → agent 原生默认) |
-| **feature flags**(webResearch、注入哪个 skill、effort…) | **实验决定** | `ctx.flags.*` —— agent 的 `send` 与 eval 的 `t.flags` 都能读 |
+| **reasoningEffort** | **实验决定(留空)** | `ctx.reasoningEffort`(省略 → agent 原生默认) |
+| **feature flags**(webResearch、注入哪个 skill…) | **实验决定** | `ctx.flags.*` —— agent 的 `send` 与 eval 的 `t.flags` 都能读 |
 | runs / earlyExit / evals / sandbox / budget | **实验决定** | 运行器据此调度 |
 
-一句话:**agent 只配「怎么连我自己」,不配「跑哪个模型、开哪些开关」**;后者全留给 [experiment](../experiments.md),经 `ctx`(eval 里是 `t`)透传。这样同一个 agent 能被不同实验以不同 model / flags 复用,不必改 agent。
+一句话:**agent 只配「怎么连我自己」,不配「跑哪个模型、开哪些开关」**;后者全留给 [experiment](../experiments.md),经 `ctx`(eval 里是 `t`)透传。这样同一个 agent 能被不同实验以不同 model / reasoningEffort / flags 复用,不必改 agent。
 
 ## `ctx`(agent 侧)与 `t`(eval 侧):同一份东西,两个名字
 

package/docs/adapters/reference/claude-code-otel-telemetry.md

@@ -79,7 +79,7 @@ OTEL_TRACES_EXPORT_INTERVAL=1000                      # 拉到近实时,eval 场
 
 ## 跟现有采集矩阵的关系
 
-[采集设计](../collection.md#采集矩阵现状与-src-对齐)那张表里"时间轨"一行,claude-code 当前写的是"无原生 OTel → transcript 时间戳合成 span"——**这句话需要更新**:Claude Code 现在有原生 OTel trace 导出,只是处于 beta、默认关、内容默认脱敏。准确说法应该是"有 beta 版原生 OTLP trace 导出(需要一串 env 才能打开、且默认无内容),目前 niceeval 仍选择更省事、内容更全的 transcript 时间戳合成方案"。
+**已落地(2026-07)**:下文"升级档"描述的接线已经实现——`claudeCodeAgent` 的 `tracing.env` 注入本页这组 env,与 bub/codex 一样默认开启(见 `src/agents/claude-code.ts`),[采集矩阵](../collection.md#采集矩阵现状与-src-对齐)的时间轨一行已同步。span 只有结构与计时(未开内容 flag),行为轨与断言仍走 transcript 旁读,与下文结论一致。
 
 ## 结论:这条路径值不值得接
 

package/docs/architecture.md

@@ -7,26 +7,26 @@ niceeval 把一个评测过程拆成四段职责:**发现**要跑什么、**驱
 ## 系统总览
 
 ```text
-                          ┌──────────────────────────── core ────────────────────────────┐
-  evals/                  │                                                               │
-  └─ *.eval.ts ──────────►│  Discovery ──► Runner ──► Scoring ──► Outcome ──► Reporters    │
-                          │   (发现)       (调度)     (评分)      (判决)      (报告)         │
-                          │                  │ 驱动                              │          │
-                          └──────────────────┼──────────────────────────────────┼──────────┘
-                                             │                                  ▼
-                                             ▼  对接口分发,不按名字分支    .niceeval/<run>/
-                          ┌──────────── Agent(自实现 Adapter)────────────┐
-                          │        远程 adapter          沙箱 adapter      │
-                          │        (你的服务)          ┌─────┴─────┐      │
-                          │                            │ claude-code│      │
-                          │                            │ codex / bub│      │
-                          │                            └─────┬──────┘     │
-                          │                                  ▼            │
-                          │                            ┌── Sandbox ──┐    │
-                          │                            │ docker      │    │
-                          │                            │ vercel / 三方│    │
-                          │                            └─────────────┘    │
-                          └────────────────────────────────────────────────┘
+                          ┌─────────────────────────── core ───────────────────────────┐
+  evals/                  │                                                            │
+  └─ *.eval.ts ──────────►│ Discovery ──► Runner ──► Scoring ──► Outcome ──► Reporters │
+                          │  (发现)       (调度)     (评分)      (判决)       (报告)   │
+                          │              │ 驱动                             │          │
+                          └──────────────┼──────────────────────────────────┼──────────┘
+                                         │                                  ▼
+                                         ▼  对接口分发,不按名字分支    .niceeval/<run>/
+                          ┌────── Agent(自实现 Adapter) ──────┐
+                          │   远程 adapter    沙箱 adapter    │
+                          │    (你的服务)   ┌───────────────┐ │
+                          │                 │  claude-code  │ │
+                          │                 │  codex / bub  │ │
+                          │                 └───────────────┘ │
+                          │                         ▼         │
+                          │                 ┌─── Sandbox ───┐ │
+                          │                 │    docker     │ │
+                          │                 │ vercel / 三方 │ │
+                          │                 └───────────────┘ │
+                          └───────────────────────────────────┘
 ```
 
 四段职责是**单向数据流**:发现产出一批 `Eval`,运行器逐个对 Agent `send` 得到 `Turn`,评分器把 `Turn` 折叠成 `Assertion[]`,再把全部断言折叠成一个互斥的 `Outcome`;报告器消费 `Outcome` + 工件。没有反向耦合 —— 评分器不知道 agent 的 transport 是 HTTP 还是沙箱 CLI,它只看 `Turn`。

package/docs/assertions.md

@@ -158,7 +158,6 @@ export default defineEval({
 | `t` | `check` / `require` / `skip` / `log` | 记录 eval run 级断言或控制流,不属于某个 session / turn |
 | `t` | `newSession()` | 只有 run 主上下文负责创建额外 session |
 | `t` | `sandbox.*` | 沙箱是 attempt / run 资源,不是某条会话或某一轮的资源 |
-| `turn` | `expectOk()` | 只对一次 `send` 的返回状态有意义 |
 | `turn` | `outputEquals(value)` / `outputMatches(schema)` | 只对这一轮的 `turn.data` 有意义 |
 
 ### 值级断言

package/docs/capabilities-by-construction.md

@@ -8,7 +8,7 @@
 
 | 能力 | 证据 | 用户要写什么 |
 |---|---|---|
-| `t.sandbox`、`t.fileChanged()` 等文件系统断言 | `defineSandboxAgent` 构造(`kind: "sandbox"`) | 无——`defineAgent` 构造的 agent(`kind: "remote"`)调用这些方法会立即得到清晰报错,这是唯一仍需要运行时守卫的能力(`src/context/context.ts` 的 `capabilityGuard`) |
+| `t.sandbox`、`t.sandbox.fileChanged()` 等文件系统断言 | `defineSandboxAgent` 构造(`kind: "sandbox"`) | 无——`defineAgent` 构造的 agent(`kind: "remote"`)调用这些方法会立即得到清晰报错,这是唯一仍需要运行时守卫的能力(`src/context/context.ts` 的 `capabilityGuard`) |
 | 多次 `t.send()`、`t.reply`、`t.newSession()` | `send` 里接了 `ctx.session` 的续接存取器(`history<TMsg>()` 或 `id` + `capture(id)`) | 无——没接就每轮各是新对话,不报错,只是断言看不到跨轮历史 |
 | `t.calledTool()` 等正断言 | `send` 返回的 events 里有 `action.*` | 无——有事件就能断,没有就是断言 fail(响,不静默) |
 | `t.notCalledTool()` / `usedNoTools()` 等负断言的**可信度** | 事件来源是否有完整性契约(SDK 原生事件流透传、`fromAiSdk` 的 `result.steps`、Responses 的 `output`) | 无——但手写映射时如果知道自己漏了工具层,应在 eval README 里如实说明这条 eval 的负断言不可信,而不是假装它和正断言一样可靠 |
@@ -38,7 +38,7 @@ export default defineAgent({
 ## 边界
 
 - **默认值问题已经不存在。** 提案担心的"`defineAgent` 默认给 `conversation: true, toolObservability: true`,教程第一步要写一行反悔"——这个问题连同整个 `capabilities` 字段一起消失了,不需要保留"opt-out 默认值"这个概念。
-- **`workspace` 对远程 agent 依然不放开。** 文件系统断言(`t.sandbox`、`t.fileChanged()`)只在 `kind: "sandbox"` 上解锁,远程 agent 即便自己改了文件,也没有 sandbox 提供的 diff 基线,这条边界和提案设想的一致。
+- **`workspace` 对远程 agent 依然不放开。** 文件系统断言(`t.sandbox`、`t.sandbox.fileChanged()`)只在 `kind: "sandbox"` 上解锁,远程 agent 即便自己改了文件,也没有 sandbox 提供的 diff 基线,这条边界和提案设想的一致。
 - **`t.newSession()` 在没有接会话续接存取器时依然可以调用。** 新会话线的第一轮就是存取器的自然空态,不需要判断"这个 agent 支不支持多轮"。
 
 ## 相关阅读

package/docs/cli.md

@@ -58,7 +58,7 @@ niceeval exp compare --no-early-exit          # 关掉,要完整通过率分布
 niceeval exp compare --max-concurrency <n>    # 并发上限
 niceeval exp compare --timeout <ms>           # 单 eval 超时
 niceeval exp compare --force                  # 忽略指纹缓存,全量重跑
-niceeval exp compare --tag <tag>              # 按标签过滤(可重复)
+niceeval exp compare --tag <tag>              # 按单个标签过滤
 ```
 
 ## 评分与退出
@@ -81,7 +81,7 @@ niceeval view                         # 起本地 web,自动打开浏览器,读
 niceeval view .niceeval/<run>/summary.json
 niceeval view --port 4317             # 固定端口;被占用时向后找可用端口
 niceeval view --no-open               # 只启动服务并打印 URL(适合远端 shell / CI)
-niceeval view --out .niceeval/report.html  # 导出静态 HTML,不启动服务
+niceeval view --out site              # 目录式静态导出,不启动服务(index.html + 查看器工件)
 niceeval clean                        # 清掉这些历史运行结果
 ```
 

package/docs/concepts.md

@@ -40,7 +40,7 @@
 
 **Integration tier** / **接入 Tier** —— 按「Adapter 接到哪里、额外拿到什么观测数据」给接入方式分的三档(和下面的**模型档**是两回事,后者说的是给 agent 指定哪个模型)。**Tier 1(只接 send)**:应用代码一行不改——adapter 适配应用现有对外接口实现 `send`,靠手写事件映射或官方转换器拿到工具断言;应用接口本身暴露模型选择的话,**模型对比**类 [Experiment](#experiment) 也在这一档(`model` 经 `ctx.model` 透传)。**Tier 2(send + OTel)**:还是同一个 `send`,事件来源换成应用发给 niceeval 的 OTel span(应用已埋点则零代码,未埋点补一段通用 OTel 初始化)——买到的是观测质量的跃升:事件流免手写映射、负断言带完整性证明、trace 瀑布图。**Tier 3(侵入改造 + experiment flags)**:改应用内部代码,把内部可变点(prompt、工具集、feature flag)暴露成 experiment 可选的配置(经 `flags` → `ctx.flags` 透传),解锁**完整的 feature A/B test**——对照的不再只是模型,而是应用内部的功能变体。前两档都是**无侵入**的:应用按自己的方式启动,eval 侧不 spawn 应用进程、不另开端口,Adapter 只对着用户前端本来就在用的那个接口收发。三档递进不互斥,详见 [docs-site · Tier](../docs-site/zh/concepts/tier.mdx)。
 
-**Model tier** / **模型档** —— 给 agent 指定模型的标识(如 `opus`、`vendor/model?reasoningEffort=high`)。由 [Experiment](#experiment) 的 `model` 字段指定;省略则用 agent 原生默认,不经额外的策略层决定。
+**Model tier** / **模型档** —— 给 agent 指定模型的标识(如 `opus`)。由 [Experiment](#experiment) 的 `model` 字段指定;省略则用 agent 原生默认,不经额外的策略层决定。推理努力程度(如 `low`/`medium`/`high`,取值由具体模型定义)是独立的 `reasoningEffort` 字段,经 `ctx.reasoningEffort`/`t.reasoningEffort` 透传,归属与 `model` 一致——都是实验决定、agent 留空。
 
 ## 数据集与发现
 
@@ -62,7 +62,7 @@
 
 **Session** —— 一条会话线。`t` 驱动主 session;`t.newSession()` 返回独立 session,用于并行或隔离的多会话测试。`session.*` 作用域断言只看这条 session 已经发生的事件;这些事件仍会汇入 `t.*` run 级断言。
 
-**Turn** —— `t.send()` 的一次返回值,对应这一轮的标准事件流片段。带 `message` / `data` / `toolCalls` / `status` / `usage` / `events` 等只读字段,以及 `expectOk()` 和一套与 `t` 同名的作用域断言(`turn.calledTool`/`turn.succeeded`/…),作用域收窄成只看这一轮,详见 [Assertions](assertions.md#作用域规则)。
+**Turn** —— `t.send()` 的一次返回值,对应这一轮的标准事件流片段。带 `message` / `data` / `toolCalls` / `status` / `usage` / `events` 等只读字段,以及一套与 `t` 同名的作用域断言(`turn.calledTool`/`turn.succeeded`/…),作用域收窄成只看这一轮,详见 [Assertions](assertions.md#作用域规则)。
 
 **EarlyExit** / **早停** —— 一个 eval 取通过率时,先过一次即中止其余 attempt 的策略(可关)。