niceeval 0.9.0 → 0.10.0

package/src/report/{tree.ts → definition/tree.ts}

@@ -10,12 +10,37 @@
 // 只在 resolve 阶段被懒加载,永远不进渲染路径。
 
 import type { ReactNode } from "react";
-import type { AttemptLocator } from "../results/locator.ts";
-import type { Results, Scope } from "../results/types.ts";
-import { DEFAULT_REPORT_LOCALE, type ReportLocale } from "./locale.ts";
-import type { ReportInput } from "./types.ts";
+import type { AttemptLocator } from "../../results/locator.ts";
+import type { AttemptEvidence } from "../../results/attempt-evidence.ts";
+import type { Results, Scope } from "../../results/types.ts";
+import { DEFAULT_REPORT_LOCALE, type ReportLocale } from "../model/locale.ts";
+import type { ReportInput } from "../model/types.ts";
 import type { ReportMeta } from "./report.ts";
 
+// ───────────────────────── 当前页判别(PageContext) ─────────────────────────
+
+/** scope-input page 的当前页上下文:消费宿主选择的 Scope,没有 locator/evidence。 */
+export interface ScopePageContext {
+  id: string;
+  input: "scope";
+}
+
+/** attempt-input page 的当前页上下文:按 locator 消费一份 AttemptEvidence。 */
+export interface AttemptPageContext {
+  id: string;
+  input: "attempt";
+  locator: AttemptLocator;
+  evidence: AttemptEvidence;
+}
+
+/**
+ * 当前渲染中的页判别联合(docs/feature/reports/library/shell.md「行为约束」、
+ * library/attempt-detail.md「page 输入与 spec / data 形态」)。经 ComposeContext.page 与
+ * ResolveContext.page 双双可见:组合组件靠它读当前页 id 与输入分支;attempt 叶子组件靠它
+ * 取省略 input 时的缺省 evidence。
+ */
+export type PageContext = ScopePageContext | AttemptPageContext;
+
 // ───────────────────────── 节点形状 ─────────────────────────
 
 /** 标准 jsx-runtime 元素形状;text 宿主只认 type / props,不管 $$typeof。 */
@@ -67,18 +92,26 @@ export interface TextContext {
   locale: ReportLocale;
   /** 容器组件渲染 children 用,宽度显式传递。 */
   render(node: ReportNode, width?: number): string;
-  /** 下钻命令,通证据室:`niceeval show @<locator>`。 */
-  attemptCommand(locator: AttemptLocator): string;
+  /**
+   * 下钻命令,通 attempt-input page:`niceeval show @<locator>`。当前报告没有声明
+   * attempt-input page 时不存在——宿主不生成假命令,locator 只是文本(architecture.md
+   * 「Attempt 详情是一张参数化 page」)。
+   */
+  attemptCommand?(locator: AttemptLocator): string;
   /**
    * 组索引一类「按实验收窄」命令的生成;宿主注入以携带完整上下文(--results / --report /
-   * --page 与位置参数),默认 `niceeval show --experiment <id>`。非契约字段,官方组件内部用。
+   * --page 与位置参数),默认 `niceeval show --exp <id>`。非契约字段,官方组件内部用。
    */
   experimentCommand(experimentIdPrefix: string): string;
 }
 
 export interface WebContext {
-  /** 证据室深链,同 view 的 attempt 路由(`#/attempt/@<locator>`,单段、不透明)。 */
-  attemptHref(locator: AttemptLocator): string;
+  /**
+   * attempt-input page 深链,同 view 的 attempt 路由(`#/attempt/@<locator>`,单段、不透明)。
+   * 当前报告没有声明 attempt-input page 时不存在——宿主不生成空 href 或假链接,locator 只是
+   * 文本(architecture.md「Attempt 详情是一张参数化 page」)。
+   */
+  attemptHref?(locator: AttemptLocator): string;
   /** chrome 文案的 locale;官方组件渲染面经上下文读取,宿主外默认 "en"。 */
   locale: ReportLocale;
 }
