niceeval 0.11.1-canary.9 → 0.11.2

package/docs-site/zh/tutorials/configuration.mdx

@@ -0,0 +1,165 @@
+---
+title: "把配置和密钥各放到该放的地方"
+sidebarTitle: "配置与环境变量"
+description: "跑几次、超时、并发、judge、语言这些值写进代码的哪一层，API key 和 provider token 用哪些环境变量。"
+---
+
+[NiceEval](https://niceeval.com/) 里的值只有两个家：
+
+- **配置写进代码**——CLI flag、`experiments/` 下的 experiment 文件、根目录的 `niceeval.config.ts`。跑几次、超时多久、并发多少、judge 用哪个模型、默认看哪份报告、界面什么语言，全都在这里，没有对应的环境变量。
+- **密钥放环境变量**——API key、provider token。再加上 `NO_COLOR`、系统语言这类描述"输出到哪个终端"的事实。
+
+所以同一个值只有一条来路。`niceeval exp --dry` 打印出来的就是真正生效的值，不用担心某个环境变量在背后改了它。
+
+## 配置：想让这个值活多久，就写在哪一层
+
+同一个值出现在多层时，按 **CLI flag → experiment → config → 内置默认** 取，前面有值就不看后面。
+
+**只想这一次不一样**——写在命令上：
+
+```bash
+npx niceeval exp ci --runs 5 --timeout 600000
+```
+
+**这个实验一直这样**——写进 experiment 文件：
+
+```ts
+// experiments/ci.ts
+import { defineExperiment } from "niceeval";
+import { codexAgent } from "niceeval/agents";
+
+export default defineExperiment({
+  agent: codexAgent(),
+  model: "gpt-5.4",
+  runs: 3,
+  timeoutMs: 600_000,
+  budget: 5,
+});
+```
+
+`agent`、`model`、`flags` 只能写在这里，没有对应的 flag——换 agent 或换模型是复制一个 experiment 文件的事，这样每次运行对着谁跑都记在快照里，事后能复现。
+
+**整个项目共享**——写进 `niceeval.config.ts`：
+
+```ts
+import { defineConfig } from "niceeval";
+
+export default defineConfig({
+  locale: "en",
+  judge: { model: "gpt-5.4-mini" },
+  maxConcurrency: 4,
+  timeoutMs: 300_000,
+});
+```
+
+### `niceeval.config.ts` 能放什么
+
+| 字段 | 放什么 |
+| --- | --- |
+| `name` | 项目名，显示在 `niceeval view` 顶部；可按语言给多份 |
+| `locale` | CLI 与运行时文案的语言（`"en"` / `"zh-CN"`）。CI 里想让日志恒定英文，写这个 |
+| `report` | 默认报告定义，裸 `show` / `view` 装载它（见[自定义报告](/zh/tutorials/custom-reports#设成项目默认)） |
+| `judge` | 默认裁判配置：`model`、`baseUrl`、`apiKeyEnv` |
+| `sandbox` | 默认 Sandbox provider，填 `dockerSandbox()` / `e2bSandbox()` / `vercelSandbox()` / `localSandbox()` 的产物 |
+| `workspace` | 上传进 Sandbox 的工作区根目录 |
+| `reporters` | 默认 reporter 列表（落盘、上报实验平台） |
+| `maxConcurrency` | 默认并发上限 |
+| `timeoutMs` | 默认单次 attempt 超时 |
+| `telemetry` | OTLP 接收配置（`host` / `port`），OTel 接入只从这里配 |
+| `pricing` | 价格表覆盖，按 model 名或 `provider/*` 通配 |
+
+每个字段的类型和完整说明在 [defineConfig 参考](/zh/reference/define-config)；flag 全表在 [CLI 参考](/zh/reference/cli)。
+
+## 环境变量：只有密钥和终端两类
+
+下面就是 NiceEval 会读的全部环境变量。每个 agent、sandbox 和 judge 只认自己那一个名字，不会在环境里翻找别的 key。
+
+| 变量 | 谁在用 | 备注 |
+| --- | --- | --- |
+| `ANTHROPIC_API_KEY` | `claudeCodeAgent()`、`openClawAgent()` | 工厂参数 `apiKey` 可覆盖 |
+| `ANTHROPIC_BASE_URL` | `claudeCodeAgent()` | 网关地址，工厂参数 `baseUrl` 可覆盖 |
+| `CODEX_API_KEY` | `codexAgent()` | 不是 `OPENAI_API_KEY`；工厂参数 `apiKey` 可覆盖 |
+| `CODEX_BASE_URL` | `codexAgent()` | OpenAI 兼容代理地址，工厂参数 `baseUrl` 可覆盖 |
+| `BUB_API_KEY` | `bubAgent()` | 工厂参数 `apiKey` 可覆盖 |
+| `BUB_API_BASE` | `bubAgent()` | 工厂参数 `apiBase` 可覆盖 |
+| `NICEEVAL_JUDGE_KEY` | judge | judge 的默认 key 变量 |
+| `E2B_API_KEY` | `e2bSandbox()` | |
+| `VERCEL_API_TOKEN` | `vercelSandbox()` | |
+| `VERCEL_TEAM_ID` | `vercelSandbox()` | |
+| `VERCEL_PROJECT_ID` | `vercelSandbox()` | |
+| `NO_COLOR` | CLI 输出 | 设了就不画颜色和框线 |
+| `LC_ALL` / `LC_MESSAGES` / `LANG` | CLI 文案 | 系统语言，决定默认界面语言；`config.locale` 优先 |
+
+judge 想用别的变量名装 key，在配置里指过去：
+
+```ts
+export default defineConfig({
+  judge: {
+    model: "gpt-5.4-mini",
+    baseUrl: "https://gateway.example.com/v1",   // 网关地址是配置，写在这里
+    apiKeyEnv: "MY_GATEWAY_KEY",                  // key 是密钥，读这个环境变量
+  },
+});
+```
+
+网关地址本身也不方便签入仓库时，不需要 niceeval 提供什么环境变量——配置是代码，自己读就行（`.env` 在这之前已经加载完）：
+
+```ts
+export default defineConfig({
+  judge: {
+    model: "gpt-5.4-mini",
+    baseUrl: process.env.MY_GATEWAY_URL,   // 变量名自己起，自己读
+    apiKeyEnv: "MY_GATEWAY_KEY",
+  },
+});
+```
+
+区别只在于：变量名是你的项目定的，不是 NiceEval 内置一个名字然后到环境里猜。
+
+本地把密钥放进 cwd 下的 `.env`，CLI 启动时自动加载（不覆盖已经存在的环境变量），不用每次 `export`：
+
+```bash
+# .env
+ANTHROPIC_API_KEY=sk-ant-...
+NICEEVAL_JUDGE_KEY=sk-...
+```
+
+`.env` 是投递密钥的地方，不是第二个配置文件——往里写 `NICEEVAL_TIMEOUT` 这种东西不会有任何效果。CI 里同样只传密钥：
+
+```yaml
+- run: npx niceeval exp ci --strict --junit .niceeval/junit.xml
+  env:
+    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+```
+
+## 在旧脚本里见到这些变量，改成配置
+
+| 旧写法 | 改成 |
+| --- | --- |
+| `NICEEVAL_RUNS` | `--runs`，或 experiment 的 `runs` |
+| `NICEEVAL_TIMEOUT` | `--timeout`，或 experiment / config 的 `timeoutMs` |
+| `NICEEVAL_BUDGET` | `--budget`，或 experiment 的 `budget` |
+| `NICEEVAL_MAX_CONCURRENCY` | `--max-concurrency`，或 config 的 `maxConcurrency` |
+| `NICEEVAL_LANG` / `NICEEVAL_LOCALE` | config 的 `locale` |
+| `NICEEVAL_JUDGE_MODEL` | config 或 eval 的 `judge.model` |
+| `NICEEVAL_JUDGE_BASE` | config 或 eval 的 `judge.baseUrl` |
+| `NICEEVAL_OTLP_HOST` / `NICEEVAL_OTLP_PORT` | config 的 `telemetry: { host, port }` |
+
+judge 也不再从 `CODEX_API_KEY` / `OPENAI_API_KEY` 借 key、从 `OPENAI_BASE_URL` 猜端点。被测应用把标准的 `OPENAI_*` 挪作它用时，judge 不会再跟着串味。
+
+## 接着看
+
+<CardGroup cols={2}>
+  <Card title="defineConfig 参考" icon="gear" href="/zh/reference/define-config">
+    每个配置字段的类型与完整说明。
+  </Card>
+  <Card title="CLI 参考" icon="terminal" href="/zh/reference/cli">
+    命令、flag 全表与退出码。
+  </Card>
+  <Card title="写 experiment" icon="flask" href="/zh/tutorials/write-experiment">
+    哪些值属于一次具体运行。
+  </Card>
+  <Card title="CI 集成" icon="circle-play" href="/zh/tutorials/ci-integration">
+    在 CI 里传 secrets、钉住日志语言。
+  </Card>
+</CardGroup>

package/docs-site/zh/tutorials/custom-reports.mdx

@@ -6,11 +6,11 @@ description: "用 defineReport、内置报告组件和双面组件编写一份
 
 [查看结果](/zh/tutorials/viewing-results)介绍 `niceeval show` 的终端输出和 `niceeval view` 的网页输出。本教程用相同的结果数据编写考试成绩单、代码行数表和质量 × 成本图等自定义报告。
 
-一份报告对应一个报告文件：一棵由内置组件搭起来的树。`niceeval show` 和 `niceeval view` 打开结果、选出当前范围（Scope），交给这棵树渲染。把文件路径传给 `--report`，同一份定义在终端和网页都能渲染。自定义报告同样支持 Attempt 证据链接、`--results` 指定结果根和静态导出。
+一份报告对应一个报告文件：一棵由内置组件搭起来的树。`niceeval show` 和 `niceeval view` 打开结果、选出当前范围（Scope），交给这棵树渲染。把文件路径传给 `--report`，同一份定义在终端和网页都能渲染；写顺手了再把它填进 `niceeval.config.ts` 的 `report` 字段，裸跑 `show` / `view` 就默认是自己的报告（见[设成项目默认](#设成项目默认)）。自定义报告同样支持 Attempt 证据链接、`--results` 指定结果根和静态导出。
 
 ## show / view 的默认报告也是一份报告文件
 
-`niceeval show` / `view` 不传 `--report` 时渲染的默认报告不是私有实现，而是包里自带的一个普通报告文件：报告、Attempts、追踪三个导航页，加一个不进导航、按 Attempt 定位符打开的详情页，每页都由 `niceeval/report` 公开导出的组件搭成。
+`niceeval show` / `view` 在没有 `--report`、配置里也没写 `report` 时渲染的默认报告不是私有实现，而是包里自带的一个普通报告文件：报告、Attempts、追踪三个导航页，加一个不进导航、按 Attempt 定位符打开的详情页，每页都由 `niceeval/report` 公开导出的组件搭成。
 
 这份默认报告本身以 `standard` 为名从 `niceeval/report/built-in` 导出。只想在默认报告上加站点标题、GitHub 链接或统计脚本时，用 `extends` 在它上面叠自己的外壳，页面内容一行不用写；NiceEval 升级带来的页面改进也会自动跟过来：
 
@@ -105,6 +105,33 @@ const ProdSummary = defineComponent((_props: {}, ctx) => (
 
 默认报告没有特权:它的四个页面全部由公开组件搭成。需要同样的当前 Scope 比较就写 `<ExperimentComparison />`;要子集就在报告里先 `filter`,或从 CLI 用 `--exp` 收窄。
 
+## 设成项目默认
+
+报告定型以后，不用再要求团队每次都敲 `--report`。把 `defineReport` 的产物 import 进配置，填给 `report` 字段：
+
+```ts
+// niceeval.config.ts
+import { defineConfig } from "niceeval";
+import site from "./reports/site";
+
+export default defineConfig({
+  report: site,
+});
+```
+
+字段收报告定义本身，不是路径字符串——配置是 TS 文件，import 就好，写错路径在类型检查时就报出来。之后：
+
+```bash
+niceeval show                     # 自己的报告,不用再写 --report
+niceeval view --page exam         # --page、位置参数收窄、@locator 下钻全部照旧
+niceeval show --report standard   # 本次回到内建默认报告,不改配置
+niceeval view --report ./reports/exam.tsx   # 本次换成另一份文件
+```
+
+`--report` 的值有两种形态：写成带路径的样子（`./reports/exam.tsx`、`reports/exam.tsx`）按文件装载，裸词当内置报告名查（今天只有 `standard`）。裸词查不到就报错并列出可用的名字，不会去猜同名文件。
+
+配置里的 `report` 只影响看结果，不影响跑：`niceeval exp` 不读它，报告也不写进结果快照，所以改报告不用重跑。
+
 ## 排版:内置排版原语
 
 排版原语也是双面组件,同一份布局会分别渲染到网页和终端:
@@ -452,4 +479,4 @@ niceeval view --report reports/exam.tsx --out site
 
 ## 自定义报告的边界
 
-一次只渲染一份报告,`--report` 收显式文件路径——没有 `reports/` 目录自动发现、没有插件注册表、没有配置文件。自定义指标和自定义组件都住在你的报告文件里,随文件一起递入,宿主不为它们长任何注册面。不传 `--report` 时渲染的就是默认报告,你的报告和它是同级实现。
+一次只渲染一份报告,来源只有两处:`--report` 的显式取值,和配置里的 `report` 字段——没有 `reports/` 目录自动发现,也没有插件注册表。自定义指标和自定义组件都住在你的报告文件里,随文件一起递入,宿主不为它们长任何注册面。两处都没有时渲染的就是内置默认报告,你的报告和它是同级实现。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "niceeval",
-  "version": "0.11.1-canary.9",
+  "version": "0.11.2",
   "description": "Agent-native eval tool — eval agents, services, functions, and coding-agent fixtures",
   "type": "module",
   "license": "MIT",

package/src/agents/bub.ts

@@ -1,6 +1,6 @@
 import { completeCoverage } from "../scoring/coverage.ts";
 import { defineSandboxAgent } from "../define.ts";
-import { requireEnv, getEnv } from "../util.ts";
+import { requireEnv } from "../util.ts";
 import { shared } from "./shared.ts";
 import {
   appendProjectInstruction,
@@ -85,16 +85,13 @@ const SKILL_DIR = ".agents/skills";
 
 // TODO(upstream): BUB_OVERRIDE 钉在个人 fork 的修复分支上(tool-call 分支丢助手文本的修复
 // 尚未进上游,见 memory/bub-tapestore-otel…drift.md 台账),等上游包含后改回发布版。
-// 可用 NICEEVAL_BUB_OVERRIDE / NICEEVAL_BUB_OTEL_PLUGIN 覆盖,不必改源码。
-const BUB_OVERRIDE =
-  getEnv("NICEEVAL_BUB_OVERRIDE") ??
-  DEFAULT_BUB_OVERRIDE;
+// 要试别的 pin 就改这两个常量——不设环境变量后门:装哪个包是配置,配置的家是代码
+// (边界见 docs/architecture.md「配置从代码来,凭据从环境来」)。
+const BUB_OVERRIDE = DEFAULT_BUB_OVERRIDE;
 const BUB_OVERRIDE_FILE = "/tmp/bub-override.txt";
 // otel 插件跟上游 main 走(bub-contrib#50 起从 bub.tape 导入,要求 bub ≥ 0.3.10dev,
 // 与上面的 override 分支兼容)。插件不发 PyPI,git 依赖是唯一安装方式。
-const OTEL_PLUGIN =
-  getEnv("NICEEVAL_BUB_OTEL_PLUGIN") ??
-  DEFAULT_BUB_OTEL_PLUGIN;
+const OTEL_PLUGIN = DEFAULT_BUB_OTEL_PLUGIN;
 
 // NiceEval 的预制配方与运行时安装都写到 $HOME/.local；显式使用该路径，避免 PATH 上
 // 另一个未知版本的 bub 抢先命中。

package/src/cli.ts

@@ -54,7 +54,7 @@ import {
 // 是两份不同源码位置,即使运行时同名同形,TS 类型与 instanceof 都不认。
 import { ReportLoadError } from "../dist/report/runtime/load.js";
 import { runShow } from "./show/index.ts";
-import { t } from "./i18n/index.ts";
+import { setConfiguredLocale, t } from "./i18n/index.ts";
 import { formatThrown, upsertManagedBlock } from "./util.ts";
 import type {
   CompletionStatus,
@@ -382,18 +382,6 @@ function firstViewerOnlyFlag(flags: Flags): { flag: string; command: string } |
   return undefined;
 }
 
-/** 调度项的环境变量层(标志 > 环境变量 > config > 默认,见 docs/cli.md「配置优先级」)。 */
-function envNumber(name: string): number | undefined {
-  const raw = process.env[name]?.trim();
-  if (!raw) return undefined;
-  const n = Number(raw);
-  if (!Number.isFinite(n)) {
-    process.stderr.write(t("cli.envInvalidNumber", { name, value: raw }));
-    process.exit(1);
-  }
-  return n;
-}
-
 /** 加载 cwd/.env(不覆盖已有环境变量)。 */
 async function loadDotenv(cwd: string): Promise<void> {
   const path = join(cwd, ".env");
@@ -413,6 +401,23 @@ async function loadDotenv(cwd: string): Promise<void> {
   }
 }
 
+/**
+ * 界面语言只从 `defineConfig({ locale })` 来,所以每条命令(含不依赖 config 的 show / view)
+ * 都要在派发前看一眼配置。这里刻意宽容:没有配置文件、或配置本身有错时静默回到系统 locale
+ * 判定——语言是装饰性设置,不该让 `niceeval show` 因为一个坏 config 打不开结果;真正需要
+ * config 的命令随后走 loadConfig,由它报出完整错误(模块缓存让这次装载不重复付出代价)。
+ */
+async function applyConfiguredLocale(cwd: string): Promise<void> {
+  const path = join(cwd, "niceeval.config.ts");
+  if (!existsSync(path)) return;
+  try {
+    const mod = (await import(pathToFileURL(path).href)) as { default?: Config };
+    setConfiguredLocale(mod.default?.locale);
+  } catch {
+    // 交给后续 loadConfig 报错;这里不抢在语言还没定下来时打印任何东西。
+  }
+}
+
 async function loadConfig(cwd: string): Promise<Config> {
   const path = join(cwd, "niceeval.config.ts");
   if (!existsSync(path)) {
@@ -606,6 +611,7 @@ async function packageVersion(): Promise<string> {
 async function main(): Promise<void> {
   const cwd = process.cwd();
   await loadDotenv(cwd);
+  await applyConfiguredLocale(cwd);
   const { command, positionals, flags } = parseArgs(process.argv.slice(2));
 
   // --help / --version 不需要 config,先于一切命令处理。
@@ -875,11 +881,11 @@ async function main(): Promise<void> {
         reasoningEffort: exp.reasoningEffort,
         flags: exp.flags ?? {},
         ...(exp.provenanceFlags !== undefined ? { provenanceFlags: exp.provenanceFlags } : {}),
-        runs: flags.runs ?? envNumber("NICEEVAL_RUNS") ?? exp.runs ?? 1,
+        runs: flags.runs ?? exp.runs ?? 1,
         earlyExit: flags.earlyExit ?? exp.earlyExit ?? false,
         sandbox: exp.sandbox ?? config.sandbox,
-        timeoutMs: flags.timeout ?? envNumber("NICEEVAL_TIMEOUT") ?? exp.timeoutMs ?? config.timeoutMs,
-        budget: flags.budget ?? envNumber("NICEEVAL_BUDGET") ?? exp.budget,
+        timeoutMs: flags.timeout ?? exp.timeoutMs ?? config.timeoutMs,
+        budget: flags.budget ?? exp.budget,
         selectedEvalIds,
         experimentId: exp.id,
         description: exp.description,
@@ -1011,7 +1017,6 @@ async function main(): Promise<void> {
   const sandboxDefaultConcurrency = resolvedSandboxRecommendedConcurrency(evals, agentRuns, config.sandbox);
   const maxConcurrency =
     flags.maxConcurrency ??
-    envNumber("NICEEVAL_MAX_CONCURRENCY") ??
     config.maxConcurrency ??
     sandboxDefaultConcurrency;
 

package/src/i18n/en.ts

@@ -83,12 +83,11 @@ export const en = {
   "runner.dispatchHaltedExperiment": "experiment halted (dispatch-halted): {{message}}\n",
   "runner.dispatchHaltedEval": "eval halted: {{message}}\n",
   "judge.modelMissing":
-    "No judge model configured. Set it in defineConfig({ judge: { model: \"...\" } }), the eval's judge config, or the NICEEVAL_JUDGE_MODEL environment variable (there is no built-in default model).\n" +
+    "No judge model configured. Set it in defineConfig({ judge: { model: \"...\" } }) or the eval's judge config (there is no built-in default model, and no environment variable for it).\n" +
     "  Docs: node_modules/niceeval/docs-site/zh/tutorials/scoring-guide.mdx",
   "loaders.yamlMissing":
     "loadYaml(\"{{path}}\") needs a YAML parser: run `pnpm add yaml` first (or switch to loadJson with a JSON dataset).",
   "cli.flag.parseError": "{{message}}\nRun `niceeval --help` for usage.\n",
-  "cli.envInvalidNumber": "Environment variable {{name}} is not a number: \"{{value}}\".\n",
   "cli.help":
     "niceeval — agent-native evals\n\n" +
     "Usage:\n" +
@@ -142,8 +141,9 @@ export const en = {
     "  --json  (machine feed: NDJSON on stdout; default is human text)\n" +
     "  --junit path  --out dir  --port n  --open / --no-open  -h, --help  -v, --version\n\n" +
     "Positional args only select which evals to run (id prefixes); which agent and\n" +
-    "how to run come from experiments/ + flags. Env overrides (flag > env > config):\n" +
-    "  NICEEVAL_RUNS  NICEEVAL_MAX_CONCURRENCY  NICEEVAL_TIMEOUT  NICEEVAL_BUDGET\n",
+    "how to run come from experiments/ + flags. Resolution: flag > experiment >\n" +
+    "niceeval.config.ts > built-in default. Configuration has no environment layer;\n" +
+    "environment variables hold credentials such as API keys.\n",
   "cli.show.noResults": "No results found under {{root}}. Run `niceeval exp` first, then `niceeval show`.\n",
   "cli.show.runDirMissing": "Results directory not found: {{dir}}\n",
   "cli.show.noEvalMatch": "No results matched: {{patterns}}. Evals with results: {{evals}}\n",
@@ -317,7 +317,7 @@ export const en = {
   "hitl.respondAllEmpty": "There is no pending input.requested request; respond() / respondAll() cannot work. Confirm the turn parked with t.parked(), then answer via t.requireInputRequest() or t.respond().",
   "hitl.respondEmpty": "t.respond(...) requires at least one answer.",
   "hitl.stringAmbiguous": "There are {{count}} pending input requests; a plain-string answer cannot be matched to one. Use the { request, optionId } or { request, text } object form to name it explicitly.",
-  "judge.apiKeyMissing": "judge is missing an API key (CODEX_API_KEY / OPENAI_API_KEY).",
+  "judge.apiKeyMissing": "judge is missing an API key: set NICEEVAL_JUDGE_KEY, or point judge.apiKeyEnv at another environment variable.",
   "judge.httpError": "judge HTTP {{status}}: {{body}}",
   "judge.probeFailed": "judge precheck failed ({{model}}): {{error}}",
   "judge.probeTimeout": "judge precheck timed out after {{seconds}}s ({{model}}): the endpoint accepted the connection but never responded — check the judge baseUrl / gateway, or point NICEEVAL_JUDGE_BASE at a responsive one",

package/src/i18n/index.ts

@@ -1,4 +1,7 @@
-// CLI 侧 i18n:内核(插值/归一)在 core.ts;这里只注入 env 来源与 zh-CN 默认值。
+// CLI 侧 i18n:内核(插值/归一)在 core.ts;这里只注入来源(config.locale + 系统 locale)与
+// zh-CN 默认值。界面语言是配置,家在 `defineConfig({ locale })`;系统 locale 是「输出到哪个
+// 终端」的环境事实,只作没配时的判定依据。niceeval 自己不发明 NICEEVAL_LANG 这类配置变量
+// (边界见 docs/architecture.md「配置从代码来,凭据从环境来」)。
 
 import { en } from "./en.ts";
 import { zhCN, type MessageKey, type Messages } from "./zh-CN.ts";
@@ -11,10 +14,20 @@ const dictionaries: Record<Locale, Messages> = {
   en,
 };
 
+/** `defineConfig({ locale })` 的归一结果;CLI 装载配置后调 setConfiguredLocale 注入一次。 */
+let configuredLocale: Locale | undefined;
+
+/**
+ * 注入项目配置声明的界面语言。传 undefined(没配 / 没有配置文件)时清空,回到系统 locale 判定。
+ * 无法归一的值(如 "C")同样按未声明处理——不为一个装饰性设置让命令失败。
+ */
+export function setConfiguredLocale(raw: string | undefined): void {
+  configuredLocale = normalizeLocale(raw);
+}
+
 export function detectLocale(env: NodeJS.ProcessEnv = process.env): Locale {
   return (
-    normalizeLocale(env.NICEEVAL_LANG) ??
-    normalizeLocale(env.NICEEVAL_LOCALE) ??
+    configuredLocale ??
     normalizeLocale(env.LC_ALL) ??
     normalizeLocale(env.LC_MESSAGES) ??
     normalizeLocale(env.LANG) ??

package/src/i18n/locale.test.ts

@@ -0,0 +1,41 @@
+// cases: docs/engineering/testing/unit/experiments-runner.md
+// 界面语言的取值链(「界面语言的取值链」类别):config.locale → 系统 locale
+// (LC_ALL → LC_MESSAGES → LANG)→ zh-CN。语言是配置,家在 defineConfig({ locale });
+// 系统 locale 只是「输出到哪个终端」的环境事实,niceeval 不再自备 NICEEVAL_LANG /
+// NICEEVAL_LOCALE 这类配置变量(边界见 docs/architecture.md「配置从代码来,凭据从环境来」)。
+
+import { afterEach, describe, expect, it } from "vitest";
+import { detectLocale, setConfiguredLocale } from "./index.ts";
+
+afterEach(() => {
+  setConfiguredLocale(undefined);
+});
+
+describe("界面语言的取值链", () => {
+  // 系统环境全是中文,config 说 en —— 取 en。反过来的错误实现(环境优先)会给出 zh-CN。
+  it("config.locale 压过系统 locale", () => {
+    setConfiguredLocale("en");
+    expect(detectLocale({ LC_ALL: "zh_CN.UTF-8", LANG: "zh_CN.UTF-8" })).toBe("en");
+  });
+
+  it("config.locale 未声明时按 LC_ALL → LC_MESSAGES → LANG 逐级回落", () => {
+    expect(detectLocale({ LC_ALL: "en_US.UTF-8", LC_MESSAGES: "zh_CN.UTF-8", LANG: "zh_CN.UTF-8" })).toBe("en");
+    expect(detectLocale({ LC_MESSAGES: "en_US.UTF-8", LANG: "zh_CN.UTF-8" })).toBe("en");
+    expect(detectLocale({ LANG: "en_US.UTF-8" })).toBe("en");
+    expect(detectLocale({})).toBe("zh-CN");
+  });
+
+  // C / POSIX 是「未指定语言」,不是一种语言:该跳过它去看下一个候选,而不是当成非中文落 en。
+  it("无法归一的值按未声明处理,继续往下找", () => {
+    expect(detectLocale({ LC_ALL: "C", LANG: "zh_CN.UTF-8" })).toBe("zh-CN");
+    setConfiguredLocale("POSIX");
+    expect(detectLocale({ LANG: "zh_CN.UTF-8" })).toBe("zh-CN");
+  });
+
+  // 旧的 niceeval 专有变量已经不是取值链的一环:摆在环境里也不该改变结果。
+  it("NICEEVAL_LANG / NICEEVAL_LOCALE 不参与判定", () => {
+    expect(detectLocale({ NICEEVAL_LANG: "en", NICEEVAL_LOCALE: "en", LANG: "zh_CN.UTF-8" })).toBe("zh-CN");
+    setConfiguredLocale("en");
+    expect(detectLocale({ NICEEVAL_LANG: "zh-CN" })).toBe("en");
+  });
+});

package/src/i18n/zh-CN.ts

@@ -80,12 +80,11 @@ export const zhCN = {
   "runner.dispatchHaltedExperiment": "实验已止损(dispatch-halted):{{message}}\n",
   "runner.dispatchHaltedEval": "eval 已止损:{{message}}\n",
   "judge.modelMissing":
-    "judge 未配置模型:在 defineConfig({ judge: { model: \"...\" } })、eval 的 judge 配置或环境变量 NICEEVAL_JUDGE_MODEL 里指定裁判模型(没有内置默认模型)。\n" +
+    "judge 未配置模型:在 defineConfig({ judge: { model: \"...\" } }) 或 eval 的 judge 配置里指定裁判模型(没有内置默认模型,也没有对应的环境变量)。\n" +
     "  文档:node_modules/niceeval/docs-site/zh/tutorials/scoring-guide.mdx",
   "loaders.yamlMissing":
     "loadYaml(\"{{path}}\") 需要 YAML 解析器:请先 `pnpm add yaml`(或改用 loadJson + JSON 数据集)。",
   "cli.flag.parseError": "{{message}}\n运行 `niceeval --help` 查看用法。\n",
-  "cli.envInvalidNumber": "环境变量 {{name}} 不是数字:\"{{value}}\"。\n",
   "cli.help":
     "niceeval — agent-native evals\n\n" +
     "用法:\n" +
@@ -134,8 +133,8 @@ export const zhCN = {
     "  --json  (机器面:stdout 上的 NDJSON 事件流;默认是人读文本)\n" +
     "  --junit path  --out dir  --port n  --open / --no-open  -h, --help  -v, --version\n\n" +
     "位置参数只选「跑哪些 eval」(id 前缀);对着哪个 agent、怎么跑来自 experiments/ 与\n" +
-    "标志。环境变量覆盖(标志 > 环境变量 > config):\n" +
-    "  NICEEVAL_RUNS  NICEEVAL_MAX_CONCURRENCY  NICEEVAL_TIMEOUT  NICEEVAL_BUDGET\n",
+    "标志。取值优先级:标志 > experiment > niceeval.config.ts > 内置默认;配置项没有\n" +
+    "环境变量层,环境变量只放 API key 这类凭据。\n",
   // show 的错误文案保持英文(错误文案英文的仓库约定);noResults 是提示,翻译。
   "cli.show.noResults": "{{root}} 下没有结果。先 `niceeval exp` 跑一轮,再 `niceeval show`。\n",
   "cli.show.runDirMissing": "Results directory not found: {{dir}}\n",
@@ -310,7 +309,7 @@ export const zhCN = {
   "hitl.respondAllEmpty": "没有待回答的 input.requested 请求,respond() / respondAll() 无法工作;先用 t.parked() 确认停轮,再用 t.requireInputRequest() 或 t.respond() 回答。",
   "hitl.respondEmpty": "t.respond(...) 至少需要一个回答。",
   "hitl.stringAmbiguous": "有 {{count}} 条待回答请求,字符串回答无法对位,请用 { request, optionId } 或 { request, text } 对象形式显式指名。",
-  "judge.apiKeyMissing": "judge 缺少 API key(CODEX_API_KEY / OPENAI_API_KEY)。",
+  "judge.apiKeyMissing": "judge 缺少 API key:设置 NICEEVAL_JUDGE_KEY,或用 judge.apiKeyEnv 指向别的环境变量。",
   "judge.httpError": "judge HTTP {{status}}: {{body}}",
   "judge.probeFailed": "judge 预检失败({{model}}): {{error}}",
   "judge.probeTimeout": "judge 预检 {{seconds}}s 超时({{model}}):端点接受了连接但一直不回 —— 检查 judge 的 baseUrl / 网关,或把 NICEEVAL_JUDGE_BASE 指向一个有响应的网关",

package/src/report/assets/styles.css

@@ -56,9 +56,10 @@
 
 /* ---- AttemptList:实体列表的叶子层,一条卡片一个 Attempt ---- */
 .nre-attempt-list .nre-attempts { list-style:none; margin:0; padding:0; }
-.nre-attempt-list .nre-attempt { border:1px solid var(--line); border-left:3px solid var(--line-strong); border-radius:8px; padding:10px 14px; margin-bottom:8px; background:var(--panel); }
+.nre-attempt-list .nre-attempt { border:1px solid var(--line); border-radius:8px; padding:10px 14px; margin-bottom:8px; background:var(--panel); }
+/* 只有 failed/errored 留左边语义色条;其余靠 hairline,避免每行都像 callout */
 .nre-attempt-list .nre-attempt-failed,
-.nre-attempt-list .nre-attempt-errored { border-left-color: var(--bad); }
+.nre-attempt-list .nre-attempt-errored { border-left: 3px solid var(--bad); }
 .nre-attempt-list .nre-attempt-head { display:flex; flex-wrap:wrap; gap:.75em; align-items:baseline; }
 .nre-attempt-list .nre-attempt-eval { font-weight:620; }
 .nre-attempt-list .nre-attempt-experiment,
@@ -336,9 +337,8 @@ table.nre,
 .nre-scope-summary .nre-scope-kpi:last-child { border-right: 0; }
 .nre-scope-summary .nre-scope-kpi dt {
   color: var(--soft);
-  font-size: 11px;
-  text-transform: uppercase;
-  letter-spacing: 0.08em;
+  font-size: 12px;
+  font-weight: 550;
 }
 .nre-scope-summary .nre-scope-kpi dd {
   margin: 6px 0 0;
@@ -949,13 +949,13 @@ table.nre,
   letter-spacing: 0.04em;
 }
 
-/* Error 与断言:同一套左侧语义边和可展开明细。 */
+/* Error 与断言:中性底 + 失败左边条;可展开明细。 */
 .nre-attempt-error {
   overflow: hidden;
-  border: 1px solid color-mix(in oklch, var(--bad), var(--line) 64%);
+  border: 1px solid var(--line);
   border-left: 3px solid var(--bad);
   border-radius: 9px;
-  background: color-mix(in oklch, var(--bad), var(--panel) 95%);
+  background: var(--panel);
 }
 .nre-attempt-error .nre-attempt-error-fields {
   display: grid;
@@ -980,8 +980,8 @@ table.nre,
   overflow: auto;
   margin: 0;
   padding: 12px 15px;
-  border-top: 1px solid color-mix(in oklch, var(--bad), var(--line) 70%);
-  background: color-mix(in oklch, var(--bad), var(--panel-2) 96%);
+  border-top: 1px solid var(--line);
+  background: var(--panel-2);
   color: var(--muted);
   font: 12px/1.55 ui-monospace, "SFMono-Regular", Consolas, "Liberation Mono", monospace;
   white-space: pre-wrap;
@@ -996,10 +996,14 @@ table.nre,
 .nre-attempt-source .nre-source-line-detail .nre-assertion-row {
   overflow: hidden;
   border: 1px solid var(--line);
-  border-left: 3px solid var(--line-strong);
   border-radius: 8px;
   background: var(--panel);
 }
+/* 只有 gate failed(tone-bad)留左边色条;soft/passed/na 用 hairline */
+.nre-attempt-assertions .nre-assertion-row:has(.nre-tone-bad),
+.nre-attempt-source .nre-source-line-detail .nre-assertion-row.nre-tone-bad {
+  border-left: 3px solid var(--bad);
+}
 .nre-attempt-assertions .nre-assertion-row > summary {
   display: flex;
   flex-wrap: wrap;
@@ -1358,12 +1362,10 @@ table.nre,
 .nre-attempt-source .nre-attempt-source-unlocated > .nre-source-turn {
   overflow: hidden;
   border: 1px solid var(--line);
-  border-left: 3px solid var(--blue, var(--nre-c0));
   border-radius: 8px;
   background: var(--panel-2);
 }
-.nre-attempt-source .nre-attempt-source-unlocated > .nre-source-turn-failed { border-left-color: var(--bad); }
-.nre-attempt-source .nre-attempt-source-unlocated > .nre-source-turn-waiting { border-left-color: var(--warn); }
+.nre-attempt-source .nre-attempt-source-unlocated > .nre-source-turn-failed { border-left: 3px solid var(--bad); }
 
 /* Other conversation(unlocated turns):TurnDetail 在这里复用 AttemptConversation 同一套回复
    renderer(showMeta/showSent 都为真,没有可依附的 send 行),但 .nre-conv-* 的规则此前只覆盖了

package/src/runner/feedback/io.ts

@@ -33,7 +33,7 @@ export interface FeedbackClock {
 export interface FeedbackIO {
   readonly stdout: FeedbackStream;
   readonly stderr: FeedbackStream;
-  /** 只读环境变量面(profile 自动检测的 CI 标记、NICEEVAL_LANG 等都从这里读,不直接碰
+  /** 只读环境变量面(profile 自动检测的 CI 标记、NO_COLOR 等都从这里读,不直接碰
    *  process.env),同样是为了让 profile.ts 的纯函数可测。 */
   readonly env: Readonly<Record<string, string | undefined>>;
   readonly clock: FeedbackClock;

package/src/runner/types.ts

@@ -323,7 +323,7 @@ export interface InvocationShape {
   configs: number;
   /** 总 attempt 数(evals × configs × runs);逐行输出与汇总计数都按它。 */
   totalAttempts: number;
-  /** 本次运行实际生效的全局并发数(flag/env/config/sandbox 默认值解析后的结果);
+  /** 本次运行实际生效的全局并发数(flag/config/sandbox 默认值解析后的结果);
    *  实验级 maxConcurrency 只在该实验内部限流,不改这个全局值。 */
   maxConcurrency: number;
   /**
@@ -643,6 +643,11 @@ export interface Config {
    * 可传字符串,或按 locale 提供多语言(如 `{ en: "...", "zh-CN": "..." }`),随 view 语言切换。
    */
   name?: LocalizedText;
+  /**
+   * CLI 与运行时文案的界面语言(BCP 47,如 `"en"` / `"zh-CN"`);CI 里想让日志恒定一种语言就写这个。
+   * 省略则按系统 locale(`LC_ALL` / `LC_MESSAGES` / `LANG`)判定,都没有时用 `zh-CN`。
+   */
+  locale?: string;
   /** 项目级默认 Sandbox provider(docker / vercel / e2b / custom);experiment 可覆盖。 */
   sandbox?: SandboxOption;
   /** 上传进 Sandbox 的工作区根目录,省略则用项目根;评估用例的 sandbox 视图从这里起步。 */
@@ -651,7 +656,7 @@ export interface Config {
   judge?: JudgeConfig;
   /** 项目级默认 reporter 列表(如落盘 / 上传结果);EvalDef.reporters 会与它合并。 */
   reporters?: Reporter[];
-  /** 项目级默认并发上限;CLI flag / env / experiment 的同名设置优先级更高。 */
+  /** 项目级默认并发上限;CLI flag / experiment 的同名设置优先级更高(没有环境变量层)。 */
   maxConcurrency?: number;
   /** 项目级默认单次 attempt 超时(毫秒);CLI flag / experiment / EvalDef 的同名设置优先级更高。 */
   timeoutMs?: number;