niceeval 0.4.6 → 0.5.0

package/docs-site/docs-ref/01-page-types.md

@@ -1,43 +0,0 @@
-# 第一步:判定页面类型
-
-蒸馏自 [01-diataxis-divio.md](../dev-docs-dx-sources/01-diataxis-divio.md)、[06-good-docs-project.md](../dev-docs-dx-sources/06-good-docs-project.md)。
-
-## 核心规则
-
-动笔前先回答:**这页服务读者的哪种需求——学习、干活、查事实,还是理解?**
-
-| 类型 | 读者需求 | 一句话定义 |
-| --- | --- | --- |
-| Tutorial | 学习 | 带用户安全地完成第一次成功,建立信心和心智模型 |
-| How-to | 干活 | 帮已有基础的用户完成一个现实任务 |
-| Reference | 查事实 | 准确、完整、低解释负担地描述字段、命令、类型 |
-| Explanation (Concept) | 理解 | 解释概念边界、背景、取舍和"为什么" |
-| Troubleshooting | 修复 | 按症状定位原因并给出解决步骤 |
-
-如果一个页面同时承担两种以上主要目标,**优先拆页**,不要加小标题硬塞。
-
-## NiceEval 目录映射
-
-- `quickstart`:Tutorial。只保留一条最短成功路径。
-- `guides/*`:How-to。一个页面解决一个任务。
-- `concepts/*`:Explanation。解释核心心智模型和概念边界。
-- `reference/*`:Reference。只列当前实现支持的事实。
-- `troubleshooting/*`(未来):按症状组织排错。
-- `example` / `examples/*`:真实可运行例子,不承担完整解释。
-
-## 每种类型的典型越界(写之前自查)
-
-- Tutorial 不要变成 API 字段大全,不要展示全部选项和复杂边界。
-- How-to 不要教零基础概念,不要写成长篇设计说明。
-- Reference 不要混入 onboarding 叙事,不要写未实现字段或 roadmap。
-- Explanation 不要伪装成操作步骤,不要写成内部设计流水账。
-- Concept 页要写"它不是什么",防止用户把相邻层次混在一起(例如 Adapter 和 Sandbox)。
-
-## 检查问题
-
-- 这页是在服务学习、工作、查事实,还是理解?
-- 页面是否同时承担了两种以上主要目标?
-- 如果是 Tutorial,用户能否安全地拿到第一次成功?
-- 如果是 How-to,读完能否完成一个具体任务?
-- 如果是 Reference,信息是否完整、准确、无叙事打断?
-- 如果是 Explanation,是否真的解释了边界和原因,而不是在重复操作步骤?

package/docs-site/docs-ref/03-style-rules.md

@@ -1,45 +0,0 @@
-# 第三步:行文规则
-
-## 语气与句法
-
-- 第二人称,直接对读者说话;主动语态,动作主体明确。
-- 短句。一段一个想法,一句一个主要信息。
-- 对话式但不轻浮;直接帮用户完成任务,不要营销式铺垫。
-- 不解释开发者已知的基础常识(一般的 TypeScript、Node.js、CLI 用法),除非 NiceEval 依赖某个不明显细节。
-- 删掉"下面我们将会""值得注意的是"这类预告式和填充式表达,直接说要完成什么。
-- 命令、路径、flag、文件名、包名、代码标识一律用反引号(术语用法见 `docs-site/AGENTS.md` 术语表)。
-
-## 步骤写作
-
-- 步骤为完成任务服务,用编号列表;单步任务不要硬写成编号流程。
-- 引导句提供上下文,不要只重复标题。
-- 一步一个主要动作。
-- 先说在哪里操作,再说做什么;条件放在动作前面("如果要 X,先运行 Y",不是"运行 Y,如果你要 X")。
-- 可选步骤用 `Optional:` / "可选:" 明确标注。
-- 多种做法并存时,先写最短、最简单的默认路径;变体放独立小节或独立页面,不要在主路径里分叉。
-- 最好的步骤是用户不需要读的步骤:如果 CLI 输出或错误信息能自解释,优先改进它们,再考虑补文档。
-
-## 可扫描性
-
-多数读者在扫描,不在通读:
-
-- 重要信息放页面前 1/3。
-- 小标题要有信息量,读者只看标题也能定位内容。
-- 列表、表格、代码块、提示块合理分隔正文。
-- 强调(加粗等)只用于真正重要的信息,滥用等于没有。
-- 链接文字要有描述性,不写"点击这里"。
-
-## 标题与搜索意图
-
-- 搜索是用户进入文档的主要入口。标题、description、正文要用**用户会搜索的词**,不是内部功能名——"连接远程 Agent"比"Adapter primitives"更适合作任务页标题。
-- 每篇文章一个清晰、离散的主题。
-- 重命名或移动页面时维护 redirect,避免旧链接失效。
-
-## 内容边界与重复
-
-- "刚好足够"优于穷举:优先高影响、高价值场景,不为完整性堆低频分支。
-- ARID,不是 DRY:文档允许适度重复关键上下文,不要为消灭重复迫使读者跨三页拼信息。但**同一事实的权威来源只有一处**,其他地方链接过去——docs-site、README、示例、CLI help 之间要有清晰边界,避免同一能力多处漂移。
-- 一旦选择覆盖某类信息就覆盖完整;只做部分覆盖时要明说。
-- FAQ 不是信息架构:真实高频问题应沉淀为 guide、reference 或 troubleshooting 页。
-- 内容要可精确链接(addressable):重要段落有稳定的标题锚点,方便从错误信息、报告和其它页面直链。
-- 先讲前置概念,再讲依赖它的内容(cumulative)。

