niceeval 0.6.2 → 0.7.1

package/src/results/select.ts

@@ -1,8 +1,8 @@
-// 快照 Selection 与 attempt 去重(定稿见 docs/feature/results/library.md「选择快照」「身份键与去重」)。
+// 快照 Scope 与 attempt 去重(定稿见 docs/feature/results/library.md「选择快照」「官方现刻水位」「身份键与去重」)。
 //
-// 选择器只有一个(latest),长在集合上;它不是 DSL,只是最常用的那次筛选。
-// 选择器必须诚实:残缺、落后、未收尾都被算出来,以结构化 warnings 随 Selection 走 ——
-// 渲染与否在消费方(message 是渲染好的英文句子),但缺口不静默。
+// 选择器长在集合上(results.latest() / results.current()),不是 DSL,只是最常用的两种口径。
+// 选择器必须诚实:残缺、落后、未收尾都被算出来,以结构化 warnings 随 Scope 走 ——
+// 渲染与否在消费方(message 是渲染好的英文句子,以下一步收尾),但缺口不静默。
 
 import type {
   AttemptHandle,
@@ -10,22 +10,23 @@ import type {
   Eval,
   Experiment,
   Results,
-  Selection,
-  SelectionWarning,
+  Scope,
+  ScopeWarning,
   Snapshot,
 } from "./types.ts";
+import type { ExperimentRunInfo, JsonValue } from "../types.ts";
 import { evalPrefixPredicate } from "../shared/aggregate.ts";
 
 /** Results.latest() 的实现:每个实验取最新一次快照(= exp.snapshots[0]),生成挑选警告。 */
 export function selectLatest(
   experiments: Experiment[],
   opts?: { experiments?: string | string[] },
-): Selection {
+): Scope {
   const selected = filterExperiments(experiments, opts?.experiments);
   const snapshots = selected.map((exp) => exp.latest);
-  const warnings: SelectionWarning[] = [];
+  const warnings: ScopeWarning[] = [];
 
-  // stale 的基准:Selection 中最新的落盘(无阈值,如实触发;要阈值消费方按字段自比)。
+  // stale 的基准:Scope 中最新的落盘(无阈值,如实触发;要阈值消费方按字段自比)。
   let latestStartedAt = "";
   for (const snapshot of snapshots) {
     if (snapshot.startedAt > latestStartedAt) latestStartedAt = snapshot.startedAt;
@@ -44,6 +45,7 @@ export function selectLatest(
         covered,
         total,
         message: `snapshot covers ${covered} of ${total} evals seen in history; re-run \`niceeval exp ${exp.id}\` for a full snapshot`,
+        command: `niceeval exp ${exp.id}`,
       });
     }
     if (snapshot.startedAt < latestStartedAt) {
@@ -52,7 +54,8 @@ export function selectLatest(
         experimentId: exp.id,
         startedAt: snapshot.startedAt,
         latestStartedAt,
-        message: `snapshot "${exp.id}" (${snapshot.startedAt}) predates the latest run in this selection by ${humanizeGap(snapshot.startedAt, latestStartedAt)}`,
+        message: `snapshot "${exp.id}" (${snapshot.startedAt}) predates the latest run in this scope by ${humanizeGap(snapshot.startedAt, latestStartedAt)}; re-run \`niceeval exp ${exp.id}\` to align, or ignore if evals, agent and model are unchanged between the runs`,
+        command: `niceeval exp ${exp.id}`,
       });
     }
     if (!snapshot.completedAt) {
@@ -61,46 +64,101 @@ export function selectLatest(
         experimentId: exp.id,
         startedAt: snapshot.startedAt,
         dir: snapshot.dir,
-        message: `snapshot "${exp.id}" (${snapshot.startedAt}) has no completedAt — the run was interrupted; results may be incomplete`,
+        message: `snapshot "${exp.id}" (${snapshot.startedAt}) has no completedAt — the run was interrupted; re-run \`niceeval exp ${exp.id}\` for a complete snapshot`,
+        command: `niceeval exp ${exp.id}`,
       });
     }
   }
