niceeval 0.6.2 → 0.7.0

package/dist/report/types.js

@@ -1,4 +1,5 @@
-// niceeval/report 的公开类型:指标(Metric)、维度(Dimension / flag())与计算函数
-// 产物(即组件的 data props)。数据契约照 docs/feature/reports/library.md「数据计算与缓存边界」;
-// 这些不是持久化格式,没有 format / schemaVersion 信封,兼容性跟随 npm 版本。
+// niceeval/report 的公开类型:指标(Metric)、维度(Dimension / flag() / runConfig())与
+// 计算函数产物(即组件的 data)。数据契约照 docs/feature/reports/library/ 各分篇;
+// 这些不是持久化格式,没有 format / schemaVersion 信封,兼容性跟随 npm 版本
+// (组件消费 data 时校验结构,不符按完整用户反馈报错并提示版本漂移)。
 export {};

package/dist/report/web.d.ts

@@ -1,15 +1,31 @@
 import type { AttemptLocator } from "../results/locator.ts";
+import type { Scope } from "../results/types.ts";
 import { type ReportLocale } from "./locale.ts";
-import type { ReportContext, ReportDefinition } from "./report.ts";
+import { type ReportDefinition, type ReportHostContext } from "./report.ts";
 export interface StaticHtmlOptions {
+    /** 渲染哪一页;缺省第一页。未命中抛 ReportPageNotFoundError。 */
+    pageId?: string;
     /** 证据室深链;缺省用 view 的 attempt 路由 `#/attempt/@<locator>`(单段、不透明)。 */
     attemptHref?: (locator: AttemptLocator) => string;
     /** 官方组件 chrome 文案的 locale;默认 "en"。 */
     locale?: ReportLocale;
 }
 /**
- * build → 渲染前解析数据组件(唯一的 await 边界)→ 树校验(与 text 宿主同一遍)→ 静态渲染
- * web 面;Selection 有挑选警告时在报告顶部前置一块警告 HTML；报告树里的 RunOverview
- * 已经渲染同一条时不重复。
+ * web 宿主的装载语义:选页 → resolve(组合展开 + spec 取数,唯一的 await 边界)→
+ * 树校验(与 text 宿主同一遍)→ 静态渲染 web 面;Scope 有挑选警告时在报告顶部前置
+ * 一块警告 HTML(宿主是 warning 的唯一呈现者,组件数据不复制 warning)。
  */
-export declare function renderReportToStaticHtml(definition: ReportDefinition, ctx: ReportContext, options?: StaticHtmlOptions): Promise<string>;
+export declare function renderReportToStaticHtml(definition: ReportDefinition, ctx: ReportHostContext, options?: StaticHtmlOptions): Promise<string>;
+/**
+ * 渲染一页报告树的 web 面(宿主逐页调用;页选择归宿主):resolve → validate → 静态渲染。
+ * Scope 有挑选警告时在页顶前置警告块(带 command 的警告渲染为可复制命令)——宿主是
+ * warning 的唯一呈现者,组件数据不复制 warning。ctx.report 是宿主规范化后的声明。
+ */
+export declare function renderReportTreeToStaticHtml(tree: import("./tree.ts").ReportNode, ctx: {
+    scope: Scope;
+    results: import("../results/types.ts").Results;
+    report: import("./report.ts").ReportMeta;
+}, options?: {
+    attemptHref?: (locator: AttemptLocator) => string;
+    locale?: ReportLocale;
+}): Promise<string>;

package/dist/report/web.js

@@ -3,35 +3,61 @@
 // 所以本文件不从 niceeval/report 的入口 re-export —— 宿主与测试按源路径 import。
 import * as React from "react";
 import { renderToStaticMarkup } from "react-dom/server";
-import { resolveReportTree, runWithWebContext, validateReportTree } from "./tree.js";
+import { resolveReportTree, runWithWebContext, validateReportTree, ResolveMemo, } from "./tree.js";
 import { DEFAULT_REPORT_LOCALE } from "./locale.js";
+import { buildReportMeta, pickReportPage } from "./report.js";
 /**
- * 挑选警告的 HTML 形态:宿主级前置块,与 RunOverview 里的警告用同一套结构和类名
- * (`.nre nre-report-warnings` 外壳内一个 `ul.nre-warnings` + `li.nre-warning[data-kind]`,
- * 复用 styles.css 已有的 `.nre .nre-warnings` 样式)。经 renderToStaticMarkup 走 React,
- * message 文本自动转义,不裸拼 HTML。裸跑 / --report 都在报告顶上如实报残缺,不静默。
+ * 挑选警告的 HTML 形态:宿主级前置块(`.nre nre-report-warnings` 外壳内一个
+ * `ul.nre-warnings` + `li.nre-warning[data-kind]`,复用 styles.css 已有样式)。
+ * 带 `command` 的警告把命令渲染为可复制块(`.nre-warning-command`);无 command 的
+ * 只显示 message,不硬造动作。经 renderToStaticMarkup 走 React,文本自动转义。
  */
