> ## 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.

# NiceEval 架构：评估用例、agents 与 sandboxes

> 理解 NiceEval、Adapter 和 Sandbox Provider 如何配合，用统一 API 评估任意 AI Agent。

[NiceEval](https://niceeval.com/) 的核心设计是把“评测逻辑”与“如何连接被测对象”分开。[NiceEval](https://niceeval.com/) 负责发现、调度、评分和报告；Adapter 负责调用被测系统；Sandbox Provider 负责隔离文件系统。

## 四层架构

```text theme={null}
Eval files / fixtures
        ↓
NiceEval
        ↓
Adapter
        ↓
Subject under test / Sandbox Provider
```

## NiceEval 负责什么

<CardGroup cols={2}>
  <Card title="评估用例发现" icon="magnifying-glass">
    发现 `*.eval.ts` 文件和 fixture 目录，并从路径推导稳定 ID。
  </Card>

  <Card title="并发调度" icon="timeline">
    控制运行池大小、重试、attempt 和 early-exit。
  </Card>

  <Card title="断言与评分" icon="chart-bar">
    收集 `t.check`、作用域断言、judge 分数和测试结果。
  </Card>

  <Card title="缓存" icon="database">
    用 fingerprint 跳过已通过且输入未变的 case。
  </Card>

  <Card title="报告" icon="file-lines">
    输出控制台、JSON、JUnit 等报告。
  </Card>

  <Card title="Artifacts" icon="folder-open">
    保存 summary、event stream、transcript、diff 和测试输出。
  </Card>
</CardGroup>

## Adapter

<Note>
  `Agent` 是 [NiceEval](https://niceeval.com/) 看到的抽象；`Adapter` 是你写的具体实现。[NiceEval](https://niceeval.com/) 不知道你的 agent 私有协议、CLI 参数或鉴权方式。
</Note>

这条边界让 [NiceEval](https://niceeval.com/) 保持通用。评估你自己的 AI agent、Claude Code、Codex 或自定义 agent 时，runner 和 scorers 的逻辑不需要改变。

## Sandbox

<Tabs>
  <Tab title="Docker">
    本地容器 Provider，适合开发和 CI 中的 coding-agent 评估用例。
  </Tab>

  <Tab title="Vercel Sandbox">
    云端 Sandbox Provider，适合更强隔离或更大的运行资源。
  </Tab>

  <Tab title="第三方 Provider">
    只要实现 `Sandbox` 接口，就可以接入其他 Sandbox 服务。
  </Tab>
</Tabs>

## 关键术语

<AccordionGroup>
  <Accordion title="评估用例">
    一个测试用例：描述和 `test(t)` 函数，agent-neutral——用哪个 Agent 由 experiment 决定。
  </Accordion>

  <Accordion title="Agent">
    [NiceEval](https://niceeval.com/) 通过名字调用的一条连接，负责返回标准 `Turn`。
  </Accordion>

  <Accordion title="Adapter">
    `Agent` 的具体实现，知道如何调用你的 runtime 或 CLI。
  </Accordion>

  <Accordion title="Sandbox">
    给 coding agent 使用的隔离运行环境。
  </Accordion>

  <Accordion title="Turn">
    一次 `t.send()` 的不可变结果快照。
  </Accordion>

  <Accordion title="Artifact">
    运行后落盘的结构化结果文件。
  </Accordion>

  <Accordion title="Experiment">
    用矩阵方式比较多个 agent、model 或 flags 的运行配置。
  </Accordion>
</AccordionGroup>

## 端到端流程

<Steps>
  <Step title="Discovery">发现评估用例文件和 fixture。</Step>
  <Step title="Scheduling">根据并发、缓存和 attempt 计划运行。</Step>
  <Step title="Agent send">调用 adapter，让被测对象产出 `Turn`。</Step>
  <Step title="Scoring">执行断言、judge 和测试。</Step>
  <Step title="Verdict">把所有结果折叠为 `passed`、`failed`、`errored` 或 `skipped`。</Step>
  <Step title="Reporting & artifacts">输出报告并保存结构化文件。</Step>
</Steps>

## 相关阅读

* [评估](/docs/zh/explanation/evals) — 评估用例是什么，以及生命周期细节。
* [Adapter](/docs/zh/explanation/adapter) — 如何写 adapter，并在 experiment 中引用它。
* [Drive](/docs/zh/explanation/drive) — `t.send()`、session 与 HITL：如何产出断言要读的 `Turn` 数据。
* [Assert](/docs/zh/explanation/assert) — 断言词汇和判定规则。
* [Judge](/docs/zh/explanation/judge) — LLM-as-judge，评开放式质量。