niceeval 0.5.4 → 0.6.0

package/dist/shared/types.d.ts

@@ -0,0 +1,27 @@
+/** JSON 可表达的任意值(递归定义),用于事件流 / 工具输入输出等跨进程/跨语言传递的数据。 */
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/** 断言的严重度:"gate" 失败必判整轮 failed;"soft" 默认只记录不拦截,仅在 `--strict` 模式或显式设阈值未达标时才计入失败。 */
+export type Severity = "gate" | "soft";
+/**
+ * eval 源码里一次调用的位置(`t.send` / 各断言),运行期从栈回溯抠出来(见 src/source-loc.ts)。
+ * view 据此把运行结果叠回真实源码行(github-diff 式代码视图)。`file` 为相对项目根的路径。
+ */
+export interface SourceLoc {
+    file: string;
+    line: number;
+    column?: number;
+}
+/** 随结果回传的一份 eval 源码(相对项目根的路径 + 文本),供 view 渲染代码视图。 */
+export interface SourceArtifact {
+    path: string;
+    content: string;
+}
+/** 通用清理闭包(setup 返回值 / teardown 的形状),异步同步皆可,统一在 finally 里执行。 */
+export type Cleanup = () => Promise<void> | void;
+/**
+ * 可本地化文案:纯字符串,或按 locale 代码(如 "en"、"zh-CN")映射多语言。
+ * view 按当前界面语言挑一条,挑不到回退到 en / 第一条。
+ */
+export type LocalizedText = string | Record<string, string>;

package/dist/shared/verdict.d.ts

@@ -0,0 +1,27 @@
+import type { Verdict } from "../types.ts";
+/** 折叠/计票只需要 verdict 字段;server 传 EvalResult,前端传 ViewResult 都满足。 */
+export interface VerdictLike {
+    verdict: Verdict;
+}
+/**
+ * 把同一个 eval 的多轮 attempt 折叠成单一判定:任一轮通过 → 该 eval 通过(对齐 earlyExit
+ * 「先过一次即停」语义),否则按 failed > errored > skipped 取最严重的一个。
+ */
+export declare function foldEvalVerdict(attempts: VerdictLike[]): Verdict;
+export interface EvalLevelStats {
+    /** 去重后的 eval 数(成功率分母的口径)。 */
+    evals: number;
+    passed: number;
+    failed: number;
+    errored: number;
+    skipped: number;
+    passRate: number;
+}
+/**
+ * 通过率与 passed/failed 一律按 eval 计票,不按 attempt:每个 eval 不管跑几轮都只占一票,先把它
+ * 的多轮折叠成单一判定再计数。否则 runs>1 时同一 eval 的 N 次 attempt 各算一票 —— 尤其 earlyExit
+ * 开时通过的 eval 只留 1 次、失败的 eval 跑满 N 次,失败 eval 被重复计入分母,把通过率拉低
+ * (见 docs/runner.md、docs/feature/scoring/README.md)。keyOf 决定「一个 eval」的粒度:单实验按 eval id,
+ * 跨实验组按 experimentId|eval id。
+ */
+export declare function evalLevelStats<T extends VerdictLike>(results: T[], keyOf: (r: T) => string): EvalLevelStats;

package/dist/shared/verdict.js

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

package/dist/tty-line.d.ts

@@ -0,0 +1,6 @@
+/** live.ts 用来订阅"即将有一行独立诊断消息落地"。返回取消订阅函数。 */
+export declare function onBeforeExternalTerminalWrite(fn: () => void): () => void;
+/** 任何要绕开 Reporter 直接往终端打一行独立诊断消息的地方,写之前都先调用这个。 */
+export declare function beforeExternalTerminalWrite(): void;
+/** process.stderr.write 的替代:文本需自带换行(沿用现有 i18n 字符串的约定)。 */
+export declare function writeStderrLine(text: string): void;

package/dist/types.d.ts

@@ -0,0 +1,7 @@
+export * from "./shared/types.ts";
+export * from "./o11y/types.ts";
+export * from "./sandbox/types.ts";
+export * from "./agents/types.ts";
+export * from "./scoring/types.ts";
+export * from "./context/types.ts";
+export * from "./runner/types.ts";

package/dist/util.d.ts