-  return makeSelection(snapshots, warnings);
+  return makeScope("latest-snapshots", snapshots, warnings);
 }
 
 /** selectCurrentResults 的范围输入:experiment id 前缀与 eval id 前缀,都可缺省。 */
 export interface ResultScope {
   /** experiment id 前缀(--experiment),分段匹配语义同 filterExperiments。 */
-  experiment?: string;
-  /** eval id 前缀(位置参数),收窄 Selection 覆盖的 eval;覆盖警告分母同步收窄到范围内。 */
+  experiment?: string | string[];
+  /** eval id 前缀(位置参数),收窄 Scope 覆盖的 eval;覆盖警告分母同步收窄到范围内。 */
   patterns?: string[];
 }
 
+// ───────────────────────── 可比性配置 ─────────────────────────
+
+/**
+ * current() 跨快照拼接的可比性前提所比较的字段集(docs/feature/results/library.md
+ * 「官方现刻水位」):会改变单题被测行为或判定的字段。runs / earlyExit / maxConcurrency /
+ * selectedEvalIds / evalFilterFingerprint / description 是编排与选题字段,不参与比较。
+ */
+export interface ComparabilityConfig {
+  agent: string;
+  model?: string;
+  reasoningEffort?: string;
+  flags?: Record<string, JsonValue>;
+  budget?: number;
+  timeoutMs?: number;
+  sandbox?: ExperimentRunInfo["sandbox"];
+}
+
+/** 一个快照的可比性配置投影;pairsByFlag 与 experimentListData 复用同一字段集。 */
+export function comparabilityConfigOf(snapshot: Snapshot): ComparabilityConfig {
+  const info = snapshot.experiment;
+  return {
+    agent: snapshot.agent,
+    ...(snapshot.model !== undefined ? { model: snapshot.model } : {}),
+    ...(info?.reasoningEffort !== undefined ? { reasoningEffort: info.reasoningEffort } : {}),
+    ...(info?.flags !== undefined ? { flags: info.flags } : {}),
+    ...(info?.budget !== undefined ? { budget: info.budget } : {}),
+    ...(info?.timeoutMs !== undefined ? { timeoutMs: info.timeoutMs } : {}),
+    ...(info?.sandbox !== undefined ? { sandbox: info.sandbox } : {}),
+  };
+}
+
+/** 可序列化值的深相等(对象键序无关;undefined 字段与缺席字段等价)。 */
+export function deepEqualJson(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (Array.isArray(a) || Array.isArray(b)) {
+    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
+    return a.every((item, i) => deepEqualJson(item, b[i]));
+  }
+  if (typeof a === "object" && typeof b === "object" && a !== null && b !== null) {
+    const keysA = Object.keys(a).filter((k) => (a as Record<string, unknown>)[k] !== undefined);
+    const keysB = Object.keys(b).filter((k) => (b as Record<string, unknown>)[k] !== undefined);
+    if (keysA.length !== keysB.length) return false;
+    return keysA.every((k) =>
+      deepEqualJson((a as Record<string, unknown>)[k], (b as Record<string, unknown>)[k]),
+    );
+  }
+  return false;
+}
+
 /**
- * 两个宿主(show / view)共用的现刻水位选择器:每个 experiment × eval 取时间上最新的那份
- * 判定,跨 run 合成。results.latest() 只挑「每实验最新快照」,带 eval 前缀的局部重跑会产出
- * 残缺快照;现刻水位承诺「不会因为一次局部重跑变残缺」,所以在实验的全部历史快照上逐 eval
- * 向更早的 run 补齐,再把合成好的 Selection 交给宿主注入报告槽——内置默认报告与 --report 吃
- * 同一份。
+ * 两个宿主(show / view)共用的现刻水位选择器:每个 experiment × eval 取「包含该 eval 的
+ * 最新快照」里的全部 attempt,跨 run 合成。results.latest() 只挑「每实验最新快照」,带 eval
+ * 前缀的局部重跑会产出残缺快照;现刻水位承诺「不会因为一次局部重跑变残缺」,所以在实验的
+ * 历史快照上逐 eval 向更早的 run 补齐,再把合成好的 Scope 交给宿主注入报告槽。
+ *
+ * **可比性前提**:每个 experiment 以最新快照的可比性配置(agent / model / reasoningEffort /
+ * flags / budget / timeoutMs / sandbox)为基准,只有配置与基准深相等的历史快照才参与补齐;
+ * 改过配置后只补跑部分 eval 时,旧配置快照覆盖的其余题不冒充新配置的水位,按 partial-coverage
+ * 如实告警。这保证 current() 产出的每个 experiment 只对应一套配置。
  *
  * 同一 eval 的全部 attempts 必须整批取自包含它的最新快照,不把历史快照的 attempts 平铺后
  * 按 eval 聚合——否则会把不同运行的重试混成一次虚构运行。合成快照的 dir/元数据只服务报告
  * 分组与来源展示,证据身份一律来自 attempt 自己的 ref。
- * 警告随 Selection 重算:partial-coverage 的分母 = 已知并集 ∩ 范围(范围收窄时分母同步收窄,
- * 不让范围外的缺口刷屏);stale / unfinished 与 results.latest() 同口径。
  */