package/docs-site/docs-ref/04-code-examples.md

@@ -1,37 +0,0 @@
-# 第四步:代码示例规则
-
-## 写示例前
-
-- **先真实跑过。** 写 reference 或示例前,实际运行过这个 API / 命令,而不是从类型定义或设计稿抄字段。这是 MDN 和 I'd Rather Be Writing 共同的第一条规则。
-- 知道这个 API 最常见的使用路径,示例展示的应该是它,不是罕见变体。
-
-## 示例的结构
-
-按"目的 → 代码 → 解释 → 结果"组织:
-
-1. 代码块前一句话说明整体目的(它完成什么任务,不是逐行复述)。
-2. 代码使用真实导入路径、真实文件名;能被复制运行。
-3. 占位符(`<your-agent-url>` 之类)逐个解释清楚。
-4. 如果输出影响读者判断,展示或描述期望输出。
-
-## 注释
-
-- 注释解释关键行的作用和**为什么这样写**,不假设读者知道示例为什么长这样。
-- 注释增加复杂度,只在确有必要时用;短示例配好前置说明通常不需要行内注释。
-
-## 输入与输出成对
-
-发送/调用类 API 的示例要同时有 request / input 示例和 response / output 示例。只给输入不给输出,读者无法验证自己跑对了。
-
-## Reference 与示例互相补足
-
-- Reference 讲字段、类型、默认值;示例讲具体用法。只有其一都不完整。
-- 每个 reference 页配至少一个短示例;每个示例链接回字段细节所在的 reference。
-
-## 维护义务
-
-- 示例随 API 更新维护:改 API 时必须同步检查所有相关示例、注释、描述和链接。
-- 过期示例比没有示例更危险,发现后优先修正或删除。
-- 一页里多个相似示例考虑合并,减少读者负担。
-- 新旧写法都有效时,明确记录差异,不要让读者猜哪个是现在的推荐。
-- 文档链接示例目录时必须指向真实存在的路径(当前完整示例在 `examples/zh/`)。

package/docs-site/docs-ref/05-dx-failure-paths.md

