niceeval 0.11.1-canary.8 → 0.11.1

package/INDEX.md

@@ -20,6 +20,7 @@
 - `docs-site/zh/tutorials/agent-onboarding.mdx` — Coding Agent 从零接入项目:给 Coding Agent 的完整接入流程：探索项目、与用户确认路径、配置 Judge、写出 Adapter / Experiment / 评估用例并跑通第一个实验。
 - `docs-site/zh/tutorials/authoring.mdx` — 编写评估用例: 单轮、多轮和数据集模式:用 defineEval 编写评估用例，包括单轮对话、多轮对话、数据驱动测试、Sandbox Workspace 和评估的生命周期与 Fixture。
 - `docs-site/zh/tutorials/ci-integration.mdx` — 在 GitHub Actions 和 CI 中运行 NiceEval:把 NiceEval 接入 GitHub Actions 或任意 CI。评估用例失败时非零退出，输出 JUnit XML，并通过缓存加速重复运行。
+- `docs-site/zh/tutorials/configuration.mdx` — 把配置和密钥各放到该放的地方:跑几次、超时、并发、judge、语言这些值写进代码的哪一层，API key 和 provider token 用哪些环境变量。
 - `docs-site/zh/tutorials/connect-otel.mdx` — OTel 接入:把应用已有的 OTel span 发送给 NiceEval，在 niceeval view 中查看每轮调用瀑布图；评估用例断言仍以 Send 返回的事件和用量为准。
 - `docs-site/zh/tutorials/connect-your-agent.mdx` — 接入你的 Agent:写一个 Adapter、配置一个 Experiment，并运行第一条评估用例；再把配置和参数从 Experiment 传给 Adapter 与被测应用。
 - `docs-site/zh/tutorials/custom-reports.mdx` — 编写自定义报告:用 defineReport、内置报告组件和双面组件编写一份同时用于 niceeval show 与 niceeval view 的自定义报告。

package/dist/i18n/en.d.ts

