niceeval 0.8.1 → 0.9.0

package/dist/results/select.js

@@ -4,9 +4,14 @@
 // 选择器必须诚实:残缺、落后、未收尾都被算出来,以结构化 warnings 随 Scope 走 ——
 // 渲染与否在消费方(message 是渲染好的英文句子,以下一步收尾),但缺口不静默。
 import { evalPrefixPredicate } from "../shared/aggregate.js";
-/** Results.latest() 的实现:每个实验取最新一次快照(= exp.snapshots[0]),生成挑选警告。 */
-export function selectLatest(experiments, opts) {
-    const selected = filterExperiments(experiments, opts?.experiments);
+/**
+ * Results.latest() 的实现:每个实验取最新一次快照(= exp.snapshots[0]),生成挑选警告。
+ * 收整个 `Results` 而不是裸 `Experiment[]`,是为了同时取 `skipped` / `root` 生成
+ * `unreadable-snapshot` 警告(非实验作用域,不受 `opts.experiments` 过滤 —— 那些落盘
+ * 本来就没能解析出 experimentId,没有前缀可过滤)。
+ */
+export function selectLatest(results, opts) {
+    const selected = filterExperiments(results.experiments, opts?.experiments);
     const snapshots = selected.map((exp) => exp.latest);
     const warnings = [];
     // stale 的基准:Scope 中最新的落盘(无阈值,如实触发;要阈值消费方按字段自比)。
@@ -52,6 +57,7 @@ export function selectLatest(experiments, opts) {
             });
         }
     }
+    warnings.push(...unreadableSnapshotWarnings(results.skipped, results.root));
     return makeScope("latest-snapshots", snapshots, warnings);
 }
 /** 一个快照的可比性配置投影;pairsByFlag 与 experimentListData 复用同一字段集。 */
@@ -188,8 +194,61 @@ export function selectCurrentResults(results, scope = {}) {
             });
         }
     }
+    warnings.push(...unreadableSnapshotWarnings(results.skipped, results.root));
     return makeScope("current-evals", snapshots, warnings);
 }
