跳转到主要内容
niceeval 的核心设计是把“评测逻辑”与“如何连接被测对象”分开。core 只负责发现、调度、评分和报告；agent adapter 负责调用被测系统；sandbox backend 负责隔离文件系统。

​
四层架构

Eval files / fixtures
        ↓
niceeval core
        ↓
Agent adapter
        ↓
Subject under test / Sandbox backend

​
core 负责什么

Eval 发现

发现 *.eval.ts 文件和 fixture 目录，并从路径推导稳定 ID。

并发调度

控制运行池大小、重试、attempt 和 early-exit。

断言与评分

收集 t.check、作用域断言、judge 分数和测试结果。

缓存

用 fingerprint 跳过已通过且输入未变的 case。

报告

输出控制台、JSON、JUnit 等报告。

Artifacts

保存 summary、event stream、transcript、diff 和测试输出。

​
Agent / Adapter 边界

Agent 是 niceeval core 看到的抽象；Adapter 是你写的具体实现。core 不知道你的 HTTP 协议、CLI 参数或鉴权方式。
这条边界让 niceeval 保持通用。评估本地函数、远程服务、Claude Code、Codex 或自定义 agent 时，runner 和 scorers 的逻辑不需要改变。

​
为什么没有 --url

URL 是某个 adapter 的私有配置，而不是 CLI 的位置参数。experiment 引用 agent；experiment 名之后的位置参数只选择“跑哪些 eval”。

​
Sandbox 负责什么

本地容器后端，适合开发和 CI 中的 coding-agent eval。

​
关键术语

一个测试用例：描述、agent 引用和 test(t) 函数。
core 通过名字调用的一条连接，负责返回标准 Turn。
agent 的具体实现，知道如何调用你的服务或 CLI。
给 coding agent 使用的隔离运行环境。
一次 t.send() 的不可变结果快照。
运行后落盘的结构化结果文件。
用矩阵方式比较多个 agent、model 或 flags 的运行配置。

​
端到端流程

1

Discovery

发现 eval 文件和 fixture。
2

Scheduling

根据并发、缓存和 attempt 计划运行。
3

Agent send

调用 adapter，让被测对象产出 Turn。
4

Scoring

执行断言、judge 和测试。
5

Outcome

把所有结果折叠为 passed、failed、passed 或 skipped。
6

Reporting & artifacts

输出报告并保存结构化文件。

​
相关阅读

  • Evals — eval 是什么，以及生命周期细节。
  • Agents & Adapters — 如何写 adapter，并在 experiment 中引用它。
  • Scoring — 断言词汇和判决规则。