> ## Documentation Index
> Fetch the complete documentation index at: https://niceeval.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 能力与证据覆盖参考

> Agent 的构造方式、运行时行为与必填的六通道 evidenceCoverage 声明，怎样共同决定 NiceEval 的断言能相信什么。

能力要回答两个不同的问题：

1. **Runner 能构造或调用什么？** Agent 的构造方式与运行时行为提供 Sandbox、tracing、会话续接和 HITL。
2. **断言能相信什么结论？** 每个 Agent 都必须用 `evidenceCoverage` 声明六个证据通道的完整性。

`defineAgent` / `defineSandboxAgent` 上没有另一个 `capabilities` 字段。这不表示「什么都不用声明」：两种定义的 `evidenceCoverage` 都是必填字段，避免缺失证据变成含糊的第四种状态。

## 构造与运行时能力

| 能力                                              | 怎么获得                                                                                   | 对证据的影响                                                              |
| ----------------------------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| `t.sandbox` / `t.sandbox.fileChanged()` 等文件系统断言 | 用 `defineSandboxAgent` 构造（`Agent.kind` 恒为 `"sandbox"`）                                 | Sandbox 结果断言消费 Attempt 的 agent 归因 diff，不对应 `evidenceCoverage` 的某个通道 |
| `tracing`（OTLP 接收 → `niceeval view` 瀑布图）        | CLI 型 Agent 配置 `tracing`。长驻应用在 config 配置固定的 `telemetry` 端口                             | Span 只进时间瀑布图，不能填补行为证据缺口                                             |
| 跨轮续接与 `t.newSession()` 隔离                       | 用 `ctx.session.id` / `capture` 续接后端会话，或用 `ctx.session.get` / `set` 保存 Adapter 私有的强类型历史 | 会话接法决定实际行为，不从一个 evidence bit 推断                                     |
| HITL（`t.respond()`）                             | `send` 返回 `status: "waiting"` 和 `input.requested`                                      | 下一轮回答按结构化 request ID 对位                                             |
| Compaction 可见                                   | 官方 parser 或完整的手写映射发出 `compaction` 事件                                                   | `t.event("compaction")` 还要受下方 `events` 覆盖声明约束                       |

## 必填的六通道声明

`defineAgent` 与 `defineSandboxAgent` 都要求一个 `EvidenceCoverage`：

```ts theme={null}
interface EvidenceCoverage {
  readonly events: EvidenceCoverageEntry;
  readonly actions: EvidenceCoverageEntry;
  readonly messages: EvidenceCoverageEntry;
  readonly usage: EvidenceCoverageEntry;
  readonly status: EvidenceCoverageEntry;
  readonly data: EvidenceCoverageEntry;
}

type EvidenceCoverageEntry =
  | { readonly status: "complete"; readonly reason?: never }
  | {
      readonly status: "partial" | "unavailable";
      readonly reason: string;
    };
```

只有 Adapter 确实完整采到全部通道时才用 `completeEvidenceCoverage`。官方 converter 会给出它对所归一协议的覆盖声明。手写映射必须把六个通道逐项如实写清：

```ts theme={null}
import type { EvidenceCoverage } from "niceeval/adapter";

const evidenceCoverage = {
  events: { status: "partial", reason: "接口只发送最终事件" },
  actions: { status: "unavailable", reason: "接口不暴露工具生命周期" },
  messages: { status: "complete" },
  usage: { status: "unavailable", reason: "接口不返回 token usage" },
  status: { status: "complete" },
  data: { status: "complete" },
} satisfies EvidenceCoverage;
```

`Turn.evidenceCoverage` 是可选的逐轮**降级**。只列这一轮比 Agent 默认值更差的通道，例如 stream 在 usage 到达前断开。省略的通道继承 Agent 声明。Turn 不能把默认覆盖升格。

## 覆盖怎样改变断言结果

Coverage 防止「没采到」看起来像「确认没发生」：

| 检查                                    | 所需通道 complete | 所需通道 partial / unavailable       |
| ------------------------------------- | ------------- | -------------------------------- |
| 正断言找到了匹配证据                            | `passed`      | `passed`——已经存在的证据仍然成立            |
| 正断言没找到匹配                              | `failed`      | `unavailable`——采集缺口不能证明 Agent 没做 |
| `notCalledTool()` / `notEvent()` 等负断言 | 正常求值          | `unavailable`                    |
| `maxTokens()` / `maxCost()` 等上限断言     | 正常求值          | `unavailable`                    |

`unavailable` 断言始终带机器可读原因落盘，绝不静默丢弃，也不折成通过：

* 非 optional 的 unavailable 断言让 Attempt `errored`。
* 显式链 `.optional()` 的断言仍显示 unavailable，但不影响 Verdict。

Judge 也遵守同一条 Verdict 规则，但有自己的不可用原因：Judge 模型或 API key 解析不到、Judge 调用失败、响应取不出分数，都会得到 `unavailable`。所以 Judge 并非「永远可用」。

## 手写映射漏事件会怎样

手写映射漏了事件，却把 `events` 或 `actions` 声明成 complete，会让负断言在残缺画面上看起来通过。这是错误的完整性声明。在映射覆盖成功、失败、拒绝和并发工具生命周期之前，应当如实声明 `partial` 或 `unavailable` 并写原因。

官方 converter 只保证其协议契约明确覆盖的表面。OTel span 不能修补不完整的事件映射：span 只进瀑布图，不进断言。

## 相关阅读

* [事件流参考](/docs/zh/reference/events) —— 标准事件流契约。
* [Adapter 概念](/docs/zh/explanation/adapter) —— `ctx` / `Turn` 完整契约。
* [defineAgent 与 defineSandboxAgent](/docs/zh/reference/define-agent) —— Agent 字段与示例。
* [断言](/docs/zh/explanation/assert) —— unavailable、`.optional()` 与 Verdict 传播。
* [OTel 接入](/docs/zh/tutorials/connect-otel) —— span 为什么只进可视化、不进断言。
* [内置 Agent 能力](/docs/zh/reference/builtin-agents) —— 各内置 Adapter 实际采到什么。