niceeval 0.5.2 → 0.5.4

package/src/report/react/MetricLine.tsx

@@ -1,4 +1,4 @@
-// MetricLine:趋势线——x 是 experiment 声明的 param(有序变量),每个系列一条线。
+// MetricLine:趋势线——x 是 experiment 声明的 flag(有序变量),每个系列一条线。
 // 与 MetricScatter 的分工:scatter 的两轴都是测出来的指标(找 frontier),
 // line 的 x 是你配置的变量(看趋势)。x 轴正常升序;y 轴向随 better;
 // x 或 y 缺数据的点不画,注脚如实报数;每个点带 <title> hover,可经 pointHref 下钻。

package/src/report/react/fixtures.ts

@@ -207,7 +207,7 @@ export const lineData: LineData = {
       y: { value: 0.7, display: "70%", samples: 6, total: 6, refs: [] },
     },
     {
-      // 未声明 param 的 experiment:作轴不画点,注脚报数
+      // 未声明 flag 的 experiment:作轴不画点,注脚报数
       key: "ultra/legacy",
       series: "1 agents",
       x: null,

package/src/report/report.test.ts

@@ -1,7 +1,7 @@
 // niceeval/report 计算层的单元测试:全部用内存 fake(Snapshot / AttemptHandle 按
 // niceeval/results 的读取契约手工构造),专门覆盖 docs/reports.md 点名的坑 ——
 // 两级聚合 vs 平铺、pass@k、examScore 空真、skipped 稀释、scoreboard 固定分母与
-// 最长前缀、scatter/delta 的 null 语义、快照键对比、param 维度与轴、
+// 最长前缀、scatter/delta 的 null 语义、快照键对比、flag 维度与轴、
 // cases 的 redact/truncated、身份键去重、Selection warnings 随行。
 
 import { describe, expect, it } from "vitest";
@@ -10,7 +10,7 @@ import type { AssertionResult, EvalResult, ResultOutcome, RunSummary } from "../
 import type { AttemptHandle, RunDir, Selection, SelectionWarning, Snapshot } from "../results/index.ts";
 import type { Dimension, MetricCell } from "./types.ts";
 import { costUSD, defineMetric, durationMs, examScore, passRate, tokens } from "./metrics.ts";
-import { param } from "./param.ts";
+import { flag } from "./flag.ts";
 import { formatMetricValue } from "./format.ts";
 import {
   CaseList,
@@ -465,22 +465,22 @@ describe("MetricScatter.data", () => {
   });
 });
 
-// ───────────────────────── param():维度与轴 ─────────────────────────
+// ───────────────────────── flag():维度与轴 ─────────────────────────
 
