niceeval 0.11.0 → 0.11.1-canary.10

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;
@@ -134,6 +133,7 @@ export declare const en: {
     "define.experimentAgentRequired": string;
     "define.experimentFlagNotJson": string;
     "define.experimentLabelInvalid": string;
+    "define.experimentProvenanceFlagsInvalid": string;
     "define.experimentSetupNotFunction": string;
     "define.experimentClassifyFailureNotFunction": string;
     "define.experimentIdRejected": 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",
@@ -202,6 +202,7 @@ export const en = {
     "define.experimentAgentRequired": "defineExperiment requires agent.",
     "define.experimentFlagNotJson": "experiment.flags.{{key}} is not JSON-serializable (functions / undefined / cycles / bigint are not allowed); flags are persisted verbatim into result snapshots and must be plain JSON.",
     "define.experimentLabelInvalid": "experiment.labels.{{key}} must be a string or a finite number; labels are report-side grouping coordinates persisted verbatim into result snapshots.",
+    "define.experimentProvenanceFlagsInvalid": "experiment.provenanceFlags must be an array of flag key names (strings); it lists the flags recorded for provenance only, which stay out of the cache fingerprint.",
     "define.experimentSetupNotFunction": "experiment.setup must be a function ((ctx) => void); use experiment.teardown for cleanup; to prepare the in-sandbox environment per experiment, chain .setup() hooks on the sandbox spec instead.",
     "define.experimentClassifyFailureNotFunction": "experiment.classifyFailure must be a function ((failure) => FailureClass | undefined); it classifies failures that surface as third-party errors and must return undefined for anything it does not recognize.",
     "define.experimentIdRejected": "defineExperiment does not accept id; ids are derived from file paths.",
@@ -273,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";
@@ -134,6 +133,7 @@ export declare const zhCN: {
     readonly "define.experimentAgentRequired": "defineExperiment 需要 agent。";
     readonly "define.experimentFlagNotJson": "experiment.flags.{{key}} 不是可 JSON 序列化的值(函数 / undefined / 循环引用 / bigint 不允许);flags 会原样进入结果快照,必须是纯 JSON。";
     readonly "define.experimentLabelInvalid": "experiment.labels.{{key}} 必须是字符串或有限数字;labels 是报告侧的归类坐标,会原样进入结果快照。";
+    readonly "define.experimentProvenanceFlagsInvalid": "experiment.provenanceFlags 必须是 flag 键名(字符串)数组;它列出只作为出处记录、不进缓存指纹的那些 flag。";
     readonly "define.experimentSetupNotFunction": "experiment.setup 必须是函数((ctx) => void);要清理请挂 experiment.teardown;要按实验准备沙箱内环境请挂 sandbox spec 的 .setup() 钩子链。";
     readonly "define.experimentClassifyFailureNotFunction": "experiment.classifyFailure 必须是函数((failure) => FailureClass | undefined):它识别以第三方错误形态浮出的失败,认不出的一律返回 undefined 交给后续链路。";
     readonly "define.experimentIdRejected": "defineExperiment 不接受 id —— id 由文件路径推导。";
@@ -205,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",
@@ -198,6 +197,7 @@ export const zhCN = {
     "define.experimentAgentRequired": "defineExperiment 需要 agent。",
     "define.experimentFlagNotJson": "experiment.flags.{{key}} 不是可 JSON 序列化的值(函数 / undefined / 循环引用 / bigint 不允许);flags 会原样进入结果快照,必须是纯 JSON。",
     "define.experimentLabelInvalid": "experiment.labels.{{key}} 必须是字符串或有限数字;labels 是报告侧的归类坐标,会原样进入结果快照。",
+    "define.experimentProvenanceFlagsInvalid": "experiment.provenanceFlags 必须是 flag 键名(字符串)数组;它列出只作为出处记录、不进缓存指纹的那些 flag。",
     "define.experimentSetupNotFunction": "experiment.setup 必须是函数((ctx) => void);要清理请挂 experiment.teardown;要按实验准备沙箱内环境请挂 sandbox spec 的 .setup() 钩子链。",
     "define.experimentClassifyFailureNotFunction": "experiment.classifyFailure 必须是函数((failure) => FailureClass | undefined):它识别以第三方错误形态浮出的失败,认不出的一律返回 undefined 交给后续链路。",
     "define.experimentIdRejected": "defineExperiment 不接受 id —— id 由文件路径推导。",
@@ -269,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/fingerprint.d.ts

@@ -1,14 +1,25 @@
-import type { DiscoveredEval, EvalResult, SandboxOption } from "../types.ts";
+import type { DiscoveredEval, EvalResult, JsonValue, SandboxOption } from "../types.ts";
 import type { AgentRun } from "./types.ts";
 export declare function cacheKey(run: AgentRun, evalId: string): string;
 /**
  * @param sourceCache 按 sourcePath 缓存文件内容:一个矩阵(实验 × eval)会对同一批源文件
  * 反复算指纹,不带缓存会在任何 attempt 起跑前做 E×N 次重复文件读。
+ * @param flagsOverride 用这份 flags 代替 `run.flags` 的指纹口径算一遍。只有一个用途:
+ * 对已落盘结果做**反事实重算**——「把 flags 换成它当时那份,指纹还相等吗」等价于问
+ * 「除 flags 外的一切是否都没变」,`acceptableFingerprints` 用它判定某条历史结果与本次
+ * 规划的差异是否完全落在 provenance flag 上。
  */
-export declare function computeFingerprint(evalDef: DiscoveredEval, run: AgentRun, sourceCache?: Map<string, Promise<string>>, configSandbox?: SandboxOption): Promise<string>;
+export declare function computeFingerprint(evalDef: DiscoveredEval, run: AgentRun, sourceCache?: Map<string, Promise<string>>, configSandbox?: SandboxOption, flagsOverride?: Record<string, JsonValue>): Promise<string>;
 export interface CarryPlan {
     /** `cacheKey(run, evalId)` → 本次规划出的指纹,供调用方按同一口径判断"这条要不要携入"。 */
     plannedFingerprints: Map<string, string>;
+    /**
+     * `cacheKey(run, evalId)` → 这条组合**可以携带的全部指纹**:本次规划的那个,加上
+     * 「只在 provenance flag 上与本次不同」的历史口径(见 `acceptableFingerprints`)。
+     * 没声明 provenance flag 时恒是单元素集合 = `plannedFingerprints` 的那一个。
+     * 携带判定一律读这个集合,`plannedFingerprints` 只用来给新跑的 attempt 落盘打戳。
+     */
+    acceptableFingerprints: Map<string, Set<string>>;
     /**
      * 携带以 attempt 为粒度:命中携入条件(该 attempt 自身 passed/failed 终态 + 指纹匹配)的
      * `${experimentId}|${evalId}` → 该 eval 下具体携入的 attempt 序号集合(0-based)。同一个
@@ -35,14 +46,16 @@ export declare function resolvedTimeoutMsForCarry(run: AgentRun, evalDef: Discov
  * 1. 该 attempt 自己是终态(`passed` / `failed`)。`errored` 是框架/环境层面的不确定失败,
  *    判定本身不可信;`skipped` 根本没跑。同一 eval 的别的序号命中不能连带把它捎上
  *    (反例与修法见 memory 的 carry-must-be-per-attempt-not-whole-eval-key)。
- * 2. 该 attempt 落盘的 `fingerprint` 与本次规划的 `fingerprint` 相等。
+ * 2. 该 attempt 落盘的 `fingerprint` 落在本次的可携带指纹集合里(`CarryPlan.acceptableFingerprints`
+ *    的那一条,通常只有本次规划出的那一个;声明了 provenance flag 时还含「只在这些键上与本次
+ *    不同」的历史口径)。
  * 3. 该 attempt 的 `durationMs` 不超过本次 resolved 的 `timeoutMs`——`timeoutMs` 是携带资格
  *    判据、不进指纹哈希(docs/runner.md「缓存:指纹去重」)。
  *
  * `planCarry`(整场静态规划)与 run.ts 派发时刻的携带重查共用这一个函数:两条路径一旦把判据
  * 各写一份就会分叉,重查会携入静态规划判过不可携带的条目(或反过来)。
  */
-export declare function carriableAttempts(priorResults: EvalResult[] | undefined, key: string, fingerprint: string | undefined, timeoutMs: number): EvalResult[];
+export declare function carriableAttempts(priorResults: EvalResult[] | undefined, key: string, fingerprints: ReadonlySet<string> | undefined, timeoutMs: number): EvalResult[];
 /**
  * 算出这一批 (agentRun × eval) 的指纹,并据此从 priorResults 里筛出可以携入(跳过重跑)的结果。
  * run.ts 与 cli.ts(live 表格构建)必须共用这同一份计算 —— 否则两边一旦对"哪些携入"的判断
@@ -58,4 +71,35 @@ export declare function carriableAttempts(priorResults: EvalResult[] | undefined
  * `resolvedTimeoutMsForCarry`)。省略时按未配置处理,不是当作 0——只有 `run.timeoutMs` /
  * `evalDef.timeoutMs` 都缺席时才轮到它兜底。
  */
-export declare function planCarry(evals: DiscoveredEval[], agentRuns: AgentRun[], priorResults: EvalResult[] | undefined, configSandbox?: SandboxOption, configTimeoutMs?: number): Promise<CarryPlan>;
+export declare function planCarry(evals: DiscoveredEval[], agentRuns: AgentRun[], priorResults: EvalResult[] | undefined, configSandbox?: SandboxOption, configTimeoutMs?: number, flagBagsByExperiment?: Map<string, Record<string, JsonValue>[]>): Promise<CarryPlan>;
+/**
+ * 这条 `(experimentId, evalId)` 本次可以携带的指纹全集。
+ *
+ * 没声明 provenance flag 时就是 `{ primary }`——判据与「指纹相等」逐字等价,一条历史结果都
+ * 不会因此多携入。声明了之后多出一类:**只在 provenance flag 上与本次不同**的历史口径。
+ *
+ * 判定不靠比对两串哈希的差异(哈希不可差分),而是**反事实重算**:取该历史结果所属快照记下的
+ * `ExperimentRunInfo.flags`(整袋原样,`applySnapshotDefaults` 已把它挂在 `EvalResult.experiment`
+ * 上),用它替换本次的 flags 口径重算一遍指纹——算出来等于历史那一串,就证明「除 flags 外的
+ * 一切(eval 源码、agent、model、sandbox、strict…)都没变」。再要求两袋 flags 抹掉 provenance
+ * 键之后逐字相等,才把这串历史指纹计入可携带集合:真改了某个影响行为的 flag(`webResearch`
+ * 从 true 改成 false)照旧作废,不会被这条通道放行。
+ *
+ * 历史结果落盘时的指纹口径是「整袋 flags」(provenance 概念引入之前),所以两个口径都要试:
+ * 整袋(老结果)与抹掉 provenance 键的那袋(声明之后跑出来的结果,与 primary 相同则自然去重)。
+ */
+export declare function acceptableFingerprints(args: {
+    evalDef: DiscoveredEval;
+    run: AgentRun;
+    key: string;
+    priorResults: EvalResult[] | undefined;
+    /** 本次规划出的指纹(新跑的 attempt 用它落盘打戳)。 */
+    primary: string;
+    /**
+     * 该实验历史快照记下过的 flags(见 `loadCarryInputs`)。候选假设的来源之一,与结果自带的那袋
+     * 并列——携带条目带着**产出它那一轮**的指纹合入新快照,那一轮的 flags 只在更早的快照里留着。
+     */
+    historicalFlagBags?: readonly Record<string, JsonValue>[];
+    sourceCache?: Map<string, Promise<string>>;
+    configSandbox?: SandboxOption;
+}): Promise<Set<string>>;

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;
     /**
@@ -500,6 +500,21 @@ export interface ExperimentDef {
      *  (defineExperiment 解析时校验,非 JSON 直接报错),经 ctx.flags 透传给 adapter、
      *  t.flags 暴露给 eval,并原样进入结果快照的 ExperimentRunInfo.flags。 */
     flags?: Record<string, JsonValue>;
+    /**
+     * `flags` 里只作为**出处记录**的键名:照常落盘、照常透给 `ctx.flags` / `t.flags`,但不参与
+     * 可比性配置——值变了不作废任何已有结果,已跑完的照常携带(carry)。
+     *
+     * 给的是「每次跑都可能换、但换了不改变 attempt 里发生什么」的坐标:隧道 / 反向代理 URL、
+     * 服务端实例地址、跑批时刻这类。它们要留在 `flags` 里(报告要按 `flag()` 看这轮连的是哪个,
+     * eval 或 adapter 也可能要读),又不该像 `webResearch: true → false` 那样让缓存全部失效。
+     *
+     * 声明前跑出来的结果同样携带得到:携带判定按快照记下的历史 flags 做一次反事实重算,
+     * 确认差异完全落在这些键上(见 `runner/fingerprint.ts` 的 `acceptableFingerprints`)。
+     * 键不必存在于 `flags` 里——把一个键从 `flags` 移走时留着这条声明,历史结果照样不作废。
+     *
+     * 完全不需要在运行时被看见的事实用 `labels`,那是报告侧坐标(本来就不进指纹)。
+     */
+    provenanceFlags?: readonly string[];
     /**
      * 报告归类标注:实验在各对比轴上的坐标(如 `{ line: "codex", memory: "mempal" }`)。
      * 值域 string | number(解析时校验)。与 `flags` 的分界是「会不会改变 attempt 里发生的事」:
@@ -600,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 视图从这里起步。 */
@@ -608,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;
@@ -669,6 +689,8 @@ export interface AgentRun {
     model?: string;
     reasoningEffort?: string;
     flags: Record<string, JsonValue>;
+    /** 只作为出处记录、不进指纹的 flag 键(来自 ExperimentDef.provenanceFlags);见该字段说明。 */
+    provenanceFlags?: readonly string[];
     runs: number;
     earlyExit: boolean;
     sandbox?: SandboxOption;
@@ -794,8 +816,14 @@ export interface ActiveAttempt {
     /** 展示 label,等价 `runWho()` 的结果;渲染要用,但绝不作为 identity/key。 */
     who: string;
     phase: LifecyclePhase;
-    /** 进入当前 phase 的墙钟时间(epoch ms),用于渲染阶段耗时;每次 phase 变化都会更新。 */
-    phaseStartedAt: number;
+    /**
+     * 这条 attempt 被派发的墙钟时间(epoch ms,取 `attempt:start` 的 `at`)—— active 行时间列的
+     * **唯一**基准,`attempt:phase` 不得改写它:live 面板不做 spinner 动画,存活性完全由这一列
+     * 持续增长证明(见 docs/feature/experiments/cli.md「active 行的列序」),一列会归零的时间既
+     * 证明不了存活,也让人误以为这条 eval 重跑了。阶段各自的耗时不进这里——它由结果的
+     * `timing.phases` 完整落盘,live 面板要回答的是「这条还活着吗、跑了多久、正在干什么」。
+     */
+    startedAt: number;
     detail?: string;
 }
 /** 实验级钩子只有 setup 与它返回的 teardown 两员,同一实验内两者永不并发

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 实例