niceeval 0.13.3 → 0.13.4-canary.39

package/docs-site/zh/tutorials/custom-reports.mdx

@@ -1,9 +1,10 @@
 ---
 title: "编写自定义报告"
-description: "先定义 Analysis 统计口径，再用标准 React JSX 编写可在终端、网页和静态站阅读的 Report。"
+sidebarTitle: "编写自定义报告"
+description: "用内建统计口径写出第一个 Report，再添加自定义 Measure、详情 overlay 和项目默认配置。"
 ---
 
-自定义 Report 只负责页面和显示。Record 保存已发布事实，Analysis 定义总体、分母和缺失语义；Report 组织 `ClosedRows`、`MetricValue` 与关闭的 DomainView。
+这篇教程会先用内建的 `model` 和 `passRate` 写出一份可运行报告。跑通以后，再把业务统计口径拆成自定义 Measure，并了解详情 overlay。
 
 ```text
 Record → Sample → Analysis
@@ -15,9 +16,169 @@ Record → Sample → Analysis
   show：一个目标 Page       view / --out：全部 Page
 ```
 
-## 从 Measure 开始
+## 写出第一个 Page
 
-把业务统计口径定义在 Report 模块之外。Measure 决定分母、缺失和 Evidence；页面不应从数组长度重新计算通过率或成本。
+项目需要使用 React JSX。确认 `tsconfig.json` 包含下面的选项：
+
+```json
+{
+  "compilerOptions": {
+    "jsx": "react-jsx"
+  }
+}
+```
+
+新建 `reports/quality.tsx`。先直接使用 NiceEval 提供的维度和 Measure：
+
+```tsx
+import {
+  aggregate,
+  Bars,
+  Col,
+  defineComponent,
+  defineReport,
+  model,
+  passRate,
+  durationMs,
+  Section,
+  Table,
+  tokens,
+} from "niceeval/report";
+
+const QualityComparison = defineComponent(async (_props: {}, ctx) => {
+  const rows = await aggregate(ctx.scope, {
+    by: { model },
+    values: { passRate, durationMs, tokens },
+  });
+
+  return (
+    <Section title="模型质量">
+      <Col>
+        <Bars points={rows} x="model" y="passRate" />
+        <Table rows={rows} caption="各模型质量与用量" />
+      </Col>
+    </Section>
+  );
+});
+
+export default defineReport({
+  title: { en: "Quality", "zh-CN": "质量" },
+  pages: [{
+    id: "overview",
+    path: "/",
+    title: { en: "Overview", "zh-CN": "概览" },
+    presentation: "page",
+    render: () => <QualityComparison />,
+  }],
+});
+```
+
+Report module 必须默认导出 `defineReport()` 的结果。`ctx.scope` 是这次命令选中的固定 Sample；`aggregate()` 按模型分组，并为每组计算通过率、平均耗时和平均 Token 数。
+
+先用已有 Run 在终端检查这个 Page，再打开完整网页：
+
+```sh
+pnpm exec niceeval show --run <run-id> --report ./reports/quality.tsx
+pnpm exec niceeval view --run <run-id> --report ./reports/quality.tsx
+```
+
+第一条命令应打印“模型质量”和各模型的通过率。第二条命令会打开报告站；修改 `quality.tsx` 后，成功的 rebuild 会替换当前内容，失败时仍保留上一份可用报告。
+
+## 用 `aggregate()` 组装图表数据
+
+所有内建图表都读取 `aggregate()` 返回的同一批 rows。组装时只做三件事：
+
+1. `by` 决定一行代表什么，例如一个模型、Agent、Experiment 或评估用例。
+2. `values` 决定每行计算哪些指标，例如通过率、平均耗时和平均 Token 数。
+3. 图表的 `x`、`y` 与 `color` 引用这些字段名，不再读取或重新计算 Sample。
+
+下面这个输入会得到每个“模型 × Agent”一行的数据：
+
+```tsx
+const rows = await aggregate(ctx.scope, {
+  by: { model, agent },
+  values: { passRate, durationMs, tokens },
+});
+```
+
+每个指标格都是完整的 `MetricValue`，包含数值、状态、实际样本数和固定分母。把同一份 `rows` 交给多个图表，才能保证图和表使用相同口径。
+
+### 用柱状图比较通过率
+
+`Bars` 适合比较一个离散维度上的同一指标。`color` 可以把第二个维度拆成不同系列：
+
+```tsx
+import {
+  agent,
+  aggregate,
+  Bars,
+  model,
+  passRate,
+} from "niceeval/report";
+
+const rows = await aggregate(ctx.scope, {
+  by: { model, agent },
+  values: { passRate },
+});
+
+return <Bars points={rows} x="model" y="passRate" color="agent" />;
+```
+
+同一个模型由多个 Agent 运行时，这张图会按 Agent 分色。若只想比较模型，删掉 `agent` 分组和 `color` 即可。
+
+### 用散点图找质量与速度的取舍
+
+`Scatter` 适合把两个连续指标放在一起。下面每个点代表一个 Experiment，横轴越靠左表示平均耗时越短，纵轴越靠上表示通过率越高：
+
+```tsx
+import {
+  aggregate,
+  durationMs,
+  experiment,
+  model,
+  passRate,
+  Scatter,
+} from "niceeval/report";
+
+const rows = await aggregate(ctx.scope, {
+  by: { experiment, model },
+  values: { durationMs, passRate },
+});
+
+return (
+  <Scatter
+    points={rows}
+    x="durationMs"
+    y="passRate"
+    color="model"
+  />
+);
+```
+
+### 用表格保留完整读数
+
+图表适合看趋势，`Table` 适合核对精确值和缺失状态。通常用 `Col` 把大图表和完整表格纵向排列：
+
+```tsx
+return (
+  <Col>
+    <Bars points={rows} x="model" y="passRate" color="agent" />
+    <Table
+      rows={rows}
+      columns={["model", "agent", "passRate", "durationMs", "tokens"]}
+      caption="模型与 Agent 对比"
+    />
+  </Col>
+);
+```
+
+`columns` 控制展示顺序，不会改变 rows 或统计口径。省略它时，`Table` 按 rows 的字段顺序显示全部列。
+
+`Grid` 是另一种选择，但不是另一套数据 API。它让每个直接子节点占一格，并根据宽度自动换列。截图里的摘要条就是 `<Grid><Stat ... /><Stat ... /></Grid>`。它适合 KPI 卡片或多个小面板；把 `Bars` 和大表格直接放进去时，两者也会各占一格，宽屏上可能并排，因此不是本教程的默认写法。
+
+## 定义自己的统计口径
+
+内建 Measure 不足时，把业务统计口径定义在 Report 模块之外。Measure 决定分母、缺失和 Evidence；页面不应从数组长度重新计算通过率或成本。
 
 ```ts
 // reports/quality-measures.ts
@@ -56,7 +217,7 @@ export const passRate = defineMeasure({
 });
 ```
 
