> ## 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 runner 如何调度和执行评估用例

> NiceEval runner 发现评估用例，用有界并发调度，缓存结果，重试脆弱基础设施，并执行预算保护。

Runner 是把评估用例文件变成一次实际运行的执行引擎。它负责发现、过滤、调度、缓存、attempt、reporters 和 artifact 输出。

## 发现

runner 会读取 `evals/` 下的：

* `*.eval.ts` 文件
* 导出评估用例数组的数据集文件

```bash theme={null}
npx niceeval list
```

`list` 只发现和打印 ID，不执行评估用例。

## 过滤

`exp` 命令中,实验名之后的位置参数是评估用例 ID 前缀：

```bash theme={null}
npx niceeval exp local
npx niceeval exp local weather
npx niceeval exp local fixtures/button
```

不要把 agent 名放进位置参数。agent/model/flags 写进 experiment。

## 并发

```bash theme={null}
npx niceeval exp local --max-concurrency 8
```

远程 HTTP agent 可以用更高并发；本地 Docker Sandbox 通常需要更低并发，避免 CPU、内存和磁盘竞争。

## runs 与 early-exit

```bash theme={null}
npx niceeval exp local fixtures/button --runs 5
npx niceeval exp local fixtures/button --runs 5 --no-early-exit
```

`runs` 用于测 pass rate。首过即停默认开启：某个 Attempt 通过后，同一 eval 的剩余 Attempt 会被停止。想拿完整的通过率分布时，用 `--no-early-exit` 关闭，让每个 eval 跑满 `runs` 次。

## 缓存

[NiceEval](https://niceeval.com/) 可以根据输入、配置和相关文件 fingerprint 跳过已判定为 `passed` 或 `failed` 的结果——两者都是判定确定的终态。`errored`（超时、Sandbox 异常等框架/环境层面的不确定失败）永远重试。缓存适合加速迭代，但如果你在调试非确定性行为，应该明确关闭（`--force`）或清理相关缓存。

## 超时和预算

```bash theme={null}
npx niceeval exp local --timeout 300000 --budget 5
```

超时保护单个评估用例，预算保护整次运行成本。NiceEval 只有在 Attempt 已经发起 Agent Turn、却连续拿不到成本数据时，才提示预算无法执行。如果 Attempt 在 `sandbox.create` 或 setup 阶段就失败，Agent 尚未运行，CLI 只显示对应的结构化执行错误，不再追加容易误导排查方向的预算警告。

## Reporter

运行中的反馈由 `--output` 选择消费者模型；Reporter 负责把完成后的结果写到其它目的地。两者不是同一层：

```bash theme={null}
npx niceeval exp local --output human  # 人：TTY dashboard + 永久错误/诊断
npx niceeval exp local --output agent  # AI：稳定 envelope + locator handoff
npx niceeval exp local --output ci     # CI：单一有序 stdout 事件流
```

省略时使用 `auto`：TTY 选择 Human，CI 环境选择 CI，其它非 TTY 选择 Agent。输出模型只改变反馈，不改变调度、判定或 artifact。

Runner 在评估用例完成后把结果交给 Reporters：

* JSON artifacts 用于后续分析。
* JUnit reporter 适合 CI。
* Braintrust reporter 把一次运行作为实验上报，跨提交比较。

挂载方式和 Braintrust 配置见 [Reporter 上报](/docs/zh/tutorials/reporters)。

## 输出目录

每次运行会写入该实验的结果快照目录 `.niceeval/<experiment>/<快照>/`，包括快照级 `snapshot.json`，以及每个 Attempt 的 `result.json`（判定、断言、结构化错误、diagnostics）和按需生成的 `events.json`、`sources.json`、`trace.json`、`o11y.json`、`diff.json` 等拆分 artifact。瞬时 progress 不落盘。

## 推荐调试流程

1. 先跑 `npx niceeval list` 确认发现结果。
2. 用 `npx niceeval exp <实验> <ID 前缀>` 缩小到一个 eval。
3. 失败后复制终端里的 locator，先运行 `npx niceeval show @<locator>` 看错误或断言摘要；需要 Agent 行为时再加 `--execution`，需要文件变化时加 `--diff`。
4. 再扩大到完整 suite 或 experiment。