@@ -86,6 +119,8 @@ export interface WebContext {
 /** 双面组件解析面的上下文:宿主注入的数据来源;props 显式给出 input 时以 props 为准。 */
 export interface ResolveContext {
   input: ReportInput;
+  /** 当前页判别;attempt 叶子组件省略 input 时从这里的 attempt 分支取缺省 evidence。 */
+  page: PageContext;
 }
 
 /** 组合组件的上下文:宿主 Scope、结果根完整读取面与规范化后的报告声明。 */
@@ -96,6 +131,8 @@ export interface ComposeContext {
   results: Results;
   /** 规范化后的报告声明,只读(docs/feature/reports/library/layout.md「自定义组件」)。 */
   report: ReportMeta;
+  /** 当前页判别:scope 分支只有 id;attempt 分支带 locator + evidence。 */
+  page: PageContext;
 }
 
 export interface ComponentFaces<P, R = P> {
@@ -125,9 +162,9 @@ export type ReportComponent<P> = ((props: P) => ReactNode) & {
 };
 
 // web 面的环境上下文:web 宿主渲染前设好;宿主之外(组件直接嵌进用户 React 应用)
-// 用默认值 —— attemptHref 默认 view 的 attempt 路由格式。
+// 用默认值——没有 attemptHref,组件显式传 prop 才产生外部链接(architecture.md
+// 「Attempt 详情是一张参数化 page」:没有 target 时 locator 只是文本,不生成假 href)。
 const DEFAULT_WEB_CONTEXT: WebContext = {
-  attemptHref: (locator) => `#/attempt/${locator}`,
   locale: DEFAULT_REPORT_LOCALE,
 };
 let activeWebContext: WebContext | null = null;
@@ -143,11 +180,6 @@ export function runWithWebContext<T>(ctx: WebContext, fn: () => T): T {
   }
 }
 
-/** 官方组件的装配用:宿主上下文激活时才把 ctx.attemptHref 当默认下钻。 */
-export function isHostWebContextActive(): boolean {
-  return activeWebContext !== null;
-}
-
 /** 函数形态:组合组件,只装配已有组件,可以异步;ctx 携带 scope / results / report。 */
 export function defineComponent<P>(
   compose: (props: P, context: ComposeContext) => ReportNode | Promise<ReportNode>,
@@ -269,11 +301,13 @@ export class ResolveMemo {
   }
 }
 
-/** resolveReportTree 的环境:宿主注入的 Scope / 读取面 / 规范化声明。 */
+/** resolveReportTree 的环境:宿主注入的 Scope / 读取面 / 规范化声明 / 当前页判别。 */
 export interface ResolveEnv {
   scope: Scope;
   results: Results;
   report: ReportMeta;
+  /** 当前渲染的页:scope 分支只有 id;attempt 分支带 locator + evidence。 */
+  page: PageContext;
   /** 一次页渲染一份;跨页共享缓存时由宿主显式传同一实例。 */
   memo?: ResolveMemo;
 }
@@ -323,7 +357,7 @@ function bareTextError(value: string | number, path: string[]): Error {
  */
 export async function resolveReportTree(node: ReportNode, env: ResolveEnv): Promise<ReportNode> {
   const memo = env.memo ?? new ResolveMemo();
-  const composeCtx: ComposeContext = { scope: env.scope, results: env.results, report: env.report };
+  const composeCtx: ComposeContext = { scope: env.scope, results: env.results, report: env.report, page: env.page };
   return resolveNode(node, { memo, composeCtx }, []);
 }
 
@@ -367,6 +401,7 @@ async function resolveNode(node: ReportNode | string | number, state: ResolveSta
       const input = ((props as { input?: unknown }).input as ReportInput | undefined) ?? state.composeCtx.scope;
       const ctx: InternalResolveContext = {
         input,
+        page: state.composeCtx.page,
         memoFetch: <T,>(dataFn: unknown, dataInput: unknown, options: unknown, compute: () => Promise<T>) =>
           state.memo.fetch(dataFn, dataInput, options, compute) as Promise<T>,
       };
@@ -528,11 +563,12 @@ function shellQuote(value: string): string {
 export function createTextContext(options?: TextRenderOptions): TextContext {
   const width = Math.max(20, options?.width ?? 80);
   const locale = options?.locale ?? DEFAULT_REPORT_LOCALE;
-  // 默认下钻命令:AttemptLocator 是 `@` 前缀的不透明短串,`niceeval show @<locator>` 是
-  // show 已实现的真实 CLI 语法,不需要反查 eval id 再拼一条近似命令。
-  const attemptCommand = options?.attemptCommand ?? ((locator: AttemptLocator) => `niceeval show ${locator}`);
+  // 没有默认值:当前报告没有声明 attempt-input page 时不存在下钻命令——宿主(report.ts /
+  // web.ts 的渲染入口)据规范化 definition 是否有 attempt page 决定要不要注入生成器,
+  // 这里只透传调用方给的值(architecture.md「Attempt 详情是一张参数化 page」)。
+  const attemptCommand = options?.attemptCommand;
   const experimentCommand =
-    options?.experimentCommand ?? ((prefix: string) => `niceeval show --experiment ${shellQuote(prefix)}`);
+    options?.experimentCommand ?? ((prefix: string) => `niceeval show --exp ${shellQuote(prefix)}`);
   const make = (w: number): TextContext => ({
     width: w,
     locale,

package/src/report/index.ts

@@ -3,7 +3,7 @@
 //
 // import 边界即运行时边界:计算函数(*Data)会经句柄触碰文件系统(懒加载 artifact),
 // 只能进服务端 / 脚本;组件的渲染面纯同步零 IO。text 宿主遍历渲染不需要 react-dom
-// (renderReportToText);web 宿主的 renderReportToStaticHtml 在 ./web.ts,只有那一侧
+// (renderReportToText);web 宿主的 renderReportToStaticHtml 在 ./runtime/web.ts,只有那一侧
 // import react-dom。写报告文件的项目要装 react(.tsx 编译产物 import react/jsx-runtime)。
 
 // 指标与维度读取器
@@ -18,59 +18,73 @@ export {
   repeatedFailedCommands,
   taskPassRate,
   tokens,
-} from "./metrics.ts";
-export { flag, numericFlag, numericRunConfig, runConfig } from "./flag.ts";
+} from "./model/metrics.ts";
+export { flag, label, numericFlag, numericLabel, numericRunConfig, runConfig } from "./model/flag.ts";
 
 // 报告定义与组件基座
 export {
   buildReportMeta,
   defineReport,
   isReportDefinition,
-  pickReportPage,
-  renderReportToText,
-  renderReportTreeToText,
-  reportTitleText,
   resolveReportTitle,
-  ReportPageNotFoundError,
   DEFAULT_PAGE_ID,
-} from "./report.ts";
+} from "./definition/report.ts";
 export type {
-  HostCommandContext,
   NonEmptyArray,
-  RenderReportTextOptions,
-  RenderTreeTextOptions,
-  ReportTreeHostContext,
   HeadTag,
   ReportAsset,
   ReportDef,
   ReportDefinition,
-  ReportHostContext,
   ReportLink,
   ReportMeta,
+  ReportMetaPage,
   ReportPage,
+  ReportPageBase,
   ReportShell,
-} from "./report.ts";
-export { defineComponent, createTextContext, renderNodeToText, resolveReportTree, validateReportTree, ResolveMemo } from "./tree.ts";
+} from "./definition/report.ts";
+export {
+  pickReportPage,
+  renderReportToText,
+  renderReportTreeToText,
+  reportTitleText,
+  ReportPageNotFoundError,
+  ReportPageNeedsLocatorError,
+} from "./runtime/text.ts";
+export type {
+  HostCommandContext,
+  RenderReportTextOptions,
+  RenderTreeTextOptions,
+  ReportTreeHostContext,
+  ReportHostContext,
+} from "./runtime/text.ts";
+export { defineComponent, createTextContext, renderNodeToText, resolveReportTree, validateReportTree, ResolveMemo } from "./definition/tree.ts";
+export type { AttemptEvidence, AttemptEvidenceCapabilities } from "../results/attempt-evidence.ts";
 export type {
+  AttemptPageContext,
   ComponentFaces,
   ComposeContext,
+  PageContext,
   ReportComponent,
   ReportElement,
   ReportNode,
   ResolveContext,
   ResolveEnv,
+  ScopePageContext,
   TextContext,
   TextRenderOptions,
   WebContext,
-} from "./tree.ts";
+} from "./definition/tree.ts";
 
-// 排版原语(八个内置双面组件)
-export { Col, Row, Section, Style, Tab, Table, Tabs, Text } from "./primitives.tsx";
+// 排版原语(十个内置双面组件)
+export { Col, Grid, Row, Section, Stat, Style, Tab, Table, Tabs, Text } from "./definition/primitives.tsx";
 export type {
   ColProps,
+  GridProps,
   LayoutProps,
   RowProps,
   SectionProps,
+  StatProps,
+  StatTone,
   StyleProps,
   TabProps,
   TableColumn,
@@ -78,7 +92,7 @@ export type {
   TableRow,
   TabsProps,
   TextProps,
-} from "./primitives.tsx";
+} from "./definition/primitives.tsx";
 
 // 文本排版工具箱:自定义组件的 text 面用的就是官方组件那把尺子。
 // 表格有 <Table> 承担,这里只给表以外的形态用 —— 尤其别拿 String.prototype.padEnd 对齐:
@@ -91,78 +105,90 @@ export {
   indentBlock as indent,
   textBar as bar,
   joinColumns as columns,
-} from "./text/layout.ts";
-export type { ColumnAlign } from "./text/layout.ts";
+} from "./model/text-layout.ts";
+export type { ColumnAlign } from "./model/text-layout.ts";
 
 // locale:官方组件 chrome 文案的语言(内置词典覆盖 en / zh-CN,其它 locale 走回退)
-export { DEFAULT_REPORT_LOCALE, localizedTextEquals, resolveLocalizedText, resolveMetricLabel } from "./locale.ts";
-export type { LocalizedText, ReportLocale } from "./locale.ts";
+export { DEFAULT_REPORT_LOCALE, localizedTextEquals, resolveLocalizedText, resolveMetricLabel } from "./model/locale.ts";
+export type { LocalizedText, ReportLocale } from "./model/locale.ts";
 
 // 官方双面组件(spec / data 双形态;配套 *Data 计算函数在下面成对导出)
 // 与站点组件(Hero / HeroCard / PoweredBy / ScopeWarnings / CopyFixPrompt / TraceWaterfall)
+export { ScopeSummary, ExperimentComparison } from "./components/summaries/index.tsx";
+export type { ScopeSummaryProps, ExperimentComparisonProps } from "./components/summaries/index.tsx";
+export { AttemptList, EvalList, ExperimentList, FailureList } from "./components/entity-lists/index.tsx";
+export type {
+  AttemptListProps,
+  EvalListProps,
+  ExperimentListProps,
+  FailureListProps,
+} from "./components/entity-lists/index.tsx";
 export {
-  AttemptList,
-  CopyFixPrompt,
   DeltaTable,
-  EvalList,
-  ExperimentComparison,
-  ExperimentList,
-  FailureList,
-  Hero,
-  HeroCard,
   MetricBars,
   MetricLine,
   MetricMatrix,
   MetricScatter,
   MetricTable,
-  PoweredBy,
   Scoreboard,
-  ScopeSummary,
-  ScopeWarnings,
-  TraceWaterfall,
-} from "./components.tsx";
+} from "./components/metric-views/index.tsx";
 export type {
-  AttemptListProps,
-  CopyFixPromptProps,
-  DataProps,
   DeltaTableProps,
-  EvalListProps,
-  ExperimentComparisonProps,
-  ExperimentListProps,
-  FailureListProps,
-  HeroCardProps,
-  HeroProps,
   MetricBarsProps,
   MetricLineProps,
   MetricMatrixProps,
   MetricScatterProps,
   MetricTableProps,
   ScoreboardProps,
-  ScopeSummaryProps,
+} from "./components/metric-views/index.tsx";
+export {
+  CopyFixPrompt,
+  Hero,
+  HeroCard,
+  PoweredBy,
+  ScopeWarnings,
+  TraceWaterfall,
+} from "./components/site-components/index.tsx";
+export type {
+  CopyFixPromptProps,
+  HeroCardProps,
+  HeroProps,
   ScopeWarningsProps,
   TraceWaterfallProps,
-} from "./components.tsx";
+} from "./components/site-components/index.tsx";
+
+// Attempt 详情组件族(docs/feature/reports/library/attempt-detail.md):11 个叶子 + 2 个
+// 只装配叶子的组合组件(AttemptAssessment / AttemptDetail),都从 niceeval/report 导出。
+export {
+  AttemptAssertions,
+  AttemptAssessment,
+  AttemptConversation,
+  AttemptDetail,
+  AttemptDiagnostics,
+  AttemptDiff,
+  AttemptError,
+  AttemptFixPrompt,
+  AttemptSource,
+  AttemptSummary,
+  AttemptTimeline,
+  AttemptTrace,
+  AttemptUsage,
+} from "./components/attempt-detail/index.tsx";
+export type { AttemptSectionProps } from "./components/attempt-detail/index.tsx";
 
 // 计算函数(组件解析面的具名形式,与组件成对;spec 形态下由管线代调,data 形态与
 // 嵌入场景下由作者手工调)