-## 组织一个 Page
+## 在 Page 中使用自定义 Measure
 
 Report 模块是 `.tsx` 文件，并使用 TypeScript 的 `"jsx": "react-jsx"`。组合组件通过 `ctx.scope` 获得这次选择固定的 Sample。组件和 Page 不获得 Record reader、文件路径或浏览器请求能力。
 
@@ -65,9 +226,9 @@ Report 模块是 `.tsx` 文件，并使用 TypeScript 的 `"jsx": "react-jsx"`
 import {
   aggregate,
   Bars,
+  Col,
   defineComponent,
   defineReport,
-  Grid,
   Table,
 } from "niceeval/report";
 import { experiment, passRate } from "./quality-measures.ts";
@@ -79,10 +240,10 @@ const QualityComparison = defineComponent(async (_props: {}, ctx) => {
   });
 
   return (
-    <Grid>
+    <Col>
       <Bars points={rows} x="experiment" y="passRate" />
       <Table rows={rows} caption="实验通过率" />
-    </Grid>
+    </Col>
   );
 });
 
@@ -92,6 +253,7 @@ export default defineReport({
     id: "overview",
     path: "/",
     title: { en: "Overview", "zh-CN": "概览" },
+    presentation: "page",
     render: () => <QualityComparison />,
   }],
 });
