niceeval 0.4.3 → 0.4.5

package/src/runner/run.ts

@@ -2,46 +2,60 @@
 // 职责只有编排:指纹缓存在 fingerprint.ts,单 attempt 生命周期在 attempt.ts,
 // reporter 编排 / 汇总在 report.ts,Sandbox 适配器在 remote-sandbox.ts。
 
+import { readFile } from "node:fs/promises";
 import { Effect, Cause, Duration, Exit } from "effect";
 import { probeJudge } from "../scoring/judge.ts";
 import { t } from "../i18n/index.ts";
 import { cacheKey, computeFingerprint } from "./fingerprint.ts";
 import { OtelReceiverPool } from "../o11y/otlp/turn-otel.ts";
 import { runAttemptEffect } from "./attempt.ts";
-import { runReporter, emitReporterEvent, summarize } from "./report.ts";
-import type { Agent, EvalResult, JudgeConfig, RunShape, RunSummary } from "../types.ts";
-import type { Attempt, RunOptions } from "./types.ts";
+import { runReporter, emitReporterEvent, scopeReporter, summarize } from "./report.ts";
+import type { Agent, EvalResult, JudgeConfig, Reporter, RunShape, RunSummary } from "../types.ts";
+import type { AgentRun, Attempt, RunOptions } from "./types.ts";
 
 export type { AgentRun, RunOptions } from "./types.ts";
 