+export { scopeSummaryData } from "./components/summaries/compute.ts";
+export { attemptListData, evalListData, experimentListData } from "./components/entity-lists/compute.ts";
 export {
-  attemptListData,
-  copyFixPromptData,
   deltaTableData,
-  evalListData,
-  experimentComparisonData,
-  experimentListData,
-  heroData,
   metricLineData,
   metricMatrixData,
   metricScatterData,
   metricTableData,
   pairsByFlag,
-  scopeSummaryData,
-  scopeWarningsData,
   scoreboardData,
-  traceWaterfallData,
-} from "./compute.ts";
+} from "./components/metric-views/compute.ts";
 export type {
   DeltaTableOptions,
   MetricLineOptions,
@@ -170,7 +196,28 @@ export type {
   MetricScatterOptions,
   MetricTableOptions,
   ScoreboardOptions,
-} from "./compute.ts";
+} from "./components/metric-views/compute.ts";
+export {
+  copyFixPromptData,
+  heroData,
+  scopeWarningsData,
+  traceWaterfallData,
+} from "./components/site-components/compute.ts";
+
+// Attempt 详情组件族的计算函数:输入恒为单个 AttemptEvidence,同步纯派生(不读文件、不 fetch)。
+export {
+  attemptAssertionsData,
+  attemptConversationData,
+  attemptDiagnosticsData,
+  attemptDiffData,
+  attemptErrorData,
+  attemptFixPromptData,
+  attemptSourceData,
+  attemptSummaryData,
+  attemptTimelineData,
+  attemptTraceData,
+  attemptUsageData,
+} from "./components/attempt-detail/compute.ts";
 
 // 数据契约(组件的 data)
 export type {
@@ -186,8 +233,6 @@ export type {
   DimensionOptions,
   DimensionRef,
   EvalListItem,
-  ExperimentComparisonData,
-  ExperimentComparisonGroupData,
   ExperimentListEvalRow,
   ExperimentListItem,
   FlagPairs,
@@ -207,15 +252,30 @@ export type {
   ScopeSummaryData,
   ScopeWarning,
   ScoreboardData,
+  SeriesInput,
   TableData,
   TraceSpanSummary,
   TraceWaterfallRow,
   VerdictTally,
-} from "./types.ts";
+} from "./model/types.ts";
+
+// Attempt 详情组件族的数据契约
+export type {
+  AttemptAssertionsData,
+  AttemptConversationData,
+  AttemptConversationReply,
+  AttemptConversationRound,
+  AttemptDiagnosticsData,
+  AttemptDiffData,
+  AttemptDiffFileEntry,
+  AttemptErrorData,
+  AttemptFixPromptData,
+  AttemptSourceData,
+  AttemptSummaryData,
+  AttemptTimelineData,
+  AttemptTraceData,
+  AttemptUsageData,
+} from "./model/types.ts";
 
 // 数据层输入的类型(家在 niceeval/results,这里 re-export 方便写指标 / 报告)
 export type { AttemptHandle, Results, Scope, Snapshot } from "../results/types.ts";
-
-// experiment id 的组键推导(id 的目录前缀,如 `compare/bub-low` 的 `compare`)。
-// 重新导出,让自定义报告能按同一份口径把 experiment 分组,不必自己重写这两行逻辑。
-export { experimentGroupOf } from "../shared/aggregate.ts";

package/src/report/{aggregate.ts → model/aggregate.ts}

@@ -6,9 +6,9 @@
 // 和重试策略纠缠在一起(eval A=[1]、eval B=[0,0,0] 平铺 = 0.25,两级宏平均 = 0.5)。
 // 自定义维度把同一道题的 attempt 分进不同组时,第一级折叠发生在各组内部。
 
-import { dedupeAttempts } from "../results/select.ts";
-import type { AttemptHandle, Scope, ScopeWarning, Snapshot } from "../results/types.ts";
-import { encodeAttemptLocator, type AttemptLocator } from "../results/locator.ts";
+import { dedupeAttempts } from "../../results/select.ts";
+import type { AttemptHandle, Scope, ScopeWarning, Snapshot } from "../../results/types.ts";
+import { encodeAttemptLocator, type AttemptLocator } from "../../results/locator.ts";
 import type {
   Aggregator,
   DimensionInput,
@@ -18,11 +18,12 @@ import type {
   MetricColumn,
   NumericAxis,
   ReportInput,
+  SeriesInput,
 } from "./types.ts";
-import { flagValueOf, runConfigValueOf } from "./flag.ts";
+import { flagValueOf, labelValueOf, runConfigValueOf } from "./flag.ts";
 import { formatMetricValue, localizedDisplay } from "./format.ts";
 import { localeText, type LocalizedText } from "./locale.ts";
-import { evalPrefixPredicate } from "../shared/aggregate.ts";
+import { evalPrefixPredicate } from "../../shared/aggregate.ts";
 
 // 复合键分隔符:NUL 不会出现在 eval id / experimentId / ISO 时间里,拼接键不会串味
 const KEY_SEP = "\u0000";
@@ -119,7 +120,9 @@ function isDimensionRef(dimension: DimensionInput): dimension is DimensionRef {
   return (
     typeof dimension === "object" &&
     "kind" in dimension &&
-    ((dimension as DimensionRef).kind === "flag" || (dimension as DimensionRef).kind === "runConfig")
+    ((dimension as DimensionRef).kind === "flag" ||
+      (dimension as DimensionRef).kind === "runConfig" ||
+      (dimension as DimensionRef).kind === "label")
   );
 }
 
@@ -147,9 +150,9 @@ export function refDisplayKey(value: unknown): [display: string, canonical: stri
 }
 
 function refValueOf(ref: DimensionRef, item: Item): unknown {
-  return ref.kind === "flag"
-    ? flagValueOf(item.attempt, ref.name)
-    : runConfigValueOf(item.attempt, ref.name as Parameters<typeof runConfigValueOf>[1]);
+  if (ref.kind === "flag") return flagValueOf(item.attempt, ref.name);
+  if (ref.kind === "label") return labelValueOf(item.attempt, ref.name);
+  return runConfigValueOf(item.attempt, ref.name as Parameters<typeof runConfigValueOf>[1]);
 }
 
 export function dimensionKey(dimension: DimensionInput, item: Item): string {
@@ -179,6 +182,25 @@ export function dimensionKey(dimension: DimensionInput, item: Item): string {
   }
 }
 
+/**
+ * series 类选项(SeriesInput)的复合维度解析:数组形态的维度 name 依声明顺序以 ` × ` 连接,
+ * 每个 attempt 的维度值为各成员显示键以 ` · ` 连接(缺失成员沿用 `(missing)` 显示键参与
+ * 连接,与单维度缺失同一条规则)。单维度形态与 dimensionName / dimensionKey 严格等价。
+ */
+export function seriesMembers(series: SeriesInput): readonly DimensionInput[] {
+  return Array.isArray(series) ? (series as readonly DimensionInput[]) : [series as DimensionInput];
+}
+
+export function seriesName(series: SeriesInput): string {
+  return seriesMembers(series).map(dimensionName).join(" × ");
+}
+
+export function seriesKey(series: SeriesInput, item: Item): string {
+  return seriesMembers(series)
+    .map((member) => dimensionKey(member, item))
+    .join(" · ");
+}
+
 /**
  * 按维度分组;维度 domain 按稳定 key 字典序(Unicode)排列,不让文件扫描顺序渗进报告。
  * flag / runConfig 维度做显示键冲突检测:不同原始值生成同一显示键时报错并要求改用

package/src/report/{flag.ts → model/flag.ts}

@@ -4,7 +4,7 @@
 // flag() 只读 `ExperimentDef.flags` 里显式声明的 KV;model / reasoningEffort / budget / runs
 // 这类顶层运行配置不在 flags 里,用 runConfig() 读快照的 ExperimentRunInfo 投影。
 
-import type { AttemptHandle } from "../results/types.ts";
+import type { AttemptHandle } from "../../results/types.ts";
 import type {
   DimensionOptions,
   DimensionRef,
@@ -20,6 +20,12 @@ export function flagValueOf(attempt: AttemptHandle, name: string): unknown {
   return info?.flags?.[name];
 }
 
+/** experiment 声明的报告归类标注 labels(同 flags 的读取回退链;值域 string | number)。 */
+export function labelValueOf(attempt: AttemptHandle, name: string): unknown {
+  const info = attempt.snapshot?.experiment ?? attempt.result.experiment;
+  return info?.labels?.[name];
+}
+
 /**
  * runConfig() 的取值:读快照的 `ExperimentRunInfo` 投影,外加桥接到快照顶层权威字段的
  * `model` / `agent` 两个键(与 "model" / "agent" 内置维度同一读法,不另造第二套口径)。
@@ -54,6 +60,21 @@ export function flag(name: string, options?: DimensionOptions): DimensionRef {
   };
 }
 
+/**
+ * 把 experiment 声明的一个报告标注(`ExperimentDef.labels` 的键)当分组维度,与 {@link flag}
+ * 同一套用法。labels 是纯报告侧的归类坐标:不透传运行时、不参与可比性配置;报告不从
+ * experiment id 字符串猜语义,归类只认声明(docs/feature/experiments/library.md「labels」)。
+ */
+export function label(name: string, options?: DimensionOptions): DimensionRef {
+  assertName(name, "label", "the key declared in the experiment's labels");
+  return {
+    kind: "label",
+    name,
+    ...(options?.label !== undefined ? { label: options.label } : {}),
+    ...(options?.unit !== undefined ? { unit: options.unit } : {}),
+  };
+}
+
 /**
  * 把一项顶层运行配置当分组维度,与 {@link flag} 同一套用法。读快照的 `ExperimentRunInfo`
  * 投影;可用键由 RunConfigKey 在类型层穷尽(那张接口的字段全集,外加桥接到快照顶层权威
@@ -86,6 +107,23 @@ export function numericFlag(name: string, options?: NumericAxisOptions): Numeric
   };
 }
 
+/**
+ * MetricLine 的 x 轴:只接受 number 值的 label。labels 由作者亲手声明,要数值轴就直接
+ * 声明成 number,不设 map;字符串值返回 null(折线不绘该点并报告缺失)。
+ */
+export function numericLabel(name: string, options?: NumericAxisOptions): NumericAxis {
+  assertName(name, "numericLabel", "the key declared in the experiment's labels");
+  return {
+    name,
+    ...(options?.label !== undefined ? { label: options.label } : {}),
+    ...(options?.unit !== undefined ? { unit: options.unit } : {}),
+    of(attempt) {
+      const value = labelValueOf(attempt, name);
+      return typeof value === "number" && Number.isFinite(value) ? value : null;
+    },
+  };
+}
+
 /**
  * 顶层运行配置作数值轴:数值配置直接返回该值;字符串配置必须显式给 `map`
  * (如 { low: 1, medium: 2, high: 3 })。未声明、未投影、非数值或未命中 map 的值返回 null。