@@ -0,0 +1,22 @@
+/** 读必需的环境变量,缺了就清晰报错(agent 鉴权用)。 */
+export declare function requireEnv(name: string): string;
+/** 取环境变量,缺了返回 undefined。 */
+export declare function getEnv(name: string): string | undefined;
+/** 去掉 JS/TS 注释(块注释 + 行注释),好让断言只对真实代码生效,不被注释里的迁移说明误伤。 */
+export declare function stripComments(code: string): string;
+/**
+ * 把 catch 到的 e 转成报告用字符串。优先带 stack(定位到 eval 脚本抛错的具体 file:line),
+ * 只在没有 stack 时才退化到 `name: message`。EvalResult.error 走这个,别再手写
+ * `e instanceof Error ? e.message : String(e)`——那样用户永远看不出错误发生在哪一行。
+ */
+export declare function formatThrown(e: unknown): string;
+/** 零填充到 4 位(数据集扇出的 id:sql/0000)。 */
+export declare function pad4(n: number): string;
+/**
+ * 在文本里维护一个带 BEGIN/END 标记的托管区块(AGENTS.md 的 niceeval 区块用)。
+ * 标记已存在 → 只替换两个标记之间的内容(升级时刷新指引,区块外的用户内容不动);
+ * 不存在 → 追加到末尾(与已有内容之间空一行)。
+ */
+export declare function upsertManagedBlock(source: string, begin: string, end: string, content: string): string;
+/** 把任意值安全地转成简短字符串(报告 / 日志用)。 */
+export declare function brief(value: unknown, max?: number): string;

package/docs-site/zh/concepts/adapter.mdx

@@ -1,7 +1,7 @@
 ---
 title: "Adapter：把 Agent 接入 NiceEval"
 sidebarTitle: "Adapter"