+/** 收集本次要探测的 judge 配置:只看「实际要跑、且源码里出现 judge 字样」的 eval 的生效
+ *  配置(evalDef.judge ?? config.judge,与 attempt.ts 的 resolveJudge 一致),按
+ *  model|baseUrl|apiKeyEnv 去重。要跑的 eval 都不用 judge 时返回空 —— 全局配了 judge
+ *  也不探测,纯确定性断言的运行不再被 judge key / 端点问题拦下。
+ *  源码扫描是启发式:judge 调用藏在 import 的 helper 里时会漏判,漏判只是退回旧行为
+ *  (评分时才报 judge 错误,损失 fail fast),不影响正确性。 */
+export function judgeProbeTargets(
+  evals: Array<{ source: string; judge: JudgeConfig | undefined }>,
+  configJudge: JudgeConfig | undefined,
+): JudgeConfig[] {
+  const seen = new Set<string>();
+  const toProbe: JudgeConfig[] = [];
+  for (const e of evals) {
+    const jc = e.judge ?? configJudge;
+    if (!jc || !/\bjudge\b/.test(e.source)) continue;
+    const key = `${jc.model ?? ""}|${jc.baseUrl ?? ""}|${jc.apiKeyEnv ?? ""}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    toProbe.push(jc);
+  }
+  return toProbe;
+}
+
 export async function runEvals(opts: RunOptions): Promise<RunSummary> {
   const startedAt = new Date().toISOString();
   const t0 = Date.now();
 
-  // 预检 judge:有显式配置时在第一步验证 API key + 端点可达,避免跑完 agent 才发现 judge 不通。
-  {
-    const seen = new Set<string>();
-    const toProbe: JudgeConfig[] = [];
-    for (const jc of [opts.config.judge, ...opts.evals.map((e) => e.judge)]) {
-      if (!jc) continue;
-      const key = `${jc.model ?? ""}|${jc.baseUrl ?? ""}|${jc.apiKeyEnv ?? ""}`;
-      if (seen.has(key)) continue;
-      seen.add(key);
-      toProbe.push(jc);
-    }
-    if (toProbe.length > 0) {
-      process.stderr.write(t("runner.judgePrecheck"));
-      for (const jc of toProbe) {
-        const err = await probeJudge(jc, opts.signal);
-        if (err) throw new Error(err);
-      }
+  // 按 sourcePath 缓存文件内容,fingerprint 与 judge 预检共用:
+  // 矩阵大时(实验 × eval)规划阶段不做串行重复文件读。
+  const sourceCache = new Map<string, Promise<string>>();
+  const readSource = (path: string): Promise<string> => {
+    let p = sourceCache.get(path);
+    if (!p) {
+      p = readFile(path, "utf-8");
+      sourceCache.set(path, p);
     }
-  }
+    return p;
+  };
 
   const plannedFingerprints = new Map<string, string>();
   {
-    // 并行 + 按 sourcePath 缓存:矩阵大时(实验 × eval)规划阶段不做串行重复文件读。
-    const sourceCache = new Map<string, Promise<string>>();
     const jobs: Promise<void>[] = [];
     for (const run of opts.agentRuns) {
       for (const evalDef of opts.evals.filter((e) => run.evalFilter(e.id))) {
@@ -88,7 +102,11 @@ export async function runEvals(opts: RunOptions): Promise<RunSummary> {
     for (let i = 0; i < run.runs; i++) {
       for (const evalDef of evals) {
         if (run.experimentId && priorRunKeys.has(`${run.experimentId}|${evalDef.id}`)) continue;
-        const key = `${run.agent.name}|${run.model ?? ""}|${evalDef.id}`;
+        // key 标识「同一个运行配置下的同一条 eval」,earlyExit 的跳过/abort 只应作用于
+        // 同 key 的重试轮。experimentId 必须进 key:两个实验可以同 agent 同 model、只差
+        // flags(feature A/B 正是这种形状),漏掉它会让先过的实验把其它实验的同名 eval
+        // 整个跳掉——花了钱还丢结果。
+        const key = `${run.experimentId ?? ""}|${run.agent.name}|${run.model ?? ""}|${evalDef.id}`;
         attempts.push({
           evalDef,
           run,
@@ -100,9 +118,39 @@ export async function runEvals(opts: RunOptions): Promise<RunSummary> {
     }
   }
 
+  // 预检 judge:验证 API key + 端点可达,避免跑完 agent 才发现 judge 不通。
+  // 放在 attempts 展开之后,fail fast 只对会真正触发 judge 的运行生效
+  // (目标收集逻辑见 judgeProbeTargets;全部结果携入、attempts 为空时也自然跳过)。
+  {
+    const uniqueEvals = [...new Map(attempts.map((a) => [a.evalDef.id, a.evalDef])).values()];
+    const sources = await Promise.all(uniqueEvals.map((e) => readSource(e.sourcePath)));
+    const toProbe = judgeProbeTargets(
+      uniqueEvals.map((e, i) => ({ source: sources[i] ?? "", judge: e.judge })),
+      opts.config.judge,
+    );
+    if (toProbe.length > 0) {
+      process.stderr.write(t("runner.judgePrecheck"));
+      for (const jc of toProbe) {
+        const err = await probeJudge(jc, opts.signal);
+        if (err) throw new Error(err);
+      }
+    }
+  }
+
   if (carriedResults.length > 0) {
     const retryCount = new Set(attempts.map((a) => `${a.run.experimentId ?? ""}|${a.evalDef.id}`)).size;
     process.stderr.write(t("runner.resumeCarry", { carried: carriedResults.length, retry: retryCount }));
+    // 按 experiment 分组列出被复用(跳过)的 eval:不列清单的话,用户只看到数量,
+    // 无法核对「跳过的是不是我以为已经过了的那些」。同一 key 多个 run 去重。
+    const carriedByExperiment = new Map<string, Set<string>>();
+    for (const r of carriedResults) {
+      const ids = carriedByExperiment.get(r.experimentId!) ?? new Set<string>();
+      ids.add(r.id);
+      carriedByExperiment.set(r.experimentId!, ids);
+    }
+    for (const [experiment, ids] of [...carriedByExperiment].sort(([a], [b]) => a.localeCompare(b))) {
+      process.stderr.write(t("runner.resumeCarryDetail", { experiment, evals: [...ids].sort().join(", ") }));
+    }
   }
 
   // onRunStart 报「本次实际要跑的 eval」(过滤 + 去重),不是发现到的全部 —— 否则计数误导。
@@ -115,11 +163,37 @@ export async function runEvals(opts: RunOptions): Promise<RunSummary> {
     totalRuns: attempts.length,
     maxConcurrency: opts.maxConcurrency,
   };
-  for (const r of opts.reporters) {
+  // eval 级 reporters:实例只观测引用它的 eval(经 scopeReporter 过滤转发)。
+  // 已经挂在全局 reporters 里的同一实例不重复挂;同一实例被多个 eval 引用时合并观测集
+  // (共享一个目的地,如同一个 Braintrust 实验)。本次没有任何被观测 eval 要跑时整个跳过。
+  const scopedSets = new Map<Reporter, Set<string>>();
+  for (const e of opts.evals) {
+    for (const r of e.reporters ?? []) {
+      if (opts.reporters.includes(r)) continue;
+      let ids = scopedSets.get(r);
+      if (!ids) scopedSets.set(r, (ids = new Set()));
+      ids.add(e.id);
+    }
+  }
+  const reporters: Reporter[] = [...opts.reporters];
+  for (const [r, ids] of scopedSets) {
+    const scopedRuns = attempts.filter((a) => ids.has(a.evalDef.id)).length;
+    if (scopedRuns === 0) continue;
+    reporters.push(
+      scopeReporter(r, ids, {
+        evals: [...ids].filter((id) => runningIds.has(id)).length,
+        configs: opts.agentRuns.length,
+        totalRuns: scopedRuns,
+        maxConcurrency: opts.maxConcurrency,
+      }),
+    );
+  }
+
+  for (const r of reporters) {
     // reporter 只是结果消费方:单个 reporter 抛错记 diagnostic,不能让整次调度崩(P2)。
     await runReporter("onRunStart", () => r.onRunStart?.(runningEvals, firstAgent as Agent, shape));
   }
-  await emitReporterEvent(opts.reporters, {
+  await emitReporterEvent(reporters, {
     type: "run:start",
     evals: runningEvals,
     agent: firstAgent as Agent,
@@ -165,6 +239,18 @@ export async function runEvals(opts: RunOptions): Promise<RunSummary> {
   // 未显式指定时跟 maxConcurrency 走——各 backend 的推荐值已在 cli 层写进 maxConcurrency 默认值。
   const sandboxSem = Effect.runSync(Effect.makeSemaphore(opts.maxConcurrency));
 
+  // 两级并发闸:全局(opts.maxConcurrency)+ 实验级(AgentRun.maxConcurrency,可选)。
+  // 实验级信号量让「有共享状态、必须串行」的实验(如跨 eval 累积记忆,maxConcurrency: 1)
+  // 只在自己内部排队,同批其它实验照常并发——旧行为是 CLI 取所有选中实验的最小值钳全局,
+  // 一个串行实验会把整批基线拖成串行。等于全局上限的实验级值不建闸(与全局闸重复)。
+  const globalSem = Effect.runSync(Effect.makeSemaphore(opts.maxConcurrency));
+  const runSems = new Map<AgentRun, Effect.Semaphore>();
+  for (const run of opts.agentRuns) {
+    if (run.maxConcurrency !== undefined && run.maxConcurrency < opts.maxConcurrency) {
+      runSems.set(run, Effect.runSync(Effect.makeSemaphore(Math.max(1, run.maxConcurrency))));
+    }
+  }
+
   // 非沙箱 tracing agent 的共享 OTLP 接收池:被测应用是长驻进程,端点不能随
   // attempt 换 —— receiver 粒度跟被测进程走(每 agent 一个,整个 run 复用),run 结束回收。
   if (!opts.otelPool) {
@@ -180,8 +266,11 @@ export async function runEvals(opts: RunOptions): Promise<RunSummary> {
     }
   }
 
-  // 有界并发调度:Effect.forEach({ concurrency }) 取代手写 queue / inFlight / Promise.race。
-  // 每个 attempt 跑在自己的 fiber;runAttemptEffect 只把「执行错误」收进 EvalResult.error(不 fail),
+  // 有界并发调度:forEach 本身 unbounded(每个 attempt 立刻有自己的 fiber),真正的
+  // 并发上限由上面两级信号量把守——执行体先过实验级闸(若有)再占全局 permit 才开跑。
+  // 获取定序恒为 runSem → globalSem,无环等待;实验级闸的持有者在等全局 permit 时
+  // 不占别的实验的并发位(并发位就是 globalSem 的 permit,不再是 forEach 的 fiber 槽)。
+  // runAttemptEffect 只把「执行错误」收进 EvalResult.error(不 fail),
   // 但中断(Ctrl+C / kill)照常向上传播 —— 所以一条挂掉不会中断其它 attempt,而中断能停掉全部。
   //
   // signal:把 opts.signal 喂给 run → abort 触发根 fiber 中断 → forEach 中断所有子 fiber
@@ -196,14 +285,15 @@ export async function runEvals(opts: RunOptions): Promise<RunSummary> {
   const exit = await Effect.runPromiseExit(
     Effect.forEach(
       attempts,
-      (a) =>
-        Effect.gen(function* () {
+      (a) => {
+        const body = Effect.gen(function* () {
             // 早停:同 key 已通过,或已 errored(重跑只会重复同一个框架错误)且开了 earlyExit
-            // → 跳过未启动的 attempt。
+            // → 跳过未启动的 attempt。检查必须在拿到 permit 之后(fiber 是 unbounded 一次性
+            // 全建的,建时结果还没出来);跳过路径短暂占一个 permit,可忽略。
             if (a.run.earlyExit && (passedKeys.has(a.key) || erroredKeys.has(a.key))) {
               yield* reportMutex.withPermits(1)(
                 Effect.promise(() =>
-                  emitReporterEvent(opts.reporters, {
+                  emitReporterEvent(reporters, {
                     type: "run:earlyExit",
                     evalId: a.evalDef.id,
                     experimentId: a.run.experimentId,
@@ -226,7 +316,7 @@ export async function runEvals(opts: RunOptions): Promise<RunSummary> {
                     budgetReported.add(budgetKey);
                     yield* reportMutex.withPermits(1)(
                       Effect.promise(() =>
-                        emitReporterEvent(opts.reporters, { type: "run:budgetExceeded", budget, spent: s.spent }),
+                        emitReporterEvent(reporters, { type: "run:budgetExceeded", budget, spent: s.spent }),
                       ),
                     );
                   }
@@ -261,7 +351,7 @@ export async function runEvals(opts: RunOptions): Promise<RunSummary> {
 
             yield* reportMutex.withPermits(1)(
               Effect.promise(() =>
-                emitReporterEvent(opts.reporters, {
+                emitReporterEvent(reporters, {
                   type: "eval:start",
                   eval: { id: a.evalDef.id },
                   agent: a.run.agent,
@@ -310,7 +400,7 @@ export async function runEvals(opts: RunOptions): Promise<RunSummary> {
               // 停掉后续 attempt(P2)。
               Effect.promise(() =>
                 Promise.all(
-                  opts.reporters.map((r) =>
+                  reporters.map((r) =>
                     runReporter("onEvalComplete", () => r.onEvalComplete?.(result)),
                   ),
                 ),
@@ -320,10 +410,14 @@ export async function runEvals(opts: RunOptions): Promise<RunSummary> {
             // attempt 各自触发的 eval:complete 会绕开 permit=1 直接并发跑,和文档承诺的
             // 「报告回调串行化」不一致。
             yield* reportMutex.withPermits(1)(
-              Effect.promise(() => emitReporterEvent(opts.reporters, { type: "eval:complete", result })),
+              Effect.promise(() => emitReporterEvent(reporters, { type: "eval:complete", result })),
             );
-          }),
-      { concurrency: opts.maxConcurrency, discard: true },
+          });
+        const gated = globalSem.withPermits(1)(body);
+        const runSem = runSems.get(a.run);
+        return runSem ? runSem.withPermits(1)(gated) : gated;
+      },
+      { concurrency: "unbounded", discard: true },
     ).pipe(
       // 中断(用户 Ctrl+C):finalizer 已在中断过程中跑完(容器已停),这里只是把它咽下,
       // 好让流程走到 summarize / onRunComplete,用已完成的 results 出一份部分汇总,而不是抛栈。
@@ -359,10 +453,10 @@ export async function runEvals(opts: RunOptions): Promise<RunSummary> {
   );
 
   const summary = summarize(allResults, firstAgent?.name ?? "", startedAt, Date.now() - t0, opts.config.name);
-  await emitReporterEvent(opts.reporters, { type: "run:summary", summary });
-  for (const r of opts.reporters) {
+  await emitReporterEvent(reporters, { type: "run:summary", summary });
+  for (const r of reporters) {
     await runReporter("onRunComplete", () => r.onRunComplete?.(summary));
   }
-  await emitReporterEvent(opts.reporters, { type: "run:saved", summary });
+  await emitReporterEvent(reporters, { type: "run:saved", summary });
   return summary;
 }

package/src/runner/types.ts

@@ -97,7 +97,8 @@ export interface RunShape {
   configs: number;
   /** 总 attempt 数(evals × configs × runs);逐行输出与汇总计数都按它。 */
   totalRuns: number;
-  /** 本次运行实际生效的并发数(flag/env/experiment/config/sandbox 默认值解析后的结果)。 */
+  /** 本次运行实际生效的全局并发数(flag/env/config/sandbox 默认值解析后的结果);
+   *  实验级 maxConcurrency 只在该实验内部限流,不改这个全局值。 */
   maxConcurrency: number;
 }
 
@@ -122,12 +123,17 @@ export type ReporterEvent =
 export interface EvalDef {
   /** 路径推导,定义里禁止手写。 */
   id?: string;
+  /** 一句话描述,展示在 `niceeval list` 和 view 里;纯说明,不影响调度或打分。 */
   description?: string;
-  agent?: string;
+  /** 标签,供 CLI `--tag` 过滤和 view 分类;与 id 前缀过滤是两套独立的筛选维度。 */
   tags?: string[];
+  /** 覆盖项目级 Config.judge,只对这一个 eval 生效(如换个更贵的评审模型)。 */
   judge?: JudgeConfig;
+  /** 覆盖 / 追加项目级 Config.reporters,只对这一个 eval 生效。 */
   reporters?: Reporter[];
+  /** 覆盖项目级 / CLI 的单次 attempt 超时(毫秒),只对这一个 eval 生效。 */
   timeoutMs?: number;
+  /** 任意附加元数据,原样透传进 EvalResult,不参与调度或打分;供自定义 reporter 消费。 */
   metadata?: Record<string, unknown>;
   /**
    * eval 级预置:拿到沙箱(已上传 workspace + git 基线 + 装好依赖前)。
@@ -135,6 +141,7 @@ export interface EvalDef {
    * (如 `runCommand("apt-get", ["install", …], { root: true })`),跨后端语义一致。
    */
   setup?: (sandbox: Sandbox) => Promise<void | Cleanup> | void | Cleanup;
+  /** eval 主体:拿到 TestContext,驱动对话 / 沙箱操作并就地断言。 */
   test(t: TestContext): Promise<void> | void;
 }
 
@@ -148,20 +155,43 @@ export interface DiscoveredEval extends EvalDef {
 }
 
 export interface ExperimentDef {
+  /** 路径推导,定义里禁止手写(defineExperiment 会拒绝显式传入)。 */
   id?: string;
+  /** 一句话描述,展示在 view / CLI 里;纯说明,不影响调度或打分。 */
   description?: string;
+  /**
+   * 必填:这个实验跑哪个 agent(defineSandboxAgent / defineAgent 的产物)。运行配置的
+   * agent 归属完全由这里决定——EvalDef.agent 不参与(见其字段注释)。
+   */
   agent: Agent;
   /** 单个模型(agent 留空时实验决定);省略=用 agent 原生默认。跨模型对比写多个实验文件,别用数组。 */
   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>;
+  /** 同一 eval 重复跑几次(结果各计一条 attempt);省略/CLI `--runs` 覆盖时默认 1。 */
   runs?: number;
+  /** 一次重复(runs > 1)里某次 attempt 失败后是否跳过剩余重复;省略默认 true(提前退出省钱)。 */
   earlyExit?: boolean;
+  /** 这个实验覆盖哪些 eval:"*" 全部、字符串数组按 id 前缀、或自定义谓词;省略等价于 "*"。 */
   evals?: "*" | string[] | ((id: string) => boolean);
+  /** 覆盖项目级 / CLI 的单次 attempt 超时(毫秒),只对这个实验生效。 */
   timeoutMs?: number;
+  /** 覆盖项目级 Config.sandbox,只对这个实验生效。 */
   sandbox?: SandboxOption;
+  /**
+   * 本实验的花费上限(USD)。调度器按「已花 + 在飞预估」的护栏口径逼近上限时限流,
+   * 累计花费到顶后跳过这个实验剩下未起飞的 attempt 并上报一次 `run:budgetExceeded`
+   * (已在飞的 attempt 仍会跑完)。
+   */
   budget?: number;
+  /**
+   * 本实验自己的并发上限:调度器只对这个实验的 attempt 限流,同批其它实验不受影响,
+   * 仍按全局并发(CLI / env / config / 沙箱默认)跑。用于串行化有共享状态的实验
+   * (如跨 eval 累积记忆:`maxConcurrency: 1` 保证 attempt 按 eval 顺序一个个跑),
+   * 或给撞后端限额的实验单独降速。
+   */
   maxConcurrency?: number;
 }
 
@@ -176,11 +206,17 @@ export interface Config {
    * 可传字符串,或按 locale 提供多语言(如 `{ en: "...", "zh-CN": "..." }`),随 view 语言切换。
    */
   name?: LocalizedText;
+  /** 项目级默认沙箱后端(docker / vercel / e2b / custom);experiment / CLI flag 可覆盖。 */
   sandbox?: SandboxOption;
+  /** 上传进沙箱的工作区根目录,省略则用项目根;eval 的 sandbox 视图从这里起步。 */
   workspace?: string;
+  /** 项目级默认 judge 配置(model / baseUrl / apiKeyEnv);EvalDef.judge 可按 eval 覆盖。 */
   judge?: JudgeConfig;
+  /** 项目级默认 reporter 列表(如落盘 / 上传结果);EvalDef.reporters 会与它合并。 */
   reporters?: Reporter[];
+  /** 项目级默认并发上限;CLI flag / env / experiment 的同名设置优先级更高。 */
   maxConcurrency?: number;
+  /** 项目级默认单次 attempt 超时(毫秒);CLI flag / experiment / EvalDef 的同名设置优先级更高。 */
   timeoutMs?: number;
   /**
    * OTLP 接收配置,niceeval 项目内唯一入口(不读 NICEEVAL_OTLP_* 环境变量)。
@@ -203,14 +239,28 @@ export interface Config {
 
 /** 每百万 token 的美元单价;省略的桶退回 `inputPerMTok`(cache token 本质也是 input)。 */
 export interface PriceOverride {
+  /** 普通输入 token 单价。 */
   inputPerMTok: number;
+  /** 输出 token 单价。 */
   outputPerMTok: number;
+  /** cache 命中(读)token 单价,省略则退回 inputPerMTok。 */
   cacheReadPerMTok?: number;
+  /** cache 写入 token 单价,省略则退回 inputPerMTok。 */
   cacheWritePerMTok?: number;
 }
 
 // ───────────────────────── 调度编排 ─────────────────────────
 
+/**
+ * 进度行 / 日志里标识一个 run 配置的短名。有 experiment 时用其 basename(唯一,
+ * 能区分同 agent 同 model 的实验变体,如 xxx 与 xxx--agents-md;与汇总表口径一致);
+ * 无 experiment 时退回 agent/model。live display 以它作行聚合 key,两处必须同源。
+ */
+export function runWho(run: Pick<AgentRun, "agent" | "model" | "experimentId">): string {
+  if (run.experimentId) return run.experimentId.split("/").pop()!;
+  return run.model ? `${run.agent.name}/${run.model}` : run.agent.name;
+}
+
 /** 一个 (agent, model, flags) 的运行配置 —— 由 CLI / 实验展开。 */
 export interface AgentRun {
   agent: Agent;
@@ -225,6 +275,9 @@ export interface AgentRun {
   evalFilter: (id: string) => boolean;
   experimentId?: string;
   strict?: boolean;
+  /** 本配置自己的并发上限(来自 ExperimentDef.maxConcurrency):调度器为它单建信号量,
+   *  attempt 先过这道闸再占全局并发位;省略则只受全局并发约束。 */
+  maxConcurrency?: number;
 }
 
 export interface RunOptions {

package/src/sandbox/types.ts

@@ -93,7 +93,9 @@ export type SandboxSpec = DockerSandboxSpec | VercelSandboxSpec | E2BSandboxSpec
 export type SandboxOption = SandboxSpec;
 
 export interface CommandOptions {
+  /** 追加/覆盖本命令的环境变量(与沙箱默认环境叠加,不清空默认值;各后端会保留自己固定的 `PATH` 等变量,不保证能被这里覆盖)。 */
   env?: Record<string, string>;
+  /** 本命令的工作目录;省略时落到 `Sandbox.workdir`。相对路径按 workdir 解析,绝对路径原样使用。 */
   cwd?: string;
   /**
    * 把本命令的输出也送进沙箱的「原生日志流」(于是 `docker logs` / Docker UI 的 Logs
@@ -115,20 +117,36 @@ export interface CommandOptions {
 }
 
 export interface Sandbox {
+  /** 沙箱内项目/工作区根目录的绝对路径(agent 命令的默认 cwd,也是 git baseline 提交的位置)。各方法的相对路径都以此为基准解析,省略 `cwd`/`targetDir` 时也落到这里。 */
   readonly workdir: string;
+  /**
+   * 执行单个命令,`args` 作为独立 argv 传递、不经 shell 解释(无 `&&`、管道、通配符展开)。
+   * 只想跑一个可执行文件、参数来自外部输入、担心注入时优先用它。
+   */
   runCommand(cmd: string, args?: string[], opts?: CommandOptions): Promise<CommandResult>;
+  /**
+   * 执行一整段脚本,经 shell(bash)解释,支持 `&&`、管道、`$()`、重定向等。
+   * 需要拼多条命令或做条件判断时用它。
+   */
   runShell(script: string, opts?: CommandOptions): Promise<CommandResult>;
+  /** 读取沙箱内文件的文本内容(UTF-8)。文件不存在时抛错,不返回空字符串——需要容错请自行 `.catch()`。 */
   readFile(path: string): Promise<string>;
+  /** 检查沙箱内路径是否存在。跨后端语义不完全一致:仅保证对普通文件可靠,对目录路径的行为不同后端不保证一致。 */
   fileExists(path: string): Promise<boolean>;
   /**
    * 一次 shell 往返读全部源码文件(按扩展名收、按目录/文件名忽略)。
    * 取代每个 eval 目录里手写的 find + 逐文件 readFile。
    */
   readSourceFiles(opts?: ReadSourceFilesOptions): Promise<SourceFiles>;
+  /** 写入若干文本文件(内容已在内存里的字符串);是 `uploadFiles` 的文本特化,省略 `targetDir` 落到 workdir。 */
   writeFiles(files: Record<string, string>, targetDir?: string): Promise<void>;
+  /** 批量写入若干文件,内容可以是文本或二进制 Buffer;省略 `targetDir` 落到 workdir。 */
   uploadFiles(files: SandboxFile[], targetDir?: string): Promise<void>;
+  /** 把本地磁盘上的一个目录整体上传进沙箱(递归读取本地文件后按 `uploadFiles` 写入);`opts.ignore` 是排除规则,省略 `targetDir` 落到 workdir。 */
   uploadDirectory(localDir: string, targetDir?: string, opts?: { ignore?: string[] }): Promise<void>;
+  /** 销毁沙箱占用的计算资源(容器/microVM)。调用后沙箱不可再用;是否可安全重复调用因后端而异,不要依赖这一点。 */
   stop(): Promise<void>;
+  /** 本沙箱的稳定标识(各后端原生 ID,如 Docker 容器 ID 前缀);用于跨调用关联同一沙箱的会话状态,也用于日志展示。 */
   readonly sandboxId: string;
   /**
    * 本地 OTLP 接收器的目标 host。

package/src/scoring/types.ts

@@ -9,7 +9,12 @@ export interface ValueAssertion {
   readonly severity: Severity;
   readonly threshold?: number;
   score(value: unknown): number | Promise<number>;
+  /** 转成硬门槛断言:未达阈值(省略 threshold 则按 score > 0 判定)整条 eval 判为 failed。返回新实例,不改原对象。 */
   gate(threshold?: number): ValueAssertion;
+  /**
+   * 转成软阈值断言:未达 threshold 时该条记为 failed,但默认不拖累整条 eval 的 outcome;
+   * `--strict` 运行下,软阈值失败也会把整条 eval 的 outcome 计为 failed。返回新实例,不改原对象。
+   */
   atLeast(threshold: number): ValueAssertion;
 }
 

package/src/shared/types.ts

@@ -2,6 +2,7 @@
 // 各域的类型住在各自目录的 types.ts(o11y / sandbox / agents / scoring / context / runner),
 // src/types.ts 是聚合 facade —— 模块代码统一从那里 import,不必记住每个类型的家。
 
+/** JSON 可表达的任意值(递归定义),用于事件流 / 工具输入输出等跨进程/跨语言传递的数据。 */
 export type JsonValue =
   | string
   | number
@@ -10,6 +11,7 @@ export type JsonValue =
   | JsonValue[]
   | { [key: string]: JsonValue };
 
+/** 断言的严重级:"gate" 失败必判整轮 failed;"soft" 默认只记录不拦截,仅在 `--strict` 模式或显式设阈值未达标时才计入失败。 */
 export type Severity = "gate" | "soft";
 
 /**
@@ -28,6 +30,7 @@ export interface SourceArtifact {
   content: string;
 }
 
+/** 通用清理闭包(setup 返回值 / teardown 的形状),异步同步皆可,统一在 finally 里执行。 */
 export type Cleanup = () => Promise<void> | void;
 
 /**

package/src/util.test.ts

@@ -1,5 +1,30 @@
 import { describe, expect, it } from "vitest";
-import { formatThrown } from "./util.ts";
+import { formatThrown, upsertManagedBlock } from "./util.ts";
+
+describe("upsertManagedBlock", () => {
+  const begin = "<!-- BEGIN:x -->";
+  const end = "<!-- END:x -->";
+
+  it("appends the block to existing content, separated by a blank line", () => {
+    const out = upsertManagedBlock("# My project\n", begin, end, "rules");
+    expect(out).toBe(`# My project\n\n${begin}\nrules\n${end}\n`);
+  });
+
+  it("creates just the block when the file is empty", () => {
+    expect(upsertManagedBlock("", begin, end, "rules")).toBe(`${begin}\nrules\n${end}\n`);
+  });
+
+  it("replaces only the content between existing markers, preserving what surrounds them", () => {
+    const before = `above\n\n${begin}\nold rules\n${end}\n\nbelow\n`;
+    const out = upsertManagedBlock(before, begin, end, "new rules");
+    expect(out).toBe(`above\n\n${begin}\nnew rules\n${end}\n\nbelow\n`);
+  });
+
+  it("is idempotent for the same content", () => {
+    const once = upsertManagedBlock("# hi\n", begin, end, "rules");
+    expect(upsertManagedBlock(once, begin, end, "rules")).toBe(once);
+  });
+});
 
 describe("formatThrown", () => {
   it("uses the stack trace when available, so the report can locate the throw site", () => {

package/src/util.ts

@@ -37,6 +37,22 @@ export function pad4(n: number): string {
   return String(n).padStart(4, "0");
 }
 
+/**
+ * 在文本里维护一个带 BEGIN/END 标记的托管区块(AGENTS.md 的 niceeval 区块用)。
+ * 标记已存在 → 只替换两个标记之间的内容(升级时刷新指引,区块外的用户内容不动);
+ * 不存在 → 追加到末尾(与已有内容之间空一行)。
+ */
+export function upsertManagedBlock(source: string, begin: string, end: string, content: string): string {
+  const block = `${begin}\n${content}\n${end}`;
+  const beginIdx = source.indexOf(begin);
+  const endIdx = source.indexOf(end);
+  if (beginIdx !== -1 && endIdx !== -1 && endIdx > beginIdx) {
+    return source.slice(0, beginIdx) + block + source.slice(endIdx + end.length);
+  }
+  if (source.trim() === "") return `${block}\n`;
+  return `${source.replace(/\n*$/, "")}\n\n${block}\n`;
+}
+
 /** 把任意值安全地转成简短字符串(报告 / 日志用)。 */
 export function brief(value: unknown, max = 200): string {
   let s: string;

package/src/view/app/App.tsx

@@ -9,7 +9,7 @@ import { Metric } from "./components/primitives.tsx";
 import { GroupSelector } from "./components/GroupSelector.tsx";
 import { CostScoreChart } from "./components/CostScoreChart.tsx";
 import { ExperimentTable } from "./components/ExperimentTable.tsx";
-import { CopyAllErrors } from "./components/CopyControls.tsx";
+import { CopyFixPrompt } from "./components/CopyControls.tsx";
 import { AttemptModal } from "./components/AttemptModal.tsx";
 import { Tabs, TabsContent, TabsList, TabsTrigger } from "./components/ui/tabs.tsx";
 import { RunsView } from "./pages/RunsPage.tsx";
@@ -239,7 +239,7 @@ export function App({ data }: { data: ViewData }) {
                 value={query}
                 onChange={(e) => setQuery(e.target.value)}
               />
-              <CopyAllErrors rows={filtered} t={t} />
+              <CopyFixPrompt rows={filtered} t={t} />
             </div>
           </div>
           {rows.length ? (

package/src/view/app/components/AttemptModal.tsx

@@ -5,6 +5,7 @@ import { artifactUrl } from "../lib/artifact-url.ts";
 import { asEvents, asSources } from "../lib/guards.ts";
 import { outcomeClass, outcomeLabel } from "../lib/outcome.ts";
 import { CodeView, NoSourceBody } from "./CodeView.tsx";
+import { CopyAttemptPrompt } from "./CopyControls.tsx";
 import { LazyArtifact } from "./LazyArtifact.tsx";
 import { Dialog, DialogClose, DialogContent, DialogTitle } from "./ui/dialog.tsx";
 import { Badge } from "./ui/badge.tsx";
@@ -44,6 +45,7 @@ export function AttemptModal({ result, onClose, t }: { result: ViewResult; onClo
             </DialogTitle>
             {result.description ? <span className="truncate text-xs text-muted">{result.description}</span> : null}
           </div>
+          <CopyAttemptPrompt result={result} t={t} />
           <DialogClose
             aria-label={t("action.close")}
             className="grid h-7 w-7 shrink-0 place-items-center rounded-md border border-transparent text-sm text-muted transition-colors hover:border-line hover:bg-panel-2 hover:text-text"