niceeval 0.6.1 → 0.7.0

package/docs-site/zh/guides/publish-report.mdx

@@ -1,91 +0,0 @@
----
-title: "通过 CI 发布报告"
-sidebarTitle: "CI 发布报告"
-description: "把报告站接进 CI:.niceeval/ 提交进仓库,构建命令一行 view --out,push 即发布。发布的站和本地 niceeval view 完全一样;零可读结果时构建失败,保住上一次部署。"
----
-
-`niceeval view --out <目录>` 把查看器导出成一个纯静态目录:报告、结果快照列表、transcript、trace 瀑布,和本地 `niceeval view` 看到的完全一样(导出行为见[查看结果 · 导出与静态托管](/zh/guides/viewing-results#导出与静态托管))。CI 发布只需要让结果数据到构建机手里——把 `.niceeval/` 提交进仓库,仓库本身就是数据源。本地跑完 eval,提交并 push 就是发布,不需要任何脚本或本地构建命令。
-
-## `.gitignore` 只排除 `diff.json`
-
-```gitignore
-# .niceeval/ 提交进仓库:它是线上报告的数据源,CI 构建时直接从这里生成整站。
-# 只排除 diff.json —— 单轮可达上百 MB,体积太大不适合进仓库;Attempt 详情仍会读取它,只是不随静态导出复制。
-.niceeval/**/diff.json
-```
-
-## 构建命令就是导出命令
-
-```bash
-npx niceeval view --out site
-```
-
-`view` 对零可读结果直接报错、非零退出,不会导出一张空报告——`.niceeval/` checkout 坏掉,或所有落盘与当前 niceeval 的 schemaVersion 不兼容被整批跳过时,构建失败,Vercel / GitHub Pages 保留上一次部署。错误逐条列出被跳过的快照目录与原因,schemaVersion 场景还给出能直接查看旧落盘的 `npx niceeval@<版本> view` 命令。
-
-## 发布自定义报告
-
-不传 `--report` 时,发布出来的首页是默认报告。想让首页换成自己的报告,把 [`defineReport` 报告文件](/zh/guides/custom-reports)传给 `--report` 就行——attempt 证据页(transcript、trace、代码视图)仍在同一个站里,报告里的每个数字点进去就是对应证据,和本地 `view --report` 看到的一模一样:
-
-```bash
-npx niceeval view --report reports/exam.tsx --out site
-```
-
-报告文件和 `.niceeval/` 一样提交在仓库里,改完版面 push,线上就跟着更新。用下面的 `vercel.json` / workflow 时,把构建命令换成这一行即可,其余配置不用动。
-
-## 接托管平台
-
-**Vercel**:仓库根放一个 `vercel.json`,导入项目后 push 即部署。
-
-```json
-{
-  "installCommand": "pnpm install --frozen-lockfile",
-  "buildCommand": "npx niceeval view --out site",
-  "outputDirectory": "site"
-}
-```
-
-**GitHub Pages**:仓库 Settings → Pages 把 Source 设为 GitHub Actions,再加 workflow:
-
-```yaml
-# .github/workflows/report.yml
-name: report
-on:
-  push:
-    branches: [main]
-
-permissions:
-  contents: read
-  pages: write
-  id-token: write
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: pnpm/action-setup@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 22
-          cache: pnpm
-      - run: pnpm install --frozen-lockfile
-      - run: npx niceeval view --out site
-      - uses: actions/upload-pages-artifact@v3
-        with:
-          path: site
-  deploy:
-    needs: build
-    runs-on: ubuntu-latest
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-    steps:
-      - id: deployment
-        uses: actions/deploy-pages@v4
-```
-
-日常循环从此只有两步:本地跑 eval,提交 `.niceeval/` 并 push。发布出去的站带完整历史——同事打开链接,看到的和你本地 `niceeval view` 一模一样;仓库、本地查看器、线上报告三处同一个真相源。仓库体积随落盘增长(`diff.json` 已排除,增长主要来自 transcript 和 trace artifact),不想保留的旧快照直接删对应快照目录即可,查看器和报告跟着仓库走。
-
-## 发布的是完整证据
-
-整站导出带完整证据:transcript、源码快照、trace 原样进站点,不消毒。发布到公网前确认结果里没有密钥或敏感数据;自定义报告页的自由文本消毒见[结果数据层](/zh/guides/results-data)的 `redact` 钩子。

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

@@ -1,102 +0,0 @@
----
-title: "Sandbox provider：Docker、Vercel 与第三方"
-sidebarTitle: "沙箱 provider"
-description: "NiceEval 在 Docker 或 Vercel sandbox 中运行 coding agents。了解如何选择 provider、配置权限，并通过 warm pools 改善性能。"
----
-
-Sandbox backend 是创建和管理隔离运行环境的基础设施。[NiceEval](https://niceeval.com/) 把它们包装成同一个 `Sandbox` 接口，所以 adapter 不需要知道当前用的是本地 Docker、Vercel micro-VM 还是第三方云服务。
-
-## `Sandbox` 接口
-
-Adapter 常用操作包括：
-
-| 方法 | 用途 |
-|---|---|
-| `runCommand(cmd, args)` | 运行命令 |
-| `runShell(script)` | 运行 shell 脚本 |
-| `readFile(path)` | 读取文件 |
-| `writeFiles(files)` | 写入一组文件 |
-| `uploadFiles(files)` | 上传 workspace 或测试文件 |
-| `workdir` | provider 真实工作目录；省略的 `cwd` / `targetDir` 都解析到这里 |
-| `runCommand(..., { cwd })` | 单条命令临时切换工作目录；相对路径按 `workdir` 解析 |
-| `stop()` | 销毁环境 |
-
-## 选择 provider
-
-选择 provider 只能写在代码里——没有对应的 CLI flag，[NiceEval](https://niceeval.com/) 也不会自动探测 provider。在 experiment 里设置 `sandbox` 字段（或者在 `niceeval.config.ts` 里设置作为项目级兜底），三选一：
-
-```ts
-// experiments/local.ts
-import { defineExperiment } from "niceeval";
-import { dockerSandbox } from "niceeval/sandbox";
-
-export default defineExperiment({
-  agent: myCodingAgent,
-  model: "claude-sonnet-4-6",
-  sandbox: dockerSandbox(), // 或 vercelSandbox() / e2bSandbox()
-});
-```
-
-如果 experiment 和 `niceeval.config.ts` 都没有设置 `sandbox`，[NiceEval](https://niceeval.com/) 在创建 sandbox 时会直接报错，而不会猜一个 provider。
-
-三个内置 provider 的 SDK 不随 NiceEval 一起安装——用哪个就装哪个，避免把用不到的依赖（以及它们的原生构建脚本）带进你的项目：
-
-| provider | 安装命令 |
-|---|---|
-| `dockerSandbox()` | `pnpm add dockerode @types/dockerode` |
-| `vercelSandbox()` | `pnpm add @vercel/sandbox` |
-| `e2bSandbox()` | `pnpm add e2b` |
-
-漏装时不会静默失败：NiceEval 在创建 sandbox 的那一刻报错并直接给出上面的安装命令，例如 `Docker sandbox requires 'dockerode'. Install it with: pnpm add dockerode @types/dockerode`。
-
-## 环境钩子
-
-`dockerSandbox()` / `vercelSandbox()` / `e2bSandbox()` 返回的 spec 上有两个链式方法：`.setup(fn)` 和 `.teardown(fn)`。它们解决一类具体问题：**有些东西你本想直接做进 Docker 镜像或 E2B 模板，但它要按实验变化**——比如某个实验要装一个额外的二进制、预热一次模型、写一份 hook 文件，或者在多次 attempt 之间载入和回存状态。静态镜像做不到"每个实验装不同的东西"，这两个钩子就是运行时补上的那一层。
-
-```ts
-export default defineExperiment({
-  agent: codexAgent({ mcpServers: [mempalMcp] }),
-  sandbox: e2bSandbox({ template: "fasteval-agents" })
-    .setup(mempalSetup("codex"))        // 装二进制、预热、写 hook、载入状态
-    .teardown(mempalTeardown("codex")), // 回存状态
-  maxConcurrency: 1,                    // 载入和回存之间不能并发，声明串行
-});
-```
-
-规则一览：
-
-- **签名**：钩子函数和 Adapter 的 `setup` / `teardown` 一样是 `(sandbox, ctx)`；`setup` 可以返回一个清理函数。
-- **不可变**：每次 `.setup()` / `.teardown()` 都返回一个新 spec，原对象不变，可以继续链。
-- **多个钩子**：多个 `.setup()` 按追加顺序执行；多个 `.teardown()` 按追加的逆序执行。
-- **执行时机**：`setup` 钩子在 sandbox 创建后、git 基线之前最先跑——它写下的文件会进基线，不会被算进 agent 产出的 diff；`teardown` 钩子在 Adapter 的 `teardown` 之后、sandbox 销毁之前最后跑——把状态回存到外部正好用这个时机。
-- **失败语义**：`setup` 钩子抛错，这次 attempt 记为 `errored`（环境问题，不是 agent 做错题）；`teardown` 钩子报错只记日志，不改变已产出的结果。
-- **不带 sandbox 的 Agent**：`defineAgent` 构造的 Agent 没有 sandbox，`sandbox` 字段对它不生效，钩子自然不会跑。
-
-钩子里可以用 `ctx.experimentId`（路径推导的实验 id）当状态隔离的键，比如不同实验各自维护一份跨 attempt 的缓存。跨 attempt 状态的载入和回存是你自己在钩子里写的普通代码——[NiceEval](https://niceeval.com/) 不提供状态存储；要保证同一实验的 attempt 不并发读写同一份状态，在 experiment 上声明 `maxConcurrency: 1`。
-
-和另外两处 setup 的分工：Adapter 的 `setup` 管"怎么连被测 agent"（装 CLI、写鉴权配置）；eval 里 `test(t)` 开头的代码管"这道题需要哪些起始文件"；sandbox 的 `.setup()` 管"这次实验的环境里要多装什么"。三层各写各的，互相不知道对方的内容。MCP server、Skill、model 这些被测 agent 的配置仍然只从 Adapter 工厂参数进——环境钩子不做 Adapter 的事。
-
-## Docker
-
-Docker 适合本地开发和标准 CI。优点是简单、可控、无云端依赖；缺点是机器资源有限，冷启动和安装依赖可能较慢。
-
-## Vercel Sandbox
-
-Vercel Sandbox 适合需要云端隔离、更多资源或更稳定环境的任务。需要相应 token 或 OIDC 配置。
-
-## 第三方 provider
-
-只要实现 `Sandbox` 接口，就可以接入其他 sandbox provider。adapter 仍然只依赖接口，不依赖 provider 私有 API。
-
-## 权限和 root
-
-不同 provider 对 root 权限、网络、文件系统和进程生命周期的约束不同。编写 fixture 时尽量避免依赖宿主机环境，把依赖写进 `package.json` 或 fixture setup。
-
-## 性能建议
-
-- 减少 fixture 依赖体积。
-- 使用缓存或预热机制。
-- 控制 `maxConcurrency`（experiment 字段或 `--max-concurrency`），避免本地 Docker 资源耗尽。
-- 把慢测试拆成必要的 gate 和可选的 soft 检查。
-
-Warm pools 和复用属于 runner / scheduler 层面的能力，详见 [Runner](/zh/guides/runner)。