niceeval 0.4.4 → 0.4.6

package/docs/results-format.md

@@ -1,228 +0,0 @@
-# Results Format —— 结果保存格式
-
-这篇记录 `Artifacts()` 报告器写到本地磁盘的格式,也是 `niceeval view` 的离线输入契约。实现入口是 `src/runner/reporters/artifacts.ts`;核心类型在 `src/types.ts` 的 `RunSummary`、`EvalResult`、`StreamEvent`、`TraceSpan`、`O11ySummary` 和 `DiffData`。
-
-## 目录结构
-
-默认输出根目录是 `.niceeval/`。每次 run 一个时间戳目录,时间戳来自 `Date#toISOString()`,并把 `:` 与 `.` 替换成 `-`:
-
-```text
-.niceeval/
-  2026-07-02T03-10-24-123Z/
-    summary.json
-    <evalId>/<agent>/<model>[/<experiment>]/a<attempt>/
-      events.json
-      sources.json
-      trace.json
-      o11y.json
-      diff.json
-```
-
-`<evalId>/<agent>/<model>[/<experiment>]/a<attempt>/` 是单个 eval attempt 的工件目录。`evalId` 里的 `/` 会保留为目录层级,其它不适合路径的字符会替换成 `_`;`agent` 和 `model` 里的非 `[\w.@-]` 字符也会替换成 `_`。没有 model 时目录名是 `default`。带 experimentId 的结果多一段实验目录(`/` 压成 `_`,如 `compare-prompts_concise`)——两个实验可以同 agent 同 model、只差 flags,少了这一段工件会互相覆盖。
-
-这些文件是按需写入的:某类数据为空就不生成对应 JSON 文件。`summary.json` 在 run 结束时写入;attempt 级重数据在每个 eval 完成时增量写入,所以长 run 中途失败时通常仍能留下已经完成的 attempt 工件。
-
-## 版本与升级设计
-
-`summary.json` 顶层带最小的版本元数据(writer 在 `src/runner/reporters/artifacts.ts`,常量在 `src/types.ts` 的 `RESULTS_FORMAT` / `RESULTS_SCHEMA_VERSION`):
-
-```json
-{
-  "format": "niceeval.results",
-  "schemaVersion": 1,
-  "producer": {
-    "name": "niceeval",
-    "version": "0.12.0"
-  },
-  "startedAt": "2026-07-02T03:10:24.123Z",
-  "results": []
-}
-```
-
-设计原则是**不做兼容机制**。没有迁移函数,没有多版本 normalize loader,没有 per-artifact 版本号:整个 run(summary + 全部 attempt 工件)共用顶层这一个 `schemaVersion`。读取器只认与自己相同的版本;版本不同就是不兼容,唯一的处理是提示用写这份报告的 niceeval 版本查看:
-
-```bash
-npx niceeval@0.3.0 view .niceeval/2026-09-10T08-00-00-000Z
-```
-
-字段规则:
-
-- `format` 必须等于 `"niceeval.results"`。它既避免把其它工具的 `summary.json` 误读成 niceeval,也是版本不匹配时识别「这是一份 niceeval 报告」的依据。
-- `schemaVersion` 用整数,只在**破坏兼容读取**时递增。新增可选字段、新增 artifact 文件、新增 `StreamEvent` variant 不递增;读取器必须忽略未知字段和未知 artifact 文件。
-- `producer.version` 是写这份报告的 npm package 版本,唯一用途是拼 npx 提示;它不是 schema 判断依据。
-- `format` / `schemaVersion` / `producer` 三个字段永久稳定:任何未来版本都不能移动、重命名或改变类型,否则版本不匹配时连 npx 提示都给不出来。
-- 缺版本字段的存量文件等价于 `schemaVersion: 1`(引入版本号不改变其余格式)。这批文件没有 `producer.version`,将来不兼容时提示只能是模糊的「用 0.1.x 旧版查看」——所以 writer 越早开始写版本元数据越好。
-- attempt 文件保持裸 JSON array/object。`events.json` 继续是 `StreamEvent[]`,不为塞版本号改成 `{ schemaVersion, data }` envelope;`jq`/`node` 直接读数组的体验不被打破。
-- 不要用目录名表达 schema。`.niceeval/<timestamp>/` 和 attempt 目录只表达身份与定位;版本全部在 `summary.json` 里,复制、重命名、归档目录不影响解析。
-
-### 版本不匹配时的读取行为
-
-读取器不解析、不迁移、不降级渲染任何版本不同的 run,行为只分三档:
-
-- **`schemaVersion` 相同**(或缺失,按 1 处理):正常读取渲染。
-- **`format === "niceeval.results"` 但 `schemaVersion` 不同**(不论新旧):整个 run 视为不兼容。目录扫描时在列表里留一个占位条目,标出 run 目录和 `producer.version`,并提示:
-
-  ```text
-  ⚠ .niceeval/2026-09-10T08-00-00-000Z: written by niceeval 0.3.0 (schemaVersion 2);
-    this CLI reads schemaVersion 1.
-    Run `npx niceeval@0.3.0 view .niceeval/2026-09-10T08-00-00-000Z` to view it.
-  ```
-
-  单文件模式 `niceeval view <run>/summary.json` 输出同样的提示后退出,而不是报「不是 niceeval summary」。
-- **不能识别**(没有 `format`,也不满足 legacy 的 `results[]` + `startedAt` 启发式):当作无关 JSON 忽略。
-
-实现入口:版本判定在 `src/view/index.ts` 的 `readSummary`(抛 `IncompatibleResultsError`);目录扫描的占位数据经 `viewData.incompatibleRuns` 进前端,由 `src/view/app/App.tsx` 的 incompatible-banner 渲染;单文件模式的提示与退出在 `src/cli.ts` 的 `exitOnIncompatibleResults`;提示文案是 i18n key `cli.view.incompatible`。
-
-报告里最小应新增的字段是:
-
-```typescript
-interface ResultFormatMeta {
-  format: "niceeval.results";
-  schemaVersion: number;
-  producer?: {
-    name: "niceeval";
-    version?: string;
-    commit?: string;
-  };
-}
-```
-
-这组字段应该放进 `RunSummary`,但 eval 作者的运行时 API 不需要看见它们;它们属于 reporter / view 的持久化契约。
-
-## `summary.json`
-
-`summary.json` 是瘦身后的 `RunSummary`,负责让控制台、`--resume` 和 `niceeval view` 先拿到榜单级信息。前三个字段(`format` / `schemaVersion` / `producer`)是上文的版本元数据:
-
-```typescript
-interface RunSummary {
-  format?: "niceeval.results";
-  schemaVersion?: number;
-  producer?: { name: "niceeval"; version?: string; commit?: string };
-  name?: LocalizedText;
-  agent: string;
-  model?: string;
-  startedAt: string;
-  completedAt: string;
-  passed: number;
-  failed: number;
-  skipped: number;
-  errored: number;
-  durationMs: number;
-  usage?: Usage;
-  estimatedCostUSD?: number;
-  results: EvalResult[];
-  outputDir?: string;
-}
-```
-
-`results[]` 里的每条 `EvalResult` 仍包含判决、断言、用量、成本、错误、fingerprint 和 experiment 元数据,但不会内联大字段:
-
-- `events`
-- `sources`
-- `trace`
-- `o11y`
-- `diff`
-- `rawTranscript`
-
-这些字段被替换成 attempt 工件引用:
-
-```typescript
-{
-  "artifactsDir": "weather/brooklyn/codex/gpt-5/a1",
-  "hasEvents": true,
-  "hasTrace": true,
-  "hasSources": true
-}
-```
-
-`artifactsDir` 是相对当前 run 目录的路径。`niceeval view` 读取 `summary.json` 后,会把它补成:
-
-- `artifactBase`: 相对 view 输入根目录的路径,供前端请求 `/artifact?p=...`;
-- `artifactAbsBase`: 本机绝对路径,供 UI 复制或展示。
-
-注意:当前 summary 只有 `hasEvents`、`hasTrace`、`hasSources` 三个存在标记。`o11y.json` 和 `diff.json` 会写盘,但 summary 里还没有对应 `hasO11y` / `hasDiff` 标记;读取方需要按路径尝试读取或先检查文件存在。
-
-## Attempt 级文件
-
-### `events.json`
-
-类型是 `StreamEvent[]`。这是从 agent 原始 transcript 归一化后的标准事件流,也是作用域断言、transcript 展示、工具调用统计的主要来源。
-
-常见事件包括:
-
-- `message`: assistant / user 文本;
-- `action.called` / `action.result`: 工具调用与结果;
-- `subagent.called` / `subagent.completed`: 子 agent 调用;
-- `input.requested`: HITL 输入请求;
-- `thinking`: 思考块;
-- `compaction`: 上下文压缩;
-- `error`: 运行时或采集错误。
-
-文件内容是一个 JSON array,不是 JSONL / NDJSON。
-
-### `sources.json`
-
-类型是 `SourceArtifact[]`:
-
-```typescript
-interface SourceArtifact {
-  path: string;
-  content: string;
-}
-```
-
-它只包含本次 test/断言通过 `loc` 引用到的 eval 源码片段。`niceeval view` 用它把 `t.send`、断言和运行结果叠回源码行。
-
-### `trace.json`
-
-类型是 `TraceSpan[]`。只有 agent 声明 tracing 能力、运行器收到 OTLP span 并成功归一化时才会生成。它回答「各步骤耗时多久、父子关系是什么」,与回答「做了什么」的 `events.json` 分开。
-
-`TraceSpan.kind` 是 view 识别的核心字段,来自 canonical GenAI 语义角色:
-
-- `turn`
-- `model`
-- `tool`
-- `agent`
-- `other`
-
-原生 span 名和属性仍保留在 `name` / `attributes` 里,但 view 的分组与着色只应依赖 canonical 字段。
-
-### `o11y.json`
-
-类型是 `O11ySummary`。这是从标准事件流派生的行为摘要,包括工具调用计数、读写文件、shell 命令、web fetch、错误、思考块、压缩次数、耗时、usage 和估算成本。
-
-这个文件面向人和调试脚本:当一个 attempt 失败时,先看 `summary.json` 的 `outcome` / `error`,再看 `events.json` 与 `o11y.json`,通常能分清是断言没过、agent runtime 错误,还是 adapter / provider / timeout 问题。
-
-### `diff.json`
-
-类型是 `DiffData`:
-
-```typescript
-interface DiffData {
-  generatedFiles: Record<string, string>;
-  deletedFiles: string[];
-}
-```
-
-它只存在于有沙箱 workspace diff 的运行。coding-agent eval 常用它验证文件修改结果;remote / in-process agent 不一定有 diff。
-
-## 读取规则
-
-读取结果时优先从 `summary.json` 开始:
-
-1. 读 `.niceeval/<run>/summary.json`,先用 `results[]` 判断 pass / fail / error / skip、耗时、成本和断言失败。
-2. 对需要下钻的 result,用 `artifactsDir` 拼出 attempt 目录。
-3. 按 `hasEvents` / `hasTrace` / `hasSources` 拉取 `events.json`、`trace.json`、`sources.json`。
-4. 需要行为摘要或 workspace diff 时,尝试读取同目录的 `o11y.json` / `diff.json`。
-
-`niceeval view` 的本地 server 只暴露 `.json` 工件,并把请求路径限制在 view 输入根目录内。`--out` 导出时 summary 聚合数据烘焙进 `index.html`,查看器要 fetch 的工件复制到 `artifact/` 下同布局路径。
-
-## 与其它 reporter 的边界
-
-这篇只描述默认 `Artifacts()` reporter 的本地目录格式。`Json(path)` reporter 写的是机器可读全量 JSON,用途不同;第三方实验平台 reporter 可以把同一批 `EvalResult` / `RunSummary` 转成自己的格式。
-
-因此,不要在文档或工具里假设本地结果有 `results.jsonl`、transcript NDJSON 或固定测试输出文件。当前稳定契约是:
-
-- run 级: `summary.json`;
-- attempt 级: `events.json`、`sources.json`、`trace.json`、`o11y.json`、`diff.json`;
-- 每个文件都是 JSON,不是 JSONL。