@@ -1,45 +0,0 @@
-# 第五步:失败路径与 DX 视角
-
-## 文档是 DX 系统的一部分
-
-文档不是孤立内容资产。错误信息、CLI 输出、报告页、示例、CHANGELOG、迁移指南都在承担文档职责。写一页文档前先问:**这页降低了哪类开发者摩擦?这个摩擦是不是该由 CLI 输出或错误信息解决?**
-
-- 报错即文档:错误信息应链接到可操作说明,并给出下一步。
-- 能用更好的 CLI 输出、默认值或自动化解决的问题,优先改产品,再补文档。
-- 测试用例和可运行示例也是用户理解用法的资料。
-
-## 覆盖失败路径,不只是成功路径
-
-用户第一次失败后能否自助修复,是文档质量的核心指标。NiceEval 文档要覆盖的失败类别:
-
-- setup 失败。
-- adapter 连接失败。
-- sandbox / runtime 失败。
-- eval assertion 失败。
-- judge 失败。
-- report / view 失败。
-
-每类失败都要告诉用户五件事:
-
-1. 现象(用户看到什么)。
-2. 看哪个 artifact。
-3. 运行哪个命令。
-4. 常见原因。
-5. 下一步。
-
-## 可预测性:结构一致是一种功能
-
-Twilio 的 DX 光谱里,比"能跑通"更高的目标是"可预测":同类页面结构一致,用户熟悉一个 adapter 的文档后,能零成本迁移到另一个 adapter 的文档,知道信息在哪个位置。所以:
-
-- 同类型页面用同一骨架(见 [02-page-skeletons.md](./02-page-skeletons.md)),不要每页自创结构。
-- 概念(Agent / Adapter / Sandbox / Turn)的解释要让用户能**预测系统行为**,不只是背定义。
-
-## 衡量文档好坏的信号
-
-写作和评审时可以对照:
-
-- Time to first successful eval 是否被 quickstart 缩短。
-- 反复出现的用户问题是否有对应文档页。
-- 文档能否从错误信息、报告、CLI 输出、README 到达。
-- 文档与产品实际行为是否一致——不一致按 Twilio 的标准就是 Broken。
-- 同一问题在 Slack / issue 里反复出现、新人 onboarding 慢、PR 因缺上下文变慢,都是文档缺口的组织信号。

package/docs-site/docs-ref/06-checklists.md

@@ -1,53 +0,0 @@
-# 第六步:检查清单
-
-## 动笔前
-
-- [ ] 谁会读这页?他们要完成什么?读完应该能做什么或理解什么?
-- [ ] 页面类型判定了吗(Tutorial / How-to / Reference / Explanation / Troubleshooting)?
-- [ ] 是否已实际跑过要写的命令、API 或示例?
-- [ ] 声明的每个能力、字段、路径,是否对当前代码或 `docs/` 核实过?
-- [ ] 这个信息的权威来源是否已存在于别处?如果是,链接过去而不是复制。
-
-## 按类型
-
-**Tutorial / Quickstart**
-
-- [ ] 只有一条最短成功路径,没有分叉。
-- [ ] 每步有明确反馈,用户知道自己成功了。
-- [ ] 没有混入字段大全和概念长文。
-
-**How-to**
-
-- [ ] 一页只解决一个任务;标题匹配用户会搜索的词。
-- [ ] 步骤按"动作 → 命令 → 占位符 → 期望输出 → 失败时下一步"组织。
-- [ ] 有"验证结果"和"常见失败"小节。
-
-**Reference**
-
-- [ ] 字段、类型、默认值、必填性完整。
-- [ ] 没有未实现字段、roadmap 或叙事化教学。
-- [ ] 有短示例并链接到对应 guide。
-
-**Concept**
-
-- [ ] 写了"它不是什么",和相邻概念划清边界。
-- [ ] 没有变成操作步骤或内部设计流水账。
-
-**Troubleshooting**
-
-- [ ] 症状、原因、检查步骤、解决办法齐全。
-- [ ] 按用户可见症状组织,不按内部模块。
-
-## 发布前
-
-- [ ] 重要信息在页面前 1/3;第一屏能判断相关性。
-- [ ] 每个步骤一个动作;条件在动作前;可选步骤已标注。
-- [ ] 代码相关文本用反引号;链接文字有描述性。
-- [ ] 示例可复制运行,导入路径真实,输出已展示或说明。
-- [ ] 改动涉及的其它入口(README、示例、英文/中文对应页)已同步或明确留待同步。
-- [ ] 新增/重命名页面已更新 `docs.json`,旧链接加了 redirect。
-- [ ] 跑过 `docs:validate` 和 `docs:links`(命令见 `docs-site/AGENTS.md`)。
-
-## 只改 `docs-ref/` 内部参考时
-
-不进导航,不需要跑 Mintlify 校验,但至少检查:文件路径正确、相对链接可达、没有把内部草稿写成正式产品承诺。

