niceeval 0.4.5 → 0.5.0

package/src/results/writer.ts

@@ -0,0 +1,258 @@
+// createRunWriter:Results Format 的写入面(定稿见 docs/results-lib.md「写:createRunWriter」)。
+//
+// writer 与 reader 是同一组类型的两半,而且是字面的两半:reader 的 attempt.result 由
+// 「snapshot() 声明的快照级字段(experiment / agent / model / startedAt)+ writeAttempt 第一参」
+// 拼成,快照级字段不在 attempt 参数类型里(AttemptEntry 的 Omit),不存在「谁的值为准」。
+// 布局知识(时间戳目录、attempt 路径清洗、大字段拆工件、has* 回填、空数据不落文件)全在这里;
+// src/runner/reporters/artifacts.ts 是本文件的薄壳。
+
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { EvalResult, RunSummary, Usage } from "../types.ts";
+import type { LocalizedText } from "../types.ts";
+import type { DiffData, O11ySummary, SourceArtifact, StreamEvent, TraceSpan } from "../types.ts";
+import { RESULTS_FORMAT, RESULTS_SCHEMA_VERSION } from "../types.ts";
+import { attemptDirOf } from "./format.ts";
+
+export interface RunWriterOptions {
+  /** 谁在写这份结果:niceeval 自己,或第三方 harness(name 如实写,别冒充 "niceeval")。 */
+  producer: NonNullable<RunSummary["producer"]>;
+}
+
+/** 快照级元数据的家:一个 experiment 开一个;这些字段不塞进每条 attempt。 */
+export interface SnapshotDeclaration {
+  experiment: string;
+  agent: string;
+  model?: string;
+  /** 必填:身份键与去重以它为锚,官方产出永不缺。 */
+  startedAt: string;
+  /** 该实验已知的 eval 并集(残缺检测的分母);转换只覆盖部分题目时如实交代全集。 */
+  knownEvalIds?: string[];
+}
+
+/**
+ * writeAttempt 的第一参 = attempt 级条目:reader 的 attempt.result 中,快照级字段
+ * (agent / model / startedAt / experimentId)以外的全部;工件引用字段由 writer 回填。
+ */
+export type AttemptEntry = Omit<
+  EvalResult,
+  | "agent"
+  | "model"
+  | "startedAt"
+  | "experimentId"
+  | "events"
+  | "sources"
+  | "o11y"
+  | "trace"
+  | "diff"
+  | "rawTranscript"
+  | "artifactsDir"
+  | "artifactBase"
+  | "artifactAbsBase"
+  | "hasTrace"
+  | "hasEvents"
+  | "hasSources"
+>;
+
+/** writeAttempt 的第二参:reader 懒加载能拿到的那几样工件,全部可选;缺哪样读取面就懒加载出 null。 */
+export interface AttemptArtifacts {
+  events?: StreamEvent[];
+  trace?: TraceSpan[];
+  o11y?: O11ySummary;
+  diff?: DiffData;
+  sources?: SourceArtifact[];
+}
+
+export interface SnapshotWriter {
+  /** 增量落盘一条 attempt:拆工件文件、算 artifactsDir(含路径清洗)、回填 has* 引用;空数据不落文件。 */
+  writeAttempt(entry: AttemptEntry, artifacts?: AttemptArtifacts): Promise<void>;
+}
+
+/** finish() 从已写 attempt 推导 summary;个别推不出的字段走这里覆盖,不让调用方手拼整份 summary。 */
+export interface FinishOverrides {
+  name?: LocalizedText;
+  agent?: string;
+  model?: string;
+  startedAt?: string;
+  completedAt?: string;
+  durationMs?: number;
+  usage?: Usage;
+  estimatedCostUSD?: number;
+  /**
+   * @internal runner 专用:携带条目(--resume 合入)与最终排序只有调度器知道,Artifacts 薄壳
+   * 从这里交权威 results(可含内联大字段,writer 统一瘦身)。第三方转换不需要它。
+   */
+  results?: EvalResult[];
+}
+
+export interface RunWriter {
+  /** 本次 run 的输出目录(root 下的时间戳目录,: 与 . 已替换)。 */
+  readonly dir: string;
+  snapshot(decl: SnapshotDeclaration): SnapshotWriter;
+  /** 写出 summary.json 收尾;没走到这里的目录读取面归入 skipped("incomplete")。 */
+  finish(overrides?: FinishOverrides): Promise<RunSummary>;
+  /**
+   * @internal runner Artifacts 薄壳的增量工件落盘入口:runner 的条目自带 agent / model /
+   * experimentId / startedAt(且存在无 experiment 的普通 run),不经 snapshot() 声明。
+   */
+  writeAttemptArtifacts(result: EvalResult): Promise<void>;
+}
+
+export async function createRunWriter(root: string, opts: RunWriterOptions): Promise<RunWriter> {
+  const createdAt = new Date();
+  const dir = join(root, safeTimestamp(createdAt));
+  await mkdir(dir, { recursive: true });
+
+  const decls: SnapshotDeclaration[] = [];
+  const entries: EvalResult[] = [];
+  let finished = false;
+
+  const writeArtifacts = async (target: EvalResult | AttemptArtifacts, dirFor: EvalResult): Promise<void> => {
+    const attemptDest = join(dir, attemptDirOf(dirFor));
+    await mkdir(attemptDest, { recursive: true });
+    const writes: Promise<unknown>[] = [];
+    if (target.events?.length) writes.push(writeFile(join(attemptDest, "events.json"), JSON.stringify(target.events), "utf-8"));
+    if (target.sources?.length) writes.push(writeFile(join(attemptDest, "sources.json"), JSON.stringify(target.sources), "utf-8"));
+    if (target.trace?.length) writes.push(writeFile(join(attemptDest, "trace.json"), JSON.stringify(target.trace), "utf-8"));
+    if (target.o11y) writes.push(writeFile(join(attemptDest, "o11y.json"), JSON.stringify(target.o11y), "utf-8"));
+    if (target.diff) writes.push(writeFile(join(attemptDest, "diff.json"), JSON.stringify(target.diff), "utf-8"));
+    await Promise.all(writes);
+  };
+
+  return {
+    dir,
+
+    snapshot(decl: SnapshotDeclaration): SnapshotWriter {
+      if (!decl.experiment || !decl.agent || !decl.startedAt) {
+        throw new Error("writer.snapshot() requires experiment, agent and startedAt. They are snapshot-level identity: declare them once here instead of on each attempt.");
+      }
+      decls.push(decl);
+      return {
+        async writeAttempt(entry: AttemptEntry, artifacts?: AttemptArtifacts): Promise<void> {
+          // 快照级字段注入用「缺才补」:参数类型上它们不存在(Omit),运行时保守处理,
+          // 不覆盖调用方带来的值,也不打乱既有键序。
+          const full = { ...entry } as EvalResult;
+          full.experimentId ??= decl.experiment;
+          full.agent ??= decl.agent;
+          if (full.model === undefined && decl.model !== undefined) full.model = decl.model;
+          full.startedAt ??= decl.startedAt;
+          await writeArtifacts(artifacts ?? {}, full);
+          entries.push(
+            slimEntry({
+              ...full,
+              events: artifacts?.events,
+              sources: artifacts?.sources,
+              trace: artifacts?.trace,
+              o11y: artifacts?.o11y,
+              diff: artifacts?.diff,
+            }),
+          );
+        },
+      };
+    },
+
+    async writeAttemptArtifacts(result: EvalResult): Promise<void> {
+      await writeArtifacts(result, result);
+    },
+
+    async finish(overrides: FinishOverrides = {}): Promise<RunSummary> {
+      if (finished) throw new Error(`finish() already called for run directory ${dir}.`);
+      finished = true;
+
+      const results = overrides.results ? overrides.results.map(slimEntry) : entries;
+      const counts = { passed: 0, failed: 0, skipped: 0, errored: 0 };
+      let inTok = 0;
+      let outTok = 0;
+      let cost = 0;
+      let duration = 0;
+      for (const r of results) {
+        counts[r.outcome] += 1;
+        inTok += r.usage?.inputTokens ?? 0;
+        outTok += r.usage?.outputTokens ?? 0;
+        cost += r.estimatedCostUSD ?? 0;
+        duration += r.durationMs ?? 0;
+      }
+
+      const startedAt =
+        overrides.startedAt ??
+        decls.map((d) => d.startedAt).sort()[0] ??
+        createdAt.toISOString();
+      const agent = overrides.agent ?? decls[0]?.agent ?? results[0]?.agent ?? "";
+      const model = overrides.model ?? decls[0]?.model;
+      const estimatedCostUSD = overrides.estimatedCostUSD ?? (cost || undefined);
+      const snapshotsMeta = buildSnapshotsMeta(decls, startedAt);
+
+      // 键序是持久化契约的一部分(与 runner 直写时代逐字节一致):format / schemaVersion /
+      // producer 在最前,results 与 outputDir 收尾,可选键缺席时不留 undefined 占位。
+      const summary: RunSummary = {
+        format: RESULTS_FORMAT,
+        schemaVersion: RESULTS_SCHEMA_VERSION,
+        producer: opts.producer,
+        ...(overrides.name !== undefined ? { name: overrides.name } : {}),
+        agent,
+        ...(model !== undefined ? { model } : {}),
+        startedAt,
+        completedAt: overrides.completedAt ?? new Date().toISOString(),
+        passed: counts.passed,
+        failed: counts.failed,
+        skipped: counts.skipped,
+        errored: counts.errored,
+        durationMs: overrides.durationMs ?? duration,
+        usage: overrides.usage ?? { inputTokens: inTok, outputTokens: outTok },
+        ...(estimatedCostUSD !== undefined ? { estimatedCostUSD } : {}),
+        results,
+        outputDir: dir,
+        ...(snapshotsMeta ? { snapshots: snapshotsMeta } : {}),
+      };
+      await writeFile(join(dir, "summary.json"), JSON.stringify(summary, null, 2), "utf-8");
+      return summary;
+    },
+  };
+}
+
+/**
+ * 瘦身条目:去掉内联大字段,回填 artifactsDir 与 has* 引用。
+ * 携带条目(--resume 合入,rest 上带着 artifactBase 指向原 run 的工件目录)原样保留:
+ * 本轮没有任何新数据,不能重新推导出 false 的 has*,更不能编出一个本轮没写过文件的 artifactsDir。
+ */
+export function slimEntry(r: EvalResult): EvalResult {
+  const { events, sources, o11y, trace, diff, rawTranscript, ...rest } = r;
+  void rawTranscript;
+  if (rest.artifactBase) return rest;
+  return {
+    ...rest,
+    artifactsDir: attemptDirOf(r),
+    hasTrace: !!(trace && trace.length),
+    hasEvents: !!(events && events.length),
+    hasSources: !!(sources && sources.length),
+  };
+}
+
+/** 快照级元数据落盘:startedAt 只在与顶层不同(一 run 多快照、时刻不同)时记;空 meta 不落字段。 */
+function buildSnapshotsMeta(
+  decls: SnapshotDeclaration[],
+  summaryStartedAt: string,
+): RunSummary["snapshots"] | undefined {
+  const meta: NonNullable<RunSummary["snapshots"]> = {};
+  let any = false;
+  for (const decl of decls) {
+    const entry: { startedAt?: string; knownEvalIds?: string[] } = {};
+    if (decl.startedAt !== summaryStartedAt) entry.startedAt = decl.startedAt;
+    if (decl.knownEvalIds?.length) entry.knownEvalIds = [...decl.knownEvalIds];
+    if (Object.keys(entry).length > 0) {
+      // 同一 experiment 声明多次时后声明覆盖(knownEvalIds 取并集,覆盖事实只会变大不会缩水)。
+      const existing = meta[decl.experiment];
+      if (existing?.knownEvalIds && entry.knownEvalIds) {
+        entry.knownEvalIds = [...new Set([...existing.knownEvalIds, ...entry.knownEvalIds])];
+      }
+      meta[decl.experiment] = { ...existing, ...entry };
+      any = true;
+    }
+  }
+  return any ? meta : undefined;
+}
+
+/** run 目录名:Date#toISOString 把 : 与 . 换成 -(与 docs/results-format.md 一致)。 */
+export function safeTimestamp(d: Date): string {
+  return d.toISOString().replace(/[:.]/g, "-");
+}