package/docs/results-lib.md

@@ -1,191 +0,0 @@
-# Results Lib —— 实验结果数据的读写库(设计提案,未实现)
-
-> 状态:读取面已首版落地——`src/results/` 的 openResults / 快照 / latestPerExperiment / 身份键去重 / copyRun(源码入口见 [Source Map](source-map.md#results-lib-与-reports));写入面 `createRunWriter` 与 view / `Artifacts()` reporter 的收编仍是提案。[Results Format](results-format.md) 是磁盘上的格式规范(已实现);本文提议把这份格式的**读与写**抽成一个专门的库 `niceeval/results`,做 runner、view、[Reports](reports.md) 和用户脚本的共同数据层。
-
-同一份磁盘格式,今天的写和读长在两个器官里。写在 `src/runner/reporters/artifacts.ts`:时间戳目录、attempt 路径清洗(evalId 保留 `/` 层级、agent/model 非 `[\w.@-]` 全换 `_`)、大字段拆工件、`artifactsDir` / `has*` 回填、空数据不落文件——全是它的私有知识。读长在 `src/view/index.ts`:`readSummary` 的版本判定、`loadSummaries` 的目录扫描、工件路径反拼。两边靠 `src/types.ts` 共享类型,但**布局知识各自实现了一遍**:格式演进要同步改两处,谁漏改谁坏。而用户侧根本没有读取 API,想编程消费只能第三次重写这些知识:
-
-```typescript
-// 今天:想比「谁的代码短」,只能手工爬目录
-const summary = JSON.parse(readFileSync(".niceeval/2026-07-02T.../summary.json", "utf-8"));
-for (const r of summary.results) {
-  const diffPath = join(runDir, r.artifactsDir ?? "", "diff.json"); // 布局知识泄漏
-  if (!existsSync(diffPath)) continue;                             // 存在性自己判断
-  const diff = JSON.parse(readFileSync(diffPath, "utf-8"));        // 类型自己想
-}
-```
-
-抽成一个专门的库,理由就是 TypeScript 最擅长的那件事:**写和读是同一组 interface 的两半,住在同一个包里,writer 的参数类型 = reader 的返回类型**——「写出去的就是读得回的」由编译器背书,布局知识(路径、清洗、拆分、版本)全宇宙只有一份实现。
-
-## 库的边界
-
-`niceeval/results` 拥有:
-
-- **类型的家。** `RunSummary` / `EvalResult` / `StreamEvent` / `TraceSpan` / `O11ySummary` / `DiffData` 等结果类型和 `RESULTS_FORMAT` / `RESULTS_SCHEMA_VERSION` 常量搬进库;core 的 `src/types.ts` facade 反向 re-export,模块代码 `import type { … } from "../types.ts"` 的老习惯不破。
-- **writer。** 目录创建、attempt 工件增量落盘、summary 收尾(见下)。
-- **reader。** `openResults`:目录扫描、版本过滤、懒加载、快照切分、选择器(见下)。
-- **身份。** attempt 身份键与去重规则——读写两侧对「同一个 attempt」的理解必须一致,所以住在这。
-
-它不拥有:「看法」(聚合、指标、组件在 [Reports](reports.md))、渲染(view)、执行(runner)。库位于依赖图最底层,不 import core 的任何其它模块;必要时可以原样提成独立 npm 包(给「只想解析或产出 niceeval 结果的工具」用),但先作为子路径导出,不预设。
-
-四个消费方:
-
-| 消费方 | 用哪面 | 变化 |
-|---|---|---|
-| runner 的 `Artifacts()` reporter | 写 | 变薄壳:订阅 reporter 事件,转手调 writer,落盘行为不变 |
-| `niceeval view` | 读 | `readSummary` / `loadSummaries` 改吃 reader,版本判定与 skipped 姿势顺带统一 |
-| [Reports](reports.md) 的计算函数 | 读 | 第二档的全部数据入口 |
-| 你的脚本 / 第三方工具 | 读、写、发布 | 读:自定义分析;写:把别家平台的结果转成 niceeval 格式,`niceeval view` 直接能看;发布:`copyRun` 瘦身快照进仓库 / CDN——兼容性都由库保证,不用抄格式文档 |
-
-## 写:`createRunWriter`
-
-```typescript
-import { createRunWriter } from "niceeval/results";
-
-const writer = await createRunWriter(".niceeval", {
-  producer: { name: "niceeval", version: "0.12.0" },
-});
-writer.dir;                        // .niceeval/2026-07-07T…Z/(时间戳目录,: 与 . 已替换)
-
-await writer.writeAttempt(result); // 吃完整 EvalResult(events / diff 等大字段内联):
-                                   // 拆成 attempt 工件文件、算 artifactsDir(含路径清洗)、
-                                   // 回填 has* 引用,返回瘦身后的条目;空数据不落文件
-
-await writer.finish(summary);      // 写 summary.json,注入 format / schemaVersion / producer
-```
-
-attempt 工件按完成增量写入(与今天的行为一致):长 run 中途失败,已完成的 attempt 工件仍留在盘上。`writeAttempt` 做的「大字段拆出去、引用填回来」正是 reader 懒加载的逆操作——两个方向的同一份知识,终于写在同一个文件里。
-
-## 复制与瘦身:`copyRun`
-
-发布场景的第三个原语:把选中的快照(或整个 run)按格式感知地复制到另一个目录——只带指定工件、只带选中的 attempt,布局知识不外泄:
-
-```typescript
-import { copyRun } from "niceeval/results";
-
-await copyRun(snapshots, "site/data/run", {
-  artifacts: ["sources", "events", "trace"],   // diff 可达百 MB、o11y 查看器不读,发布时常见地不带
-});
-```
-
-动机来自真实消费者:coding-agent-memory-evals 把最新 run 快照进仓库供静态托管,今天是 40 行手写脚本——按 `summary.json` 的 mtime 挑「最新」(口径还错了:该挑快照,不该挑 run),再按白名单拷贝工件文件(布局知识第三次泄漏)。`copyRun` 之后这段只剩上面三行,挑选交给 `latestPerExperiment`(见[静态导出场景](reports.md#dx-模拟))。复制忠实于源:不改内容、不消毒——发布消毒是自由文本的事,归 [Reports 的 `cases({ redact })`](reports.md#计算函数与数据契约)。
-
-## 读:`openResults`
-
-输入是 `.niceeval/` 目录(或单个 run 目录),输出是类型化句柄:
-
-```typescript
-import { openResults } from "niceeval/results";
-
-const results = await openResults(".niceeval");
-
-results.runs;                  // RunHandle[]:一个落盘 run 目录一项,忠实反映磁盘,不合并
-results.snapshots;             // SnapshotHandle[]:experiment × run 的切片,选择与聚合的天然单元
-results.skipped;               // 读不了的 run:{ dir, reason, producerVersion? }[],不静默丢
-
-const run = results.runs[0];
-run.dir;                       // 绝对路径
-run.summary;                   // RunSummary(与写入侧同一类型)
-run.attempts;                  // AttemptHandle[]:summary.results[] 逐条包一层
-
-const attempt = run.attempts[0];
-attempt.result;                // EvalResult 瘦身条目:判决、断言、用量、成本、experiment 元数据
-attempt.ref;                   // { run, result }:证据引用(run 目录名 + results 下标),
-                               // Reports 的 MetricCell.refs 与 view 深链 #/attempt/... 同一身份
-await attempt.events();        // StreamEvent[] | null —— 重工件全部懒加载
-await attempt.trace();         // TraceSpan[] | null
-await attempt.o11y();          // O11ySummary | null
-await attempt.diff();          // DiffData | null(可达百 MB,所以必须懒)
-await attempt.sources();       // SourceArtifact[] | null
-```
-
-要点:
-
-- **懒加载即存在性判断。** 工件缺失返回 `null`,不抛错。今天 summary 里只有 `hasEvents` / `hasTrace` / `hasSources`,连 `hasO11y` / `hasDiff` 标记都没有——这类不对称全被方法语义吸收,消费方不再碰路径。
-- **版本过滤沿用格式规范。** 按 [Results Format 的版本规则](results-format.md#版本与升级设计)判定,不兼容的 run 进 `skipped` 并带 `producerVersion`(拼 `npx niceeval@<version> view` 提示的素材),与 [View 的报错与降级](view.md#报错与降级)同一姿势。
-- **同一进程内按 handle 记忆化。** 两个都要读 diff 的消费方不会把「可达百 MB」的 `diff.json` 读两遍;扫全部历史仍然可能慢,但要慢得线性、可预期。
-- **只读不写事实。** reader 的一切派生物删了随时可重算;唯一事实来源仍是磁盘上的 Results Format。
-
-## 快照:experiment × run,不是 run
-
-一次 CLI 调用写一个 run 目录,但一个 run 目录里可以装多个 experiment:`niceeval exp compare` 把整组对照跑进同一份 `summary.json`(runner 收的是 `agentRuns[]` 复数),顶层 `RunSummary.agent` 只是第一个配置的 agent(`src/runner/run.ts` 的 `summarize(allResults, firstAgent?.name …)`)。所以「每个 experiment 最新一次」没法用 run 粒度表达——周一跑了整组 compare,周二只重跑 `compare/bub-gpt-5.4`,bub 的最新快照在周二的 run 里,codex 的还在周一的 run 里。
-
-reader 把这层身份显式化:**快照 = 一个 experiment 在一个 run 里的那部分 attempt**,与 [View · Compare 计划](view.md#compare-挑两次运行对比)的 `(experimentId, startedAt)` 同一口径:
-
-```typescript
-interface SnapshotHandle {
-  experimentId: string;        // 结果里缺 experimentId 时以 "<agent>/<model>" 合成键,并记入 warnings
-  run: RunHandle;              // 所属物理 run
-  startedAt: string;
-  agent: string;               // 本快照自己的 agent —— 不是 run 顶层那个「第一个配置」
-  model?: string;
-  attempts: AttemptHandle[];
-  evalIds: string[];           // 覆盖的 eval 集合,供选择器做残缺检测(见下)
-}
-```
-
-`results.runs` 忠实磁盘,`results.snapshots` 只切片、不合并、不去重;合并与聚合永远发生在消费方([Reports](reports.md) 的计算函数,或你自己的脚本),reader 不预设看法——这条教训来自 view 的 `aggregateRows` 把全部历史揉成一行的现状(见 [View · 已知差异](view.md#已知的文档-vs-实现差异))。
-
-## 选择快照:`latestPerExperiment`
-
-多数消费场景先回答「现在什么水平」,所以第一批只有一个选择器:
-
-```typescript
-function latestPerExperiment(
-  snapshots: SnapshotHandle[],
-  opts?: { experiments?: string | string[] },   // experiment id 前缀过滤,同 CLI 语义
-): { snapshots: SnapshotHandle[]; warnings: string[] };
-```
-
-每个 experiment 取最新一次快照,最不误导。要累计历史就不调它;要更细的口径,普通 `.filter` 就够——选择器不是 DSL,只是最常用的那次筛选。
-
-但「最新」可能残缺:位置参数允许只重跑一道题(`niceeval exp midterm algebra/quadratic` 是正常的 debug 姿势),它产出的「最新快照」只有一道题,安静吞下的话下游报表就变成按一道题打分。所以**选择器同样要诚实**:把每个选中快照的 `evalIds` 与该 experiment 历史快照的并集对比,缩水就写进 `warnings`:
-
-```text
-warning: snapshot "midterm/bub-gpt-5.4" @ 2026-07-05T… covers 1 of 50 evals seen in history.
-  Re-run `niceeval exp midterm/bub-gpt-5.4` for a full snapshot, or pick another via .filter().
-```
-
-`warnings` 是普通字符串数组,渲染与否在消费方,但缺口永远被算出来,不静默。
-
-## 身份键与去重
-
-`--resume` 会把上一轮已通过的结果**原样合入**新 run 的 summary(`RunOptions.priorResults`):这让续跑出来的最新快照天然完整(正好配合 `latestPerExperiment`),代价是同一个 attempt 存在于多份落盘,而 `EvalResult` 今天没有任何「合入」标记。
-
-reader 忠实反映这份重复,不擅自去重;**跨快照聚合前按身份键去重是消费方的义务**:
-
-- 身份键:`(experimentId, evalId, attempt, startedAt)`,重复时保留最新 run 里的那份;
-- `startedAt` 缺失时宁可不去重也不误删,并记入 warnings;
-- [Reports 的计算函数](reports.md#计算函数与数据契约)内置这条;自己写脚本跨快照累计时,要么复用计算函数,要么自己按键去重。
-
-更根治的做法是 writer 给合入的结果打标——读写同库之后,这类格式演进只改一处实现,再同步 [Results Format](results-format.md) 规范即可;是否值得为它递增 `schemaVersion`,留给格式规范那边定。
-
-## 直接吃读取面:一个真实脚本
-
-折叠类的看法(表格、矩阵、成绩单、散点)去用 [Reports](reports.md) 的计算函数;直接吃 reader 服务的是连算法都自定义的场景,比如「每个 agent 的 shell 命令分布直方图」——那是分布,不是折叠:
-
-```typescript
-import { openResults } from "niceeval/results";
-
-const results = await openResults(".niceeval");
-const points = [];
-for (const snap of results.snapshots) {
-  for (const attempt of snap.attempts) {
-    const o11y = await attempt.o11y();
-    points.push({
-      agent: snap.agent,
-      eval: attempt.result.id,
-      passed: attempt.result.outcome === "passed",
-      shellCommands: o11y?.shellCommands.length ?? 0,
-    });
-  }
-}
-```
-
-即使在这条最深的路径上,用户也**不碰磁盘布局**——`artifactsDir` 拼接、存在性判断、版本过滤、快照切分都被库消化了。Results Format 若演进,全宇宙只有这一个库要改。
-
-## 相关阅读
-
-- [Results Format](results-format.md) —— 磁盘格式规范;本库是它唯一的官方读写实现,一格式一库,成对演进。
-- [Reports](reports.md) —— 建立在本库读取面之上的积木:指标、计算函数、React 组件。
-- [View](view.md) —— 内置前端;`readSummary` / `loadSummaries` / skipped 处理是本库 reader 要收编的现状。
-- [Experiments](experiments.md) —— experimentId 与可对比组从哪来。

package/docs/runner.md

@@ -1,104 +0,0 @@
-# Runner —— 执行引擎
-
-运行器是把"一批 eval"变成"一份结果"的调度引擎。它拥有对所有被测对象都一样的部分:发现、有界并发、早停、缓存、报告编排。被测对象的差异它一概不管 —— 它只对着 `Agent` 接口(统一动词 `send`)驱动。
-
-这是 niceeval "跑得快"承诺的落点,见 [Vision](vision.md#跑得快)。
-
-## 职责边界
-
-运行器**做**:发现 eval、算指纹决定跳过、建 attempt 列表、有界并发调度、早停、把结果交给报告器、落盘工件、定退出码。
-
-运行器**不做**:不知道怎么驱动 agent(那是 Agent/Adapter)、不知道怎么打分(那是 Scorer)、不知道结果存哪种格式细节(那是 Reporter)。它是协调者,不是执行者。
-
-## 发现
-
-`runner/discover.ts` 扫 `evals/`:
-
-- 找所有 `*.eval.ts`,`import` 后看默认导出 —— 单个 eval 用文件 id;数组则扇出,id 加零填充索引(`sql/0000`)。没有另一种基于目录约定的隐式发现——沙箱型 eval 也必须有一个 `.eval.ts` 文件。
-- 按相对路径排序,保证 id 稳定、输出可比。
-- 应用过滤:`niceeval exp <组|配置>` 后的位置参数(id 前缀,如 `weather` 命中 `weather/*`)、`--tag`。
-- `niceeval exp` 时另从 `experiments/` 扫实验文件(默认导出 `defineExperiment` 的 `.ts`),据路径推导实验 id;**目录段即"可对比组"** —— `niceeval exp <组>` 跑整个文件夹、同组互为对照(见 [实验怎么组织](experiments.md#实验怎么组织文件夹--一组可对比的实验))。实验的 `evals` 字段再筛要跑哪些 eval(见[矩阵展开](#矩阵展开与通过率))。
-
-## 调度:有界并发
-
-核心调度用 `Effect.forEach({ concurrency: maxConcurrency })` 实现:每个 attempt 跑在自己的 fiber,至多 `maxConcurrency` 个并发。报告回调走 **permit=1 的信号量串行化**,不阻塞执行 fiber。结果最后按**发现顺序**排序(而非完成顺序),让输出稳定可 diff。
-
-并发上限来源:`--max-concurrency` → 配置 `maxConcurrency` → 默认。沙箱型受沙箱后端容量约束(本地 Docker 别开太高;云后端可大)。
-
-## 矩阵展开与通过率
-
-一次 `exp` 运行把一批配置展成 attempt:通常来自**一组文件夹里的多个单一配置**(`compare/bub-gpt-5.4` + `compare/codex-gpt-5.4`,见 [实验怎么组织](experiments.md#实验怎么组织文件夹--一组可对比的实验));再 × `eval × runs`。比如 2 个实验配置 × `runs: 5` × 3 个 eval = 30 个 attempt。汇总按 `(agent, model, eval)` 分组,不再是单一判决,而是**通过率** + 平均耗时 / token / 成本:
-
-```text
-fixtures/button   claude-code   pass@5 = 4/5 (80%)   mean 34s · 58k tok · $0.44
-fixtures/button   codex         pass@5 = 3/5 (60%)   mean 41s · 72k tok · $0.39
-```
-
-用于衡量 agent 的稳定性(一次过 ≠ 可靠),以及跨 agent 的**质量 × 成本**对比。不写实验时退化成单 agent × `runs`。
-
-## 早停(earlyExit)
-
-取通过率本可以跑满 N 次,但若只关心"能不能做到",先过一次即可停其余:
-
-- 每个 eval 配一个 `AbortController`。
-- 某 attempt 通过且 `earlyExit` 开 → `abort()` 同 eval 其余 attempt;被 abort 的不计入分母。
-- 某 attempt `errored`(框架/环境层面的意外,不是断言没过)且 `earlyExit` 开 → 同样 `abort()` 其余 attempt。errored 通常会确定性重复,跑满 `runs` 只是重复烧同一个错误;只有 `failed` 才是 agent 行为的样本,值得跑满 `runs` 测通过率。
-- 默认开;`--no-early-exit` 关(想要完整通过率分布时)。
-
-## 预算护栏(budget)
-
-实验可设 `budget`(整轮估算成本上限 $),`--budget` 覆盖。运行器在派发每个 attempt 前检查已花成本(用量 × 价格表,见 [Observability](observability.md#用量与成本token--计费)),并给**在飞的 attempt 做预扣**:还没有任何完成样本时,同一 budget 域只放一个 attempt 在飞(先探出单次成本);有样本后按平均实测成本给每个在飞 attempt 预扣,预计总额到顶就等在飞的结算。已花到顶则**停止派发新 attempt**(在飞的跑完),整轮提前收尾并发 `run:budgetExceeded`。没有预扣的话,`maxConcurrency` 个 attempt 会在任何成本回写前全部起飞,实际花费能冲到 budget 的好几倍。借鉴 crabbox 的 spend cap,避免一次跑爆账单。
-
-## 缓存:指纹去重
-
-`runner/fingerprint.ts` 对每个 eval 算 `(eval 代码 + 相关配置)` 的哈希:
-
-- 上次已 `passed` 且指纹未变 → 默认**跳过**,直接复用结果。
-- 改了 fixture、改了配置、或 `--force` → 重跑。
-- 失败的结果不缓存(总会重试失败项)。
-
-让"改一个 case 重跑"只花那一个 case 的时间,而不是全量。
-
-## 超时:双层保护
-
-- **Adapter 内层超时** —— agent CLI 自己的超时。
-- **运行器外层超时** —— `Promise.race` 一个 `AbortSignal.timeout`,即使 agent 卡死也能强行收尾,标记该 attempt / eval 为 `errored`(error: timeout)并触发 abort。
-
-外层是兜底,保证一个卡死的 case 不会挂起整批。
-
-## 环境预置不进运行器
-
-niceeval **没有 run / experiment 级生命周期钩子**——运行器只固定"发现 → 调度 → 沙箱起停 / git 基线 / 采 diff → 评分 → 报告"这条主轴,不替用户在整轮实验前后跑任意 `setup` / `teardown`。要在跑 agent 前准备环境,分摊到三处已有职责:这条 eval 的沙箱预置走 `EvalDef.setup` 或 `test(t)`,连 agent / 装 CLI 走 [`SandboxAgent.setup`](adapters/contract.md#agent-契约),整轮共享的外部服务(mock API、DB)用外部编排(`docker compose` / CI 脚本)起停、经 env 传入。完整说明见 [环境预置放哪](sandbox.md#环境预置放哪)。
-
-**下游分析**(二次评分、自定义指标)走 [reporter](observability.md#reporters),不另设运行钩子——这是从 agent-eval 的 `onRunComplete` 收敛过来的(见 [Experiments 砍字段](experiments.md#从-agent-eval-砍掉了什么以及为什么))。
-
-## 运行器事件
-
-运行器发一串事件,供 CLI dashboard、reporter、外部集成消费:
-
-```text
-run:start          { total, agent, model }
-eval:start         { id, attempt }
-eval:complete      { id, attempt, outcome, durationMs, usage, estimatedCostUSD }
-run:earlyExit      { id }
-run:budgetExceeded { spentUSD, budgetUSD }
-run:saved          { outputDir }
-run:summary        { passed, failed, skipped, errored, durationMs, usage, estimatedCostUSD }
-```
-
-`outcome` 是互斥的判决分类:`passed` / `failed` / `errored` / `skipped`,没有 `scored` 中间态。`run:summary.failed` 只统计断言/评分不通过,环境、超时、adapter 或 agent runtime 问题统计到 `errored`。
-
-## 退出码
-
-- 全 `passed` → `0`。
-- 任一 `failed`(含 `--strict` 下 soft 未达标而改判的)→ 非零。
-- 任一 `errored` → 非零。
-
-供 CI 直接判红绿。
-
-## 相关阅读
-
-- [Architecture](architecture.md) —— 运行器在四段数据流里的位置与端到端时序。
-- [Sandbox](sandbox.md) —— 预热与复用的后端支持,以及环境预置放哪。
-- [Observability](observability.md) —— 运行器产出的工件与报告。
-- [CLI](cli.md) —— 暴露这些调度行为的标志。