package/docs-site/docs.json

@@ -1,256 +0,0 @@
-{
-  "$schema": "https://mintlify.com/docs.json",
-  "name": "niceeval",
-  "theme": "luma",
-  "favicon": "/favicon.svg",
-  "logo": {
-    "light": "/images/logo.svg",
-    "dark": "/images/logo.svg"
-  },
-  "colors": {
-    "primary": "#848c8e",
-    "light": "#11161e",
-    "dark": "#cfd0d2"
-  },
-  "navbar": {
-    "primary": {
-      "type": "github",
-      "href": "https://github.com/CorrectRoadH/niceeval"
-    }
-  },
-  "redirects": [
-    {
-      "source": "/concepts/scoring",
-      "destination": "/concepts/assert"
-    },
-    {
-      "source": "/concepts/agents-adapters",
-      "destination": "/concepts/adapter"
-    },
-    {
-      "source": "/guides/connect-agent",
-      "destination": "/guides/connect-your-agent"
-    },
-    {
-      "source": "/concepts/write-send",
-      "destination": "/guides/write-send"
-    },
-    {
-      "source": "/zh/concepts/scoring",
-      "destination": "/zh/concepts/assert"
-    },
-    {
-      "source": "/zh/concepts/agents-adapters",
-      "destination": "/zh/concepts/adapter"
-    },
-    {
-      "source": "/zh/concepts/write-send",
-      "destination": "/zh/guides/write-send"
-    },
-    {
-      "source": "/reference/configuration",
-      "destination": "/reference/define-config"
-    },
-    {
-      "source": "/zh/reference/configuration",
-      "destination": "/zh/reference/define-config"
-    },
-    {
-      "source": "/zh/example/eval-multil-turn-for-your-agent",
-      "destination": "/zh/concepts/drive"
-    }
-  ],
-  "navigation": {
-    "languages": [
-      {
-        "language": "en",
-        "default": true,
-        "tabs": [
-          {
-            "tab": "Documentation",
-            "groups": [
-              {
-                "group": "Get Started",
-                "pages": [
-                  "introduction",
-                  "quickstart"
-                ]
-              },
-              {
-                "group": "Core Concepts",
-                "pages": [
-                  "concepts/overview",
-                  "concepts/evals",
-                  "concepts/experiment",
-                  "concepts/adapter",
-                  "concepts/tier",
-                  "concepts/drive",
-                  "concepts/hitl",
-                  "concepts/assert",
-                  "concepts/judge"
-                ]
-              },
-              {
-                "group": "Connecting Agents",
-                "pages": [
-                  "guides/connect-your-agent",
-                  "guides/write-send",
-                  "guides/connect-otel",
-                  "guides/sandbox-agent",
-                  "guides/sandbox-backends"
-                ]
-              },
-              {
-                "group": "Evals & Experiments",
-                "pages": [
-                  "guides/authoring",
-                  "guides/write-experiment",
-                  "guides/experiments",
-                  "guides/fixtures",
-                  "guides/dataset-fanout",
-                  "guides/scoring-guide"
-                ]
-              },
-              {
-                "group": "Examples",
-                "pages": [
-                  "example/claude-code-codex-plugin",
-                  "example/claude-code-codex-skill",
-                  "example/ai-agent-application",
-                  "example/showcase"
-                ]
-              },
-              {
-                "group": "Running & Observing",
-                "pages": [
-                  "guides/runner",
-                  "guides/ci-integration",
-                  "guides/reporters",
-                  "guides/viewing-results"
-                ]
-              }
-            ]
-          },
-          {
-            "tab": "Reference",
-            "groups": [
-              {
-                "group": "API",
-                "pages": [
-                  "reference/define-eval",
-                  "reference/define-agent",
-                  "reference/events",
-                  "reference/capabilities",
-                  "reference/builtin-agents",
-                  "reference/define-config",
-                  "reference/expect"
-                ]
-              },
-              {
-                "group": "CLI",
-                "pages": [
-                  "reference/cli"
-                ]
-              }
-            ]
-          }
-        ]
-      },
-      {
-        "language": "zh-Hans",
-        "tabs": [
-          {
-            "tab": "文档",
-            "groups": [
-              {
-                "group": "开始使用",
-                "pages": [
-                  "zh/introduction",
-                  "zh/quickstart"
-                ]
-              },
-              {
-                "group": "核心概念",
-                "pages": [
-                  "zh/concepts/overview",
-                  "zh/concepts/evals",
-                  "zh/concepts/experiment",
-                  "zh/concepts/adapter",
-                  "zh/concepts/tier",
-                  "zh/concepts/drive",
-                  "zh/concepts/hitl",
-                  "zh/concepts/assert",
-                  "zh/concepts/judge"
-                ]
-              },
-              {
-                "group": "连接 Agent",
-                "pages": [
-                  "zh/guides/connect-your-agent",
-                  "zh/guides/official-adapters",
-                  "zh/guides/write-send",
-                  "zh/guides/connect-otel",
-                  "zh/guides/sandbox-agent",
-                  "zh/guides/sandbox-backends"
-                ]
-              },
-              {
-                "group": "评估与实验",
-                "pages": [
-                  "zh/guides/authoring",
-                  "zh/guides/write-experiment",
-                  "zh/guides/experiments",
-                  "zh/guides/fixtures",
-                  "zh/guides/dataset-fanout",
-                  "zh/guides/scoring-guide"
-                ]
-              },
-              {
-                "group": "示例",
-                "pages": [
-                  "zh/example/claude-code-codex-plugin",
-                  "zh/example/claude-code-codex-skill",
-                  "zh/example/ai-agent-application",
-                  "zh/example/showcase"
-                ]
-              },
-              {
-                "group": "运行与观察",
-                "pages": [
-                  "zh/guides/runner",
-                  "zh/guides/ci-integration",
-                  "zh/guides/reporters",
-                  "zh/guides/viewing-results",
-                  "zh/guides/agent-feedback-loop"
-                ]
-              }
-            ]
-          },
-          {
-            "tab": "参考",
-            "groups": [
-              {
-                "group": "API",
-                "pages": [
-                  "zh/reference/define-eval",
-                  "zh/reference/define-agent",
-                  "zh/reference/events",
-                  "zh/reference/capabilities",
-                  "zh/reference/builtin-agents",
-                  "zh/reference/define-config",
-                  "zh/reference/expect"
-                ]
-              },
-              {
-                "group": "CLI",
-                "pages": [
-                  "zh/reference/cli"
-                ]
-              }
-            ]
-          }
-        ]
-      }
-    ]
-  }
-}

