niceeval 0.5.4 → 0.6.0

package/INDEX.md

@@ -0,0 +1,55 @@
+# NiceEval AI 文档索引
+
+这是 coding agent 读取 NiceEval 文档的稳定入口，随 npm 包发布，不属于公开文档站。不要根据训练数据、官网或 GitHub `main` 分支猜测 API。
+
+以下路径都相对于包根 `node_modules/niceeval/`。文档位于 `docs-site/zh/`，与当前安装的 NiceEval 版本一起发布。先按任务读取对应页面；页面再引用其它概念或参考时，继续读取包内文件。
+
+## 开始接入
+
+| 任务 | 读取 |
+| --- | --- |
+| 初始化并跑通第一条 Eval | `docs-site/zh/quickstart.mdx` |
+| 理解 Adapter、Experiment、Eval 的分工 | `docs-site/zh/concepts/overview.mdx` |
+| 接入自己的 Agent | `docs-site/zh/guides/connect-your-agent.mdx` |
+| 选择官方 Adapter | `docs-site/zh/guides/official-adapters.mdx` |
+| 接入 coding agent CLI | `docs-site/zh/guides/sandbox-agent.mdx` |
+| 选择 Sandbox Provider | `docs-site/zh/guides/sandbox-providers.mdx` |
+
+## 编写配置与 Eval
+
+| 任务 | 读取 |
+| --- | --- |
+| 编写 Adapter | `docs-site/zh/concepts/adapter.mdx`、`docs-site/zh/reference/define-agent.mdx` |
+| 映射消息、工具调用和事件流 | `docs-site/zh/guides/write-send.mdx`、`docs-site/zh/reference/events.mdx` |
+| 编写 Experiment | `docs-site/zh/guides/write-experiment.mdx` |
+| 编写 Eval | `docs-site/zh/concepts/evals.mdx`、`docs-site/zh/reference/define-eval.mdx` |
+| 编写断言和评分 | `docs-site/zh/guides/authoring.mdx`、`docs-site/zh/guides/scoring-guide.mdx`、`docs-site/zh/reference/expect.mdx` |
+| 配置 Judge | `docs-site/zh/concepts/judge.mdx`、`docs-site/zh/reference/define-config.mdx` |
+| 配置 OTel | `docs-site/zh/guides/connect-otel.mdx` |
+| 查 CLI 命令与 flag | `docs-site/zh/reference/cli.mdx` |
+
+## 运行、调试与优化
+
+| 任务 | 读取 |
+| --- | --- |
+| 让 AI 自主运行、观察、修改和重跑 | `docs-site/zh/guides/agent-feedback-loop.mdx` |
+| 用 `show`、`view` 和 artifact 定位失败 | `docs-site/zh/guides/viewing-results.mdx` |
+| 组织实验和对比 | `docs-site/zh/guides/experiments.mdx` |
+| 编写自定义报告 | `docs-site/zh/guides/custom-reports.mdx`、`docs-site/zh/guides/report-components.mdx` |
+| 读取或转换结构化结果 | `docs-site/zh/guides/results-data.mdx` |
+
+## 专项场景
+
+| 任务 | 读取 |
+| --- | --- |
+| 评估 Claude Code / Codex Skill | `docs-site/zh/example/claude-code-codex-skill.mdx` |
+| 评估 Plugin、Hook 或 MCP server | `docs-site/zh/example/claude-code-codex-plugin.mdx` |
+| 编写多轮会话 | `docs-site/zh/concepts/adapter.mdx`、`docs-site/zh/guides/write-send.mdx` |
+| 编写人工审批流（HITL） | `docs-site/zh/concepts/hitl.mdx` |
+| 做 feature flag A/B 对比 | `docs-site/zh/concepts/tier.mdx`、`docs-site/zh/concepts/experiment.mdx` |
+
+## 版本规则
+
+- 安装后只从本索引进入包内文档。官网适合安装前了解产品，不是安装版本的 API 事实源。
+- 升级 `niceeval` 后重新运行 `niceeval init`，刷新项目里的托管指引。
+- 如果某个路径不存在，先重新读取本文件。不要自行推测替代文件名或旧 API。

