niceeval 0.6.2 → 0.7.0

package/INDEX.md

@@ -8,45 +8,45 @@
 
 | 任务 | 读取 |
 | --- | --- |
-| 初始化并跑通第一条 Eval | `docs-site/zh/quickstart.mdx` |
-| 理解 Adapter、Experiment、Eval 的分工 | `docs-site/zh/concepts/overview.mdx` |
-| 接入自己的 Agent | `docs-site/zh/guides/connect-your-agent.mdx` |
-| 选择官方 Adapter | `docs-site/zh/guides/official-adapters.mdx` |
-| 接入 coding agent CLI | `docs-site/zh/guides/sandbox-agent.mdx` |
-| 选择 Sandbox Provider | `docs-site/zh/guides/sandbox-providers.mdx` |
+| 初始化并跑通第一条 Eval | `docs-site/zh/tutorials/quickstart.mdx` |
+| 理解 Adapter、Experiment、Eval 的分工 | `docs-site/zh/explanation/overview.mdx` |
+| 接入自己的 Agent | `docs-site/zh/how-to/connect-your-agent.mdx` |
+| 选择官方 Adapter | `docs-site/zh/reference/official-adapters.mdx` |
+| 接入 coding agent CLI | `docs-site/zh/how-to/sandbox-agent.mdx` |
+| 选择 Sandbox Provider | `docs-site/zh/how-to/sandbox-providers.mdx` |
 
 ## 编写配置与 Eval
 
 | 任务 | 读取 |
 | --- | --- |
-| 编写 Adapter | `docs-site/zh/concepts/adapter.mdx`、`docs-site/zh/reference/define-agent.mdx` |
-| 映射消息、工具调用和事件流 | `docs-site/zh/guides/write-send.mdx`、`docs-site/zh/reference/events.mdx` |
-| 编写 Experiment | `docs-site/zh/guides/write-experiment.mdx` |
-| 编写 Eval | `docs-site/zh/concepts/evals.mdx`、`docs-site/zh/reference/define-eval.mdx` |
-| 编写断言和评分 | `docs-site/zh/guides/authoring.mdx`、`docs-site/zh/guides/scoring-guide.mdx`、`docs-site/zh/reference/expect.mdx` |
-| 配置 Judge | `docs-site/zh/concepts/judge.mdx`、`docs-site/zh/reference/define-config.mdx` |
-| 配置 OTel | `docs-site/zh/guides/connect-otel.mdx` |
+| 编写 Adapter | `docs-site/zh/explanation/adapter.mdx`、`docs-site/zh/reference/define-agent.mdx` |
+| 映射消息、工具调用和事件流 | `docs-site/zh/how-to/write-send.mdx`、`docs-site/zh/reference/events.mdx` |
+| 编写 Experiment | `docs-site/zh/how-to/write-experiment.mdx` |
+| 编写 Eval | `docs-site/zh/explanation/evals.mdx`、`docs-site/zh/reference/define-eval.mdx` |
+| 编写断言和评分 | `docs-site/zh/how-to/authoring.mdx`、`docs-site/zh/how-to/scoring-guide.mdx`、`docs-site/zh/reference/expect.mdx` |
+| 配置 Judge | `docs-site/zh/explanation/judge.mdx`、`docs-site/zh/reference/define-config.mdx` |
+| 配置 OTel | `docs-site/zh/how-to/connect-otel.mdx` |
 | 查 CLI 命令与 flag | `docs-site/zh/reference/cli.mdx` |
 
 ## 运行、调试与优化
 
 | 任务 | 读取 |
 | --- | --- |
-| 让 AI 自主运行、观察、修改和重跑 | `docs-site/zh/guides/agent-feedback-loop.mdx` |
-| 用 `show`、`view` 和 artifact 定位失败 | `docs-site/zh/guides/viewing-results.mdx` |
-| 组织实验和对比 | `docs-site/zh/guides/experiments.mdx` |
-| 编写自定义报告 | `docs-site/zh/guides/custom-reports.mdx`、`docs-site/zh/guides/report-components.mdx` |
-| 读取或转换结构化结果 | `docs-site/zh/guides/results-data.mdx` |
+| 让 AI 自主运行、观察、修改和重跑 | `docs-site/zh/how-to/agent-feedback-loop.mdx` |
+| 用 `show`、`view` 和 artifact 定位失败 | `docs-site/zh/how-to/viewing-results.mdx` |
+| 组织实验和对比 | `docs-site/zh/how-to/experiments.mdx` |
+| 编写自定义报告 | `docs-site/zh/how-to/custom-reports.mdx`、`docs-site/zh/reference/report-components.mdx` |
+| 读取或转换结构化结果 | `docs-site/zh/reference/results-data.mdx` |
 
 ## 专项场景
 
 | 任务 | 读取 |
 | --- | --- |
