niceeval 0.5.2 → 0.5.4

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,6 +60,7 @@ interface Flags {
   budget?: number;
   tag?: string;
   junit?: string;
+  json?: string;
   open?: boolean;
   out?: string;
   port?: number;
@@ -80,43 +81,69 @@ 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;
 
@@ -155,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";
@@ -178,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,
@@ -449,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,
@@ -465,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 + "/")),
@@ -526,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,9 @@ export interface ContextDeps {
   sandbox: Sandbox;
   model?: string;
   reasoningEffort?: string;
-  params: Record<string, unknown>;
+  flags: Record<string, unknown>;
+  /** 路径推导出的实验 id(经 send ctx 透给 adapter,见 AgentContext.experimentId)。 */
+  experimentId?: string;
   signal: AbortSignal;
   log(msg: string): void;
   judge: JudgeConfig | undefined;
@@ -92,7 +94,8 @@ export function createEvalContext(deps: ContextDeps): { context: TestContext; st
     sandbox: deps.sandbox,
     model: deps.model,
     reasoningEffort: deps.reasoningEffort,
-    params: deps.params,
+    flags: deps.flags,
+    experimentId: deps.experimentId,
     signal: deps.signal,
     log: deps.log,
     telemetry: deps.telemetry,
@@ -284,7 +287,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,9 +88,11 @@ export interface SessionDeps {
   sandbox: Sandbox;
   model?: string;
   reasoningEffort?: string;
-  params: Record<string, unknown>;
+  flags: Record<string, unknown>;
   signal: AbortSignal;
   log(msg: string): void;
+  /** 路径推导出的实验 id(经 send ctx 透给 adapter,见 AgentContext.experimentId)。 */
+  experimentId?: string;
   /** tracing agent 的 OTLP 端点(经 send ctx 透给 adapter,用于注入导出 env)。 */
   telemetry?: Telemetry;
   /** 非沙箱 tracing agent 的共享 OTLP 通道(runner 从 run 级池取,经它做逐轮 span 归属)。 */
@@ -138,7 +140,8 @@ export class SessionManager {
       signal: this.deps.signal,
       model: this.deps.model,
       reasoningEffort: this.deps.reasoningEffort,
-      params: this.deps.params,
+      flags: this.deps.flags,
+      experimentId: this.deps.experimentId,
       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/define.test.ts

@@ -0,0 +1,82 @@
+// SandboxSpec 链式钩子(.setup()/.teardown())的构造期契约:不可变、多次追加按顺序累加。
+// 执行顺序(setup 正序 / teardown 逆序 / LIFO cleanup)是 runner 的事,见
+// test/e2e-sandbox-hooks.test.ts;这里只测 dockerSandbox()/vercelSandbox()/e2bSandbox()/
+// defineSandbox() 这四个工厂产出的 spec 对象本身的构造行为。
+import { describe, expect, it } from "vitest";
+import { dockerSandbox, e2bSandbox, vercelSandbox, defineSandbox } from "./define.ts";
+import type { AgentSetup, AgentTeardown } from "./types.ts";
+
+const noopSetup: AgentSetup = () => {};
+const noopTeardown: AgentTeardown = () => {};
+
+describe("sandbox factories: .setup()/.teardown() chain", () => {
+  it("dockerSandbox() starts with empty hook arrays", () => {
+    const spec = dockerSandbox({ image: "custom:latest" });
+    expect(spec.backend).toBe("docker");
+    expect(spec.image).toBe("custom:latest");
+    expect(spec.setupHooks).toEqual([]);
+    expect(spec.teardownHooks).toEqual([]);
+  });
+
+  it(".setup() returns a new spec and does not mutate the original", () => {
+    const base = dockerSandbox();
+    const withSetup = base.setup(noopSetup);
+    expect(withSetup).not.toBe(base);
+    expect(base.setupHooks).toEqual([]);
+    expect(withSetup.setupHooks).toEqual([noopSetup]);
+  });
+
+  it("multiple .setup() calls accumulate in append order", () => {
+    const a: AgentSetup = () => {};
+    const b: AgentSetup = () => {};
+    const spec = dockerSandbox().setup(a).setup(b);
+    expect(spec.setupHooks).toEqual([a, b]);
+  });
+
+  it("multiple .teardown() calls accumulate in append order (execution order is the runner's job)", () => {
+    const x: AgentTeardown = () => {};
+    const y: AgentTeardown = () => {};
+    const spec = dockerSandbox().teardown(x).teardown(y);
+    expect(spec.teardownHooks).toEqual([x, y]);
+  });
+
+  it("chaining preserves backend-specific fields and stacks across calls", () => {
+    const spec = dockerSandbox({ image: "img" }).setup(noopSetup).teardown(noopTeardown).setup(noopSetup);
+    expect(spec.backend).toBe("docker");
+    expect(spec.image).toBe("img");
+    expect(spec.setupHooks).toHaveLength(2);
+    expect(spec.teardownHooks).toHaveLength(1);
+  });
+
+  it("vercelSandbox() / e2bSandbox() chain the same way and keep their own fields", () => {
+    const vercel = vercelSandbox({ snapshotId: "snap-1" }).setup(noopSetup);
+    expect(vercel.backend).toBe("vercel");
+    expect(vercel.snapshotId).toBe("snap-1");
+    expect(vercel.setupHooks).toEqual([noopSetup]);
+
+    const e2b = e2bSandbox({ template: "niceeval-agents" }).teardown(noopTeardown);
+    expect(e2b.backend).toBe("e2b");
+    expect(e2b.template).toBe("niceeval-agents");
+    expect(e2b.teardownHooks).toEqual([noopTeardown]);
+  });
+
+  it("defineSandbox() (custom backend) chains too and keeps create()/name", async () => {
+    const create = async () => {
+      throw new Error("not called in this test");
+    };
+    const spec = defineSandbox({ name: "my-backend", create }).setup(noopSetup).setup(noopSetup);
+    expect(spec.backend).toBe("my-backend");
+    expect(spec.create).toBe(create);
+    expect(spec.setupHooks).toHaveLength(2);
+  });
+
+  it("each chain call produces an independent object (no shared mutable state)", () => {
+    const base = dockerSandbox();
+    const other: AgentSetup = () => {};
+    const branchA = base.setup(noopSetup);
+    const branchB = base.setup(other);
+    expect(branchA.setupHooks).toEqual([noopSetup]);
+    expect(branchB.setupHooks).toEqual([other]);
+    expect(branchA.setupHooks).not.toBe(branchB.setupHooks);
+  });
+});

package/src/define.ts

@@ -3,6 +3,8 @@
 
 import type {
   Agent,
+  AgentSetup,
+  AgentTeardown,
   Config,
   CustomSandboxSpec,
   DockerSandboxSpec,
@@ -11,6 +13,7 @@ import type {
   ExperimentDef,
   RemoteAgentDef,
   SandboxAgentDef,
+  SandboxHooks,
   VercelSandboxSpec,
 } from "./types.ts";
 import { t } from "./i18n/index.ts";
@@ -71,20 +74,70 @@ export function defineConfig(config: Config): Config {
 // ───────────────────────── Sandbox 工厂 ─────────────────────────
 // Sandbox 与 agent 一样用数据结构带参数(见 docs/sandbox.md)。这些工厂只是把
 // 后端 + 参数包成 spec 对象;真正的行为在 sandbox/<backend>.ts 里,由 resolve.ts 派发。
+//
+// 四个工厂都要挂上 `.setup()` / `.teardown()` 链式方法(见 sandbox/types.ts 的
+// SandboxHooks<Self>):累积的钩子数组随 `HookState` 传递,每次链式调用都重新调
+// `build()` 产出一个新对象,原 spec 不被修改。
+
+/** 链式追加中累积的钩子(setup 按追加顺序执行,teardown 执行时逆序,见 SandboxHooks)。 */
+interface HookState {
+  readonly setupHooks: readonly AgentSetup[];
+  readonly teardownHooks: readonly AgentTeardown[];
+}
+
+/** 四个工厂共用:把当前钩子状态包成 `.setup()` / `.teardown()` 方法,调用即用新状态重新 build。 */
+function hookMethods<TSpec>(
+  state: HookState,
+  rebuild: (state: HookState) => TSpec,
+): Pick<SandboxHooks<TSpec>, "setup" | "teardown"> {
+  return {
+    setup: (fn) => rebuild({ setupHooks: [...state.setupHooks, fn], teardownHooks: state.teardownHooks }),
+    teardown: (fn) => rebuild({ setupHooks: state.setupHooks, teardownHooks: [...state.teardownHooks, fn] }),
+  };
+}
+
+const EMPTY_HOOKS: HookState = { setupHooks: [], teardownHooks: [] };
 
 /** Docker 沙箱:本地容器。`image` 可覆盖默认 `node:*-slim`(预制模板:烘焙好 agent CLI 的镜像)。 */
-export function dockerSandbox(opts: Omit<DockerSandboxSpec, "backend"> = {}): DockerSandboxSpec {
-  return { backend: "docker", ...opts };
+export function dockerSandbox(
+  opts: Omit<DockerSandboxSpec, "backend" | keyof SandboxHooks<unknown>> = {},
+): DockerSandboxSpec {
+  const build = (state: HookState): DockerSandboxSpec => ({
+    backend: "docker",
+    ...opts,
+    setupHooks: state.setupHooks,
+    teardownHooks: state.teardownHooks,
+    ...hookMethods(state, build),
+  });
+  return build(EMPTY_HOOKS);
 }
 
 /** Vercel Sandbox:microVM。`snapshotId` 从已有快照起(预制模板:烘焙好 agent CLI 的快照)。 */
-export function vercelSandbox(opts: Omit<VercelSandboxSpec, "backend"> = {}): VercelSandboxSpec {
-  return { backend: "vercel", ...opts };
+export function vercelSandbox(
+  opts: Omit<VercelSandboxSpec, "backend" | keyof SandboxHooks<unknown>> = {},
+): VercelSandboxSpec {
+  const build = (state: HookState): VercelSandboxSpec => ({
+    backend: "vercel",
+    ...opts,
+    setupHooks: state.setupHooks,
+    teardownHooks: state.teardownHooks,
+    ...hookMethods(state, build),
+  });
+  return build(EMPTY_HOOKS);
 }
 
 /** E2B 沙箱。`template` 选 e2b 模板名/ID(预制模板:如 `"niceeval-agents"`);省略用 e2b 默认 `"base"`。 */
-export function e2bSandbox(opts: Omit<E2BSandboxSpec, "backend"> = {}): E2BSandboxSpec {
-  return { backend: "e2b", ...opts };
+export function e2bSandbox(
+  opts: Omit<E2BSandboxSpec, "backend" | keyof SandboxHooks<unknown>> = {},
+): E2BSandboxSpec {
+  const build = (state: HookState): E2BSandboxSpec => ({
+    backend: "e2b",
+    ...opts,
+    setupHooks: state.setupHooks,
+    teardownHooks: state.teardownHooks,
+    ...hookMethods(state, build),
+  });
+  return build(EMPTY_HOOKS);
 }
 
 /**
@@ -98,5 +151,13 @@ export function defineSandbox(def: {
 }): CustomSandboxSpec {
   if (!def.name) throw new Error(t("define.sandboxNameRequired"));
   if (typeof def.create !== "function") throw new Error(t("define.sandboxCreateRequired"));
-  return { backend: def.name, create: def.create, recommendedConcurrency: def.recommendedConcurrency };
+  const build = (state: HookState): CustomSandboxSpec => ({
+    backend: def.name,
+    create: def.create,
+    recommendedConcurrency: def.recommendedConcurrency,
+    setupHooks: state.setupHooks,
+    teardownHooks: state.teardownHooks,
+    ...hookMethods(state, build),
+  });
+  return build(EMPTY_HOOKS);
 }

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  -v, --version\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":
@@ -186,6 +186,8 @@ export const en = {
   "runner.startAgentSetup": "agent setup (install CLI / write config)...",
   "runner.startAgentTracing": "agent tracing (write OTEL export config)...",
   "runner.startSandbox": "starting sandbox...",
+  "runner.startSandboxSetup": "sandbox setup (environment provisioning hooks)...",
+  "runner.startSandboxTeardown": "sandbox teardown (environment provisioning hooks)...",
   "runner.timeout": "attempt timed out ({{timeoutMs}}ms)\nRecent progress:\n{{recentLogs}}",
   "runner.traceSelected": " -> kept {{count}} semantic spans",
   "runner.resumeCarry": "  · reusing {{carried}} passing results from last run, re-running {{retry}} evals\n",

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  -v, --version\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":
@@ -183,6 +183,8 @@ export const zhCN = {
   "runner.startAgentSetup": "agent setup(装 CLI / 写配置)…",
   "runner.startAgentTracing": "agent tracing(写 otel 导出配置)…",
   "runner.startSandbox": "起沙箱…",
+  "runner.startSandboxSetup": "sandbox setup(环境预置钩子)…",
+  "runner.startSandboxTeardown": "sandbox teardown(环境预置钩子)…",
   "runner.timeout": "attempt 超时({{timeoutMs}}ms)\n最近进度:\n{{recentLogs}}",
   "runner.traceSelected": " → 留 {{count}}(按语义)",
   "runner.resumeCarry": "  · 复用上次 {{carried}} 个通过的结果,重跑 {{retry}} 个 eval\n",

package/src/report/aggregate.ts

@@ -18,15 +18,15 @@ import type {
   Metric,
   MetricCell,
   MetricColumn,
-  ParamRef,
+  FlagRef,
 } from "./types.ts";
 import { formatMetricValue } from "./format.ts";
 
 // 复合键分隔符:NUL 不会出现在 eval id / experimentId / ISO 时间里,拼接键不会串味
 const KEY_SEP = "\u0000";
 
-/** param 未声明时的组名:不猜,如实归一组。 */
-export const PARAM_UNSET = "(unset)";
+/** flag 未声明时的组名:不猜,如实归一组。 */
+export const FLAG_UNSET = "(unset)";
 
 /** 计算函数的第一参:选集(warnings 随行)或手工挑的快照数组(没有挑选过程,自然无警告)。 */
 export type SnapshotsInput = Selection | Snapshot[];
@@ -105,33 +105,33 @@ export function evalGroupOf(id: string): string {
   return slash === -1 ? id : id.slice(0, slash);
 }
 
-function isParamRef(dimension: DimensionInput): dimension is ParamRef {
-  return typeof dimension === "object" && "kind" in dimension && dimension.kind === "param";
+function isFlagRef(dimension: DimensionInput): dimension is FlagRef {
+  return typeof dimension === "object" && "kind" in dimension && dimension.kind === "flag";
 }
 
-/** experiment 声明的 params(经 runner 原样透传进持久化字段 ExperimentRunInfo.params)。 */
-function paramsOf(attempt: AttemptHandle): Record<string, unknown> | undefined {
-  return attempt.result.experiment?.params;
+/** experiment 声明的 flags(经 runner 原样透传进持久化字段 ExperimentRunInfo.flags)。 */
+function flagsOf(attempt: AttemptHandle): Record<string, unknown> | undefined {
+  return attempt.result.experiment?.flags;
 }
 
-/** param 声明值 → 组标签:label 函数优先,其余 String();未声明 → PARAM_UNSET。 */
-export function paramGroupKey(ref: ParamRef, item: Item): string {
-  const value = paramsOf(item.attempt)?.[ref.name];
-  if (value === undefined) return PARAM_UNSET;
+/** flag 声明值 → 组标签:label 函数优先,其余 String();未声明 → FLAG_UNSET。 */
+export function flagGroupKey(ref: FlagRef, item: Item): string {
+  const value = flagsOf(item.attempt)?.[ref.name];
+  if (value === undefined) return FLAG_UNSET;
   // 持久化字段是 Record<string, unknown>;声明侧的合法值就是这三种标量
   if (typeof ref.label === "function") return ref.label(value as string | number | boolean);
   return String(value);
 }
 
-/** param 作轴:要求数值;未声明或非数值 → null(点不画,注脚报数)。 */
-export function paramAxisValue(ref: ParamRef, item: Item): number | null {
-  const value = paramsOf(item.attempt)?.[ref.name];
+/** flag 作轴:要求数值;未声明或非数值 → null(点不画,注脚报数)。 */
+export function flagAxisValue(ref: FlagRef, item: Item): number | null {
+  const value = flagsOf(item.attempt)?.[ref.name];
   return typeof value === "number" ? value : null;
 }
 
 export function dimensionKey(dimension: DimensionInput, item: Item): string {
   if (typeof dimension !== "string") {
-    if (isParamRef(dimension)) return paramGroupKey(dimension, item);
+    if (isFlagRef(dimension)) return flagGroupKey(dimension, item);
     return dimension.of(item.attempt);
   }
   const result = item.attempt.result;

package/src/report/components.tsx

@@ -159,7 +159,7 @@ export const MetricScatter = Object.assign(
 );
 MetricScatter.displayName = "MetricScatter";
 
-/** 趋势线:x 是 experiment 声明的 param(param()),同系列按 x 排序连线。 */
+/** 趋势线:x 是 experiment 声明的 flag(flag()),同系列按 x 排序连线。 */
 export const MetricLine = Object.assign(
   defineComponent<MetricLineProps>({
     web: (props) => <MetricLineWeb {...props} />,

package/src/report/compute.ts

@@ -19,7 +19,7 @@ import type {
   Metric,
   MetricCell,
   OverviewData,
-  ParamRef,
+  FlagRef,
   ScatterData,
   ScoreboardData,
   TableData,
@@ -39,7 +39,7 @@ import {
   experimentIdOf,
   filterItems,
   groupItems,
-  paramAxisValue,
+  flagAxisValue,
   resolveInput,
   snapshotKeyOf,
   toColumn,
@@ -52,7 +52,7 @@ import { formatMetricValue, formatPlainNumber } from "./format.ts";
 // ───────────────────────── MetricTable.data ─────────────────────────
 
 export interface TableDataOptions<M extends readonly Metric[]> {
-  /** 行维度(内置 / 自定义 / param())。 */
+  /** 行维度(内置 / 自定义 / flag())。 */
   rows: DimensionInput;
   /** 每列一个指标;列键 = metric.name 的字面量,拼错编译不过。 */
   columns: M;
@@ -289,10 +289,10 @@ export async function scatterData(input: SnapshotsInput, opts: ScatterDataOption
 // ───────────────────────── MetricLine.data ─────────────────────────
 
 export interface LineDataOptions {
-  /** x 轴:experiment 声明的 param(数值),不解析 experiment 命名。 */
-  x: ParamRef;
+  /** x 轴:experiment 声明的 flag(数值),不解析 experiment 命名。 */
+  x: FlagRef;
   y: Metric;
-  /** 可选:每个系列一条线(param 或普通维度);省略 = 单系列。 */
+  /** 可选:每个系列一条线(flag 或普通维度);省略 = 单系列。 */
   series?: DimensionInput;
 }
 
@@ -303,7 +303,7 @@ export async function lineData(input: SnapshotsInput, opts: LineDataOptions): Pr
   const groups = groupItems(items, "experiment");
   const rows: LineData["rows"] = [];
   for (const [key, group] of groups) {
-    const x = paramAxisValue(opts.x, group[0]); // param 是 experiment 级声明,组内一致
+    const x = flagAxisValue(opts.x, group[0]); // flag 是 experiment 级声明,组内一致
     rows.push({
       key,
       series: opts.series ? dimensionKey(opts.series, group[0]) : undefined,

package/src/report/dual-face.test.tsx

@@ -228,7 +228,7 @@ describe("MetricLine 双面", () => {
     `);
   });
 
-  it("两面同口径:未声明 param 的点两面都不画、注脚同数", () => {
+  it("两面同口径:未声明 flag 的点两面都不画、注脚同数", () => {
     expect(html).toContain("1 point missing data");
     expect(term).toContain("1 point missing data");
     expect(html).not.toContain('data-key="ultra/legacy"'); // 注脚 title 如实列缺数据的点,但不画

package/src/report/{param.ts → flag.ts}

@@ -1,18 +1,18 @@
-// param():把 experiment 声明的 params 当维度或轴(docs/reports.md「params 与新摆法」)。
+// flag():把 experiment 声明的 flags 当维度或轴(docs/reports.md「flags 与新摆法」)。
 // 变量来自配置,不来自命名 —— 报告不解析 experiment id 字符串抠变量。
 
-import type { ParamRef } from "./types.ts";
+import type { FlagRef } from "./types.ts";
 
-export function param(
+export function flag(
   name: string,
   opts?: {
     /** 组标签 / 轴标签;函数形态把声明值折成组名(如 `(v) => \`${v} agents\``)。 */
     label?: string | ((value: string | number | boolean) => string);
     unit?: string;
   },
-): ParamRef {
+): FlagRef {
   if (typeof name !== "string" || name.length === 0) {
-    throw new Error("param: name must be a non-empty string (the key declared in the experiment's params).");
+    throw new Error("flag: name must be a non-empty string (the key declared in the experiment's flags).");
   }
-  return { kind: "param", name, label: opts?.label, unit: opts?.unit };
+  return { kind: "flag", name, label: opts?.label, unit: opts?.unit };
 }

package/src/report/index.ts

@@ -8,9 +8,9 @@
 // ./web.ts,只有那一侧 import react-dom。写报告文件的项目要装 react(.tsx 编译产物
 // import react/jsx-runtime)。
 
-// 指标与 param
+// 指标与 flag
 export { defineMetric, passRate, examScore, durationMs, tokens, costUSD } from "./metrics.ts";
-export { param } from "./param.ts";
+export { flag } from "./flag.ts";
 
 // 报告基座与双面组件基座
 export { defineReport, isReportDefinition, renderReportToText } from "./report.ts";
@@ -84,7 +84,7 @@ export type {
   MetricCell,
   MetricColumn,
   OverviewData,
-  ParamRef,
+  FlagRef,
   ScatterData,
   ScoreboardData,
   SelectionWarning,