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

# defineConfig：项目默认配置

> defineConfig 参考：judge、reporters、并发、超时和 sandbox 默认值。

`defineConfig` 从根目录的 `niceeval.config.ts` 默认导出，只放项目级默认值。agent、model、flags、attempts 和实验预算写在 `experiments/` 下的 `defineExperiment` 文件里。

```ts theme={null}
import { defineConfig } from "niceeval";
import site from "./reports/site";

export default defineConfig({
  judge: { model: "gpt-5.4-mini" },
  maxConcurrency: 4,
  timeoutMs: 300_000,
  report: site,
});
```

`report` 收 `defineReport` 的产物本身（import 自己的报告文件），不是路径字符串。`niceeval show` 与 `niceeval view` 不带 `--report` 时装载它，没写就装载内置的默认报告。`--report` 按次覆盖，`--report standard` 回到内置报告。写法与整套报告能力见[编写自定义报告](/docs/zh/tutorials/custom-reports#设成项目默认)。

## Config 字段

#### `report`

```ts theme={null}
report?: ReportDefinition;
```

view/show 的项目默认报告。

#### `theme`

```ts theme={null}
theme?: ThemeDefinition;
```

view 的 host-owned closed visual token declaration.

#### `name`

```ts theme={null}
name?: LocalizedText;
```

项目名,显示在 `niceeval view` 顶部 hero(`<h1>`),省略则回退到通用标题。
可传字符串,或按 locale 提供多语言(如 `{ en: "...", "zh-CN": "..." }`),随 view 语言切换。

#### `workspace`

```ts theme={null}
workspace?: string;
```

上传进 Sandbox 的工作区根目录,省略则用项目根;评估用例的 sandbox 视图从这里起步。

#### `judge`

```ts theme={null}
judge?: JudgeConfig;
```

项目级默认 judge 配置(model / baseUrl / apiKeyEnv);EvalDef.judge 可按评估用例覆盖。

#### `reporters`

```ts theme={null}
reporters?: Reporter[];
```

项目级默认 reporter 列表(如落盘 / 上传结果);EvalDef.reporters 会与它合并。

#### `maxConcurrency`

```ts theme={null}
maxConcurrency?: number;
```

项目级默认并发上限;CLI flag / experiment 的同名设置优先级更高(没有环境变量层)。

#### `maxBuildConcurrency`

```ts theme={null}
maxBuildConcurrency?: number;
```

Run 级 Sandbox 镜像准备并发；与 attempt 并发独立，省略时安全默认 2。

#### `timeoutMs`

```ts theme={null}
timeoutMs?: number;
```

项目级默认单次 attempt 超时(毫秒);CLI flag / experiment / EvalDef 的同名设置优先级更高。

#### `telemetry`

```ts theme={null}
telemetry?: { host?: string; port?: number };
```

OTLP 接收配置,niceeval 项目内唯一入口(不读 NICEEVAL\_OTLP\_\* 环境变量)。
`port` 钉住接收端口(固定端口模式:长驻服务把 OTEL\_EXPORTER\_OTLP\_ENDPOINT 一次性指到
`http://localhost:<port>/v1/traces`,跑多少次评估用例都不用改)。省略 = 每次运行动态分配
临时端口(经 ctx.telemetry 交给 adapter)。代价:固定端口下同机同时只能跑一个 niceeval 进程,
且该端口被别的进程占用时会报错——换一个空闲端口写回这里即可。
`host` 是报给 adapter 的接收端 hostname(而非监听地址,监听地址恒为 0.0.0.0):默认
"127.0.0.1"。只有作者已经提供受控 tunnel / 可达路由时才在这里覆盖；Docker Sandbox
默认把 receiver 放在 Sandbox 内，不依赖隐式宿主 gateway。

#### `pricing`

```ts theme={null}
pricing?: globalThis.Record<string, PriceOverride>;
```

内置价格表(`o11y/prices.json`)之上的用户覆盖 / 补充,按 model 查(见 Observability
· 用量与成本)。key 支持精确 model 名或 `provider/*` 通配(自托管/网关折扣按 provider 批量覆盖);
精确 key 优先于通配。pricing 只驱动 `estimatedCostUSD` 的估算(`estimateCost`),与
`usage.costUSD`(网关实测)无关——两者独立并存,互不兜底。它是 runtime/config 价目表,
不是 Report 的成本投影:Report 不消费该字段(Report 侧使用自己的 PricingProfile)。

> 成本边界：这里的 `pricing` 只提供 Runner 的 Config/runtime price table 输入，Runner 会独立产生 `estimatedCostUSD`，不论是否已有 `Usage.costUSD`。`maxCost` 只使用该 estimate。Report 不读取此配置；它必须在 Report module 以 `definePricingProfile()` 显式声明自己的 USD Profile，并只对 sealed Usage 做 Analysis 投影。

[NiceEval](https://niceeval.com/) 把环境准备放在普通代码里：评估用例自己需要的文件写在 `test(t)`，agent 自己的准备写在 adapter 的 setup。`Config` 刻意没有 `sandbox` 字段，也不自动探测 provider。请在 Eval 或 Experiment 上声明 template-bearing `SandboxLayer`，让 link planning 在创建任何资源前确定它的 owner 与配对结果。