-function renderSelectionWarningsHtml(warnings) {
-    return renderToStaticMarkup(React.createElement("div", { className: "nre nre-report-warnings" }, React.createElement("ul", { className: "nre-warnings" }, warnings.map((w, i) => React.createElement("li", { key: i, className: "nre-warning", "data-kind": w.kind }, w.message)))));
+function renderScopeWarningsHtml(scope) {
+    return renderToStaticMarkup(React.createElement("div", { className: "nre nre-report-warnings" }, React.createElement("ul", { className: "nre-warnings" }, scope.warnings.map((w, i) => React.createElement("li", { key: i, className: "nre-warning", "data-kind": w.kind }, w.message, "command" in w && w.command
+        ? React.createElement("code", { className: "nre-warning-command", "data-nre-copy": w.command }, w.command)
+        : null)))));
 }
 /**
- * build → 渲染前解析数据组件(唯一的 await 边界)→ 树校验(与 text 宿主同一遍)→ 静态渲染
- * web 面;Selection 有挑选警告时在报告顶部前置一块警告 HTML；报告树里的 RunOverview
- * 已经渲染同一条时不重复。
+ * web 宿主的装载语义:选页 → resolve(组合展开 + spec 取数,唯一的 await 边界)→
+ * 树校验(与 text 宿主同一遍)→ 静态渲染 web 面;Scope 有挑选警告时在报告顶部前置
+ * 一块警告 HTML(宿主是 warning 的唯一呈现者,组件数据不复制 warning)。
  */
 export async function renderReportToStaticHtml(definition, ctx, options) {
-    const node = await definition.build(ctx);
-    const resolved = await resolveReportTree(node);
+    const page = pickReportPage(definition, options?.pageId);
+    const meta = buildReportMeta(definition, ctx.scope, page.id);
+    const resolved = await resolveReportTree(page.content, {
+        scope: ctx.scope,
+        results: ctx.results,
+        report: meta,
+        memo: new ResolveMemo(),
+    });
     validateReportTree(resolved);
     const webCtx = {
         attemptHref: options?.attemptHref ?? ((locator) => `#/attempt/${locator}`),
         locale: options?.locale ?? DEFAULT_REPORT_LOCALE,
     };
     const body = runWithWebContext(webCtx, () => renderToStaticMarkup(resolved));
-    const missingWarnings = ctx.selection.warnings.filter((warning) => {
-        const escapedMessage = renderToStaticMarkup(React.createElement(React.Fragment, null, warning.message));
-        return !body.includes(escapedMessage);
+    const warnings = ctx.scope.warnings.length > 0 ? renderScopeWarningsHtml(ctx.scope) : "";
+    return warnings + body;
+}
+/**
+ * 渲染一页报告树的 web 面(宿主逐页调用;页选择归宿主):resolve → validate → 静态渲染。
+ * Scope 有挑选警告时在页顶前置警告块(带 command 的警告渲染为可复制命令)——宿主是
+ * warning 的唯一呈现者,组件数据不复制 warning。ctx.report 是宿主规范化后的声明。
+ */
+export async function renderReportTreeToStaticHtml(tree, ctx, options) {
+    const resolved = await resolveReportTree(tree, {
+        scope: ctx.scope,
+        results: ctx.results,
+        report: ctx.report,
+        memo: new ResolveMemo(),
     });
-    const warnings = missingWarnings.length > 0 ? renderSelectionWarningsHtml(missingWarnings) : "";
+    validateReportTree(resolved);
+    const webCtx = {
+        attemptHref: options?.attemptHref ?? ((locator) => `#/attempt/${locator}`),
+        locale: options?.locale ?? DEFAULT_REPORT_LOCALE,
+    };
+    const body = runWithWebContext(webCtx, () => renderToStaticMarkup(resolved));
+    const warnings = ctx.scope.warnings.length > 0 ? renderScopeWarningsHtml(ctx.scope) : "";
     return warnings + body;
 }

package/dist/results/select.d.ts

@@ -1,37 +1,59 @@
-import type { AttemptHandle, DedupeWarning, Experiment, Results, Selection, SelectionWarning, Snapshot } from "./types.ts";
+import type { AttemptHandle, DedupeWarning, Experiment, Results, Scope, ScopeWarning, Snapshot } from "./types.ts";
+import type { ExperimentRunInfo, JsonValue } from "../types.ts";
 /** Results.latest() 的实现:每个实验取最新一次快照(= exp.snapshots[0]),生成挑选警告。 */
 export declare function selectLatest(experiments: Experiment[], opts?: {
     experiments?: string | string[];
-}): Selection;
+}): Scope;
 /** selectCurrentResults 的范围输入:experiment id 前缀与 eval id 前缀,都可缺省。 */
 export interface ResultScope {
     /** experiment id 前缀(--experiment),分段匹配语义同 filterExperiments。 */
-    experiment?: string;
-    /** eval id 前缀(位置参数),收窄 Selection 覆盖的 eval;覆盖警告分母同步收窄到范围内。 */
+    experiment?: string | string[];
+    /** eval id 前缀(位置参数),收窄 Scope 覆盖的 eval;覆盖警告分母同步收窄到范围内。 */
     patterns?: string[];
 }
 /**
- * 两个宿主(show / view)共用的现刻水位选择器:每个 experiment × eval 取时间上最新的那份
- * 判定,跨 run 合成。results.latest() 只挑「每实验最新快照」,带 eval 前缀的局部重跑会产出
- * 残缺快照;现刻水位承诺「不会因为一次局部重跑变残缺」,所以在实验的全部历史快照上逐 eval
- * 向更早的 run 补齐,再把合成好的 Selection 交给宿主注入报告槽——内置默认报告与 --report 吃
- * 同一份。
+ * current() 跨快照拼接的可比性前提所比较的字段集(docs/feature/results/library.md
+ * 「官方现刻水位」):会改变单题被测行为或判定的字段。runs / earlyExit / maxConcurrency /
+ * selectedEvalIds / evalFilterFingerprint / description 是编排与选题字段,不参与比较。
+ */
+export interface ComparabilityConfig {
+    agent: string;
+    model?: string;
+    reasoningEffort?: string;
+    flags?: Record<string, JsonValue>;
+    budget?: number;
+    timeoutMs?: number;
+    sandbox?: ExperimentRunInfo["sandbox"];
+}
+/** 一个快照的可比性配置投影;pairsByFlag 与 experimentListData 复用同一字段集。 */
+export declare function comparabilityConfigOf(snapshot: Snapshot): ComparabilityConfig;
+/** 可序列化值的深相等(对象键序无关;undefined 字段与缺席字段等价)。 */
+export declare function deepEqualJson(a: unknown, b: unknown): boolean;
+/**
+ * 两个宿主(show / view)共用的现刻水位选择器:每个 experiment × eval 取「包含该 eval 的
+ * 最新快照」里的全部 attempt,跨 run 合成。results.latest() 只挑「每实验最新快照」,带 eval
+ * 前缀的局部重跑会产出残缺快照;现刻水位承诺「不会因为一次局部重跑变残缺」,所以在实验的
+ * 历史快照上逐 eval 向更早的 run 补齐,再把合成好的 Scope 交给宿主注入报告槽。
+ *
+ * **可比性前提**:每个 experiment 以最新快照的可比性配置(agent / model / reasoningEffort /
+ * flags / budget / timeoutMs / sandbox)为基准,只有配置与基准深相等的历史快照才参与补齐;
+ * 改过配置后只补跑部分 eval 时,旧配置快照覆盖的其余题不冒充新配置的水位,按 partial-coverage
+ * 如实告警。这保证 current() 产出的每个 experiment 只对应一套配置。
  *
  * 同一 eval 的全部 attempts 必须整批取自包含它的最新快照,不把历史快照的 attempts 平铺后
  * 按 eval 聚合——否则会把不同运行的重试混成一次虚构运行。合成快照的 dir/元数据只服务报告
  * 分组与来源展示,证据身份一律来自 attempt 自己的 ref。
- * 警告随 Selection 重算:partial-coverage 的分母 = 已知并集 ∩ 范围(范围收窄时分母同步收窄,
- * 不让范围外的缺口刷屏);stale / unfinished 与 results.latest() 同口径。
  */
-export declare function selectCurrentResults(results: Results, scope?: ResultScope): Selection;
+export declare function selectCurrentResults(results: Results, scope?: ResultScope): Scope;
 /**
- * Selection 构造:filter 只删不换 —— 快照删减,warnings 修剪规则是
- * 「experimentId 不在幸存快照中的丢弃,非实验作用域的保留」(为将来非 per-experiment 的 kind 留位置)。
+ * Scope 构造:attempts 按口径物化(快照 attempts 的平铺);filter 只删不换 —— 快照删减,
+ * attempts 随之同步修剪,warnings 修剪规则是「experimentId 不在幸存快照中的丢弃,
+ * 非实验作用域的保留」(为将来非 per-experiment 的 kind 留位置)。
  */
-export declare function makeSelection(snapshots: Snapshot[], warnings: SelectionWarning[]): Selection;
+export declare function makeScope(mode: Scope["mode"], snapshots: Snapshot[], warnings: ScopeWarning[]): Scope;
 /**
  * 跨快照聚合前的身份键去重:(experimentId, evalId, attempt, startedAt)。
- * --resume 会把上一轮已通过的结果原样合入新快照,同一 attempt 因此存在于多份落盘;
+ * 携带合入会把上一轮已通过的结果原样合入新快照,同一 attempt 因此存在于多份落盘;
  * 重复时保留最新快照里的那份(内容相同,取新快照的副本让 ref 落在最新落盘上;
  * 位置取首次出现处,顺序稳定)。startedAt 缺失时宁可不去重也不误删,记入 warnings。
  */

package/dist/results/select.js

@@ -1,15 +1,15 @@
-// 快照 Selection 与 attempt 去重(定稿见 docs/feature/results/library.md「选择快照」「身份键与去重」)。
+// 快照 Scope 与 attempt 去重(定稿见 docs/feature/results/library.md「选择快照」「官方现刻水位」「身份键与去重」)。
 //
-// 选择器只有一个(latest),长在集合上;它不是 DSL,只是最常用的那次筛选。
-// 选择器必须诚实:残缺、落后、未收尾都被算出来,以结构化 warnings 随 Selection 走 ——
-// 渲染与否在消费方(message 是渲染好的英文句子),但缺口不静默。
+// 选择器长在集合上(results.latest() / results.current()),不是 DSL,只是最常用的两种口径。
+// 选择器必须诚实:残缺、落后、未收尾都被算出来,以结构化 warnings 随 Scope 走 ——
+// 渲染与否在消费方(message 是渲染好的英文句子,以下一步收尾),但缺口不静默。
 import { evalPrefixPredicate } from "../shared/aggregate.js";
 /** Results.latest() 的实现:每个实验取最新一次快照(= exp.snapshots[0]),生成挑选警告。 */
 export function selectLatest(experiments, opts) {
     const selected = filterExperiments(experiments, opts?.experiments);
     const snapshots = selected.map((exp) => exp.latest);
     const warnings = [];
-    // stale 的基准:Selection 中最新的落盘(无阈值,如实触发;要阈值消费方按字段自比)。
+    // stale 的基准:Scope 中最新的落盘(无阈值,如实触发;要阈值消费方按字段自比)。
     let latestStartedAt = "";
     for (const snapshot of snapshots) {
         if (snapshot.startedAt > latestStartedAt)
@@ -28,6 +28,7 @@ export function selectLatest(experiments, opts) {
                 covered,
                 total,
                 message: `snapshot covers ${covered} of ${total} evals seen in history; re-run \`niceeval exp ${exp.id}\` for a full snapshot`,
+                command: `niceeval exp ${exp.id}`,
             });
         }
         if (snapshot.startedAt < latestStartedAt) {
@@ -36,7 +37,8 @@ export function selectLatest(experiments, opts) {
                 experimentId: exp.id,
                 startedAt: snapshot.startedAt,
                 latestStartedAt,
-                message: `snapshot "${exp.id}" (${snapshot.startedAt}) predates the latest run in this selection by ${humanizeGap(snapshot.startedAt, latestStartedAt)}`,
+                message: `snapshot "${exp.id}" (${snapshot.startedAt}) predates the latest run in this scope by ${humanizeGap(snapshot.startedAt, latestStartedAt)}; re-run \`niceeval exp ${exp.id}\` to align, or ignore if evals, agent and model are unchanged between the runs`,
+                command: `niceeval exp ${exp.id}`,
             });
         }
         if (!snapshot.completedAt) {
@@ -45,24 +47,58 @@ export function selectLatest(experiments, opts) {
                 experimentId: exp.id,
                 startedAt: snapshot.startedAt,
                 dir: snapshot.dir,
-                message: `snapshot "${exp.id}" (${snapshot.startedAt}) has no completedAt — the run was interrupted; results may be incomplete`,
+                message: `snapshot "${exp.id}" (${snapshot.startedAt}) has no completedAt — the run was interrupted; re-run \`niceeval exp ${exp.id}\` for a complete snapshot`,
+                command: `niceeval exp ${exp.id}`,
             });
         }
     }
