niceeval 0.5.3 → 0.6.0

package/src/sandbox/types.ts

@@ -1,5 +1,7 @@
-// sandbox 域类型:Sandbox 接口、后端 spec(可辨识联合)、命令与文件 IO 的形状。
-// 「在哪里跑、如何隔离」的全部契约在这里;后端实现见本目录各文件,分发见 resolve.ts。
+// sandbox 域类型:Sandbox 接口、provider spec(可辨识联合)、命令与文件 IO 的形状。
+// 「在哪里跑、如何隔离」的全部契约在这里;provider 实现见本目录各文件,分发见 resolve.ts。
+
+import type { AgentSetup, AgentTeardown } from "../agents/types.ts";
 
 export interface CommandResult {
   stdout: string;
@@ -45,43 +47,82 @@ export interface ReadSourceFilesOptions {
   ignoreFiles?: string[];
 }
 
-/** 内置后端名;只在 sandbox/resolve.ts 内部做环境探测和 CLI `--sandbox` 解析用,不出现在 `sandbox` 字段的类型里。 */
-export type SandboxBackend = "docker" | "vercel" | "e2b";
+/** 内置 provider 名;不出现在 `sandbox` 字段的类型里(spec 用各自的 `provider` 判别字段区分)。 */
+export type SandboxProvider = "docker" | "vercel" | "e2b";
 
 /** 镜像/模板里的 Node 运行时版本。 */
 export type SandboxRuntime = "node20" | "node24";
 
 /**
- * Sandbox 的「数据结构」定义 —— 与 agent 一样可带参数(见 docs/sandbox.md)。
+ * SandboxSpec 四个变体共有的沙箱生命周期钩子挂载点:`.setup(fn)` / `.teardown(fn)` 链式方法,
+ * 由 `dockerSandbox()` / `vercelSandbox()` / `e2bSandbox()` / `defineSandbox()` 产出的对象上
+ * 直接可调。
+ *
+ * **语义**:环境预置层,俗称「动态镜像层」——本想直接烘进镜像/快照/模板,但内容要按实验
+ * (`ctx.flags` / `ctx.experimentId`)动态变化的东西:装某个实验专属的二进制、预热缓存、
+ * 写运行期才知道内容的 hook 文件、按 `ctx.experimentId` 载入/回存跨 attempt 的状态。
+ *
+ * **与另外两层 setup 的分工**(三者都在同一个沙箱生命周期里,各管一层):
+ *   · `sandbox.setup`(这里)—— 环境层,不知道具体跑哪个 eval / 接哪个 agent;
+ *   · `eval.setup` —— 任务层,准备这次 eval 的素材(如 `npm install` 起始项目依赖);
+ *   · `agent.setup` —— 协议层,接入被测 agent(装 CLI、写鉴权 / 模型配置)。
+ *
+ * **执行顺序**:沙箱就绪 → `sandbox.setup` 钩子 → workspace 上传 / git 基线 / `eval.setup` →
+ * `agent.setup` → `agent.tracing.configure` → 逐轮 `send`。`sandbox.setup` 特意排在 git
+ * 基线之前——它的改动会被提交进基线,不会被误算进 agent 产出的 diff。收尾按 LIFO:
+ * agent 级 cleanup / `agent.teardown` 先跑,`sandbox.teardown` 钩子最后跑(沙箱销毁前)。
+ *
+ * **多钩子**:`.setup(a).setup(b)` 按追加顺序依次执行(a 先 b 后);`.teardown(x).teardown(y)`
+ * 按追加的**逆序**执行(y 先 x 后)。每次调用都返回一个新 spec(不改变原对象),可继续链式。
+ *
+ * **失败语义**:`setup` 钩子抛错按执行错误计——与 `eval.setup` / `agent.setup` 抛错走同一条
+ * 路径,不新增错误分类;但不阻断该 attempt 已进入的收尾(已跑过的 setup 返回的 cleanup、
+ * `teardown` 钩子仍会在 finally 里跑)。`teardown` 钩子报错只作诊断(吞掉 / 记 log),不改变
+ * 已产出的结果——与 `agent.teardown` 现状一致。
+ */
+export interface SandboxHooks<Self> {
+  /** 已挂载的 setup 钩子,按追加顺序保存(内部读取,一般用不到)。 */
+  readonly setupHooks?: readonly AgentSetup[];
+  /** 已挂载的 teardown 钩子,按追加顺序保存,执行时逆序(内部读取,一般用不到)。 */
+  readonly teardownHooks?: readonly AgentTeardown[];
+  /** 追加一个沙箱级 setup 钩子,返回新 spec;详细契约见 {@link SandboxHooks}。 */
+  setup(fn: AgentSetup): Self;
+  /** 追加一个沙箱级 teardown 钩子,返回新 spec;详细契约见 {@link SandboxHooks}。 */
+  teardown(fn: AgentTeardown): Self;
+}
+
+/**
+ * Sandbox 的「数据结构」定义 —— 与 agent 一样可带参数(见 docs/feature/sandbox/library.md)。
  * 必须用工厂函数构造(`dockerSandbox()` / `vercelSandbox()` / `e2bSandbox()` / `defineSandbox()`),
  * 放进 config / experiment 的 `sandbox` 字段 —— 字段类型只接受这个数据结构,不接受裸字符串。
- * 各后端的参数互不相同 —— 这是个按 `backend` 区分的可辨识联合(discriminated union)。
+ * 各 provider 的参数互不相同 —— 这是个按 `provider` 区分的可辨识联合(discriminated union)。
+ * 四个变体都带 {@link SandboxHooks} 的 `.setup()` / `.teardown()` 链式方法。
  */
-export interface DockerSandboxSpec {
-  readonly backend: "docker";
+export interface DockerSandboxSpec extends SandboxHooks<DockerSandboxSpec> {
+  readonly provider: "docker";
   /** 覆盖默认镜像;默认按 runtime 选 `node:*-slim`。预制模板:传烘焙好 agent CLI 的镜像名。 */
   readonly image?: string;
   readonly runtime?: SandboxRuntime;
 }
-export interface VercelSandboxSpec {
-  readonly backend: "vercel";
+export interface VercelSandboxSpec extends SandboxHooks<VercelSandboxSpec> {
+  readonly provider: "vercel";
   /** 从已有快照起 microVM。预制模板:烘焙好 agent CLI 的 snapshotId。 */
   readonly snapshotId?: string;
   readonly runtime?: SandboxRuntime;
 }
-export interface E2BSandboxSpec {
-  readonly backend: "e2b";
+export interface E2BSandboxSpec extends SandboxHooks<E2BSandboxSpec> {
+  readonly provider: "e2b";
   /** e2b 模板名/ID。预制模板:烘焙好 agent CLI 的模板(如 `"niceeval-agents"`)。省略用 e2b 默认 `"base"`。 */
   readonly template?: string;
   /** 仅作记录;e2b 的 node 版本由模板决定,不在创建时选。 */
   readonly runtime?: SandboxRuntime;
 }
 /**
- * 用户自定义后端:`create` 直接产出一个 `Sandbox` 实例,不经 resolve.ts 的内置 backend switch。
- * 用 `defineSandbox()` 构造(见 src/define.ts)。`backend` 只用于展示 / 日志,不参与分发。
+ * 用户自定义 provider:`create` 直接产出一个 `Sandbox` 实例,不经 resolve.ts 的内置 provider switch。
+ * 用 `defineSandbox()` 构造(见 src/define.ts)。`provider` 只用于展示 / 日志,不参与分发。
  */
-export interface CustomSandboxSpec {
-  readonly backend: string;
+export interface CustomSandboxSpec extends SandboxHooks<CustomSandboxSpec> {
+  readonly provider: string;
   readonly runtime?: SandboxRuntime;
   readonly recommendedConcurrency?: number;
   readonly create: (opts: { timeout?: number; runtime?: SandboxRuntime }) => Promise<Sandbox>;
@@ -93,25 +134,25 @@ export type SandboxSpec = DockerSandboxSpec | VercelSandboxSpec | E2BSandboxSpec
 export type SandboxOption = SandboxSpec;
 
 export interface CommandOptions {
-  /** 追加/覆盖本命令的环境变量(与沙箱默认环境叠加,不清空默认值;各后端会保留自己固定的 `PATH` 等变量,不保证能被这里覆盖)。 */
+  /** 追加/覆盖本命令的环境变量(与沙箱默认环境叠加,不清空默认值;各 provider 会保留自己固定的 `PATH` 等变量,不保证能被这里覆盖)。 */
   env?: Record<string, string>;
   /** 本命令的工作目录;省略时落到 `Sandbox.workdir`。相对路径按 workdir 解析,绝对路径原样使用。 */
   cwd?: string;
   /**
    * 把本命令的输出也送进沙箱的「原生日志流」(于是 `docker logs` / Docker UI 的 Logs
    * 标签页能实时看到它)。给 agent 命令(codex exec / bub run / claude)开它,就能在容器
-   * 日志里看到 agent 的【原始输出】。后端各自实现(docker:tee 到 PID1 tail 的文件;
-   * 不支持的后端忽略)—— 日志怎么浮现是 backend 的事,adapter 只声明意图。
+   * 日志里看到 agent 的【原始输出】。provider 各自实现(docker:tee 到 PID1 tail 的文件;
+   * 不支持的 provider 忽略)—— 日志怎么浮现是 provider 的事,adapter 只声明意图。
    */
   stream?: boolean;
   /**
    * 以 root 跑本命令。默认 `false` —— 命令以沙箱的标准**非 root** 用户跑(agent 的自然环境)。
    * 给 setup 阶段装系统依赖用(`apt-get install …`、`pip install --break-system-packages …`)。
    *
-   * 语义跨后端一致:"本命令以 root 跑,否则以标准非 root 用户跑"。各后端映射到自己的原生机制
+   * 语义跨 provider 一致:"本命令以 root 跑,否则以标准非 root 用户跑"。各 provider 映射到自己的原生机制
    * (docker:`exec --user root`;E2B:`{ user: "root" }`;Vercel:`{ sudo: true }`;Daytona:`{ user }`)。
-   * 本就全程 root 的后端(如 Modal)视作 no-op;完全无法提权的后端可不支持(抛错)—— 但**默认值与
-   * 语义保持一致**,不因后端而变。
+   * 本就全程 root 的 provider(如 Modal)视作 no-op;完全无法提权的 provider 可不支持(抛错)—— 但**默认值与
+   * 语义保持一致**,不因 provider 而变。
    */
   root?: boolean;
 }
@@ -131,7 +172,7 @@ export interface Sandbox {
   runShell(script: string, opts?: CommandOptions): Promise<CommandResult>;
   /** 读取沙箱内文件的文本内容(UTF-8)。文件不存在时抛错,不返回空字符串——需要容错请自行 `.catch()`。 */
   readFile(path: string): Promise<string>;
-  /** 检查沙箱内路径是否存在。跨后端语义不完全一致:仅保证对普通文件可靠,对目录路径的行为不同后端不保证一致。 */
+  /** 检查沙箱内路径是否存在。跨 provider 语义不完全一致:仅保证对普通文件可靠,对目录路径的行为不同 provider 不保证一致。 */
   fileExists(path: string): Promise<boolean>;
   /**
    * 一次 shell 往返读全部源码文件(按扩展名收、按目录/文件名忽略)。
@@ -144,9 +185,9 @@ export interface Sandbox {
   uploadFiles(files: SandboxFile[], targetDir?: string): Promise<void>;
   /** 把本地磁盘上的一个目录整体上传进沙箱(递归读取本地文件后按 `uploadFiles` 写入);`opts.ignore` 是排除规则,省略 `targetDir` 落到 workdir。 */
   uploadDirectory(localDir: string, targetDir?: string, opts?: { ignore?: string[] }): Promise<void>;
-  /** 销毁沙箱占用的计算资源(容器/microVM)。调用后沙箱不可再用;是否可安全重复调用因后端而异,不要依赖这一点。 */
+  /** 销毁沙箱占用的计算资源(容器/microVM)。调用后沙箱不可再用;是否可安全重复调用因 provider 而异,不要依赖这一点。 */
   stop(): Promise<void>;
-  /** 本沙箱的稳定标识(各后端原生 ID,如 Docker 容器 ID 前缀);用于跨调用关联同一沙箱的会话状态,也用于日志展示。 */
+  /** 本沙箱的稳定标识(各 provider 原生 ID,如 Docker 容器 ID 前缀);用于跨调用关联同一沙箱的会话状态,也用于日志展示。 */
   readonly sandboxId: string;
   /**
    * 本地 OTLP 接收器的目标 host。
@@ -158,19 +199,19 @@ export interface Sandbox {
 
   /**
    * 可选:把一行写进容器的「主日志」(PID1 在 tail 它)——于是 `docker logs` /
-   * Docker UI 的 Logs 标签页能实时看到 agent 逐轮活动。docker 后端实现,其它可省略。
+   * Docker UI 的 Logs 标签页能实时看到 agent 逐轮活动。docker provider 实现,其它可省略。
    */
   appendLog?(line: string): Promise<void>;
 
   /**
    * 从沙箱内任意路径读取文件,返回二进制 Buffer。
-   * 对应各 backend:Docker getArchive / Vercel readFileToBuffer / e2b files.read(bytes) / …
+   * 对应各 provider:Docker getArchive / Vercel readFileToBuffer / e2b files.read(bytes) / …
    */
   downloadFile(path: string): Promise<Buffer>;
 
   /**
    * 向沙箱内任意路径写入文件(二进制)。
-   * 对应各 backend:Docker putArchive / Vercel fs.writeFile(Buffer) / e2b files.write / …
+   * 对应各 provider:Docker putArchive / Vercel fs.writeFile(Buffer) / e2b files.write / …
    */
   uploadFile(path: string, content: Buffer): Promise<void>;
 }

package/src/sandbox/vercel.ts

@@ -1,7 +1,7 @@
-// Vercel Sandbox 后端:用 @vercel/sandbox SDK 把 Vercel microVM 当隔离工作区跑 eval。
+// Vercel Sandbox provider:用 @vercel/sandbox SDK 把 Vercel microVM 当隔离工作区跑 eval。
 // 契约对齐 ../types.ts 的 Sandbox 接口,与 DockerSandbox 可互换。
 
-import { Sandbox as VSandbox } from "@vercel/sandbox";
+import { Sandbox as VSandbox, APIError } from "@vercel/sandbox";
 import type {
   Sandbox,
   CommandResult,
@@ -14,6 +14,17 @@ import { readSourceFilesByList } from "./source-files.ts";
 import { collectLocalFiles } from "./local-files.ts";
 import { resolveSandboxPath } from "./paths.ts";
 import { t } from "../i18n/index.ts";
+import { beforeExternalTerminalWrite } from "../tty-line.ts";
+import type { SandboxProvisionErrorKind } from "./errors.ts";
+
+/**
+ * vercel SDK 对单次 fetch 的 429 已有内部重试(见 @vercel/sandbox 的 with-retry.js,
+ * 5 次指数退避);这里再分类是为了给 create() 整体重试兜底——耗尽内部重试后仍返回 429
+ * 响应的 APIError,或 create() 轮询 session 状态过程里撞到的限流,都会走到这里。
+ */
+export function classifyProvisionError(e: unknown): SandboxProvisionErrorKind {
+  return e instanceof APIError && e.response.status === 429 ? "rate_limit" : "unknown";
+}
 
 // Vercel Sandbox 的默认工作区路径(SDK writeFiles 默认落这里)。
 const VERCEL_WORKDIR = "/vercel/sandbox";
@@ -111,15 +122,18 @@ export class VercelSandbox implements Sandbox {
       // 挂起的 stop(最长 15s)不该拖住触发 rotate 的那条命令,还烧新 session 的时长。
       // 失败只警告不静默(旧的到 session timeout 也会被平台回收)。
       void withTimeout(oldVsb.stop(), STOP_OLD_SESSION_TIMEOUT_MS).catch((stopErr) => {
+        beforeExternalTerminalWrite();
         console.error(
           `[VercelSandbox] warning: failed to stop rotated-out session, microVM may leak until session timeout: ${String(stopErr)}`,
         );
       });
+      beforeExternalTerminalWrite();
       console.error(t("vercel.rotated", {
         seconds: Math.round(elapsed / 1000),
         sessionId: newVsb.currentSession().sessionId,
       }));
     } catch (err) {
+      beforeExternalTerminalWrite();
       console.error(t("vercel.rotateFailed", {
         seconds: Math.round(elapsed / 1000),
         error: String(err),
@@ -176,7 +190,7 @@ export class VercelSandbox implements Sandbox {
   }
 
   // targetDir 已由 paths.ts 的 normalizeSandboxPaths 解析成绝对路径;这里再解析一次
-  // 只是对直接使用后端实例(未包 normalize)的幂等防御,提到 map 外只算一次。
+  // 只是对直接使用 provider 实例(未包 normalize)的幂等防御,提到 map 外只算一次。
   async writeFiles(files: Record<string, string>, targetDir?: string): Promise<void> {
     const base = resolveSandboxPath(this.workdir, targetDir);
     const entries = Object.entries(files).map(([p, content]) => ({

package/src/scoring/collector.ts

@@ -1,5 +1,5 @@
-// 断言收集器:test 期间记录断言(值级就地、作用域延迟),test 结束后对完整运行
-// 结果(ScoringContext)统一 finalize 成 AssertionResult[],再交判决。
+// 断言收集器:test 期间记录断言(值断言就地、作用域断言延迟),test 结束后对完整运行
+// 结果(ScoringContext)统一 finalize 成 AssertionResult[],再交判定。
 
 import type { AssertionResult, ScoringContext, Severity, SourceLoc } from "../types.ts";
 import { captureLoc } from "../source-loc.ts";
@@ -26,7 +26,7 @@ export interface Spec {
   evaluate(ctx: ScoringContext): number | EvalScore | Promise<number | EvalScore>;
 }
 
-/** 作者拿到的可链式句柄,改严重级 / 阈值(回头改 spec)。 */
+/** 作者拿到的可链式句柄,改严重度 / 阈值(回头改 spec)。 */
 export interface RecordHandle {
   atLeast(threshold: number): RecordHandle;
   gate(threshold?: number): RecordHandle;

package/src/scoring/judge.ts

@@ -1,6 +1,6 @@
-// LLM-as-judge:用一个与被测 agent 完全分离的评判模型做结构化 autoevals 评分。
+// LLM-as-judge:用一个与被测 agent 完全分离的裁判模型做结构化 autoevals 评分。
 //
-// 评判模型走 OpenAI 兼容的 /chat/completions。base_url + key 解析优先级:
+// 裁判模型走 OpenAI 兼容的 /chat/completions。base_url + key 解析优先级:
 //   judge.baseUrl / judge.apiKeyEnv  →  NICEEVAL_JUDGE_BASE / CODEX_BASE_URL  →  OpenAI 官方
 //
 // closedQA / factuality / summarizes 直接用 autoevals 库(braintrust)。

package/src/scoring/scoped.ts

@@ -191,7 +191,19 @@ export function maxToolCalls(max: number): Spec {
 }
 
 export function loadedSkill(skill: string): Spec {
-  return calledTool("load_skill", { input: { skill } });
+  return {
+    name: `loadedSkill(${skill})`,
+    severity: "gate",
+    // 读 skill.loaded 一等事件,不按名字猜工具调用:各 agent 表达 Skill 加载的原生形态不同
+    // (Claude Code 是 Skill tool_use、eve 是 load-skill action kind),归一化的责任在 parser。
+    evaluate: (ctx) => {
+      const loaded = ctx.events.filter((e): e is Extract<StreamEvent, { type: "skill.loaded" }> => e.type === "skill.loaded");
+      const matched = loaded.filter((e) => e.skill === skill);
+      // 没命中时把实际加载过的 skill 列出来(常见失败是名字对不上,而不是一个都没加载)。
+      const shown = matched.length ? matched : loaded;
+      return { score: matched.length ? 1 : 0, evidence: shown.length ? shown.map((e) => e.skill).join(", ") : undefined };
+    },
+  };
 }
 
 export function noFailedActions(): Spec {

package/src/scoring/types.ts

@@ -1,9 +1,9 @@
-// scoring 域类型:值级断言(expect 匹配器)、断言记录与结果、评分上下文、judge 配置。
+// scoring 域类型:值断言(expect 匹配器)、断言记录与结果、评分上下文、judge 配置。
 
 import type { Severity, SourceLoc } from "../shared/types.ts";
 import type { DerivedFacts, StreamEvent, Usage } from "../o11y/types.ts";
 
-/** 值级断言(expect 匹配器)。纯函数 score + 可链式改严重级 / 阈值。 */
+/** 值断言(expect 匹配器)。纯函数 score + 可链式改严重度 / 阈值。 */
 export interface ValueAssertion {
   readonly name: string;
   readonly severity: Severity;
@@ -12,8 +12,8 @@ export interface ValueAssertion {
   /** 转成硬门槛断言:未达阈值(省略 threshold 则按 score > 0 判定)整条 eval 判为 failed。返回新实例,不改原对象。 */
   gate(threshold?: number): ValueAssertion;
   /**
-   * 转成软阈值断言:未达 threshold 时该条记为 failed,但默认不拖累整条 eval 的 outcome;
-   * `--strict` 运行下,软阈值失败也会把整条 eval 的 outcome 计为 failed。返回新实例,不改原对象。
+   * 转成软阈值断言:未达 threshold 时该条记为 failed,但默认不拖累整条 eval 的 verdict;
+   * `--strict` 运行下,软阈值失败也会把整条 eval 的 verdict 计为 failed。返回新实例,不改原对象。
    */
   atLeast(threshold: number): ValueAssertion;
 }
@@ -27,7 +27,7 @@ export interface AssertionSpec {
   evaluate(ctx: ScoringContext): Promise<number> | number;
 }
 
-/** 断言评估完的结果(进判决 / 报告)。 */
+/** 断言评估完的结果(进判定 / 报告)。 */
 export interface AssertionResult {
   name: string;
   severity: Severity;
@@ -39,7 +39,7 @@ export interface AssertionResult {
   evidence?: string;
   /** 所属分组(t.group 标题)。纯报告用,不影响 passed/score。 */
   group?: string;
-  /** 断言在 eval 源码里的调用点(栈回溯抠出);view 把判决叠回这一行。 */
+  /** 断言在 eval 源码里的调用点(栈回溯抠出);view 把判定叠回这一行。 */
   loc?: SourceLoc;
 }
 
@@ -71,7 +71,7 @@ export interface DiffData {
   deletedFiles: string[];
 }
 
-export type ResultOutcome = "passed" | "failed" | "errored" | "skipped";
+export type Verdict = "passed" | "failed" | "errored" | "skipped";
 
 export interface JudgeConfig {
   model: string;

package/src/scoring/verdict.ts

@@ -1,13 +1,13 @@
-// 判决:把执行结果 + 断言 + 跳过原因折叠成一个 Outcome(见 docs/scoring.md)。
+// 判定:把执行结果 + 断言 + 跳过原因折叠成一个 Verdict(见 docs/feature/scoring/README.md)。
 
-import type { AssertionResult, ResultOutcome } from "../types.ts";
+import type { AssertionResult, Verdict } from "../types.ts";
 
-export function computeOutcome(input: {
+export function computeVerdict(input: {
   error?: string;
   assertions: readonly AssertionResult[];
   skipReason?: string;
   strict?: boolean;
-}): ResultOutcome {
+}): Verdict {
   if (input.error !== undefined) return "errored";
 
   for (const a of input.assertions) {

package/src/shared/aggregate.ts

@@ -1,13 +1,13 @@
 // CLI 表格(runner/reporters/table.ts)与 view 榜单(view/aggregate.ts)共用的聚合小工具。
-// 实验标签推导、token/成本求和、outcome 排序各只有一份 —— 否则同一个实验在终端和网页上
+// 实验标签推导、token/成本求和、verdict 排序各只有一份 —— 否则同一个实验在终端和网页上
 // 会显示成两个名字 / 两组数。保持环境无关(纯函数,只 type import)。
 
 import type { Usage } from "../o11y/types.ts";
 import type { EvalResult, ExperimentRunInfo } from "../runner/types.ts";
-import type { ResultOutcome } from "../scoring/types.ts";
+import type { Verdict } from "../scoring/types.ts";
 
 /** 明细行排序:失败最靠前(failed > errored > skipped > passed 的紧急程度)。 */
-export const OUTCOME_ORDER: Record<ResultOutcome, number> = {
+export const VERDICT_ORDER: Record<Verdict, number> = {
   failed: 0,
   errored: 1,
   skipped: 2,
@@ -34,6 +34,26 @@ export function displayExperimentName(id: string | undefined): string | undefine
   return id.split("/").filter(Boolean).at(-1) ?? id;
 }
 
+/**
+ * 实验 id 的组推导:去掉末段的目录前缀("compare/bub-low" → "compare");
+ * 无 "/" 的顶层实验不属于任何组,返回 undefined。view 榜单分组与自定义报告
+ * 的分组用同一份,两边的「组」永远指同一个东西。
+ */
+export function experimentGroupOf(experimentId: string): string | undefined {
+  if (!experimentId.includes("/")) return undefined;
+  return experimentId.split("/").slice(0, -1).join("/");
+}
+
+/**
+ * eval id 前缀过滤,同 CLI 位置参数的分段语义(src/runner/discover.ts):
+ * "algebra" 匹配自身与 "algebra/..." 子级,不误配 "algebra2";允许 "algebra/" 尾斜杠写法,等价。
+ */
+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 + "/"));
+}
+
 /** 无 experimentId 时的兜底标签。 */
 export function fallbackExperimentLabel(result: {
   experiment?: ExperimentRunInfo;

package/src/shared/types.ts

@@ -1,4 +1,4 @@
-// 真正跨域的原子类型:序列化 / 严重级 / 源码位置 / 生命周期。
+// 真正跨域的原子类型:序列化 / 严重度 / 源码位置 / 生命周期。
 // 各域的类型住在各自目录的 types.ts(o11y / sandbox / agents / scoring / context / runner),
 // src/types.ts 是聚合 facade —— 模块代码统一从那里 import,不必记住每个类型的家。
 
@@ -11,7 +11,7 @@ export type JsonValue =
   | JsonValue[]
   | { [key: string]: JsonValue };
 
-/** 断言的严重级:"gate" 失败必判整轮 failed;"soft" 默认只记录不拦截,仅在 `--strict` 模式或显式设阈值未达标时才计入失败。 */
+/** 断言的严重度:"gate" 失败必判整轮 failed;"soft" 默认只记录不拦截,仅在 `--strict` 模式或显式设阈值未达标时才计入失败。 */
 export type Severity = "gate" | "soft";
 
 /**

package/src/shared/{outcome.ts → verdict.ts}

@@ -1,23 +1,23 @@
-// server(aggregate.ts)与前端(app/lib/outcome.ts)共用的判决折叠口径。
+// server(aggregate.ts)与前端(app/lib/verdict.ts)共用的判定折叠口径。
 // 必须保持环境无关且只依赖 type import,vite 前端会直接打包它。
 // 单独成模块的原因:折叠/计票口径两边必须逐字一致,否则折叠行状态会和 KPI / 成功率对不上。
 
-import type { ResultOutcome } from "../types.ts";
+import type { Verdict } from "../types.ts";
 
-/** 折叠/计票只需要 outcome 字段;server 传 EvalResult,前端传 ViewResult 都满足。 */
-export interface OutcomeLike {
-  outcome: ResultOutcome;
+/** 折叠/计票只需要 verdict 字段;server 传 EvalResult,前端传 ViewResult 都满足。 */
+export interface VerdictLike {
+  verdict: Verdict;
 }
 
 /**
- * 把同一个 eval 的多轮 attempt 折叠成单一判决:任一轮通过 → 该 eval 通过(对齐 earlyExit
+ * 把同一个 eval 的多轮 attempt 折叠成单一判定:任一轮通过 → 该 eval 通过(对齐 earlyExit
  * 「先过一次即停」语义),否则按 failed > errored > skipped 取最严重的一个。
  */
-export function foldEvalOutcome(attempts: OutcomeLike[]): ResultOutcome {
-  const outcomes = attempts.map((a) => a.outcome);
-  if (outcomes.some((o) => o === "passed")) return "passed";
-  if (outcomes.some((o) => o === "failed")) return "failed";
-  if (outcomes.some((o) => o === "errored")) return "errored";
+export function foldEvalVerdict(attempts: VerdictLike[]): Verdict {
+  const verdicts = attempts.map((a) => a.verdict);
+  if (verdicts.some((o) => o === "passed")) return "passed";
+  if (verdicts.some((o) => o === "failed")) return "failed";
+  if (verdicts.some((o) => o === "errored")) return "errored";
   return "skipped";
 }
 
@@ -33,16 +33,16 @@ export interface EvalLevelStats {
 
 /**
  * 通过率与 passed/failed 一律按 eval 计票,不按 attempt:每个 eval 不管跑几轮都只占一票,先把它
- * 的多轮折叠成单一判决再计数。否则 runs>1 时同一 eval 的 N 次 attempt 各算一票 —— 尤其 earlyExit
+ * 的多轮折叠成单一判定再计数。否则 runs>1 时同一 eval 的 N 次 attempt 各算一票 —— 尤其 earlyExit
  * 开时通过的 eval 只留 1 次、失败的 eval 跑满 N 次,失败 eval 被重复计入分母,把通过率拉低
- * (见 docs/runner.md、docs/scoring.md)。keyOf 决定「一个 eval」的粒度:单实验按 eval id,
+ * (见 docs/runner.md、docs/feature/scoring/README.md)。keyOf 决定「一个 eval」的粒度:单实验按 eval id,
  * 跨实验组按 experimentId|eval id。
  */
-export function evalLevelStats<T extends OutcomeLike>(results: T[], keyOf: (r: T) => string): EvalLevelStats {
+export function evalLevelStats<T extends VerdictLike>(results: T[], keyOf: (r: T) => string): EvalLevelStats {
   const byEval = new Map<string, T[]>();
   for (const r of results) byEval.set(keyOf(r), [...(byEval.get(keyOf(r)) ?? []), r]);
   const counts = { passed: 0, failed: 0, errored: 0, skipped: 0 };
-  for (const group of byEval.values()) counts[foldEvalOutcome(group)] += 1;
+  for (const group of byEval.values()) counts[foldEvalVerdict(group)] += 1;
   const ran = counts.passed + counts.failed + counts.errored; // skipped 不进分母
   return { evals: byEval.size, ...counts, passRate: ran ? counts.passed / ran : 0 };
 }