package/src/runner/attempt.ts

@@ -228,7 +228,7 @@ async function runAttemptBody(
     signal,
     model: run.model,
     reasoningEffort: run.reasoningEffort,
-    flags: run.flags,
+    params: run.params,
     sandbox,
     session: createAgentSession(),
     telemetry,
@@ -270,7 +270,7 @@ async function runAttemptBody(
       sandbox,
       model: run.model,
       reasoningEffort: run.reasoningEffort,
-      flags: run.flags,
+      params: run.params,
       signal,
       log,
       judge,
@@ -442,7 +442,7 @@ async function collectSources(
 function experimentRunInfo(run: AgentRun): EvalResult["experiment"] {
   return {
     id: run.experimentId,
-    flags: run.flags,
+    params: run.params,
     runs: run.runs,
     earlyExit: run.earlyExit,
     sandbox: run.sandbox === undefined ? undefined : sandboxLabel(run.sandbox),

package/src/runner/fingerprint.ts

@@ -38,7 +38,7 @@ export async function computeFingerprint(
       experimentId: run.experimentId,
       agent: run.agent.name,
       model: run.model,
-      flags: run.flags,
+      params: run.params,
       sandbox: run.sandbox === undefined ? undefined : sandboxLabel(run.sandbox),
       timeoutMs: run.timeoutMs,
       strict: run.strict,

package/src/runner/reporters/artifacts.ts

@@ -1,15 +1,13 @@
 // 默认本地工件报告器:给 `niceeval view` 提供稳定的离线输入。
 //
-// 布局(每 eval-attempt 一个文件夹,重数据分文件;summary.json 只留榜单元数据):
-//   .niceeval/<run>/
-//     summary.json                         # run 元数据 + 各 result 的判决/usage/断言/引用(瘦身)
-//     <evalId>/<agent>/<model>/a<attempt>/
-//       events.json  sources.json  trace.json  o11y.json  diff.json
-// view 读 summary.json 渲染榜单,展开某条 trace 时再按需 fetch 它的 trace.json。
+// 本文件是 niceeval/results 写入面(createRunWriter)的薄壳:订阅 reporter 事件转手调 writer,
+// 自己不持有任何布局知识(时间戳目录、attempt 路径、大字段拆分、瘦身、版本元数据都在库内)。
+// 落盘格式见 docs/results-format.md;每 eval-attempt 一个文件夹,重数据分文件,
+// summary.json 只留榜单元数据,view 展开某条 trace 时再按需 fetch 它的 trace.json。
 
-import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { join } from "node:path";
-import { RESULTS_FORMAT, RESULTS_SCHEMA_VERSION, type EvalResult, type Reporter, type RunSummary } from "../../types.ts";
+import { readFile } from "node:fs/promises";
+import type { Reporter } from "../../types.ts";
+import { createRunWriter, type RunWriter } from "../../results/writer.ts";
 
 /** niceeval 自身的 npm 版本,写进 producer.version;版本不匹配时读取器靠它拼 npx 提示。 */
 let producerVersionPromise: Promise<string | undefined> | undefined;
@@ -20,91 +18,53 @@ function producerVersion(): Promise<string | undefined> {
   return producerVersionPromise;
 }
 
-/** 一个 attempt 的工件子目录(相对 run 根):<evalId>/<agent>/<model>[/<experiment>]/a<attempt>。 */
-function attemptDir(r: EvalResult): string {
-  const safe = (s: string) => s.replace(/[^\w.@-]/g, "_");
-  // evalId 里的 / 保留作目录层级,其余危险字符替换。
-  const id = r.id.replace(/[^\w./@-]/g, "_");
-  // experiment 段:两个实验可以同 agent 同 model、只差 flags(feature A/B),没有这一段
-  // 它们的工件会互相覆盖。experimentId 里的 / 不作层级(压成 _),整个实验一格。
-  const exp = r.experimentId ? `/${safe(r.experimentId)}` : "";
-  return `${id}/${safe(r.agent)}/${safe(r.model ?? "default")}${exp}/a${r.attempt}`;
-}
-
-/** summary.json 用的瘦身结果:去掉大数组(events/trace/o11y/diff/sources),换成目录引用 + 存在标记。 */
-function slimResult(r: EvalResult): EvalResult {
-  const { events, sources, o11y, trace, diff, rawTranscript, ...rest } = r;
-  void events;
-  void sources;
-  void o11y;
-  void trace;
-  void diff;
-  void rawTranscript;
-  // 携带结果(跨实验复用上次 pass,见 run.ts 的 carriedResults):本轮没有任何新数据,
-  // rest 上已经带着 artifactBase 指向旧 run 的产物目录,hasSources/hasEvents/hasTrace
-  // 也是从旧 summary 带过来的真值——不能因为"这轮没数据"就重新推导成 false / 编出一个
-  // 这轮压根没写过文件的新 artifactsDir(会让 artifactBase 在下次 withViewRefs 时被覆盖)。
-  if (rest.artifactBase) return rest;
-  return {
-    ...rest,
-    artifactsDir: attemptDir(r),
-    hasTrace: !!(trace && trace.length),
-    hasEvents: !!(events && events.length),
-    hasSources: !!(sources && sources.length),
-  };
-}
-
 /** Artifacts 报告器额外暴露输出目录:CLI 在 run 结束时打出 summary.json 路径给 agent 直读。 */
 export type ArtifactsReporter = Reporter & { outputDir(): string };
 
 export function Artifacts(root = ".niceeval"): ArtifactsReporter {
-  let outputDir = "";
-  const ensureDir = async (): Promise<void> => {
-    if (!outputDir) outputDir = join(root, safeTimestamp(new Date()));
-    await mkdir(outputDir, { recursive: true });
+  let writer: Promise<RunWriter> | undefined;
+  let dir = "";
+  const ensureWriter = (): Promise<RunWriter> => {
+    writer ??= (async () => {
+      const w = await createRunWriter(root, {
+        producer: { name: "niceeval", version: await producerVersion() },
+      });
+      dir = w.dir;
+      return w;
+    })();
+    return writer;
   };
 
   return {
-    outputDir: () => outputDir,
+    outputDir: () => dir,
 
     async onRunStart() {
-      outputDir = join(root, safeTimestamp(new Date()));
-      await mkdir(outputDir, { recursive: true });
+      // 每次 run 开一个新的时间戳目录(同一个 reporter 实例可能被复用)。
+      writer = undefined;
+      await ensureWriter();
     },
 
     // 每条结果一出来就把它的重数据落到自己的文件夹(增量、互不影响)。
+    // runner 的条目自带 agent / model / experimentId / startedAt(且存在无 experiment 的
+    // 普通 run),不经 snapshot() 声明,走 writer 的内部增量入口。
     async onEvalComplete(result) {
-      await ensureDir();
-      const dir = join(outputDir, attemptDir(result));
-      await mkdir(dir, { recursive: true });
-      const writes: Promise<unknown>[] = [];
-      if (result.events?.length)
-        writes.push(writeFile(join(dir, "events.json"), JSON.stringify(result.events), "utf-8"));
-      if (result.sources?.length)
-        writes.push(writeFile(join(dir, "sources.json"), JSON.stringify(result.sources), "utf-8"));
-      if (result.trace?.length)
-        writes.push(writeFile(join(dir, "trace.json"), JSON.stringify(result.trace), "utf-8"));
-      if (result.o11y) writes.push(writeFile(join(dir, "o11y.json"), JSON.stringify(result.o11y), "utf-8"));
-      if (result.diff) writes.push(writeFile(join(dir, "diff.json"), JSON.stringify(result.diff), "utf-8"));
-      await Promise.all(writes);
+      await (await ensureWriter()).writeAttemptArtifacts(result);
     },
 
-    // run 结束写瘦身 summary.json(版本元数据 + 榜单要的字段 + 工件引用)。
+    // run 结束写瘦身 summary.json:携带条目(--resume 合入)与最终排序只有调度器知道,
+    // 权威 results 经 overrides 交给 writer,瘦身与版本元数据注入都在库内发生。
     async onRunComplete(summary) {
-      await ensureDir();
-      const slim: RunSummary = {
-        format: RESULTS_FORMAT,
-        schemaVersion: RESULTS_SCHEMA_VERSION,
-        producer: { name: "niceeval", version: await producerVersion() },
-        ...summary,
-        outputDir,
-        results: summary.results.map(slimResult),
-      };
-      await writeFile(join(outputDir, "summary.json"), JSON.stringify(slim, null, 2), "utf-8");
+      await (await ensureWriter()).finish({
+        ...(summary.name !== undefined ? { name: summary.name } : {}),
+        agent: summary.agent,
+        ...(summary.model !== undefined ? { model: summary.model } : {}),
+        startedAt: summary.startedAt,
+        completedAt: summary.completedAt,
+        durationMs: summary.durationMs,
+        ...(summary.usage !== undefined ? { usage: summary.usage } : {}),
+        ...(summary.estimatedCostUSD !== undefined ? { estimatedCostUSD: summary.estimatedCostUSD } : {}),
+        results: summary.results,
+      });
     },
   };
 }
-
-function safeTimestamp(d: Date): string {
-  return d.toISOString().replace(/[:.]/g, "-");
-}

package/src/runner/reporters/braintrust.test.ts

@@ -85,7 +85,7 @@ describe("toBraintrustEvent", () => {
         model: "gpt-5.2",
         attempt: 1,
         outcome: "failed",
-        experiment: { id: "compare/codex", flags: { tape: true } },
+        experiment: { id: "compare/codex", params: { tape: true } },
         assertions: [{ name: "compiles", severity: "gate", score: 0, passed: false, detail: "tsc failed" }],
       }),
     );
@@ -96,7 +96,7 @@ describe("toBraintrustEvent", () => {
       outcome: "failed",
       model: "gpt-5.2",
       experiment: "compare/codex",
-      flags: { tape: true },
+      params: { tape: true },
       failedAssertions: [{ name: "compiles", detail: "tsc failed" }],
     });
     expect(event.id).toBe("compare/codex|algebra/quadratic|codex|gpt-5.2|a1");

package/src/runner/reporters/braintrust.ts

@@ -113,7 +113,7 @@ export function Braintrust(config: BraintrustConfig = {}): Reporter {
  * - scores:soft 断言按名字记分,gate 断言记在 `gate:` 前缀下 —— 实验 diff 里
  *   gate 回归和 soft 分数回归用同一套机制看。重名断言追加 `#n` 消歧,不静默覆盖。
  * - metrics:start/end(Braintrust 由此算时长)+ token 用量 + 估算成本;缺就不写,不编 0。
- * - metadata:身份维度(agent / model / experiment / attempt / flags)+ 失败断言明细。
+ * - metadata:身份维度(agent / model / experiment / attempt / params)+ 失败断言明细。
  */
 export function toBraintrustEvent(result: EvalResult): BraintrustLogEvent {
   const scores: Record<string, number> = {};
@@ -150,8 +150,8 @@ export function toBraintrustEvent(result: EvalResult): BraintrustLogEvent {
   };
   if (result.model !== undefined) metadata.model = result.model;
   if (result.experimentId !== undefined) metadata.experiment = result.experimentId;
-  if (result.experiment?.flags && Object.keys(result.experiment.flags).length > 0) {
-    metadata.flags = result.experiment.flags;
+  if (result.experiment?.params && Object.keys(result.experiment.params).length > 0) {
+    metadata.params = result.experiment.params;
   }
   if (result.skipReason !== undefined) metadata.skipReason = result.skipReason;
   const failed = result.assertions

package/src/runner/run.ts

@@ -104,7 +104,7 @@ export async function runEvals(opts: RunOptions): Promise<RunSummary> {
         if (run.experimentId && priorRunKeys.has(`${run.experimentId}|${evalDef.id}`)) continue;
         // key 标识「同一个运行配置下的同一条 eval」,earlyExit 的跳过/abort 只应作用于
         // 同 key 的重试轮。experimentId 必须进 key:两个实验可以同 agent 同 model、只差
-        // flags(feature A/B 正是这种形状),漏掉它会让先过的实验把其它实验的同名 eval
+        // params(feature A/B 正是这种形状),漏掉它会让先过的实验把其它实验的同名 eval
         // 整个跳掉——花了钱还丢结果。
         const key = `${run.experimentId ?? ""}|${run.agent.name}|${run.model ?? ""}|${evalDef.id}`;
         attempts.push({

package/src/runner/types.ts

@@ -12,7 +12,7 @@ import type { TestContext } from "../context/types.ts";
 
 export interface ExperimentRunInfo {
   id?: string;
-  flags?: Record<string, unknown>;
+  params?: Record<string, unknown>;
   runs?: number;
   earlyExit?: boolean;
   sandbox?: string;
@@ -49,9 +49,9 @@ export interface EvalResult {
   // ── 拆分工件的引用(Artifacts 报告器写 summary.json 时填;view 按需懒加载)──
   /** 本 attempt 工件目录(相对 run 根),下有 events/trace/o11y/diff.json。 */
   artifactsDir?: string;
-  /** view 拼好的工件目录(相对 view 输入根,供前端 fetch);loadSummaries 注入。 */
+  /** 工件目录(相对结果根,供前端 fetch 与懒加载回退);view 的 loader 注入,--resume 携带条目落盘时保留。 */
   artifactBase?: string;
-  /** 工件目录的绝对路径;loadSummaries 注入,供复制/展示用。 */
+  /** 工件目录的绝对路径;历史字段,当前读取面不再注入。 */
   artifactAbsBase?: string;
   hasTrace?: boolean;
   hasEvents?: boolean;
@@ -61,15 +61,16 @@ export interface EvalResult {
 /** `summary.json` 的格式标记;把 niceeval 报告和其它工具的同名文件区分开。 */
 export const RESULTS_FORMAT = "niceeval.results";
 /** 结果格式版本,只在破坏兼容读取时递增;读取器只认相同版本,缺失按 1。见 docs/results-format.md。 */
-export const RESULTS_SCHEMA_VERSION = 1;
+export const RESULTS_SCHEMA_VERSION = 2;
 
 export interface RunSummary {
   /** 恒为 "niceeval.results";和 schemaVersion、producer 一起构成持久化契约,永不移动或改名。 */
   format?: typeof RESULTS_FORMAT;
   /** 结果格式版本;与读取器不同即视为不兼容,提示用 producer.version 对应的 niceeval 查看。 */
   schemaVersion?: number;
-  /** 写这份报告的 niceeval;version 唯一用途是拼 `npx niceeval@<version> view` 提示。 */
-  producer?: { name: "niceeval"; version?: string; commit?: string };
+  /** 写这份报告的工具:niceeval 自己,或经 niceeval/results 写入面转换的第三方 harness。
+   *  name === "niceeval" 时 version 用于拼 `npx niceeval@<version> view` 提示;其它 name 如实报出。 */
+  producer?: { name: string; version?: string; commit?: string };
   /** 项目名(来自 config.name),透传给 `niceeval view` 顶部 hero 显示。 */
   name?: LocalizedText;
   agent: string;
@@ -87,13 +88,18 @@ export interface RunSummary {
   estimatedCostUSD?: number;
   results: EvalResult[];
   outputDir?: string;
+  /** 快照级元数据,按 experiment 键(缺 experimentId 时为 "<agent>/<model>" 合成键)存放:
+   *  startedAt 只在与顶层 startedAt 不同(一个 run 装多份不同时刻的快照)时需要;
+   *  knownEvalIds 是写入时刻该实验已知的 eval 并集(copySnapshots 自动补记,writer.snapshot 可声明)。
+   *  可选新增字段,不递增 schemaVersion(docs/results-format.md 版本规则)。 */
+  snapshots?: Record<string, { startedAt?: string; knownEvalIds?: string[] }>;
 }
 
-/** onRunStart 的运行规模:去重后 eval 数 × 配置(agent×model×flags)数 → 总运行(attempt)数。 */
+/** onRunStart 的运行规模:去重后 eval 数 × 配置(agent×model×params)数 → 总运行(attempt)数。 */
 export interface RunShape {
   /** 去重后实际要跑的 eval 数(= evals.length)。 */
   evals: number;
-  /** (agent, model, flags) 配置组合数;compare 多 agent 时 > 1。 */
+  /** (agent, model, params) 配置组合数;compare 多 agent 时 > 1。 */
   configs: number;
   /** 总 attempt 数(evals × configs × runs);逐行输出与汇总计数都按它。 */
   totalRuns: number;
@@ -168,8 +174,8 @@ export interface ExperimentDef {
   model?: string;
   /** 模型推理努力程度(如 "low"/"medium"/"high",取值由具体模型/adapter 决定);省略=用 agent 原生默认。经 ctx.reasoningEffort 透给 adapter 与 eval。 */
   reasoningEffort?: string;
-  /** 传给每次 attempt 的 flags,经 t.flags 暴露给 eval;与 CLI flag 合并(CLI 优先)。 */
-  flags?: Record<string, unknown>;
+  /** 传给每次 attempt 的 params,经 t.params 暴露给 eval;与 CLI flag 合并(CLI 优先)。 */
+  params?: Record<string, unknown>;
   /** 同一 eval 重复跑几次(结果各计一条 attempt);省略/CLI `--runs` 覆盖时默认 1。 */
   runs?: number;
   /** 一次重复(runs > 1)里某次 attempt 失败后是否跳过剩余重复;省略默认 true(提前退出省钱)。 */
@@ -261,12 +267,12 @@ export function runWho(run: Pick<AgentRun, "agent" | "model" | "experimentId">):
   return run.model ? `${run.agent.name}/${run.model}` : run.agent.name;
 }
 
-/** 一个 (agent, model, flags) 的运行配置 —— 由 CLI / 实验展开。 */
+/** 一个 (agent, model, params) 的运行配置 —— 由 CLI / 实验展开。 */
 export interface AgentRun {
   agent: Agent;
   model?: string;
   reasoningEffort?: string;
-  flags: Record<string, unknown>;
+  params: Record<string, unknown>;
   runs: number;
   earlyExit: boolean;
   sandbox?: SandboxOption;