用 niceeval/results 直接读写结果数据

import { openResults } from "niceeval/results";

const results = await openResults(".niceeval");

results.experiments;           // Experiment[]:每个实验一项,挂着自己的全部历史
results.skipped;               // 读不了的落盘:{ dir, reason, schemaVersion?, producer? }[]

const exp = results.experiments.find((e) => e.id === "compare/bub-gpt-5.4")!;

exp.snapshots;                 // Snapshot[]:历次快照,最新在前
exp.latest;                    // 最新一次(= snapshots[0])
exp.evalIds;                   // 历史覆盖过的 eval 并集,残缺检测的依据

const snap = exp.latest;

snap.agent;                    // 本快照自己的 agent
snap.model;
snap.startedAt;                // 这次实验什么时候跑的
snap.completedAt;              // 收尾时补写;缺失 = 进程中断,已落盘的 attempt 仍可正常读
snap.dir;                      // 快照目录的绝对路径 —— 物理落盘就是快照本身,没有更低一层
snap.producer;                 // { name: "niceeval", version: "0.4.6" } —— 谁写的这份结果
snap.schemaVersion;            // 结果格式版本

for (const ev of snap.evals) {
  ev.id;                       // "algebra/quadratic"
  ev.attempts;                 // AttemptHandle[]:该题的全部 attempt
}
snap.attempts;                 // 不关心题目边界时,全部 attempt 平铺

const attempt = snap.evals[0].attempts[0];

attempt.evalId;                // "algebra/quadratic" —— 属于哪道题,不用绕 result
attempt.experimentId;          // 属于哪个实验
attempt.result;                // EvalResult:判定、断言、结构化 error/diagnostics、用量、成本
attempt.ref;                   // { snapshot, attempt }:证据引用,与 view 深链、报告格子的 refs 同一身份
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

[niceeval] truncated 51467156 → 262144 bytes

const events = await attempt.events();
for (const e of events ?? []) {
  for (const t of e.truncated ?? []) {
    console.log(`${t.path} 原始 ${t.originalBytes} 字节,已截断`);
  }
}

for (const s of results.skipped) {
  s.reason;                    // "incompatible-version" | "malformed" | "incomplete"
  s.schemaVersion;             // 那份结果声明的格式版本
  s.producer;                  // { name, version }:谁写的它
}

const latest = results.latest({
  experiments: "compare/",     // 可选:experiment id 前缀过滤(string | string[]),同 CLI 前缀语义
});

latest.snapshots;              // Snapshot[]:每个实验最新一次
latest.warnings;               // 结构化警告,不是渲染好的文本

latest.warnings[0];
// {
//   kind: "partial-coverage",
//   experimentId: "midterm/bub-gpt-5.4",
//   covered: 1,
//   total: 50,
//   message: "snapshot covers 1 of 50 evals seen in history; re-run `niceeval exp midterm/bub-gpt-5.4` for a full snapshot",
// }

import { openResults } from "niceeval/results";

const results = await openResults(".niceeval");
const points = [];
for (const exp of results.experiments) {
  for (const attempt of exp.latest.attempts) {
    const o11y = await attempt.o11y();
    points.push({
      agent: exp.latest.agent,
      eval: attempt.evalId,
      passed: attempt.result.verdict === "passed",
      shellCommands: o11y?.shellCommands.length ?? 0,
    });
  }
}

import { dedupeAttempts } from "niceeval/results";

const all = exp.snapshots.flatMap((s) => s.attempts);   // 跨快照累计:历史全量
const { attempts, warnings } = dedupeAttempts(all);      // resume 合入的重复被折掉

import { createResultsWriter } from "niceeval/results";

const writer = createResultsWriter(".niceeval", {
  producer: { name: "my-harness", version: "1.0.0" },
});

const snap = await writer.snapshot({   // 建快照目录(独占创建,撞名换后缀重试)+ 写 snapshot.json
  experimentId: "compare/my-agent",
  agent: "my-agent",
  model: "gpt-5.4",
  startedAt: sourceRun.startedAt,      // 必填:去重身份键以它为锚
});

for (const r of convertedResults) {
  await snap.writeAttempt(r.result, {  // 写 result.json(判定权威落点,一次写成)+ 拆 artifact 文件
    events: r.events,                  // 第二参 = artifact,都可选;缺哪样读取面就懒加载出 null
    diff: r.diff,
  });                                  // 拆 artifact 文件、算目录、回填引用,全在库内发生
}

await writer.finish();                 // 给每个快照补 completedAt,没有任何收尾聚合

import { openResults, copySnapshots } from "niceeval/results";

const results = await openResults(".niceeval");
await copySnapshots(results.latest(), "site-data/run", {
  artifacts: ["sources", "events", "trace", "o11y"],   // diff 不截断,缺省也不带;
});                                                     // 每个待发布文件还会经过 50 MiB 预检;
                                                        // o11y 只有几 KB,报告用到 turns 这类
                                                        // 读 o11y 的指标就把它带上,不然渲染成「—」