-    return makeSelection(snapshots, warnings);
+    return makeScope("latest-snapshots", snapshots, warnings);
+}
+/** 一个快照的可比性配置投影;pairsByFlag 与 experimentListData 复用同一字段集。 */
+export function comparabilityConfigOf(snapshot) {
+    const info = snapshot.experiment;
+    return {
+        agent: snapshot.agent,
+        ...(snapshot.model !== undefined ? { model: snapshot.model } : {}),
+        ...(info?.reasoningEffort !== undefined ? { reasoningEffort: info.reasoningEffort } : {}),
+        ...(info?.flags !== undefined ? { flags: info.flags } : {}),
+        ...(info?.budget !== undefined ? { budget: info.budget } : {}),
+        ...(info?.timeoutMs !== undefined ? { timeoutMs: info.timeoutMs } : {}),
+        ...(info?.sandbox !== undefined ? { sandbox: info.sandbox } : {}),
+    };
+}
+/** 可序列化值的深相等(对象键序无关;undefined 字段与缺席字段等价)。 */
+export function deepEqualJson(a, b) {
+    if (a === b)
+        return true;
+    if (Array.isArray(a) || Array.isArray(b)) {
+        if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length)
+            return false;
+        return a.every((item, i) => deepEqualJson(item, b[i]));
+    }
+    if (typeof a === "object" && typeof b === "object" && a !== null && b !== null) {
+        const keysA = Object.keys(a).filter((k) => a[k] !== undefined);
+        const keysB = Object.keys(b).filter((k) => b[k] !== undefined);
+        if (keysA.length !== keysB.length)
+            return false;
+        return keysA.every((k) => deepEqualJson(a[k], b[k]));
+    }
+    return false;
 }
 /**
- * 两个宿主(show / view)共用的现刻水位选择器:每个 experiment × eval 取时间上最新的那份
- * 判定,跨 run 合成。results.latest() 只挑「每实验最新快照」,带 eval 前缀的局部重跑会产出
- * 残缺快照;现刻水位承诺「不会因为一次局部重跑变残缺」,所以在实验的全部历史快照上逐 eval
- * 向更早的 run 补齐,再把合成好的 Selection 交给宿主注入报告槽——内置默认报告与 --report 吃
- * 同一份。
+ * 两个宿主(show / view)共用的现刻水位选择器:每个 experiment × eval 取「包含该 eval 的
+ * 最新快照」里的全部 attempt,跨 run 合成。results.latest() 只挑「每实验最新快照」,带 eval
+ * 前缀的局部重跑会产出残缺快照;现刻水位承诺「不会因为一次局部重跑变残缺」,所以在实验的
+ * 历史快照上逐 eval 向更早的 run 补齐,再把合成好的 Scope 交给宿主注入报告槽。
+ *
+ * **可比性前提**:每个 experiment 以最新快照的可比性配置(agent / model / reasoningEffort /
+ * flags / budget / timeoutMs / sandbox)为基准,只有配置与基准深相等的历史快照才参与补齐;
+ * 改过配置后只补跑部分 eval 时,旧配置快照覆盖的其余题不冒充新配置的水位,按 partial-coverage
+ * 如实告警。这保证 current() 产出的每个 experiment 只对应一套配置。
  *
  * 同一 eval 的全部 attempts 必须整批取自包含它的最新快照,不把历史快照的 attempts 平铺后
  * 按 eval 聚合——否则会把不同运行的重试混成一次虚构运行。合成快照的 dir/元数据只服务报告
  * 分组与来源展示,证据身份一律来自 attempt 自己的 ref。
- * 警告随 Selection 重算:partial-coverage 的分母 = 已知并集 ∩ 范围(范围收窄时分母同步收窄,
- * 不让范围外的缺口刷屏);stale / unfinished 与 results.latest() 同口径。
  */
 export function selectCurrentResults(results, scope = {}) {
     const match = scope.patterns && scope.patterns.length > 0 ? evalPrefixPredicate(scope.patterns) : () => true;
@@ -70,9 +106,13 @@ export function selectCurrentResults(results, scope = {}) {
     const snapshots = [];
     const warnings = [];
     for (const exp of experiments) {
+        // 可比性基准 = 该实验最新快照的可比性配置;不一致的旧快照整份跳过,不贡献 attempt。
+        const baseline = comparabilityConfigOf(exp.latest);
         // 逐题取最新:快照按最新在前,首个出现即最新判定
         const taken = new Map();
         for (const snapshot of exp.snapshots) {
+            if (!deepEqualJson(comparabilityConfigOf(snapshot), baseline))
+                continue;
             for (const ev of snapshot.evals) {
                 if (!match(ev.id) || taken.has(ev.id))
                     continue;
@@ -97,6 +137,8 @@ export function selectCurrentResults(results, scope = {}) {
             startedAt,
             agent: base.agent,
             ...(base.model !== undefined ? { model: base.model } : {}),
+            ...(base.experiment !== undefined ? { experiment: base.experiment } : {}),
+            ...(base.name !== undefined ? { name: base.name } : {}),
             producer: base.producer,
             schemaVersion: base.schemaVersion,
             evals,
@@ -105,8 +147,8 @@ export function selectCurrentResults(results, scope = {}) {
             ...(newest.completedAt !== undefined ? { completedAt: newest.completedAt } : {}),
             ...(base.knownEvalIds ? { knownEvalIds: [...base.knownEvalIds] } : {}),
         });
-        // 残缺检测:跨快照补齐后仍缺,只可能是历史上见过(或 knownEvalIds 声明过)
-        // 却从未在可读落盘里出现的题 —— 分母收窄到范围内,不让范围外的缺口刷屏。
+        // 残缺检测:跨快照补齐后仍缺,来自「历史上见过却从未在可比配置的可读落盘里出现」的题
+        // (含改配置后未补跑的题)—— 分母收窄到范围内,不让范围外的缺口刷屏。
         const total = exp.evalIds.filter(match).length;
         if (evals.length < total) {
             warnings.push({
@@ -115,6 +157,7 @@ export function selectCurrentResults(results, scope = {}) {
                 covered: evals.length,
                 total,
                 message: `verdicts cover ${evals.length} of ${total} evals seen in history; re-run \`niceeval exp ${exp.id}\` for a full snapshot`,
+                command: `niceeval exp ${exp.id}`,
             });
         }
     }
@@ -130,7 +173,8 @@ export function selectCurrentResults(results, scope = {}) {
                 experimentId: snapshot.experimentId,
                 startedAt: snapshot.startedAt,
                 latestStartedAt,
-                message: `verdicts for "${snapshot.experimentId}" were produced at ${snapshot.startedAt}, before the latest run in this selection (${latestStartedAt})`,
+                message: `verdicts for "${snapshot.experimentId}" were produced at ${snapshot.startedAt}, ${humanizeGap(snapshot.startedAt, latestStartedAt)} before the latest run in this scope; re-run \`niceeval exp ${snapshot.experimentId}\` to align, or ignore if evals, agent and model are unchanged between the runs`,
+                command: `niceeval exp ${snapshot.experimentId}`,
             });
         }
         if (snapshot.completedAt === undefined) {
@@ -139,19 +183,23 @@ export function selectCurrentResults(results, scope = {}) {
                 experimentId: snapshot.experimentId,
                 startedAt: snapshot.startedAt,
                 dir: snapshot.dir,
-                message: `snapshot "${snapshot.experimentId}" (${snapshot.startedAt}) is unfinished (the process was interrupted); completed attempts are read as-is, but the set may be incomplete`,
+                message: `snapshot "${snapshot.experimentId}" (${snapshot.startedAt}) is unfinished (the process was interrupted); completed attempts are read as-is, but the set may be incomplete — re-run \`niceeval exp ${snapshot.experimentId}\` for a complete snapshot`,
+                command: `niceeval exp ${snapshot.experimentId}`,
             });
         }
     }
-    return makeSelection(snapshots, warnings);
+    return makeScope("current-evals", snapshots, warnings);
 }
 /**
- * Selection 构造:filter 只删不换 —— 快照删减,warnings 修剪规则是
- * 「experimentId 不在幸存快照中的丢弃,非实验作用域的保留」(为将来非 per-experiment 的 kind 留位置)。
+ * Scope 构造:attempts 按口径物化(快照 attempts 的平铺);filter 只删不换 —— 快照删减,
+ * attempts 随之同步修剪,warnings 修剪规则是「experimentId 不在幸存快照中的丢弃,
+ * 非实验作用域的保留」(为将来非 per-experiment 的 kind 留位置)。
  */