@@ -153,7 +315,11 @@ Codex sealed Usage 含 `requestKind: "model"` observation。因此即使 model r
 
 ## 添加详情与显示原语
 
-需要多个详情地址时，定义参数 Page。`pages` 是唯一的页面集合，详情页必须在此显式声明；`params.enumerate(sample)` 只在 view 或静态导出时列出全部实例，Host 不会补建详情 route。`show --page <route>` 只执行请求的一个实例，并检查 `decode()` 后再 `encode()` 得到同一 canonical key。
+需要多个详情地址时，定义参数 Page。每个 Page 都要说明 `presentation`：独立业务页面使用 `"page"`，在当前页面上打开的 Attempt、Source 或 Diff 详情使用 `"overlay"`。
+
+`pages` 是唯一的页面集合，详情必须在此显式声明；`params.enumerate(sample)` 只在 view 或静态导出时列出全部实例，Host 不会补建详情。`show --page <route>` 只执行请求的一个实例，并检查 `decode()` 后再 `encode()` 得到同一 canonical key。
+
+浏览器中的 Report 只有一个根 document。业务 Page 和 overlay 通过 hash 导航；overlay 会保留当前业务 Page，按 Escape、点击关闭按钮或浏览器返回即可关闭。静态报告仍需要浏览器启用随包交付的 JavaScript。
 
 新的显示原语使用双面 `defineComponent()`：`resolve()` 最多取得一次关闭输入，`text()` 与 `web()` 同步读取同一个值。两个面不能各自再次调用 Analysis，也不能用网页专有内容代替终端文字。
 

package/docs-site/zh/tutorials/docker-in-docker.mdx

@@ -13,6 +13,20 @@ description: "根据任务信任边界选择 Docker socket、raw privileged DinD
 | Raw privileged DinD | 一次性 VM 或专用 runner，需要独立 image、network 和 cache | 每个 Sandbox 启动 inner daemon | outer container 是 raw privileged，不是安全隔离方案 |
 | Managed rootless DinD | 不可信 Agent、共享宿主、并发评估、需要资源准入和强杀恢复 | 最高，需要宿主 profile | privileged 限制在受管 rootless user namespace 或专用 VM，并有 watchdog 与容量契约 |
 
+完整的 Docker profile 依赖 Linux cgroup v2、systemd 和支持 project quota 的文件系统。NixOS 可以用
+NiceEval module 部署；Ubuntu、Debian 与其它 systemd Linux 需要安装等价的宿主服务。
+
+macOS 上的实际选择是 OrbStack 或 Apple `container`：
+
+- OrbStack 的 Docker engine 可以用于可信任务的 Docker socket 模式。需要完整 profile 时，在 OrbStack
+  Linux machine 内运行 NiceEval，并按该发行版的 Linux 安装方式部署宿主服务。
+- Apple 官方 [`container`](https://github.com/apple/container) 在 Apple silicon 和 macOS 26 上把 Linux
+  container 作为轻量 VM 运行。当前 NiceEval Docker Provider 不操作它的 CLI 或 API，因此不能直接选择
+  `container`；这需要独立 Provider。
+
+Apple `container` 使用 Containerization framework，不是 containerd。直接安装 containerd 也不会让 Darwin
+获得 Linux cgroup 或 project quota；它仍需要 Linux VM。
+
 三种模式都要求镜像预装 Docker CLI。两种 DinD 模式只接受从官方
 `docker:<version>-dind` 派生的兼容镜像。镜像需要 Docker daemon、Node 和评估工具，
 但不需要自定义 NiceEval `ENTRYPOINT`。NiceEval 负责启动与监督 inner daemon、
@@ -173,13 +187,40 @@ export default defineExperiment({
     dockerAccess: {
       mode: "dind",
       isolation: "raw-privileged",
+      storageProfile: "default",
+    },
+    resources: {
+      dockerDataBytes: 6 * 1024 ** 3,
     },
   }),
 });
 ```
 
 必填的 `raw-privileged` 字面量是风险授权。NiceEval 不会把 raw 模式描述成 rootless，也不会在失败时
-自动改用 managed profile。
+自动改用 managed profile。`storageProfile` 为 inner `/var/lib/docker` 分配磁盘配额；不要把该路径放进
+`tmpfs`。这个 profile 只增加磁盘准入、配额和强杀恢复，不会把 raw privileged 变成安全隔离方案。
+
+### 在 macOS 上使用 OrbStack
+
+可信的本地评估可以复用 OrbStack Docker engine。先让 OrbStack 创建 Docker context，再读取实际 Unix socket：
+
+```bash
+docker context inspect orbstack --format '{{.Endpoints.docker.Host}}'
+```
+
+把输出的 `unix://` 路径去掉 scheme 后填入 `dockerAccess.socketPath`。这仍是 Docker socket 模式；Agent
+可以完全控制 OrbStack daemon，不适合不可信任务。
+
+需要 managed profile 时，使用 OrbStack 的完整 Ubuntu machine，而不是把 profile 服务装进 macOS：
+
+```bash
+orb create ubuntu niceeval-runner
+orb -m niceeval-runner
+```
+
+进入 machine 后，按 Ubuntu 的宿主安装流程准备 systemd、cgroup v2 和 project-quota 文件系统，并在该
+machine 内运行 NiceEval。Ubuntu 安装包发布前，这条路径不是开箱即用能力；不要用 OrbStack Docker engine
+冒充 managed profile。
 
 ### Managed rootless DinD
 