-describe("param()", () => {
-  const withParams = (id: string, params: Record<string, unknown> | undefined, outcome: ResultOutcome) =>
+describe("flag()", () => {
+  const withFlags = (id: string, flags: Record<string, unknown> | undefined, outcome: ResultOutcome) =>
     snap({
       experimentId: id,
-      results: [res("A", outcome, { experimentId: id, experiment: { id, params } })],
+      results: [res("A", outcome, { experimentId: id, experiment: { id, flags } })],
     });
 
-  it("MetricLine.data:x 收 param、按 experiment 聚合;未声明的作轴 x=null 报数", async () => {
-    const s1 = withParams("ultra/lat-100", { latencyMs: 100, agents: 1 }, "passed");
-    const s2 = withParams("ultra/lat-300", { latencyMs: 300, agents: 1 }, "failed");
-    const legacy = withParams("ultra/legacy", undefined, "passed");
+  it("MetricLine.data:x 收 flag、按 experiment 聚合;未声明的作轴 x=null 报数", async () => {
+    const s1 = withFlags("ultra/lat-100", { latencyMs: 100, agents: 1 }, "passed");
+    const s2 = withFlags("ultra/lat-300", { latencyMs: 300, agents: 1 }, "failed");
+    const legacy = withFlags("ultra/legacy", undefined, "passed");
     const data = await MetricLine.data([s1, s2, legacy], {
-      x: param("latencyMs", { label: "Simulated latency", unit: "ms" }),
-      series: param("agents", { label: (v) => `${v} agents` }),
+      x: flag("latencyMs", { label: "Simulated latency", unit: "ms" }),
+      series: flag("agents", { label: (v) => `${v} agents` }),
       y: passRate,
     });
     expect(data.x).toEqual({ key: "latencyMs", label: "Simulated latency", unit: "ms" });
@@ -493,18 +493,18 @@ describe("param()", () => {
     expect(p100.series).toBe("1 agents");
     expect(p100.y.value).toBe(1);
 
-    // 未声明 param 的 experiment 不猜:作轴 x=null(组件不画、注脚报数),分组归 (unset)
+    // 未声明 flag 的 experiment 不猜:作轴 x=null(组件不画、注脚报数),分组归 (unset)
     const legacyRow = data.rows.find((r) => r.key === "ultra/legacy")!;
     expect(legacyRow.x).toBeNull();
     expect(legacyRow.xDisplay).toBe("");
     expect(legacyRow.series).toBe("(unset)");
   });
 
-  it("param 当维度用:按声明值分组,label 函数折组名", async () => {
-    const s1 = withParams("exp/a", { agents: 1 }, "passed");
-    const s2 = withParams("exp/b", { agents: 16 }, "failed");
+  it("flag 当维度用:按声明值分组,label 函数折组名", async () => {
+    const s1 = withFlags("exp/a", { agents: 1 }, "passed");
+    const s2 = withFlags("exp/b", { agents: 16 }, "failed");
     const data = await MetricTable.data([s1, s2], {
-      rows: param("agents", { label: (v) => `${v} agents` }),
+      rows: flag("agents", { label: (v) => `${v} agents` }),
       columns: [passRate],
     });
     expect(data.dimension).toBe("agents");

package/src/report/report.ts

@@ -18,7 +18,7 @@ import {
 import { prepareDefaultReportData, runWithDefaultReportData } from "./default-report.tsx";
 
 export interface ReportContext {
-  /** results.latest() 挑好的选集:现刻水位快照 + 结构化挑选警告,同官方榜单口径。 */
+  /** results.latest() 挑好的选集:现刻水位快照 + 结构化挑选警告,同默认报告口径。 */
   selection: Selection;
   /** 默认挑法不合口径时,全量数据自己挑(见 docs/results-lib.md)。 */
   results: Results;

package/src/report/types.ts

@@ -1,4 +1,4 @@
-// niceeval/report 的公开类型:指标(Metric)、维度(Dimension / param())与计算函数
+// niceeval/report 的公开类型:指标(Metric)、维度(Dimension / flag())与计算函数
 // 产物(即组件的 data props)。数据契约照 docs/reports.md「计算函数与数据契约」;
 // 这些不是持久化格式,没有 format / schemaVersion 信封,兼容性跟随 npm 版本。
 
@@ -66,20 +66,20 @@ export type Dimension =
   | { name: string; of: (attempt: AttemptHandle) => string };
 
 /**
- * param() 的产物:把 experiment 声明的 params 当维度(series / rows / columns / points
+ * flag() 的产物:把 experiment 声明的 flags 当维度(series / rows / columns / points
  * 槽,按声明值分组)或轴(MetricLine 的 x 槽,要求数值并驱动刻度)。
- * 未声明该 param 的 experiment 不猜:分组如实归「(unset)」,作轴不画点、注脚报数。
+ * 未声明该 flag 的 experiment 不猜:分组如实归「(unset)」,作轴不画点、注脚报数。
  */
-export interface ParamRef {
-  readonly kind: "param";
+export interface FlagRef {
+  readonly kind: "flag";
   readonly name: string;
   /** 组标签 / 轴标签;函数形态把声明值折成组名(如 `(v) => \`${v} agents\``)。 */
   readonly label?: string | ((value: string | number | boolean) => string);
   readonly unit?: string;
 }
 
-/** 维度槽的输入:内置/自定义维度,或 experiment 声明的 param。 */
-export type DimensionInput = Dimension | ParamRef;
+/** 维度槽的输入:内置/自定义维度,或 experiment 声明的 flag。 */
+export type DimensionInput = Dimension | FlagRef;
 
 // ───────────────────────── 计算产物(组件 data props)─────────────────────────
 
@@ -174,9 +174,9 @@ export interface ScatterData {
   }[];
 }
 
-/** MetricLine 的 x 轴:experiment 声明的 param,数值驱动刻度。 */
+/** MetricLine 的 x 轴:experiment 声明的 flag,数值驱动刻度。 */
 export interface LineAxis {
-  /** param 名。 */
+  /** flag 名。 */
   key: string;
   label: string;
   unit?: string;
@@ -184,14 +184,14 @@ export interface LineAxis {
 
 export interface LineData {
   x: LineAxis;
-  /** 系列维度名(param 或普通维度)。 */
+  /** 系列维度名(flag 或普通维度)。 */
   series?: string;
   y: MetricColumn;
   rows: {
     /** 点的键(experiment id):每个点 = 一个 experiment 的聚合。 */
     key: string;
     series?: string;
-    /** param 声明值;未声明或非数值 → null,点不画、注脚报数。 */
+    /** flag 声明值;未声明或非数值 → null,点不画、注脚报数。 */
     x: number | null;
     /** 已格式化的 x("300 ms");x 为 null 时为空串。 */
     xDisplay: string;

package/src/results/results.test.ts

@@ -600,7 +600,7 @@ describe("Artifacts reporter(writer 薄壳)", () => {
     const fresh: EvalResult = {
       id: "algebra/q1",
       experimentId: "compare/bub",
-      experiment: { id: "compare/bub", params: { style: "concise" } },
+      experiment: { id: "compare/bub", flags: { style: "concise" } },
       agent: "bub",
       model: "gpt-5.4",
       outcome: "passed",
@@ -707,7 +707,7 @@ describe("Artifacts reporter(writer 薄壳)", () => {
       "experimentId": "compare/bub",
       "experiment": {
         "id": "compare/bub",
-        "params": {
+        "flags": {
           "style": "concise"
         }
       },

package/src/runner/attempt.ts

@@ -24,6 +24,8 @@ import { captureGeneratedFiles, initGitAndCommit } from "./sandbox-prep.ts";
 import { createRemoteSandbox, withEvalLocalPaths } from "./remote-sandbox.ts";
 import type {
   AgentContext,
+  AgentSetup,
+  AgentTeardown,
   Cleanup,
   Config,
   EvalResult,
@@ -88,6 +90,9 @@ export function runAttemptEffect(
 
   return Effect.scoped(
     Effect.gen(function* () {
+      // run.sandbox ?? config.sandbox 是同一个 SandboxSpec 对象,既用来起沙箱后端,
+      // 也是 sandbox.setup / sandbox.teardown 钩子(SandboxSpec.setup()/.teardown() 链式挂的)的来源。
+      const sandboxSpec = run.sandbox ?? config.sandbox;
       const sandbox =
         run.agent.kind === "sandbox"
           ? yield* sandboxSem.withPermits(1)(
@@ -96,7 +101,7 @@ export function runAttemptEffect(
                 // sandboxSem 只覆盖「容器创建」阶段;容器起好后立即释放,后续 npm install / agent 不占位。
                 log(t("runner.startSandbox"));
                 return yield* createSandbox({
-                  sandbox: run.sandbox ?? config.sandbox,
+                  sandbox: sandboxSpec,
                   timeout: timeoutMs,
                   runtime: "node24",
                 });
@@ -161,6 +166,8 @@ export function runAttemptEffect(
       return yield* Effect.promise((interruptSignal) =>
         runAttemptBody(a, config, t0, base, {
           sandbox,
+          sandboxSetupHooks: sandboxSpec?.setupHooks ?? [],
+          sandboxTeardownHooks: sandboxSpec?.teardownHooks ?? [],
           receiver,
           telemetry,
           otel: otelChannel,
@@ -203,6 +210,10 @@ function causeToError(cause: Cause.Cause<never>): string {
 
 interface AttemptResources {
   sandbox: Sandbox;
+  /** SandboxSpec.setup() 链式挂的钩子,按追加顺序;非沙箱 agent 传空数组(usesSandbox 挡住不会跑)。 */
+  sandboxSetupHooks: readonly AgentSetup[];
+  /** SandboxSpec.teardown() 链式挂的钩子,按追加顺序保存,执行时逆序。 */
+  sandboxTeardownHooks: readonly AgentTeardown[];
   receiver?: TraceReceiver;
   telemetry?: Telemetry;
   /** 非沙箱 tracing agent 的共享 OTLP 通道(run 级池持有,不随 attempt 关)。 */
@@ -221,14 +232,15 @@ async function runAttemptBody(
   res: AttemptResources,
 ): Promise<EvalResult> {
   const { evalDef, run, attempt } = a;
-  const { sandbox, receiver, telemetry, otel, signal, log } = res;
+  const { sandbox, sandboxSetupHooks, sandboxTeardownHooks, receiver, telemetry, otel, signal, log } = res;
   const usesSandbox = run.agent.kind === "sandbox";
   // 整个 attempt 共用一份 agent ctx(sandbox 钩子 / agent setup / tracing configure / teardown 都用它)。
   const attemptCtx: AgentContext = {
     signal,
     model: run.model,
     reasoningEffort: run.reasoningEffort,
-    params: run.params,
+    flags: run.flags,
+    experimentId: run.experimentId,
     sandbox,
     session: createAgentSession(),
     telemetry,
@@ -236,8 +248,20 @@ async function runAttemptBody(
   };
   let agentCleanup: Cleanup | void = undefined;
   let agentDidSetup = false;
+  // SandboxSpec.setup() 返回的 cleanup 闭包,按调用顺序收集;finally 里 LIFO 跑(见下)。
+  const sandboxCleanups: Cleanup[] = [];
   try {
     if (usesSandbox) {
+      // 沙箱级生命周期钩子(SandboxSpec.setup):环境预置层,先于 workspace 上传 / git 基线 /
+      // eval.setup 跑——改动进 git 基线,不会被误算进 agent 产出的 diff。按追加顺序依次执行;
+      // 单个抛错走下面的执行错误路径(与 eval.setup / agent.setup 同一条),已跑过的 cleanup /
+      // sandbox.teardown 钩子仍在 finally 里跑(见 catch/finally)。
+      if (sandboxSetupHooks.length > 0) log(t("runner.startSandboxSetup"));
+      for (const hook of sandboxSetupHooks) {
+        const cleanup = await hook(sandbox, attemptCtx);
+        if (typeof cleanup === "function") sandboxCleanups.push(cleanup);
+      }
+
       await initGitAndCommit(sandbox);
 
       // eval 级 setup(starter prep:npm install / 装系统依赖等)。命令默认非 root;
@@ -270,7 +294,8 @@ async function runAttemptBody(
       sandbox,
       model: run.model,
       reasoningEffort: run.reasoningEffort,
-      params: run.params,
+      flags: run.flags,
+      experimentId: run.experimentId,
       signal,
       log,
       judge,
@@ -406,7 +431,8 @@ async function runAttemptBody(
     };
   } finally {
     // teardown / cleanup 一律在 finally 跑(失败也跑),不改判决,各自兜错(diagnostic)。
-    // LIFO:先 agent(setup 最晚),再沙箱 Scope。
+    // LIFO:agent 级(setup 最晚 → cleanup / teardown 先跑)在前,sandbox 级(最早就绪)收尾在后
+    //(即 sandbox.setup 返回的 cleanup、sandbox.teardown 钩子最后跑,沙箱销毁前)。
     // 沙箱 stop / 接收器 close 不在这里 —— 由 runAttemptEffect 的 Scope 在本函数返回后回收。
     try {
       if (typeof agentCleanup === "function") await agentCleanup();
@@ -414,6 +440,27 @@ async function runAttemptBody(
     } catch {
       // teardown 失败只是 diagnostic,不影响已出的结果
     }
+    if (usesSandbox) {
+      // sandbox.setup 返回的 cleanup:LIFO(后 setup 先 cleanup),与 agent 级同构。
+      for (let i = sandboxCleanups.length - 1; i >= 0; i--) {
+        try {
+          await sandboxCleanups[i]();
+        } catch {
+          // 同上,只作 diagnostic
+        }
+      }
+      // sandbox.teardown 钩子:按追加的逆序执行,沙箱销毁前最后一步。
+      if (sandboxTeardownHooks.length > 0) {
+        log(t("runner.startSandboxTeardown"));
+        for (let i = sandboxTeardownHooks.length - 1; i >= 0; i--) {
+          try {
+            await sandboxTeardownHooks[i](sandbox, attemptCtx);
+          } catch {
+            // 同上,只作 diagnostic
+          }
+        }
+      }
+    }
   }
 }
 
@@ -442,7 +489,7 @@ async function collectSources(
 function experimentRunInfo(run: AgentRun): EvalResult["experiment"] {
   return {
     id: run.experimentId,
-    params: run.params,
+    flags: run.flags,
     runs: run.runs,
     earlyExit: run.earlyExit,
     sandbox: run.sandbox === undefined ? undefined : sandboxLabel(run.sandbox),

package/src/runner/fingerprint.ts

@@ -38,7 +38,7 @@ export async function computeFingerprint(
       experimentId: run.experimentId,
       agent: run.agent.name,
       model: run.model,
-      params: run.params,
+      flags: run.flags,
       sandbox: run.sandbox === undefined ? undefined : sandboxLabel(run.sandbox),
       timeoutMs: run.timeoutMs,
       strict: run.strict,

package/src/runner/reporters/braintrust.test.ts

@@ -85,7 +85,7 @@ describe("toBraintrustEvent", () => {
         model: "gpt-5.2",
         attempt: 1,
         outcome: "failed",
-        experiment: { id: "compare/codex", params: { tape: true } },
+        experiment: { id: "compare/codex", flags: { tape: true } },
         assertions: [{ name: "compiles", severity: "gate", score: 0, passed: false, detail: "tsc failed" }],
       }),
     );
@@ -96,7 +96,7 @@ describe("toBraintrustEvent", () => {
       outcome: "failed",
       model: "gpt-5.2",
       experiment: "compare/codex",
-      params: { tape: true },
+      flags: { tape: true },
       failedAssertions: [{ name: "compiles", detail: "tsc failed" }],
     });
     expect(event.id).toBe("compare/codex|algebra/quadratic|codex|gpt-5.2|a1");

package/src/runner/reporters/braintrust.ts

@@ -113,7 +113,7 @@ export function Braintrust(config: BraintrustConfig = {}): Reporter {
  * - scores:soft 断言按名字记分,gate 断言记在 `gate:` 前缀下 —— 实验 diff 里
  *   gate 回归和 soft 分数回归用同一套机制看。重名断言追加 `#n` 消歧,不静默覆盖。
  * - metrics:start/end(Braintrust 由此算时长)+ token 用量 + 估算成本;缺就不写,不编 0。
- * - metadata:身份维度(agent / model / experiment / attempt / params)+ 失败断言明细。
+ * - metadata:身份维度(agent / model / experiment / attempt / flags)+ 失败断言明细。
  */
 export function toBraintrustEvent(result: EvalResult): BraintrustLogEvent {
   const scores: Record<string, number> = {};
@@ -150,8 +150,8 @@ export function toBraintrustEvent(result: EvalResult): BraintrustLogEvent {
   };
   if (result.model !== undefined) metadata.model = result.model;
   if (result.experimentId !== undefined) metadata.experiment = result.experimentId;
-  if (result.experiment?.params && Object.keys(result.experiment.params).length > 0) {
-    metadata.params = result.experiment.params;
+  if (result.experiment?.flags && Object.keys(result.experiment.flags).length > 0) {
+    metadata.flags = result.experiment.flags;
   }
   if (result.skipReason !== undefined) metadata.skipReason = result.skipReason;
   const failed = result.assertions

package/src/runner/run.ts

@@ -104,7 +104,7 @@ export async function runEvals(opts: RunOptions): Promise<RunSummary> {
         if (run.experimentId && priorRunKeys.has(`${run.experimentId}|${evalDef.id}`)) continue;
         // key 标识「同一个运行配置下的同一条 eval」,earlyExit 的跳过/abort 只应作用于
         // 同 key 的重试轮。experimentId 必须进 key:两个实验可以同 agent 同 model、只差
-        // params(feature A/B 正是这种形状),漏掉它会让先过的实验把其它实验的同名 eval
+        // flags(feature A/B 正是这种形状),漏掉它会让先过的实验把其它实验的同名 eval
         // 整个跳掉——花了钱还丢结果。
         const key = `${run.experimentId ?? ""}|${run.agent.name}|${run.model ?? ""}|${evalDef.id}`;
         attempts.push({

package/src/runner/types.ts

@@ -12,7 +12,7 @@ import type { TestContext } from "../context/types.ts";
 
 export interface ExperimentRunInfo {
   id?: string;
-  params?: Record<string, unknown>;
+  flags?: Record<string, unknown>;
   runs?: number;
   earlyExit?: boolean;
   sandbox?: string;
@@ -61,7 +61,7 @@ export interface EvalResult {
 /** `summary.json` 的格式标记;把 niceeval 报告和其它工具的同名文件区分开。 */
 export const RESULTS_FORMAT = "niceeval.results";
 /** 结果格式版本,只在破坏兼容读取时递增;读取器只认相同版本,缺失按 1。见 docs/results-format.md。 */
-export const RESULTS_SCHEMA_VERSION = 2;
+export const RESULTS_SCHEMA_VERSION = 3;
 
 export interface RunSummary {
   /** 恒为 "niceeval.results";和 schemaVersion、producer 一起构成持久化契约,永不移动或改名。 */
@@ -95,11 +95,11 @@ export interface RunSummary {
   snapshots?: Record<string, { startedAt?: string; knownEvalIds?: string[] }>;
 }
 
-/** onRunStart 的运行规模:去重后 eval 数 × 配置(agent×model×params)数 → 总运行(attempt)数。 */
+/** onRunStart 的运行规模:去重后 eval 数 × 配置(agent×model×flags)数 → 总运行(attempt)数。 */
 export interface RunShape {
   /** 去重后实际要跑的 eval 数(= evals.length)。 */
   evals: number;
-  /** (agent, model, params) 配置组合数;compare 多 agent 时 > 1。 */
+  /** (agent, model, flags) 配置组合数;compare 多 agent 时 > 1。 */
   configs: number;
   /** 总 attempt 数(evals × configs × runs);逐行输出与汇总计数都按它。 */
   totalRuns: number;
@@ -174,8 +174,8 @@ export interface ExperimentDef {
   model?: string;
   /** 模型推理努力程度(如 "low"/"medium"/"high",取值由具体模型/adapter 决定);省略=用 agent 原生默认。经 ctx.reasoningEffort 透给 adapter 与 eval。 */
   reasoningEffort?: string;
-  /** 传给每次 attempt 的 params,经 t.params 暴露给 eval;与 CLI flag 合并(CLI 优先)。 */
-  params?: Record<string, unknown>;
+  /** 实验条件(A/B 里的 feature flag),由实验文件声明;经 ctx.flags 透传给 adapter、t.flags 暴露给 eval。 */
+  flags?: Record<string, unknown>;
   /** 同一 eval 重复跑几次(结果各计一条 attempt);省略/CLI `--runs` 覆盖时默认 1。 */
   runs?: number;
   /** 一次重复(runs > 1)里某次 attempt 失败后是否跳过剩余重复;省略默认 true(提前退出省钱)。 */
@@ -267,12 +267,12 @@ export function runWho(run: Pick<AgentRun, "agent" | "model" | "experimentId">):
   return run.model ? `${run.agent.name}/${run.model}` : run.agent.name;
 }
 
-/** 一个 (agent, model, params) 的运行配置 —— 由 CLI / 实验展开。 */
+/** 一个 (agent, model, flags) 的运行配置 —— 由 CLI / 实验展开。 */
 export interface AgentRun {
   agent: Agent;
   model?: string;
   reasoningEffort?: string;
-  params: Record<string, unknown>;
+  flags: Record<string, unknown>;
   runs: number;
   earlyExit: boolean;
   sandbox?: SandboxOption;

package/src/sandbox/types.ts

@@ -1,6 +1,8 @@
 // sandbox 域类型:Sandbox 接口、后端 spec(可辨识联合)、命令与文件 IO 的形状。
 // 「在哪里跑、如何隔离」的全部契约在这里;后端实现见本目录各文件,分发见 resolve.ts。
 
+import type { AgentSetup, AgentTeardown } from "../agents/types.ts";
+
 export interface CommandResult {
   stdout: string;
   stderr: string;
@@ -51,25 +53,64 @@ export type SandboxBackend = "docker" | "vercel" | "e2b";
 /** 镜像/模板里的 Node 运行时版本。 */
 export type SandboxRuntime = "node20" | "node24";
 
+/**
+ * SandboxSpec 四个变体共有的沙箱生命周期钩子挂载点:`.setup(fn)` / `.teardown(fn)` 链式方法,
+ * 由 `dockerSandbox()` / `vercelSandbox()` / `e2bSandbox()` / `defineSandbox()` 产出的对象上
+ * 直接可调。
+ *
+ * **语义**:环境预置层,俗称「动态镜像层」——本想直接烘进镜像/快照/模板,但内容要按实验
+ * (`ctx.flags` / `ctx.experimentId`)动态变化的东西:装某个实验专属的二进制、预热缓存、
+ * 写运行期才知道内容的 hook 文件、按 `ctx.experimentId` 载入/回存跨 attempt 的状态。
+ *
+ * **与另外两层 setup 的分工**(三者都在同一个沙箱生命周期里,各管一层):
+ *   · `sandbox.setup`(这里)—— 环境层,不知道具体跑哪个 eval / 接哪个 agent;
+ *   · `eval.setup` —— 任务层,准备这次 eval 的素材(如 `npm install` 起始项目依赖);
+ *   · `agent.setup` —— 协议层,接入被测 agent(装 CLI、写鉴权 / 模型配置)。
+ *
+ * **执行顺序**:沙箱就绪 → `sandbox.setup` 钩子 → workspace 上传 / git 基线 / `eval.setup` →
+ * `agent.setup` → `agent.tracing.configure` → 逐轮 `send`。`sandbox.setup` 特意排在 git
+ * 基线之前——它的改动会被提交进基线,不会被误算进 agent 产出的 diff。收尾按 LIFO:
+ * agent 级 cleanup / `agent.teardown` 先跑,`sandbox.teardown` 钩子最后跑(沙箱销毁前)。
+ *
+ * **多钩子**:`.setup(a).setup(b)` 按追加顺序依次执行(a 先 b 后);`.teardown(x).teardown(y)`
+ * 按追加的**逆序**执行(y 先 x 后)。每次调用都返回一个新 spec(不改变原对象),可继续链式。
+ *
+ * **失败语义**:`setup` 钩子抛错按执行错误计——与 `eval.setup` / `agent.setup` 抛错走同一条
+ * 路径,不新增错误分类;但不阻断该 attempt 已进入的收尾(已跑过的 setup 返回的 cleanup、
+ * `teardown` 钩子仍会在 finally 里跑)。`teardown` 钩子报错只作诊断(吞掉 / 记 log),不改变
+ * 已产出的结果——与 `agent.teardown` 现状一致。
+ */
+export interface SandboxHooks<Self> {
+  /** 已挂载的 setup 钩子,按追加顺序保存(内部读取,一般用不到)。 */
+  readonly setupHooks?: readonly AgentSetup[];
+  /** 已挂载的 teardown 钩子,按追加顺序保存,执行时逆序(内部读取,一般用不到)。 */
+  readonly teardownHooks?: readonly AgentTeardown[];
+  /** 追加一个沙箱级 setup 钩子,返回新 spec;详细契约见 {@link SandboxHooks}。 */
+  setup(fn: AgentSetup): Self;
+  /** 追加一个沙箱级 teardown 钩子,返回新 spec;详细契约见 {@link SandboxHooks}。 */
+  teardown(fn: AgentTeardown): Self;
+}
+
 /**
  * Sandbox 的「数据结构」定义 —— 与 agent 一样可带参数(见 docs/sandbox.md)。
  * 必须用工厂函数构造(`dockerSandbox()` / `vercelSandbox()` / `e2bSandbox()` / `defineSandbox()`),
  * 放进 config / experiment 的 `sandbox` 字段 —— 字段类型只接受这个数据结构,不接受裸字符串。
  * 各后端的参数互不相同 —— 这是个按 `backend` 区分的可辨识联合(discriminated union)。
+ * 四个变体都带 {@link SandboxHooks} 的 `.setup()` / `.teardown()` 链式方法。
  */
-export interface DockerSandboxSpec {
+export interface DockerSandboxSpec extends SandboxHooks<DockerSandboxSpec> {
   readonly backend: "docker";
   /** 覆盖默认镜像;默认按 runtime 选 `node:*-slim`。预制模板:传烘焙好 agent CLI 的镜像名。 */
   readonly image?: string;
   readonly runtime?: SandboxRuntime;
 }
-export interface VercelSandboxSpec {
+export interface VercelSandboxSpec extends SandboxHooks<VercelSandboxSpec> {
   readonly backend: "vercel";
   /** 从已有快照起 microVM。预制模板:烘焙好 agent CLI 的 snapshotId。 */
   readonly snapshotId?: string;
   readonly runtime?: SandboxRuntime;
 }
-export interface E2BSandboxSpec {
+export interface E2BSandboxSpec extends SandboxHooks<E2BSandboxSpec> {
   readonly backend: "e2b";
   /** e2b 模板名/ID。预制模板:烘焙好 agent CLI 的模板(如 `"niceeval-agents"`)。省略用 e2b 默认 `"base"`。 */
   readonly template?: string;
@@ -80,7 +121,7 @@ export interface E2BSandboxSpec {
  * 用户自定义后端:`create` 直接产出一个 `Sandbox` 实例,不经 resolve.ts 的内置 backend switch。
  * 用 `defineSandbox()` 构造(见 src/define.ts)。`backend` 只用于展示 / 日志,不参与分发。
  */
-export interface CustomSandboxSpec {
+export interface CustomSandboxSpec extends SandboxHooks<CustomSandboxSpec> {
   readonly backend: string;
   readonly runtime?: SandboxRuntime;
   readonly recommendedConcurrency?: number;

package/src/show/compose.ts

@@ -4,7 +4,7 @@
 // results.latest() 只挑「每实验最新快照」,带 eval 前缀的局部重跑会产出残缺快照;
 // 榜单承诺「不会因为一次局部重跑变残缺」,所以宿主在实验的全部历史快照上逐 eval
 // 向更早的 run 补齐,再把合成好的选集注入报告槽——内置默认报告与 --report 吃同一份,
-// 官方榜单口径 = 宿主注入口径。本文件只消费 niceeval/results 的读取面。
+// 默认报告口径 = 宿主注入口径。本文件只消费 niceeval/results 的读取面。
 
 import { foldEvalOutcome } from "../shared/outcome.ts";
 import { evalPrefixPredicate } from "../report/aggregate.ts";

package/src/view/app/App.tsx

@@ -15,7 +15,7 @@ import { Tabs, TabsContent, TabsList, TabsTrigger } from "./components/ui/tabs.t
 import { RunsView } from "./pages/RunsPage.tsx";
 import { TracesView } from "./pages/TracesPage.tsx";
 
-// 报告槽只有一个:默认装官方榜单(Experiments tab);--report 整槽替换成用户报告。
+// 首页报告只有一份:不传 --report 时是默认报告(Experiments tab),传了整页替换成用户报告。
 // 证据室(Runs / Traces / AttemptModal)是 view 本体,两种模式下原样保留。
 export const navItems: { id: Tab; label: MessageKey }[] = [
   { id: "experiments", label: "nav.experiments" },

package/src/view/app/css.d.ts

@@ -0,0 +1,3 @@
+// TS7 默认开启 noUncheckedSideEffectImports,CSS 副作用导入(main.tsx 引 styles.css,
+// 由 Vite 处理)需要显式模块声明才能通过 typecheck。
+declare module "*.css";

package/src/view/app/i18n.ts

@@ -58,7 +58,7 @@ export type MessageKey =
   | "detail.rawSample"
   | "detail.rawNote"
   | "config.experiment"
-  | "config.paramsNone"
+  | "config.flagsNone"
   | "config.default"
   | "config.none"
   | "config.notApplicable"
@@ -177,7 +177,7 @@ const dictionaries: Record<Locale, Dictionary> = {
     "detail.rawSample": "Raw sample result",
     "detail.rawNote": "debug JSON, defaults to first error/failure when available",
     "config.experiment": "experiment",
-    "config.paramsNone": "none",
+    "config.flagsNone": "none",
     "config.default": "default",
     "config.none": "none",
     "config.notApplicable": "n/a",
@@ -293,7 +293,7 @@ const dictionaries: Record<Locale, Dictionary> = {
     "detail.rawSample": "原始样例结果",
     "detail.rawNote": "调试 JSON，默认选择第一条错误/失败",
     "config.experiment": "实验",
-    "config.paramsNone": "无",
+    "config.flagsNone": "无",
     "config.default": "默认",
     "config.none": "无",
     "config.notApplicable": "不适用",

package/src/view/app/lib/rows.ts

@@ -10,7 +10,7 @@ import { evalLevelStats } from "../../../shared/outcome.ts";
 import { displayExperimentName, fallbackExperimentLabel, sumMaybe } from "../../../shared/aggregate.ts";
 import { formatConfigValue } from "./format.ts";
 
-/** 官方榜单格子的列键(= 内置指标的 metric.name,见 src/report/metrics.ts)。 */
+/** 默认报告格子的列键(= 内置指标的 metric.name,见 src/report/metrics.ts)。 */
 export const CELL_KEYS = {
   passRate: "pass-rate",
   duration: "duration",
@@ -127,9 +127,9 @@ export function valueFor(row: ViewRow, key: SortKey): string | number | null {
 
 export function configChips(row: ViewRow, t: T): [string, ReactNode][] {
   const exp = row.experiment || {};
-  const params = exp.params && Object.keys(exp.params).length
-    ? Object.entries(exp.params).map(([k, v]) => k + "=" + formatConfigValue(v)).join(", ")
-    : t("config.paramsNone");
+  const flags = exp.flags && Object.keys(exp.flags).length
+    ? Object.entries(exp.flags).map(([k, v]) => k + "=" + formatConfigValue(v)).join(", ")
+    : t("config.flagsNone");
   return [
     [t("config.experiment"), row.synthetic ? row.label : row.experimentId],
     [t("table.model"), row.model || t("config.default")],
@@ -138,6 +138,6 @@ export function configChips(row: ViewRow, t: T): [string, ReactNode][] {
     ["earlyExit", exp.earlyExit === undefined ? t("config.notApplicable") : String(exp.earlyExit)],
     ["sandbox", exp.sandbox || t("config.default")],
     ["budget", exp.budget === undefined ? t("config.none") : "$" + exp.budget],
-    ["params", params],
+    ["flags", flags],
   ];
 }

package/src/view/app/types.ts

@@ -48,7 +48,7 @@ export interface ViewRow {
   model?: string;
   /** 该快照的 startedAt(ISO)—— 榜单「每行带判决产生的时间」。 */
   lastRunAt: string;
-  /** 官方榜单格子(pass-rate / duration / tokens / cost),display 已格式化。 */
+  /** 默认报告格子(pass-rate / duration / tokens / cost),display 已格式化。 */
   cells: Partial<Record<string, MetricCell>>;
   /** 快照内 attempt 总数。 */
   runs: number;