-export function makeSelection(snapshots, warnings) {
+export function makeScope(mode, snapshots, warnings) {
     return {
+        mode,
         snapshots,
+        attempts: snapshots.flatMap((s) => s.attempts),
         warnings,
         filter(predicate) {
             const kept = snapshots.filter(predicate);
@@ -160,13 +208,13 @@ export function makeSelection(snapshots, warnings) {
                 const scope = w.experimentId;
                 return typeof scope !== "string" || survivors.has(scope);
             });
-            return makeSelection(kept, keptWarnings);
+            return makeScope(mode, kept, keptWarnings);
         },
     };
 }
 /**
  * 跨快照聚合前的身份键去重:(experimentId, evalId, attempt, startedAt)。
- * --resume 会把上一轮已通过的结果原样合入新快照,同一 attempt 因此存在于多份落盘;
+ * 携带合入会把上一轮已通过的结果原样合入新快照,同一 attempt 因此存在于多份落盘;
  * 重复时保留最新快照里的那份(内容相同,取新快照的副本让 ref 落在最新落盘上;
  * 位置取首次出现处,顺序稳定)。startedAt 缺失时宁可不去重也不误删,记入 warnings。
  */

package/dist/results/types.d.ts

@@ -157,46 +157,68 @@ export interface Results {
     experiments: Experiment[];
     skipped: SkippedDir[];
     /**
-     * 每个实验取最新一次快照,返回 Selection(快照与挑选警告绑在一起走)。
+     * 每个实验取最新一次快照,返回 Scope(快照与挑选警告绑在一起走)。
      * `experiments` 是 experiment id 前缀过滤(string | string[]),同 CLI 位置参数语义。
      */
     latest(opts?: {
         experiments?: string | string[];
-    }): Selection;
+    }): Scope;
+    /**
+     * 官方现刻水位:每个 experiment × eval 取「包含该 eval 的最新快照」里的全部 attempt,
+     * 跨历史拼出当前判定水位。可比性前提:每个 experiment 以最新快照的可比性配置
+     * (agent / model / reasoningEffort / flags / budget / timeoutMs / sandbox)为基准,
+     * 配置不一致的旧快照不贡献 attempt,缺口走 partial-coverage
+     * (见 docs/feature/results/library.md「官方现刻水位」)。
+     */
+    current(opts?: {
+        experiments?: string | string[];
+    }): Scope;
 }
 /**
- * Selection:选出的快照 + 挑选过程算出的警告。渲染与否在消费方,但缺口永远被算出来。
- * 下游(Reports 计算函数、copySnapshots)收 `Selection | Snapshot[]`;
- * 手工挑的裸数组没有挑选过程,自然没有 warnings 可带,也如实。
+ * Scope(范围):选出的快照 + 口径 + 已按口径物化的 attempt 全集 + 挑选警告。
+ * 渲染与否在消费方,但缺口永远被算出来。下游(Reports 计算函数、copySnapshots)收
+ * `Scope | readonly Snapshot[]`;手工挑的裸数组没有挑选过程,自然没有 warnings 可带,也如实。
  */