-| 评估 Claude Code / Codex Skill | `docs-site/zh/example/claude-code-codex-skill.mdx` |
-| 评估 Plugin、Hook 或 MCP server | `docs-site/zh/example/claude-code-codex-plugin.mdx` |
-| 编写多轮会话 | `docs-site/zh/concepts/adapter.mdx`、`docs-site/zh/guides/write-send.mdx` |
-| 编写人工审批流（HITL） | `docs-site/zh/concepts/hitl.mdx` |
-| 做 feature flag A/B 对比 | `docs-site/zh/concepts/tier.mdx`、`docs-site/zh/concepts/experiment.mdx` |
+| 评估 Claude Code / Codex Skill | `docs-site/zh/examples/coding-agent-extensions.mdx` |
+| 评估 Plugin、Hook 或 MCP server | `docs-site/zh/examples/coding-agent-extensions.mdx` |
+| 编写多轮会话 | `docs-site/zh/explanation/adapter.mdx`、`docs-site/zh/how-to/write-send.mdx` |
+| 编写人工审批流（HITL） | `docs-site/zh/explanation/hitl.mdx` |
+| 做 feature flag A/B 对比 | `docs-site/zh/explanation/tier.mdx`、`docs-site/zh/explanation/experiment.mdx` |
 
 ## 版本规则
 

package/README.zh.md

@@ -80,7 +80,7 @@ NiceEval 支持两种接入方式，取决于被测 agent 是否需要隔离的
 | Sandbox | 需要隔离工作区的 coding agent 才用得到；直连 Web Agent 不需要。 |
 | Tier | 接入 Adapter 的三档投入：Tier 1 只接 send，Tier 2 加 OTel 换调用瀑布图，Tier 3 侵入改造做 feature A/B。 |
 
