niceeval 0.4.3 → 0.4.5

package/src/agents/types.ts

@@ -143,10 +143,23 @@ export interface AgentSession {
 }
 
 export interface AgentContext {
+  /**
+   * 软取消信号:合并了 attempt 超时、run 级中断(用户 Ctrl+C)与 eval 自身的中断请求
+   * (见 src/runner/attempt.ts)。adapter 可以选择性检查它(或直接传给 `fetch`)以提前
+   * 优雅退出,但这不是唯一的硬边界——即便 adapter 完全忽略它,运行器也会用
+   * `Effect.timeoutTo` 兜底强制收尾(停沙箱容器)。
+   */
   readonly signal: AbortSignal;
+  /** 本次 attempt 用的模型名,透传自 experiment 的 `model` 字段。sandbox 型 agent 通常在 setup 里用它写配置,remote 型通常在 send 里用它选模型。 */
   readonly model?: string;
   /** 模型推理努力程度;归属同 model——实验决定,省略时不覆盖 agent 原生默认。 */
   readonly reasoningEffort?: string;
+  /**
+   * experiment 的 `flags` 字段原样透传,内容和结构完全由 experiment 作者自定义
+   * (如 `{ webResearch: true }`、`{ systemPrompt: "..." }`)。adapter 按自己的约定
+   * 读取其中的字段;框架本身不解释、不校验它的内容。与 CLI 解析出的同名 `flags`
+   * (跑法层面的 --timeout/--budget 等)是两个不相关的概念。
+   */
   readonly flags: Readonly<Record<string, unknown>>;
   /** 仅沙箱型 agent 有(运行器按 --sandbox 备好)。 */
   readonly sandbox: Sandbox;
@@ -160,6 +173,12 @@ export interface AgentContext {
    * (defineConfig({ telemetry: { port } }))固定的,不从这里传。
    */
   readonly telemetry?: Telemetry;
+  /**
+   * 写一行进运行器自身的进度日志(落 stderr,或调用方传入的 `onProgress` 回调)。
+   * 超时失败时,最近若干行会并入结果的 error 信息,方便定位卡在哪一步。
+   * 与 `Sandbox.appendLog` 是两回事:那个是把一行写进容器自己的原生日志
+   * (`docker logs` 能看到),这里只是运行器的观测通道。
+   */
   log(msg: string): void;
 }
 
@@ -198,23 +217,43 @@ export interface Agent {
   teardown?: AgentTeardown;
 }
 
+/** `defineSandboxAgent()` 的入参形状(见 src/define.ts)——`kind: "sandbox"` 由 define 固定填入,不由用户声明。 */
 export interface SandboxAgentDef {
+  /** agent 的显示名/标识,原样进入 `Agent.name`——不是注册表查找 key,只用于展示、结果归属与去重指纹。 */
   name: string;
-  /** 每个沙箱一次:装 CLI、写 config.toml / 鉴权配置。 */
+  /**
+   * 每个沙箱一次(不是每轮一次):装 CLI、写 config.toml / 鉴权配置(model/base/auth 等
+   * 本轮内不变的东西)。运行器在沙箱备好(上传/基线/eval.setup 之后)、第一次 send 前
+   * 调用一次。可返回一个 cleanup 闭包,与 `teardown` 一起在 finally 里跑。
+   */
   setup?: AgentSetup;
   /** OTLP 导出配置:沙箱里怎么让 CLI 把 trace 发到 endpoint(env / 配置文件),从 setup 拆出。 */
   tracing?: AgentTracing;
+  /** 原生 span → canonical 的薄 mapper;省略走通用 heuristic。只影响瀑布图。 */
   spanMapper?: SpanMapper;
   /** 每轮一次:跑 prompt(fresh / resume)+ 解析成 events。 */
   send(input: TurnInput, ctx: AgentContext): Promise<Turn>;
+  /** 沙箱销毁前的清理(与 setup 返回的 cleanup 一起、都在 finally 里跑一次)。 */
   teardown?: AgentTeardown;
 }
 
+/** `defineAgent()` 的入参形状(见 src/define.ts)——`kind: "remote"` 由 define 固定填入,不由用户声明。 */
 export interface RemoteAgentDef {
+  /** agent 的显示名/标识,原样进入 `Agent.name`——不是注册表查找 key,只用于展示、结果归属与去重指纹。 */
   name: string;
+  /**
+   * 每个 attempt 一次(remote agent 没有真实沙箱,运行器会传入一个仅含 `workdir`/`sandboxId`/
+   * `otlpHost`/`stop` 等元信息的 stub `Sandbox`,其余方法调用即抛错——不要在这里调用
+   * 文件/命令类沙箱方法)。常用于建立连接、鉴权等一次性准备。可返回一个 cleanup 闭包,
+   * 与 `teardown` 都在 finally 里跑。
+   */
   setup?: AgentSetup;
+  /** OTLP 导出配置:远程被测对象怎么把 trace 发到 endpoint(env-based 注入 / file-based 配置)。 */
   tracing?: AgentTracing;
+  /** 原生 span → canonical 的薄 mapper;省略走通用 heuristic。只影响瀑布图。 */
   spanMapper?: SpanMapper;
+  /** 每轮一次:把一轮 prompt 发给远程被测对象(HTTP/SDK 等),解析响应成 events。 */
   send(input: TurnInput, ctx: AgentContext): Promise<Turn>;
+  /** 运行结束前的清理(与 setup 返回的 cleanup 一起、都在 finally 里跑一次)。 */
   teardown?: AgentTeardown;
 }

package/src/agents/ui-message-stream.ts

@@ -216,6 +216,7 @@ export interface UiMessageStreamAgentOptions {
   settleMs?: number;
   /** 应用有 OTel 时的端点投递方式(拿瀑布图);事件流不依赖它。 */
   tracing?: AgentTracing;
+  /** 应用有 OTel 时的 span 归一函数(拿瀑布图);事件流不依赖它。 */
   spanMapper?: SpanMapper;
 }
 

package/src/cli.ts

@@ -11,7 +11,9 @@ import { pathToFileURL } from "node:url";
 import { parseArgs as nodeParseArgs } from "node:util";
 import { discoverEvals, discoverExperiments, makeFilter } from "./runner/discover.ts";
 import { runEvals, type AgentRun } from "./runner/run.ts";
+import { runWho } from "./runner/types.ts";
 import { stopAllSandboxes, liveSandboxCount } from "./sandbox/registry.ts";
+import { evalLevelStats } from "./shared/outcome.ts";
 import { sandboxRecommendedConcurrency } from "./sandbox/resolve.ts";
 import { Console as ConsoleReporter } from "./runner/reporters/console.ts";
 import { JUnit } from "./runner/reporters/json.ts";
@@ -19,7 +21,7 @@ import { Live as LiveReporter, type LiveRow } from "./runner/reporters/live.ts";
 import { Artifacts as ArtifactsReporter } from "./runner/reporters/artifacts.ts";
 import { buildView, startViewServer, loadLatestResultsPerEval, IncompatibleResultsError } from "./view/index.ts";
 import { t } from "./i18n/index.ts";
-import { formatThrown } from "./util.ts";
+import { formatThrown, upsertManagedBlock } from "./util.ts";
 import type { Config, DiscoveredExperiment, Reporter } from "./types.ts";
 
 /** `niceeval view <summary.json>` 指向版本不同的报告时:打印 npx 提示后退出,不抛堆栈。 */
@@ -182,6 +184,19 @@ async function loadConfig(cwd: string): Promise<Config> {
   return mod.default;
 }
 
+// AGENTS.md 托管区块:告诉在这个项目里干活的 coding agent「niceeval 不在你的训练数据里,
+// 先读随包文档,跑完读结构化结果」。init 时写入/刷新;标记之外的用户内容永不触碰。
+const AGENT_RULES_BEGIN = "<!-- BEGIN:niceeval-agent-rules -->";
+const AGENT_RULES_END = "<!-- END:niceeval-agent-rules -->";
+const AGENT_RULES_CONTENT = [
+  "# niceeval is NOT in your training data",
+  "",
+  "Its APIs and conventions may differ from anything you have seen. Read the relevant",
+  "guide in `node_modules/niceeval/docs-site/` (English at the top level, Chinese under",
+  "`zh/`) before writing any eval, experiment, adapter, or niceeval config. After a run,",
+  "read the `summary.json` path the CLI prints for structured results.",
+].join("\n");
+
 async function initProject(cwd: string): Promise<void> {
   await mkdir(join(cwd, "evals"), { recursive: true });
   const configPath = join(cwd, "niceeval.config.ts");
@@ -199,6 +214,10 @@ async function initProject(cwd: string): Promise<void> {
       "utf-8",
     );
   }
+  const agentsPath = join(cwd, "AGENTS.md");
+  const existing = existsSync(agentsPath) ? await readFile(agentsPath, "utf-8") : "";
+  const next = upsertManagedBlock(existing, AGENT_RULES_BEGIN, AGENT_RULES_END, AGENT_RULES_CONTENT);
+  if (next !== existing) await writeFile(agentsPath, next, "utf-8");
 }
 
 async function openBrowser(url: string): Promise<boolean> {
@@ -289,7 +308,6 @@ async function main(): Promise<void> {
   }
 
   const agentRuns: AgentRun[] = [];
-  let expMaxConcurrency: number | undefined;
 
   if (command === "exp") {
     if (flags.agent || flags.model) {
@@ -324,10 +342,11 @@ async function main(): Promise<void> {
         evalFilter: evalsFilterFromExperiment(exp.evals, extraPatterns),
         experimentId: exp.id,
         strict: flags.strict,
+        // 实验级并发上限:随 AgentRun 进调度器按实验单独限流(runner 两级信号量),
+        // 不再取所有选中实验的最小值钳全局——那会让一个串行实验拖慢整批基线。
+        maxConcurrency: exp.maxConcurrency,
       });
     }
-    const vals = selected.map((e) => e.maxConcurrency).filter((v): v is number => v !== undefined);
-    if (vals.length > 0) expMaxConcurrency = Math.min(...vals);
   } else {
     // 裸 run / `niceeval <eval>` 不再执行。运行配置必须来自 experiments/,
     // 这样 agent/model/flags/runs/budget 与结果聚合都有可签入的身份。
@@ -372,9 +391,9 @@ async function main(): Promise<void> {
       // TTY 模式:用 live display 替换 Console reporter,把 attempt log 路由到状态表行尾
       const liveRows: LiveRow[] = [];
       for (const agentRun of agentRuns) {
-        const who = agentRun.model
-          ? `${agentRun.agent.name}/${agentRun.model}`
-          : agentRun.agent.name;
+        // who 必须与 attempt.ts 的进度上报同源(runWho):曾用 agent/model,同 agent 同 model
+        // 的实验变体(xxx 与 xxx--agents-md)会被折叠成一行,0/2 看起来像同一 eval 跑两次。
+        const who = runWho(agentRun);
         const matched = evals.filter((e) => agentRun.evalFilter(e.id));
         for (const evalDef of matched) {
           liveRows.push({ evalId: evalDef.id, who, total: agentRun.runs });
@@ -388,7 +407,8 @@ async function main(): Promise<void> {
       reporters.push(ConsoleReporter());
     }
   }
-  reporters.push(ArtifactsReporter());
+  const artifacts = ArtifactsReporter();
+  reporters.push(artifacts);
   if (flags.junit) reporters.push(JUnit(flags.junit));
   reporters.push(...(config.reporters ?? []));
 
@@ -445,7 +465,6 @@ async function main(): Promise<void> {
     maxConcurrency:
       flags.maxConcurrency ??
       envNumber("NICEEVAL_MAX_CONCURRENCY") ??
-      expMaxConcurrency ??
       config.maxConcurrency ??
       sandboxDefaultConcurrency,
     signal: ctrl.signal,
@@ -457,7 +476,18 @@ async function main(): Promise<void> {
   // 跑顺利时登记表已空,是 no-op。
   await stopAllSandboxes();
 
-  const failedExit = summary.failed > 0 || summary.errored > 0;
+  // agent 反馈闭环的入口:跑完直接给出结构化结果路径,agent 读 summary.json 与各
+  // attempt 的工件(events/trace/diff),不必解析人类向的流式输出。--quiet 下也输出。
+  if (artifacts.outputDir()) {
+    process.stdout.write(t("cli.resultsPath", { path: join(artifacts.outputDir(), "summary.json") }));
+  }
+
+  // 退出码按 eval 级判决,不按 attempt:summary.failed/errored 统计的是每次 attempt,
+  // 被 runs+earlyExit 重试吸收的失败(先挂一次、后来过了)不该把进程判红——否则
+  // 「runs 吸收单次抖动」在 CI 退出码这层永远不成立。折叠口径与报表/view 共用
+  // foldEvalOutcome(任一轮通过 → 该 eval 通过),粒度 experimentId|eval id。
+  const stats = evalLevelStats(summary.results, (r) => `${r.experimentId ?? ""}|${r.id}`);
+  const failedExit = stats.failed > 0 || stats.errored > 0;
   process.exit(failedExit ? 1 : 0);
 }
 

package/src/context/types.ts

@@ -13,34 +13,59 @@ import type {
 
 /** t.send() 返回的句柄:从事件流派生便利字段 + expectOk。 */
 export interface TurnHandle {
+  /** 本轮的原始事件流(工具调用、消息增量等);下面的派生字段都算自它。 */
   readonly events: StreamEvent[];
+  /** 本轮内被调用的工具列表,从 events 派生。 */
   readonly toolCalls: readonly ToolCall[];
+  /** 本轮结束状态:"completed" 正常结束、"failed" 出错、"waiting" 卡在 HITL 输入请求上。 */
   readonly status: "completed" | "failed" | "waiting";
+  /** 本轮助手最终文本回复(events 里的消息增量拼接结果)。 */
   readonly message: string;
+  /** adapter 附带的结构化输出(如有),供 outputEquals / outputMatches 比对。 */
   readonly data?: unknown;
+  /** 本轮 token 用量与估算成本(仅上报了 usage 的 agent 才有)。 */
   readonly usage?: Usage;
   /** 上一轮若 failed 则抛(中止后续)。 */
   expectOk(): TurnHandle;
+  /** 断言 data 与给定值深度相等。 */
   outputEquals(value: unknown): AssertionHandle;
+  /** 断言 data 满足给定 schema(如 zod schema)。 */
   outputMatches(schema: unknown): AssertionHandle;
   /** 断言本轮助手回复包含 token(仅限本轮事件流,不跨轮)。 */
   messageIncludes(token: string | RegExp): AssertionHandle;
+  /** 断言本轮 status 为 "completed"。 */
   succeeded(): AssertionHandle;
+  /** 断言本轮卡在 HITL 输入请求上(status 为 "waiting")。 */
   parked(): AssertionHandle;
+  /** 断言本轮调用过指定名字的工具;`match` 可进一步约束入参 / 次数 / 状态。 */
   calledTool(name: string, match?: ToolMatch): AssertionHandle;
+  /** 断言本轮未调用指定工具(或未按 match 条件调用)。 */
   notCalledTool(name: string, match?: ToolMatch): AssertionHandle;
+  /** 断言本轮工具调用按给定顺序出现(允许中间夹杂其它调用)。 */
   toolOrder(names: string[]): AssertionHandle;
+  /** 断言本轮未调用任何工具。 */
   usedNoTools(): AssertionHandle;
+  /** 断言本轮工具调用总数不超过 max。 */
   maxToolCalls(max: number): AssertionHandle;
+  /** 断言本轮加载过指定 skill。 */
   loadedSkill(skill: string): AssertionHandle;
+  /** 断言本轮没有失败的工具调用 / 命令。 */
   noFailedActions(): AssertionHandle;
+  /** 断言本轮出现过指定类型的事件;`opts.count` 可约束出现次数。 */
   event(type: StreamEvent["type"], opts?: { count?: number }): AssertionHandle;
+  /** 断言本轮未出现指定类型的事件。 */
   notEvent(type: StreamEvent["type"]): AssertionHandle;
+  /** 断言本轮调用过指定名字的子 agent;`match` 可约束次数 / 状态 / remoteUrl。 */
   calledSubagent(name: string, match?: SubagentMatch): AssertionHandle;
+  /** 断言本轮事件按给定类型顺序出现(允许中间夹杂其它事件)。 */
   eventOrder(types: StreamEvent["type"][]): AssertionHandle;
+  /** 用自定义谓词对本轮整段事件流断言;失败时用 label 说明原因。 */
   eventsSatisfy(predicate: (events: readonly StreamEvent[]) => boolean, label?: string): AssertionHandle;
+  /** 断言本轮 token 用量不超过 max。 */
   maxTokens(max: number): AssertionHandle;
+  /** 断言本轮花费(USD)不超过 usd。 */
   maxCost(usd: number): AssertionHandle;
+  /** 本轮可用的 judge 命名空间(t.judge.autoevals.*)。 */
   readonly judge: JudgeNamespace;
 }
 
@@ -56,31 +81,43 @@ export interface JudgeNamespace {
   autoevals: AutoevalsNamespace;
 }
 
+/** 最终 diff 的只读视图(t.sandbox.diff);内容在 test() 跑完、finalize 前才落定。 */
 export interface DiffView {
+  /** 取某个生成 / 修改文件的最终内容;文件不在 diff 里则 undefined。 */
   get(path: string): string | undefined;
+  /** 整个 diff 是否为空(既没有生成/修改的文件,也没有删除的文件)。 */
   isEmpty(): boolean;
+  /** 正则是否命中 diff 里任意文件的路径或内容。 */
   matches(re: RegExp): boolean;
 }
 
 /** 工具匹配小语言。 */
 export interface ToolMatch {
+  /** 只匹配入参包含这些键值的调用(浅层包含,非深度相等)。 */
   input?: Record<string, unknown>;
+  /** 精确匹配调用次数,省略则只要求「至少一次」。 */
   count?: number;
+  /** 只匹配处于该状态的调用(如 HITL 场景下的 rejected)。 */
   status?: "completed" | "failed" | "rejected";
 }
 
+/** calledSubagent 的匹配小语言,语义同 ToolMatch。 */
 export interface SubagentMatch {
+  /** 精确匹配调用次数,省略则只要求「至少一次」。 */
   count?: number;
   status?: "completed" | "failed";
+  /** 只匹配指向该远程地址的子 agent 调用。 */
   remoteUrl?: string | RegExp;
 }
 
+/** requireInputRequest 的过滤条件;多个字段之间是 AND 关系。 */
 export interface InputRequestFilter {
   id?: string | RegExp;
   prompt?: string | RegExp;
   display?: string | RegExp;
   action?: string | RegExp;
   input?: Record<string, unknown>;
+  /** 请求的可选项 id 集合必须与此完全一致(顺序无关)。 */
   optionIds?: readonly string[];
 }
 
@@ -97,53 +134,104 @@ export interface RespondAnswer {
 
 /** eval 作者可见的受限沙箱视图:能执行命令 / 文件 IO / 读最终 diff,但不能 stop。 */
 export interface SandboxHandle {
+  /** 沙箱内的工作目录绝对路径。 */
   readonly workdir: string;
+  /** 在沙箱里执行一条命令(argv 形式,不经 shell)。装系统依赖等需要 root 时传 `{ root: true }`。 */
   runCommand(cmd: string, args?: string[], opts?: CommandOptions): Promise<CommandResult>;
+  /** 在沙箱里执行一段 shell 脚本(经 shell 解释,支持管道 / 重定向)。 */
   runShell(script: string, opts?: CommandOptions): Promise<CommandResult>;
+  /** 读沙箱内某文件此刻的文本内容(实时读,不是 diff 快照)。 */
   readFile(path: string): Promise<string>;
+  /** 沙箱内某路径此刻是否存在。 */
   fileExists(path: string): Promise<boolean>;
+  /** 按选项批量读回沙箱里的源文件,供比对 / judge 用材料。 */
   readSourceFiles(opts?: ReadSourceFilesOptions): Promise<SourceFiles>;
+  /** 把一组内容写进沙箱(路径相对 targetDir,默认 workdir)。 */
   writeFiles(files: Record<string, string>, targetDir?: string): Promise<void>;
+  /** 把一批内存中的文件上传进沙箱。 */
   uploadFiles(files: SandboxFile[], targetDir?: string): Promise<void>;
+  /** 把本地目录整体上传进沙箱;`opts.ignore` 排除指定路径。 */
   uploadDirectory(localDir: string, targetDir?: string, opts?: { ignore?: string[] }): Promise<void>;
+  /** 从沙箱下载某文件内容。 */
   downloadFile(path: string): Promise<Buffer>;
+  /** 把一段内容上传成沙箱里的单个文件。 */
   uploadFile(path: string, content: Buffer): Promise<void>;
+  /** 沙箱后端分配的实例 id,用于排查 / 关联日志。 */
   readonly sandboxId: string;
+  /** 相对 git 基线的最终 diff 视图(test() 跑完、finalize 前才落定)。 */
   readonly diff: DiffView;
+  /** 取沙箱内某文件的最终内容,占位延迟到 finalize 才真正读取;只能配合 t.check 使用。 */
   file(path: string): string;
+  /** 断言 diff 里某路径发生了变化(新增或修改)。 */
   fileChanged(path: string): AssertionHandle;
+  /** 断言 diff 里某路径被删除。 */
   fileDeleted(path: string): AssertionHandle;
+  /** 断言 diff 的路径与内容都不匹配给定正则(常用来否定式检查不该出现的改动)。 */
   notInDiff(re: RegExp): AssertionHandle;
+  /** 断言沙箱里执行过的命令都没有失败退出。 */
   noFailedShellCommands(): AssertionHandle;
 }
 
+/**
+ * `t.newSession()` 返回的独立会话句柄:另开一路对话,发送与断言都与默认会话及其它
+ * `newSession()` 会话相互隔离(各自的 events / usage 互不叠加)。下面的断言方法都按
+ * 「这个会话到目前为止的累计事件流」评估(跨该会话所有轮次),不是仅最后一轮——
+ * 只看最后一轮要用 `send()` 返回的 TurnHandle。
+ */
 export interface SessionHandle {
+  /** 在这个会话里发一条消息,返回该轮的 TurnHandle。 */
   send(text: string): Promise<TurnHandle>;
+  /** 在这个会话里发一条带文件的消息,语义同 TestContext.sendFile。 */
   sendFile(path: string, text?: string): Promise<TurnHandle>;
+  /** 取这个会话里等待中的 HITL 输入请求;拿不到就抛,语义同 TestContext.requireInputRequest。 */
   requireInputRequest(filter?: InputRequestFilter): InputRequest;
+  /** 回答这个会话里等待中的输入请求,返回续接的 TurnHandle。 */
   respond(...responses: (string | RespondAnswer)[]): Promise<TurnHandle>;
+  /** 用同一个 optionId 批量回答这个会话里全部等待中的输入请求。 */
   respondAll(optionId: string): Promise<TurnHandle>;
+  /** 这个会话最近一轮的助手回复文本。 */
   readonly reply: string;
+  /** adapter 侧的会话 id(有会话概念的 agent 才有)。 */
   readonly sessionId: string | undefined;
+  /** 这个会话累计的事件流(跨该会话内所有轮次,不含其它会话)。 */
   readonly events: readonly StreamEvent[];
+  /** 断言这个会话累计状态为 "completed"(跨全部轮次)。 */
   succeeded(): AssertionHandle;
+  /** 断言这个会话当前卡在 HITL 输入请求上。 */
   parked(): AssertionHandle;
+  /** 断言这个会话累计的助手回复包含 token(跨全部轮次)。 */
   messageIncludes(token: string | RegExp): AssertionHandle;
+  /** 断言这个会话累计调用过指定名字的工具;match 可约束入参 / 次数 / 状态。 */
   calledTool(name: string, match?: ToolMatch): AssertionHandle;
+  /** 断言这个会话累计未调用指定工具(或未按 match 条件调用)。 */
   notCalledTool(name: string, match?: ToolMatch): AssertionHandle;
+  /** 断言这个会话累计工具调用按给定顺序出现。 */
   toolOrder(names: string[]): AssertionHandle;
+  /** 断言这个会话至今未调用任何工具。 */
   usedNoTools(): AssertionHandle;
+  /** 断言这个会话累计工具调用总数不超过 max。 */
   maxToolCalls(max: number): AssertionHandle;
+  /** 断言这个会话累计加载过指定 skill。 */
   loadedSkill(skill: string): AssertionHandle;
+  /** 断言这个会话累计没有失败的工具调用 / 命令。 */
   noFailedActions(): AssertionHandle;
+  /** 断言这个会话累计出现过指定类型的事件;opts.count 可约束次数。 */
   event(type: StreamEvent["type"], opts?: { count?: number }): AssertionHandle;
+  /** 断言这个会话累计未出现指定类型的事件。 */
   notEvent(type: StreamEvent["type"]): AssertionHandle;
+  /** 断言这个会话累计调用过指定名字的子 agent;match 可约束次数 / 状态 / remoteUrl。 */
   calledSubagent(name: string, match?: SubagentMatch): AssertionHandle;
+  /** 断言这个会话累计事件按给定类型顺序出现。 */
   eventOrder(types: StreamEvent["type"][]): AssertionHandle;
+  /** 用自定义谓词对这个会话累计的整段事件流断言。 */
   eventsSatisfy(predicate: (events: readonly StreamEvent[]) => boolean, label?: string): AssertionHandle;
+  /** 断言这个会话累计 token 用量不超过 max。 */
   maxTokens(max: number): AssertionHandle;
+  /** 断言这个会话累计花费(USD)不超过 usd。 */
   maxCost(usd: number): AssertionHandle;
+  /** 这个会话累计的 token 用量与估算成本。 */
   readonly usage: Usage;
+  /** 这个会话可用的 judge 命名空间。 */
   readonly judge: JudgeNamespace;
 }
 
@@ -153,27 +241,59 @@ export interface SessionHandle {
  */
 export interface TestContext {
   // 会话
+  /** 向默认会话发一条消息,返回该轮的 TurnHandle。事件同时累加进默认会话的累计事件流,供下面的作用域断言使用。 */
   send(text: string): Promise<TurnHandle>;
   /** 发一条带文件(图片等多模态输入)的消息。`path` 相对项目根;读出后 base64 随 TurnInput.files 交给 adapter。 */
   sendFile(path: string, text?: string): Promise<TurnHandle>;
+  /** 取默认会话里等待中的 HITL 输入请求;不传 filter 要求恰好一条,拿不到就抛。 */
   requireInputRequest(filter?: InputRequestFilter): InputRequest;
+  /**
+   * 回答默认会话里等待中的输入请求,返回续接的 TurnHandle。字符串形式按顺序对应各请求;
+   * 多个请求并停、需要指名回答哪一条时用 RespondAnswer 对象形式(见其类型注释)。
+   */
   respond(...responses: (string | RespondAnswer)[]): Promise<TurnHandle>;
+  /** 用同一个 optionId 批量回答默认会话里全部等待中的输入请求。 */
   respondAll(optionId: string): Promise<TurnHandle>;
+  /** 默认会话最近一轮的助手回复文本。 */
   readonly reply: string;
+  /** adapter 侧的默认会话 id(有会话概念的 agent 才有)。 */
   readonly sessionId: string | undefined;
+  /** 默认会话累计的事件流(跨该会话所有轮次)。 */
   readonly events: readonly StreamEvent[];
+  /**
+   * 另开一路独立会话,返回它的 SessionHandle——不是 void。多会话隔离的关键入口:
+   * 新会话的发送与断言都与默认会话及其它 newSession() 会话相互隔离,常用于「多用户
+   * 并行对话」「一条主线 + 一条旁支」这类场景。
+   */
   newSession(): SessionHandle;
 
   // 运行上下文
+  /** 本次 attempt 的中止信号;超时 / 早停 / 用户 Ctrl-C 时触发,传给 adapter 的长耗时调用做取消。 */
   readonly signal: AbortSignal;
+  /** 本次 attempt 使用的模型名(由 experiment/CLI flag 决定);省略即 agent 原生默认,不代表「无模型」。 */
   readonly model?: string;
+  /** 本次 attempt 的推理努力程度(如 "low"/"medium"/"high",取值由 adapter/模型决定)。 */
   readonly reasoningEffort?: string;
+  /** 本次 attempt 生效的 flags(experiment.flags 与 CLI flag 合并后的只读视图)。 */
   readonly flags: Readonly<Record<string, unknown>>;
+  /** 打一行调试日志;有 live 进度回调时走该回调,否则落到 stderr,不出现在最终结果里。 */
   log(msg: string): void;
+  /** 立即中止本 eval 并标记为 skipped(outcome / EvalResult.skipReason),reason 不能为空。 */
   skip(reason: string): never;
 
   // 值级断言
+  /**
+   * 对任意值跑一个 ValueAssertion,返回可链 `.gate()` / `.atLeast()` 的 AssertionHandle。
+   * 打分延迟到 eval 结束后统一 finalize,调用本身同步、不抛错——不通过只是记一条失败断言,
+   * 不会中止后续代码。要「不满足就立即中止 eval」用 require。
+   */
   check(value: unknown, assertion: ValueAssertion): AssertionHandle;
+  /**
+   * 对任意值跑一个 ValueAssertion,立即(await 时)求值;不满足就抛错中止整个 eval 剩余步骤
+   * (仍会把这条断言计入报告,不影响已记录的其它断言)。跟 check 的区别:check 只记录、
+   * 从不抛错,打分留到最后统一算;require 当场判定、失败即中止,适合「前置条件不满足,
+   * 后面写了也没意义」的场景。
+   */
   require(value: unknown, assertion: ValueAssertion): Promise<unknown>;
   /**
    * 把一组断言归到一个有标题的分组下(对照 vitest 的 test('title', ...))。纯组织/报告用,
@@ -182,30 +302,50 @@ export interface TestContext {
   group<T>(title: string, fn: () => Promise<T> | T): Promise<T>;
 
   // 作用域断言(工具 / 会话)
+  /** 断言默认会话累计状态为 "completed"(跨该会话所有轮次,不止最后一轮)。 */
   succeeded(): AssertionHandle;
+  /** 断言默认会话当前卡在 HITL 输入请求上。 */
   parked(): AssertionHandle;
+  /** 断言默认会话累计的助手回复包含 token(跨该会话所有轮次,不止最后一轮)。 */
   messageIncludes(token: string | RegExp): AssertionHandle;
+  /** 断言默认会话累计调用过指定名字的工具;match 可约束入参 / 次数 / 状态。 */
   calledTool(name: string, match?: ToolMatch): AssertionHandle;
+  /** 断言默认会话累计未调用指定工具(或未按 match 条件调用)。 */
   notCalledTool(name: string, match?: ToolMatch): AssertionHandle;
+  /** 断言默认会话累计工具调用按给定顺序出现(允许中间夹杂其它调用)。 */
   toolOrder(names: string[]): AssertionHandle;
+  /** 断言默认会话至今未调用任何工具。 */
   usedNoTools(): AssertionHandle;
+  /** 断言默认会话累计工具调用总数不超过 max。 */
   maxToolCalls(max: number): AssertionHandle;
+  /** 断言默认会话累计加载过指定 skill。 */
   loadedSkill(skill: string): AssertionHandle;
+  /** 断言默认会话累计没有失败的工具调用 / 命令。 */
   noFailedActions(): AssertionHandle;
+  /** 断言默认会话累计出现过指定类型的事件;opts.count 可约束出现次数。 */
   event(type: StreamEvent["type"], opts?: { count?: number }): AssertionHandle;
+  /** 断言默认会话累计未出现指定类型的事件。 */
   notEvent(type: StreamEvent["type"]): AssertionHandle;
+  /** 断言默认会话累计调用过指定名字的子 agent;match 可约束次数 / 状态 / remoteUrl。 */
   calledSubagent(name: string, match?: SubagentMatch): AssertionHandle;
+  /** 断言默认会话累计事件按给定类型顺序出现(允许中间夹杂其它事件)。 */
   eventOrder(types: StreamEvent["type"][]): AssertionHandle;
+  /** 用自定义谓词对默认会话累计的整段事件流断言;失败时用 label 说明原因。 */
   eventsSatisfy(predicate: (events: readonly StreamEvent[]) => boolean, label?: string): AssertionHandle;
 
   // 工作区 / 沙箱
+  /** 受限沙箱视图:能执行命令 / 读写文件 / 看最终 diff,不能 stop 沙箱本身(见 SandboxHandle)。 */
   readonly sandbox: SandboxHandle;
 
   // 效率 / 成本
+  /** 默认会话累计的 token 用量与估算成本。 */
   readonly usage: Usage;
+  /** 断言默认会话累计 token 用量不超过 max。 */
   maxTokens(max: number): AssertionHandle;
+  /** 断言默认会话累计花费(USD)不超过 usd。 */
   maxCost(usd: number): AssertionHandle;
 
   // judge
+  /** 可用的 judge 命名空间(t.judge.autoevals.*)。 */
   readonly judge: JudgeNamespace;
 }

package/src/expect/index.ts

@@ -112,8 +112,9 @@ export function equals(expected: unknown): ValueAssertion {
 }
 
 /**
- * 用 schema 校验 value。优先 Standard Schema(schema['~standard'].validate),
- * 否则退化到 zod 风格的 .safeParse / .parse。校验通过 1,否则 0;任何异常 → 0。
+ * 用 schema 校验 value——不是正则匹配,是 Standard Schema / zod 风格的结构校验。
+ * 优先 Standard Schema(schema['~standard'].validate),否则退化到 zod 风格的
+ * .safeParse / .parse。校验通过 1,否则 0;任何异常 → 0。默认硬门槛。
  */
 export function matches(schema: unknown): ValueAssertion {
   return createAssertion("matches(schema)", "gate", async (value) =>
@@ -121,7 +122,10 @@ export function matches(schema: unknown): ValueAssertion {
   );
 }
 
-/** 归一化 Levenshtein 相似度 [0,1]。默认软分,阈值 0.6。 */
+/**
+ * 纯字符串编辑距离,不是语义相似度——归一化 Levenshtein 距离 [0,1](1 - 编辑距离 / 较长串长度),
+ * 不理解含义,同义改写 / 语序调整会被判低分。默认软分,阈值 0.6。
+ */
 export function similarity(expected: string): ValueAssertion {
   return createAssertion(
     `similarity(${safeLabel(expected)})`,
@@ -143,19 +147,19 @@ export function satisfies(predicate: (v: unknown) => boolean, label?: string): V
   return createAssertion(name, "gate", (value) => (predicate(value) ? 1 : 0));
 }
 
-/** value 非 null / 非 undefined 则 1,否则 0。省掉 `x !== undefined` + isTrue 的样板。 */
+/** value 非 null / 非 undefined 则 1,否则 0。省掉 `x !== undefined` + isTrue 的样板。默认硬门槛。 */
 export function isDefined(label?: string): ValueAssertion {
   const name = label ? `isDefined(${label})` : "isDefined()";
   return createAssertion(name, "gate", (value) => (value != null ? 1 : 0));
 }
 
-/** value === true 则 1,否则 0。带 label 的布尔断言(fileExists 等检查用)。 */
+/** value === true 则 1,否则 0。带 label 的布尔断言(fileExists 等检查用)。默认硬门槛。 */
 export function isTrue(label?: string): ValueAssertion {
   const name = label ? `isTrue(${label})` : "isTrue()";
   return createAssertion(name, "gate", (value) => (value === true ? 1 : 0));
 }
 
-/** CommandResult.exitCode === 0 则通过。 */
+/** CommandResult.exitCode === 0 则 1,否则 0。默认硬门槛。 */
 export function commandSucceeded(): ValueAssertion {
   return createAssertion("commandSucceeded()", "gate", (value) => {
     if (value === null || typeof value !== "object") return 0;
@@ -163,13 +167,16 @@ export function commandSucceeded(): ValueAssertion {
   });
 }
 
-/** value === false 则 1,否则 0。带 label 的布尔断言。 */
+/** value === false 则 1,否则 0。带 label 的布尔断言。默认硬门槛。 */
 export function isFalse(label?: string): ValueAssertion {
   const name = label ? `isFalse(${label})` : "isFalse()";
   return createAssertion(name, "gate", (value) => (value === false ? 1 : 0));
 }
 
-/** 自定义断言工厂:直接给名字 / 严重级 / 阈值 / score。severity 省略默认 gate。 */
+/**
+ * 自定义断言工厂:直接给名字 / 严重级 / 阈值 / score,一次调用即返回可用的 ValueAssertion——
+ * 不像 gate()/atLeast() 那样需要二段链式调用来定级。severity 省略默认 gate。
+ */
 export function makeAssertion(spec: {
   name: string;
   severity?: Severity;