-export function selectCurrentResults(results: Results, scope: ResultScope = {}): Selection {
+export function selectCurrentResults(results: Results, scope: ResultScope = {}): Scope {
   const match =
     scope.patterns && scope.patterns.length > 0 ? evalPrefixPredicate(scope.patterns) : () => true;
   const experiments = filterExperiments(results.experiments, scope.experiment);
 
   const snapshots: Snapshot[] = [];
-  const warnings: SelectionWarning[] = [];
+  const warnings: ScopeWarning[] = [];
 
   for (const exp of experiments) {
+    // 可比性基准 = 该实验最新快照的可比性配置;不一致的旧快照整份跳过,不贡献 attempt。
+    const baseline = comparabilityConfigOf(exp.latest);
     // 逐题取最新:快照按最新在前,首个出现即最新判定
     const taken = new Map<string, { ev: Eval; snapshot: Snapshot }>();
     for (const snapshot of exp.snapshots) {
+      if (!deepEqualJson(comparabilityConfigOf(snapshot), baseline)) continue;
       for (const ev of snapshot.evals) {
         if (!match(ev.id) || taken.has(ev.id)) continue;
         taken.set(ev.id, { ev, snapshot });
@@ -124,6 +182,8 @@ export function selectCurrentResults(results: Results, scope: ResultScope = {}):
       startedAt,
       agent: base.agent,
       ...(base.model !== undefined ? { model: base.model } : {}),
+      ...(base.experiment !== undefined ? { experiment: base.experiment } : {}),
+      ...(base.name !== undefined ? { name: base.name } : {}),
       producer: base.producer,
       schemaVersion: base.schemaVersion,
       evals,
@@ -133,8 +193,8 @@ export function selectCurrentResults(results: Results, scope: ResultScope = {}):
       ...(base.knownEvalIds ? { knownEvalIds: [...base.knownEvalIds] } : {}),
     });
 
-    // 残缺检测:跨快照补齐后仍缺,只可能是历史上见过(或 knownEvalIds 声明过)
-    // 却从未在可读落盘里出现的题 —— 分母收窄到范围内,不让范围外的缺口刷屏。
+    // 残缺检测:跨快照补齐后仍缺,来自「历史上见过却从未在可比配置的可读落盘里出现」的题
+    // (含改配置后未补跑的题)—— 分母收窄到范围内,不让范围外的缺口刷屏。
     const total = exp.evalIds.filter(match).length;
     if (evals.length < total) {
       warnings.push({
@@ -143,6 +203,7 @@ export function selectCurrentResults(results: Results, scope: ResultScope = {}):
         covered: evals.length,
         total,
         message: `verdicts cover ${evals.length} of ${total} evals seen in history; re-run \`niceeval exp ${exp.id}\` for a full snapshot`,
+        command: `niceeval exp ${exp.id}`,
       });
     }
   }
@@ -158,7 +219,8 @@ export function selectCurrentResults(results: Results, scope: ResultScope = {}):
         experimentId: snapshot.experimentId,
         startedAt: snapshot.startedAt,
         latestStartedAt,
-        message: `verdicts for "${snapshot.experimentId}" were produced at ${snapshot.startedAt}, before the latest run in this selection (${latestStartedAt})`,
+        message: `verdicts for "${snapshot.experimentId}" were produced at ${snapshot.startedAt}, ${humanizeGap(snapshot.startedAt, latestStartedAt)} before the latest run in this scope; re-run \`niceeval exp ${snapshot.experimentId}\` to align, or ignore if evals, agent and model are unchanged between the runs`,
+        command: `niceeval exp ${snapshot.experimentId}`,
       });
     }
     if (snapshot.completedAt === undefined) {
@@ -167,37 +229,45 @@ export function selectCurrentResults(results: Results, scope: ResultScope = {}):
         experimentId: snapshot.experimentId,
         startedAt: snapshot.startedAt,
         dir: snapshot.dir,
-        message: `snapshot "${snapshot.experimentId}" (${snapshot.startedAt}) is unfinished (the process was interrupted); completed attempts are read as-is, but the set may be incomplete`,
+        message: `snapshot "${snapshot.experimentId}" (${snapshot.startedAt}) is unfinished (the process was interrupted); completed attempts are read as-is, but the set may be incomplete — re-run \`niceeval exp ${snapshot.experimentId}\` for a complete snapshot`,
+        command: `niceeval exp ${snapshot.experimentId}`,
       });
     }
   }
 
