niceeval 0.4.6 → 0.5.1

package/docs-site/zh/guides/viewing-results.mdx

@@ -1,10 +1,10 @@
 ---
 title: "查看 NiceEval 结果并调试 agent 行为"
 sidebarTitle: "查看结果"
-description: "NiceEval 每次运行后会在 .niceeval/ 写入结构化 artifacts。用 npx niceeval view 查看 transcript、diff、event stream 和 pass rate。"
+description: "每次运行写入 .niceeval/ 的结构化工件有两扇门：niceeval show 在终端逐级下钻榜单、断言、transcript、trace 与 diff；niceeval view 在网页看同一份证据。"
 ---
 
-每次运行后，[NiceEval](https://niceeval.com/) 都会把结构化结果写入 `.niceeval/<timestamp>/`。控制台提供即时反馈，结果查看器用于深入分析失败原因。
+每次运行后，[NiceEval](https://niceeval.com/) 都会把结构化结果写入 `.niceeval/<timestamp>/`。看结果有两扇门，读的是同一批工件：`niceeval show` 是终端读法，人和 coding agent 都能用；`niceeval view` 是网页读法，适合人浏览证据。show 就是 view 的终端版，两处读到的判决口径不分叉。
 
 ## 控制台输出
 
@@ -16,10 +16,16 @@ Discovered 3 evals
   ✗ api-validation (38s)
     - gate: expected src/routes/users.ts to include .safeParse() [FAILED]
 
-Results:  2 passed, 1 failed, 0 errored, 0 skipped
+Failing:
+  ✗ api-validation
+      gate fileIncludes("src/routes/users.ts", ".safeParse()")
+      → niceeval show api-validation
+
+Results: 2 passed, 1 failed, 0 errored, 0 skipped
+Structured results: .niceeval/2026-07-09T10-00-00-000Z/summary.json
 ```
 
-每行包含 eval ID、outcome 和耗时。失败项会显示断言类型和错误信息。
+运行中每个 eval 一条流式行，失败断言内联展开；运行结束的收尾块把失败集中重放一遍，每条自带下钻命令，末尾是结构化结果入口。这段输出怎么进「跑→读→修→再跑」的循环，见 [Agent 反馈闭环](/zh/guides/agent-feedback-loop)。
 
 ## `.niceeval/<timestamp>/`
 
@@ -38,7 +44,130 @@ Results:  2 passed, 1 failed, 0 errored, 0 skipped
          └─ diff.json
 ```
 
-## `niceeval view`
+## `niceeval show`：终端下钻
+
+`niceeval show` 的位置参数与 `exp` 同一语义——eval id 前缀选「看哪些 eval」；flag 选「看哪个切面」：
+
+```bash
+niceeval show                       # 榜单：每个 experiment 的通过率、成本、耗时与失败清单
+niceeval show weather               # 前缀过滤：weather/* 下每个 eval 的判决
+niceeval show weather/brooklyn      # 单个 eval：各 experiment 的 attempt、断言明细、错误与用量
+niceeval show weather/brooklyn --transcript   # agent 的完整对话与工具调用
+niceeval show weather/brooklyn --trace        # trace 瀑布的文本版
+niceeval show fixtures/button --diff          # sandbox 里的文件改动
+niceeval show weather/brooklyn --history      # 跨 run 时间轴：抖动与回归拐点
+```
+
+同一个实验多次跑会留下多份结果，默认视图只回答一个问题——「现在什么水位」：每个 experiment × eval 取时间上最新的那份判决，跨 run 合成。按前缀只重跑了部分 eval 时，其余 eval 的判决从更早的 run 补齐，榜单永远是全局水位，不会因为一次局部重跑变残缺。合成是有标注的：每行带判决产生的时间，榜单头写明合成自几个 run。合成状态可能混着不同版本的被测代码——所以收工判决以 `--force` 全量重跑为准，迭代途中的 `show` 负责快、收尾的全量跑负责真。
+
+多 experiment、多 attempt 时，证据切面默认挑最新一次失败的 attempt；用 `--experiment` 与 `--attempt` 指定其它，用 `--run <目录>` 钉死看某一次历史 run，用 `--history` 看跨 run 趋势（见下文）。默认榜单只是报告槽的出厂填充：`--report <文件>` 可以把它整槽换成你自己的口径，同一个文件也能喂给 `view`，见[自定义报告](/zh/guides/custom-reports)。位置前缀、`--run`、`--experiment` 对 `--report` 同样生效（收窄报告拿到的选集）；`--history` 与 `--report` 互斥，证据切面 flag 出现时走证据室、不渲染报告槽。
+
+`niceeval view` 的每个视图都有 CLI 对应物：
+
+| `niceeval view` 里的视图 | 终端对应 |
+| --- | --- |
+| Experiments 榜单 | `niceeval show` |
+| attempt 详情（断言、错误、用量） | `niceeval show <eval id>` |
+| transcript | `niceeval show <eval id> --transcript` |
+| trace 瀑布图 | `niceeval show <eval id> --trace` |
+| 文件改动 | `niceeval show <eval id> --diff` |
+| 历史 run 列表 | `niceeval show <eval id> --history`；钉死某一次用 `--run <目录>` |
+| 质量 × 成本散点图 | `niceeval show` 榜单的 pass / cost 列已含同一份数据；要图形化口径，用 `MetricScatter` 积木写[自定义报告](/zh/guides/custom-reports) |
+
+### 榜单
+
+```text
+$ niceeval show
+Current verdicts · 2 experiments · composed from 3 runs · latest 2026-07-09T10-00-00-000Z
+
+experiment              evals    pass   cost    duration
+compare/bub-gpt-5.4     13/15    87%    $0.42   4m 12s
+compare/codex-gpt-5.4   12/15    80%    $0.51   5m 03s
+
+Failing:
+  ✗ weather/brooklyn   compare/codex-gpt-5.4   gate calledTool("get_weather")      41s ago
+  ✗ fixtures/button    compare/bub-gpt-5.4     gate fileChanged("src/components/Button.tsx")   2h ago
+```
+
+跑多 experiment 的组时，`niceeval exp` 收尾块里的汇总表就是这个形状——同一份表格渲染，判决折叠口径也相同；区别只在数据范围：收尾块只汇总本次 run，`show` 榜单是跨 run 合成的现刻水位，各自在表头如实标注。
+
+### 单个 eval
+
+```text
+$ niceeval show weather/brooklyn
+weather/brooklyn — 布鲁克林天气查询
+
+compare/bub-gpt-5.4     ✓ passed   1 attempt    38s   $0.03   (2h ago)
+compare/codex-gpt-5.4   ✗ failed   3 attempts   41s   $0.04   (just now)
+
+attempt 3 · compare/codex-gpt-5.4 · failed · 41s · 12.3k tokens · $0.04
+  ✗ gate calledTool("get_weather") — tool was never called
+  ✓ gate succeeded()
+  ✗ soft judge("回答基于实时数据") — 0.2/1: reply invents a temperature without any tool call
+
+artifacts: .niceeval/2026-07-09T10-00-00-000Z/artifacts/compare__codex-gpt-5.4__weather__brooklyn__2/
+next: niceeval show weather/brooklyn --transcript | --trace | --diff
+```
+
+### transcript、trace 与 diff
+
+`--transcript` 把 `events.json` 渲染成逐轮对话，工具调用带出入参与耗时：
+
+```text
+$ niceeval show weather/brooklyn --transcript
+attempt 3 · compare/codex-gpt-5.4 · failed
+
+[user]      布鲁克林今天天气怎么样?
+[assistant] 布鲁克林今天大约 24°C，晴。
+
+(2 events · no tool calls · full stream: …/events.json)
+```
+
+`--trace` 把 `trace.json` 画成文本瀑布，span 类目与 web 版同一套标准化口径，不同 agent 的图天然可比：
+
+```text
+$ niceeval show weather/brooklyn --trace
+agent run                     ▕████████████████████▏ 41.2s
+├─ inference                  ▕█████░░░░░░░░░░░░░░░▏ 10.1s
+├─ inference                  ▕░░░░░█████████░░░░░░▏ 18.3s
+└─ inference                  ▕░░░░░░░░░░░░░░██████▏ 12.4s
+
+(3 spans · no execute_tool spans · full trace: …/trace.json)
+```
+
+`--diff` 默认给文件级摘要；看单个文件的完整改动用 `--diff=<文件路径>`——路径必须用 `=` 连写，位置参数永远留给 eval id 前缀：
+
+```text
+$ niceeval show fixtures/button --diff
+M src/components/Button.tsx   +42 −3
+A src/components/Button.css   +18
+
+(full diff: …/diff.json)
+$ niceeval show fixtures/button --diff=src/components/Button.tsx
+```
+
+三个切面对长内容都会截断，但截断永远如实标注剩余数量和原始工件路径——输出对上下文窗口友好，事实源一字不少地留在盘上。
+
+### 历史与抖动：`--history`
+
+榜单和单个 eval 视图回答「现在」；「这个 eval 稳不稳」「什么时候开始坏的」问的是趋势。`--history` 给跨 run 时间轴，每次真实执行一行：
+
+```text
+$ niceeval show weather/brooklyn --history
+compare/codex-gpt-5.4 · 5 runs · passed 2/5
+
+  2026-07-09T10-00   ✗ failed   3 attempts   $0.04   gate calledTool("get_weather")
+  2026-07-09T08-12   ✓ passed   1 attempt    $0.03
+  2026-07-08T18-22   ✗ failed   3 attempts   $0.05   gate calledTool("get_weather")
+  2026-07-08T11-05   ✓ passed   1 attempt    $0.03
+  2026-07-07T16-40   ✗ failed   3 attempts   $0.05   gate calledTool("get_weather")
+```
+
+✓✗ 交替说明这个 eval 在抖，该修的是稳定性（被测程序或断言），反复重跑碰运气只会烧钱；连续绿转红的拐点就是回归引入的位置，用 `--run <目录>` 钉住拐点前后两次细看。时间轴只列真实执行——缓存携带的旧结果是判决的复印件，不占行，否则趋势会被复印件灌满假数据。不带 eval id 的 `niceeval show --history` 给每个 experiment 的 per-run 通过率序列，同一份趋势的榜单视角。
+
+两次 run 的精确对比（这次修复具体翻转了哪些 eval）不做成 flag：用 `DeltaTable` 积木写一份报告递给 `--report`，几行就是一份自定义对比报告，终端和网页两扇门都认——内置命令只管固定摆法，自定义口径见[自定义报告](/zh/guides/custom-reports)。
+
+## `niceeval view`：网页证据室
 
 ```bash
 npx niceeval view
@@ -50,9 +179,11 @@ npx niceeval view
   失败后立刻运行 `npx niceeval view`，可以直接打开刚刚那次运行的 artifacts。
 </Tip>
 
+view 的结构是「报告槽 + 证据室」：报告槽默认装官方榜单，`--report <文件>` 整槽换成你自己的报告（与 `show --report` 吃同一个文件），见[自定义报告](/zh/guides/custom-reports)；证据室（attempt 弹窗、transcript、trace 瀑布）始终保留，报告里的数字点进去就是证据。
+
 ## 导出与静态托管
 
-发布结果只有一种导出：`--out <目录>` 整站导出，完整带上能查看的一切。想要自己的页面形态，再用报告积木自建。
+发布结果只有一种导出：`--out <目录>` 整站导出，完整带上能查看的一切。想要自己的页面形态，用报告积木自建（见[自定义报告](/zh/guides/custom-reports)）。
 
 ### 内置查看器整站：静态托管
 
@@ -69,86 +200,25 @@ NiceEval 写入 `<dir>/index.html`，并把查看器要读取的工件（`source
 - `diff.json` 和 `o11y.json` 不会被复制。查看器不读取它们，且 diff 可能达到上百 MB。
 - 用 `file://` 直接打开 `index.html` 时浏览器不允许 fetch 工件，代码视图会提示源码不可用。本地预览用 http 服务打开。
 
-最简单的流程是在跑过 eval 的机器上导出，把产物目录直接部署，不需要额外步骤。`.niceeval/` 通常不进版本库，如果构建发生在别的机器（CI、托管平台），先用 `copyRun` 把要发布的快照瘦身复制进仓库，再对着快照目录导出：
+最简单的流程是在跑过 eval 的机器上导出，把产物目录直接部署，不需要额外步骤。`.niceeval/` 通常不进版本库，如果构建发生在别的机器（CI、托管平台），先用 `copySnapshots` 把要发布的快照瘦身复制进仓库，再对着快照目录导出：
 
 ```typescript
 // scripts/snapshot.ts —— 跑完 eval 后执行，产物提交进仓库
-import { openResults, latestPerExperiment, copyRun } from "niceeval/results";
+import { openResults, copySnapshots } from "niceeval/results";
 
 const results = await openResults(".niceeval");
-const { snapshots } = latestPerExperiment(results.snapshots);
-await copyRun(snapshots, "site-data/run", {
+await copySnapshots(results.latest(), "site-data/run", {
   artifacts: ["sources", "events", "trace"],
 });
 ```
 
 ```bash
-npx niceeval view --out site site-data/run   # CI 上对着快照构建
+npx niceeval view --run site-data/run --out site   # CI 上对着快照构建
 ```
 
-`latestPerExperiment` 按 experiment 挑最新快照，而不是挑最新的 run——某次运行只跑了部分实验时，其它实验仍保留上一轮的结果。
-
-### 自建报告页：自己的看法
-
-内置查看器的榜单形态是固定的。想要自己的看法——考试成绩单、benchmark 榜、质量 × 成本散点——用报告积木搭进你自己的应用：`niceeval/results` 读结果，`niceeval/report` 算数据，`niceeval/report/react` 渲染组件。
-
-计算和渲染之间是一条可序列化边界：计算函数（`table()`、`scatter()`、`overview()` 等）读文件系统，只能跑在 Node（构建脚本、服务端、CI）；组件只认算好的 JSON 数据，零 IO，在哪都能渲染。静态发布因此有两种姿势。
+结果目录经 `--run` 递入，与 `show --run` 同一语义——位置参数永远留给 eval id 前缀。
 
-**姿势一：构建时算好，导出纯静态页。** 页面在能读到结果数据的机器上构建（Next.js RSC 或任何 SSG），产物就是普通静态文件：
-
-```tsx
-// app/evals/page.tsx
-import { openResults, latestPerExperiment } from "niceeval/results";
-import { table, passRate, costUSD } from "niceeval/report";
-import { MetricTable } from "niceeval/report/react";
-import "niceeval/report/react/styles.css";
-
-export default async function EvalsPage() {
-  const results = await openResults(".niceeval");
-  const { snapshots } = latestPerExperiment(results.snapshots);
-  const data = await table(snapshots, {
-    rows: "agent",
-    columns: [passRate, costUSD],
-    sort: passRate,
-  });
-  return <MetricTable data={data} />;
-}
-```
-
-**姿势二：CI 落 JSON，任意前端渲染。** 计算跑在出结果的地方，页面在哪都行（Vite SPA、已有的内部面板）：
-
-```typescript
-// scripts/build-report-data.ts —— CI 里跑完 eval 后执行
-import { writeFile } from "node:fs/promises";
-import { openResults, latestPerExperiment } from "niceeval/results";
-import { table, passRate, costUSD } from "niceeval/report";
-
-const results = await openResults(".niceeval");
-const { snapshots } = latestPerExperiment(results.snapshots);
-await writeFile("public/report.json", JSON.stringify({
-  board: await table(snapshots, { rows: "agent", columns: [passRate, costUSD] }),
-}));
-```
-
-```tsx
-// 前端：任何 React 应用
-import { MetricTable } from "niceeval/report/react";
-
-const doc = await fetch("/report.json").then((r) => r.json());
-
-<MetricTable data={doc.board} />;
-```
-
-组件不 hydrate 也完整：排序在数据侧预排、下钻是普通链接、展开折叠用 `<details>`，静态导出的产物不需要任何客户端 JS。样式随包发布（`niceeval/report/react/styles.css`），在其后加载自己的 CSS 即可覆盖。
-
-自建页负责结论，逐条 attempt 的 transcript 和 trace 不必自己画：把内置查看器一起导出到子路径（`npx niceeval view --out <站点目录>/evidence`），再用组件的 `attemptHref` 生成深链跳过去：
-
-```tsx
-<MetricTable
-  data={data}
-  attemptHref={(ref) => `/evidence/#/attempt/${encodeURIComponent(ref.run)}/${ref.result}`}
-/>
-```
+`results.latest()` 按实验挑最新快照，而不是挑最新的 run——某次运行只跑了部分实验时，其它实验仍保留上一轮的结果。
 
 ## Artifact 说明
 
@@ -189,7 +259,7 @@ Soft 断言的分数记录在 `assertions[].score` 里；非 `--strict` 模式
 
 ## 调试建议
 
-- 先看 `summary.json` 找到失败断言。
-- 再看 transcript 视图，了解 agent 的决策过程。
-- coding-agent 失败时看 `diff.json` 和命令事件输出。
-- 工具调用问题看 `events.json`。
+- 收尾块的失败清单每条自带下钻命令：`niceeval show <eval id>` 先看断言明细。
+- 想知道 agent 为什么这么做，看 `--transcript`（或 view 的 transcript 视图）了解决策过程。
+- coding-agent 失败时看 `--diff` 和命令事件输出；工具调用问题看 `--trace` 与 `events.json`。
+- 判断缺陷在被测程序还是 eval 本身、修完怎么重跑，流程见 [Agent 反馈闭环](/zh/guides/agent-feedback-loop)。

package/docs-site/zh/guides/write-experiment.mdx

@@ -1,10 +1,10 @@
 ---
 title: "写实验：用 defineExperiment 固定运行配置"
 sidebarTitle: "写实验"
-description: "学习如何在 experiments/ 里用 defineExperiment 选择 agent、传 model 和 flags、设置 runs、预算、并发与 sandbox。"
+description: "学习如何在 experiments/ 里用 defineExperiment 选择 agent、传 model 和 params、设置 runs、预算、并发与 sandbox。"
 ---
 
-Experiment 是可签入的运行配置：同一批 eval 对着哪个 adapter、哪个模型、哪些 feature flags、跑几次、预算多少，都写在 `experiments/` 里。CLI 的位置参数只负责筛 eval，不负责临时改 agent 或运行配置。
+Experiment 是可签入的运行配置：同一批 eval 对着哪个 adapter、哪个模型、哪些参数、跑几次、预算多少，都写在 `experiments/` 里。CLI 的位置参数只负责筛 eval，不负责临时改 agent 或运行配置。
 
 ## 最小实验
 
@@ -20,7 +20,7 @@ export default defineExperiment({
 
 `agent` 放的是已经配置好的 agent 实例。被测系统的 URL、鉴权、协议细节通常传给 adapter 工厂；运行器不会单独保存一个 `agentConfig` 字段。
 
-## 传 model 和 flags
+## 传 model 和 params
 
 ```ts
 // experiments/concise.ts
@@ -34,7 +34,7 @@ export default defineExperiment({
     apiKey: process.env.STAGING_AGENT_API_KEY,
   }),
   model: "gpt-5.4",
-  flags: {
+  params: {
     promptVariant: "concise",
     webResearch: false,
   },
@@ -46,7 +46,7 @@ export default defineExperiment({
 
 `model` 会作为 `ctx.model` 传给 adapter；应用接口支持模型选择时，adapter 把它放进请求体、header 或 CLI 参数即可。
 
-`flags` 会作为 `ctx.flags` 传给 adapter，也会作为 `t.flags` 出现在 eval 里。它适合表达 experiment 维度的 feature 开关，例如 prompt 版本、工具集、检索开关。真正按 flag 切换行为的是你的应用或 adapter，[NiceEval](https://niceeval.com/) 只负责原样透传。
+`params` 会作为 `ctx.params` 传给 adapter，也会作为 `t.params` 出现在 eval 里。它适合表达 experiment 维度的 feature 开关，例如 prompt 版本、工具集、检索开关。真正按参数切换行为的是你的应用或 adapter，[NiceEval](https://niceeval.com/) 只负责原样透传。
 
 ```ts
 // agents/web-agent.ts
@@ -57,7 +57,7 @@ async send(input, ctx) {
     body: JSON.stringify({
       message: input.text,
       model: ctx.model,
-      flags: ctx.flags,
+      params: ctx.params,
     }),
     signal: ctx.signal,
   });
@@ -66,7 +66,7 @@ async send(input, ctx) {
 
 ## 一组实验怎么写
 
-一个实验文件是一格配置。要比较多个模型、agent 或 flags，就把多个文件放进同一个文件夹：
+一个实验文件是一格配置。要比较多个模型、agent 或 params，就把多个文件放进同一个文件夹：
 
 ```text
 experiments/
@@ -89,7 +89,7 @@ npx niceeval exp prompt-variants
 | `agent` | 选择并配置 adapter；必填 |
 | `model` | 单个模型名，经 `ctx.model` 透传 |
 | `reasoningEffort` | 单个推理努力程度（如 `"high"`），经 `ctx.reasoningEffort` / `t.reasoningEffort` 透传，归属与 `model` 一致 |
-| `flags` | 任意 JSON 对象，经 `ctx.flags` / `t.flags` 透传 |
+| `params` | 任意 JSON 对象，经 `ctx.params` / `t.params` 透传 |
 | `runs` | 每个 eval × 配置最多跑几次 |
 | `earlyExit` | 多次运行里通过一次就提前停止 |
 | `evals` | 限定这一格配置跑哪些 eval |
@@ -98,4 +98,4 @@ npx niceeval exp prompt-variants
 | `maxConcurrency` | 这一格配置的并发上限 |
 | `sandbox` | sandbox agent 使用的后端，如 `dockerSandbox()` / `e2bSandbox()` |
 
-跨配置比较的设计建议见[实验矩阵](/zh/guides/experiments)。adapter 如何消费 `ctx.model` 和 `ctx.flags` 见[Adapter](/zh/concepts/adapter)。
+跨配置比较的设计建议见[实验矩阵](/zh/guides/experiments)。adapter 如何消费 `ctx.model` 和 `ctx.params` 见[Adapter](/zh/concepts/adapter)。

package/docs-site/zh/guides/write-send.mdx

@@ -1,7 +1,7 @@
 ---
 title: "如何写好 Send"
 sidebarTitle: "如何写好 Send"
-description: "手写 Adapter 的 send 函数，一条主线七步走：发消息拿回复、接上之前的消息、记录消费、把工具解析成事件、人工介入（HITL）、接上 OTel trace、透传 experiment 的 flags。每一步只在上一步的代码上多几行，每一步解锁一组断言。"
+description: "手写 Adapter 的 send 函数，一条主线七步走：发消息拿回复、接上之前的消息、记录消费、把工具解析成事件、人工介入（HITL）、接上 OTel trace、透传 experiment 的 params。每一步只在上一步的代码上多几行，每一步解锁一组断言。"
 ---
 
 [Adapter](/zh/concepts/adapter) 讲了契约：`send` 传入 `TurnInput` 和 `AgentContext`，返回 `Turn`。这一页讲怎么写它——从"发一条消息拿到回复"的最小形态起步，一步一步加到完整接入。每一步只在上一步的代码上多几行，前面已有的部分在代码里用 `// ……省略` 标出；每一步末尾说明这几行解锁了哪些断言。改完任何一步都能立刻验证：把新解锁的断言写进一条 eval 重跑 `npx niceeval exp`，`niceeval view` 里能看到这一步新增的数据——多轮轨迹、用量、工具事件、待回答请求。
@@ -303,16 +303,16 @@ OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318/v1/traces node server.js
 
 **这一步解锁**：`niceeval view` 里的调用瀑布图——应用内部每次模型调用、每次工具执行的耗时与 token，按轮铺成时间线。断言不变：判决依据在前几步的事件映射里已经齐了，span 只进瀑布图、不喂断言。接收器怎么起、span 怎么归属到轮，见 [OTel 接入](/zh/guides/connect-otel)。
 
-## 第七步：透传 experiment 的 flags（A/B 对比）
+## 第七步：透传 experiment 的 params（A/B 对比）
 
-应用把变体暴露成可切换的配置后，experiment 声明 `flags`，运行器每轮经 `ctx.flags` 原样递给 `send`；Adapter 不解释它们的含义，只随请求转发——应用按 flag 切换变体：
+应用把变体暴露成可切换的配置后，experiment 声明 `params`，运行器每轮经 `ctx.params` 原样递给 `send`；Adapter 不解释它们的含义，只随请求转发——应用按参数切换变体：
 
 ```ts
       // ……send 其余部分同前，省略
       body: JSON.stringify({
         messages,
         model: ctx.model,        // ← 第一步就转发的 experiment.model；这里一起列出
-        flags: ctx.flags,        // ← experiment.flags 原样透传；没配时是 {}
+        params: ctx.params,      // ← experiment.params 原样透传；没配时是 {}
       }),
 ```
 
@@ -324,11 +324,11 @@ import chatApp from "../agents/chat-app.ts";
 export default defineExperiment({
   agent: chatApp,
   model: "gpt-5.4",                      // ← 经 ctx.model 到 send
-  flags: { promptVariant: "concise" },   // ← 每轮经 ctx.flags 到 send
+  params: { promptVariant: "concise" },  // ← 每轮经 ctx.params 到 send
 });
 ```
 
-两个 experiment 文件各声明一份 `flags`，`npx niceeval exp` 分别跑同一批 eval，就是一组 A/B 对比。这是三档接入里的 Tier 3（要求应用配合暴露开关），投入与回报见 [Tier](/zh/concepts/tier)；`flags` 与 `model`、`runs` 等其余 experiment 字段见[写实验](/zh/guides/write-experiment)。
+两个 experiment 文件各声明一份 `params`，`npx niceeval exp` 分别跑同一批 eval，就是一组 A/B 对比。这是三档接入里的 Tier 3（要求应用配合暴露开关），投入与回报见 [Tier](/zh/concepts/tier)；`params` 与 `model`、`runs` 等其余 experiment 字段见[写实验](/zh/guides/write-experiment)。
 
 **这一步解锁**：同一批 eval 跨变体的成绩对比。
 

package/docs-site/zh/index.mdx

@@ -87,7 +87,7 @@ eval 运行完成后，[NiceEval](https://niceeval.com/) 会生成易读报告
 | 概念 | 一句话 |
 |---|---|
 | [Eval](/zh/concepts/evals) | 一个测试用例：写在 `evals/*.eval.ts` 里，描述测什么。 |
-| [Experiment](/zh/concepts/experiment) | 可签入的运行配置：决定连哪个 Adapter、什么 model、什么 flags。 |
+| [Experiment](/zh/concepts/experiment) | 可签入的运行配置：决定连哪个 Adapter、什么 model、什么 params。 |
 | [Adapter](/zh/concepts/adapter) | 连接被测系统的适配层：实现一个 `send`，把返回翻译成标准事件流。 |
 | [Sandbox](/zh/guides/sandbox-backends) | 需要隔离工作区的 coding agent 才用得到；直连 Web Agent 不需要。 |
 | [Tier](/zh/concepts/tier) | 接入 Adapter 的三档投入：Tier 1 只接 send，Tier 2 加 OTel 换调用瀑布图，Tier 3 侵入改造做 feature A/B。 |

package/docs-site/zh/introduction.mdx

@@ -114,7 +114,7 @@ NiceEval 是一个 Agent-Native 的评估工具。Dataset / golden 那一套「
 | 概念 | 一句话 |
 |---|---|
 | Eval | 一个测试用例：写在 `evals/*.eval.ts` 里，描述测什么。 |
-| Experiment | 可签入的运行配置：决定连哪个 Adapter、什么 model、什么 flags。 |
+| Experiment | 可签入的运行配置：决定连哪个 Adapter、什么 model、什么 params。 |
 | Adapter | 连接被测系统的适配层：实现一个 `send`，把返回翻译成标准事件流。 |
 | Sandbox | 需要隔离工作区的 coding agent 才用得到；直连 Web Agent 不需要。 |
 | Tier | 接入 Adapter 的三档投入：Tier 1 只接 send，Tier 2 加 OTel 换调用瀑布图，Tier 3 侵入改造做 feature A/B。 |

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

@@ -4,7 +4,7 @@ sidebarTitle: "命令行"
 description: "NiceEval CLI 参考：exp、init、list、clean 和 view 命令，以及 experiment、eval 过滤、sandbox、并发、预算和 JUnit CI 输出。"
 ---
 
-[NiceEval](https://niceeval.com/) CLI 是发现、运行和查看 eval 的入口。实际执行 eval 时采用 experiment-first 模型：**`exp` 选择可签入的运行配置**，experiment 后的位置参数才按 eval ID 前缀过滤。agent、model 和 feature flags 写在 `experiments/`，不靠临时 CLI 参数。
+[NiceEval](https://niceeval.com/) CLI 是发现、运行和查看 eval 的入口。实际执行 eval 时采用 experiment-first 模型：**`exp` 选择可签入的运行配置**，experiment 后的位置参数才按 eval ID 前缀过滤。agent、model 和 params 写在 `experiments/`，不靠临时 CLI 参数。
 
 ## 命令
 
@@ -13,7 +13,7 @@ description: "NiceEval CLI 参考：exp、init、list、clean 和 view 命令，
     运行命名实验组或配置。可选尾随位置参数按 eval ID 前缀过滤。
   </Card>
   <Card title="npx niceeval init" icon="wand-magic-sparkles">
-    创建空的 `evals/` 目录和最小的 `niceeval.config.ts`；不生成示例 eval 文件。同时在 `AGENTS.md` 写入/刷新 niceeval 指引区块（见[Agent 反馈闭环](/zh/guides/agent-feedback-loop)）。
+    创建空的 `evals/` 目录和最小的 `niceeval.config.ts`；不生成示例 eval 文件。同时写入/刷新 niceeval 指引区块——项目已有 `AGENTS.md` 就写那份，只有 `CLAUDE.md` 就写进 `CLAUDE.md`，都没有则新建 `AGENTS.md`（见[Agent 反馈闭环](/zh/guides/agent-feedback-loop)）。
   </Card>
   <Card title="npx niceeval list" icon="list">
     发现并打印所有 eval，不运行。
@@ -72,6 +72,14 @@ npx niceeval exp compare-models weather
 | `--junit` | string | 额外写一份 JUnit XML 报告到指定路径,供 CI 消费。 |
 | `--out` | string | `view` 命令专用:把结果查看器静态导出到指定目录。 |
 | `--port` | number | `view` 命令专用:指定本地服务器监听端口。 |
+| `--transcript` | boolean | `show` 命令专用:渲染单个 eval 的完整对话与工具调用(证据切面)。 |
+| `--trace` | boolean | `show` 命令专用:渲染单个 eval 的 trace 瀑布文本版(证据切面)。 |
+| `--diff` | boolean | `show` 命令专用:sandbox 里的文件改动摘要;`--diff=<文件路径>` 看单个文件的完整改动(路径必须 `=` 连写)。 |
+| `--history` | boolean | `show` 命令专用:跨 run 时间轴,只列真实执行;与 `--report` 互斥。 |
+| `--experiment` | string | `show` 命令专用:选集只留该实验。 |
+| `--attempt` | number | `show` 命令专用:指定详情 / 证据切面看第几次 attempt(与展示一致的 1 计序号)。 |
+| `--run` | string | `show` 命令专用:钉死看某一个结果目录(历史 run 或 `copySnapshots` 产物)。 |
+| `--report` | string | `show` 命令专用:把默认榜单整槽换成你的报告文件(默认导出 `defineReport(...)`)。 |
 | `--dry` | boolean | 只打印本次会匹配到的 eval × 运行配置,不实际执行。 |
 | `--quiet` | boolean | 关闭控制台 / live 进度输出(reporter 仍会写 artifacts)。 |
 | `--force` | boolean | 忽略上次运行结果,不跳过已通过的 (experiment, eval) 组合,强制全部重跑。 |
@@ -97,7 +105,7 @@ npx niceeval exp compare-models
 npx niceeval exp compare-models weather-tool
 ```
 
-运行命名 experiment，用矩阵比较 agents、models 或 flags。第二个参数开始是 eval ID 前缀过滤。
+运行命名 experiment，用矩阵比较 agents、models 或 params。第二个参数开始是 eval ID 前缀过滤。
 
 ## `view`
 

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

@@ -214,16 +214,16 @@ readonly reasoningEffort?: string;
 
 模型推理努力程度;归属同 model——实验决定,省略时不覆盖 agent 原生默认。
 
-#### `flags`
+#### `params`
 
 ```ts
-readonly flags: Readonly<Record<string, unknown>>;
+readonly params: Readonly<Record<string, unknown>>;
 ```
 
-experiment 的 `flags` 字段原样透传,内容和结构完全由 experiment 作者自定义
+experiment 的 `params` 字段原样透传,内容和结构完全由 experiment 作者自定义
 (如 `{ webResearch: true }`、`{ systemPrompt: "..." }`)。adapter 按自己的约定
-读取其中的字段;框架本身不解释、不校验它的内容。与 CLI 解析出的同名 `flags`
-(跑法层面的 --timeout/--budget 等)是两个不相关的概念。
+读取其中的字段;框架本身不解释、不校验它的内容。命名特意避开 CLI 解析出的
+`flag`(跑法层面的 --timeout/--budget 等),两者是不相关的概念。
 
 #### `sandbox`
 

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

@@ -4,7 +4,7 @@ sidebarTitle: "defineConfig"
 description: "defineConfig 参考：judge、reporters、并发、超时和 sandbox 默认值。"
 ---
 
-`defineConfig` 从根目录的 `niceeval.config.ts` 默认导出，只放项目级默认值。agent、model、flags、runs 和实验预算写在 `experiments/` 下的 `defineExperiment` 文件里。
+`defineConfig` 从根目录的 `niceeval.config.ts` 默认导出，只放项目级默认值。agent、model、params、runs 和实验预算写在 `experiments/` 下的 `defineExperiment` 文件里。
 
 ```ts
 import { defineConfig } from "niceeval";

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

@@ -207,13 +207,13 @@ readonly reasoningEffort?: string;
 
 本次 attempt 的推理努力程度(如 "low"/"medium"/"high",取值由 adapter/模型决定)。
 
-#### `flags`
+#### `params`
 
 ```ts
-readonly flags: Readonly<Record<string, unknown>>;
+readonly params: Readonly<Record<string, unknown>>;
 ```
 
-本次 attempt 生效的 flags(experiment.flags 与 CLI flag 合并后的只读视图)。
+本次 attempt 生效的 params(experiment.params 与 CLI flag 合并后的只读视图)。
 
 #### `log`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "niceeval",
-  "version": "0.4.6",
+  "version": "0.5.1",
   "description": "Agent-native eval tool — eval agents, services, functions, and coding-agent fixtures",
   "type": "module",
   "license": "MIT",
@@ -61,7 +61,8 @@
   "files": [
     "src",
     "bin",
-    "docs-site"
+    "docs-site/zh",
+    "docs-site/images"
   ],
   "dependencies": {
     "autoevals": "0.0.132",

package/src/agents/ai-sdk.test.ts

@@ -454,7 +454,7 @@ function fakeCtx(opts: { id?: string } = {}): AgentContext {
   return {
     signal: new AbortController().signal,
     model: undefined,
-    flags: {},
+    params: {},
     sandbox: undefined as unknown as AgentContext["sandbox"],
     session,
     log: () => {},

package/src/agents/ai-sdk.ts

@@ -367,7 +367,7 @@ export interface AiSdkGenerateContext<M = unknown> {
   /** 实验钉的推理努力程度(ctx.reasoningEffort);省略 → 用应用自己的默认。应用自己决定怎么塞进 providerOptions(如 OpenAI 的 reasoningEffort)。 */
   readonly reasoningEffort?: string;
   readonly signal: AbortSignal;
-  readonly flags: Readonly<Record<string, unknown>>;
+  readonly params: Readonly<Record<string, unknown>>;
   /**
    * 配了 `tracing`(如 `aiSdkOtel()`)才有:直接放进 generateText / streamText 的
    * `telemetry` 选项。OTel provider、per-attempt 端点绑定和轮末 flush 都由工厂做,
@@ -505,7 +505,7 @@ export function aiSdkAgent<M = unknown>(options: AiSdkAgentOptions<M>): Agent {
           model: ctx.model,
           reasoningEffort: ctx.reasoningEffort,
           signal: ctx.signal,
-          flags: ctx.flags,
+          params: ctx.params,
           telemetry: otel?.settings,
         });
       } catch (error) {

package/src/agents/claude-code.ts

@@ -94,7 +94,7 @@ export function claudeCodeAgent(config?: ClaudeCodeConfig): Agent {
       const args = ["--print", "--dangerously-skip-permissions"];
       if (ctx.model) args.push("--model", ctx.model);
       if (config?.maxTurns != null) args.push("--max-turns", String(config.maxTurns));
-      if (ctx.flags.webResearch) args.push("--allowedTools", "WebSearch,WebFetch");
+      if (ctx.params.webResearch) args.push("--allowedTools", "WebSearch,WebFetch");
       if (ctx.session.id) args.push("--resume", ctx.session.id);
       args.push(input.text);
 

package/src/agents/codex.ts

@@ -9,7 +9,7 @@ import type { Agent, McpServer } from "../types.ts";
 //
 // 连接方式:在沙箱里 spawn `codex exec --json`,stdout JSONL → parseCodex → 标准事件流。
 // 配置:鉴权本地(config / env),模型交给实验(ctx.model),推理努力程度经 ctx.reasoningEffort
-// (兼容旧的 ctx.flags.effort),其余 feature flags 经 ctx.flags。
+// (兼容旧的 ctx.params.effort),其余参数经 ctx.params。
 // ───────────────────────────────────────────────────────────────────────────
 
 export interface CodexConfig {
@@ -44,7 +44,7 @@ export function codexAgent(config?: CodexConfig): Agent {
       // model 归属:实验决定(ctx.model);省略时不写 model 行,交给 codex CLI 原生默认,
       // 不在 adapter 里硬编码一个会过期的模型名。
       const modelLine = ctx.model ? `model = "${ctx.model}"\n` : "";
-      const effort = ctx.reasoningEffort ?? (ctx.flags.effort as string | undefined) ?? "medium";
+      const effort = ctx.reasoningEffort ?? (ctx.params.effort as string | undefined) ?? "medium";
       const base = getBaseUrl();
 
       if (base) {

package/src/agents/streaming.test.ts

@@ -9,7 +9,7 @@ import { createAgentSession } from "../context/session.ts";
 function lineCtx(): AgentContext {
   return {
     signal: new AbortController().signal,
-    flags: {},
+    params: {},
     session: createAgentSession(),
     sandbox: undefined as never,
     log() {},

package/src/agents/types.ts

@@ -155,12 +155,12 @@ export interface AgentContext {
   /** 模型推理努力程度;归属同 model——实验决定,省略时不覆盖 agent 原生默认。 */
   readonly reasoningEffort?: string;
   /**
-   * experiment 的 `flags` 字段原样透传,内容和结构完全由 experiment 作者自定义
+   * experiment 的 `params` 字段原样透传,内容和结构完全由 experiment 作者自定义
    * (如 `{ webResearch: true }`、`{ systemPrompt: "..." }`)。adapter 按自己的约定
-   * 读取其中的字段;框架本身不解释、不校验它的内容。与 CLI 解析出的同名 `flags`
-   * (跑法层面的 --timeout/--budget 等)是两个不相关的概念。
+   * 读取其中的字段;框架本身不解释、不校验它的内容。命名特意避开 CLI 解析出的
+   * `flag`(跑法层面的 --timeout/--budget 等),两者是不相关的概念。
    */
-  readonly flags: Readonly<Record<string, unknown>>;
+  readonly params: Readonly<Record<string, unknown>>;
   /** 仅沙箱型 agent 有(运行器按 --sandbox 备好)。 */
   readonly sandbox: Sandbox;
   readonly session: AgentSession;

package/src/agents/ui-message-stream.test.ts

@@ -73,7 +73,7 @@ function ctx(overrides: Partial<{ model: string }> = {}): AgentContext {
   return {
     signal: new AbortController().signal,
     model: overrides.model,
-    flags: {},
+    params: {},
     sandbox: undefined as never,
     // 同一个 ctx 重复用 = 同一条会话线(续接,同一个 ctx.session);新造 = 新线。
     session: createAgentSession(),