package/docs-site/example/ai-agent-application.mdx

@@ -1,148 +0,0 @@
----
-title: "Eval Your AI Agent Application"
-sidebarTitle: "Eval AI Agent Applications"
-description: ""
----
-
-This example shows how to use niceeval to evaluate your own AI agent application.
-
-See the full example code: https://github.com/CorrectRoadH/niceeval/tree/main/examples/zh/ai-sdk
-
-The system under test is a general-purpose AI assistant application built with an AI SDK tool loop. It handles messages, calls tools (weather / calculator / search), understands images, and uses Langfuse for its own observability. The application doesn't need a sandbox during testing — niceeval reaches it through a direct adapter.
-
-## Directory structure
-
-```text
-examples/zh/ai-sdk/
-  src/                     # web agent under test (POST /api/turn, tools + image understanding)
-  adapter/adapter.ts       # niceeval adapter: factory webAgent({ baseUrl })
-  evals/                   # conversational evals
-    weather-tool.eval.ts        # ask about weather → calls get_weather
-    image-understanding.eval.ts # image understanding
-  experiments/
-    compare-models/        # experiment group: one file per model
-      gpt-5.4.ts
-      deepseek-v4-pro.ts
-  niceeval.config.ts       # register adapter, judge, concurrency
-```
-
-## Define the adapter
-
-The adapter tells niceeval how to send requests to the AI agent and how to read responses as a standard event stream. It's a factory function: `baseUrl` (where the service runs) is passed in from the outside so the adapter never hardcodes it or reads from env.
-
-```ts
-// adapter/adapter.ts
-import { defineAgent } from "niceeval/adapter";
-import type { Agent } from "niceeval/adapter";
-import type { StreamEvent } from "niceeval";
-import type { AgentEvent, AgentResponse } from "../src/protocol.ts";
-
-export function webAgent(opts: { baseUrl: string }): Agent {
-  const baseUrl = opts.baseUrl.replace(/\/$/, "");
-  return defineAgent({
-    name: "web-agent",
-    async send(input, ctx) {
-      const response = await fetch(`${baseUrl}/api/turn`, {
-        method: "POST",
-        headers: { "content-type": "application/json" },
-        body: JSON.stringify({
-          sessionId: ctx.session.id,
-          message: input.text,
-          model: ctx.model,
-          files: input.files,
-          otelEndpoint: ctx.telemetry?.endpoint, // dual observability: let the app send this turn's spans back to niceeval
-        }),
-        signal: ctx.signal,
-      });
-      // Shared contract within the same workspace — read as AgentResponse directly, no need to validate as unknown.
-      const body = (await response.json()) as AgentResponse;
-      ctx.session.capture(body.sessionId);
-      return {
-        events: body.events.map(toStreamEvent),
-        data: body.data,
-        status: "completed" as const,
-      };
-    },
-  });
-}
-
-function toStreamEvent(event: AgentEvent): StreamEvent {
-  if (event.type === "action.called") return { ...event, tool: "unknown" };
-  return event;
-}
-```
-
-## Multi-turn messages
-
-Within the same conversation line, `ctx.session.id` automatically carries over to the next turn; the adapter just writes the agent's returned `sessionId` back with `ctx.session.capture()`. To split traffic by feature flag within an experiment, see [Experiments](/guides/experiments).
-
-## Define evals
-
-Each eval sends a message and asserts on the reply, tool calls, and image understanding. Deterministic assertions (`calledTool`, `messageIncludes`) run without an API key; open-ended scoring with a judge requires a key to be set.
-
-```ts
-// evals/weather-tool.eval.ts
-import { defineEval } from "niceeval";
-
-export default defineEval({
-  description: "AI assistant: asking about weather calls get_weather",
-  async test(t) {
-    const turn = await t.send("What's the weather like in Brooklyn today?");
-    turn.succeeded();
-    await t.group("calls get_weather with correct city", () => {
-      t.calledTool("get_weather", { input: { city: "Brooklyn" } });
-      t.messageIncludes(/°[CF]|temperature|weather/i);
-    });
-    t.judge.autoevals.closedQA("Does the assistant answer based on the tool's returned weather data, not a hallucination?").atLeast(0.7);
-  },
-});
-```
-
-For image understanding, use `t.sendFile()` to attach an image. The adapter forwards `input.files` to the web agent:
-
-```ts
-// evals/image-understanding.eval.ts
-await t.sendFile(new URL("./fixtures/sample.png", import.meta.url).pathname);
-const turn = await t.send("What's in this image?");
-t.messageIncludes(/cat/i); // the sample image is a cat
-```
-
-## Define experiments
-
-**One experiment file = one configuration** (single model). For cross-model comparison, write multiple files in the same experiment group folder:
-
-```ts
-// experiments/compare-models/gpt-5.4.ts
-import { defineExperiment } from "niceeval";
-import { webAgent } from "../../adapter/adapter.ts";
-
-export default defineExperiment({
-  description: "gpt-5.4: model comparison",
-  agent: webAgent({ baseUrl: "http://127.0.0.1:5188" }),
-  model: "gpt-5.4", // single string; copy this file and change one line for each model
-  runs: 2,
-  earlyExit: true,
-});
-```
-
-## Start evaluating
-
-First start the service under test (defaults to mock mode — no API key required). This example is a standalone npm project where `niceeval` is a local dependency:
-
-```bash
-cd examples/zh/ai-sdk && pnpm install && pnpm dev
-```
-
-Open a second terminal and run evals:
-
-```bash
-cd examples/zh/ai-sdk
-pnpm exec niceeval exp compare-models   # run the model comparison experiment
-pnpm exec niceeval exp compare-models weather-tool   # run one eval inside that experiment
-```
-
-## Next steps
-
-- [Connect Your Agent](/guides/connect-your-agent) — the from-scratch tutorial for `defineAgent`.
-- [Authoring Evals](/guides/authoring) — single-turn, multi-turn, and dataset evals.
-- [CI Integration](/guides/ci-integration) — put agent regression tests in PRs.