-  return makeSelection(snapshots, warnings);
+  return makeScope("current-evals", snapshots, warnings);
 }
 
 /**
- * Selection 构造:filter 只删不换 —— 快照删减,warnings 修剪规则是
- * 「experimentId 不在幸存快照中的丢弃,非实验作用域的保留」(为将来非 per-experiment 的 kind 留位置)。
+ * Scope 构造:attempts 按口径物化(快照 attempts 的平铺);filter 只删不换 —— 快照删减,
+ * attempts 随之同步修剪,warnings 修剪规则是「experimentId 不在幸存快照中的丢弃,
+ * 非实验作用域的保留」(为将来非 per-experiment 的 kind 留位置)。
  */
-export function makeSelection(snapshots: Snapshot[], warnings: SelectionWarning[]): Selection {
+export function makeScope(
+  mode: Scope["mode"],
+  snapshots: Snapshot[],
+  warnings: ScopeWarning[],
+): Scope {
   return {
+    mode,
     snapshots,
+    attempts: snapshots.flatMap((s) => s.attempts),
     warnings,
-    filter(predicate: (snapshot: Snapshot) => boolean): Selection {
+    filter(predicate: (snapshot: Snapshot) => boolean): Scope {
       const kept = snapshots.filter(predicate);
       const survivors = new Set(kept.map((s) => s.experimentId));
       const keptWarnings = warnings.filter((w) => {
         const scope = (w as { experimentId?: unknown }).experimentId;
         return typeof scope !== "string" || survivors.has(scope);
       });
-      return makeSelection(kept, keptWarnings);
+      return makeScope(mode, kept, keptWarnings);
     },
   };
 }
 
 /**
  * 跨快照聚合前的身份键去重:(experimentId, evalId, attempt, startedAt)。
- * --resume 会把上一轮已通过的结果原样合入新快照,同一 attempt 因此存在于多份落盘;
+ * 携带合入会把上一轮已通过的结果原样合入新快照,同一 attempt 因此存在于多份落盘;
  * 重复时保留最新快照里的那份(内容相同,取新快照的副本让 ref 落在最新落盘上;
  * 位置取首次出现处,顺序稳定)。startedAt 缺失时宁可不去重也不误删,记入 warnings。
  */

package/src/results/types.ts

@@ -171,33 +171,49 @@ export interface Results {
   experiments: Experiment[];
   skipped: SkippedDir[];
   /**
-   * 每个实验取最新一次快照,返回 Selection(快照与挑选警告绑在一起走)。
+   * 每个实验取最新一次快照,返回 Scope(快照与挑选警告绑在一起走)。
    * `experiments` 是 experiment id 前缀过滤(string | string[]),同 CLI 位置参数语义。
    */
-  latest(opts?: { experiments?: string | string[] }): Selection;
+  latest(opts?: { experiments?: string | string[] }): Scope;
+  /**
+   * 官方现刻水位:每个 experiment × eval 取「包含该 eval 的最新快照」里的全部 attempt,
+   * 跨历史拼出当前判定水位。可比性前提:每个 experiment 以最新快照的可比性配置
+   * (agent / model / reasoningEffort / flags / budget / timeoutMs / sandbox)为基准,
+   * 配置不一致的旧快照不贡献 attempt,缺口走 partial-coverage
+   * (见 docs/feature/results/library.md「官方现刻水位」)。
+   */
+  current(opts?: { experiments?: string | string[] }): Scope;
 }
 
 /**
- * Selection:选出的快照 + 挑选过程算出的警告。渲染与否在消费方,但缺口永远被算出来。
- * 下游(Reports 计算函数、copySnapshots)收 `Selection | Snapshot[]`;
- * 手工挑的裸数组没有挑选过程,自然没有 warnings 可带,也如实。
+ * Scope(范围):选出的快照 + 口径 + 已按口径物化的 attempt 全集 + 挑选警告。
+ * 渲染与否在消费方,但缺口永远被算出来。下游(Reports 计算函数、copySnapshots)收
+ * `Scope | readonly Snapshot[]`;手工挑的裸数组没有挑选过程,自然没有 warnings 可带,也如实。
  */
-export interface Selection {
+export interface Scope {
+  /** 这份 Scope 的口径,字面写在数据上。 */
+  mode: "latest-snapshots" | "current-evals";
   snapshots: Snapshot[];
-  warnings: SelectionWarning[];
   /**
-   * 只删不换:返回新 Selection,快照删减,warnings 按规则修剪 ——
-   * experimentId 不在幸存快照中的丢弃,非实验作用域的保留。
+   * 按口径物化的 attempt 全集:消费 attempts 就自动正确,不需要自己 flatten snapshots,
+   * 也就不可能算错口径。官方计算函数同样只消费它。
+   */
+  attempts: AttemptHandle[];
+  warnings: ScopeWarning[];
+  /**
+   * 只删不换:返回新 Scope,快照删减,attempts 与 warnings 随之同步修剪 ——
+   * experimentId 不在幸存快照中的警告丢弃,非实验作用域的警告保留。
    * 「换成上一个完整快照」这类替换式重挑不给方法,回 exp.snapshots 自己挑。
    */
-  filter(predicate: (snapshot: Snapshot) => boolean): Selection;
+  filter(predicate: (snapshot: Snapshot) => boolean): Scope;
 }
 
 /**
- * 挑选警告:每种带 kind、可判断的结构化字段和渲染好的英文 message;
- * kind 是契约的一部分,全集与触发条件见 docs/feature/results/library.md「警告 kind 全集」。
+ * 挑选警告:每种带 kind、可判断的结构化字段和渲染好的英文 message;能用一条命令直接推进的
+ * kind 同时带 `command`(已替换真实 id,复制即跑)。kind 是契约的一部分,全集与触发条件见
+ * docs/feature/results/library.md「警告 kind 全集」。
  */
-export type SelectionWarning =
+export type ScopeWarning =
   | {
       /** 选中快照的覆盖 < 该实验已知 eval 并集(本地历史 ∪ knownEvalIds)。 */
       kind: "partial-coverage";
@@ -205,14 +221,18 @@ export type SelectionWarning =
       covered: number;
       total: number;
       message: string;
+      /** 一条可复制即跑的推进命令:`niceeval exp <experimentId>`。 */
+      command: string;
     }
   | {
-      /** 该实验选中的快照早于 Selection 中最新的落盘;无阈值,如实触发,要阈值消费方按字段自比。 */
+      /** 该实验选中的快照早于 Scope 中最新的落盘;无阈值,如实触发,要阈值消费方按字段自比。 */
       kind: "stale-snapshot";
       experimentId: string;
       startedAt: string;
       latestStartedAt: string;
       message: string;
+      /** 一条可复制即跑的推进命令:`niceeval exp <experimentId>`。 */
+      command: string;
     }
   | {
       /** 选中快照缺 completedAt(进程中断,未收尾);已落盘 attempt 照常读出,警告提示集合可能不完整。 */
@@ -222,6 +242,8 @@ export type SelectionWarning =
       /** 该快照目录的绝对路径。 */
       dir: string;
       message: string;
+      /** 一条可复制即跑的推进命令:`niceeval exp <experimentId>`。 */
+      command: string;
     };
 
 /** dedupeAttempts 的警告:身份键缺 startedAt,宁可不去重也不误删。 */

package/src/runner/feedback/human.test.ts

@@ -353,7 +353,7 @@ describe("完成页:失败优先摘要 + locator + show/view 下一步 + 快照
     expect(text).toContain("gate: Issue 15193: selected proposal matches the accepted proposal");
     expect(text).toContain("equals(4) · expected 4 · received 3");
     expect(text).toContain("Inspect: niceeval show @17m2k9p");
-    expect(text).toContain("Eval:    niceeval show @17m2k9p --eval");
+    expect(text).toContain("Eval:    niceeval show @17m2k9p --source");
     expect(text).toContain("Trace:   niceeval show @17m2k9p --execution");
     expect(text).toContain("Diff:    niceeval show @17m2k9p --diff");
     expect(text).toContain("Compare: niceeval view compare");

package/src/runner/run.ts

@@ -265,7 +265,7 @@ export async function runEvals(opts: RunOptions): Promise<RunSummary> {
   // budget 护栏:只按「已完成 attempt 的实测花费」判断,不做预测性节流。之前的实现会按
   // 「平均成本 × 在飞数」预扣,快到顶就让还没起飞的 attempt 排队等——这在探测阶段(还没有任何
   // 成本样本时)等价于把同一 budgetKey 的并发摁到一个很小的数,且完全没有文档承诺过这个副作用
-  // (`docs-site/zh/guides/write-experiment.mdx` 对 `budget` 的描述只有一句「这一格配置的预算
+  // (`docs-site/zh/how-to/write-experiment.mdx` 对 `budget` 的描述只有一句「这一格配置的预算
   // 上限」)。新语义:已完成 attempt 的花费加总一旦到顶,就不再放新 attempt 起飞(已经在飞的
   // 照常跑完,不会被中途打断);到顶之前不做任何预测性限流,并发完全由 globalSem / runSem 决定。
   // 代价是「已花 + 在飞未结算」的总花费可能短暂超出 budget——这是有意识的取舍:budget 是防止

package/src/sandbox/cli-commands.ts

@@ -47,7 +47,7 @@ export async function runSandboxCommand(
   const root = await resolveRegistryRoot(cwd, flags.run);
   if (root === undefined) {
     io.err(
-      `No .niceeval directory found from ${cwd} upward. Run this inside the project, or pass --run <results-root> to point at it.\n`,
+      `No .niceeval directory found from ${cwd} upward. Run this inside the project, or pass --results <results-root> to point at it.\n`,
     );
     return 1;
   }
@@ -71,7 +71,7 @@ export async function runSandboxCommand(
 async function resolveRegistryRoot(cwd: string, runFlag: string | undefined): Promise<string | undefined> {
   if (runFlag !== undefined) {
     const base = resolve(cwd, runFlag);
-    // --run 可以指 .niceeval 本身或它的父目录。
+    // --results 可以指 .niceeval 本身或它的父目录。
     return base.endsWith(".niceeval") ? base : `${base}/.niceeval`;
   }
   return findNiceevalRoot(cwd);

package/src/scoring/judge.test.ts

@@ -2,7 +2,7 @@
 // judge 解析与请求材料的单测:端点/凭据/模型解析结果必须进入真实请求,低分过不了 .gate()。
 // fixture judge client = 截获 globalThis.fetch(autoevals 底层 openai client 走全局 fetch),
 // 不起 HTTP server、不 spawn CLI。契约见 docs/feature/scoring/library/judge.md 与
-// docs-site/zh/concepts/judge.mdx 的解析优先级表;用例登记在
+// docs-site/zh/explanation/judge.mdx 的解析优先级表;用例登记在
 // docs/engineering/unit-tests/scoring/cases.md 的 Judge 分区。
 
 import { afterEach, describe, expect, it, vi } from "vitest";

package/src/shared/aggregate.ts

@@ -45,13 +45,14 @@ export function experimentGroupOf(experimentId: string): string | undefined {
 }
 
 /**
- * eval id 前缀过滤,同 CLI 位置参数的分段语义(src/runner/discover.ts):
- * "algebra" 匹配自身与 "algebra/..." 子级,不误配 "algebra2";允许 "algebra/" 尾斜杠写法,等价。
+ * eval id 前缀过滤,同 CLI 位置参数语义(docs/feature/reports/show.md「打开与收窄」):
+ * eval 位置参数是收窄过滤,按**裸前缀宽松匹配**——"algebra" 命中 "algebra"、"algebra/..."
+ * 也命中 "algebra2",多命中正是它的用途(与 `--experiment` 的按路径段匹配有意不同)。
  */
 export function evalPrefixPredicate(evals?: string | string[]): (id: string) => boolean {
   if (evals === undefined) return () => true;
-  const prefixes = (Array.isArray(evals) ? evals : [evals]).map((p) => p.replace(/\/+$/, ""));
-  return (id) => prefixes.some((prefix) => id === prefix || id.startsWith(prefix + "/"));
+  const prefixes = Array.isArray(evals) ? evals : [evals];
+  return (id) => prefixes.some((prefix) => id.startsWith(prefix));
 }
 
 /** 无 experimentId 时的兜底标签。 */

package/src/show/compose.ts

@@ -1,95 +1,78 @@
-// show 专属的跨 run 时间轴口径(--history;docs-site/zh/guides/viewing-results.mdx 是行为规范)。
+// show 专属的执行时间轴口径(--history;契约:docs/feature/reports/show.md「--history:一个 eval
+// 的执行时间轴」)。逐 attempt 而非逐快照:对 Scope 中匹配的每个 experimentId + evalId 分节,
+// 节内按 startedAt 升序列出跨快照按 attempt 身份键去重后的历次 attempt——时间、verdict、
+// 单行结果摘要(Scoring display 契约)、耗时、成本与 locator。resume 携带的复印件不占行。
 //
-// 现刻水位 Selection(两个宿主共用)住在 ../results/select.ts 的 selectCurrentResults;
-// 本文件只留 show 独有的时间轴计算:每个快照 / 每次真实执行一行,resume 携带的复印件不占行。
+// 现刻水位 Scope(两个宿主共用)住在 ../results/select.ts;本文件只留 show 独有的时间轴计算。
 // 数据只消费 niceeval/results 的读取面。
 
-import { foldEvalVerdict } from "../shared/verdict.ts";
 import { attemptCostUSD } from "../report/metrics.ts";
-import type { Verdict } from "../types.ts";
+import { compactAssertionSummary, primaryAssertionSummary, summaryText } from "../scoring/display.ts";
+import type { EvalResult, Verdict } from "../types.ts";
 import type { AttemptHandle, Experiment } from "../results/index.ts";
 
 // ───────────────────────── 时间轴(--history)─────────────────────────
 
-export interface EvalHistoryRow {
-  /** 该次真实执行所在 run(快照)的时刻。 */
-  startedAt: string;
+export interface AttemptHistoryRow {
+  /** 该 attempt 自己的开始时刻(ISO);第三方落盘可能缺失,如实缺省、排序沉底。 */
+  startedAt?: string;
   verdict: Verdict;
-  attempts: number;
+  /** 单行结果摘要(display 契约):主失败断言 / 结构化 error 一层摘要 / skip 理由;passed 缺省。 */
+  summary?: string;
+  durationMs: number;
   costUSD: number | null;
-  /** 最新一次 attempt 的第一条失败断言("gate calledTool(...)")。 */
-  failedAssertion?: string;
-  /** errored 时的错误摘要。 */
-  error?: string;
+  /** attempt 的稳定引用(`@` 前缀),复制给 `niceeval show @<locator>` 下钻。 */
+  locator?: string;
 }
 
-/** attempt 的身份键(去重口径与 dedupeAttempts 一致);缺 startedAt 时不参与去重(宁可多列不误删)。 */
+/** attempt 的身份键(去重口径与 results 的 dedupeAttempts 一致);缺 startedAt 时不参与去重(宁可多列不误删)。 */
 function attemptKey(attempt: AttemptHandle): string | undefined {
   const r = attempt.result;
   return r.startedAt === undefined ? undefined : `${r.attempt}|${r.startedAt}`;
 }
 
 /**
- * 单 eval 的跨 run 时间轴:每次真实执行一行,新→旧。--resume 携带的复印件
- * (身份键与原判定相同的条目)不占行 —— 否则趋势会被复印件灌满假数据。
+ * 单行结果摘要:与榜单 Result 单元格同一条 display 契约(docs/feature/scoring/library/display.md)——
+ * 结构化 error 取一层 message 摘要,skipped 取理由,failed 取主失败断言的紧凑单行;passed 无摘要。
  */
-export function evalHistory(exp: Experiment, evalId: string): EvalHistoryRow[] {
-  const rows: EvalHistoryRow[] = [];
+function rowSummary(result: EvalResult): string | undefined {
+  if (result.error !== undefined) return summaryText(result.error.message);
+  if (result.skipReason !== undefined) return summaryText(result.skipReason);
+  const summary = primaryAssertionSummary(result.assertions, result.verdict);
+  return summary === undefined ? undefined : compactAssertionSummary(summary);
+}
+
+/**
+ * 一个 experimentId + evalId 的执行时间轴:跨快照收集全部 attempt,按身份键去重
+ * (--resume 携带的复印件不占行),startedAt 升序;缺 startedAt 的行按发现顺序沉底。
+ */
+export function attemptHistory(exp: Experiment, evalId: string): AttemptHistoryRow[] {
   const seen = new Set<string>();
-  // 旧→新扫描,首次出现的身份键 = 真实执行;最后整体反转成新→旧
-  for (const snapshot of [...exp.snapshots].reverse()) {
+  const dated: AttemptHistoryRow[] = [];
+  const undated: AttemptHistoryRow[] = [];
+  // 新→旧扫描(exp.snapshots 已按新→旧排序):同一身份键保留最新落盘里的那份
+  // (locator 在携带条目上原样复制,取哪份行内容相同;取最新与 dedupeAttempts 口径一致)。
+  for (const snapshot of exp.snapshots) {
     const ev = snapshot.evals.find((e) => e.id === evalId);
     if (!ev) continue;
-    const fresh: AttemptHandle[] = [];
     for (const attempt of ev.attempts) {
       const key = attemptKey(attempt);
-      if (key === undefined) {
-        fresh.push(attempt);
-        continue;
+      if (key !== undefined) {
+        if (seen.has(key)) continue;
+        seen.add(key);
       }
-      if (seen.has(key)) continue;
-      seen.add(key);
-      fresh.push(attempt);
-    }
-    if (fresh.length === 0) continue; // 纯复印件:判定在更早的行里已经出现过
-    let cost: number | null = null;
-    for (const attempt of fresh) {
-      const c = attemptCostUSD(attempt.result);
-      if (c !== null) cost = (cost ?? 0) + c;
+      const r = attempt.result;
+      const row: AttemptHistoryRow = {
+        ...(r.startedAt !== undefined ? { startedAt: r.startedAt } : {}),
+        verdict: r.verdict,
+        ...(rowSummary(r) !== undefined ? { summary: rowSummary(r) } : {}),
+        durationMs: r.durationMs,
+        costUSD: attemptCostUSD(r),
+        ...(attempt.locator !== undefined ? { locator: attempt.locator } : {}),
+      };
+      (row.startedAt === undefined ? undated : dated).push(row);
     }
-    const latest = fresh[fresh.length - 1];
-    const failed = latest.result.assertions.find((a) => a.outcome !== "passed");
-    rows.push({
-      startedAt: snapshot.startedAt,
-      verdict: foldEvalVerdict(fresh.map((a) => a.result)),
-      attempts: fresh.length,
-      costUSD: cost,
-      ...(failed ? { failedAssertion: `${failed.severity} ${failed.name}` } : {}),
-      ...(latest.result.error !== undefined ? { error: latest.result.error.message } : {}),
-    });
   }
-  return rows.reverse();
-}
-
-export interface ExperimentHistoryRow {
-  startedAt: string;
-  passedEvals: number;
-  totalEvals: number;
-  costUSD: number | null;
-}
-
-/** 实验级 per-run 通过率序列(裸 `show --history`):每个快照一行,新→旧。 */
-export function experimentHistory(exp: Experiment): ExperimentHistoryRow[] {
-  return exp.snapshots.map((snapshot) => {
-    let passed = 0;
-    for (const ev of snapshot.evals) {
-      if (foldEvalVerdict(ev.attempts.map((a) => a.result)) === "passed") passed += 1;
-    }
-    let cost: number | null = null;
-    for (const attempt of snapshot.attempts) {
-      const c = attemptCostUSD(attempt.result);
-      if (c !== null) cost = (cost ?? 0) + c;
-    }
-    return { startedAt: snapshot.startedAt, passedEvals: passed, totalEvals: snapshot.evals.length, costUSD: cost };
-  });
+  dated.sort((a, b) => (a.startedAt! < b.startedAt! ? -1 : a.startedAt! > b.startedAt! ? 1 : 0));
+  return [...dated, ...undated.reverse()];
 }