-完整术语表见[架构概览](https://niceeval.com/docs/zh/concepts/overview)。
+完整术语表见[架构概览](https://niceeval.com/docs/zh/explanation/overview)。
 
 ## 示例
 
@@ -134,9 +134,9 @@ READ https://niceeval.com/INIT.md and install niceeval for this repo.
 
 从你的场景开始：
 
-- [如果你需要 eval 你的 Claude Code / Codex 插件](https://niceeval.com/docs/zh/example/claude-code-codex-plugin)
-- [如果你需要 eval 你的 Claude Code / Codex Skill](https://niceeval.com/docs/zh/example/claude-code-codex-skill)
-- [如果你需要 eval 你的 AI Agent 应用](https://niceeval.com/docs/zh/example/ai-agent-application)
+- [浏览可运行示例](https://niceeval.com/docs/zh/examples)
+- [评估 Coding Agent 扩展](https://niceeval.com/docs/zh/examples/coding-agent-extensions)
+- [自写 Adapter 评估 AI Agent 应用](https://niceeval.com/docs/zh/examples/ai-agent-application)
 
 
 ## Roadmap
@@ -161,7 +161,7 @@ READ https://niceeval.com/INIT.md and install niceeval for this repo.
 
 ## 文档
 
-- [快速开始](https://www.niceeval.com/docs/zh/quickstart)
+- [快速开始](https://www.niceeval.com/docs/zh/tutorials/quickstart)
 
 # 感谢
 该项目受下面项目所启发或者是由AI从下面项目中学习代码所写
@@ -170,4 +170,4 @@ READ https://niceeval.com/INIT.md and install niceeval for this repo.
 - [ponytail](https://github.com/DietrichGebert/ponytail)
 
 感谢下列社区
-- WIP
+- WIP

package/dist/agents/types.d.ts

@@ -131,7 +131,7 @@ export interface InputFile {
 }
 /**
  * HITL 回答轮里,人的裁决以结构化形式随 `input.responses` 到达——adapter 不需要解析
- * `text` 去猜哪句回答对应哪个请求、算不算批准。见 docs-site/zh/concepts/adapter.mdx
+ * `text` 去猜哪句回答对应哪个请求、算不算批准。见 docs-site/zh/explanation/adapter.mdx
  * 「不同回答的入参」一节的四种典型形态。
  */
 export interface InputResponse {
@@ -223,7 +223,7 @@ export interface AgentTracing {
  * 新会话线(eval 第一轮 / t.newSession() 之后)拿到一个全新的。**
  * 会话续接(`id`/`capture`、`history`)和 HITL 停轮现场(`hold`/`take`)的存取器都在它上面,
  * "第一轮"是新会话线的自然形态,没有要判断的分支;`state` 是这些存取器之外的逃生舱,
- * 框架从不往里写数据。见 docs-site/zh/concepts/adapter.mdx「AgentContext」一节。
+ * 框架从不往里写数据。见 docs-site/zh/explanation/adapter.mdx「AgentContext」一节。
  */
 export interface AgentSession {
     /** 会话续接:服务端记历史。本线记过的会话 id;新会话线是 undefined。 */

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

@@ -54,8 +54,8 @@ export declare const zhCN: {
     readonly "cli.show.runDirMissing": "Results directory not found: {{dir}}\n";
     readonly "cli.show.noEvalMatch": "No results matched: {{patterns}}. Evals with results: {{evals}}\n";
     readonly "cli.show.noExperimentMatch": "No experiment matched --experiment {{arg}}. Experiments with results: {{experiments}}\n";
-    readonly "cli.show.historyReportConflict": "`--history` and `--report` are mutually exclusive: --history is the built-in trend view. For a custom trend, compose exp.snapshots inside your report file instead.\n";
-    readonly "cli.show.evidenceNeedsEval": "--eval / --execution / --diff show one attempt's evidence, but the selection matched {{matched}} evals. Pick an attempt locator from the index below:\n{{index}}\n";
+    readonly "cli.show.historyReportConflict": "`--history` and `--report` are mutually exclusive: both take over the main output. --history is the host's per-attempt execution timeline; for snapshot-level trends, compose exp.snapshots inside your report file instead.\n";
+    readonly "cli.show.evidenceNeedsEval": "--source / --execution / --diff show one attempt's evidence, but the selection matched {{matched}} evals. Pick an attempt locator from the index below:\n{{index}}\n";
     readonly "cli.show.locatorMalformed": "{{message}}\n";
     readonly "cli.show.locatorNotFound": "{{message}}\n";
     readonly "cli.eval.noMatch": "没有匹配的 eval:{{patterns}}。\n";
@@ -109,7 +109,7 @@ export declare const zhCN: {
     readonly "feedback.human.compare": "Compare: niceeval view {{group}}";
     readonly "feedback.human.counts": "共 {{total}} · 复用 {{reused}} · 运行中 {{running}} · 排队 {{queued}} · 已完成 {{completed}}";
     readonly "feedback.human.diffHint": "Diff:    niceeval show {{locator}} --diff";
-    readonly "feedback.human.evalHint": "Eval:    niceeval show {{locator}} --eval";
+    readonly "feedback.human.evalHint": "Eval:    niceeval show {{locator}} --source";
     readonly "feedback.human.failuresHeader": "FAILURES";
     readonly "feedback.human.heartbeat": "已运行 {{elapsed}} · {{counts}}";
     readonly "feedback.human.inspect": "Inspect: niceeval show {{locator}}";

package/dist/report/aggregate.d.ts

@@ -1,14 +1,11 @@
-import type { AttemptHandle, Selection, SelectionWarning, Snapshot } from "../results/types.ts";
+import type { AttemptHandle, ScopeWarning, Snapshot } from "../results/types.ts";
 import { type AttemptLocator } from "../results/locator.ts";
-import type { Aggregator, AxisInput, ConfigRef, DimensionInput, Metric, MetricCell, MetricColumn, FlagRef } from "./types.ts";
+import type { Aggregator, DimensionInput, Metric, MetricCell, MetricColumn, NumericAxis, ReportInput } from "./types.ts";
+import { type LocalizedText } from "./locale.ts";
 import { evalPrefixPredicate } from "../shared/aggregate.ts";
-/** flag 未声明时的组名:不猜,如实归一组。 */
-export declare const FLAG_UNSET = "(unset)";
-/** 计算函数的第一参:Selection(warnings 随行)或手工挑的快照数组(没有挑选过程,自然无警告)。 */
-export type SnapshotsInput = Selection | Snapshot[];
-export declare function resolveInput(input: SnapshotsInput): {
-    snapshots: Snapshot[];
-    warnings: SelectionWarning[];
+export declare function resolveInput(input: ReportInput): {
+    snapshots: readonly Snapshot[];
+    warnings: readonly ScopeWarning[];
 };
 /** 展平后的一条样本:attempt + 它所属的快照(维度解析与题级折叠都需要快照身份)。 */
 export interface Item {
@@ -17,13 +14,13 @@ export interface Item {
 }
 export declare function experimentIdOf(item: Item): string;
 export declare function evalIdOf(item: Item): string;
-/** 快照键:与 view Compare 同口径的 "<experimentId> @ <startedAt>"。 */
+/** 快照键:"<experimentId> @ <startedAt>"("snapshot" 维度与手挑快照数组的对比用)。 */
 export declare function snapshotKeyOf(snapshot: Snapshot): string;
+/** 一组 Item 的 eval 全身份键:experimentId + eval id(聚合中的题级身份始终是这一对)。 */
+export declare function fullEvalKey(item: Item): string;
 /**
  * 一条 Item 的 AttemptLocator:真实读取路径(openResults() 产出的 handle)恒有
- * `attempt.locator`;手工构造的测试 fixture 若省略它,按当前身份元组兜底算一份
- * (与 `loadAttemptEvidence`、`open.ts` 的回填同一口径)——只服务这类场景,不改变真实
- * 读取路径的行为。
+ * `attempt.locator`;手工构造的测试 fixture 若省略它,按当前身份元组兜底算一份。
  */
 export declare function locatorOf(item: Item): AttemptLocator;
 /**
@@ -31,29 +28,38 @@ export declare function locatorOf(item: Item): AttemptLocator;
  * (experimentId, evalId, attempt, startedAt))。missing-startedAt 的警告不透出:
  * 官方产出永不缺 startedAt,缺失只可能来自 legacy 落盘,「不去重、如实保留重复」即终稿。
  */
-export declare function collectItems(snapshots: Snapshot[]): Item[];
+export declare function collectItems(snapshots: readonly Snapshot[]): Item[];
 export { evalPrefixPredicate };
-export declare function filterItems(items: Item[], evals?: string | string[]): Item[];
+export declare function filterItems(items: Item[], evals?: string | readonly string[]): Item[];
 export declare function dimensionName(dimension: DimensionInput): string;
-/** eval id 的第一段:"algebra/quadratic" → "algebra";没有 "/" 时就是 id 本身。 */
+/** eval id 的完整父路径:"a/b/c" → "a/b";没有 "/" 时取完整 id(与可比组同一条派生规则)。 */
 export declare function evalGroupOf(id: string): string;
-/** flag 声明值 → 组标签:label 函数优先,其余 String();未声明 → FLAG_UNSET。 */
-export declare function flagGroupKey(ref: FlagRef, item: Item): string;
-/** config 投影值 → 组标签,规则与 flagGroupKey 一致;未投影 → FLAG_UNSET。 */
-export declare function configGroupKey(ref: ConfigRef, item: Item): string;
-/** flag / config 作轴:要求数值;未声明、未投影或非数值 → null(点不画,注脚报数)。 */
-export declare function axisValue(ref: AxisInput, item: Item): number | null;
+/** flag / runConfig 未声明时的显示键:内置文案,en / zh-CN 同形。 */
+export declare const MISSING_GROUP_KEY: string;
+/**
+ * flag / runConfig 声明值 → 分组显示键(稳定 JSON 规则):字符串直接显示,其它值用对象键
+ * 递归排序后的 JSON,缺失值显示内置文案 `(missing)`。返回 [显示键, 冲突检测用的规范形]。
+ */
+export declare function refDisplayKey(value: unknown): [display: string, canonical: string];
 export declare function dimensionKey(dimension: DimensionInput, item: Item): string;
-/** 按维度分组,保持首次出现顺序(无 sort 时表格行序即此序)。 */
+/**
+ * 按维度分组;维度 domain 按稳定 key 字典序(Unicode)排列,不让文件扫描顺序渗进报告。
+ * flag / runConfig 维度做显示键冲突检测:不同原始值生成同一显示键时报错并要求改用
+ * CustomDimension,绝不静默合组。
+ */
 export declare function groupItems(items: Item[], dimension: DimensionInput): Map<string, Item[]>;
-export declare function applyAggregator(aggregator: Aggregator, values: number[]): number;
-/** where 不满足 → null,语义等价于 value 开头 return null。 */
+export declare function applyAggregator(aggregator: Aggregator, values: readonly number[]): number;
+/** where 不满足 → null,语义等价于 value 开头 return null;抛错与非有限数按完整用户反馈失败。 */
 export declare function evaluateMetric(metric: Metric, attempt: AttemptHandle): Promise<number | null>;
-export declare function displayValue(metric: Metric, value: number | null): string;
+/** 单值 → LocalizedText display:metric.display 覆盖内置 unit 格式化;null 的兜底归渲染面。 */
+export declare function displayValue(metric: Metric, value: number | null): LocalizedText;
 /**
  * 一个格子:组内 attempt → 两级聚合 → 终值。
  * null 值不进聚合但计入 total(覆盖率经 samples/total 如实暴露);全 null → value null。
+ * refs 跟随覆盖范围(含值为 null 的 attempt),去重后按 locator 字典序。
  */
 export declare function computeCell(metric: Metric, items: Item[]): Promise<MetricCell>;
 export declare function toColumn(metric: Metric): MetricColumn;
 export declare function assertUniqueMetricNames(metrics: readonly Metric[], where: string): void;
+/** NumericAxis 的取值,带完整反馈的非法值检查(NaN / Infinity 一律报错,不静默当缺失)。 */
+export declare function axisValueOf(axis: NumericAxis, attempt: AttemptHandle): number | null;

package/dist/report/aggregate.js

@@ -1,20 +1,23 @@
-// 两级聚合引擎:去重 → 按维度分组 → 组内按 (eval × 快照) 折叠(perEval)→ 跨题折叠(across)→ MetricCell。
+// 两级聚合引擎:去重 → 按维度分组 → 组内按 (experiment × eval) 折叠(perEval)→ 跨题折叠
+// (acrossEvals)→ MetricCell(docs/feature/reports/architecture.md「指标聚合不变量」、
+// docs/feature/reports/library/metrics.md「公开计算模型」)。
 //
 // 为什么是两级:earlyExit 默认开,失败的题天然比通过的题样本多;平铺求均值会把分数
 // 和重试策略纠缠在一起(eval A=[1]、eval B=[0,0,0] 平铺 = 0.25,两级宏平均 = 0.5)。
 // 自定义维度把同一道题的 attempt 分进不同组时,第一级折叠发生在各组内部。
 import { dedupeAttempts } from "../results/select.js";
 import { encodeAttemptLocator } from "../results/locator.js";
-import { formatMetricValue } from "./format.js";
+import { flagValueOf, runConfigValueOf } from "./flag.js";
+import { formatMetricValue, localizedDisplay } from "./format.js";
+import { localeText } from "./locale.js";
 import { evalPrefixPredicate } from "../shared/aggregate.js";
 // 复合键分隔符:NUL 不会出现在 eval id / experimentId / ISO 时间里,拼接键不会串味
 const KEY_SEP = "\u0000";
-/** flag 未声明时的组名:不猜,如实归一组。 */
-export const FLAG_UNSET = "(unset)";
 export function resolveInput(input) {
     if (Array.isArray(input))
         return { snapshots: input, warnings: [] };
-    return { snapshots: input.snapshots, warnings: input.warnings };
+    const scope = input;
+    return { snapshots: scope.snapshots, warnings: scope.warnings };
 }
 export function experimentIdOf(item) {
     return item.attempt.experimentId || item.snapshot.experimentId;
@@ -22,15 +25,17 @@ export function experimentIdOf(item) {
 export function evalIdOf(item) {
     return item.attempt.evalId || item.attempt.result.id;
 }
-/** 快照键:与 view Compare 同口径的 "<experimentId> @ <startedAt>"。 */
+/** 快照键:"<experimentId> @ <startedAt>"("snapshot" 维度与手挑快照数组的对比用)。 */
 export function snapshotKeyOf(snapshot) {
     return `${snapshot.experimentId} @ ${snapshot.startedAt}`;
 }
+/** 一组 Item 的 eval 全身份键:experimentId + eval id(聚合中的题级身份始终是这一对)。 */
+export function fullEvalKey(item) {
+    return `${experimentIdOf(item)}${KEY_SEP}${evalIdOf(item)}`;
+}
 /**
  * 一条 Item 的 AttemptLocator:真实读取路径(openResults() 产出的 handle)恒有
- * `attempt.locator`;手工构造的测试 fixture 若省略它,按当前身份元组兜底算一份
- * (与 `loadAttemptEvidence`、`open.ts` 的回填同一口径)——只服务这类场景,不改变真实
- * 读取路径的行为。
+ * `attempt.locator`;手工构造的测试 fixture 若省略它,按当前身份元组兜底算一份。
  */
 export function locatorOf(item) {
     return (item.attempt.locator ??
@@ -64,71 +69,55 @@ export { evalPrefixPredicate };
 export function filterItems(items, evals) {
     if (evals === undefined)
         return items;
-    const match = evalPrefixPredicate(evals);
+    const match = evalPrefixPredicate(Array.isArray(evals) ? [...evals] : evals);
     return items.filter((item) => match(evalIdOf(item)));
 }
 // ───────────────────────── 维度 ─────────────────────────
 export function dimensionName(dimension) {
     return typeof dimension === "string" ? dimension : dimension.name;
 }
-/** eval id 的第一段:"algebra/quadratic" → "algebra";没有 "/" 时就是 id 本身。 */
+/** eval id 的完整父路径:"a/b/c" → "a/b";没有 "/" 时取完整 id(与可比组同一条派生规则)。 */
 export function evalGroupOf(id) {
-    const slash = id.indexOf("/");
+    const slash = id.lastIndexOf("/");
     return slash === -1 ? id : id.slice(0, slash);
 }
-function isFlagRef(dimension) {
-    return typeof dimension === "object" && "kind" in dimension && dimension.kind === "flag";
-}
-function isConfigRef(dimension) {
-    return typeof dimension === "object" && "kind" in dimension && dimension.kind === "config";
+function isDimensionRef(dimension) {
+    return (typeof dimension === "object" &&
+        "kind" in dimension &&
+        (dimension.kind === "flag" || dimension.kind === "runConfig"));
 }
-/** experiment 声明的 flags(经 runner 原样透传进持久化字段 ExperimentRunInfo.flags)。 */
-function flagsOf(attempt) {
-    return attempt.result.experiment?.flags;
+/** flag / runConfig 未声明时的显示键:内置文案,en / zh-CN 同形。 */
+export const MISSING_GROUP_KEY = localeText("en", "cell.missingValue");
+/** 对象键递归排序后的稳定 JSON(分组显示键与冲突检测共用)。 */
+function canonicalJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    if (typeof value === "object" && value !== null) {
+        const keys = Object.keys(value).sort();
+        return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalJson(value[k])}`).join(",")}}`;
+    }
+    return JSON.stringify(value);
 }
 /**
- * config() 的取值:读快照的 `ExperimentRunInfo` 投影(快照优先;第三方落盘只把投影拼在
- * 条目上时回退 result.experiment),外加桥接到快照顶层权威字段的 `model` / `agent` 两个键
- * (与 "model" / "agent" 内置维度同一读法,不另造第二套口径)。未投影 → undefined。
+ * flag / runConfig 声明值 → 分组显示键(稳定 JSON 规则):字符串直接显示,其它值用对象键
+ * 递归排序后的 JSON,缺失值显示内置文案 `(missing)`。返回 [显示键, 冲突检测用的规范形]。
  */
-function configValueOf(ref, item) {
-    if (ref.name === "model")
-        return item.attempt.result.model ?? item.snapshot.model;
-    if (ref.name === "agent")
-        return item.attempt.result.agent || item.snapshot.agent;
-    const info = item.snapshot.experiment ?? item.attempt.result.experiment;
-    // ExperimentRunInfo 是穷尽可序列化投影;按字段名取值,新增投影字段无需改这里
-    return info?.[ref.name];
-}
-/** flag 声明值 → 组标签:label 函数优先,其余 String();未声明 → FLAG_UNSET。 */
-export function flagGroupKey(ref, item) {
-    return refGroupKey(ref, flagsOf(item.attempt)?.[ref.name]);
-}
-/** config 投影值 → 组标签,规则与 flagGroupKey 一致;未投影 → FLAG_UNSET。 */
-export function configGroupKey(ref, item) {
-    return refGroupKey(ref, configValueOf(ref, item));
-}
-function refGroupKey(ref, value) {
+export function refDisplayKey(value) {
     if (value === undefined)
-        return FLAG_UNSET;
-    // 声明侧的合法标量就是这三种;非标量投影(sandbox / selectedEvalIds…)如实 JSON 化,不猜
-    if (typeof ref.label === "function")
-        return ref.label(value);
-    if (typeof value === "object" && value !== null)
-        return JSON.stringify(value);
-    return String(value);
-}
-/** flag / config 作轴:要求数值;未声明、未投影或非数值 → null(点不画,注脚报数)。 */
-export function axisValue(ref, item) {
-    const value = ref.kind === "flag" ? flagsOf(item.attempt)?.[ref.name] : configValueOf(ref, item);
-    return typeof value === "number" ? value : null;
+        return [MISSING_GROUP_KEY, "undefined"];
+    if (typeof value === "string")
+        return [value, `string:${value}`];
+    return [canonicalJson(value), `json:${canonicalJson(value)}`];
+}
+function refValueOf(ref, item) {
+    return ref.kind === "flag"
+        ? flagValueOf(item.attempt, ref.name)
+        : runConfigValueOf(item.attempt, ref.name);
 }
 export function dimensionKey(dimension, item) {
     if (typeof dimension !== "string") {
-        if (isFlagRef(dimension))
-            return flagGroupKey(dimension, item);
-        if (isConfigRef(dimension))
-            return configGroupKey(dimension, item);
+        if (isDimensionRef(dimension))
+            return refDisplayKey(refValueOf(dimension, item))[0];
         return dimension.of(item.attempt);
     }
     const result = item.attempt.result;
@@ -152,18 +141,39 @@ export function dimensionKey(dimension, item) {
         }
     }
 }
-/** 按维度分组,保持首次出现顺序(无 sort 时表格行序即此序)。 */
+/**
+ * 按维度分组;维度 domain 按稳定 key 字典序(Unicode)排列,不让文件扫描顺序渗进报告。
+ * flag / runConfig 维度做显示键冲突检测:不同原始值生成同一显示键时报错并要求改用
+ * CustomDimension,绝不静默合组。
+ */
 export function groupItems(items, dimension) {
     const groups = new Map();
+    const canonicalByDisplay = new Map();
+    const checkConflicts = typeof dimension !== "string" && isDimensionRef(dimension);
     for (const item of items) {
-        const key = dimensionKey(dimension, item);
+        let key;
+        if (checkConflicts) {
+            const [display, canonical] = refDisplayKey(refValueOf(dimension, item));
+            const existing = canonicalByDisplay.get(display);
+            if (existing === undefined)
+                canonicalByDisplay.set(display, canonical);
+            else if (existing !== canonical) {
+                throw new Error(`Dimension "${dimensionName(dimension)}" maps two different raw values to the same display key "${display}" ` +
+                    `(e.g. the string "5" and the number 5). Grouping them silently would merge distinct configurations; ` +
+                    `use a CustomDimension ({ name, of(attempt) }) to define an unambiguous key.`);
+            }
+            key = display;
+        }
+        else {
+            key = dimensionKey(dimension, item);
+        }
         const list = groups.get(key);
         if (list)
             list.push(item);
         else
             groups.set(key, [item]);
     }
-    return groups;
+    return new Map([...groups.entries()].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
 }
 // ───────────────────────── 聚合 ─────────────────────────
 export function applyAggregator(aggregator, values) {
@@ -180,52 +190,109 @@ export function applyAggregator(aggregator, values) {
             return Math.max(...values);
     }
 }
-/** where 不满足 → null,语义等价于 value 开头 return null。 */
+function metricError(metric, step, cause, locator) {
+    const at = locator === undefined ? "" : ` at attempt ${locator}`;
+    return new Error(`Metric "${metric.name}" ${step} failed${at}: ${cause instanceof Error ? cause.message : String(cause)}. ` +
+        "Computation errors are not disguised as missing data — fix the metric (return null for expected gaps), then re-run.", { cause });
+}
+/** where 不满足 → null,语义等价于 value 开头 return null;抛错与非有限数按完整用户反馈失败。 */
 export async function evaluateMetric(metric, attempt) {
-    if (metric.where && !metric.where(attempt))
-        return null;
-    return metric.value(attempt);
+    const locator = attempt.locator;
+    if (metric.where) {
+        let pass;
+        try {
+            pass = metric.where(attempt);
+        }
+        catch (e) {
+            throw metricError(metric, "where()", e, locator);
+        }
+        if (!pass)
+            return null;
+    }
+    let value;
+    try {
+        value = await metric.value(attempt);
+    }
+    catch (e) {
+        throw metricError(metric, "value()", e, locator);
+    }
+    if (value !== null && !Number.isFinite(value)) {
+        throw metricError(metric, "value()", `returned a non-finite number (${String(value)}); return null for "not measurable"`, locator);
+    }
+    return value;
 }
+/** 单值 → LocalizedText display:metric.display 覆盖内置 unit 格式化;null 的兜底归渲染面。 */
 export function displayValue(metric, value) {
     // null 的纯文本兜底;组件把 null 渲染成「缺数据」,绝不画 0
     if (value === null)
         return "—";
-    return metric.display ? metric.display(value) : formatMetricValue(value, metric.unit);
+    if (metric.display) {
+        const display = metric.display;
+        return localizedDisplay((locale) => {
+            try {
+                return display(value, locale);
+            }
+            catch (e) {
+                throw metricError(metric, "display()", e);
+            }
+        });
+    }
+    return formatMetricValue(value, metric.unit);
+}
+function foldAggregator(metric, step, values) {
+    const aggregator = metric.aggregate?.[step] ?? "mean";
+    let folded;
+    try {
+        folded = applyAggregator(aggregator, values);
+    }
+    catch (e) {
+        throw metricError(metric, `${step} aggregator`, e);
+    }
+    if (!Number.isFinite(folded)) {
+        throw metricError(metric, `${step} aggregator`, `returned a non-finite number (${String(folded)})`);
+    }
+    return folded;
 }
 /**
  * 一个格子:组内 attempt → 两级聚合 → 终值。
  * null 值不进聚合但计入 total(覆盖率经 samples/total 如实暴露);全 null → value null。
+ * refs 跟随覆盖范围(含值为 null 的 attempt),去重后按 locator 字典序。
  */
 export async function computeCell(metric, items) {
-    // 第一级桶:同一 (eval × 快照) 的 attempt 折成一个题级值
+    // 第一级桶:同一 (experiment × eval × 快照) 的 attempt 折成一个题级值
     const buckets = new Map();
-    const refs = [];
+    const refs = new Set();
     let samples = 0;
     for (const item of items) {
+        refs.add(locatorOf(item));
         const value = await evaluateMetric(metric, item.attempt);
         if (value === null)
             continue;
         samples += 1;
-        refs.push(locatorOf(item)); // 证据引用由句柄直供,不反查下标
-        const bucketKey = `${evalIdOf(item)}${KEY_SEP}${snapshotKeyOf(item.snapshot)}`;
+        const bucketKey = `${fullEvalKey(item)}${KEY_SEP}${snapshotKeyOf(item.snapshot)}`;
         const bucket = buckets.get(bucketKey);
         if (bucket)
             bucket.push(value);
         else
             buckets.set(bucketKey, [value]);
     }
-    const perEval = metric.aggregate?.perEval ?? "mean";
-    const across = metric.aggregate?.across ?? "mean";
-    const evalValues = [...buckets.values()].map((values) => applyAggregator(perEval, values));
-    const value = evalValues.length === 0 ? null : applyAggregator(across, evalValues);
-    return { value, display: displayValue(metric, value), samples, total: items.length, refs };
+    const evalValues = [...buckets.values()].map((values) => foldAggregator(metric, "perEval", values));
+    const value = evalValues.length === 0 ? null : foldAggregator(metric, "acrossEvals", evalValues);
+    return {
+        value,
+        display: displayValue(metric, value),
+        samples,
+        total: items.length,
+        refs: [...refs].sort(),
+    };
 }
 export function toColumn(metric) {
     return {
         key: metric.name,
         label: metric.label ?? metric.name,
-        unit: metric.unit,
-        better: metric.better,
+        ...(metric.description !== undefined ? { description: metric.description } : {}),
+        ...(metric.unit !== undefined ? { unit: metric.unit } : {}),
+        ...(metric.better !== undefined ? { better: metric.better } : {}),
     };
 }
 export function assertUniqueMetricNames(metrics, where) {
@@ -237,3 +304,17 @@ export function assertUniqueMetricNames(metrics, where) {
         seen.add(metric.name);
     }
 }
+/** NumericAxis 的取值,带完整反馈的非法值检查(NaN / Infinity 一律报错,不静默当缺失)。 */
+export function axisValueOf(axis, attempt) {
+    let value;
+    try {
+        value = axis.of(attempt);
+    }
+    catch (e) {
+        throw new Error(`Numeric axis "${axis.name}" of() failed${attempt.locator ? ` at attempt ${attempt.locator}` : ""}: ${e instanceof Error ? e.message : String(e)}`, { cause: e });
+    }
+    if (value !== null && !Number.isFinite(value)) {
+        throw new Error(`Numeric axis "${axis.name}" of() returned a non-finite number (${String(value)}); return null for attempts without a plottable x value.`);
+    }
+    return value;
+}

package/dist/report/built-in/index.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("../report.ts").ReportDefinition;
+export default _default;

package/dist/report/built-in/index.js

@@ -0,0 +1,8 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// niceeval/report/built-in —— 包里自带的一个报告文件,没有任何私有钩子
+// (docs/feature/reports/library/built-in.md)。裸 `niceeval show` 与 `niceeval view`
+// 装载的就是这份默认导出:一份普通 defineReport,与用户的 --report 文件同层、
+// 走同一条 装载 → resolve → validate → render 管线。「builtin」不是装载逻辑里的类别,
+// 只是宿主默认拿哪个值的事实。
+import { ExperimentComparison, defineReport } from "../index.js";
+export default defineReport(_jsx(ExperimentComparison, {}));