niceeval 0.6.1 → 0.7.0

package/dist/scoring/types.d.ts

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

package/dist/shared/aggregate.d.ts

@@ -16,12 +16,14 @@ export declare function displayExperimentName(id: string | undefined): string |
  */
 export declare function experimentGroupOf(experimentId: string): string | undefined;
 /**
- * eval id 前缀过滤,同 CLI 位置参数的分段语义(src/runner/discover.ts):
- * "algebra" 匹配自身与 "algebra/..." 子级,不误配 "algebra2";允许 "algebra/" 尾斜杠写法,等价。
+ * eval id 前缀过滤,同 CLI 位置参数语义(docs/feature/reports/show.md「打开与收窄」):
+ * eval 位置参数是收窄过滤,按**裸前缀宽松匹配**——"algebra" 命中 "algebra"、"algebra/..."
+ * 也命中 "algebra2",多命中正是它的用途(与 `--experiment` 的按路径段匹配有意不同)。
  */
 export declare function evalPrefixPredicate(evals?: string | string[]): (id: string) => boolean;
 /** 无 experimentId 时的兜底标签。 */
 export declare function fallbackExperimentLabel(result: {
+    experimentId?: string;
     experiment?: ExperimentRunInfo;
     agent: string;
     model?: string;

package/dist/shared/aggregate.js

@@ -1,4 +1,4 @@
-// CLI 表格(runner/reporters/table.ts)与 view 榜单(view/aggregate.ts)共用的聚合小工具。
+// report 聚合(report/aggregate.ts)与 view 榜单(view/app/lib/rows.ts)共用的聚合小工具。
 // 实验标签推导、token/成本求和、verdict 排序各只有一份 —— 否则同一个实验在终端和网页上
 // 会显示成两个名字 / 两组数。保持环境无关(纯函数,只 type import)。
 /** 明细行排序:失败最靠前(failed > errored > skipped > passed 的紧急程度)。 */
@@ -36,19 +36,20 @@ export function experimentGroupOf(experimentId) {
     return experimentId.split("/").slice(0, -1).join("/");
 }
 /**
- * eval id 前缀过滤,同 CLI 位置参数的分段语义(src/runner/discover.ts):
- * "algebra" 匹配自身与 "algebra/..." 子级,不误配 "algebra2";允许 "algebra/" 尾斜杠写法,等价。
+ * eval id 前缀过滤,同 CLI 位置参数语义(docs/feature/reports/show.md「打开与收窄」):
+ * eval 位置参数是收窄过滤,按**裸前缀宽松匹配**——"algebra" 命中 "algebra"、"algebra/..."
+ * 也命中 "algebra2",多命中正是它的用途(与 `--experiment` 的按路径段匹配有意不同)。
  */
 export function evalPrefixPredicate(evals) {
     if (evals === undefined)
         return () => true;
-    const prefixes = (Array.isArray(evals) ? evals : [evals]).map((p) => p.replace(/\/+$/, ""));
-    return (id) => prefixes.some((prefix) => id === prefix || id.startsWith(prefix + "/"));
+    const prefixes = Array.isArray(evals) ? evals : [evals];
+    return (id) => prefixes.some((prefix) => id.startsWith(prefix));
 }
 /** 无 experimentId 时的兜底标签。 */
 export function fallbackExperimentLabel(result) {
-    if (result.experiment?.id)
-        return displayExperimentName(result.experiment.id) ?? result.experiment.id;
+    if (result.experimentId)
+        return displayExperimentName(result.experimentId) ?? result.experimentId;
     if (result.model)
         return `${result.agent}/${result.model}`;
     return result.agent || "ad hoc run";

package/dist/shared/types.d.ts

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

package/dist/tty-line.d.ts

@@ -1,6 +1,2 @@
-/** 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/util.d.ts

@@ -10,6 +10,29 @@ export declare function stripComments(code: string): string;
  * `e instanceof Error ? e.message : String(e)`——那样用户永远看不出错误发生在哪一行。
  */
 export declare function formatThrown(e: unknown): string;
+/**
+ * 截到第一个换行为止。`formatThrown()` 优先带完整 `.stack`(含本地绝对文件路径的多行调用栈)
+ * 给需要按 file:line 定位问题的落盘产物(`EvalResult.error`、`niceeval show`);但机器消费的
+ * 单行 envelope(`FailureNotice.reason`、reporter 失败诊断的 `message`……)只要「一层可行动摘要」
+ * ——`Error.stack` 的第一行恒为 `name: message`,不含栈帧,直接满足这个要求。完整栈仍然原样
+ * 留在调用方各自的落盘字段里,这个函数只负责第二次、更短的那份表达,不是唯一出口。
+ */
+export declare function firstLine(text: string): string;
+/**
+ * 把 catch 到的 e 拆成 `AttemptError` 的三段:`message`(一层原因,Error.message,不带 name 前缀、
+ * 不拼 stack)、`stack`(完整多行栈,供 `niceeval show` 展开)、`cause`(沿 `e.cause` 取一层结构化
+ * 摘要 `{ name?, code?, message }`)。Node 的 `Error.stack` 不展开 cause 链,所以 cause 只能从
+ * `e.cause` 单独取。非 Error 值只给 message。
+ */
+export declare function describeError(e: unknown): {
+    message: string;
+    stack?: string;
+    cause?: {
+        name?: string;
+        code?: string;
+        message: string;
+    };
+};
 /** 零填充到 4 位(数据集扇出的 id:sql/0000)。 */
 export declare function pad4(n: number): string;
 /**

package/docs-site/zh/README.md

@@ -0,0 +1,44 @@
+# 中文公开文档信息架构
+
+`zh/` 按读者此刻的需求组织，不按 NiceEval 的内部模块组织。判断一页放在哪里时，先问读者是在学习、完成任务、查事实、理解原理，还是修复问题。
+
+## 五个正文分区
+
+| 目录 | 页面类型 | 读者要什么 | 本站边界 |
+| --- | --- | --- | --- |
+| `tutorials/` | Tutorial | 跟着一条安全路径拿到第一次成功 | 当前只有 `quickstart.mdx`。不为凑齐目录增加第二条入门路径 |
+| `how-to/` | How-to | 完成一个现实任务 | 标题用任务表述；步骤、验证方式和失败后的下一步要清楚 |
+| `explanation/` | Explanation | 理解概念、边界和运行原理 | 不承担完整操作步骤或字段罗列 |
+| `reference/` | Technical Reference | 快速查准确、完整的事实 | API 签名、字段、类型和 CLI flags 以源码为权威来源 |
+| `troubleshooting/` | Troubleshooting | 从可见症状定位并修复问题 | 按症状组织，不按内部模块组织 |
+
+`index.mdx` 和 `introduction.mdx` 是站点入口，不硬归入正文类型。`examples/` 是独立资源入口，不属于 Diátaxis 的四种正文类型。
+
+## Examples 的收录标准
+
+`examples/` 只收录有真实可运行源码的项目。一个案例页只回答四件事：被测对象是什么、这个项目证明什么、源码在哪里、怎么运行。操作步骤的通用版本链接 How-to，字段和配置全集链接 Reference，不在案例页复制。
+
+- 接入前后能从仓库源码计算时，由生成器产出 diff 页面，不手抄代码。
+- 同一个可运行项目只保留一张案例页。Skill、Plugin 等相邻主题共享实验设计时合并，不复制两份近似正文。
+- 只有一个条目的 Showcase 不单独成页，真实项目直接列在 `examples/index.mdx`。
+- 没有可运行源码、只有片段或设想的内容不进 Examples。片段进入对应 How-to，未实现方向留在 Roadmap。
+
+## Reference 的生成边界
+
+Technical Reference 不等于整页都由生成器拼出来。页面仍可手写短导语、最小示例和去往 How-to 的链接，但代码形状不能手抄：
+
+- `{/* GENERATED:BEGIN ... */}` 与 `{/* GENERATED:END ... */}` 之间的 API 成员、字段和 CLI flags 由 `pnpm docs:reference` 从源码紧邻注释生成。
+- 新增需要穷举的接口字段、函数、联合类型或 CLI flag 时，扩展 `scripts/generate-reference.ts` 的 region 映射，不在 MDX 里另写一份字段全集。
+- 能力矩阵、选择表和行为约束暂时由手写 Reference 承担；它们必须只描述当前实现，并避免重复已经生成的类型签名。
+- `reference/` 中没有生成区块的页面不因此成为 API 事实的第二来源。出现代码形状时，优先链接已有生成页；确实缺少生成入口时先补生成器。
+
+运行 `pnpm docs:reference` 后，生成器只改 `zh/reference/` 中已登记的 region。`test/reference-consistency.test.ts` 会拦截源码与生成区块的漂移。
+
+## 当前页面归类
+
+- `explanation/runner.mdx` 解释执行引擎如何发现、调度、缓存和产出结果，不是一步一任务的操作指南。
+- `reference/official-adapters.mdx`、`reference/report-components.mdx` 和 `reference/results-data.mdx` 用于查能力、组件或数据 API，不能留在 How-to。
+- `troubleshooting/debugging.mdx` 与 `troubleshooting/debug-sandbox.mdx` 从失败症状出发，目录独立，在导航中归入 How-to Guides。
+- `how-to/sandbox-providers.mdx` 目前保留在 How-to，因为主问题是选择并配置 Provider；若以后字段表继续增长，再拆出独立 Provider Reference。
+
+新增或移动页面时，同时更新 `docs-site/docs.json` 和旧路径 redirect。校验命令以 [`../AGENTS.md`](../AGENTS.md) 为准。

package/docs-site/zh/examples/ai-agent-application.mdx

@@ -0,0 +1,63 @@
+---
+title: "自写 Adapter 评估 AI Agent 应用"
+sidebarTitle: "AI Agent 应用"
+description: "一个可运行的 AI SDK v6 Web Agent 评测项目，覆盖自写 Adapter、工具调用、图片理解、多轮会话、模型对比和双路可观测。"
+---
+
+这个项目演示如何用 `defineAgent` 把已有 HTTP Agent 接入 NiceEval。它适合需要控制自有协议和事件映射的应用。
+
+- [查看完整源码](https://github.com/CorrectRoadH/niceeval/tree/main/examples/zh/ai-sdk)
+- 本地目录：`examples/zh/ai-sdk/`
+
+<Note>
+  如果应用使用 AI SDK v7 的 UI Message Stream，优先使用内置 `uiMessageStreamAgent`。对应的无侵入示例见 [AI SDK v7](/zh/examples/integrations/ai-sdk-v7)。
+</Note>
+
+## 这个项目证明什么
+
+| 部分 | 实现 |
+| --- | --- |
+| 被测应用 | AI SDK v6 Web Agent，HTTP `POST /api/turn` |
+| Adapter | `defineAgent` + 自定义 `AgentEvent` → `StreamEvent` 映射 |
+| Eval | 天气工具、图片理解、多轮文本、多轮图片上下文 |
+| Experiment | 每个文件固定一个模型，同组比较 DeepSeek 与 GPT |
+| 可观测 | 应用继续上报 Langfuse，同时把本轮 OTLP 数据发给 NiceEval |
+
+Adapter 只负责连接和翻译。URL 与模型属于 Experiment；Eval 只描述交互与好结果。这个分层让同一批 Eval 可以复用到不同模型和部署实例。
+
+## 目录
+
+```text
+examples/zh/ai-sdk/
+├── src/                     # 被测 Web Agent
+├── adapter/adapter.ts       # 自写 NiceEval Adapter
+├── evals/                   # 工具、图片和多轮 Eval
+├── experiments/             # 模型对比
+└── niceeval.config.ts
+```
+
+## 跑起来
+
+这个示例调用真实模型，没有 Mock 模式。先复制环境变量并填入 OpenAI 兼容服务的凭据：
+
+```bash
+cd examples/zh/ai-sdk
+pnpm install
+cp .env.example .env
+pnpm dev
+```
+
+另开一个终端运行：
+
+```bash
+cd examples/zh/ai-sdk
+pnpm exec niceeval list
+pnpm exec niceeval exp compare-models weather-tool
+pnpm exec niceeval view
+```
+
+## 继续阅读
+
+- [接入你的 Agent](/zh/how-to/connect-your-agent)：从最小 Adapter 开始接入自己的协议。
+- [如何写好 Send](/zh/how-to/write-send)：逐步补齐会话、工具、HITL 和 OTel。
+- [实验矩阵](/zh/how-to/experiments)：组织模型和配置对比。

package/docs-site/zh/examples/coding-agent-extensions.mdx

@@ -0,0 +1,57 @@
+---
+title: "评估 Coding Agent 扩展"
+sidebarTitle: "Coding Agent 扩展"
+description: "用真实 Workspace、基线实验和自定义报告，评估 Skill、提示词与 Plugin Benchmark 是否改善 Coding Agent 的任务结果。"
+---
+
+这个案例把扩展内容作为 Experiment 变量，让同一个 Coding Agent 在同一批真实开发任务上运行，再比较任务成功率、成本、耗时和行为差异。
+
+- [查看完整源码](https://github.com/CorrectRoadH/coding-agent-skill)
+- [查看 Fixtures 指南](/zh/how-to/fixtures)
+
+## 两组实验
+
+| 实验 | 对照 | 测什么 |
+| --- | --- | --- |
+| Zod Skill | `with-skill` vs `baseline` | Skill 是否让 Agent 稳定使用 `z.object().safeParse()`，而不是退回手写校验 |
+| Ponytail Benchmark | Baseline / Caveman / Ponytail / YAGNI One-liner | 完整决策 Skill 是否比裸 Agent、简短风格 Skill 或一句提示更有效 |
+
+Ponytail 这一组迁移自第三方 Plugin 的 Agentic Benchmark，但这个仓库实际比较的是注入给 Agent 的内容与提示。它不用于证明某个原生 Plugin 包装或安装协议是否正确。原生 Skill / Plugin 的安装配置见 [官方适配器](/zh/reference/official-adapters)。
+
+## 实验设计
+
+每个 Arm 固定相同的模型、Sandbox、任务集、Runs 和预算，只改变注入内容。Eval 不读取“当前是哪个 Arm”，也不为实验组降低验收标准。
+
+```text
+coding-agent-skill/
+├── skills/                  # 各 Arm 注入的内容
+├── workspaces/ts-starter/   # 每个 Eval 的初始项目
+├── evals/                   # 真实开发任务与验证
+├── experiments/             # Baseline 和实验 Arm
+└── reports/benchmark.tsx    # Arm × Metric 自定义报告
+```
+
+验证优先看最终产物：项目测试、隐藏探针、源码和 Diff。只有事件稳定且完整时，才把 Skill Load 或工具调用作为 Gate。
+
+## 跑起来
+
+```bash
+git clone https://github.com/CorrectRoadH/coding-agent-skill.git
+cd coding-agent-skill
+pnpm install
+cp .env.example .env
+docker info
+
+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 --report reports/benchmark.tsx
+```
+
+## 从这个案例复用什么
+
+- 用 Experiment 表达有扩展和无扩展的对照，不让 Eval 知道实验条件。
+- Prompt 不泄露答案；验证阶段再检查测试、源码、Diff 和行为证据。
+- 把任务成功率作为主指标，把 Token、成本、耗时和行为作为解释指标。
+- [评分指南](/zh/how-to/scoring-guide) 负责选择 Gate、Soft 和 Judge；本页不复制评分 API。

package/docs-site/zh/examples/index.mdx

@@ -0,0 +1,50 @@
+---
+title: "NiceEval Examples"
+sidebarTitle: "选择示例"
+description: "按被测对象选择可运行的 NiceEval 示例：Agent Framework 接入、完整 AI Agent 评测、Coding Agent 扩展 benchmark 和真实项目。"
+---
+
+这里的每个示例都有真实可运行源码。先按被测对象选择，不必从头依次阅读。
+
+如果你还没有跑通过第一条 Eval，先读 [Quickstart](/zh/tutorials/quickstart)。如果你已经知道要完成什么，直接进入对应的 [How-to Guides](/zh/how-to/connect-your-agent)。
+
+## 接入已有 Agent Framework
+
+下面五组示例都保留接入前的普通应用和接入 NiceEval 后的完整项目。页面中的代码 diff 从这两份源码生成。
+
+| 被测对象 | 接入方式 | 示例覆盖 |
+| --- | --- | --- |
+| [AI SDK v7](/zh/examples/integrations/ai-sdk-v7) | 内置 `uiMessageStreamAgent` | UI Message Stream、多轮、工具、HITL |
+| [Claude Agent SDK](/zh/examples/integrations/claude-sdk) | `fromClaudeSdkMessages` | 原生事件流、多轮、工具、HITL |
+| [Codex SDK](/zh/examples/integrations/codex-sdk) | `fromCodexThreadEvents` | 编码任务、文件和命令、usage；SDK 不支持 HITL |
+| [pi-agent-core](/zh/examples/integrations/pi-sdk) | `fromPiAgentEvents` | 原生事件流、多轮、工具、HITL；SDK 没有 OTel |
+| [LangGraph](/zh/examples/integrations/langgraph) | 手写自定义 SSE 帧映射 | Python 应用、多轮、工具、HITL |
+
+每组源码都位于 [`examples/zh/origin/`](https://github.com/CorrectRoadH/niceeval/tree/main/examples/zh/origin) 和 [`examples/zh/tier1/`](https://github.com/CorrectRoadH/niceeval/tree/main/examples/zh/tier1)。需要 OTel 或 Experiment Flags 时，再沿相同项目进入 `tier2/` 和 `tier3/`。
+
+## 完整评测项目
+
+<CardGroup cols={2}>
+  <Card title="自写 Adapter 评估 AI Agent 应用" icon="robot" href="/zh/examples/ai-agent-application">
+    一个 AI SDK v6 Web Agent，覆盖工具调用、图片理解、多轮会话、模型对比和双路可观测。
+  </Card>
+  <Card title="评估 Coding Agent 扩展" icon="wand-magic-sparkles" href="/zh/examples/coding-agent-extensions">
+    用真实 Workspace 和对照实验衡量 Skill、提示词与 Plugin Benchmark 对任务结果的影响。
+  </Card>
+</CardGroup>
+
+## 真实项目
+
+### Coding Agent Memory Evals
+
+[coding-agent-memory-evals](https://github.com/CorrectRoadH/coding-agent-memory-evals) 用同一批开发任务和同一个模型，对比 Coding Agent 是否带持久记忆时的任务成功率、成本、耗时和行为差异。
+
+- [查看在线报告](https://niceeval.com/showcase/memory)
+- [查看项目源码](https://github.com/CorrectRoadH/coding-agent-memory-evals)
+
+## 什么不放在 Examples
+
+- 单段 API 用法放进 How-to 或 Reference。
+- 没有可运行源码的伪项目不收录。
+- Roadmap 和尚未实现的接入不收录。
+- 同一个项目不为 Skill、Plugin、Hook 等相邻叫法复制多张案例页。

package/docs-site/zh/{concepts → explanation}/adapter.mdx

@@ -6,7 +6,7 @@ description: "Adapter 是你写的适配器。本文讲清楚 send 函数传入
 
 在 [NiceEval](https://niceeval.com/) 里，`Adapter` 是连接运行器和被测系统的适配层。Adapter 需要实现 `send` 函数：把 `t.send()` 等 eval 侧动作发给你的应用，再把应用返回翻译成 [NiceEval](https://niceeval.com/) 的标准 `Turn`。
 
-后续阅读[写 send](/zh/guides/write-send)
+后续阅读[写 send](/zh/how-to/write-send)
 
 ## 适配器
 如果被测系统使用标准的 OpenAI Chat Completions 或 Responses 协议，可以直接用官方适配器。自己实现的前后端协议（HTTP、gRPC、WebSocket 都行）则写一个 Adapter：它知道怎么鉴权、怎么调用你的应用、怎么把返回翻译成标准事件流。
@@ -37,6 +37,7 @@ export function webAgent(options: WebAgentOptions): Agent {
   return defineAgent({
     name: "web-agent",
     async send(input, ctx) {
+      ctx.progress({ message: "等待 Web Agent" });
       const response = await fetch(`${baseUrl}/api/turn`, {
         method: "POST",
         headers: {
@@ -54,6 +55,12 @@ export function webAgent(options: WebAgentOptions): Agent {
       });
 
       if (!response.ok) {
+        ctx.diagnostic({
+          code: "agent-http-error",
+          level: "error",
+          message: `Web Agent 返回 HTTP ${response.status}`,
+          data: { status: response.status },
+        });
         return {
           status: "failed",
           events: [{ type: "error", message: `HTTP ${response.status}` }],
@@ -87,12 +94,12 @@ export default defineExperiment({
 
 ## 接入等级
 
-按「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/explanation/tier)。
 
 eval 侧的驱动 API——`t.send()`、`t.sendFile()`、`t.newSession()`、HITL 的 `t.respond()` / `t.respondAll()`
 统一都是调用 Adapter 的 `send`。
 
-怎么收敛、send 里怎么接，见[写 send](/zh/guides/write-send)。
+怎么收敛、send 里怎么接，见[写 send](/zh/how-to/write-send)。
 
 ## send 函数
 
@@ -107,10 +114,12 @@ interface Agent {
 }
 ```
 
+`progress` 是运行中的短期状态，不落盘；`diagnostic` 是需要运行后回顾的有界 warning/error，会随 Attempt 保存。它们都不能指定 lifecycle phase，也不会自动改变 `Turn.status`。连接失败或响应无法解析时抛出异常；runner 会把它记录为 `errored`，并在终端给出可下钻的 locator。
+
 `send` 是唯一要实现的函数。它的签名里只有三个类型，分开看。
 
 <Note>
-  这里的 `setup` / `teardown` 是 Agent 自己"怎么连自己"的私事（装 CLI、写鉴权配置）。按实验变化的环境准备（装某个实验专属的二进制、预热、跨 attempt 保存状态）不写在 Agent 上，挂在 `sandbox` 字段那个 Sandbox spec 自己的 `.setup()` / `.teardown()` 链式方法上，见 [Sandbox 后端 · 环境钩子](/zh/guides/sandbox-providers#环境钩子)。
+  这里的 `setup` / `teardown` 是 Agent 自己"怎么连自己"的私事（装 CLI、写鉴权配置）。按实验变化的环境准备（装某个实验专属的二进制、预热、跨 attempt 保存状态）不写在 Agent 上，挂在 `sandbox` 字段那个 Sandbox spec 自己的 `.setup()` / `.teardown()` 链式方法上，见 [沙箱 provider · 环境钩子](/zh/how-to/sandbox-providers#环境钩子)。
 </Note>
 
 ### 传入：`TurnInput`
@@ -182,10 +191,17 @@ Adapter 侧的对应义务：按 `requestId` 把裁决交回应用（不要按
 
 ```ts
 interface AgentContext {
-  // 每轮都在的三个
+  // 每轮都在的反馈与运行上下文
   readonly signal: AbortSignal;    // 运行器的超时与取消：透传给你发出的每个请求
   readonly session: AgentSession;  // 本条会话线的状态槽
-  log(msg: string): void;          // 写进本轮日志，niceeval view 里可见
+  progress(update: { message: string; current?: number; total?: number }): void;
+  diagnostic(input: {
+    code: string;
+    level: "warning" | "error";
+    message: string;
+    data?: Readonly<Record<string, JsonValue>>;
+    dedupeKey?: string;
+  }): void;
 
   // 按接入档位出现的三个（见「接入分三个 Tier」）
   readonly model?: string;         // Tier 1 的模型对比：experiment.model 透传；应用接口收模型选择就转发
@@ -214,7 +230,9 @@ 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-providers#环境钩子)。
+Runner 为 Agent 的 `setup`、每次 `send` 和 `teardown` 分别绑定 lifecycle scope。Adapter 只报告当前回调内部的 progress/diagnostic，不能传 phase、颜色或输出流。`progress` 不落盘；diagnostic 会进入 Attempt 的 `result.json`。无法继续时抛错，由 runner 保存结构化 error 并把 Attempt 标为 `errored`。
+
+`ctx` 里没有要你检查的标志位。三个档位字段都是"透传"语义：`model`、`flags` 由 experiment 声明、运行器原样递过来，Adapter 只负责随请求转发给应用，不解释它们的含义；`telemetry` 仅在配置了 OTel 接入时出现，`send` 里只需要把 `headers` spread 进请求头——接收端点在 `defineConfig` 里固定、由应用启动时指向，不从这里传，见[OTel 接入](/zh/how-to/connect-otel)。`experimentId` 是路径推导出的稳定标识，典型用途是在 Sandbox 的环境钩子里按实验隔离跨 attempt 的状态（缓存目录名、沙箱快照 tag 按它分区），见 [沙箱 provider · 环境钩子](/zh/how-to/sandbox-providers#环境钩子)。
 
 `session` 是本条会话线的自有状态，[NiceEval](https://niceeval.com/) 对它只承诺一件事：**同一条会话线的每次 `send` 拿到同一个 `ctx.session`，新会话线（eval 的第一轮，或 `t.newSession()` 之后）拿到一个全新的。** 会话续接（`id`/`capture`、`history`）和 HITL 停轮现场（`hold`/`take`）的存取器都在它上面，"第一轮"就是新会话线的自然形态——`id` 是 `undefined`、`history.get()` 是空数组，没有要判断的分支；`state` 是这些存取器之外的逃生舱，框架从不往里写数据。
 
@@ -239,7 +257,7 @@ interface Turn {
 ]
 ```
 
-对象统共十种类型（`message`、`action.*`、`input.requested`……完整清单见[事件流参考](/zh/reference/events)）。断言读的就是这个数组：`t.calledTool("get_weather")` 数 `action.called`，`t.reply` 取最后一条 assistant `message`。注意 `send` 每次只返回**本轮**的数组——跨轮拼成整条会话线是运行器的事，见下一节。多数情况下你也不手写这些对象：官方转换器的返回值就是一个填好 `events`、`usage`、`status` 的完整 `Turn`，怎么选转换器见[写 send](/zh/guides/write-send)。
+对象统共十种类型（`message`、`action.*`、`input.requested`……完整清单见[事件流参考](/zh/reference/events)）。断言读的就是这个数组：`t.calledTool("get_weather")` 数 `action.called`，`t.reply` 取最后一条 assistant `message`。注意 `send` 每次只返回**本轮**的数组——跨轮拼成整条会话线是运行器的事，见下一节。多数情况下你也不手写这些对象：官方转换器的返回值就是一个填好 `events`、`usage`、`status` 的完整 `Turn`，怎么选转换器见[写 send](/zh/how-to/write-send)。
 
 `data` 不是"随便放点什么"的口袋，它只有一条规则：**要什么，由 eval 在 send 上用 schema 声明；声明了才有 data，拿到手就是声明的类型。**
 
@@ -284,8 +302,8 @@ turn.data.amount;   // 类型是 number——不是 unknown，不用手动收窄
 
 ## 相关阅读
 
-- [写 send](/zh/guides/write-send) — 实操教程：从发一条消息到完整接入，七步递进，每步解锁一组断言。
-- [接入你的 Agent](/zh/guides/connect-your-agent) — 接入全景：最小接入、参数通道与增量地图。
-- [Drive](/zh/concepts/drive) — eval 侧视角：`t.send()`、`t.newSession()` 与 HITL 怎么用。
-- [Assert](/zh/concepts/assert) — 标准事件流驱动的完整断言词汇。
-- [架构概览](/zh/concepts/overview) — 四层架构和边界。
+- [写 send](/zh/how-to/write-send) — 实操教程：从发一条消息到完整接入，七步递进，每步解锁一组断言。
+- [接入你的 Agent](/zh/how-to/connect-your-agent) — 接入全景：最小接入、参数通道与增量地图。
+- [Drive](/zh/explanation/drive) — eval 侧视角：`t.send()`、`t.newSession()` 与 HITL 怎么用。
+- [Assert](/zh/explanation/assert) — 标准事件流驱动的完整断言词汇。
+- [架构概览](/zh/explanation/overview) — 四层架构和边界。