niceeval 0.6.1 → 0.7.0

package/src/scoring/types.ts

@@ -2,12 +2,25 @@
 
 import type { Severity, SourceLoc } from "../shared/types.ts";
 import type { DerivedFacts, StreamEvent, Usage } from "../o11y/types.ts";
+import type { ResolvedCoverage } from "./coverage.ts";
 
-/** 值断言(expect 匹配器)。纯函数 score + 可链式改严重度 / 阈值。 */
+// 覆盖代数(解析 / 降级 / 聚合)住在 coverage.ts;类型经这里进聚合 facade(src/types.ts)。
+export type {
+  CoverageChannel,
+  ResolvedCoverage,
+  ResolvedCoverageChannel,
+  ResolvedCoverageStatus,
+} from "./coverage.ts";
+
+/** 值断言(expect 匹配器)。纯函数 score + 可链式改严重度 / 阈值 / optional。 */
 export interface ValueAssertion {
   readonly name: string;
   readonly severity: Severity;
   readonly threshold?: number;
+  /** `.optional()` 链过的标记:评不了只记 unavailable,不把 attempt 拖成 errored。 */
+  readonly isOptional?: boolean;
+  /** 期望条件的有界文本描述(如 `contains "Brooklyn"`),失败时进 AssertionResult.expected。 */
+  readonly expected?: string;
   score(value: unknown): number | Promise<number>;
   /** 转成硬门槛断言:未达阈值(省略 threshold 则按 score > 0 判定)整条 eval 判为 failed。返回新实例,不改原对象。 */
   gate(threshold?: number): ValueAssertion;
@@ -16,37 +29,82 @@ export interface ValueAssertion {
    * `--strict` 运行下,软阈值失败也会把整条 eval 的 verdict 计为 failed。返回新实例,不改原对象。
    */
   atLeast(threshold: number): ValueAssertion;
+  /**
+   * 允许这条断言证据缺席:评不了时只记录 `outcome: "unavailable"`,不影响判定。
+   * 与 severity 正交(severity 说影不影响质量判定,optional 说证据允不允许缺席)。返回新实例,不改原对象。
+   */
+  optional(): ValueAssertion;
 }
 
-/** 收集到 collector 里的一条断言记录(评估前)。 */
-export interface AssertionSpec {
+/**
+ * 断言记录的公共字段(见 docs/feature/scoring/architecture.md「断言记录」——字段契约的单点定义)。
+ */
+export interface AssertionBase {
+  /** 断言标题:t.group 内是该断言自己的摘要,组外是 matcher 摘要或 judge 问题;show/view 失败行的标题。 */
   name: string;
+  /** 所属分组路径:外层在前的 t.group 标题数组;无分组省略。纯报告用,不影响判定。 */
+  groupPath?: string[];
   severity: Severity;
-  threshold?: number;
-  /** 延迟评估:final 时拿到完整运行结果再算分。 */
-  evaluate(ctx: ScoringContext): Promise<number> | number;
+  /** 作者用 .optional() 显式允许该断言缺席;只改变 unavailable 的折叠方式(见 Severity 与 Verdict),不改变 severity 语义。 */
+  optional?: true;
+  /** matcher / judge 摘要,如 `equals(4)`、`closedQA("…")`;与 name 分开,供 show/view 同时展示分组标题与检查方式。 */
+  detail?: string;
+  /** 断言在 eval 源码中的调用点,`--eval` 把结果标回源码行的锚。 */
+  loc?: SourceLoc;
 }
 
-/** 断言评估完的结果(进判定 / 报告)。 */
-export interface AssertionResult {
-  name: string;
+/**
+ * 断言评估完的结果(进判定 / 报告)。判别键是 `outcome`——`unavailable` 是没有分数的独立态,
+ * 普通聚合代码按 `outcome` 分支就不可能把证据缺口算成零分。判定只消费
+ * `severity` / `outcome` / `optional` / `score` / `threshold`。
+ */
+export type AssertionResult =
+  | (AssertionBase & {
+      outcome: "passed" | "failed";
+      /** 归一化得分:值断言 0/1,judge 等打分断言 0..1。 */
+      score: number;
+      /** soft 断言的 .atLeast(x) 阈值;没有设阈值则省略。 */
+      threshold?: number;
+      /** 失败证据摘要:期望值的有界文本预览,供 show/view 直接展示。 */
+      expected?: string;
+      /** 失败证据摘要:实际值的有界文本预览。 */
+      received?: string;
+      /** 这条分数看着什么材料算出(judge 输入或被检查值预览);view 展开排查用,默认不展示。 */
+      evidence?: string;
+    })
+  | (AssertionBase & {
+      outcome: "unavailable";
+      /** 机器可读原因,如 "judge-model-unresolved"、"coverage:actions=partial"。 */
+      reason: string;
+    });
+
+/**
+ * 摘要面从完整 `AssertionResult[]` 选出的一条主失败断言。它只负责展示，不参与 verdict；
+ * `show @locator` / view Attempt 详情仍读取完整断言数组。字段保持结构化，使 CI 不必解析
+ * Human 的 `gate: …` 文案。
+ */
+export interface PrimaryAssertionSummary {
   severity: Severity;
+  /** `groupPath.join(" > ")`，无 group 时回退到断言 name。 */
+  assertion: string;
+  /** `detail ?? name`；与 assertion 相同时省略，避免重复。 */
+  matcher?: string;
+  expected?: string;
+  received?: string;
+  score?: number;
   threshold?: number;
-  score: number;
-  passed: boolean;
-  detail?: string;
-  /** 这条分数是看着什么材料算出来的(judge 收到的输入,或 t.check 失败时实际被检查的值)。view 展开排查「为什么是这个分」,默认不展示。 */
-  evidence?: string;
-  /** 所属分组(t.group 标题)。纯报告用,不影响 passed/score。 */
-  group?: string;
-  /** 断言在 eval 源码里的调用点(栈回溯抠出);view 把判定叠回这一行。 */
-  loc?: SourceLoc;
+  /** unavailable 断言的结构化原因。 */
+  reason?: string;
+  /** 同类因果失败中除主失败外的条数。 */
+  additionalFailures: number;
 }
 
 /** eval 作者拿到的可链式句柄(t.judge.autoevals.closedQA(...).atLeast(0.7))。 */
 export interface AssertionHandle {
   atLeast(threshold: number): AssertionHandle;
   gate(threshold?: number): AssertionHandle;
+  /** 允许这条断言证据缺席:unavailable 只保留在记录里,不影响判定(见 Severity 与 Verdict)。 */
+  optional(): AssertionHandle;
 }
 
 /** scoped / judge 断言在 final 评估时拿到的运行结果。 */
@@ -57,6 +115,8 @@ export interface ScoringContext {
   readonly scripts: Record<string, ScriptResult>;
   readonly usage: Usage;
   readonly status: "completed" | "failed" | "waiting";
+  /** 当前作用域(turn / session / attempt)解析后的证据覆盖;断言按它做三值折叠(见 scoped.ts)。 */
+  readonly coverage: ResolvedCoverage;
   /** 读沙箱里某文件的最终内容(judge / file 断言用)。 */
   readFile(path: string): Promise<string | undefined>;
 }
@@ -66,9 +126,46 @@ export interface ScriptResult {
   output: string;
 }
 
+// ── agent 归因增量(见 docs/feature/results/architecture.md「diff.json」与
+//    docs/feature/sandbox/architecture.md「变更归因:send 窗口与分类账」)──
+
+/** diff.json 的落盘形状:按时序的窗口数组(逐窗口 delta 序列,不做跨窗口压缩)。 */
+export type DiffArtifact = DiffWindow[];
+
+export interface DiffWindow {
+  /** send 窗口标签,与时间树 turn 节点、--execution 轮次同源(如 "s1/t2")。 */
+  window: string;
+  /** 该窗口内 agent 改动的文件;窗口内没有 workspace 变化时窗口仍落一条、changes 为空对象。 */
+  changes: Record<string, WindowChange>;
+}
+
+export interface WindowChange {
+  status: "added" | "modified" | "deleted";
+  /** 窗口开始时的内容;added 无此字段。 */
+  before?: string;
+  /** 窗口结束时的内容;deleted 无此字段。 */
+  after?: string;
+  /** 二进制文件不内联内容,只记字节数。 */
+  binary?: { beforeBytes?: number; afterBytes?: number };
+}
+
+/** 读取面在窗口序列之上派生的文件级视图(派生物可随时重算,不落盘)。 */
+export interface DiffFileSummary {
+  /** 净效果:首个触及窗口的起点 vs 最后触及窗口的终点;"none" = 动过但净无变化(创建又删除、改回原样)。 */
+  net: "added" | "modified" | "deleted" | "none";
+  /** 触及该文件的窗口标签,按时序。 */
+  windows: string[];
+  binary?: true;
+}
+
+/** agent 归因 diff 的消费视图:窗口序列(落盘事实)+ 派生的文件级摘要与终态读取。 */
 export interface DiffData {
-  generatedFiles: Record<string, string>;
-  deletedFiles: string[];
+  /** 落盘事实,原样。 */
+  windows: DiffWindow[];
+  /** 派生:每个被 agent 触及的文件一条。 */
+  files: Record<string, DiffFileSummary>;
+  /** 该文件最后一个触及窗口结束时的内容;净删除或从未触及返回 undefined。t.sandbox.diff.get 同一语义。 */
+  get(path: string): string | undefined;
 }
 
 export type Verdict = "passed" | "failed" | "errored" | "skipped";

package/src/scoring/verdict.ts

@@ -1,17 +1,29 @@
-// 判定:把执行结果 + 断言 + 跳过原因折叠成一个 Verdict(见 docs/feature/scoring/README.md)。
+// 判定:把执行结果 + 断言 + 跳过原因折叠成一个 Verdict
+// (见 docs/feature/scoring/architecture/severity-and-verdict.md)。固定优先级取第一个成立项:
+//   执行异常 / 任一非 optional 断言 unavailable → errored
+//   任一 gate 不通过,或 strict 下 soft 低于阈值 → failed
+//   显式 t.skip(reason)                         → skipped
+//   否则                                        → passed
+// errored 压过一切(执行证据已不可信);failed 压过 skipped(t.skip 不掩盖已记录的硬失败)。
 
-import type { AssertionResult, Verdict } from "../types.ts";
+import type { AssertionResult, AttemptError, Verdict } from "../types.ts";
 
 export function computeVerdict(input: {
-  error?: string;
+  error?: AttemptError;
   assertions: readonly AssertionResult[];
   skipReason?: string;
   strict?: boolean;
 }): Verdict {
   if (input.error !== undefined) return "errored";
 
+  // 作者写下的每条断言默认都要求可评估:非 optional 的 unavailable 使 attempt errored,
+  // 不分 gate / soft——「soft 全部评不了但 attempt 还绿着」是没有测量的绿,不允许出现。
   for (const a of input.assertions) {
-    if (a.passed) continue;
+    if (a.outcome === "unavailable" && !a.optional) return "errored";
+  }
+
+  for (const a of input.assertions) {
+    if (a.outcome !== "failed") continue;
     if (a.severity === "gate" || input.strict) return "failed";
   }
 

package/src/shared/aggregate.ts

@@ -1,4 +1,4 @@
-// CLI 表格(runner/reporters/table.ts)与 view 榜单(view/aggregate.ts)共用的聚合小工具。
+// report 聚合(report/aggregate.ts)与 view 榜单(view/app/lib/rows.ts)共用的聚合小工具。
 // 实验标签推导、token/成本求和、verdict 排序各只有一份 —— 否则同一个实验在终端和网页上
 // 会显示成两个名字 / 两组数。保持环境无关(纯函数,只 type import)。
 
@@ -45,22 +45,24 @@ 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 时的兜底标签。 */
 export function fallbackExperimentLabel(result: {
+  experimentId?: string;
   experiment?: ExperimentRunInfo;
   agent: string;
   model?: string;
 }): string {
-  if (result.experiment?.id) return displayExperimentName(result.experiment.id) ?? result.experiment.id;
+  if (result.experimentId) return displayExperimentName(result.experimentId) ?? result.experimentId;
   if (result.model) return `${result.agent}/${result.model}`;
   return result.agent || "ad hoc run";
 }

package/src/shared/types.ts

@@ -33,6 +33,37 @@ export interface SourceArtifact {
 /** 通用清理闭包(setup 返回值 / teardown 的形状),异步同步皆可,统一在 finally 里执行。 */
 export type Cleanup = () => Promise<void> | void;
 
+/** `ScopedFeedback.progress` 的入参:此刻正在做什么(短命状态,可被后续更新覆盖)。 */
+export interface ProgressUpdate {
+  message: string;
+  current?: number;
+  total?: number;
+}
+
+/** `ScopedFeedback.diagnostic` 的入参:运行结束后仍应保留的问题(永久事件)。 */
+export interface DiagnosticInput {
+  code: string;
+  level: "warning" | "error";
+  message: string;
+  data?: Readonly<Record<string, JsonValue>>;
+  /** 并发 attempt 产生同一问题时的去重键;相同 key 折叠成一条并累计次数。 */
+  dedupeKey?: string;
+}
+
+/**
+ * 作用域反馈 API(见 docs/feature/experiments/library.md「生命周期代码怎样向这次运行反馈」):
+ * sandbox provider、sandbox hook、eval 与 Agent Adapter 从 runner 注入的上下文获得同一套入口。
+ * - `progress` 是短命状态:Human profile 更新 active 行,Agent/CI 不逐条打印,不进最终结果;
+ * - `diagnostic` 是永久事件:进 Human/Agent/CI 的永久输出流并落进 attempt 的 diagnostics;
+ *   即使 level 为 "error" 也不自动改变 verdict(要 errored 抛异常,要 failed 用断言)。
+ * 两个方法都不接受 phase / scope / 颜色 / 输出流——runner 知道当前回调属于哪个生命周期阶段,
+ * 调用方不能冒充其它阶段。
+ */
+export interface ScopedFeedback {
+  progress(update: ProgressUpdate): void;
+  diagnostic(input: DiagnosticInput): void;
+}
+
 /**
  * 可本地化文案:纯字符串,或按 locale 代码(如 "en"、"zh-CN")映射多语言。
  * view 按当前界面语言挑一条,挑不到回退到 en / 第一条。

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.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 } : {}),
-    });
   }
-  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()];
 }