+/**
+ * `results.skipped` 里每一条不可读落盘 → 一条 `unreadable-snapshot` ScopeWarning。
+ * 非实验作用域(没有 experimentId 字段):`latest()` / `current()` 都原样带上全部
+ * `skipped` 条目,不受 `opts.experiments` 前缀过滤影响(那些落盘本来就没能解析出
+ * experimentId,没有前缀可比);`makeScope().filter()` 按「非实验作用域的警告保留」
+ * 规则自动放行,不需要额外分支。
+ */
+function unreadableSnapshotWarnings(skipped, root) {
+    return skipped.map((s) => {
+        switch (s.reason) {
+            case "incompatible-version": {
+                const producer = s.producer;
+                const schemaText = s.schemaVersion !== undefined ? ` (schemaVersion ${s.schemaVersion})` : "";
+                if (producer?.name === "niceeval" && producer.version) {
+                    const command = `npx niceeval@${producer.version} show --results ${root}`;
+                    return {
+                        kind: "unreadable-snapshot",
+                        dir: s.dir,
+                        reason: s.reason,
+                        message: `snapshot at "${s.dir}" was written by niceeval ${producer.version}${schemaText} and cannot be read by this version; run \`${command}\` to open it`,
+                        command,
+                    };
+                }
+                const writtenBy = producer?.name
+                    ? `${producer.name}${producer.version ? ` ${producer.version}` : ""}`
+                    : "an incompatible tool version";
+                return {
+                    kind: "unreadable-snapshot",
+                    dir: s.dir,
+                    reason: s.reason,
+                    message: `snapshot at "${s.dir}" was written by ${writtenBy}${schemaText} and cannot be read by this version; open it with the tool version that produced it`,
+                };
+            }
+            case "malformed": {
+                const detail = s.detail ? ` (${s.detail})` : "";
+                return {
+                    kind: "unreadable-snapshot",
+                    dir: s.dir,
+                    reason: s.reason,
+                    message: `snapshot at "${s.dir}" is malformed${detail} and was skipped; inspect snapshot.json in that directory for corrupted JSON or a missing required field`,
+                };
+            }
+            case "incomplete":
+                return {
+                    kind: "unreadable-snapshot",
+                    dir: s.dir,
+                    reason: s.reason,
+                    message: `snapshot at "${s.dir}" has attempt data but no snapshot.json (likely interrupted before metadata was written) and was skipped; inspect ${s.dir} — completed attempts remain on disk for manual review`,
+                };
+        }
+    });
+}
 /**
  * Scope 构造:attempts 按口径物化(快照 attempts 的平铺);filter 只删不换 —— 快照删减,
  * attempts 随之同步修剪,warnings 修剪规则是「experimentId 不在幸存快照中的丢弃,
@@ -261,18 +320,24 @@ export function filterExperiments(experiments, filter) {
     const prefixes = (Array.isArray(filter) ? filter : [filter]).map((p) => p.replace(/\/+$/, ""));
     return experiments.filter((exp) => prefixes.some((p) => exp.id === p || exp.id.startsWith(p + "/")));
 }
-/** stale 警告的人话时距:选粒度最大的单位,四舍五入。 */
-function humanizeGap(fromIso, toIso) {
+/**
+ * stale 警告的人话时距:选粒度最大的单位,四舍五入。结构化形态是单源——message 的英文时距
+ * 与 ScopeWarnings 徽标的本地化时距都从这里出,阈值不写两份。
+ */
+export function gapParts(fromIso, toIso) {
     const ms = Math.max(0, Date.parse(toIso) - Date.parse(fromIso));
     const seconds = Math.round(ms / 1000);
     if (seconds < 90)
-        return `${seconds} second${seconds === 1 ? "" : "s"}`;
+        return { n: seconds, unit: "second" };
     const minutes = Math.round(seconds / 60);
     if (minutes < 90)
-        return `${minutes} minute${minutes === 1 ? "" : "s"}`;
+        return { n: minutes, unit: "minute" };
     const hours = Math.round(minutes / 60);
     if (hours < 36)
-        return `${hours} hour${hours === 1 ? "" : "s"}`;
-    const days = Math.round(hours / 24);
-    return `${days} day${days === 1 ? "" : "s"}`;
+        return { n: hours, unit: "hour" };
+    return { n: Math.round(hours / 24), unit: "day" };
+}
+function humanizeGap(fromIso, toIso) {
+    const { n, unit } = gapParts(fromIso, toIso);
+    return `${n} ${unit}${n === 1 ? "" : "s"}`;
 }

package/dist/results/types.d.ts

@@ -142,6 +142,12 @@ export interface SkippedDir {
 }
 /** openResults 的返回:experiments 分层;skipped 不静默丢。 */
 export interface Results {
+    /**
+     * 结果根目录的绝对路径(`openResults()` 入参解析后的原样值,不论传入的是结果根、
+     * 实验目录、快照目录还是某个 snapshot.json)。`unreadable-snapshot` 警告拼版本化
+     * `command`(`npx niceeval@<version> show --results <root>`)时取它。
+     */
+    root: string;
     /** 每个实验一项,挂着自己的全部历史(id 字典序)。 */
     experiments: Experiment[];
     skipped: SkippedDir[];
@@ -218,6 +224,26 @@ export type ScopeWarning = {
     message: string;
     /** 一条可复制即跑的推进命令:`niceeval exp <experimentId>`。 */
     command: string;
+} | {
+    /**
+     * 扫描结果根遇到的不可读快照:schema 不兼容、JSON 损坏 / 必需字段错误(malformed)、
+     * attempt 已写入但缺 `snapshot.json`(incomplete)。该快照被跳过,不挡其余结果
+     * (非 niceeval JSON 静默忽略,不产生这个 kind)。非实验作用域(没有 experimentId
+     * 字段) —— `Scope.filter()` 修剪时恒保留。
+     */
+    kind: "unreadable-snapshot";
+    /** 该快照目录的绝对路径。 */
+    dir: string;
+    /** 与 `SkippedDir.reason` 同一取值集,原样透传。 */
+    reason: "incompatible-version" | "malformed" | "incomplete";
+    message: string;
+    /**
+     * 只有 reason 为 `incompatible-version` 且能确定是 niceeval 自己产出(`producer.name
+     * === "niceeval"` 且带 `producer.version`)时给出:`npx niceeval@<version> show --results
+     * <root>`。第三方 producer、版本信息缺失,或 reason 为 malformed / incomplete 时省略——
+     * 这些情况没有单条命令能解决,message 改给定位动作。
+     */
+    command?: string;
 };
 /** dedupeAttempts 的警告:身份键缺 startedAt,宁可不去重也不误删。 */
 export interface DedupeWarning {

package/dist/runner/fingerprint.d.ts

@@ -1,11 +1,11 @@
-import type { DiscoveredEval, EvalResult } from "../types.ts";
+import type { DiscoveredEval, EvalResult, SandboxOption } from "../types.ts";
 import type { AgentRun } from "./types.ts";
 export declare function cacheKey(run: AgentRun, evalId: string): string;
 /**
  * @param sourceCache 按 sourcePath 缓存文件内容:一个矩阵(实验 × eval)会对同一批源文件
  * 反复算指纹,不带缓存会在任何 attempt 起跑前做 E×N 次重复文件读。
  */
-export declare function computeFingerprint(evalDef: DiscoveredEval, run: AgentRun, sourceCache?: Map<string, Promise<string>>): Promise<string>;
+export declare function computeFingerprint(evalDef: DiscoveredEval, run: AgentRun, sourceCache?: Map<string, Promise<string>>, configSandbox?: SandboxOption): Promise<string>;
 export interface CarryPlan {
     /** `cacheKey(run, evalId)` → 本次规划出的指纹,供调用方按同一口径判断"这条要不要携入"。 */
     plannedFingerprints: Map<string, string>;
@@ -20,4 +20,4 @@ export interface CarryPlan {
  * 不一致,live 表格就会显示"还在等名额",而 run.ts 其实已经把它筛掉、根本不会调度这个 attempt
  * (见 memory 的 live-carry-row-shows-waiting-forever)。
  */
-export declare function planCarry(evals: DiscoveredEval[], agentRuns: AgentRun[], priorResults: EvalResult[] | undefined): Promise<CarryPlan>;
+export declare function planCarry(evals: DiscoveredEval[], agentRuns: AgentRun[], priorResults: EvalResult[] | undefined, configSandbox?: SandboxOption): Promise<CarryPlan>;

package/dist/runner/sandbox-selection.d.ts

@@ -0,0 +1,12 @@
+import type { DiscoveredEval, SandboxOption, SandboxRunInfo } from "../types.ts";
+import type { AgentRun } from "./types.ts";
+/** 该 eval 实际起步的 spec:未声明 environment 用基础 spec;声明了则查表派生并缓存。 */
+export declare function sandboxForEval(run: AgentRun, evalDef: DiscoveredEval, fallback?: SandboxOption): SandboxOption | undefined;
+/** 在 dry-run / carry / concurrency / attempt 展开之前一次性查表;全部缺项一次穷举,不等到花费发生后才出现。 */
+export declare function prepareRunSandboxes(evals: DiscoveredEval[], runs: AgentRun[], fallback?: SandboxOption): void;
+/** ExperimentRunInfo 的 sandbox 投影:顶层恒为基础 spec;sandboxByEval 只含声明了 environment 的选中 eval。 */
+export declare function sandboxProjection(run: AgentRun, fallback?: SandboxOption): {
+    sandbox?: SandboxRunInfo;
+    sandboxByEval?: Record<string, SandboxRunInfo>;
+};
+export declare function resolvedSandboxRecommendedConcurrency(evals: DiscoveredEval[], runs: AgentRun[], fallback?: SandboxOption): number;

package/dist/runner/types.d.ts

@@ -25,11 +25,14 @@ export interface ExperimentRunInfo {
     /** evals 过滤器的指纹(数组内容 / 函数体哈希),供「配置没变」判断;与 selectedEvalIds 一起取代原过滤器。 */
     evalFilterFingerprint?: string;
     /** provider 名、provider 的公开参数投影与配置 fingerprint;参数只经投影落盘,token/凭据永不进来。 */
-    sandbox?: {
-        provider: string;
-        params?: Record<string, JsonValue>;
-        fingerprint?: string;
-    };
+    sandbox?: SandboxRunInfo;
+    /** spec 携带 environments 表时:声明了 environment 的选中 eval 各自解析到的产物投影,按 eval id 留审计映射;其余 eval 以 `sandbox` 为准。 */
+    sandboxByEval?: Record<string, SandboxRunInfo>;
+}
+export interface SandboxRunInfo {
+    provider: string;
+    params?: Record<string, JsonValue>;
+    fingerprint?: string;
 }
 /**
  * 一次 attempt 的生命周期词表——**全仓唯一一套**(见 docs/feature/results/architecture.md
@@ -309,6 +312,8 @@ export interface EvalDef {
     description?: string;
     /** 标签,供 CLI `--tag` 过滤和 view 分类;与 id 前缀过滤是两套独立的筛选维度。 */
     tags?: string[];
+    /** 这条 eval 需要的环境 profile id(provider-neutral,如 `"python-3.9-astropy-4.2"`);由 sandbox spec 的 `environments` 表翻译成该 provider 的预制产物。 */
+    environment?: string;
     /** 覆盖项目级 Config.judge,只对这一个 eval 生效(如换个更贵的评审模型)。 */
     judge?: JudgeConfig;
     /** 覆盖 / 追加项目级 Config.reporters,只对这一个 eval 生效。 */
@@ -377,7 +382,10 @@ export interface ExperimentDef {
     evals?: "*" | string[] | ((id: string) => boolean);
     /** 覆盖项目级 / CLI 的单次 attempt 超时(毫秒),只对这个实验生效。 */
     timeoutMs?: number;
-    /** 覆盖项目级 Config.sandbox,只对这个实验生效。 */
+    /**
+     * 覆盖项目级 Config.sandbox,只对这个实验生效。固定 SandboxSpec 对全部选中 eval 复用;
+     * spec 可携带 `environments` 表,按 eval 的 `environment` profile 换预制产物。
+     */
     sandbox?: SandboxOption;
     /**
      * 本实验的花费上限(USD)。调度器按「已完成 attempt 的实测花费」累计,到顶后跳过这个实验
@@ -474,6 +482,8 @@ export interface AgentRun {
     runs: number;
     earlyExit: boolean;
     sandbox?: SandboxOption;
+    /** environments 查表的规划期缓存(只含声明了 environment 的 selected eval);每条只派生一次。 */
+    resolvedSandboxes?: Map<string, SandboxOption>;
     timeoutMs?: number;
     budget?: number;
     evalFilter: (id: string) => boolean;
@@ -534,6 +544,8 @@ export interface Attempt {
     /** agent+model+evalId,用于首过即停。 */
     key: string;
     fingerprint: string;
+    /** 规划期按 eval 的 environment 查表派生的具体 spec；attempt 生命周期不再重新查表。 */
+    sandboxSpec?: SandboxOption;
     /**
      * 构造 fresh attempt plan 时即算好的 Attempt 定位符(不是完成后写回):由 invocation 的
      * snapshotStartedAt 与 attempt 身份派生,贯穿执行、留存登记与落盘——登记项、run 收尾反馈与

package/dist/sandbox/types.d.ts

@@ -109,18 +109,30 @@ export interface DockerSandboxSpec extends SandboxHooks<DockerSandboxSpec> {
     readonly provider: "docker";
     /** 覆盖默认镜像;默认按 runtime 选 `node:*-slim`。预制模板:传烘焙好 agent CLI 的镜像名。 */
     readonly image?: string;
+    /** 按 eval 的 `environment` profile 覆盖预制镜像:键为 profile id,值为该 profile 起步的镜像。未声明 environment 的 eval 用 `image`。 */
+    readonly environments?: Readonly<Record<string, {
+        readonly image: string;
+    }>>;
     readonly runtime?: SandboxRuntime;
 }
 export interface VercelSandboxSpec extends SandboxHooks<VercelSandboxSpec> {
     readonly provider: "vercel";
     /** 从已有快照起 microVM。预制模板:烘焙好 agent CLI 的 snapshotId。 */
     readonly snapshotId?: string;
+    /** 按 eval 的 `environment` profile 覆盖预制快照:键为 profile id,值为该 profile 起步的 snapshotId。未声明 environment 的 eval 用 `snapshotId`。 */
+    readonly environments?: Readonly<Record<string, {
+        readonly snapshotId: string;
+    }>>;
     readonly runtime?: SandboxRuntime;
 }
 export interface E2BSandboxSpec extends SandboxHooks<E2BSandboxSpec> {
     readonly provider: "e2b";
     /** e2b 模板名/ID。预制模板:烘焙好 agent CLI 的模板(如 `"niceeval-agents"`)。省略用 e2b 默认 `"base"`。 */
     readonly template?: string;
+    /** 按 eval 的 `environment` profile 覆盖预制模板:键为 profile id,值为该 profile 起步的模板。未声明 environment 的 eval 用 `template`。 */
+    readonly environments?: Readonly<Record<string, {
+        readonly template: string;
+    }>>;
     /** 仅作记录;e2b 的 node 版本由模板决定,不在创建时选。 */
     readonly runtime?: SandboxRuntime;
 }

package/docs-site/zh/explanation/evals.mdx

@@ -28,6 +28,7 @@ export default defineEval({
 | 字段 | 说明 |
 |---|---|
 | `description` | 给人看的描述，出现在报告里 |
+| `environment` | 可选的环境需求 profile，由 sandbox spec 的 `environments` 表映射到具体预制环境 |
 | `test(t)` | 交互和断言逻辑 |
 
 eval 本身不声明用哪个 Agent——它默认保持 agent-neutral，同一个 eval 可以在不同 experiment 下跑不同 Agent。选哪个 Agent 是 experiment 的字段，不由 CLI 临时覆盖。
@@ -45,7 +46,7 @@ npx niceeval exp local weather
 npx niceeval exp local weather/brooklyn
 ```
 
-这种方式让 ID 稳定、可读，并自然跟目录结构保持一致。
+这种方式让 ID 稳定、可读，并自然跟目录结构保持一致。位置参数采用裸字符串前缀：`terminal-swe-bench` 也会命中 `terminal-swe-bench-astropy-1`，不要求后一个字符必须是 `/`。
 
 ## 生命周期
 

package/docs-site/zh/explanation/experiment.mdx

@@ -27,6 +27,8 @@ export default defineExperiment({
 
 Experiment 是纯配置数据，没有 `setup` / `teardown` 这类生命周期字段。要按实验准备环境（装二进制、预热、跨 attempt 存取状态），挂在 `sandbox` 字段的 spec 上——`dockerSandbox()` 等工厂返回的对象可以链 `.setup()` / `.teardown()`，见 [沙箱 provider · 环境钩子](/zh/how-to/sandbox-providers#环境钩子)。
 
+同一实验里的 eval 需要不同预制环境时，eval 只声明 provider-neutral 的 `environment` profile；sandbox spec 的 `environments` 表再把 profile 映射到 Docker image、E2B template 或 Vercel sandbox snapshot。这样任务需求留在 eval，provider 产物留在 spec，一个实验仍覆盖全部 eval、对比不拆分。写法见[写实验 · 让不同 eval 使用不同预制环境](/zh/how-to/write-experiment#让不同-eval-使用不同预制环境)。
+
 ## 矩阵对比
 
 要比较的每个变体写一个 experiment 文件：两个模型就是两个文件，只差 `model` 一行；prompt A/B 就是只差一个参数。同一批 eval 在多个 experiment 下各跑一遍，pass rate、成本、延迟就有了可比的横截面——`niceeval view` 里叠着看。适合比什么、结果怎么读，见[实验矩阵](/zh/how-to/experiments)。

package/docs-site/zh/how-to/custom-reports.mdx

@@ -8,12 +8,28 @@ description: "一份报告就是一个报告文件：官方宿主打开结果、
 
 一份报告就是一个报告文件。你不用打开结果目录、不用写渲染代码、不用起自己的应用：`niceeval show` / `niceeval view` 本体就是宿主——替你打开结果、把数据注入进来，你用官方组件和 `Row` / `Col` 摆版面，写完把文件路径递给 `--report`，终端和网页两扇门就都认它——官方的证据深链、`--results` 换根、静态导出，自定义报告全部原样享有。
 
-## show / view 的默认报告也是一份报告定义
+## show / view 的默认报告也是一份报告文件
 
-`niceeval show` / `view` 不传 `--report` 时渲染的默认报告不是私有实现，而是 `niceeval/report` 公开导出的一个值：
+`niceeval show` / `view` 不传 `--report` 时渲染的默认报告不是私有实现，而是包里自带的一个普通报告文件：三个页面（报告、Attempts、追踪），每页由 `niceeval/report` 公开导出的组件搭成——页首的标题区（`Hero`）、选择警告（`ScopeWarnings`），首页的比较组件 `ExperimentComparison`，Attempts 页的 Attempt 列表（`AttemptList`），追踪页的追踪瀑布（`TraceWaterfall`）。
+
+这份默认报告本身以 `standard` 为名从 `niceeval/report/built-in` 导出。只想在默认报告上加站点标题、GitHub 链接或统计脚本时，用 `extends` 在它上面叠自己的外壳，页面内容一行不用写；NiceEval 升级带来的页面改进也会自动跟过来：
+
+```tsx
+// reports/branded.tsx —— 默认报告整站 + 自己的标题和链接
+import { defineReport } from "niceeval/report";
+import { standard } from "niceeval/report/built-in";
+
+export default defineReport({
+  extends: standard,
+  title: "Memory Evals",
+  links: [{ label: "GitHub", href: "https://github.com/you/repo" }],
+});
+```
+
+`niceeval/report/built-in` 是内置报告的集合，每份一个名字；今天只有 `standard`，以后新增的内置报告也从这里按名字导入。想改页面内容本身，用同一批公开组件自己搭——你的报告文件能逐字写出同样的页面，也能只留自己要的部分：
 
 ```ts
-import { ExperimentComparison } from "niceeval/report";
+import { ExperimentComparison, Hero, ScopeWarnings } from "niceeval/report";
 ```
 
 `ExperimentComparison` 先按 experiment id 的父目录切成可比组，再为每组分别计算成本 × 端到端成功率散点图和实验明细表。`compare/bub` 与 `compare/codex` 可以同图，`dev-e2b/bub` 必须在另一个组；顶层 experiment 各自成为单例组。网页持有全部组并一次聚焦一组；终端命中多组时只列索引和单组查看命令，命中单组时才展开详情。两面都不会生成跨组总榜。
@@ -63,13 +79,13 @@ niceeval view --report reports/exam.tsx    # 网页：同一棵树走网页面
 
 报告文件里有两种数据形态。实体列表的 `.data(selection)` 返回普通数组：`ExperimentListItem[]`、`EvalListItem[]`、`AttemptListItem[]`。报告作者用 JavaScript `.filter()` / `.slice()` 决定展示哪些实体，再把数组作为 `items` 传给列表；组件不藏另一套过滤 DSL。指标图形和汇总组件收算好的 `data`；其中 `MetricScatter` 也提供 `selection` 简写，由宿主在渲染前计算。计算后的组件只渲染传入数据，不碰结果目录。
 
-挑选提醒（覆盖不全、快照过期、有没跑完的运行）不用你在报告里专门摆一个组件来显示：不管你的报告摆了哪些组件，`niceeval show` 和 `niceeval view` 都会把 `selection.warnings` 显示在报告正文上方，不会因为你没摆某一块就静默丢掉。
+挑选提醒（覆盖不全、快照过期、有没跑完的运行、读不出来的快照）由选择警告（`ScopeWarnings`）组件显示：提醒按实验归组，组头列出实验名、问题标签和一条可复制的重跑命令，每条提醒的原文收在组内可展开的折叠块里（提醒少时默认展开），读不出来的快照单独归成一组。默认报告每一页都摆了它；自己的报告想显示提醒，就在页首摆一个 `<ScopeWarnings />`——不摆就不显示，数字是否附带完整性提醒由你对读者负责。
 
 命令行的范围先作用在挑选上，报告拿到的就是收窄到这个范围后的 `selection`：位置参数的 eval id 前缀收窄 Selection 覆盖的 eval（覆盖提醒的分母同样收窄到范围内），`--results` 把结果根换成指定目录，`--experiment` 让 Selection 只留该实验。`--history` 与 `--report` 互斥——趋势在报告里用 `exp.snapshots` 自己摆；证据切面（`--eval` / `--execution` / `--diff`）只看证据，不渲染报告。
 
 页面里的每个组件都是**双面**的：网页面是 React 渲染，终端面是字符渲染，两面吃同一份算好的数据。实体列表按 experiment → Eval → Attempt 展示事实；指标表、矩阵、条形图、成绩单、散点图、趋势图和差异表展示聚合值。完整清单见[报告组件](/zh/reference/report-components)。网页面的实体、格子和点深链到 Attempt 详情，终端面印出对应的 `niceeval show <eval id>` 下钻命令。
 
-默认报告没有特权：它就是上面导出的 `ExperimentComparison`。你的报告和它同级；需要同样的“按目录分组、组内比较”摆法就直接引用它，不需要就不摆。自己直接组合 `MetricScatter` / `ExperimentList` 时，通用组件只消费你传入的数据，不会自动分组；把跨组 Selection 传进去就表示你明确要做跨组分析。
+默认报告没有特权：它的三个页面全部由公开组件搭成，你的报告和它同级。需要同样的“按目录分组、组内比较”摆法就直接写 `<ExperimentComparison />`，需要 Attempts 页就写带过滤的 `<AttemptList />`，不需要就不摆——包括页首标题区和 `Powered by NiceEval` 品牌行：它们分别是 `Hero` 和 `PoweredBy` 组件，用了就带、不用就没有，组件本身不提供开关。自己直接组合 `MetricScatter` / `ExperimentList` 时，通用组件只消费你传入的数据，不会自动分组；把跨组数据传进去就表示你明确要做跨组分析。
 
 ## 排版：Row 与 Col 在两个面都成立
 
@@ -395,4 +411,4 @@ niceeval view --report reports/exam.tsx --out site
 
 ## 界线：内置命令不长配置
 
-一次只渲染一份报告，`--report` 收显式文件路径——没有 `reports/` 目录自动发现、没有插件注册表、没有配置文件。自定义指标和自定义组件都住在你的报告文件里，随文件一起递入，宿主不为它们长任何注册面。不传 `--report` 时渲染的就是内置的 `ExperimentComparison`，你的报告和它是同级实现。
+一次只渲染一份报告，`--report` 收显式文件路径——没有 `reports/` 目录自动发现、没有插件注册表、没有配置文件。自定义指标和自定义组件都住在你的报告文件里，随文件一起递入，宿主不为它们长任何注册面。不传 `--report` 时渲染的就是默认报告，你的报告和它是同级实现。

package/docs-site/zh/how-to/publish-report.mdx

@@ -35,7 +35,7 @@ npx niceeval view --results report-data --out site
 
 ## 发布自定义报告
 
-不传 `--report` 时,发布出来的首页是默认报告。想让首页换成自己的报告,把 [`defineReport` 报告文件](/zh/how-to/custom-reports)传给 `--report` 就行——attempt 证据页(transcript、trace、代码视图)仍在同一个站里,报告里的每个数字点进去就是对应证据,和本地 `view --report` 看到的一模一样:
+不传 `--report` 时,发布出来的站点就是默认报告的三个页面(报告、Attempts、追踪)。想换成自己的页面,把 [`defineReport` 报告文件](/zh/how-to/custom-reports)传给 `--report` 就行——attempt 详情(transcript、trace、代码视图)仍在同一个站里,报告里的每个数字点进去就是对应证据,和本地 `view --report` 看到的一模一样:
 
 ```bash
 npx niceeval view --results report-data --report reports/exam.tsx --out site
@@ -45,12 +45,14 @@ npx niceeval view --results report-data --report reports/exam.tsx --out site
 
 ## 接站点分析与第三方脚本
 
-发布出去的站想挂 Google Analytics、埋点或评论组件,在报告文件的 `head` 字段里声明标签。厂商文档里的 snippet 逐字段照抄成对象就行——以 GA4 为例,官方给的两段 `<script>` 写成两个条目:
+发布出去的站想挂 Google Analytics、埋点或评论组件,在报告文件的 `head` 字段里声明标签。厂商文档里的 snippet 逐字段照抄成对象就行——以 GA4 为例,官方给的两段 `<script>` 写成两个条目。页面内容不用重写:默认报告以 `standard` 为名从 `niceeval/report/built-in` 导出,`extends` 它就是原样的默认站点加上你的标题和脚本:
 
 ```tsx
-import { ExperimentComparison, defineReport } from "niceeval/report";
+import { defineReport } from "niceeval/report";
+import { standard } from "niceeval/report/built-in";
 
 export default defineReport({
+  extends: standard,
   title: "Memory Evals",
   head: [
     { tag: "script", attrs: { async: true, src: "https://www.googletagmanager.com/gtag/js?id=G-XXXX" } },
@@ -64,7 +66,6 @@ export default defineReport({
       `,
     },
   ],
-  content: <ExperimentComparison />,
 });
 ```
 

package/docs-site/zh/how-to/viewing-results.mdx

@@ -323,7 +323,7 @@ compare/codex-gpt-5.4 · 5 runs · passed 2/5
 
 两次 run 的精确对比（这次修复具体翻转了哪些 eval）不做成 flag：用 `DeltaTable` 积木写一份报告递给 `--report`，几行就是一份自定义对比报告，终端和网页两扇门都认——内置命令只管固定摆法，自定义口径见[自定义报告](/zh/how-to/custom-reports)。
 
-## `niceeval view`：网页证据室
+## `niceeval view`：在网页看证据
 
 ```bash
 npx niceeval view
@@ -335,9 +335,9 @@ npx niceeval view
   失败后立刻运行 `npx niceeval view`，可以直接打开刚刚那次运行的 artifacts。
 </Tip>
 
-`view` 的首页是一份报告：不传 `--report` 时完整加载当前结果并显示全部可比组索引，选中一组后只显示该组的成本 × 端到端成功率散点图与实验表。切组只改变页面状态，不重新读取或计算；不同组不会混进同一张图或榜单。浏览器禁用 JS 时，每组作为独立的 `<details>` 完整可读；启用 JS 后一次聚焦一组。传了 `--report` 就换成你自己的报告（与 `show --report` 吃同一个文件），见[自定义报告](/zh/how-to/custom-reports)。证据部分（Attempt 弹窗、transcript、trace 瀑布、run 列表）始终保留。
+`view` 的首页是一份报告：不传 `--report` 时完整加载当前结果并显示全部可比组索引，选中一组后只显示该组的成本 × 端到端成功率散点图与实验表。切组只改变页面状态，不重新读取或计算；不同组不会混进同一张图或榜单。浏览器禁用 JS 时，每组作为独立的 `<details>` 完整可读；启用 JS 后一次聚焦一组。传了 `--report` 就换成你自己的报告（与 `show --report` 吃同一个文件），页面与导航完全由报告文件决定，见[自定义报告](/zh/how-to/custom-reports)。Attempt 详情（弹窗里的 transcript、时间树、trace、diff）始终可用——它是查看器自身的能力，报告里的每个数字点进去都是对应证据；默认报告另有 Attempts 列表页和追踪瀑布页，自己的报告要同款页面就摆同名组件。
 
-网页版多几样浏览操作：切换可比组、点表头就地排序、在当前组的过滤框里筛行、点开一个 experiment 行看它每道题的判定与原因、悬停散点看数值——这些只影响眼前的视图，不改判定口径，刷新即恢复。Attempt 弹窗里有与 `show --timing` 同源的统一时间树：Sandbox 启动、setup hook 及其 shell、agent 安装命令、每轮 send 与可关联的 OTel model/tool、评分与收尾都能逐层展开。报告上方有 **Copy fix prompt** 按钮，把全部失败打包成可直接粘给 coding agent 的修复 prompt（attempt 弹窗里有单条版）。报告文案有中英两份，随界面语言切换。
+网页版多几样浏览操作：切换可比组、点表头就地排序、在当前组的过滤框里筛行、点开一个 experiment 行看它每道题的判定与原因、悬停散点看数值——这些只影响眼前的视图，不改判定口径，刷新即恢复。Attempt 弹窗里有与 `show --timing` 同源的统一时间树：Sandbox 启动、setup hook 及其 shell、agent 安装命令、每轮 send 与可关联的 OTel model/tool、评分与收尾都能逐层展开。默认报告页里有 **Copy fix prompt** 按钮（`CopyFixPrompt` 组件，自己的报告可以直接摆同款），把全部失败打包成可直接粘给 coding agent 的修复 prompt（attempt 弹窗里有单条版）。报告文案有中英两份，随界面语言切换。
 
 ## 导出与静态托管
 

package/docs-site/zh/how-to/write-experiment.mdx

@@ -104,7 +104,7 @@ npx niceeval exp prompt-variants/concise
 | `timeoutMs` | 单个 attempt 的超时 |
 | `budget` | 这一格配置的预算上限 |
 | `maxConcurrency` | 这一格配置的并发上限 |
-| `sandbox` | sandbox agent 使用的 provider，如 `dockerSandbox()` / `e2bSandbox()`；spec 上可以链 `.setup()` / `.teardown()` 挂按实验变化的环境钩子 |
+| `sandbox` | sandbox agent 使用的固定 spec；spec 可带 `environments` 表按 eval 的环境 profile 换预制产物，也可以链 `.setup()` / `.teardown()` 挂环境钩子 |
 
 Experiment 本身是纯配置数据，没有 `setup` / `teardown` 这类字段。要在跑 agent 前按实验准备环境（装二进制、预热、跨 attempt 载入和回存状态），挂在 `sandbox` 字段的 spec 上：
 
@@ -122,4 +122,43 @@ export default defineExperiment({
 
 钩子的执行时机、多钩子顺序和失败语义见 [沙箱 provider · 环境钩子](/zh/how-to/sandbox-providers#环境钩子)。
 
+## 让不同 eval 使用不同预制环境
+
+一批真实任务可能需要不同版本的运行时和依赖。eval 用 `environment` 声明一个与 provider 无关的 profile ID；sandbox spec 的 `environments` 表再把它映射到具体模板或快照：
+
+```ts
+// evals/astropy-2021.eval.ts
+export default defineEval({
+  environment: "python-3.9-astropy-4.2",
+  async test(t) {
+    // 驱动任务并验证结果
+  },
+});
+```
+
+```ts
+// experiments/shared.ts —— 一个 provider 一张表，所有实验共用
+import { e2bSandbox } from "niceeval/sandbox";
+
+export const e2b = e2bSandbox({
+  template: "codex-default",              // 未声明 environment 的 eval 用它
+  environments: {
+    "python-3.9-astropy-4.2": { template: "codex-python39" },
+  },
+});
+```
+
+```ts
+// experiments/e2b.ts —— 实验保持一行 diff，覆盖全部 eval
+import { defineExperiment } from "niceeval";
+import { e2b } from "./shared";
+
+export default defineExperiment({
+  agent: codexAgent(),
+  sandbox: e2b,
+});
+```
+
+`environment` 是非空的稳定字符串，不是包版本约束。`environments` 表的值就是该 provider 预制产物字段的覆盖（Docker 的 `image`、E2B 的 `template`、Vercel 的 `snapshotId`）。NiceEval 在启动任何 Sandbox 前对所有选中的 eval 完成查表；某条 eval 声明的 profile 缺表项会在启动时一次性报出全部缺项。remote Agent 不创建 Sandbox，不参与查表。因为映射是随 spec 复用的数据，同一个实验能覆盖全部 eval——分数和对比表不会因为环境不同被拆成多个实验。
+
 跨配置比较的设计建议见[实验矩阵](/zh/how-to/experiments)。adapter 如何消费 `ctx.model` 和 `ctx.flags` 见[Adapter](/zh/explanation/adapter)。

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

@@ -41,7 +41,7 @@ description: "NiceEval 内置的 claude-code、codex、bub 适配器分别做到
 
 ### codex
 
-- 连接方式：沙箱里跑 `codex exec --json`（续接时是 `codex exec resume <id> --json`），stdout JSONL 当 transcript。
+- 连接方式：沙箱里跑 `codex exec --json`（续接时是 `codex exec resume <id> --json`），stdout JSONL 当 transcript。命令带 `--dangerously-bypass-approvals-and-sandbox` 与 `--dangerously-bypass-hook-trust`：沙箱里没人能回答 codex 的交互确认，插件或 `postSetup` 装好的 hook 因此不需要交互授信就能生效。
 - 鉴权：`CODEX_API_KEY`（不是 `OPENAI_API_KEY`），可选 `CODEX_BASE_URL` 接 OpenAI 兼容代理；配置项见下方 `CodexConfig`。
 - `tracing` 通过 `~/.codex/config.toml` 的 `[otel.trace_exporter.otlp-http]` 段配置，协议 `http/json`。
 
@@ -93,7 +93,8 @@ mcpServers?: McpServer[];
 ```
 
 额外 MCP server(每个沙箱 setup 时写进用户级 ~/.claude.json)。
-示例:&#123; name: "browser", command: "npx", args: ["-y", "@anthropic/mcp-browser"] &#125;
+stdio 形态写 command(可带 args / env);Streamable HTTP 形态写 url(可带 headers,
+逐字进请求头),落成 &#123; "type": "http", "url": …, "headers": … &#125; 条目。
 
 #### `skills`
 
@@ -125,6 +126,18 @@ niceeval 的项目根(含 `niceeval.config.ts` 的目录)解析,不是 Sandbox
 (不继承宿主机配置、不拼接、不重新序列化);保留键 `model` 与 `env` 出现在文件里
 setup 报错。manifest 只记项目相对路径与字节 SHA-256,不落正文。
 
+#### `postSetup`
+
+```ts
+postSetup?: SandboxHook[];
+```
+
+安装后按数组顺序运行的用户钩子(复用 SandboxHook 的窄上下文):在写 settings、挂 MCP、
+装 Skills / Plugin、写 manifest 全部完成后执行,适合跑插件自带的 setup 脚本这类
+「安装产物就位后才能跑」的过程动作。钩子返回的 cleanup 按 LIFO 与 teardown 一起收尾;
+抛错按基础设施错误计(attempt errored)。
+见 docs/feature/adapters/library/coding-agent-extensions.md「安装后运行脚本」。
+
 ### `CodexConfig`
 
 #### `apiKey`
@@ -150,7 +163,8 @@ mcpServers?: McpServer[];
 ```
 
 额外 MCP server(每个沙箱 setup 时追加进 ~/.codex/config.toml)。
-格式对应 codex config.toml 的 [mcp_servers.&lt;name&gt;] 表。
+stdio 形态(command/args/env)写 [mcp_servers.&lt;name&gt;] 的 command 行;
+Streamable HTTP 形态(url/headers)写 url 行,headers 进 [mcp_servers.&lt;name&gt;.http_headers] 子表。
 
 #### `skills`
 
@@ -184,6 +198,18 @@ niceeval 的项目根(含 `niceeval.config.ts` 的目录)解析,不是 Sandbox
 `model_reasoning_effort`、`mcp_servers`、`otel` 出现在文件里 setup 报错。manifest 只记
 项目相对路径与字节 SHA-256,不落正文。
 
+#### `postSetup`
+
+```ts
+postSetup?: SandboxHook[];
+```
+
+安装后按数组顺序运行的用户钩子(复用 SandboxHook 的窄上下文):在写主配置、挂 MCP、
+装 Skills / Plugin、写 manifest 全部完成后执行,适合跑插件自带的 setup 脚本这类
+「安装产物就位后才能跑」的过程动作。钩子返回的 cleanup 按 LIFO 与 teardown 一起收尾;
+抛错按基础设施错误计(attempt errored)。
+见 docs/feature/adapters/library/coding-agent-extensions.md「安装后运行脚本」。
+
 ### `BubConfig`
 
 #### `apiKey`
@@ -221,6 +247,17 @@ pythonPlugins?: PythonPluginSpec[];
 规范化后的 package 列表进安装 checkpoint key:plugin 集合不同的两个 agent 变体不会复用同一个
 安装 checkpoint(否则第二个变体会静默拿到第一个变体的环境)。
 
+#### `postSetup`
+
+```ts
+postSetup?: SandboxHook[];
+```
+
+安装后按数组顺序运行的用户钩子(复用 SandboxHook 的窄上下文):在装 bub、装 Skills /
+Python package、写 manifest 全部完成后执行。钩子返回的 cleanup 按 LIFO 与 teardown 一起
+收尾;抛错按基础设施错误计(attempt errored)。
+见 docs/feature/adapters/library/coding-agent-extensions.md「安装后运行脚本」。
+
 {/* GENERATED:END builtin-agent-config */}
 
 ## `uiMessageStreamAgent`：接 AI SDK 应用的内建无侵入 adapter（含 HITL）

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

@@ -97,7 +97,7 @@ npx niceeval exp compare-models weather
 | `--results` | string | `show` / `view` / `sandbox enter\|list\|stop` 共用:结果根目录(`.niceeval` 之外的另一个根,如 `copySnapshots` 产出的发布根)。 |
 | `--snapshot` | string | `view` 命令专用:只打开这一份快照文件(`snapshot.json`);文件不可读时命令失败(扫描模式只跳过)。 |
 | `--report` | string | `show` / `view` 命令专用:用文件默认导出的 `defineReport(...)` 替换两者共用的默认报告。 |
-| `--page` | string | `show` / `view` 命令专用:选择多页报告的页(页 id 见 `show --report` 的页索引);`view` 里定初始页。 |
+| `--page` | string | `show` / `view` 命令专用:选择报告的初始页;`show` 渲染该页并在尾部附其余页索引,`view` 以它作初始路由。未命中的页 id 按用法错误退出并列出可用页 id。 |
 | `--dry` | boolean | 只打印本次会匹配到的 eval × 运行配置,不实际执行(按下面 `--output` 选中的 profile 给出预览)。 |
 | `--output` | string | 反馈 profile:`auto`(默认)按环境自动选择,`human` / `agent` / `ci` 强制指定;只改变终端展示,不改变选择、调度、判定、artifact 或退出码。`auto` 依次判定:stderr 是 TTY → human;否则 `CI`(或其它常见 CI 平台环境变量)存在 → ci;否则 → agent。 |
 | `--force` | boolean | 忽略上次运行结果,不跳过已通过的 (experiment, eval) 组合,强制全部重跑。 |

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

@@ -52,6 +52,14 @@ tags?: string[];
 
 标签,供 CLI `--tag` 过滤和 view 分类;与 id 前缀过滤是两套独立的筛选维度。
 
+#### `environment`
+
+```ts
+environment?: string;
+```
+
+这条 eval 需要的环境 profile id(provider-neutral,如 `"python-3.9-astropy-4.2"`);由 sandbox spec 的 `environments` 表翻译成该 provider 的预制产物。
+
 #### `judge`
 
 ```ts