-export interface Selection {
+export interface Scope {
+    /** 这份 Scope 的口径,字面写在数据上。 */
+    mode: "latest-snapshots" | "current-evals";
     snapshots: Snapshot[];
-    warnings: SelectionWarning[];
     /**
-     * 只删不换:返回新 Selection,快照删减,warnings 按规则修剪 ——
-     * experimentId 不在幸存快照中的丢弃,非实验作用域的保留。
+     * 按口径物化的 attempt 全集:消费 attempts 就自动正确,不需要自己 flatten snapshots,
+     * 也就不可能算错口径。官方计算函数同样只消费它。
+     */
+    attempts: AttemptHandle[];
+    warnings: ScopeWarning[];
+    /**
+     * 只删不换:返回新 Scope,快照删减,attempts 与 warnings 随之同步修剪 ——
+     * experimentId 不在幸存快照中的警告丢弃,非实验作用域的警告保留。
      * 「换成上一个完整快照」这类替换式重挑不给方法,回 exp.snapshots 自己挑。
      */
-    filter(predicate: (snapshot: Snapshot) => boolean): Selection;
+    filter(predicate: (snapshot: Snapshot) => boolean): Scope;
 }
 /**
- * 挑选警告:每种带 kind、可判断的结构化字段和渲染好的英文 message;
- * kind 是契约的一部分,全集与触发条件见 docs/feature/results/library.md「警告 kind 全集」。
+ * 挑选警告:每种带 kind、可判断的结构化字段和渲染好的英文 message;能用一条命令直接推进的
+ * kind 同时带 `command`(已替换真实 id,复制即跑)。kind 是契约的一部分,全集与触发条件见
+ * docs/feature/results/library.md「警告 kind 全集」。
  */
-export type SelectionWarning = {
+export type ScopeWarning = {
     /** 选中快照的覆盖 < 该实验已知 eval 并集(本地历史 ∪ knownEvalIds)。 */
     kind: "partial-coverage";
     experimentId: string;
     covered: number;
     total: number;
     message: string;
+    /** 一条可复制即跑的推进命令:`niceeval exp <experimentId>`。 */
+    command: string;
 } | {
-    /** 该实验选中的快照早于 Selection 中最新的落盘;无阈值,如实触发,要阈值消费方按字段自比。 */
+    /** 该实验选中的快照早于 Scope 中最新的落盘;无阈值,如实触发,要阈值消费方按字段自比。 */
     kind: "stale-snapshot";
     experimentId: string;
     startedAt: string;
     latestStartedAt: string;
     message: string;
+    /** 一条可复制即跑的推进命令:`niceeval exp <experimentId>`。 */
+    command: string;
 } | {
     /** 选中快照缺 completedAt(进程中断,未收尾);已落盘 attempt 照常读出,警告提示集合可能不完整。 */
     kind: "unfinished-snapshot";
@@ -205,6 +227,8 @@ export type SelectionWarning = {
     /** 该快照目录的绝对路径。 */
     dir: string;
     message: string;
+    /** 一条可复制即跑的推进命令:`niceeval exp <experimentId>`。 */
+    command: string;
 };
 /** dedupeAttempts 的警告:身份键缺 startedAt,宁可不去重也不误删。 */
 export interface DedupeWarning {

package/dist/shared/aggregate.d.ts

@@ -16,8 +16,9 @@ export declare function displayExperimentName(id: string | undefined): string |
  */
 export declare function experimentGroupOf(experimentId: string): string | undefined;
 /**
- * eval id 前缀过滤,同 CLI 位置参数的分段语义(src/runner/discover.ts):
- * "algebra" 匹配自身与 "algebra/..." 子级,不误配 "algebra2";允许 "algebra/" 尾斜杠写法,等价。
+ * eval id 前缀过滤,同 CLI 位置参数语义(docs/feature/reports/show.md「打开与收窄」):
+ * eval 位置参数是收窄过滤,按**裸前缀宽松匹配**——"algebra" 命中 "algebra"、"algebra/..."
+ * 也命中 "algebra2",多命中正是它的用途(与 `--experiment` 的按路径段匹配有意不同)。
  */
 export declare function evalPrefixPredicate(evals?: string | string[]): (id: string) => boolean;
 /** 无 experimentId 时的兜底标签。 */

package/dist/shared/aggregate.js

@@ -36,14 +36,15 @@ export function experimentGroupOf(experimentId) {
     return experimentId.split("/").slice(0, -1).join("/");
 }
 /**
- * eval id 前缀过滤,同 CLI 位置参数的分段语义(src/runner/discover.ts):
- * "algebra" 匹配自身与 "algebra/..." 子级,不误配 "algebra2";允许 "algebra/" 尾斜杠写法,等价。
+ * eval id 前缀过滤,同 CLI 位置参数语义(docs/feature/reports/show.md「打开与收窄」):
+ * eval 位置参数是收窄过滤,按**裸前缀宽松匹配**——"algebra" 命中 "algebra"、"algebra/..."
+ * 也命中 "algebra2",多命中正是它的用途(与 `--experiment` 的按路径段匹配有意不同)。
  */
 export function evalPrefixPredicate(evals) {
     if (evals === undefined)
         return () => true;
-    const prefixes = (Array.isArray(evals) ? evals : [evals]).map((p) => p.replace(/\/+$/, ""));
-    return (id) => prefixes.some((prefix) => id === prefix || id.startsWith(prefix + "/"));
+    const prefixes = Array.isArray(evals) ? evals : [evals];
+    return (id) => prefixes.some((prefix) => id.startsWith(prefix));
 }
 /** 无 experimentId 时的兜底标签。 */
 export function fallbackExperimentLabel(result) {

package/docs-site/zh/README.md

@@ -0,0 +1,44 @@
+# 中文公开文档信息架构
+
+`zh/` 按读者此刻的需求组织，不按 NiceEval 的内部模块组织。判断一页放在哪里时，先问读者是在学习、完成任务、查事实、理解原理，还是修复问题。
+
+## 五个正文分区
+
+| 目录 | 页面类型 | 读者要什么 | 本站边界 |
+| --- | --- | --- | --- |
+| `tutorials/` | Tutorial | 跟着一条安全路径拿到第一次成功 | 当前只有 `quickstart.mdx`。不为凑齐目录增加第二条入门路径 |
+| `how-to/` | How-to | 完成一个现实任务 | 标题用任务表述；步骤、验证方式和失败后的下一步要清楚 |
+| `explanation/` | Explanation | 理解概念、边界和运行原理 | 不承担完整操作步骤或字段罗列 |
+| `reference/` | Technical Reference | 快速查准确、完整的事实 | API 签名、字段、类型和 CLI flags 以源码为权威来源 |
+| `troubleshooting/` | Troubleshooting | 从可见症状定位并修复问题 | 按症状组织，不按内部模块组织 |
+
+`index.mdx` 和 `introduction.mdx` 是站点入口，不硬归入正文类型。`examples/` 是独立资源入口，不属于 Diátaxis 的四种正文类型。
+
+## Examples 的收录标准
+
+`examples/` 只收录有真实可运行源码的项目。一个案例页只回答四件事：被测对象是什么、这个项目证明什么、源码在哪里、怎么运行。操作步骤的通用版本链接 How-to，字段和配置全集链接 Reference，不在案例页复制。
+
+- 接入前后能从仓库源码计算时，由生成器产出 diff 页面，不手抄代码。
+- 同一个可运行项目只保留一张案例页。Skill、Plugin 等相邻主题共享实验设计时合并，不复制两份近似正文。
+- 只有一个条目的 Showcase 不单独成页，真实项目直接列在 `examples/index.mdx`。
+- 没有可运行源码、只有片段或设想的内容不进 Examples。片段进入对应 How-to，未实现方向留在 Roadmap。
+
+## Reference 的生成边界
+
+Technical Reference 不等于整页都由生成器拼出来。页面仍可手写短导语、最小示例和去往 How-to 的链接，但代码形状不能手抄：
+
+- `{/* GENERATED:BEGIN ... */}` 与 `{/* GENERATED:END ... */}` 之间的 API 成员、字段和 CLI flags 由 `pnpm docs:reference` 从源码紧邻注释生成。
+- 新增需要穷举的接口字段、函数、联合类型或 CLI flag 时，扩展 `scripts/generate-reference.ts` 的 region 映射，不在 MDX 里另写一份字段全集。
+- 能力矩阵、选择表和行为约束暂时由手写 Reference 承担；它们必须只描述当前实现，并避免重复已经生成的类型签名。
+- `reference/` 中没有生成区块的页面不因此成为 API 事实的第二来源。出现代码形状时，优先链接已有生成页；确实缺少生成入口时先补生成器。
+
+运行 `pnpm docs:reference` 后，生成器只改 `zh/reference/` 中已登记的 region。`test/reference-consistency.test.ts` 会拦截源码与生成区块的漂移。
+
+## 当前页面归类
+
+- `explanation/runner.mdx` 解释执行引擎如何发现、调度、缓存和产出结果，不是一步一任务的操作指南。
+- `reference/official-adapters.mdx`、`reference/report-components.mdx` 和 `reference/results-data.mdx` 用于查能力、组件或数据 API，不能留在 How-to。
+- `troubleshooting/debugging.mdx` 与 `troubleshooting/debug-sandbox.mdx` 从失败症状出发，目录独立，在导航中归入 How-to Guides。
+- `how-to/sandbox-providers.mdx` 目前保留在 How-to，因为主问题是选择并配置 Provider；若以后字段表继续增长，再拆出独立 Provider Reference。
+
+新增或移动页面时，同时更新 `docs-site/docs.json` 和旧路径 redirect。校验命令以 [`../AGENTS.md`](../AGENTS.md) 为准。