niceeval 0.5.1 → 0.5.3

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

@@ -56,6 +56,8 @@ description: "NiceEval 内置的 claude-code、codex、bub 适配器分别做到
 
 {/* GENERATED:BEGIN builtin-agent-config */}
 
+{/* 本区块由 pnpm docs:reference 从源码注释生成,勿手改;要改文案,改对应源码的 TSDoc/JSDoc(映射见 scripts/generate-reference.ts) */}
+
 ### `ClaudeCodeConfig`
 
 #### `apiKey`
@@ -196,6 +198,8 @@ export default uiMessageStreamAgent({
 
 {/* GENERATED:BEGIN ui-message-stream-options */}
 
+{/* 本区块由 pnpm docs:reference 从源码注释生成,勿手改;要改文案,改对应源码的 TSDoc/JSDoc(映射见 scripts/generate-reference.ts) */}
+
 #### `name`
 
 ```ts

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 和 params 写在 `experiments/`，不靠临时 CLI 参数。
+[NiceEval](https://niceeval.com/) CLI 是发现、运行和查看 eval 的入口。实际执行 eval 时采用 experiment-first 模型：**`exp` 选择可签入的运行配置**，experiment 后的位置参数才按 eval ID 前缀过滤。agent、model 和 flags 写在 `experiments/`，不靠临时 CLI 参数。
 
 ## 命令
 
@@ -56,10 +56,12 @@ npx niceeval exp compare-models weather
 
 ## 常用 flags
 
-下表由 CLI 的 flag 解析表生成。**没有**用于选择 sandbox 后端的 CLI flag：sandbox 后端只能写在代码里——在 experiment（`defineExperiment`）里设置 `sandbox`，或者在 `niceeval.config.ts`（`defineConfig`）里设置作为项目级兜底，值来自 `niceeval/sandbox` 的 `dockerSandbox()` / `vercelSandbox()` / `e2bSandbox()`；在 CLI 上尝试传入 `--sandbox` 会直接报错并以非零状态退出。`--watch` / `--json` 是文档曾接受、尚未实现的 flag，容忍解析（no-op）但不接任何行为，同样不在下表出现。
+下表由 CLI 的 flag 解析表生成，表外的 flag 一律按未知 flag 报错并以非零状态退出。**没有**用于选择 sandbox 后端的 CLI flag：sandbox 后端只能写在代码里——在 experiment（`defineExperiment`）里设置 `sandbox`，或者在 `niceeval.config.ts`（`defineConfig`）里设置作为项目级兜底，值来自 `niceeval/sandbox` 的 `dockerSandbox()` / `vercelSandbox()` / `e2bSandbox()`。
 
 {/* GENERATED:BEGIN cli-flags */}
 
+{/* 本区块由 pnpm docs:reference 从源码注释生成,勿手改;要改文案,改对应源码的 TSDoc/JSDoc(映射见 scripts/generate-reference.ts) */}
+
 | Flag | 类型 | 说明 |
 |---|---|---|
 | `--agent` | string | experiment 运行不支持该 flag。要换 agent,请在 `experiments/` 下新增或复制一个配置文件。 |
@@ -70,16 +72,17 @@ npx niceeval exp compare-models weather
 | `--budget` | number | 整次运行的预算上限(美元)。 |
 | `--tag` | string | 只运行带有该 tag 的 eval(见 `defineEval` 的 `tags`)。 |
 | `--junit` | string | 额外写一份 JUnit XML 报告到指定路径,供 CI 消费。 |
+| `--json` | string | 额外写一份 JSON 结果(`RunSummary` 原样序列化)到指定路径,供 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` 命令专用:选集只留该实验。 |
+| `--experiment` | string | `show` / `view` 命令专用:选集只留该实验。 |
 | `--attempt` | number | `show` 命令专用:指定详情 / 证据切面看第几次 attempt(与展示一致的 1 计序号)。 |
-| `--run` | string | `show` 命令专用:钉死看某一个结果目录(历史 run 或 `copySnapshots` 产物)。 |
-| `--report` | string | `show` 命令专用:把默认榜单整槽换成你的报告文件(默认导出 `defineReport(...)`)。 |
+| `--run` | string | `show` / `view` 命令专用:钉死看某一个结果目录(历史 run 或 `copySnapshots` 产物)。 |
+| `--report` | string | `show` / `view` 命令专用:把默认榜单整槽换成你的报告文件(默认导出 `defineReport(...)`)。 |
 | `--dry` | boolean | 只打印本次会匹配到的 eval × 运行配置,不实际执行。 |
 | `--quiet` | boolean | 关闭控制台 / live 进度输出(reporter 仍会写 artifacts)。 |
 | `--force` | boolean | 忽略上次运行结果,不跳过已通过的 (experiment, eval) 组合,强制全部重跑。 |
@@ -87,6 +90,7 @@ npx niceeval exp compare-models weather
 | `--early-exit` / `--no-early-exit` | boolean | 某个 eval 的一次 attempt 通过后,停止该 eval 剩余的 attempts。 |
 | `--open` / `--no-open` | boolean | `view` 命令专用:启动后自动打开浏览器(默认行为)。 |
 | `--help` | boolean | 打印用法说明并退出。 |
+| `--version` | boolean | 打印 niceeval 的版本号并退出。 |
 
 {/* GENERATED:END cli-flags */}
 
@@ -105,7 +109,7 @@ npx niceeval exp compare-models
 npx niceeval exp compare-models weather-tool
 ```
 
-运行命名 experiment，用矩阵比较 agents、models 或 params。第二个参数开始是 eval ID 前缀过滤。
+运行命名 experiment，用矩阵比较 agents、models 或 flags。第二个参数开始是 eval ID 前缀过滤。
 
 ## `view`
 

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

@@ -80,6 +80,8 @@ export default defineExperiment({
 
 {/* GENERATED:BEGIN agent-def */}
 
+{/* 本区块由 pnpm docs:reference 从源码注释生成,勿手改;要改文案,改对应源码的 TSDoc/JSDoc(映射见 scripts/generate-reference.ts) */}
+
 ### `RemoteAgentDef`
 
 #### `name`
@@ -214,13 +216,13 @@ readonly reasoningEffort?: string;
 
 模型推理努力程度;归属同 model——实验决定,省略时不覆盖 agent 原生默认。
 
-#### `params`
+#### `flags`
 
 ```ts
-readonly params: Readonly<Record<string, unknown>>;
+readonly flags: Readonly<Record<string, unknown>>;
 ```
 
-experiment 的 `params` 字段原样透传,内容和结构完全由 experiment 作者自定义
+experiment 的 `flags` 字段原样透传,内容和结构完全由 experiment 作者自定义
 (如 `{ webResearch: true }`、`{ systemPrompt: "..." }`)。adapter 按自己的约定
 读取其中的字段;框架本身不解释、不校验它的内容。命名特意避开 CLI 解析出的
 `flag`(跑法层面的 --timeout/--budget 等),两者是不相关的概念。
@@ -280,6 +282,8 @@ log(msg: string): void;
 
 {/* GENERATED:BEGIN sandbox-methods */}
 
+{/* 本区块由 pnpm docs:reference 从源码注释生成,勿手改;要改文案,改对应源码的 TSDoc/JSDoc(映射见 scripts/generate-reference.ts) */}
+
 ### `Sandbox`
 
 #### `workdir`

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、params、runs 和实验预算写在 `experiments/` 下的 `defineExperiment` 文件里。
+`defineConfig` 从根目录的 `niceeval.config.ts` 默认导出，只放项目级默认值。agent、model、flags、runs 和实验预算写在 `experiments/` 下的 `defineExperiment` 文件里。
 
 ```ts
 import { defineConfig } from "niceeval";
@@ -20,6 +20,8 @@ export default defineConfig({
 
 {/* GENERATED:BEGIN config-fields */}
 
+{/* 本区块由 pnpm docs:reference 从源码注释生成,勿手改;要改文案,改对应源码的 TSDoc/JSDoc(映射见 scripts/generate-reference.ts) */}
+
 #### `name`
 
 ```ts

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

@@ -26,6 +26,8 @@ export default defineEval({
 
 {/* GENERATED:BEGIN defineeval-options */}
 
+{/* 本区块由 pnpm docs:reference 从源码注释生成,勿手改;要改文案,改对应源码的 TSDoc/JSDoc(映射见 scripts/generate-reference.ts) */}
+
 #### `id`
 
 ```ts
@@ -108,6 +110,8 @@ eval 主体:拿到 TestContext,驱动对话 / 沙箱操作并就地断言。
 
 {/* GENERATED:BEGIN test-context */}
 
+{/* 本区块由 pnpm docs:reference 从源码注释生成,勿手改;要改文案,改对应源码的 TSDoc/JSDoc(映射见 scripts/generate-reference.ts) */}
+
 #### `send`
 
 ```ts
@@ -207,13 +211,13 @@ readonly reasoningEffort?: string;
 
 本次 attempt 的推理努力程度(如 "low"/"medium"/"high",取值由 adapter/模型决定)。
 
-#### `params`
+#### `flags`
 
 ```ts
-readonly params: Readonly<Record<string, unknown>>;
+readonly flags: Readonly<Record<string, unknown>>;
 ```
 
-本次 attempt 生效的 params(experiment.params 与 CLI flag 合并后的只读视图)。
+本次 attempt 生效的实验 flags(experiment.flags 的只读视图;实验条件,非命令行开关)。
 
 #### `log`
 
@@ -440,6 +444,8 @@ t.judge.autoevals.summarizes(sourceText, { on: t.reply }).atLeast(0.7);
 
 {/* GENERATED:BEGIN turn-handle */}
 
+{/* 本区块由 pnpm docs:reference 从源码注释生成,勿手改;要改文案,改对应源码的 TSDoc/JSDoc(映射见 scripts/generate-reference.ts) */}
+
 #### `events`
 
 ```ts

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

@@ -23,6 +23,8 @@ interface Turn {
 
 {/* GENERATED:BEGIN usage-fields */}
 
+{/* 本区块由 pnpm docs:reference 从源码注释生成,勿手改;要改文案,改对应源码的 TSDoc/JSDoc(映射见 scripts/generate-reference.ts) */}
+
 #### `inputTokens`
 
 ```ts
@@ -81,6 +83,8 @@ token 用量或 OTel span 反推得到)。存在时优先于按价格表(`define
 
 {/* GENERATED:BEGIN stream-events */}
 
+{/* 本区块由 pnpm docs:reference 从源码注释生成,勿手改;要改文案,改对应源码的 TSDoc/JSDoc(映射见 scripts/generate-reference.ts) */}
+
 #### `message`
 
 ```ts

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

@@ -29,6 +29,8 @@ t.require(turn.status, equals("completed"));
 
 {/* GENERATED:BEGIN expect-matchers */}
 
+{/* 本区块由 pnpm docs:reference 从源码注释生成,勿手改;要改文案,改对应源码的 TSDoc/JSDoc(映射见 scripts/generate-reference.ts) */}
+
 #### `includes`
 
 ```ts
@@ -150,6 +152,8 @@ t.check(t.reply, includes("nice to have").atLeast(0.7));
 
 {/* GENERATED:BEGIN value-assertion */}
 
+{/* 本区块由 pnpm docs:reference 从源码注释生成,勿手改;要改文案,改对应源码的 TSDoc/JSDoc(映射见 scripts/generate-reference.ts) */}
+
 #### `name`
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "niceeval",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "Agent-native eval tool — eval agents, services, functions, and coding-agent fixtures",
   "type": "module",
   "license": "MIT",
@@ -100,7 +100,8 @@
     "shiki": "^4.3.0",
     "tailwind-merge": "^3.6.0",
     "tailwindcss": "^4.3.1",
-    "typescript": "^5.6.0",
+    "typescript": "npm:@typescript/typescript6@^6.0.2",
+    "@typescript/native": "npm:typescript@^7.0.2",
     "vite": "^8.1.0",
     "vitest": "^4.1.9"
   },

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

@@ -454,7 +454,7 @@ function fakeCtx(opts: { id?: string } = {}): AgentContext {
   return {
     signal: new AbortController().signal,
     model: undefined,
-    params: {},
+    flags: {},
     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 params: Readonly<Record<string, unknown>>;
+  readonly flags: 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,
-          params: ctx.params,
+          flags: ctx.flags,
           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.params.webResearch) args.push("--allowedTools", "WebSearch,WebFetch");
+      if (ctx.flags.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.params.effort),其余参数经 ctx.params。
+// (兼容旧的 ctx.flags.effort),其余参数经 ctx.flags。
 // ───────────────────────────────────────────────────────────────────────────
 
 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.params.effort as string | undefined) ?? "medium";
+      const effort = ctx.reasoningEffort ?? (ctx.flags.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,
-    params: {},
+    flags: {},
     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 的 `params` 字段原样透传,内容和结构完全由 experiment 作者自定义
+   * experiment 的 `flags` 字段原样透传,内容和结构完全由 experiment 作者自定义
    * (如 `{ webResearch: true }`、`{ systemPrompt: "..." }`)。adapter 按自己的约定
    * 读取其中的字段;框架本身不解释、不校验它的内容。命名特意避开 CLI 解析出的
    * `flag`(跑法层面的 --timeout/--budget 等),两者是不相关的概念。
    */
-  readonly params: Readonly<Record<string, unknown>>;
+  readonly flags: 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,
-    params: {},
+    flags: {},
     sandbox: undefined as never,
     // 同一个 ctx 重复用 = 同一条会话线(续接,同一个 ctx.session);新造 = 新线。
     session: createAgentSession(),

package/src/cli.ts

@@ -17,7 +17,7 @@ import { stopAllSandboxes, liveSandboxCount } from "./sandbox/registry.ts";
 import { evalLevelStats } from "./shared/outcome.ts";
 import { sandboxRecommendedConcurrency } from "./sandbox/resolve.ts";
 import { Console as ConsoleReporter } from "./runner/reporters/console.ts";
-import { JUnit } from "./runner/reporters/json.ts";
+import { Json, JUnit } from "./runner/reporters/json.ts";
 import { Live as LiveReporter, type LiveRow } from "./runner/reporters/live.ts";
 import { Artifacts as ArtifactsReporter } from "./runner/reporters/artifacts.ts";
 import {
@@ -60,10 +60,12 @@ interface Flags {
   budget?: number;
   tag?: string;
   junit?: string;
+  json?: string;
   open?: boolean;
   out?: string;
   port?: number;
   help: boolean;
+  version: boolean;
   // ── show 专属(位置参数仍是 eval id 前缀;这些 flag 选「怎么看」)──
   transcript: boolean;
   trace: boolean;
@@ -79,43 +81,70 @@ interface Flags {
 
 // 表驱动的 flag 定义(node:util parseArgs)。--no-x 显式声明,不依赖 allowNegative(需 Node 20.14+,
 // engines 是 >=18)。未知 flag 由 strict 模式报清晰错误,不再静默吞掉后面的位置参数。
+//
+// 每个 flag 的 JSDoc 就是它在 docs-site/zh/reference/cli.mdx flag 表里的说明,由
+// scripts/generate-reference.ts 提取渲染——改 flag 语义时改这里的注释即可,不用碰生成脚本。
+// 负向 flag(no-x)与正向 flag 合并成一行展示,不需要单独写 JSDoc。
 const FLAG_OPTIONS = {
+  /** experiment 运行不支持该 flag。要换 agent,请在 `experiments/` 下新增或复制一个配置文件。 */
   agent: { type: "string" },
+  /** experiment 运行不支持该 flag。要换模型,请新增或复制一个 experiment 文件并修改 `model`。 */
   model: { type: "string" },
+  /** 每个 eval 运行多少次,常用于 pass@N。 */
   runs: { type: "string" },
+  /** 设置同时运行的 eval 数量。 */
   "max-concurrency": { type: "string" },
+  /** 单个 attempt 的超时时间,单位毫秒。 */
   timeout: { type: "string" },
+  /** 整次运行的预算上限(美元)。 */
   budget: { type: "string" },
+  /** 只运行带有该 tag 的 eval(见 `defineEval` 的 `tags`)。 */
   tag: { type: "string" },
+  /** 额外写一份 JUnit XML 报告到指定路径,供 CI 消费。 */
   junit: { type: "string" },
+  /** 额外写一份 JSON 结果(`RunSummary` 原样序列化)到指定路径,供 CI 或下游脚本消费。 */
+  json: { type: "string" },
+  /** `view` 命令专用:把结果查看器静态导出到指定目录。 */
   out: { type: "string" },
+  /** `view` 命令专用:指定本地服务器监听端口。 */
   port: { type: "string" },
-  // --sandbox 已移除(sandbox 归 config/experiment);留着解析是为了给出迁移提示而非「未知 flag」。
-  sandbox: { type: "string" },
-  // --watch / --json:文档曾接受、尚未实现的 flag。容忍(no-op)而不是硬报「未知 flag」,
-  // 免得照旧文档写的脚本直接崩;真正实现前不接任何行为。
-  watch: { type: "boolean" },
-  json: { type: "boolean" },
   // show 的证据切面 / 时间轴 / 报告装载(docs-site/zh/guides/viewing-results.mdx)。
+  /** `show` 命令专用:渲染单个 eval 的完整对话与工具调用(证据切面)。 */
   transcript: { type: "boolean" },
+  /** `show` 命令专用:渲染单个 eval 的 trace 瀑布文本版(证据切面)。 */
   trace: { type: "boolean" },
   // --diff 是布尔;--diff=<路径> 在 parseArgs 前预扫成 diffPath(路径必须 = 连写,
   // 空格形式的下一个 token 仍是位置参数 = eval id 前缀,与文档一致)。
+  /** `show` 命令专用:sandbox 里的文件改动摘要;`--diff=<文件路径>` 看单个文件的完整改动(路径必须 `=` 连写)。 */
   diff: { type: "boolean" },
+  /** `show` 命令专用:跨 run 时间轴,只列真实执行;与 `--report` 互斥。 */
   history: { type: "boolean" },
+  /** `show` / `view` 命令专用:选集只留该实验。 */
   experiment: { type: "string" },
+  /** `show` 命令专用:指定详情 / 证据切面看第几次 attempt(与展示一致的 1 计序号)。 */
   attempt: { type: "string" },
+  /** `show` / `view` 命令专用:钉死看某一个结果目录(历史 run 或 `copySnapshots` 产物)。 */
   run: { type: "string" },
+  /** `show` / `view` 命令专用:把默认榜单整槽换成你的报告文件(默认导出 `defineReport(...)`)。 */
   report: { type: "string" },
+  /** 只打印本次会匹配到的 eval × 运行配置,不实际执行。 */
   dry: { type: "boolean" },
+  /** 关闭控制台 / live 进度输出(reporter 仍会写 artifacts)。 */
   quiet: { type: "boolean" },
+  /** 忽略上次运行结果,不跳过已通过的 (experiment, eval) 组合,强制全部重跑。 */
   force: { type: "boolean" },
+  /** CI 中推荐使用:让软阈值(`soft`)失败也计入整条 eval 的 outcome。 */
   strict: { type: "boolean" },
+  /** 某个 eval 的一次 attempt 通过后,停止该 eval 剩余的 attempts。 */
   "early-exit": { type: "boolean" },
   "no-early-exit": { type: "boolean" },
+  /** `view` 命令专用:启动后自动打开浏览器(默认行为)。 */
   open: { type: "boolean" },
   "no-open": { type: "boolean" },
+  /** 打印用法说明并退出。 */
   help: { type: "boolean", short: "h" },
+  /** 打印 niceeval 的版本号并退出。 */
+  version: { type: "boolean", short: "v" },
 } as const;
 
 function numberFlag(name: string, raw: string | undefined): number | undefined {
@@ -153,11 +182,6 @@ function parseArgs(argv: string[]): { command: string; positionals: string[]; fl
     process.exit(1);
   }
 
-  if (values.sandbox !== undefined) {
-    process.stderr.write(t("cli.sandboxFlagRemoved"));
-    process.exit(1);
-  }
-
   // 第一个位置参数若是已知命令,则为命令;其余是 eval id 前缀 / view 输入。
   const commands = new Set(["exp", "show", "list", "view", "clean", "init", "watch", "run"]);
   let command = "run";
@@ -176,6 +200,7 @@ function parseArgs(argv: string[]): { command: string; positionals: string[]; fl
     budget: numberFlag("budget", values.budget as string | undefined),
     tag: values.tag as string | undefined,
     junit: values.junit as string | undefined,
+    json: values.json as string | undefined,
     out: values.out as string | undefined,
     port: numberFlag("port", values.port as string | undefined),
     dry: values.dry === true,
@@ -185,6 +210,7 @@ function parseArgs(argv: string[]): { command: string; positionals: string[]; fl
     earlyExit: values["no-early-exit"] === true ? false : values["early-exit"] === true ? true : undefined,
     open: values["no-open"] === true ? false : values.open === true ? true : undefined,
     help: values.help === true,
+    version: values.version === true,
     transcript: values.transcript === true,
     trace: values.trace === true,
     diff: values.diff === true && diffPath === undefined,
@@ -324,17 +350,28 @@ function evalsFilterFromExperiment(
   return (id) => expFilter(id) && patternFilter(id);
 }
 
+/** package.json 的 version 字段;-v/--version 直接回显这个号。 */
+async function packageVersion(): Promise<string> {
+  const raw = await readFile(new URL("../package.json", import.meta.url), "utf-8");
+  return (JSON.parse(raw) as { version: string }).version;
+}
+
 async function main(): Promise<void> {
   const cwd = process.cwd();
   await loadDotenv(cwd);
   const { command, positionals, flags } = parseArgs(process.argv.slice(2));
 
-  // --help 不需要 config,先于一切命令处理。
+  // --help / --version 不需要 config,先于一切命令处理。
   if (flags.help) {
     process.stdout.write(t("cli.help"));
     process.exit(0);
   }
 
+  if (flags.version) {
+    process.stdout.write(`${await packageVersion()}\n`);
+    process.exit(0);
+  }
+
   if (command === "view") {
     // 位置参数 = eval id 前缀(收窄报告槽选集);存在的文件路径 = 单文件模式;
     // 结果目录经 --run 递入;--report 整槽替换报告槽(与 show --report 吃同一个文件)。
@@ -435,7 +472,7 @@ async function main(): Promise<void> {
         agent: exp.agent,
         model: exp.model,
         reasoningEffort: exp.reasoningEffort,
-        params: exp.params ?? {},
+        flags: exp.flags ?? {},
         runs: flags.runs ?? envNumber("NICEEVAL_RUNS") ?? exp.runs ?? 1,
         earlyExit: flags.earlyExit ?? exp.earlyExit ?? true,
         sandbox: exp.sandbox ?? config.sandbox,
@@ -451,7 +488,7 @@ async function main(): Promise<void> {
     }
   } else {
     // 裸 run / `niceeval <eval>` 不再执行。运行配置必须来自 experiments/,
-    // 这样 agent/model/params/runs/budget 与结果聚合都有可签入的身份。
+    // 这样 agent/model/flags/runs/budget 与结果聚合都有可签入的身份。
     const experiments = await discoverExperiments(cwd);
     const asExp = experiments.filter((e) =>
       positionals.some((p) => e.group === p || e.id === p || e.id.startsWith(p + "/")),
@@ -512,6 +549,7 @@ async function main(): Promise<void> {
   const artifacts = ArtifactsReporter();
   reporters.push(artifacts);
   if (flags.junit) reporters.push(JUnit(flags.junit));
+  if (flags.json) reporters.push(Json(flags.json));
   reporters.push(...(config.reporters ?? []));
 
   // Ctrl+C / kill 的三级响应,核心目标:任何情况下都不留下孤儿沙箱。

package/src/context/context.test.ts

@@ -57,7 +57,7 @@ function makeContext(agent: Agent, sandbox = fakeSandbox(), evalBaseDir?: string
   return createEvalContext({
     agent,
     sandbox,
-    params: {},
+    flags: {},
     signal: new AbortController().signal,
     log: () => {},
     judge: undefined,

package/src/context/context.ts

@@ -61,7 +61,7 @@ export interface ContextDeps {
   sandbox: Sandbox;
   model?: string;
   reasoningEffort?: string;
-  params: Record<string, unknown>;
+  flags: Record<string, unknown>;
   signal: AbortSignal;
   log(msg: string): void;
   judge: JudgeConfig | undefined;
@@ -92,7 +92,7 @@ export function createEvalContext(deps: ContextDeps): { context: TestContext; st
     sandbox: deps.sandbox,
     model: deps.model,
     reasoningEffort: deps.reasoningEffort,
-    params: deps.params,
+    flags: deps.flags,
     signal: deps.signal,
     log: deps.log,
     telemetry: deps.telemetry,
@@ -284,7 +284,7 @@ export function createEvalContext(deps: ContextDeps): { context: TestContext; st
     signal: deps.signal,
     model: deps.model,
     reasoningEffort: deps.reasoningEffort,
-    params: deps.params,
+    flags: deps.flags,
     log: deps.log,
     skip: (reason: string) => {
       if (reason.trim().length === 0) throw new Error(t("context.skipEmpty"));

package/src/context/session.ts

@@ -88,7 +88,7 @@ export interface SessionDeps {
   sandbox: Sandbox;
   model?: string;
   reasoningEffort?: string;
-  params: Record<string, unknown>;
+  flags: Record<string, unknown>;
   signal: AbortSignal;
   log(msg: string): void;
   /** tracing agent 的 OTLP 端点(经 send ctx 透给 adapter,用于注入导出 env)。 */
@@ -138,7 +138,7 @@ export class SessionManager {
       signal: this.deps.signal,
       model: this.deps.model,
       reasoningEffort: this.deps.reasoningEffort,
-      params: this.deps.params,
+      flags: this.deps.flags,
       sandbox: this.deps.sandbox,
       session,
       telemetry: this.deps.telemetry,

package/src/context/types.ts

@@ -274,8 +274,8 @@ export interface TestContext {
   readonly model?: string;
   /** 本次 attempt 的推理努力程度(如 "low"/"medium"/"high",取值由 adapter/模型决定)。 */
   readonly reasoningEffort?: string;
-  /** 本次 attempt 生效的 params(experiment.params 与 CLI flag 合并后的只读视图)。 */
-  readonly params: Readonly<Record<string, unknown>>;
+  /** 本次 attempt 生效的实验 flags(experiment.flags 的只读视图;实验条件,非命令行开关)。 */
+  readonly flags: Readonly<Record<string, unknown>>;
   /** 打一行调试日志;有 live 进度回调时走该回调,否则落到 stderr,不出现在最终结果里。 */
   log(msg: string): void;
   /** 立即中止本 eval 并标记为 skipped(outcome / EvalResult.skipReason),reason 不能为空。 */

package/src/i18n/en.ts

@@ -59,7 +59,7 @@ export const en = {
     "Flags:\n" +
     "  --runs n  --max-concurrency n  --timeout ms  --budget usd  --tag t\n" +
     "  --early-exit / --no-early-exit  --strict  --force  --dry  --quiet\n" +
-    "  --junit path  --out dir  --port n  --open / --no-open  -h, --help\n\n" +
+    "  --junit path  --json path  --out dir  --port n  --open / --no-open  -h, --help  -v, --version\n\n" +
     "Positional args only select which evals to run (id prefixes); which agent and\n" +
     "how to run come from experiments/ + flags. Env overrides (flag > env > config):\n" +
     "  NICEEVAL_RUNS  NICEEVAL_MAX_CONCURRENCY  NICEEVAL_TIMEOUT  NICEEVAL_BUDGET\n",
@@ -94,10 +94,10 @@ export const en = {
     "  Docs: node_modules/niceeval/docs-site/zh/guides/write-experiment.mdx\n",
   "cli.run.experimentRequiredHint": "Hint: \"{{pattern}}\" is an experiment{{kind}}; you probably meant: niceeval exp {{pattern}}\n",
   "cli.run.experimentRequiredKnown": "Discovered experiments: {{experiments}}\n",
-  "cli.sandboxFlagRemoved": "`--sandbox` is not a CLI flag. Set `sandbox` in the experiment (or `niceeval.config.ts` as a project-wide fallback) to dockerSandbox() / vercelSandbox() / e2bSandbox() (import from \"niceeval/sandbox\").\n",
   "cli.unimplemented": "Command \"{{command}}\" is not implemented yet (MVP).\n",
   "cli.view.exportedDir": "Exported static report site: {{out}} (serve the whole directory with any static host; opening index.html via file:// cannot fetch artifacts)\n",
   "cli.view.incompatible": "{{dir}}: written by niceeval {{producer}} (schemaVersion {{schemaVersion}}); this CLI reads schemaVersion {{supported}}.\nRun `{{command}}` to view it.\n",
+  "cli.view.noResults": "No results found under {{root}}. Run `niceeval exp` first, then `niceeval view`.\n",
   "cli.view.incompatibleForeign": "{{dir}}: written by {{name}} {{version}} (schemaVersion {{schemaVersion}}); this CLI reads schemaVersion {{supported}}.\nOpen this report with the tool that produced it.\n",
   "cli.view.url": "niceeval view: {{url}}\n",
   "context.capabilityMissing":

package/src/i18n/zh-CN.ts

@@ -55,7 +55,7 @@ export const zhCN = {
     "标志:\n" +
     "  --runs n  --max-concurrency n  --timeout ms  --budget usd  --tag t\n" +
     "  --early-exit / --no-early-exit  --strict  --force  --dry  --quiet\n" +
-    "  --junit path  --out dir  --port n  --open / --no-open  -h, --help\n\n" +
+    "  --junit path  --json path  --out dir  --port n  --open / --no-open  -h, --help  -v, --version\n\n" +
     "位置参数只选「跑哪些 eval」(id 前缀);对着哪个 agent、怎么跑来自 experiments/ 与\n" +
     "标志。环境变量覆盖(标志 > 环境变量 > config):\n" +
     "  NICEEVAL_RUNS  NICEEVAL_MAX_CONCURRENCY  NICEEVAL_TIMEOUT  NICEEVAL_BUDGET\n",
@@ -91,10 +91,10 @@ export const zhCN = {
     "  文档:node_modules/niceeval/docs-site/zh/guides/write-experiment.mdx\n",
   "cli.run.experimentRequiredHint": "提示:\"{{pattern}}\" 是实验{{kind}},你大概想跑:niceeval exp {{pattern}}\n",
   "cli.run.experimentRequiredKnown": "已发现实验:{{experiments}}\n",
-  "cli.sandboxFlagRemoved": "`--sandbox` 不是 CLI flag。请在 experiment(或 niceeval.config.ts 做全项目兜底)里把 sandbox 设成 dockerSandbox() / vercelSandbox() / e2bSandbox()(从 \"niceeval/sandbox\" 导入)。\n",
   "cli.unimplemented": "命令 \"{{command}}\" 暂未实现(MVP)。\n",
   "cli.view.exportedDir": "已导出静态查看站:{{out}}(整个目录可直接静态托管;本地打开 {{out}}/index.html 需经 http 服务,file:// 下工件 fetch 不可用)\n",
   "cli.view.incompatible": "{{dir}}: 由 niceeval {{producer}} 写入(schemaVersion {{schemaVersion}}),当前 CLI 只读 schemaVersion {{supported}}。\n运行 `{{command}}` 查看这份报告。\n",
+  "cli.view.noResults": "{{root}} 下没有结果。先 `niceeval exp` 跑一轮,再 `niceeval view`。\n",
   "cli.view.incompatibleForeign": "{{dir}}: 由 {{name}} {{version}} 写入(schemaVersion {{schemaVersion}}),当前 CLI 只读 schemaVersion {{supported}}。\n请用写出它的那个工具查看这份报告。\n",
   "cli.view.url": "niceeval view: {{url}}\n",
   "context.capabilityMissing":