niceeval 0.6.2 → 0.7.0

package/dist/report/locale.js

@@ -1,9 +1,43 @@
-// 官方组件 chrome 文案的 locale 字典(en / zh-CN 两份)。
+// 官方组件 chrome 文案的 locale 字典与 LocalizedText 解析。
+// ReportLocale 是开放的 BCP 47 标签(数据协议不封语言上限);官方内置文案与
+// MetricCell.display 生成面当前覆盖 en / zh-CN,其它 locale 走 LocalizedText 回退规则。
 // 只覆盖组件自带的固定文案(verdict 词、缺数据、覆盖率角标、注脚、占位符等);
-// 数据本身(display、维度键、warnings 的 message)不经这里。
-// 刻意不 import src/i18n/(CLI 专用字典,locale 来源与 key 面完全不同);
-// zh-CN 译法与默认 Reports 契约保持一致(端到端成功率/平均耗时/预估成本…)。
+// 维度键、warnings 的 message 不经这里。
+// 刻意不 import src/i18n/(CLI 专用字典,locale 来源与 key 面完全不同)。
 export const DEFAULT_REPORT_LOCALE = "en";
+/** MetricCell.display 生成面覆盖的 locale 全集;其它 locale 按 LocalizedText 回退取 en。 */
+export const DISPLAY_LOCALES = ["en", "zh-CN"];
+/**
+ * LocalizedText 的确定回退:取当前 locale;缺失时取 en;仍缺失时取按 locale 键字典序的
+ * 第一个非空值。对象没有任何非空值时报错,不渲染空文案
+ * (docs/feature/reports/library/shell.md「行为约束」)。
+ */
+export function resolveLocalizedText(text, locale) {
+    if (typeof text === "string")
+        return text;
+    const direct = text[locale];
+    if (direct !== undefined && direct !== "")
+        return direct;
+    const en = text.en;
+    if (en !== undefined && en !== "")
+        return en;
+    for (const key of Object.keys(text).sort()) {
+        const value = text[key];
+        if (value !== undefined && value !== "")
+            return value;
+    }
+    throw new Error("LocalizedText object has no non-empty value. Provide at least one locale entry, e.g. { en: \"…\" }.");
+}
+/** LocalizedText 按字段值深相等(键顺序无关;标题回退链的「唯一且相同」判定用)。 */
+export function localizedTextEquals(a, b) {
+    if (typeof a === "string" || typeof b === "string")
+        return a === b;
+    const keysA = Object.keys(a).sort();
+    const keysB = Object.keys(b).sort();
+    if (keysA.length !== keysB.length)
+        return false;
+    return keysA.every((key, i) => key === keysB[i] && a[key] === b[key]);
+}
 const en = {
     "verdict.passed": "passed",
     "verdict.failed": "failed",
@@ -14,6 +48,7 @@ const en = {
     "cell.measuredTitle": "{samples}/{total} attempts measured",
     "cell.noneMeasurableTitle": "0/{total} attempts measurable",
     "cell.coverageTitle": "coverage {samples}/{total}: this metric is null for the remaining attempts",
+    "cell.missingValue": "(missing)",
     "table.higherBetter": "higher is better",
     "table.lowerBetter": "lower is better",
     "table.model": "Model",
@@ -29,45 +64,45 @@ const en = {
     "experimentList.avgDuration": "Avg duration",
     "experimentList.passRate": "End-to-end pass rate",
     "experimentList.tokens": "Tokens",
-    "experimentList.estimatedCost": "Est. cost",
+    "experimentList.cost": "Cost",
     "experimentList.result": "Result",
     "experimentList.status": "Status",
     "experimentList.evalAttempt": "Eval / Attempt",
     "experimentList.duration": "Duration",
-    "experimentList.cost": "Cost",
     "experimentList.filterPlaceholder": "Filter experiments…",
     "experimentList.defaultModel": "default",
     "experimentList.flags": "Flags",
     "entityList.average": "{value} avg",
+    "entityList.moreFailures.one": "+{n} more failure",
+    "entityList.moreFailures.other": "+{n} more failures",
     /** <Table> 压到下限仍放不下时,从右侧丢列并如实报数。 */
     "table.columnsHidden.one": "({n} more column not shown)",
     "table.columnsHidden.other": "({n} more columns not shown)",
-    "overview.snapshots": "Snapshots",
-    "overview.evals": "Evals",
-    "overview.attempts": "attempts",
-    "overview.passRate": "End-to-end pass rate",
-    "overview.totalCost": "Total cost",
-    "overview.totalDuration": "Total duration",
-    "overview.source": "Source: {n} snapshots",
+    /** ScopeSummary 的 KPI 标签。 */
+    "scopeSummary.experiments": "Experiments",
+    "scopeSummary.evals": "Evals",
+    "scopeSummary.attempts": "attempts",
+    "scopeSummary.passRate": "End-to-end pass rate",
+    "scopeSummary.totalCost": "Total cost",
+    "scopeSummary.range": "{from} – {to}",
+    "scopeSummary.votesEval": "eval verdicts",
+    "scopeSummary.votesAttempt": "attempt verdicts",
     "overview.experiments.one": "{n} experiment",
     "overview.experiments.other": "{n} experiments",
     "overview.evalsCount": "{n} evals",
     "overview.attemptsCount": "{n} attempts",
-    /** GroupSummary 的 KPI dt 标签(其余字段复用 verdict.* / overview.* 已有 key)。 */
-    "groupSummary.experiments": "Experiments",
+    "overview.evals": "Evals",
+    "overview.passRate": "End-to-end pass rate",
+    "overview.totalCost": "Cost",
     "experimentComparison.groups": "Experiment groups",
     "experimentComparison.group": "Experiment group",
-    "experimentComparison.results": "Results",
+    "experimentComparison.results": "Eval results",
     "experimentComparison.lastRun": "Last run",
     "experimentComparison.selectGroup": "Select experiment group {group}",
-    "experimentComparison.command": "Details: {command}",
+    "experimentComparison.commandsHead": "Group details:",
     "experimentComparison.empty": "No experiment groups",
-    "composedFrom.one": "composed from {n} run",
-    "composedFrom.other": "composed from {n} runs",
-    "latestRun": "latest {run}",
-    "scatter.betterHint": "better ↗",
+    /** 方向提示唯一文案:轴向已随 better 反正,「更好」恒指向右上(两轴都声明 better 时才显示)。 */
     "scatter.betterUpperRight": "better → upper right",
-    "scatter.axisReversed": "(axis reversed: right = better)",
     /** 0 个可画点:x/y 指标没有可用数据。 */
     "scatter.noData": "No data to plot {x} × {y}",
     "pointsMissing.one": "{n} point missing data",
@@ -80,16 +115,21 @@ const en = {
     "attemptList.details": "details",
     "scoreboard.total": "Total",
     "scoreboard.totalText": "total",
-    "scoreboard.missing.one": "{n} eval missing, scored 0",
-    "scoreboard.missing.other": "{n} evals missing, scored 0",
-    "scoreboard.missingText": "({n} missing)",
+    "scoreboard.notRun.one": "{n} eval not run, scored 0",
+    "scoreboard.notRun.other": "{n} evals not run, scored 0",
+    "scoreboard.unscorable.one": "{n} eval unscorable, scored 0",
+    "scoreboard.unscorable.other": "{n} evals unscorable, scored 0",
+    "scoreboard.notRunText": "({n} not run)",
+    "scoreboard.unscorableText": "({n} unscorable)",
+    "scoreboard.ignored.one": "{n} eval outside the question set ignored",
+    "scoreboard.ignored.other": "{n} evals outside the question set ignored",
     "scoreboard.weights": "weights:",
     "scoreboard.allWeights": "all evals ×1",
     "scoreboard.othersWeight": "others ×1",
-    "scoreboard.subjectTitle": "{evals} evals, weighted {earned} of {possible}",
+    "scoreboard.subjectTitle": "{questions} evals, weighted {earned} of {possible}",
     "delta.pairHeader": "pair (A → B)",
-    "board.currentVerdicts": "Current verdicts",
-    "board.failing": "Failing:",
+    "delta.empty": "{experiments} experiments, 0 comparable pairs",
+    "tabs.tab": "Tab",
 };
 const zhCN = {
     "verdict.passed": "通过",
@@ -100,6 +140,7 @@ const zhCN = {
     "cell.measuredTitle": "{samples}/{total} 次 attempt 测得",
     "cell.noneMeasurableTitle": "0/{total} 次 attempt 可测",
     "cell.coverageTitle": "覆盖率 {samples}/{total}:其余 attempt 测不了这个指标",
+    "cell.missingValue": "(missing)",
     "table.higherBetter": "越高越好",
     "table.lowerBetter": "越低越好",
     "table.model": "模型",
@@ -114,43 +155,42 @@ const zhCN = {
     "experimentList.avgDuration": "平均耗时",
     "experimentList.passRate": "端到端成功率",
     "experimentList.tokens": "Tokens",
-    "experimentList.estimatedCost": "预估成本",
+    "experimentList.cost": "成本",
     "experimentList.result": "结果",
     "experimentList.status": "状态",
     "experimentList.evalAttempt": "题目 / Attempt",
     "experimentList.duration": "耗时",
-    "experimentList.cost": "成本",
     "experimentList.filterPlaceholder": "筛选实验…",
     "experimentList.defaultModel": "默认",
     "experimentList.flags": "Flags",
     "entityList.average": "平均 {value}",
+    "entityList.moreFailures.one": "+{n} 条其它失败",
+    "entityList.moreFailures.other": "+{n} 条其它失败",
     "table.columnsHidden.one": "(还有 {n} 列未列出)",
     "table.columnsHidden.other": "(还有 {n} 列未列出)",
-    "overview.snapshots": "快照",
-    "overview.evals": "题目",
-    "overview.attempts": "尝试",
-    "overview.passRate": "端到端成功率",
-    "overview.totalCost": "总成本",
-    "overview.totalDuration": "总耗时",
-    "overview.source": "数据来源:{n} 个快照",
+    "scopeSummary.experiments": "实验数",
+    "scopeSummary.evals": "题目",
+    "scopeSummary.attempts": "次 attempt",
+    "scopeSummary.passRate": "端到端成功率",
+    "scopeSummary.totalCost": "总成本",
+    "scopeSummary.range": "{from} – {to}",
+    "scopeSummary.votesEval": "Eval 计票",
+    "scopeSummary.votesAttempt": "Attempt 计票",
     "overview.experiments.one": "{n} 个实验",
     "overview.experiments.other": "{n} 个实验",
     "overview.evalsCount": "{n} 道题",
     "overview.attemptsCount": "{n} 次 attempt",
-    "groupSummary.experiments": "实验数",
+    "overview.evals": "Eval",
+    "overview.passRate": "端到端成功率",
+    "overview.totalCost": "成本",
     "experimentComparison.groups": "实验组",
     "experimentComparison.group": "实验组",
-    "experimentComparison.results": "结果",
+    "experimentComparison.results": "Eval 结果",
     "experimentComparison.lastRun": "最后运行",
     "experimentComparison.selectGroup": "选择实验组 {group}",
-    "experimentComparison.command": "查看：{command}",
+    "experimentComparison.commandsHead": "查看组内详情:",
     "experimentComparison.empty": "没有实验组",
-    "composedFrom.one": "合成自 {n} 个 run",
-    "composedFrom.other": "合成自 {n} 个 run",
-    "latestRun": "最新 {run}",
-    "scatter.betterHint": "更好 ↗",
-    "scatter.betterUpperRight": "更好 → 右上",
-    "scatter.axisReversed": "(轴反向:右 = 更好)",
+    "scatter.betterUpperRight": "越靠右上越好",
     "scatter.noData": "{x} × {y} 没有可绘制的数据",
     "pointsMissing.one": "{n} 个点缺数据",
     "pointsMissing.other": "{n} 个点缺数据",
@@ -162,22 +202,27 @@ const zhCN = {
     "attemptList.details": "详情",
     "scoreboard.total": "总分",
     "scoreboard.totalText": "总分",
-    "scoreboard.missing.one": "{n} 道题缺席,按 0 计",
-    "scoreboard.missing.other": "{n} 道题缺席,按 0 计",
-    "scoreboard.missingText": "(缺 {n} 题)",
+    "scoreboard.notRun.one": "{n} 道题没跑,按 0 计",
+    "scoreboard.notRun.other": "{n} 道题没跑,按 0 计",
+    "scoreboard.unscorable.one": "{n} 道题测不了,按 0 计",
+    "scoreboard.unscorable.other": "{n} 道题测不了,按 0 计",
+    "scoreboard.notRunText": "(没跑 {n} 题)",
+    "scoreboard.unscorableText": "(测不了 {n} 题)",
+    "scoreboard.ignored.one": "题集之外的 {n} 道题已忽略",
+    "scoreboard.ignored.other": "题集之外的 {n} 道题已忽略",
     "scoreboard.weights": "权重:",
     "scoreboard.allWeights": "全部题 ×1",
     "scoreboard.othersWeight": "其余 ×1",
-    "scoreboard.subjectTitle": "{evals} 道题,加权得分 {earned}/{possible}",
+    "scoreboard.subjectTitle": "{questions} 道题,加权得分 {earned}/{possible}",
     "delta.pairHeader": "对比 (A → B)",
-    "board.currentVerdicts": "现刻判定",
-    "board.failing": "失败清单:",
+    "delta.empty": "{experiments} 个实验、0 个可配对",
+    "tabs.tab": "Tab",
 };
 const dictionaries = {
     en,
     "zh-CN": zhCN,
 };
-/** 查字典 + 简单插值({name} 占位符)。缺 locale 回退 en。 */
+/** 查字典 + 简单插值({name} 占位符)。内置词典未覆盖的 locale 回退 en。 */
 export function localeText(locale, key, vars) {
     const template = dictionaries[locale]?.[key] ?? dictionaries.en[key];
     if (!vars)
@@ -189,13 +234,16 @@ export function countText(locale, base, n) {
     return localeText(locale, `${base}.${n === 1 ? "one" : "other"}`, { n });
 }
 /**
- * 按 locale 解析指标 label:字符串原样;字典取当前 locale,缺项回退 en,
- * 再回退字典里任一值;全空回退 fallback(= metric.name)。渲染面(web / text)共用。
+ * 按 locale 解析指标 / 列 label:字符串原样;字典按 LocalizedText 回退规则取值;
+ * undefined 回退 fallback(= metric.name)。渲染面(web / text)共用。
  */
 export function resolveMetricLabel(label, locale, fallback) {
     if (label === undefined)
         return fallback;
-    if (typeof label === "string")
-        return label;
-    return label[locale] ?? label.en ?? Object.values(label).find((v) => v !== undefined) ?? fallback;
+    try {
+        return resolveLocalizedText(label, locale);
+    }
+    catch {
+        return fallback;
+    }
 }

package/dist/report/metrics.d.ts

@@ -26,8 +26,15 @@ export declare const durationMs: Metric<"duration">;
 export declare const tokens: Metric<"tokens">;
 export declare const costUSD: Metric<"cost">;
 /**
- * 唯一读 artifact(o11y,懒加载)的内置指标——其余五个只读瘦身字段。
+ * 读 artifact(o11y,懒加载)的内置指标之一——其余只读瘦身字段。
  * 发布时若该 attempt 没带 o11y(如 copySnapshots 的 artifacts 选项漏了它),
- * value 如实返回 null,渲染成「—」,不冒充 0——见 docs/feature/reports/library.md「内置指标」。
+ * value 如实返回 null,渲染成「—」,不冒充 0。名字带限定词:o11y 事件流中的 assistant
+ * turn 数与 `t.send` 的 `s<session>/t<turn>` 轮次是两个计数。
  */
-export declare const turns: Metric<"turns">;
+export declare const assistantTurns: Metric<"assistant-turns">;
+/**
+ * 同一 attempt 内同一条 shell 命令的重复失败数:每条命令失败 n 次(n > 1)记 n − 1,求和。
+ * 成功执行与只失败一次的命令不计。回答 agent 是否在反复撞同一个已知失败的命令。
+ * 读 o11y.json;skipped 与缺 o11y 返回 null(docs/feature/reports/library/metrics.md「内置指标」)。
+ */
+export declare const repeatedFailedCommands: Metric<"repeated-failed-commands">;

package/dist/report/metrics.js

@@ -12,12 +12,14 @@
 //   durationMs(duration)                           null     实测             实测     实测          lower
 //   tokens(tokens)                                 null     实测;无 usage→null 同左   同左          lower
 //   costUSD(cost)                                  null     同上             同左     同左          lower
-//   turns(turns)                                   null     实测;o11y 缺失→null 同左  同左          lower
+//   assistantTurns(assistant-turns)                null     实测;o11y 缺失→null 同左  同左          lower
+//   repeatedFailedCommands(repeated-failed-commands) null   实测;o11y 缺失→null 同左  同左          lower
 //
-// 两档指标(docs/feature/reports/library.md「内置指标」):以上除 turns 外全部只读 attempt.result
-// 的瘦身字段——任何 producer、任何 copySnapshots artifacts 选择都算得出,内置报告
-// ExperimentComparison 只用这一档。turns 读 attempt.o11y()(懒加载 artifact),发布时若
-// o11y 没随行就诚实渲染缺数据「—」,不算 0——报告作者自己摆时心里要有这根弦,内置报告不用它。
+// 两档指标(docs/feature/reports/library/metrics.md「内置指标」):以上除 assistantTurns 与
+// repeatedFailedCommands 外全部只读 attempt.result 的瘦身字段——任何 producer、任何
+// copySnapshots artifacts 选择都算得出,内置报告 ExperimentComparison 只用这一档。
+// 后两个读 attempt.o11y()(懒加载 artifact),发布时若 o11y 没随行就诚实渲染缺数据「—」,
+// 不算 0——报告作者自己摆时心里要有这根弦,内置报告不用它们。
 /**
  * 定义一个指标。内置指标与自定义指标是同一个类型,没有特权;
  * 校验只管「能进计算」的最低要求,聚合语义见 docs/feature/reports/architecture.md「指标聚合不变量」。
@@ -140,21 +142,22 @@ export const tokens = defineMetric({
 });
 export const costUSD = defineMetric({
     name: "cost",
-    label: { en: "Cost", "zh-CN": "预估成本" },
+    label: { en: "Cost", "zh-CN": "成本" },
     description: "USD cost per attempt (gateway-measured beats estimated).",
     better: "lower",
     unit: "$",
     value: (a) => (a.result.verdict === "skipped" ? null : attemptCostUSD(a.result)),
 });
 /**
- * 唯一读 artifact(o11y,懒加载)的内置指标——其余五个只读瘦身字段。
+ * 读 artifact(o11y,懒加载)的内置指标之一——其余只读瘦身字段。
  * 发布时若该 attempt 没带 o11y(如 copySnapshots 的 artifacts 选项漏了它),
- * value 如实返回 null,渲染成「—」,不冒充 0——见 docs/feature/reports/library.md「内置指标」。
+ * value 如实返回 null,渲染成「—」,不冒充 0。名字带限定词:o11y 事件流中的 assistant
+ * turn 数与 `t.send` 的 `s<session>/t<turn>` 轮次是两个计数。
  */
-export const turns = defineMetric({
-    name: "turns",
-    label: { en: "Turns", "zh-CN": "轮次" },
-    description: "Total agent turns (assistant replies) per attempt. Reads o11y — “—” if not published alongside this attempt.",
+export const assistantTurns = defineMetric({
+    name: "assistant-turns",
+    label: { en: "Assistant turns", "zh-CN": "Assistant 轮次" },
+    description: "Assistant turns in the o11y event stream per attempt. Reads o11y — “—” if not published alongside this attempt.",
     better: "lower",
     unit: "turns",
     async value(a) {
@@ -164,3 +167,34 @@ export const turns = defineMetric({
         return o11y?.totalTurns ?? null;
     },
 });
+/**
+ * 同一 attempt 内同一条 shell 命令的重复失败数:每条命令失败 n 次(n > 1)记 n − 1,求和。
+ * 成功执行与只失败一次的命令不计。回答 agent 是否在反复撞同一个已知失败的命令。
+ * 读 o11y.json;skipped 与缺 o11y 返回 null(docs/feature/reports/library/metrics.md「内置指标」)。
+ */
+export const repeatedFailedCommands = defineMetric({
+    name: "repeated-failed-commands",
+    label: { en: "Repeated failed commands", "zh-CN": "重复失败命令" },
+    description: "Per attempt: for each shell command failing n > 1 times, count n − 1, summed. Reads o11y — “—” if not published alongside this attempt.",
+    better: "lower",
+    unit: "cmds",
+    async value(a) {
+        if (a.result.verdict === "skipped")
+            return null;
+        const o11y = await a.o11y();
+        if (!o11y)
+            return null;
+        const failures = new Map();
+        for (const entry of o11y.shellCommands) {
+            const failed = entry.success === false || (entry.success === undefined && entry.exitCode !== undefined && entry.exitCode !== 0);
+            if (!failed)
+                continue;
+            failures.set(entry.command, (failures.get(entry.command) ?? 0) + 1);
+        }
+        let repeated = 0;
+        for (const n of failures.values())
+            if (n > 1)
+                repeated += n - 1;
+        return repeated;
+    },
+});

package/dist/report/primitives.d.ts

@@ -1,33 +1,60 @@
 import type { AttemptLocator } from "../results/locator.ts";
 import { type ReportNode } from "./tree.ts";
-import { type ReportLocale } from "./locale.ts";
-import { type ColumnAlign } from "./text/layout.ts";
+import { type LocalizedText, type ReportLocale } from "./locale.ts";
+import type { ColumnAlign } from "./text/layout.ts";
 export interface LayoutProps {
     children?: ReportNode;
     className?: string;
 }
-/** 纵向依次排列:网页是块级堆叠,终端是逐块输出(块间空一行)。 */
+export type RowProps = LayoutProps;
+export type ColProps = LayoutProps;
+/** 纵向依次排列:网页是块级堆叠,终端是逐块输出(块间空一行)。两面都按声明序。 */
 export declare const Col: import("./tree.ts").ReportComponent<LayoutProps>;
-/** 并排:网页横向排布,终端字符分栏;终端宽度不够时自动降级为纵向。 */
+/**
+ * 并排:web 面横排;text 面在可用宽度装得下全部子块时按显示宽度并排(与 `columns` 工具
+ * 同一把尺),装不下时整块退化为纵向堆叠——不截断、不隐藏任何子块。
+ */
 export declare const Row: import("./tree.ts").ReportComponent<LayoutProps>;
 export interface SectionProps extends LayoutProps {
-    title: string;
+    title: LocalizedText;
 }
 /** 带标题的块:网页是标题层级,终端是标题行加缩进。 */
 export declare const Section: import("./tree.ts").ReportComponent<SectionProps>;
-/** 说明文字:网页是段落,终端是折行文本。 */
-export declare const Text: import("./tree.ts").ReportComponent<LayoutProps>;
+export interface TextProps {
+    /** 自由正文原样渲染,不随 locale 自动翻译。 */
+    children: string | number;
+    className?: string;
+}
+/** 自由文本的显式载体:web 面负责转义,text 面按显示宽度折行。 */
+export declare const Text: import("./tree.ts").ReportComponent<TextProps>;
 export interface StyleProps {
-    children?: string;
+    children: string;
 }
-/** 自定义组件的样式随树带走:web 面吐 <style> 标签,text 面渲染为空。 */
+/**
+ * 注入页级全局 CSS:树位置只决定声明顺序,不限定作用域;text 面零输出。
+ * 配置对象形态的报告要全站样式优先用外壳 styles,两条通道注入同一增强层。
+ */
 export declare const Style: import("./tree.ts").ReportComponent<StyleProps>;
+export interface TabsProps extends LayoutProps {
+}
+export interface TabProps extends LayoutProps {
+    title: LocalizedText;
+}
+/**
+ * 页内并列视图的可切换块。tab 是页内浏览状态,不是数据边界,也不是宿主寻址单位——
+ * 两个渲染面都输出全部 tab 的完整内容:web 静态 HTML 每 tab 一个 <details>(首个默认展开,
+ * 渐进增强升级成单选 tab 条,切换不改变数据);text 面按声明序输出带标题分节,不折成索引
+ * 也不省略(tab 没有选择器,索引只能是死路)。
+ */
+export declare const Tabs: import("./tree.ts").ReportComponent<TabsProps>;
+/** 只能直接放在 <Tabs> 下;除通用 children / className 外只有 title。不参与路由,没有 id。 */
+export declare const Tab: import("./tree.ts").ReportComponent<TabProps>;
 /** 一列的定义:取哪个 cells 键、表头写什么、往哪边对齐。 */
 export interface TableColumn {
     /** 取 `row.cells[key]` 的键。 */
     key: string;
-    /** 表头文案,两个面都原样渲染。 */
-    header: string;
+    /** 表头文案,按渲染 locale 选择。 */
+    header: LocalizedText;
     /** 对齐方向,默认 `"left"`;`"right"` 按显示宽度右对齐,数字列用。 */
     align?: ColumnAlign;
     /**
@@ -42,15 +69,15 @@ export interface TableRow {
     /** 行身份。 */
     key: string;
     /** 已格式化的显示值;`null`(或缺这个键)渲染成 `—`,不补 0。 */
-    cells: Record<string, string | null>;
+    cells: Readonly<Record<string, string | null>>;
     /** 带上就多一列 attempt:web 面链到证据室,text 面列出 locator。 */
     locator?: AttemptLocator;
 }
 export interface TableProps {
-    /** 列定义;数组顺序即渲染顺序。 */
-    columns: TableColumn[];
+    /** 非空列定义;数组顺序即渲染顺序。 */
+    columns: readonly [TableColumn, ...TableColumn[]];
     /** 行数据;数组顺序即渲染顺序,组件不重排也不过滤。 */
-    rows: TableRow[];
+    rows: readonly TableRow[];
     /** 组件自带文案(attempt 表头、丢列提示)的语言;省略时随宿主。 */
     locale?: ReportLocale;
     /** web 面挂到 `<table>` 上。 */