@@ -63,7 +63,6 @@ export declare const en: {
     "judge.modelMissing": string;
     "loaders.yamlMissing": string;
     "cli.flag.parseError": string;
-    "cli.envInvalidNumber": string;
     "cli.help": string;
     "cli.show.noResults": string;
     "cli.show.runDirMissing": string;

package/dist/i18n/en.js

@@ -65,11 +65,10 @@ export const en = {
     "runner.gateLeaseWaiting": "waiting on another run for experiment {{experimentId}}'s concurrency slots: all {{effectiveN}} in use ({{holders}}). Concurrent runs share this experiment's slots, and the smallest maxConcurrency in play wins — this run declared {{declaredN}}. Nothing dispatches until a slot frees up; the other run's slots release when its attempts finish, or 30s after it dies.\n",
     "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" +
+    "judge.modelMissing": "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" +
         "  niceeval exp [path|experiment] [eval-id-prefix…]    run experiments\n" +
@@ -122,8 +121,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",
@@ -274,7 +274,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/dist/i18n/index.d.ts

@@ -1,5 +1,10 @@
 import { type MessageKey } from "./zh-CN.ts";
 import { type Locale, type Vars } from "./core.ts";
 export type { Locale, Vars } from "./core.ts";
+/**
+ * 注入项目配置声明的界面语言。传 undefined(没配 / 没有配置文件)时清空,回到系统 locale 判定。
+ * 无法归一的值(如 "C")同样按未声明处理——不为一个装饰性设置让命令失败。
+ */
+export declare function setConfiguredLocale(raw: string | undefined): void;
 export declare function detectLocale(env?: NodeJS.ProcessEnv): Locale;
 export declare function t(key: MessageKey, vars?: Vars): string;

package/dist/i18n/index.js

@@ -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.js";
 import { zhCN } from "./zh-CN.js";
 import { interpolate, normalizeLocale } from "./core.js";
@@ -6,9 +9,17 @@ const dictionaries = {
     "zh-CN": zhCN,
     en,
 };
+/** `defineConfig({ locale })` 的归一结果;CLI 装载配置后调 setConfiguredLocale 注入一次。 */
+let configuredLocale;
+/**
+ * 注入项目配置声明的界面语言。传 undefined(没配 / 没有配置文件)时清空,回到系统 locale 判定。
+ * 无法归一的值(如 "C")同样按未声明处理——不为一个装饰性设置让命令失败。
+ */
+export function setConfiguredLocale(raw) {
+    configuredLocale = normalizeLocale(raw);
+}
 export function detectLocale(env = process.env) {
-    return (normalizeLocale(env.NICEEVAL_LANG) ??
-        normalizeLocale(env.NICEEVAL_LOCALE) ??
+    return (configuredLocale ??
         normalizeLocale(env.LC_ALL) ??
         normalizeLocale(env.LC_MESSAGES) ??
         normalizeLocale(env.LANG) ??

package/dist/i18n/zh-CN.d.ts

@@ -63,7 +63,6 @@ export declare const zhCN: {
     readonly "judge.modelMissing": string;
     readonly "loaders.yamlMissing": "loadYaml(\"{{path}}\") 需要 YAML 解析器:请先 `pnpm add yaml`(或改用 loadJson + JSON 数据集)。";
     readonly "cli.flag.parseError": "{{message}}\n运行 `niceeval --help` 查看用法。\n";
-    readonly "cli.envInvalidNumber": "环境变量 {{name}} 不是数字:\"{{value}}\"。\n";
     readonly "cli.help": string;
     readonly "cli.show.noResults": "{{root}} 下没有结果。先 `niceeval exp` 跑一轮,再 `niceeval show`。\n";
     readonly "cli.show.runDirMissing": "Results directory not found: {{dir}}\n";
@@ -206,7 +205,7 @@ export declare const zhCN: {
     readonly "hitl.respondAllEmpty": "没有待回答的 input.requested 请求,respond() / respondAll() 无法工作;先用 t.parked() 确认停轮,再用 t.requireInputRequest() 或 t.respond() 回答。";
     readonly "hitl.respondEmpty": "t.respond(...) 至少需要一个回答。";
     readonly "hitl.stringAmbiguous": "有 {{count}} 条待回答请求,字符串回答无法对位,请用 { request, optionId } 或 { request, text } 对象形式显式指名。";
-    readonly "judge.apiKeyMissing": "judge 缺少 API key(CODEX_API_KEY / OPENAI_API_KEY)。";
+    readonly "judge.apiKeyMissing": "judge 缺少 API key:设置 NICEEVAL_JUDGE_KEY,或用 judge.apiKeyEnv 指向别的环境变量。";
     readonly "judge.httpError": "judge HTTP {{status}}: {{body}}";
     readonly "judge.probeFailed": "judge 预检失败({{model}}): {{error}}";
     readonly "judge.probeTimeout": "judge 预检 {{seconds}}s 超时({{model}}):端点接受了连接但一直不回 —— 检查 judge 的 baseUrl / 网关,或把 NICEEVAL_JUDGE_BASE 指向一个有响应的网关";

package/dist/i18n/zh-CN.js

@@ -65,11 +65,10 @@ export const zhCN = {
     "runner.gateLeaseWaiting": "在等别的运行让出实验 {{experimentId}} 的并发名额:生效的 {{effectiveN}} 个位子全被占着({{holders}})。并行运行共用同一实验的名额,生效值取在场声明里最小的那个——本次运行声明的是 {{declaredN}}。名额腾出来之前不会派发任何 attempt;对方的名额会在它的 attempt 跑完时释放,它若已死则 30s 后过期被接管。\n",
     "runner.dispatchHaltedExperiment": "实验已止损(dispatch-halted):{{message}}\n",
     "runner.dispatchHaltedEval": "eval 已止损:{{message}}\n",
-    "judge.modelMissing": "judge 未配置模型:在 defineConfig({ judge: { model: \"...\" } })、eval 的 judge 配置或环境变量 NICEEVAL_JUDGE_MODEL 里指定裁判模型(没有内置默认模型)。\n" +
+    "judge.modelMissing": "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" +
         "  niceeval exp [路径|实验] [eval-id 前缀…]   跑实验\n" +
@@ -117,8 +116,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",
@@ -270,7 +269,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/dist/runner/types.d.ts

@@ -280,7 +280,7 @@ export interface InvocationShape {
     configs: number;
     /** 总 attempt 数(evals × configs × runs);逐行输出与汇总计数都按它。 */
     totalAttempts: number;
-    /** 本次运行实际生效的全局并发数(flag/env/config/sandbox 默认值解析后的结果);
+    /** 本次运行实际生效的全局并发数(flag/config/sandbox 默认值解析后的结果);
      *  实验级 maxConcurrency 只在该实验内部限流,不改这个全局值。 */
     maxConcurrency: number;
     /**
@@ -615,6 +615,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 视图从这里起步。 */
@@ -623,7 +628,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;

package/docs-site/zh/examples/integrations/langgraph.mdx

@@ -19,7 +19,7 @@ description: "一个纯 Python LangGraph + LangSmith OTel 导出的应用，接
 
 接入的全部代码变更（生成时从两个目录实测统计）：
 
-<table className="gd-summary"><tbody><tr><th>{"类别"}</th><th>{"文件数"}</th><th>{"行数"}</th></tr><tr><td>{"评估用例侧 TS 项目脚手架（必要：被测应用是 Python，全新文件）"}</td><td>{"3"}</td><td>{"+42"}</td></tr><tr><td>{"adapter（必要：传输粘合，协议映射在官方包里）"}</td><td>{"2"}</td><td>{"+182"}</td></tr><tr><td>{"evals 与 experiments（评测内容，按需增长）"}</td><td>{"6"}</td><td>{"+118"}</td></tr><tr className="gd-total"><td>{"合计"}</td><td>{"11"}</td><td>{"+342"}</td></tr></tbody></table>
+<table className="gd-summary"><tbody><tr><th>{"类别"}</th><th>{"文件数"}</th><th>{"行数"}</th></tr><tr><td>{"评估用例侧 TS 项目脚手架（必要：被测应用是 Python，全新文件）"}</td><td>{"3"}</td><td>{"+42"}</td></tr><tr><td>{"adapter（必要：传输粘合，协议映射在官方包里）"}</td><td>{"2"}</td><td>{"+181"}</td></tr><tr><td>{"evals 与 experiments（评测内容，按需增长）"}</td><td>{"6"}</td><td>{"+118"}</td></tr><tr className="gd-total"><td>{"合计"}</td><td>{"11"}</td><td>{"+341"}</td></tr></tbody></table>
 
 ## 文件清单
 
@@ -67,9 +67,9 @@ langgraph/
 ## 新增的 adapter、evals 与 experiments
 
 <div className="gd-file">
-<div className="gd-head"><span className="gd-name">{"niceeval.config.ts"}</span><span className="gd-stats"><span className="gd-plus">{"+14"}</span></span></div>
+<div className="gd-head"><span className="gd-name">{"niceeval.config.ts"}</span><span className="gd-stats"><span className="gd-plus">{"+13"}</span></span></div>
 <div className="gd-body">
-<table className="gd-table"><tbody><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"1"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt4">{"import"}</span><span className="gdt0">{" { defineConfig } "}</span><span className="gdt4">{"from"}</span><span className="gdt0">{" "}</span><span className="gdt2">{"\"niceeval\""}</span><span className="gdt0">{";"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"2"}</td><td className="gd-sign">{"+"}</td><td className="gd-code">{" "}</td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"3"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt6">{"// 注:这个 app 的 .env 把标准的 OPENAI_API_KEY / OPENAI_BASE_URL 挪用给了 DeepSeek"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"4"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt6">{"// (agent.py 里 ChatOpenAI 直接读这两个 env 名)。niceeval 的 judge(t.judge.autoevals.*)"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"5"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt6">{"// 兜底链路最后也会读这两个名字,和应用自己的凭证会撞车——真的要用 judge 时在 .env 里另配"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"6"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt6">{"// NICEEVAL_JUDGE_KEY / NICEEVAL_JUDGE_BASE(judge.ts 里优先级最高),judge 走独立凭证,"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"7"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt6">{"// 不和应用的模型配置互相干扰。"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"8"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt4">{"export"}</span><span className="gdt0">{" "}</span><span className="gdt4">{"default"}</span><span className="gdt0">{" "}</span><span className="gdt5">{"defineConfig"}</span><span className="gdt0">{"({"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"9"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"  name: { "}</span><span className="gdt2">{"\"zh-CN\""}</span><span className="gdt0">{": "}</span><span className="gdt2">{"\"LangGraph 示例\""}</span><span className="gdt0">{", en: "}</span><span className="gdt2">{"\"LangGraph example\""}</span><span className="gdt0">{" },"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"10"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"  judge: { model: "}</span><span className="gdt2">{"\"gpt-5.4\""}</span><span className="gdt0">{" },"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"11"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"  timeoutMs: "}</span><span className="gdt1">{"120_000"}</span><span className="gdt0">{","}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"12"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"  "}</span><span className="gdt6">{"// 被测应用是用户自己起的长驻服务,别开太高并发。"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"13"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"  maxConcurrency: "}</span><span className="gdt1">{"2"}</span><span className="gdt0">{","}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"14"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"});"}</span></td></tr></tbody></table>
+<table className="gd-table"><tbody><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"1"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt4">{"import"}</span><span className="gdt0">{" { defineConfig } "}</span><span className="gdt4">{"from"}</span><span className="gdt0">{" "}</span><span className="gdt2">{"\"niceeval\""}</span><span className="gdt0">{";"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"2"}</td><td className="gd-sign">{"+"}</td><td className="gd-code">{" "}</td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"3"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt6">{"// 注:这个 app 的 .env 把标准的 OPENAI_API_KEY / OPENAI_BASE_URL 挪用给了 DeepSeek"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"4"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt6">{"// (agent.py 里 ChatOpenAI 直接读这两个 env 名)。niceeval 的 judge(t.judge.autoevals.*)"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"5"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt6">{"// 不碰这两个名字:端点写在 judge.baseUrl,key 只读 NICEEVAL_JUDGE_KEY(或 judge.apiKeyEnv"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"6"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt6">{"// 指定的变量名),judge 走独立凭证,不和应用的模型配置互相干扰。"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"7"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt4">{"export"}</span><span className="gdt0">{" "}</span><span className="gdt4">{"default"}</span><span className="gdt0">{" "}</span><span className="gdt5">{"defineConfig"}</span><span className="gdt0">{"({"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"8"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"  name: { "}</span><span className="gdt2">{"\"zh-CN\""}</span><span className="gdt0">{": "}</span><span className="gdt2">{"\"LangGraph 示例\""}</span><span className="gdt0">{", en: "}</span><span className="gdt2">{"\"LangGraph example\""}</span><span className="gdt0">{" },"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"9"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"  judge: { model: "}</span><span className="gdt2">{"\"gpt-5.4\""}</span><span className="gdt0">{" },"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"10"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"  timeoutMs: "}</span><span className="gdt1">{"120_000"}</span><span className="gdt0">{","}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"11"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"  "}</span><span className="gdt6">{"// 被测应用是用户自己起的长驻服务,别开太高并发。"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"12"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"  maxConcurrency: "}</span><span className="gdt1">{"2"}</span><span className="gdt0">{","}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"13"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"});"}</span></td></tr></tbody></table>
 </div>
 </div>
 

package/docs-site/zh/explanation/judge.mdx

@@ -83,7 +83,7 @@ defineEval({
 t.judge.autoevals.closedQA("rubric", { on: t.reply, model: "openai/gpt-4o" });
 ```
 
-三级都没配时，最后还会读环境变量 `NICEEVAL_JUDGE_MODEL`；连它也没有就是配置错误，调用点直接报错——judge 没有内置默认模型。
+三级都没配就是配置错误，调用点直接报错——judge 没有内置默认模型，也没有对应的环境变量（模型是配置，只从代码来）。
 
 ## 评判端点与 key：OpenAI 兼容协议
 
@@ -100,15 +100,17 @@ defineConfig({
 });
 ```
 
-`baseUrl` 和 key 都按从具体到笼统解析，配置字段优先、环境变量兜底：
+端点是配置，key 是凭据，两者的来源分开：
 
 | 项 | 解析顺序 |
 |---|---|
-| 端点 | `judge.baseUrl` → `NICEEVAL_JUDGE_BASE` → `CODEX_BASE_URL` → `OPENAI_BASE_URL` → `https://api.openai.com/v1` |
-| key | `judge.apiKeyEnv` 指定的环境变量 → `NICEEVAL_JUDGE_KEY` → `CODEX_API_KEY` → `OPENAI_API_KEY` |
+| 端点 | `judge.baseUrl` → `https://api.openai.com/v1` |
+| key | `judge.apiKeyEnv` 指定的环境变量 → `NICEEVAL_JUDGE_KEY` |
+
+接自己的网关或 OpenAI 兼容代理时把地址显式写进 `judge.baseUrl`——NiceEval 不去环境里翻 `OPENAI_BASE_URL` 这类变量猜端点。key 同理只读一个名字：`judge.apiKeyEnv` 指定的那个，或默认的 `NICEEVAL_JUDGE_KEY`；judge 有自己的凭据，不会借用被测应用或某个 agent 的 key。
 
 <Warning>
-  key 一个都解析不到时，judge 断言**静默跳过**——不报错、不记分，eval 照常跑。全绿不代表 judge 真的评过。配完 key 先跑一条带 `t.judge` 的 eval，在 `niceeval view` 里确认出现了 judge 分数。
+  模型或 key 解析不到时，这条 judge 断言记成 `unavailable`（带原因），不会静默消失：除非显式链了 `.optional()`，评不了就让这次 attempt 记 `errored`——评不出来的结论既不算通过，也不该算 agent 答错。配完 key 先跑一条带 `t.judge` 的 eval，在 `niceeval view` 里确认出现了 judge 分数。
 </Warning>
 
 ## 严重度：judge 默认 soft

package/docs-site/zh/explanation/runner.mdx

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

package/docs-site/zh/reference/cli.mdx

@@ -31,14 +31,17 @@ description: "NiceEval CLI 参考：exp、show、view、init、list 和 clean
 
 ## 输出语言
 
-[NiceEval](https://niceeval.com/) 的 CLI 和运行时文案支持本地化，不需要在 `niceeval.config.ts` 里加配置。需要固定输出语言时用环境变量：
+[NiceEval](https://niceeval.com/) 的 CLI 和运行时文案支持本地化。要固定输出语言（CI 日志尤其需要），写在 `niceeval.config.ts` 里：
 
-```bash
-NICEEVAL_LANG=en npx niceeval list
-NICEEVAL_LANG=zh-CN npx niceeval list
+```ts
+import { defineConfig } from "niceeval";
+
+export default defineConfig({
+  locale: "en",
+});
 ```
 
-检测顺序是 `NICEEVAL_LANG`、`NICEEVAL_LOCALE`、`LC_ALL`、`LC_MESSAGES`、`LANG`。以 `zh` 开头的值使用 `zh-CN`,其它语言使用 `en`;都没有时默认 `zh-CN`。这只影响终端/runtime 文案,不改变结果 JSON 里的机器字段,也不翻译 LLM judge prompt。
+没写 `locale` 时按系统 locale 判定，依次看 `LC_ALL`、`LC_MESSAGES`、`LANG`。以 `zh` 开头的值使用 `zh-CN`,其它语言使用 `en`;都没有时默认 `zh-CN`。这只影响终端/runtime 文案,不改变结果 JSON 里的机器字段,也不翻译 LLM judge prompt。
 
 ## `npx niceeval exp [path|config] [id-prefix...]`
 
@@ -193,20 +196,11 @@ npx niceeval show weather/brooklyn --history
 
 `--strict` 不是"更严格地报错"，而是改变软阈值断言的判定：`.atLeast(n)` 这类软阈值（`soft` severity）平时失败不会把整条评估用例判为 `failed`（只是记一条不达标的断言），加了 `--strict` 之后，软阈值没达标也会让整条评估用例的 verdict 计为 `failed`。CI 中推荐加上，避免"断言分数不够但评估用例显示通过"的情况被放过。
 
-## 环境变量覆盖
-
-以下环境变量对应部分 flag，用于不便传 CLI 参数的场景（如 CI 环境配置）：
-
-| 环境变量 | 对应 flag |
-|---|---|
-| `NICEEVAL_RUNS` | `--runs` |
-| `NICEEVAL_MAX_CONCURRENCY` | `--max-concurrency` |
-| `NICEEVAL_TIMEOUT` | `--timeout` |
-| `NICEEVAL_BUDGET` | `--budget` |
+## 环境变量只放凭据
 
-优先级从高到低：CLI flag > 环境变量 > experiment / `niceeval.config.ts` 里的值 > 内置默认值。四个环境变量都要求合法数字，解析失败会直接报错退出。
+跑几次、超时、并发、预算、judge 模型和端点、界面语言——这些都是配置，只从 CLI flag、`experiments/` 下的 experiment 文件和 `niceeval.config.ts` 读。优先级从高到低：CLI flag > experiment > `niceeval.config.ts` > 内置默认值。没有对应的环境变量，同一个值不会有第三条来路。
 
-[NiceEval](https://niceeval.com/) 还会在启动时自动加载 cwd 下的 `.env` 文件（不需要额外配置，也不覆盖已经存在的环境变量），常用于本地放 `ANTHROPIC_API_KEY` 这类鉴权信息，不用每次手动 `export`。
+环境变量留给凭据（API key、provider token）和终端环境（`NO_COLOR`、系统 locale）。每个 agent / sandbox / judge 只认自己那一个变量名，不会在环境里翻找其它 key；启动时自动加载 cwd 下的 `.env`（不覆盖已经存在的环境变量）。完整清单和迁移对照见[配置与环境变量](/zh/tutorials/configuration)。
 
 ## 退出码
 

package/docs-site/zh/reference/define-config.mdx

@@ -8,14 +8,18 @@ description: "defineConfig 参考：judge、reporters、并发、超时和 sandb
 
 ```ts
 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` 回到内置报告。写法与整套报告能力见[编写自定义报告](/zh/tutorials/custom-reports#设成项目默认)。
+
 ## Config 字段
 
 {/* GENERATED:BEGIN config-fields */}
@@ -31,6 +35,15 @@ name?: LocalizedText;
 项目名,显示在 `niceeval view` 顶部 hero(`<h1>`),省略则回退到通用标题。
 可传字符串,或按 locale 提供多语言(如 `{ en: "...", "zh-CN": "..." }`),随 view 语言切换。
 
+#### `locale`
+
+```ts
+locale?: string;
+```
+
+CLI 与运行时文案的界面语言(BCP 47,如 `"en"` / `"zh-CN"`);CI 里想让日志恒定一种语言就写这个。
+省略则按系统 locale(`LC_ALL` / `LC_MESSAGES` / `LANG`)判定,都没有时用 `zh-CN`。
+
 #### `sandbox`
 
 ```ts
@@ -69,7 +82,7 @@ reporters?: Reporter[];
 maxConcurrency?: number;
 ```
 
-项目级默认并发上限;CLI flag / env / experiment 的同名设置优先级更高。
+项目级默认并发上限;CLI flag / experiment 的同名设置优先级更高(没有环境变量层)。
 
 #### `timeoutMs`
 

package/docs-site/zh/troubleshooting/recover-after-kill.mdx

@@ -18,7 +18,7 @@ niceeval exp compare/bub-e2b memory/commit0
 - 只补跑缺的部分：`--runs 5` 已经落盘 3 次，就只再跑 2 次。
 - 被强杀的实验如果留了没做完的收尾，重跑会先补一次实验级 `teardown` 再开始，泄漏不会越积越多。
 - 判定为 `errored` 的 Attempt 不复用，照常重跑。
-- 想全部重来，加 `--force`。
+- 想全部重来，加 `--rerun all`。
 
 ## 收回没清理的 Sandbox 实例
 

package/docs-site/zh/tutorials/agent-feedback-loop.mdx

@@ -232,15 +232,15 @@ AI 通常按任务选择这些入口：
   </Step>
   <Step title="局部重跑并验证假设">
     ```bash
-    npx niceeval exp local weather/brooklyn --json --force
+    npx niceeval exp local weather/brooklyn --json --rerun all
     npx niceeval show weather/brooklyn
     ```
 
-    位置参数按评估用例 ID 前缀缩小实验范围。调试同一个失败时加 `--force`，确保刚才的修改真的触发一次新运行。然后用 `show` 验证判定、断言和证据是否按预期变化。
+    位置参数按评估用例 ID 前缀缩小实验范围。调试同一个失败时加 `--rerun all`，确保刚才的修改真的触发一次新运行。然后用 `show` 验证判定、断言和证据是否按预期变化。
   </Step>
   <Step title="全量确认没有回归">
     ```bash
-    npx niceeval exp local --json --force
+    npx niceeval exp local --json --rerun all
     npx niceeval show
     ```
 
@@ -275,25 +275,26 @@ Coding Agent 应从 `failure` / `error` 事件里取出 `locator`，再逐个运
 - `events.json` 是对话与工具调用事件，`trace.json` 是调用链，`diff.json` 是 Sandbox 文件变化。
 - 某类证据不存在时，对应文件不会生成。先以 `show` 的提示为准，不要假设每个目录都有全部文件。
 
-`show` 的默认结果可能合成自多次运行：每个 Experiment × 评估用例选择最新判定，因此局部重跑后仍能看到其它评估用例的旧结果。该视图用于查看每条评估用例的最新已知判定；同一版代码的整体结果必须通过一次 `--force` 全量运行确认。
+`show` 的默认结果可能合成自多次运行：每个 Experiment × 评估用例选择最新判定，因此局部重跑后仍能看到其它评估用例的旧结果。该视图用于查看每条评估用例的最新已知判定；同一版代码的整体结果必须通过一次 `--rerun all` 全量运行确认。
 
 ## 结果复用条件
 
-不传 `--force` 时，NiceEval 会比较当前指纹与最近结果。指纹由评估用例源码和运行配置组成，包括实验 ID、Agent、model、flags、Sandbox、timeout 与 strict 等设置。
+不传 `--rerun all` 时，NiceEval 会比较当前指纹与最近结果。指纹由评估用例源码和运行配置组成，包括实验 ID、Agent、model、flags、Sandbox、timeout 与 strict 等设置。
 
 | 最近结果与当前输入 | 本次行为 |
 | --- | --- |
 | 指纹相同，判定为 `passed` 或 `failed` | 携入旧结果，不重新执行 |
 | 指纹不同 | 重新执行 |
 | 最近结果为 `errored` 或 `skipped` | 重新执行 |
-| 使用 `--force` | 忽略旧结果，重新执行 |
+| 使用 `--rerun` | 只有 `passed` 携入，失败项重新执行 |
+| 使用 `--rerun all` | 忽略旧结果，全部重新执行 |
 
 被测程序的源码不在指纹里。修改实现后，即使行为已经变化，旧的 `passed` 或 `failed` 仍可能被复用。因此可以这样选择：
 
 - 只想重看已有结果：运行 `niceeval show`，不产生新费用。
 - 修改了评估用例或实验配置：直接重跑；指纹变化会触发对应任务。
-- 修改了被测程序：对受影响的评估用例使用 `--force`。
-- 准备结束本轮工作：对整个实验使用 `--force`，排除其它评估用例的回归。
+- 修改了被测程序，要复验失败项：加 `--rerun`。已通过的照常携入，不必先去找失败的评估用例 ID——失败面板的 `Retry:` 行给的就是这条命令。
+- 准备结束本轮工作：对整个实验使用 `--rerun all`，排除其它评估用例的回归。
 
 ## 设置自主迭代协议
 
@@ -306,9 +307,9 @@ Coding Agent 应从 `failure` / `error` 事件里取出 `locator`，再逐个运
 并按问题选择 --source、--execution、--timing 或 --diff；--timing 从 lifecycle 展开 setup/teardown
 hook、shell 命令、每轮 send 与可关联的 OTel model/tool，回答整个 Attempt 的时间花在哪里。
 写出失败原因的假设，并判断应该修改被测程序、
-Eval，还是实验环境。修改后用 --force 重跑对应 Eval，比较新的判定和证据。
+Eval，还是实验环境。修改后用 --rerun 重跑失败项，比较新的判定和证据。
 同一问题连续三轮没有新证据或改善时停止并汇报，不要为得到通过结果而放宽正确的断言。
-全部局部失败清零后，用 npx niceeval exp local --json --force 全量验证；退出码 0 才完成。
+全部局部失败清零后，用 npx niceeval exp local --json --rerun all 全量验证；退出码 0 才完成。
 ```
 
 真实 Agent 的运行可能产生费用。实验阶段可以加 `--budget <美元>` 限制本轮累计成本；预算只能限制单次命令，不能替代上面的停止条件。

package/docs-site/zh/tutorials/ci-integration.mdx

@@ -11,7 +11,7 @@ description: "把 NiceEval 接入 GitHub Actions 或任意 CI。评估用例失
 默认情况下，只要存在失败的 gate，[NiceEval](https://niceeval.com/) 将以非零状态码退出。CI 中通常使用 `--strict`，让失败更明确。
 
 ```bash
-NICEEVAL_LANG=en npx niceeval exp ci \
+npx niceeval exp ci \
   --strict \
   --junit .niceeval/junit.xml
 ```
@@ -38,7 +38,6 @@ jobs:
       - run: npm ci
       - run: npx niceeval exp ci --strict --junit .niceeval/junit.xml
         env:
-          NICEEVAL_LANG: en
           OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
           ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
 ```
@@ -90,7 +89,7 @@ NEXT
 需要机器解析运行事件（自建 annotation adapter、实时看板）时把这条命令加上 `--json`，得到同一套事实的 NDJSON 事件流，`start` 打头、`result` 收尾：
 
 ```bash
-NICEEVAL_LANG=en npx niceeval exp ci --strict --junit .niceeval/junit.xml --json
+npx niceeval exp ci --strict --junit .niceeval/junit.xml --json
 ```
 
 需要一份 JSON 汇总文件时不解析运行日志，运行后单独读结果面：