package/dist/agents/types.d.ts

@@ -0,0 +1,317 @@
+import type { Cleanup } from "../shared/types.ts";
+import type { StreamEvent, TraceSpan, Usage } from "../o11y/types.ts";
+import type { Sandbox } from "../sandbox/types.ts";
+/**
+ * MCP server 描述符 —— 支持 MCP 的 adapter(Claude Code / Codex)共用的工具服务单元,
+ * 不是 native plugin 的一种。在 agent factory config 里声明,setup 阶段写进各自的配置文件。
+ * 见 docs/feature/adapters/architecture/coding-agent-extensions.md「类型边界」。
+ */
+export interface McpServer {
+    /** 服务器唯一名(config key)。 */
+    name: string;
+    /** 启动命令(如 "npx"、"node"、"uvx")。 */
+    command: string;
+    /** 传给命令的参数。 */
+    args?: string[];
+    /** 注入服务器进程的环境变量。 */
+    env?: Record<string, string>;
+}
+/**
+ * Skill 的来源描述 —— Claude Code / Codex / Bub 共用的**数据类型**:只统一「从哪里取得
+ * 哪份 Skill」,安装位置、发现机制、要不要额外写 project instruction 由各 Adapter 决定。
+ * 见 docs/feature/adapters/architecture/coding-agent-extensions.md「类型边界」。
+ */
+export type SkillSpec = {
+    kind: "local";
+    /** 相对项目根(跑 niceeval 的目录)的 Skill 文件或目录:`SKILL.md`、含 `SKILL.md` 的目录,或单个 `.md`。 */
+    path: string;
+    /** 展示名;省略时由文件或目录名推导(`<dir>/SKILL.md` → `<dir>`,`foo.md` → `foo`)。 */
+    name?: string;
+} | {
+    kind: "repo";
+    /** GitHub `owner/repo` 或 Git URL。 */
+    source: string;
+    /** 多 Skill Repo 中要启用的 Skill;repo 只有一个 Skill 时可省略,多个时省略即 setup 失败。 */
+    skills?: string[];
+    /** Tag、Commit 或 Branch;省略表示 repo 默认 ref。 */
+    ref?: string;
+};
+/** Manifest 里的一条 Skill 安装记录:本地(带内容哈希)或 repo(带来源与 ref)。 */
+export type AgentSetupSkill = {
+    kind: "local";
+    name: string;
+    path: string;
+    sha256: string;
+} | {
+    kind: "repo";
+    source: string;
+    ref?: string;
+    skills: string[];
+};
+/**
+ * 一次 Agent setup 实际装了什么 —— 沙箱型 Coding Agent Adapter 在 setup 收尾写出的安装清单。
+ * 沙箱内落在 `__niceeval__/agent-setup.json`,运行器把它作为 attempt artifact 存成
+ * `agent-setup.json`(见 docs/feature/results/architecture.md)。不参与评分,只回答「这次实际
+ * 装了什么」;**环境变量值与 secret 不写进来**(所以 mcpServers 只记 name/command/args)。
+ */
+export interface AgentSetupManifest {
+    /** 装进去的 Skill(按配置顺序;同名来自多个来源时逐条保留,不静默合并)。 */
+    skills: AgentSetupSkill[];
+    /** Agent 原生 Plugin(Claude Code / Codex 各自的 Marketplace 协议)。 */
+    nativePlugins?: Array<{
+        agent: "claude-code" | "codex";
+        marketplace: {
+            name: string;
+            source: string;
+            ref?: string;
+        };
+        name: string;
+        /** 安装后 CLI 报告的版本;取不到时省略。 */
+        resolvedVersion?: string;
+    }>;
+    /** 挂上的 MCP server(不含 env:secret 不进 manifest)。 */
+    mcpServers?: Array<{
+        name: string;
+        command: string;
+        args?: string[];
+    }>;
+    /** Bub 的 Python Plugin(规范化后的 package 串)。 */
+    pythonPlugins?: Array<{
+        package: string;
+    }>;
+}
+/** 随一轮消息附带的文件(图片等多模态输入)。 */
+export interface InputFile {
+    /** 文件名(可选,供 adapter / 模型参考)。 */
+    readonly filename?: string;
+    /** MIME 类型,如 `image/png`、`image/jpeg`。 */
+    readonly mimeType: string;
+    /** base64 编码的文件内容(JSON 友好,remote adapter 可直接放进请求体)。 */
+    readonly dataBase64: string;
+}
+/**
+ * HITL 回答轮里,人的裁决以结构化形式随 `input.responses` 到达——adapter 不需要解析
+ * `text` 去猜哪句回答对应哪个请求、算不算批准。见 docs-site/zh/concepts/adapter.mdx
+ * 「不同回答的入参」一节的四种典型形态。
+ */
+export interface InputResponse {
+    /** 对应哪条 input.requested 请求;多个请求并停时靠它对位。 */
+    readonly requestId: string;
+    /** 与 text 二选一:回答命中了请求 options 里的某个 id(approve / deny…)。 */
+    readonly optionId?: string;
+    /** 与 optionId 二选一:自由文本回答(请求没有选项,或回答不是任何选项)。 */
+    readonly text?: string;
+}
+export interface TurnInput {
+    readonly text: string;
+    /** 本轮附带的文件(图片等)。adapter 自行决定怎么投递;不支持多模态的 adapter 忽略它。 */
+    readonly files?: readonly InputFile[];
+    /** 仅回答轮(t.respond / t.respondAll):逐请求的结构化回答,按 requestId 对位。 */
+    readonly responses?: readonly InputResponse[];
+}
+/** adapter 的 send 返回值(事件流为核心)。 */
+export interface Turn {
+    readonly events: StreamEvent[];
+    readonly data?: unknown;
+    readonly status: "completed" | "failed" | "waiting";
+    readonly usage?: Usage;
+}
+/**
+ * 本次运行的 OTLP traces 接收信息(仅当配置了 OTel 接入时有——agent 的 `tracing` 块 /
+ * config 的 telemetry 存在)。经 ctx.telemetry 交给 agent。span 只进瀑布图,不喂断言。
+ * 远程 HTTP 接入的 send 只需要 spread `headers`(每轮一个新 traceparent);接收端点是
+ * 启动期配置(`defineConfig({ telemetry: { port } } )`)固定的,不从这里传。
+ */
+export interface Telemetry {
+    /** 接收端点(完整路径,形如 http://host.docker.internal:PORT/v1/traces)。 */
+    readonly endpoint: string;
+    /**
+     * env-based 导出的 env(= AgentTracing.env(endpoint) 的结果),ready-to-spread。
+     * adapter 的 send 直接 `{ ...ctx.telemetry?.env }` 注入,不必手搓 OTEL_* 拼装。
+     */
+    readonly env?: Readonly<Record<string, string>>;
+    /**
+     * 本轮的 W3C trace context(traceparent),每轮一个新值。send 把它 spread 进 HTTP 请求头
+     * (或注入子进程 env)——应用埋点支持 context 传播时,本轮 span 挂到我们给的 trace 下,
+     * 并发跑 eval 的 span 归属才精确;不带则回退时间窗口归属(该 agent 自动降为串行)。
+     */
+    readonly headers?: Readonly<Record<string, string>>;
+}
+/**
+ * agent 的 OTLP 导出配置 —— 「沙箱里怎么让这个 CLI 把 trace 发到 endpoint」。
+ * 刻意从 setup 里拆出来:setup 管装 CLI / 写主配置,这里只管 otel 导出。两种投递方式
+ * (互不排斥,按 CLI 而定):
+ *   · env-based(标准 OTEL_* 环境变量,如 bub/Python OTel SDK)—— 用 `env`;
+ *   · file-based(CLI 自有配置文件,如 codex 的 config.toml [otel] 块)—— 用 `configure`。
+ */
+export interface AgentTracing {
+    /**
+     * 线协议(codex 发 OTLP/JSON、bub 发 OTLP/protobuf)。接收器按 content-type 自动解码,
+     * 此字段仅作声明/日志用,也为将来按协议分流留口。
+     */
+    protocol?: "http/json" | "http/protobuf";
+    /**
+     * 接收器粒度(仅非沙箱 agent;沙箱型每沙箱一个,与此无关):
+     *   · "attempt"(默认)—— 每个 attempt 一个接收器。适合每轮能切换导出端点的被测对象
+     *     (进程内 adapter,如内置 aiSdkAgent 的可切换 exporter),attempt 间天然隔离、可全并发。
+     *   · "run" —— 整个 run 共享一个接收器(每 agent 一个)。**长驻服务必选**:应用的 OTEL_*
+     *     env 进程启动时读一次,per-attempt 端口会在第一个 attempt 结束时失效。span 逐轮归属
+     *     (traceparent / 时间窗口 + 串行守卫),见 ctx.telemetry.headers。
+     * config 配了 `telemetry`(固定端口,无侵入接入的长驻服务场景)的非沙箱 agent 自动按 "run" 处理。
+     */
+    scope?: "attempt" | "run";
+    /**
+     * env-based 导出:给 endpoint → 返回要注入每轮 send 的 env(纯函数)。运行器把结果
+     * 放进 ctx.telemetry.env,send 直接 spread。
+     */
+    env?(endpoint: string): Record<string, string>;
+    /**
+     * file-based 导出:给 sandbox + ctx(ctx.telemetry.endpoint 必有),自己写 / 追加配置文件。
+     * 运行器在 agent.setup 之后、首次 send 之前调一次(仅当 tracing 开 + 有 endpoint)。
+     * 注:codex 的 [otel.trace_exporter.otlp-http] 是子表,configure 在 setup 写完主配置后
+     * 追加到 config.toml 末尾,天然满足「子表在所有上层表之后」。
+     */
+    configure?(sandbox: Sandbox, ctx: AgentContext): Promise<void> | void;
+}
+/**
+ * 一条会话线。核心承诺只有一句:**同一条会话线的每次 send 拿到同一个 `ctx.session`,
+ * 新会话线(eval 第一轮 / t.newSession() 之后)拿到一个全新的。**
+ * 会话续接(`id`/`capture`、`history`)和 HITL 停轮现场(`hold`/`take`)的存取器都在它上面,
+ * "第一轮"是新会话线的自然形态,没有要判断的分支;`state` 是这些存取器之外的逃生舱,
+ * 框架从不往里写数据。见 docs-site/zh/concepts/adapter.mdx「AgentContext」一节。
+ */
+export interface AgentSession {
+    /** 会话续接:服务端记历史。本线记过的会话 id;新会话线是 undefined。 */
+    readonly id?: string;
+    /** 记回传的会话 id;只在还没记过时落地(first-writer-wins),空值忽略。 */
+    capture(id: string | undefined): void;
+    /** 会话续接:客户端带全量历史。返回本会话线的历史槽句柄;新线 get() 是空数组。 */
+    history<TMsg>(): {
+        get(): TMsg[];
+        commit(messages: TMsg[]): void;
+    };
+    /** HITL 停轮现场:存。 */
+    hold<T>(state: T): void;
+    /** HITL 停轮现场:取,取到即清除(一次消费)。 */
+    take<T>(): T | undefined;
+    /** 逃生舱:自由状态槽,起始 `{}`,框架从不写入。 */
+    readonly state: Record<string, unknown>;
+}
+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 解析出的
+     * `flag`(跑法层面的 --timeout/--budget 等),两者是不相关的概念。
+     */
+    readonly flags: Readonly<Record<string, unknown>>;
+    /**
+     * 路径推导出的实验 id(与结果归属 `runWho` / `AgentRun.experimentId` 同源);不经
+     * experiment 跑(如脱离 CLI、直接构造 `AgentRun` 的场景)时为 undefined。典型用途:
+     * `SandboxSpec.setup` 钩子按实验隔离跨 attempt 的状态(缓存目录名、快照 tag 等按
+     * `ctx.experimentId` 分区),或 adapter 按实验切换鉴权 / 路由。与 `flags`(实验条件的
+     * 具体取值)是两个维度——这里只是「跑的是哪个实验」的稳定标识,不携带条件内容。
+     */
+    readonly experimentId?: string;
+    /** 仅沙箱型 agent 有(运行器按 --sandbox 备好)。 */
+    readonly sandbox: Sandbox;
+    readonly session: AgentSession;
+    /**
+     * 仅当配置了 OTel 接入时有(agent 的 `tracing` 块 / config 的 telemetry 存在):
+     * 本次运行的 OTLP traces 接收信息(endpoint + env-based 导出 env)。
+     * 怎么把它交给 CLI 由 agent 的 `tracing` 块声明:env-based 的把 ctx.telemetry.env
+     * spread 进 send;file-based 的在 tracing.configure 里写配置。远程 HTTP 接入的 send
+     * 只需要把 headers spread 进请求头(每轮一个新 traceparent);端点是启动期配置
+     * (defineConfig({ telemetry: { port } }))固定的,不从这里传。
+     */
+    readonly telemetry?: Telemetry;
+    /**
+     * 写一行进运行器自身的进度日志(落 stderr,或调用方传入的 `onProgress` 回调)。
+     * 超时失败时,最近若干行会并入结果的 error 信息,方便定位卡在哪一步。
+     * 与 `Sandbox.appendLog` 是两回事:那个是把一行写进容器自己的原生日志
+     * (`docker logs` 能看到),这里只是运行器的观测通道。
+     */
+    log(msg: string): void;
+}
+/**
+ * agent 自己的沙箱生命周期(每个沙箱一次,与「每轮 send」分开):
+ * `setup` 装 CLI、写配置(model/base/auth 等本轮内不变的东西),`send` 只管把一轮 prompt
+ * 跑起来(第一次 fresh / 后续 resume)+ 解析 transcript,`teardown` 清理。
+ * 运行器在备好沙箱(上传 / 基线 / eval.setup)后、第一次 send 前调一次 `setup`;
+ * `setup` 可返回 cleanup 闭包,与 `teardown` 都在 finally 跑。
+ */
+export type AgentSetup = (sandbox: Sandbox, ctx: AgentContext) => Promise<void | Cleanup> | void | Cleanup;
+export type AgentTeardown = (sandbox: Sandbox, ctx: AgentContext) => Promise<void> | void;
+/**
+ * 本 agent 的原生 OTLP span → canonical GenAI semconv 的薄 mapper。
+ * 由 adapter 声明(和 tracing.env 一样属于「连到谁」的特殊性),core 只调接口——
+ * 省略时 core 走通用 heuristic 兜底,不按 agent 名字分支。
+ */
+export type SpanMapper = (spans: TraceSpan[]) => TraceSpan[];
+/** 注册表里的 agent(defineAgent / defineSandboxAgent 产出)。 */
+export interface Agent {
+    readonly name: string;
+    /**
+     * 内部判别字段(用户不声明):`defineSandboxAgent` 恒设 "sandbox",`defineAgent` 恒设
+     * "remote"。t 上的能力不再是问卷式声明,而是构造证据——sandbox 型才解锁
+     * `t.sandbox`/`t.sandbox.fileChanged()` 等文件系统断言,见 docs-site「能力从哪来」一节。
+     */
+    readonly kind: "sandbox" | "remote";
+    setup?: AgentSetup;
+    /** OTLP 导出配置(仅当此字段存在时运行器才为该 agent 开 OTLP 接收);与 setup 分开,见 AgentTracing。 */
+    tracing?: AgentTracing;
+    /** 原生 span → canonical 的薄 mapper;省略走通用 heuristic。只影响瀑布图。 */
+    spanMapper?: SpanMapper;
+    send(input: TurnInput, ctx: AgentContext): Promise<Turn>;
+    teardown?: AgentTeardown;
+}
+/** `defineSandboxAgent()` 的入参形状(见 src/define.ts)——`kind: "sandbox"` 由 define 固定填入,不由用户声明。 */
+export interface SandboxAgentDef {
+    /** agent 的显示名/标识,原样进入 `Agent.name`——不是注册表查找 key,只用于展示、结果归属与去重指纹。 */
+    name: string;
+    /**
+     * 每个沙箱一次(不是每轮一次):装 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;
+}