-description: "Adapter 是你写的适配器。本文讲清楚 send 函数传入什么返回什么、被测系统配置怎么传、三个接入 Tier，以及 t 上的能力从哪来。"
+description: "Adapter 是你写的适配器。本文讲清楚 send 函数传入什么返回什么、被测系统配置怎么传、三个接入等级，以及 t 上的能力从哪来。"
 ---
 
 在 [NiceEval](https://niceeval.com/) 里，`Adapter` 是连接运行器和被测系统的适配层。Adapter 需要实现 `send` 函数：把 `t.send()` 等 eval 侧动作发给你的应用，再把应用返回翻译成 [NiceEval](https://niceeval.com/) 的标准 `Turn`。
@@ -85,9 +85,9 @@ export default defineExperiment({
 });
 ```
 
-## 接入 Tier
+## 接入等级
 
-按「Adapter 接到哪里、额外拿到什么观测数据」，接入分三档：**Tier 1 只接 send**（应用代码一行不改，全套断言在这一档就齐了）、**Tier 2 send + OTel**（应用把 span 发给 [NiceEval](https://niceeval.com/)，换 `niceeval view` 的调用瀑布图）、**Tier 3 侵入改造 + experiment flags**（feature A/B）。每档投入什么、买到什么、什么时候升级，见 [Tier](/zh/concepts/tier)。
+按「Adapter 接到哪里、额外拿到什么观测数据」，接入分三级：**Tier 1 只接 send**（应用代码一行不改，全套断言在这一级就齐了）、**Tier 2 send + OTel**（应用把 span 发给 [NiceEval](https://niceeval.com/)，换 `niceeval view` 的调用瀑布图）、**Tier 3 侵入改造 + experiment flags**（feature A/B）。每档投入什么、买到什么、什么时候升级，见 [Tier](/zh/concepts/tier)。
 
 eval 侧的驱动 API——`t.send()`、`t.sendFile()`、`t.newSession()`、HITL 的 `t.respond()` / `t.respondAll()`
 统一都是调用 Adapter 的 `send`。
@@ -110,7 +110,7 @@ interface Agent {
 `send` 是唯一要实现的函数。它的签名里只有三个类型，分开看。
 
 <Note>
-  这里的 `setup` / `teardown` 是 Agent 自己"怎么连自己"的私事（装 CLI、写鉴权配置）。按实验变化的环境准备（装某个实验专属的二进制、预热、跨 attempt 保存状态）不写在 Agent 上，挂在 `sandbox` 字段那个 Sandbox spec 自己的 `.setup()` / `.teardown()` 链式方法上，见 [Sandbox 后端 · 环境钩子](/zh/guides/sandbox-backends#环境钩子)。
+  这里的 `setup` / `teardown` 是 Agent 自己"怎么连自己"的私事（装 CLI、写鉴权配置）。按实验变化的环境准备（装某个实验专属的二进制、预热、跨 attempt 保存状态）不写在 Agent 上，挂在 `sandbox` 字段那个 Sandbox spec 自己的 `.setup()` / `.teardown()` 链式方法上，见 [Sandbox 后端 · 环境钩子](/zh/guides/sandbox-providers#环境钩子)。
 </Note>
 
 ### 传入：`TurnInput`
@@ -214,7 +214,7 @@ interface AgentSession {
 }
 ```
 
-`ctx` 里没有要你检查的标志位。三个档位字段都是"透传"语义：`model`、`flags` 由 experiment 声明、运行器原样递过来，Adapter 只负责随请求转发给应用，不解释它们的含义；`telemetry` 仅在配置了 OTel 接入时出现，`send` 里只需要把 `headers` spread 进请求头——接收端点在 `defineConfig` 里固定、由应用启动时指向，不从这里传，见[OTel 接入](/zh/guides/connect-otel)。`experimentId` 是路径推导出的稳定标识，典型用途是在 Sandbox 的环境钩子里按实验隔离跨 attempt 的状态（缓存目录名、快照 tag 按它分区），见 [Sandbox 后端 · 环境钩子](/zh/guides/sandbox-backends#环境钩子)。
+`ctx` 里没有要你检查的标志位。三个档位字段都是"透传"语义：`model`、`flags` 由 experiment 声明、运行器原样递过来，Adapter 只负责随请求转发给应用，不解释它们的含义；`telemetry` 仅在配置了 OTel 接入时出现，`send` 里只需要把 `headers` spread 进请求头——接收端点在 `defineConfig` 里固定、由应用启动时指向，不从这里传，见[OTel 接入](/zh/guides/connect-otel)。`experimentId` 是路径推导出的稳定标识，典型用途是在 Sandbox 的环境钩子里按实验隔离跨 attempt 的状态（缓存目录名、沙箱快照 tag 按它分区），见 [Sandbox 后端 · 环境钩子](/zh/guides/sandbox-providers#环境钩子)。
 
 `session` 是本条会话线的自有状态，[NiceEval](https://niceeval.com/) 对它只承诺一件事：**同一条会话线的每次 `send` 拿到同一个 `ctx.session`，新会话线（eval 的第一轮，或 `t.newSession()` 之后）拿到一个全新的。** 会话续接（`id`/`capture`、`history`）和 HITL 停轮现场（`hold`/`take`）的存取器都在它上面，"第一轮"就是新会话线的自然形态——`id` 是 `undefined`、`history.get()` 是空数组，没有要判断的分支；`state` 是这些存取器之外的逃生舱，框架从不往里写数据。
 

package/docs-site/zh/concepts/assert.mdx

@@ -1,10 +1,10 @@
 ---
 title: "NiceEval 断言：值、作用域事实、测试与成本"
 sidebarTitle: "断言"
-description: "NiceEval 的断言词汇——值断言、作用域断言、test-as-scoring 和效率断言——以及 gate / soft 严重级和判决 outcome 的规则。"
+description: "NiceEval 的断言词汇——值断言、作用域断言、test-as-scoring 和效率断言——以及 gate / soft 严重度和判定 verdict 的规则。"
 ---
 
-断言把 agent 在一次 eval 里做的一切——每条消息、每次工具调用、每处文件改动、每一分 token——折叠成一个可解释的结果。[NiceEval](https://niceeval.com/) 提供四种互补的断言机制：有的立即检查一个值，有的在整轮跑完后评估整次运行，有的在沙箱里跑测试，有的衡量效率。四种都产出同一种 `Assertion` 类型，都进同一套判决规则。第五种机制——让语言模型评判开放式质量——见 [Judge](/zh/concepts/judge)。
+断言把 agent 在一次 eval 里做的一切——每条消息、每次工具调用、每处文件改动、每一分 token——折叠成一个可解释的结果。[NiceEval](https://niceeval.com/) 提供四种互补的断言机制：有的立即检查一个值，有的在整轮跑完后评估整次运行，有的在沙箱里跑测试，有的衡量效率。四种都产出同一种 `Assertion` 类型，都进同一套判定规则。第五种机制——让语言模型评判开放式质量——见 [Judge](/zh/concepts/judge)。
 
 ## 四种断言机制
 
@@ -23,9 +23,9 @@ description: "NiceEval 的断言词汇——值断言、作用域断言、test-a
   </Card>
 </CardGroup>
 
-## gate 与 soft 严重级
+## gate 与 soft 严重度
 
-每条断言都带一个**严重级**，决定它如何影响最终判决，只有两档：
+每条断言都带一个**严重度**，决定它如何影响最终判定，只有两档：
 
 <Tabs>
   <Tab title="gate">
@@ -42,7 +42,7 @@ description: "NiceEval 的断言词汇——值断言、作用域断言、test-a
   </Tab>
 </Tabs>
 
-在任意匹配器或断言上用链式方法覆盖默认严重级：
+在任意匹配器或断言上用链式方法覆盖默认严重度：
 
 ```ts
 t.check(t.reply, includes("confirmed"));          // 默认 gate
@@ -50,7 +50,7 @@ t.check(t.reply, similarity(expected).gate());    // 提升为 gate
 t.maxTokens(80_000).atLeast(0.7);                 // 降为 soft 并带阈值
 ```
 
-## 判决规则
+## 判定规则
 
 所有断言收齐后，运行器按这个顺序折叠成一个结果：
 
@@ -77,7 +77,7 @@ t.maxTokens(80_000).atLeast(0.7);                 // 降为 soft 并带阈值
   </Card>
 </CardGroup>
 
-多次运行（`runs > 1`）时，单个 eval 的汇总变成**通过率**（产出 `passed` 的运行占比）和平均耗时，而不是单一 outcome。
+多次运行（`runs > 1`）时，单个 eval 的汇总变成**通过率**（产出 `passed` 的运行占比）和平均耗时，而不是单一 verdict。
 
 ## 1. 值断言 —— `niceeval/expect` 匹配器
 
@@ -240,4 +240,4 @@ t.check(t.reply, jsonValid());
 - [Drive](/zh/concepts/drive) — `t.send()`、`t.newSession()` 和 HITL：这些断言读的 Turn 数据是怎么产出的。
 - [Judge](/zh/concepts/judge) — 第五种评分机制，评无法写成固定规则的开放式质量。
 - [写 send](/zh/guides/write-send) — 标准事件流如何产出，作用域断言依赖它什么。
-- [Evals](/zh/concepts/evals) — 断言如何折进 eval 生命周期和 outcome 类型。
+- [Evals](/zh/concepts/evals) — 断言如何折进 eval 生命周期和 verdict 类型。

package/docs-site/zh/concepts/evals.mdx

@@ -1,5 +1,5 @@
 ---
-title: "NiceEval 中的 eval：生命周期、outcome 与文件"
+title: "NiceEval 中的 eval：生命周期、verdict 与文件"
 sidebarTitle: "评估"
 description: "eval 是一个测试用例：描述、agent 引用和 test 函数。了解 eval 如何被发现、调度、评分和报告。"
 ---
@@ -61,15 +61,15 @@ npx niceeval exp local weather/brooklyn
   <Step title="Scoring">
     [NiceEval](https://niceeval.com/) 收集值断言、作用域断言、judge 分数和测试结果。
   </Step>
-  <Step title="Outcome">
-    所有断言结果折叠成一个最终 outcome。
+  <Step title="Verdict">
+    所有断言结果折叠成一个最终 verdict。
   </Step>
   <Step title="Report">
     控制台和 reporters 输出结果，同时写入 `.niceeval/` artifacts。
   </Step>
 </Steps>
 
-## Outcome 类型
+## Verdict 类型
 
 <CardGroup cols={2}>
   <Card title="passed" icon="circle-check" color="#22c55e">
@@ -121,4 +121,4 @@ export default rows.map((row) =>
 ## 相关阅读
 
 - [实验](/zh/concepts/experiment) — 另一半：评谁、怎么跑；为什么和 eval 分开（晚绑定）。
-- [Assert](/zh/concepts/assert) — gate 与 soft 的完整判决规则。
+- [Assert](/zh/concepts/assert) — gate 与 soft 的完整判定规则。

package/docs-site/zh/concepts/experiment.mdx

@@ -25,7 +25,7 @@ export default defineExperiment({
 - `model` / `flags`：透传语义。[NiceEval](https://niceeval.com/) 不解释它们的含义，原样经 `ctx` 递给 Adapter，由 Adapter 随请求转发、应用按需切换——这正是 [Tier](/zh/concepts/tier) 里模型对比（Tier 1）和 feature A/B（Tier 3）的通道。
 - `runs`、`budget`、并发、`sandbox` 等运行参数：怎么跑、跑多少。完整字段见[写实验](/zh/guides/write-experiment)。
 
-Experiment 是纯配置数据，没有 `setup` / `teardown` 这类生命周期字段。要按实验准备环境（装二进制、预热、跨 attempt 存取状态），挂在 `sandbox` 字段的 spec 上——`dockerSandbox()` 等工厂返回的对象可以链 `.setup()` / `.teardown()`，见 [Sandbox 后端 · 环境钩子](/zh/guides/sandbox-backends#环境钩子)。
+Experiment 是纯配置数据，没有 `setup` / `teardown` 这类生命周期字段。要按实验准备环境（装二进制、预热、跨 attempt 存取状态），挂在 `sandbox` 字段的 spec 上——`dockerSandbox()` 等工厂返回的对象可以链 `.setup()` / `.teardown()`，见 [Sandbox 后端 · 环境钩子](/zh/guides/sandbox-providers#环境钩子)。
 
 ## 矩阵对比
 
@@ -35,5 +35,5 @@ Experiment 是纯配置数据，没有 `setup` / `teardown` 这类生命周期
 
 - [写实验](/zh/guides/write-experiment) — `defineExperiment` 的完整字段：runs、预算、并发与 sandbox。
 - [实验矩阵](/zh/guides/experiments) — 跨 agent / model / flags 的对比怎么组织、怎么读结果。
-- [评估](/zh/concepts/evals) — 另一半：eval 是什么、生命周期与 outcome。
+- [评估](/zh/concepts/evals) — 另一半：eval 是什么、生命周期与 verdict。
 - [Tier](/zh/concepts/tier) — `model` / `flags` 各在哪一档生效。

package/docs-site/zh/concepts/judge.mdx

@@ -1,10 +1,10 @@
 ---
 title: "NiceEval 里的 LLM-as-judge: 给开放式输出打分"
 sidebarTitle: "评判"
-description: "t.judge / session.judge / turn.judge 如何用独立评判模型评估事实性、闭合式质量和摘要忠实度，以及模型解析优先级和严重级。"
+description: "t.judge / session.judge / turn.judge 如何用独立裁判模型评估事实性、闭合式质量和摘要忠实度，以及模型解析优先级和严重度。"
 ---
 
-judge 断言是第五种评分机制，和 [Assert](/zh/concepts/assert) 里的四种并列。用在“对不对靠规则说不清”的地方——开放式行文、语气、事实一致性、摘要质量。评判模型和被测 agent **完全分离**，避免自评：同一个模型给自己的输出打分，天然会打得偏高。
+judge 断言是第五种评分机制，和 [Assert](/zh/concepts/assert) 里的四种并列。用在“对不对靠规则说不清”的地方——开放式行文、语气、事实一致性、摘要质量。裁判模型和被测 agent **完全分离**，避免自评：同一个模型给自己的输出打分，天然会打得偏高。
 
 ```ts
 t.judge.autoevals.factuality(reference).atLeast(0.8);   // 与参考文本的事实一致性
@@ -21,7 +21,7 @@ t.judge.autoevals.closedQA("自定义评分标准描述", { on: t.reply });
 - **`factuality(reference, opts?)`** —— 输出和你给的参考文本之间的事实一致性。
 - **`summarizes(source, opts?)`** —— 输出是否忠实摘要了某个源文档。
 
-`{ on }` 指定被评的值，默认值按接收者决定（见下文）；`{ model }` 单次覆盖评判模型。
+`{ on }` 指定被评的值，默认值按接收者决定（见下文）；`{ model }` 单次覆盖裁判模型。
 
 ## judge 挂在哪：`t`、`session`、`turn`
 
@@ -57,7 +57,7 @@ t.judge.autoevals.closedQA("生成的代码是否是地道的 TypeScript?", {
 
 ## judge 模型解析优先级
 
-评判模型按从具体到笼统解析：
+裁判模型按从具体到笼统解析：
 
 ```
 单次调用的 { model } 选项
@@ -87,7 +87,7 @@ t.judge.autoevals.closedQA("rubric", { on: t.reply, model: "openai/gpt-4o" });
 
 ## 评判端点与 key：OpenAI 兼容协议
 
-评判模型走 **OpenAI 兼容的 `/chat/completions`** 协议。OpenAI 官方、DeepSeek，以及任何兼容这个协议的网关都能当评判端点，在 `judge` 配置里指定：
+裁判模型走 **OpenAI 兼容的 `/chat/completions`** 协议。OpenAI 官方、DeepSeek，以及任何兼容这个协议的网关都能当评判端点，在 `judge` 配置里指定：
 
 ```ts
 // niceeval.config.ts
@@ -111,9 +111,9 @@ defineConfig({
   key 一个都解析不到时，judge 断言**静默跳过**——不报错、不记分，eval 照常跑。全绿不代表 judge 真的评过。配完 key 先跑一条带 `t.judge` 的 eval，在 `niceeval view` 里确认出现了 judge 分数。
 </Warning>
 
-## 严重级：judge 默认 soft
+## 严重度：judge 默认 soft
 
-judge 调用和其它断言一样是评分函数，遵守 [Assert · gate 与 soft 严重级](/zh/concepts/assert#gate-与-soft-严重级) 同一套机制——只是**默认值**和大多数值匹配器不同：
+judge 调用和其它断言一样是评分函数，遵守 [Assert · gate 与 soft 严重度](/zh/concepts/assert#gate-与-soft-严重度) 同一套机制——只是**默认值**和大多数值匹配器不同：
 
 ```ts
 t.judge.autoevals.closedQA("语气是否礼貌?");              // 不带阈值 → soft，纯记分，永不让 eval 失败
@@ -125,6 +125,6 @@ t.judge.autoevals.closedQA("语气是否礼貌?").gate();       // 提升为 gat
 
 ## 相关阅读
 
-- [Assert](/zh/concepts/assert) — gate / soft 严重级的完整规则，以及 judge 分数最终折进的判决规则。
+- [Assert](/zh/concepts/assert) — gate / soft 严重度的完整规则，以及 judge 分数最终折进的判定规则。
 - [Drive](/zh/concepts/drive) — `t.send()`、`t.newSession()`，以及 `t.judge` / `session.judge` / `turn.judge` 各自挂在哪个 handle 上。
-- [Evals](/zh/concepts/evals) — judge 分数如何折进 eval 生命周期和 outcome 类型。
+- [Evals](/zh/concepts/evals) — judge 分数如何折进 eval 生命周期和 verdict 类型。

package/docs-site/zh/concepts/overview.mdx

@@ -96,7 +96,7 @@ Subject under test / Sandbox backend
   <Step title="Scheduling">根据并发、缓存和 attempt 计划运行。</Step>
   <Step title="Agent send">调用 adapter，让被测对象产出 `Turn`。</Step>
   <Step title="Scoring">执行断言、judge 和测试。</Step>
-  <Step title="Outcome">把所有结果折叠为 `passed`、`failed`、`errored` 或 `skipped`。</Step>
+  <Step title="Verdict">把所有结果折叠为 `passed`、`failed`、`errored` 或 `skipped`。</Step>
   <Step title="Reporting & artifacts">输出报告并保存结构化文件。</Step>
 </Steps>
 
@@ -105,5 +105,5 @@ Subject under test / Sandbox backend
 - [Evals](/zh/concepts/evals) — eval 是什么，以及生命周期细节。
 - [Adapter](/zh/concepts/adapter) — 如何写 adapter，并在 experiment 中引用它。
 - [Drive](/zh/concepts/drive) — `t.send()`、session 与 HITL：如何产出断言要读的 `Turn` 数据。
-- [Assert](/zh/concepts/assert) — 断言词汇和判决规则。
+- [Assert](/zh/concepts/assert) — 断言词汇和判定规则。
 - [Judge](/zh/concepts/judge) — LLM-as-judge，评开放式质量。

package/docs-site/zh/concepts/tier.mdx

@@ -1,10 +1,10 @@
 ---
-title: "接入 Tier：三档投入，三组能力"
-sidebarTitle: "Tier"
-description: "按「Adapter 接到哪里、额外拿到什么观测数据」接入分三档：Tier 1 只接 send，Tier 2 加 OTel，Tier 3 侵入改造暴露 experiment flags。每档买到什么、什么时候升级。"
+title: "接入等级（Tier）：三级投入，三组能力"
+sidebarTitle: "接入等级"
+description: "按「Adapter 接到哪里、额外拿到什么观测数据」接入分三级：Tier 1 只接 send，Tier 2 加 OTel，Tier 3 侵入改造暴露 experiment flags。每档买到什么、什么时候升级。"
 ---
 
-接入 [NiceEval](https://niceeval.com/) 不是全有或全无的一次性工程。按「Adapter 接到哪里、额外拿到什么观测数据」，接入分三档——每一档在上一档之上加一种投入、换一组新能力，已写的 eval 全程复用，不用改。
+接入 [NiceEval](https://niceeval.com/) 不是全有或全无的一次性工程。按「Adapter 接到哪里、额外拿到什么观测数据」，接入分三级——每一级在上一级之上加一种投入、换一组新能力，已写的 eval 全程复用，不用改。
 
 ![接入分三个 Tier：Tier 1 只接 send 应用零改动；Tier 2 加 OTel 换 niceeval view 的调用瀑布图；Tier 3 侵入改造把变体暴露成 flags 做 A/B。](/images/adapter-tiers-zh.svg)
 
@@ -12,7 +12,7 @@ description: "按「Adapter 接到哪里、额外拿到什么观测数据」接
 
 应用代码一行不改，接入只有一个 Adapter 文件——`send` 对着用户前端本来就在用的那个接口收发。
 
-**全套断言都在这一档**：文本断言与 judge、结构化输出校验、多轮与会话隔离、HITL 审批流、事件映射给到的工具断言，以及 `send` 返回 usage 带来的用量断言——判决依据全部来自 `send` 返回的 `Turn`，后面两档不会再多出任何断言。应用接口本身暴露模型选择的话，**模型对比** experiment 也在这一档——experiment 的 `model` 经 `ctx.model` 传给 Adapter，随请求转发即可。
+**全套断言都在这一档**：文本断言与 judge、结构化输出校验、多轮与会话隔离、HITL 审批流、事件映射给到的工具断言，以及 `send` 返回 usage 带来的用量断言——判定依据全部来自 `send` 返回的 `Turn`，后面两档不会再多出任何断言。应用接口本身暴露模型选择的话，**模型对比** experiment 也在这一档——experiment 的 `model` 经 `ctx.model` 传给 Adapter，随请求转发即可。
 
 大多数团队从这里开始，很多也停在这里就够了。
 
@@ -34,7 +34,7 @@ description: "按「Adapter 接到哪里、额外拿到什么观测数据」接
 
 ## 怎么升级
 
-三档递进不互斥：先用 Tier 1 跑通基线和模型对比；要调用瀑布图，升 Tier 2；要对照应用内部变体，再升 Tier 3。每次升级都只是给 Adapter 或应用加东西，experiment 侧怎么组织对比见[实验](/zh/concepts/experiment)。
+三级递进不互斥：先用 Tier 1 跑通基线和模型对比；要调用瀑布图，升 Tier 2；要对照应用内部变体，再升 Tier 3。每次升级都只是给 Adapter 或应用加东西，experiment 侧怎么组织对比见[实验](/zh/concepts/experiment)。
 
 ## 相关阅读
 

package/docs-site/zh/example/claude-code-codex-plugin.mdx

@@ -6,12 +6,12 @@ description: "用 NiceEval 把 coding-agent 插件放进真实 workspace，比
 
 如果你在给 Claude Code、Codex 或其它 coding agent 写插件，最有价值的 eval 不是问它“会不会用插件”，而是把插件放进真实 workspace，让 agent 完成一组真实开发任务，再比较有插件和无插件时的 pass rate、耗时、成本和 diff。
 
-当前可运行示例在 [`examples/zh/coding-agent-skill`](https://github.com/CorrectRoadH/niceeval/tree/main/examples/zh/coding-agent-skill)。其中的 Ponytail 组就是一个插件 benchmark 迁移示例：把第三方 Ponytail skill/plugin 的 agentic benchmark 改写成 [NiceEval](https://niceeval.com/) eval，并与无插件 baseline 对比。
+当前可运行示例在 [coding-agent-skill](https://github.com/CorrectRoadH/coding-agent-skill)，一个独立仓库。其中的 Ponytail 组就是一个插件 benchmark 迁移示例：把第三方 Ponytail skill/plugin 的 agentic benchmark 改写成 [NiceEval](https://niceeval.com/) eval，并与无插件 baseline 对比。
 
 ## 目录结构
 
 ```text
-examples/zh/coding-agent-skill/
+coding-agent-skill/
 ├─ niceeval.config.ts
 ├─ skills/
 │  └─ ponytail.md
@@ -133,9 +133,13 @@ export default defineEval({
 ## 运行对比
 
 ```bash
-cd examples/zh/coding-agent-skill
+git clone https://github.com/CorrectRoadH/coding-agent-skill.git
+cd coding-agent-skill
 pnpm install
-pnpm exec niceeval exp ponytail ponytail-baseline
+pnpm exec niceeval exp ponytail-baseline
+pnpm exec niceeval exp caveman
+pnpm exec niceeval exp ponytail
+pnpm exec niceeval exp yagni-oneliner
 pnpm exec niceeval view
 ```
 
@@ -153,7 +157,7 @@ pnpm exec niceeval view
 
 ```text
 READ docs-site/zh/example/claude-code-codex-plugin.mdx and install niceeval for this repo.
-Use examples/zh/coding-agent-skill as the reference shape: put the plugin in skills/, inject it from an experiment setup hook, write one .eval.ts task against a real workspace, then add a no-plugin baseline experiment.
+Use https://github.com/CorrectRoadH/coding-agent-skill as the reference shape: put the plugin in skills/, inject it from an experiment setup hook, write one .eval.ts task against a real workspace, then add a no-plugin baseline experiment.
 ```
 
 ## 下一步

package/docs-site/zh/example/claude-code-codex-skill.mdx

@@ -6,7 +6,7 @@ description: "用 NiceEval 对比有 Skill 和无 Skill 的 coding-agent 任务
 
 Skill 的价值不只是“agent 最后答案对不对”，还包括它是否在正确场景遵循你的流程、是否避免反模式、是否稳定提升通过率、成本和耗时。[NiceEval](https://niceeval.com/) 的推荐做法是把 Skill 注入到 sandbox 里的真实 coding-agent 工作区，再与无 Skill baseline 对比。
 
-当前可运行示例在 [`examples/zh/coding-agent-skill`](https://github.com/CorrectRoadH/niceeval/tree/main/examples/zh/coding-agent-skill)。它包含两组实验：
+当前可运行示例在 [coding-agent-skill](https://github.com/CorrectRoadH/coding-agent-skill)，一个独立仓库。它包含两组实验：
 
 - Zod skill：自编写 `skills/zod.md`，验证 agent 是否用 Zod 做请求体和环境变量校验。
 - Ponytail plugin：迁移第三方 Ponytail benchmark，验证安全、复用和简洁性。
@@ -14,7 +14,7 @@ Skill 的价值不只是“agent 最后答案对不对”，还包括它是否
 ## 目录结构
 
 ```text
-examples/zh/coding-agent-skill/
+coding-agent-skill/
 ├─ skills/
 │  ├─ zod.md
 │  └─ ponytail.md
@@ -120,14 +120,19 @@ export default defineEval({
 ## 运行
 
 ```bash
-cd examples/zh/coding-agent-skill
+git clone https://github.com/CorrectRoadH/coding-agent-skill.git
+cd coding-agent-skill
 pnpm install
 
-# Zod skill A/B 对比
-pnpm exec niceeval exp compare
+# Zod skill A/B 对比(各是独立实验文件,不是同一个 group,分开跑)
+pnpm exec niceeval exp with-skill
+pnpm exec niceeval exp baseline
 
-# Ponytail plugin A/B 对比
-pnpm exec niceeval exp ponytail ponytail-baseline
+# Ponytail plugin:baseline / caveman / ponytail / yagni-oneliner 四臂对比
+pnpm exec niceeval exp ponytail-baseline
+pnpm exec niceeval exp caveman
+pnpm exec niceeval exp ponytail
+pnpm exec niceeval exp yagni-oneliner
 
 pnpm exec niceeval view
 ```