@@ -216,9 +257,9 @@ export default defineExperiment({
       cpus: 4,
       memoryBytes: 6 * GiB,
       pidsLimit: 2048,
+      dockerDataBytes: 6 * GiB,
       readOnlyRootfs: true,
       tmpfs: {
-        "/var/lib/docker": { sizeBytes: 3 * GiB, mode: 0o711, executable: true },
         "/home/sandbox/workspace": {
           sizeBytes: 2 * GiB,
           mode: 0o755,
@@ -238,6 +279,10 @@ export default defineExperiment({
 profile 缺失、拼错、attestation 失败或容量不足时，NiceEval 会在模型调用前失败，绝不降级成 raw
 privileged。宿主部署完成后先检查 profile：
 
+`dockerDataBytes` 是每个 Attempt 的 inner Docker data 硬上限。watchdog 从磁盘配额池中授予一份私有
+allocation，并把它挂到 `/var/lib/docker`。Docker image layer 与 BuildKit cache 因而占磁盘，不计入宿主
+`Shmem`；workspace、`/tmp` 等确实需要内存语义的路径仍可使用有界 `tmpfs`。
+
 ```bash
 npx niceeval docker profile list
 npx niceeval docker profile doctor default --smoke
@@ -250,16 +295,16 @@ Dockerfile。项目镜像仍由默认 `docker info` readiness 验证。
 
 ### 为 DinD 设置运行并发
 
-`resources.memoryBytes` 限制一台 Sandbox，不会自动设置 Run 的并发数。DinD 还会占用 inner
-image、BuildKit、tmpfs 和 page cache，默认并发对本机可能过高。先用较小并发完成 smoke run：
+`resources.memoryBytes` 限制一台 Sandbox，`dockerDataBytes` 限制它的 inner Docker data。profile 会对
+所有 NiceEval 进程执行共享容量准入；当前没有足够的内存或磁盘 allocation 时，新 Attempt 会等待。先用
+较小并发完成 smoke run：
 
 ```bash
 pnpm exec niceeval exp dind-managed --max-concurrency 2
 ```
 
-再根据宿主的可用内存、CPU 和磁盘吞吐逐步增加。可以先用
-`可用内存 ÷ memoryBytes` 估算保守上限，同时为宿主 Docker、NiceEval 和其它进程留余量。
-Experiment 只服务这类重型 Sandbox 时，也可以直接设置 `maxConcurrency`。
+再根据宿主的可用内存、CPU 和磁盘吞吐逐步增加。profile 的总预算负责阻止多个 Experiment 合计超过宿主
+容量，`maxConcurrency` 仍负责限制单次 Run 的并行度。两者不能互相替代。
 
 ### 定位 DinD 创建失败
 

package/docs-site/zh/tutorials/eval-groups.mdx

@@ -104,8 +104,7 @@ export default defineExperiment({
 这里不要写 `sandboxReuse: true`。`maxConcurrency: 4` 是整个 Experiment 的上限，不会让
 同组同时跑四条；它允许其它评估组或未分组评估用例使用剩余并发位。
 
-评估组只支持 Sandbox 型 Agent 和支持复用的 Provider。Direct Agent 与 `localSandbox()`
-不能运行评估组。
+评估组只支持 Sandbox 型 Agent 和支持复用的 Provider。Direct Agent 不能运行评估组。
 
 ## 第 4 步：先检查组 ID 和选择结果
 

package/docs-site/zh/tutorials/evaluation-kinds.mdx

@@ -79,22 +79,53 @@ export default defineScoreEval({
 
 ## Judge 也是 measurement
 
-Judge recipe 直接登记 measurement Assertion。先声明 `judge` capability，再在同一 handle 上配置阈值或分数：
+Judge recipe 直接登记 measurement Assertion。先声明 `judge` capability，再根据评估类型消费同一条结果。
+
+通过制评估表达“这些要求都必须成立”。把每个可以独立失败的开放式要求拆成一条 Judge，并分别调用 `.gate(n)`：
+
+```ts
+export default defineEval({
+  judge: true,
+  async test(t) {
+    const turn = await t.send("说明这项变更的动机、风险和回滚方法。");
+
+    turn.judge.autoevals.closedQA("说明是否交代了变更动机？")
+      .gate(1)
+      .label("变更动机");
+    turn.judge.autoevals.closedQA("说明是否识别了具体风险？")
+      .gate(1)
+      .label("具体风险");
+    turn.judge.autoevals.closedQA("说明是否给出了可执行的回滚方法？")
+      .gate(1)
+      .label("回滚方法");
+  },
+});
+```
+
+三项中的任意一项失败，Attempt 都会失败。不要只写一个“是否说明了动机、风险和回滚”的 Judge；`closedQA` 只返回 `0` 或 `1`，合并后既没有部分分，也看不出哪项失败。
+
+计分制评估表达“各项完成多少就累计多少”。独立要求仍然拆开，并用 `.score(n)` 写出各自权重：
 
 ```ts
 export default defineScoreEval({
   judge: true,
   async test(t) {
     const turn = await t.send("说明这项变更的动机和风险。");
-    turn.judge.autoevals.closedQA("说明是否具体、准确？")
-      .score(20)
-      .atLeast(0.7)
-      .label("说明质量");
+    turn.judge.autoevals.closedQA("说明是否交代了变更动机？")
+      .score(8)
+      .label("变更动机");
+    turn.judge.autoevals.closedQA("说明是否识别了具体风险？")
+      .score(12)
+      .label("具体风险");
   },
 });
 ```
 
-同一条 Judge Assertion 可以同时配置 `.score(n)` 与 `.atLeast(n)`，evaluator 只运行一次。Judge 没有单独的消费 API。
+如果两项都满足，上例贡献 `20` 分；只满足风险要求时贡献 `12` 分。`.score(n)` 的 `n` 是单项权重，不是自动声明的固定总分。
+
+评价一个不可分割的整体质量时，可以只使用一条 Judge。例如“整段说明相对参考答案的事实一致性”可以用一条 `factuality(...).score(20)`。它只会按 recipe 的固定档位贡献 `0`、`8`、`12` 或 `20` 分，不能表示“三个要求完成了两个，所以得到三分之二”。
+
+同一条 Judge Assertion 可以同时配置 `.score(n)` 与 `.atLeast(n)`，evaluator 只运行一次。`.atLeast(n)` 只记录该项是否达到阈值，不改变分数，也不会让计分制评估失败。Judge 没有单独的消费 API。
 
 ## 代码任务用真实命令验收
 
@@ -110,6 +141,8 @@ await t.check(
 ## 实用建议
 
 - 把每个必须成立的条件登记为 Boolean Assertion，让一次 Attempt 收集完整失败信息。
+- 把可以独立失败、独立计权或需要单独诊断的开放式标准拆成多个 Judge。
+- 只有不可分割的整体质量维度才使用一个 Judge 的 measurement 乘单项权重。
 - 后续步骤依赖某条结果时，`await handle.orStop()`。
 - 任务存在有意义的部分完成度时使用 `defineScoreEval`；`test` 正常返回时自动收尾。
 - 开放式语义用 Judge；可精确检查的文件、命令与结构化输出优先用确定性 Match。

package/docs-site/zh/tutorials/nixos-managed-dind.mdx

@@ -8,6 +8,11 @@ Managed rootless DinD 适合在共享 NixOS 宿主上运行不可信 Agent。Nic
 系统用户、rootless Docker daemon、容量受限的数据盘、资源 slice 和 watchdog。日常运行 NiceEval
 不需要 `sudo`，但首次部署和更新系统配置需要管理员权限。
 
+本页只介绍 NixOS 的部署入口。Docker profile 本身是 Linux 宿主能力，不是 NixOS 专属能力。Ubuntu、
+Debian 与其它 systemd Linux 需要安装等价的宿主服务。macOS 用户可以在 OrbStack Linux machine 内运行
+NiceEval 和对应的 Linux 宿主服务；Apple `container` 当前需要独立 NiceEval Provider。具体边界与命令见
+[让 Sandbox 使用 Docker](/zh/tutorials/docker-in-docker#在-macos-上使用-orbstack)。
+
 如果任务可以信任 Agent，或者只在一次性 VM 中运行，先阅读[让 Sandbox 使用 Docker](/zh/tutorials/docker-in-docker)
 选择 Docker socket 或 raw privileged DinD。它们不需要本页的宿主 profile。
 
@@ -66,6 +71,8 @@ Managed rootless DinD 适合在共享 NixOS 宿主上运行不可信 Agent。Nic
       pids = 4096;
       maxContainers = 2;
       maxBuilds = 1;
+      ephemeralDiskBytes = "6G";
+      dockerDataAllocationCount = 2;
     };
 
     aggregate = {
@@ -82,11 +89,13 @@ Managed rootless DinD 适合在共享 NixOS 宿主上运行不可信 Agent。Nic
 }
 ```
 
-`capacity` 是 NiceEval 可以分配给评估任务的预算。`aggregate` 是 daemon、构建进程、watchdog 和评估
-容器共同受到的硬限制，因此每一项都不能小于 `capacity`。两者之间的余量留给宿主侧开销。
+`capacity` 是 NiceEval 可以分配给评估任务的预算。`ephemeralDiskBytes` 是每个 Docker data allocation
+的硬上限，`dockerDataAllocationCount` 是 profile 可同时授予的 Docker data allocation 数量。`aggregate` 是 daemon、构建进程、
+watchdog 和评估容器共同受到的硬限制，因此每一项都不能小于 `capacity`。两者之间的余量留给宿主侧开销。
 
-`loop-ext4` 会在 `/var/lib/niceeval/docker-profiles/default.img` 创建稀疏镜像，并挂载为 Docker
-data root。`size` 是这个 profile 的磁盘上限，不代表 rebuild 时立即占用同等物理空间。
+`loop-ext4` 会在 `/var/lib/niceeval/docker-profiles/default.img` 创建独立的 ext4 quota 文件系统。
+watchdog 从中分配私有目录，并把目录挂到每个 Sandbox 的 `/var/lib/docker`。不要再为该路径声明
+`tmpfs`；inner image layer 和 BuildKit cache 应占磁盘，不应计入宿主 `Shmem`。
 
 ## 应用系统配置
 
@@ -142,7 +151,7 @@ dockerAccess: {
 },
 ```
 
-Experiment 还必须声明单容器 CPU、内存、PID、只读 rootfs 和 tmpfs。完整配置见
+Experiment 还必须声明单容器 CPU、内存、PID、`dockerDataBytes`、只读 rootfs 和其余可写路径的 tmpfs。完整配置见
 [让 Sandbox 使用 Docker](/zh/tutorials/docker-in-docker#managed-rootless-dind)。先用较小的
 `maxConcurrency` 运行一次，再根据 profile 的 `capacity` 增加并发。
 

package/docs-site/zh/tutorials/sandbox-providers.mdx

@@ -51,7 +51,6 @@ export default defineExperiment({
 | `dockerSandbox({ source: { type: "image", image: "node:24-slim" } })` | `pnpm add dockerode @types/dockerode` |
 | `vercelSandbox({ snapshotId })` | `pnpm add @vercel/sandbox` |
 | `e2bSandbox({ template })` | `pnpm add e2b` |
-| `localSandbox()` | 无需额外安装 |
 
 漏装时不会静默失败：NiceEval 在创建 sandbox 的那一刻报错并直接给出上面的安装命令，例如 `Docker sandbox requires 'dockerode'. Install it with: pnpm add dockerode @types/dockerode`。
 
@@ -381,35 +380,9 @@ Docker 适合本地开发和标准 CI。优点是简单、可控、无云端依
 
 Vercel Sandbox 适合需要云端隔离、更多资源或更稳定环境的任务。需要相应 token 或 OIDC 配置。
 
-## 本地目录
-
-`localSandbox()` 让 Agent 直接在你机器上的一个 Git 仓库里跑，不需要 Docker，也不需要云凭据：
-
-```ts
-import { defineExperiment } from "niceeval";
-import { localSandbox } from "niceeval/sandbox";
-
-export default defineExperiment({
-  agent: myCodingAgent,
-  sandbox: localSandbox(), // 默认用当前 Git 仓库根做工作目录
-});
-```
-
-要评别的目录，传 `localSandbox({ dir: "/path/to/repo" })`。
-
-NiceEval 只观察、不还原：Agent 改了什么会真实落在你的工作树上。NiceEval 用一份独立的私有 Git 记录采集 diff 和评分，不碰你自己的 `.git`、暂存区和未提交改动，跑完也不会执行任何 `git reset`。要保留还是丢弃 Agent 的改动，由你决定。
-
-使用前记住三件事：
-
-- Agent 以你的身份、在你的机器上执行命令。只在你信任任务和 Prompt 的时候用它。要隔离就用 Docker 或云 Provider。
-- 本地目录同一时刻只跑一个 Attempt（强制串行），`--max-concurrency` 抬不高它。
-- 连续跑多个评估用例时，前一个的改动会留在工作树上，成为后一个的起点。要每题干净起点，用容器 Provider。
-
-`{ user: "..." }` 和 `--keep-sandbox` 对本地目录不可用，会直接报错：NiceEval 不在你的机器上提权或换身份，也不需要「留存」一个本来就在你工作树里的现场。
-
 ## 自定义 Provider
 
-用 `defineSandbox` 接入其它服务。`create` 的 `feedback` 已绑定到 `sandbox.create` 阶段，可以报告分配实例、拉镜像或恢复 Sandbox 快照的状态：
+用 `defineSandbox` 接入其它服务。自定义 Provider 的作者必须负责文件系统、进程、网络与凭据隔离；NiceEval 不会为一个任意 `Sandbox` 实现自动补上这些安全边界。`create` 的 `feedback` 已绑定到 `sandbox.create` 阶段，可以报告分配实例、拉镜像或恢复 Sandbox 快照的状态：
 
 ```ts
 import { defineSandbox } from "niceeval/sandbox";

package/docs-site/zh/tutorials/sandbox-reuse.mdx

@@ -32,7 +32,7 @@ import { SandboxLanes } from '/snippets/diagram-sandbox-lanes.jsx';
   同一条实验轨迹。否则应换干净 cohort 从头重建。
 - **工作目录之外的状态会留下。** `$HOME`、`/tmp`、全局安装、后台进程都活过题间重置。
   评估的准备代码必须能接受这一点（下面「把准备代码写对」）。
-- 与 `--keep-sandbox`、`localSandbox()` 互斥。
+- 与 `--keep-sandbox` 互斥。
 
 适合的场景：本地冒烟一批评估、同一道题重复跑 N 次看稳定性、验证接线——要的是快，
 同时保留结果沿用与 `--rerun` 的选择。

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

@@ -71,6 +71,8 @@ Problems
 
 `Result` 显示 `passed`、`failed`、`errored`、`not started` 或 `using result @<locator>`；`Details` 的 locator 可继续下钻。Attempt 创建前失败时，页面另外显示 `Run errors` 和该错误真正影响的未启动 Attempt 数。Human 页不显示 Slot 等内部字段；机器 `--json` 仍保留稳定 membership keys。
 
+Attempt 的 `failed` 只说明影响 Verdict 的断言未满足，不会自动把原因归给被测对象。按[排查手册](/zh/troubleshooting/debugging#attempt-判定为-failed)分别比较任务、实际产物与断言，再决定修哪一层。
+
 `show --json` 仍是同一个单目标操作。内建 Report 返回 Host 拥有的具名领域 JSON；自定义 Report 返回该 Page 的 route、标题、固定英语 80-column rendered text、下载摘要和问题表。
 两种 v1 JSON 都在顶层带有同一形状的 `projections` 对象，只包含目标 Page 捕获的闭合投影。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "niceeval",
-  "version": "0.13.3",
+  "version": "0.13.4-canary.39",
   "description": "Agent-native eval tool — eval agents, services, functions, and coding-agent fixtures",
   "type": "module",
   "license": "MIT",
@@ -115,6 +115,16 @@
         "default": "./dist/analysis/index.cjs"
       }
     },
+    "./eval/host": {
+      "import": {
+        "types": "./dist/eval/host/index.d.mts",
+        "default": "./dist/eval/host/index.mjs"
+      },
+      "require": {
+        "types": "./dist/eval/host/index.d.cts",
+        "default": "./dist/eval/host/index.cjs"
+      }
+    },
     "./experiment/host": {
       "import": {
         "types": "./dist/experiment/host/index.d.mts",
@@ -215,6 +225,16 @@
         "default": "./dist/report/extension/index.cjs"
       }
     },
+    "./project/host": {
+      "import": {
+        "types": "./dist/project/host/index.d.mts",
+        "default": "./dist/project/host/index.mjs"
+      },
+      "require": {
+        "types": "./dist/project/host/index.d.cts",
+        "default": "./dist/project/host/index.cjs"
+      }
+    },
     "./report/react/styles.css": "./dist/report/react/styles.css",
     "./report/react/enhance.js": "./dist/report/react/enhance.js"
   },
@@ -316,27 +336,12 @@
     }
   },
   "scripts": {
-    "typecheck": "tsc --noEmit && tsc -p docs/feature/assertions/reference/tsconfig.json",
-    "lint": "pnpm run docs:mint && concurrently --names vitest,validate,links \"pnpm run lint:vitest\" \"pnpm run docs:validate\" \"pnpm run docs:links\"",
-    "lint:vitest": "vitest run --project lint-docs --project lint-docs-site",
-    "lint:docs": "vitest run --project lint-docs",
-    "lint:docs-site": "pnpm run docs:mint && concurrently --names vitest,validate,links \"vitest run --project lint-docs-site\" \"pnpm run docs:validate\" \"pnpm run docs:links\"",
+    "typecheck": "tsc --noEmit",
     "niceeval": "node bin/niceeval.js",
-    "e2e": "tsx e2e/scripts/cli.ts",
-    "gen:diff-code": "tsx scripts/gen-diff-code.ts",
-    "pr:body": "tsx scripts/pr-body.ts",
-    "docs:reference": "tsx scripts/generate-reference.ts",
-    "tiers:sync": "node scripts/sync-tiers.mjs sync",
     "view:build": "vite build --config src/report/client/vite.config.ts",
     "build:report": "pnpm run build:package",
     "build:package": "pnpm run view:build && node scripts/package-runtime/build.mjs",
-    "build:index": "tsx scripts/generate-reference.ts --bundled-index",
-    "dev:link": "node scripts/link-consumer.mjs",
-    "site:dev": "cd site && node scripts/dev.mjs",
-    "site:build": "cd site && next build && cd .. && tsx scripts/submit-indexnow.ts",
-    "docs:dev": "node scripts/docs-dev.mjs",
-    "docs:mint": "cd docs-site && npx --yes mint@4.2.812 --version",
-    "docs:validate": "cd docs-site && npx --yes mint@4.2.812 validate",
-    "docs:links": "cd docs-site && npx --yes mint@4.2.812 broken-links --check-anchors --check-redirects"
+    "build:index": "tsx ../../scripts/generate-reference.ts --bundled-index",
+    "stage:docs": "node scripts/stage-docs.mjs"
   }
 }