niceeval 0.12.2-canary.31 → 0.13.0

package/docs-site/zh/reference/report-components.mdx

@@ -1,121 +1,125 @@
 ---
 title: "报告 API"
-description: "RecordProjection、Calculation、Page、ReportExecution 与静态导出的公开边界。"
+description: "用标准 React JSX、Page 与关闭的 Analysis 值编写终端、网页和静态报告。"
 ---
 
-Report 作者只从 `niceeval/report` 声明需要哪些 `RecordProjection`，再把投影结果和计算结果包装成页面或下载。作者不接收 reader、路径、raw Attachment 或磁盘字段。
+Report 作者只组织已经关闭的 Analysis 值。作者文件使用标准 React JSX；它不读取 Record 路径、不会取得 reader，也不需要 NiceEval 专属 JSX runtime 或 `jsxImportSource`。
 
 ```text
-AnalysisSample
-        ↓  opaque RecordProjection declarations
-ProjectedSample
-        ↓  Calculation / Page / PageFamily / Download
-immutable ReportExecution
-        ├─ show
-        ├─ view revision
-        └─ static export
+已发布的 Record
+        ↓ 选择
+Sample → Analysis 的 ClosedRows / MetricValue / DomainView
+        ↓
+Report：Page + component
+        ├─ show：一个选中的 Page → terminal text 或 JSON
+        └─ view / view --out：全部 Page → 完整静态站
 ```
 
-## 声明 RecordProjection
+## 定义一个 Report
+
+把 Report 写成 `.tsx` 模块，并在项目的 TypeScript 配置中启用 `"jsx": "react-jsx"`。组合组件通过 `ctx.scope` 取得这次命令固定的 `Sample`，再把 `aggregate()` 返回的 `ClosedRows` 交给标准组件。
+
+```tsx
+import {
+  aggregate,
+  Bars,
+  defineComponent,
+  defineReport,
+  Grid,
+  model,
+  passRate,
+  Section,
+  Table,
+} from "niceeval/report";
+
+const Overview = defineComponent(async (_props: {}, ctx) => {
+  const rows = await aggregate(ctx.scope, {
+    by: { model },
+    values: { passRate },
+  });
+
+  return (
+    <Section title={ctx.report.title}>
+      <Grid>
+        <Bars points={rows} x="model" y="passRate" />
+        <Table rows={rows} />
+      </Grid>
+    </Section>
+  );
+});
 
-NiceEval 提供的 opaque projector 固定形成一种 typed view。Report 用三个 constructor 声明逻辑访问；作者不能定义 raw family/projector：
+export default defineReport({
+  title: { en: "Quality", "zh-CN": "质量" },
+  pages: [{
+    id: "overview",
+    path: "/",
+    title: { en: "Overview", "zh-CN": "概览" },
+    render: () => <Overview />,
+  }],
+});
+```
 
-| constructor | 对齐方式 |
-| --- | --- |
-| `attemptSlotProjection(projector)` | 对 Sample 的每个 slot 形成 entry，并读取它精确引用的 Attempt Attachment。 |
-| `attemptOriginRunProjection(projector)` | 对每个 slot 形成 entry，并读取该 Attempt 的 origin Run Attachment。 |
-| `selectedRunProjection(projector)` | 对每个 selected Run 形成 entry，并读取该 Run Attachment。 |
+`ctx.scope` 是组件取得 Sample 的唯一字段。`ctx.report` 提供 Report 标题、导航 Page 摘要和只读的 `pricing`；后者是已验证的
+`PricingProfile` 或 `null`，与 `ReportDefinition.pricing` 是同一个值，不提供 Config、Runner price table 或第二份价格输入。`ctx.report`
+不提供当前目录、Record、主题或其它 Page 的数据读取能力。
 
-前两种访问不会丢掉 `excluded`、`not-recorded` 或 `core-invalid` slot。相同 Attempt 被多个 slot 引用时，公开结果仍按 slot 对齐。
+成本 Measure 必须显式调用 `costUSD(profile)` 或 `totalCostUSD(profile)`，其中 `profile` 就是该 Report 的已验证 `pricing`；没有零参数
+或别名入口。Analysis 拥有 slot-provider ledger、exact total 与 `numerator / denominator` mean，Host 只闭合并呈现这些结果。
 
-```ts
-const verdicts = attemptSlotProjection(verdictProjector);
-const evaluations = selectedRunProjection(evaluationsProjector);
+`MetricValue` 来自 Analysis，并完整保留 `value`、`state`、`samples`、`total`、`issues` 和 `refs`。`value: 0` 是有效读数。不要从可见行数重算分母，也不要把 `null` 写成零。
 
-const inputs = reportInputs({ verdicts, evaluations });
-```
+## 两种组件形态
 
-`reportInputs` 固定输入 key 与其 projection 的类型。host 在执行任何 Record I/O 前闭合这组依赖，并让每个 projection 至多执行一次。
+上例是组合组件。它可以在 Page 执行期间异步读取固定 Sample 上的关闭值。
 
-## 定义 Calculation 和页面
+显示原语使用另一种 `defineComponent()` 形态。可选的 `resolve()` 只运行一次；同步的 `text()` 与 `web()` 读取同一个关闭结果。
 
-Calculation 只从静态声明的 projection 派生业务值。它自己返回业务 `observed` 与 `denominator`；host 不会从 coverage 或 entry 数量猜测统计口径。
+```tsx
+import {
+  defineComponent,
+  formatMetricValue,
+  Stat,
+  type MetricValue,
+} from "niceeval/report";
 
-```ts
-const passRate = defineCalculation({
-  id: Either.getOrThrow(reportComponentId("pass-rate")),
-  inputs,
-  completeness: "allow-partial",
-  calculate: ({ sample, inputs }) =>
-    calculatePassRate(sample, inputs.verdicts, inputs.evaluations),
+const MetricCard = defineComponent<
+  { readonly label: string; readonly value: MetricValue },
+  { readonly label: string; readonly value: MetricValue }
+>({
+  resolve: props => props,
+  text: data => `${data.label}: ${formatMetricValue(data.value)}`,
+  web: data => <Stat label={data.label} value={formatMetricValue(data.value)} />,
 });
 ```
 
-直接消费 projection 的 Calculation、Page、PageFamily 和 Download 必须选择完整度：
-
-| 选择 | 行为 |
-| --- | --- |
-| `allow-partial` | callback 收到完整的 `ProjectedSample`、coverage 与 issues，可以显示部分结果。 |
-| `require-complete` | 必需数据不完整时不调用 callback，result 是 `data-unavailable`。 |
-
-`unavailable`、`migration-required`、`migration-unavailable`、`unsupported`、`invalid` 与 partial collection 都是 recorded-data problem。callback 的意外 throw 属于 execution problem，两者不能互相替代。
-
-Page 返回闭合的 `ReportDocument` 语义树。它不是 HTML、React element 或另一套文本输出。PageFamily 只能根据已投影或已计算的内存值展开 route，不能在展开时追加 Attachment I/O。
-
-## 组合一个 Report
-
-```ts
-const overview = definePage({
-  id: Either.getOrThrow(reportComponentId("overview")),
-  route: Either.getOrThrow(reportRoute("/")),
-  calculations: { passRate },
-  render: ({ calculations }) =>
-    reportDocument({
-      title: "Summary",
-      children: [
-        reportMetric({
-          label: "Pass rate",
-          value:
-            calculations.passRate.state === "available"
-              ? calculations.passRate.value.rate
-              : null,
-        }),
-      ],
-    }),
-});
+`text()` 返回文字，`web()` 返回 React JSX。两面不能再次读取 Sample、发起网络请求或各自计算统计。不要从 HTML、文字或 React element 反推机器数据。
 
-export default defineReport({
-  id: Either.getOrThrow(reportId("summary")),
-  calculations: { passRate },
-  pages: [overview],
-});
-```
+## Page、参数和页面选择
 
-`defineReport` 验证 ID 与组件引用。Page、PageFamily 和 Download 只能引用同一个 Report 已注册的 Calculation。页面 route 与下载路径必须通过对应 constructor 创建，避免输出冲突。
+普通 Page 的 `render` 可以直接接收固定 Sample，或先用 `load(sample, params, context)` 关闭输入。参数 Page 还要声明 `navigation: false` 与 `params`：
 
-## 由 show / view 执行 Report
+- `encode(params)` 产生 canonical key；
+- `decode(key)` 必须能把同一种 key 还原；
+- `enumerate(sample)` 只为完整站点列出实例；
+- `context.evidence(locator)` 只返回当前 Sample 内的关闭证据视图。
 
-应用代码不调用 Report host。`niceeval show`、`niceeval view` 与 `view --out` 的内部 host
-选择 Run、执行 projection 与作者 graph，并形成不可变、自包含的 `ReportExecution`。
-包不导出 `niceeval/report/host`、`niceeval/report/host/node` 或 `executeReport()`。
+`pages` 是 Report 唯一的页面集合，详情必须作为 Page 或参数 Page 显式声明；Host 不补建任何 route。`niceeval show --page <route>` 只 decode、load 和 render 这个目标 Page。它不会调用 `enumerate()` 或执行其它 Page。`niceeval view` 与 `niceeval view --out` 才会枚举全部普通 Page 和参数实例，并在所有路径、链接、资源和预算通过校验后形成完整站点。
 
-`ReportExecution` 包含 Sample、projection 摘要、Calculation、family、页面、下载项与 problem table，但不包含 reader、路径、Scope、callback 或 projector token。
+## JSON、网页和静态站
 
-每个 projection、Calculation、PageFamily、页面实例与 Download 在同一 execution 中最多执行一次。`show`、`view` 与 `exportStaticReport` 只消费完成后的 execution。
+`show --json` 固定输出英语 JSON。内建 Report 输出 Host 拥有的具名领域文档；自定义 Report 输出一个 Page 的 route、标题、80-column rendered text、下载摘要和问题表。两种 v1 JSON 都在顶层以相同的 `projections` 对象携带该目标 Page 的闭合成本数据；它们不包含作者树、HTML、全站路由或站点 identity。
 
-| 情况 | `show` / `view` | 静态导出 |
-| --- | --- | --- |
-| recorded-data problem | 显示问题，并保留其它成功内容。 | 可以导出，问题必须可见。 |
-| execution problem | 保留其它成功页面，并显示问题。 | 不导出。 |
+view 与静态导出使用同一份完整站点版本。同一路由的 HTTP body 与导出目录页面 body 逐字节相同。两者都携带同一个 reload client；静态目录找不到 view 的端点时，它会安静停用。禁用 JavaScript 或断开网络后，正文、导航、详情、完整度、问题和下载仍可读。
 
-## view 与静态导出
+## 样式和资源边界
 
-`view` 每次 rebuild 构造新的固定 `ReportExecution`。完整成功后才替换当前 revision；失败保留 last-good execution，并显示 bounded rebuild problem。
+Report CSS 是唯一的产品样式 owner。它负责 reset、基础排版、theme token 与组件样式。View shell 只负责浏览器语言切换、reload 状态和 Host 提示，不重绘 Report 内容。
 
-静态导出只写一份已经完成的 execution。它先验证 semantic tree、route、下载项与 execution problems，再写出页面、host-data、downloads、manifest 和内建 runtime。所有内容写完后，最后写入 `complete` marker。
+Report 可以在 `head` 中声明结构化 `meta`、`link`、`style` 和 `script`，也可以选择 theme。脚本只能做渐进增强，不能成为正文、导航、Evidence 或机器文档的唯一入口。自定义样式不能建立第二份 reset、theme 或 View shell。
 
 ## 相关页面
 
-- [结果数据 API](/zh/reference/results-data)：在 Report callback 中消费 Sample 与 `ProjectedSample`。
-- [编写自定义报告](/zh/tutorials/custom-reports)：从投影写出一个实际 Report。
-- [发布静态报告](/zh/tutorials/publish-report)：导出并分享固定 execution。
+- [结果数据 API](/zh/reference/results-data)：选择 Analysis 输入并读取关闭数据。
+- [编写自定义报告](/zh/tutorials/custom-reports)：从统计口径到一个可运行的 Report。
+- [查看结果](/zh/tutorials/viewing-results)：选择范围、单目标 `show` 与全站 `view`。
+- [发布静态报告](/zh/tutorials/publish-report)：导出离线可读的完整站点。

package/docs-site/zh/reference/results-data.mdx

@@ -1,75 +1,65 @@
 ---
 title: "在 Report 中读取结果数据"
 sidebarTitle: "结果数据 API"
-description: "通过 niceeval/report 的 AnalysisSample 与官方 opaque projector 声明读取结果。"
+description: "在 Page 或组合组件中用固定 Sample、aggregate() 和具名领域投影读取关闭的 Analysis 结果。"
 ---
 
-Record 是 `.niceeval/record/` 下可携带、可进入 Git 的 opaque 目录。应用代码不读取内部结构或写入
-其中的文件，也不 import Record reader / writer。选择运行和执行 projection 由 `niceeval show`
-与 `niceeval view` 的内部 host 完成。
+结果查看从已发布 Run 开始。NiceEval 先形成 `Sample`，再只在 Page 或组合组件执行期间通过 `ctx.scope` 提供它。应用代码不能构造 Sample、打开结果目录或持有 reader。
 
-要在终端或浏览器中查看结果，请阅读[查看结果](/zh/tutorials/viewing-results)。要定义页面和
-计算，请阅读[报告 API](/zh/reference/report-components)。
+## Sample 保留已选范围
 
-## Report callback 收到 AnalysisSample
+Sample 固定本次选择的 Run、logical Slot 与分母。每个位置保留 `included`、`not-recorded`、`core-invalid` 或 `excluded` 状态。
 
-Report 的 Calculation、Page 与 PageFamily callback 收到一份纯 `AnalysisSample`。它保存
-selection 已建立的每个 expected slot 和完整分母，不包含路径、reader、文件句柄或延迟 I/O。
-`--run` 使用具名 Run 的完整 expected slots；`project-current` 只把身份仍匹配当前目标的 slots 纳入 Sample：
+`--run` 保留指定 Run 的完整计划范围。`project-current` 只保留仍与当前项目身份匹配的范围。两种选择都不会因为某个度量缺少输入而缩小分母。
 
-| 状态 | 含义 |
-| --- | --- |
-| `included` | 有合法 Member，指向精确 Attempt。 |
-| `not-recorded` | expected slot 没有 Member。 |
-| `core-invalid` | Member、Attempt 或核心引用不能可靠读取。 |
-| `excluded` | host 在已有 Sample 上明确排除了该项。 |
-
-作者可以从 `niceeval/report` 导入必要的 Sample / identity 类型，也可以对已有 Sample 使用纯
-`narrowAnalysisSample`。这些值不能恢复 Record I/O。
+Sample 只能在 `load()`、Page 或组合组件执行期间传给 Report facade。回调结束后，页面只保留已经关闭的值，不能再次读取结果。
 
-## 用官方 projector 声明数据
+## 用 `aggregate()` 取得 rows
 
-Report 作者选择 NiceEval 提供的 opaque projector，再声明它怎样与 Sample 对齐：
+`niceeval/report` 重新导出 Report 所需的 Analysis facade。`aggregate()` 返回带稳定 identity、issues、refs 和完整 `MetricValue` 的 `ClosedRows`。
 
-```ts
+```tsx
 import {
-  attemptSlotProjection,
-  selectedRunProjection,
-  evaluationsProjector,
-  verdictProjector,
+  aggregate,
+  defineComponent,
+  Table,
 } from "niceeval/report";
+import { experiment, passRate } from "./quality-measures.ts";
 
-const verdicts = attemptSlotProjection(verdictProjector);
-const evaluations = selectedRunProjection(evaluationsProjector);
+const ResultTable = defineComponent(async (_props: {}, ctx) => {
+  const rows = await aggregate(ctx.scope, {
+    by: { experiment },
+    values: { passRate },
+  });
+
+  return <Table rows={rows} />;
+});
 ```
 
-`attemptSlotProjection` 对每个 slot 形成 entry。`attemptOriginRunProjection` 仍对每个 slot
-形成 entry，但使用 Attempt 的 origin Run。`selectedRunProjection` 对每个 selected Run
-形成 entry。
+`Table` 使用 rows，图表使用 points，`Stat` 使用格式化后的完整度量。显示层可以排序、限制或过滤行，但不能用显示后的数组重算数值或减少 `MetricValue.total`。
+
+## 取得关闭领域数据
 
-作者不能定义 raw Attachment family/projector，不能接收 payload 或 blob capability，也不能
-直接调用 projection runtime。需要新的持久事实时，由 NiceEval 提供新的高层 projector 或
-未来独立设计的 Eval / Experiment / Plugin 能力。
+Attempt Evidence、Observability、File Changes、Sources 和 Sandbox history 都有具名 Report facade。
+它们分别使用 `toAttemptEvidence()`、`toAttemptObservability()`、`toFileChanges()`、`toSources()` 和 `toSandboxHistory()`。
+这些 facade 只接收固定 Sample 和可选的 Attempt locator，并返回关闭 DomainView。
 
-## Projection 结果保持穷尽
+参数 Page 使用 `context.evidence(locator)` 取得目标详情的关闭 Evidence。Host 验证 locator 属于当前 Sample；它不会把路径、原始 Record payload 或任意查询能力交给页面。
 
-前两种 slot projection 保留 `excluded`、`not-recorded`、`core-invalid` 与
-`attachment-result`。Attachment result 再表达：
+## 读懂 `MetricValue`
 
-| 状态 | 含义 |
+| 字段 | 含义 |
 | --- | --- |
-| `available` | 官方 projector 已形成 typed value。 |
-| `unavailable` | owner 没有请求的事实。 |
-| `migration-required` | 需要运行 `niceeval migrate`。 |
-| `migration-unavailable` | 历史事实不能无损形成当前值。 |
-| `unsupported` | 当前 NiceEval 不认识该事实版本。 |
-| `invalid` | 已记录的数据无法可靠解释。 |
+| `value` | 当前数值；`0` 是有效值。 |
+| `samples` | 实际贡献成员数。 |
+| `total` | Measure 预先确定的分母。 |
+| `state` 与 `issues` | 缺口、不可用或失败的原因。 |
+| `refs` | 可复核的 Evidence 定位。 |
 
-这些是 Report 可显示的数据状态，不会改变 Sample 的 Core 状态。I/O、权限、reader Scope 与
-raw schema errors 留在内部 host；公开作者面只收到自包含值和结构化 Report problem。
+`available`、`partial`、`empty`、`unsupported` 和 `failed` 都是不同状态。不要把 `null` 当成零，也不要用只剩下的可见行数替换总分母。
 
 ## 相关页面
 
-- [Record](/zh/explanation/record)：理解为什么 Record 是 opaque 产品资产。
-- [查看结果](/zh/tutorials/viewing-results)：用 `show` 与 `view` 选择结果。
-- [报告 API](/zh/reference/report-components)：消费 `ProjectedSample` 并生成 Report。
+- [报告 API](/zh/reference/report-components)：Page、组件、JSON 和全站构建边界。
+- [编写自定义报告](/zh/tutorials/custom-reports)：从 Measure 到 Report 的完整路径。
+- [查看结果](/zh/tutorials/viewing-results)：通过 CLI 选择 Sample。

package/docs-site/zh/troubleshooting/debug-sandbox.mdx

@@ -30,7 +30,7 @@ Kept sandboxes (1)
 Stop them with: niceeval sandbox stop --all
 ```
 
-每行给三样东西：Attempt identity、Sandbox 实例 id、进入现场的命令。落盘证据从 `niceeval show --run <runId> --page attempt-<attemptId>` 查看。保留下来的 Sandbox 不会一直跑着烧资源——Docker 容器停在磁盘上，E2B 微 VM 暂停计费，Vercel 保存文件系统。
+每行给三样东西：Attempt identity、Sandbox 实例 id、进入现场的命令。落盘证据从 `niceeval show @<attempt-locator>` 查看。保留下来的 Sandbox 不会一直跑着烧资源——Docker 容器停在磁盘上，E2B 微 VM 暂停计费，Vercel 保存文件系统。
 
 `niceeval sandbox enter` 会先唤醒再进入，在 workdir 打开 shell。退出 shell 后现场自动回到休眠；想让它保持运行，加 `--leave-running`。进去之后就是这次 Attempt 跑完时的环境，可以手动执行命令、翻文件、复现失败。
 

package/docs-site/zh/troubleshooting/debugging.mdx

@@ -1,38 +1,38 @@
 ---
-title: "排查 Record 与报告问题"
+title: "排查结果与报告问题"
 sidebarTitle: "排查手册"
-description: "根据可见错误、Sample 状态、Attachment 状态和 rebuild 反馈，定位查看、重跑与导出问题。"
+description: "根据可见错误、Sample 状态和 rebuild 反馈，定位查看、重跑与导出问题。"
 ---
 
 先用明确 Run 读取问题，不要从目录名或时间猜测目标。
 
 ```sh
-npx niceeval show --run 01J9ZK3M6P4T7V9X2C5N8QW0RY
-npx niceeval show --run 01J9ZK3M6P4T7V9X2C5N8QW0RY --page /
+npx niceeval show --run <run-id>
+npx niceeval view --run <run-id> --no-open
 ```
 
-Record reader 只看已经带 `complete` 的 Run。它冻结本次可见的集合；正在写入的目录不会混进 Sample。
+这两条命令从同一范围形成 Sample，并执行同一份 Report。先确定选择是否正确，再检查页面中的度量和问题。
 
-## 找不到或无法打开 Record
+## 找不到或无法打开结果
 
 | 可见错误 | 含义 | 下一步 |
 | --- | --- | --- |
-| `record-root-missing` | 指定的 Record 根目录不存在。 | 检查项目目录或 `--record` 参数。 |
-| `record-migration-required` | Core 是已知旧 major。 | 运行 `niceeval migrate`。 |
-| `record-format-unsupported` | 当前 NiceEval 不认识该 Core major。 | 安装支持该格式的 NiceEval。 |
-| `core-invalid` | 已完成 Run 的 Core 或引用不能可靠读取。 | 查看具名 issue；不要把它当成缺失结果。 |
+| `record-root-missing` | 指定的结果集不存在。 | 检查项目目录或 `--record` 参数。 |
+| `record-migration-required` | 已发布结果需要迁移。 | 运行 `niceeval migrate`。 |
+| `record-format-unsupported` | 当前 NiceEval 不认识该结果格式。 | 安装支持该格式的 NiceEval。 |
+| `core-invalid` | 某个位置的身份或引用不能可靠读取。 | 阅读具名问题；不要把它当成缺失结果。 |
 
-不要用空值替代这些结果。已发布的 Record 不提供手工编辑修复路径；需要不同事实时创建新的 Run。格式迁移使用 `niceeval migrate`，未完成目录使用 `niceeval clean`。
+已发布结果不提供手工编辑修复路径。需要不同事实时创建新的 Run；需要清理未完成残留时运行 `niceeval clean`。
 
 ## Sample 中缺少预期结果
 
-Sample 会保留 Run 的 expected-slot 分母。查看页面上每个 slot 的状态：
+Sample 会保留 Run 的预期分母。查看页面上每个位置的状态：
 
 | 状态 | 含义 | 下一步 |
 | --- | --- | --- |
-| `included` | Member 和 Attempt 可读。 | 检查需要的 Attachment。 |
-| `not-recorded` | expected slot 没有 Member。 | 检查 Invocation 是否完成，或重新运行该范围。 |
-| `core-invalid` | Member、Attempt 或引用有问题。 | 处理具名 issue，不要把它当成未采集。 |
+| `included` | 有可分析的 Attempt。 | 检查报告显示的度量或证据。 |
+| `not-recorded` | 计划中的位置没有结果。 | 检查 Invocation 是否完成，或重新运行该范围。 |
+| `core-invalid` | 该位置的身份或引用有问题。 | 处理具名问题，不要把它当成未采集。 |
 | `excluded` | 本次选择排除了该项。 | 检查 `--experiment`、`--eval` 或其他选择条件。 |
 
 需要判断下一次运行会做什么时，先执行：
@@ -41,27 +41,26 @@ Sample 会保留 Run 的 expected-slot 分母。查看页面上每个 slot 的
 npx niceeval exp checkout --dry
 ```
 
-输出会显示每个 slot 会执行还是沿用已有 Attempt，并列出沿用条件不满足的原因。
+输出会显示每个位置会执行还是沿用已有 Attempt，并列出沿用条件不满足的原因。
 
-## Attachment 显示不可用
+## 度量或详情显示不完整
 
-一个 RecordAttachment 的状态只影响请求它的 Page、PageFamily、Calculation 或 Download：
+Measure 和领域视图会把自己的状态与问题带进页面：
 
 | 状态 | 含义 | 下一步 |
 | --- | --- | --- |
-| `unavailable` | owner 没有这个 Attachment。 | 确认它是否适用于这次运行。 |
-| `migration-required` | 有完整相邻 converter 链。 | 运行 `niceeval migrate`。 |
-| `migration-unavailable` | 不能从历史事实无损形成当前值。 | 使用能读取历史值的功能，或发布新的 Run。 |
-| `unsupported` | 当前功能不认识该 schema。 | 安装 owning plugin，或查看不依赖它的页面。 |
-| `invalid` | envelope、payload 或 blob 无效。 | 阅读具名 issue；其它 Attachment 仍可读取。 |
+| `partial` | 有可显示结果，但部分分母成员没有贡献。 | 检查问题和分母，不要把它当成完整结果。 |
+| `empty` | 输入完整，领域结果合法为空。 | 确认这个空结果是否符合任务。 |
+| `unsupported` | 当前环境不支持所需输入。 | 使用支持该能力的环境，或查看不依赖它的页面。 |
+| `failed` | 读取、关联或归并失败。 | 阅读具名问题并修复原因。 |
 
-未请求的坏 Attachment 不会阻止无关页面。`require-complete` consumer 显示 data-unavailable；`allow-partial` consumer 可显示完整分母与问题。
+需要迁移的历史结果先运行 `niceeval migrate`。度量问题不会改变 Sample 的既定分母，也不会阻止无关页面显示。
 
 ## view 没有显示新的结果
 
-`view` 每次成功 rebuild 才发布一份新的 `ReportExecution`。如果 Report、配置、主题或 Record 的变化导致 rebuild 失败，页面继续显示 last-good execution，并显示本次问题。
+`view` 每次成功 rebuild 才发布一份新的完整站点。如果 Report、配置、主题或结果变化导致 rebuild 失败，页面继续显示上一份可用站点，并显示本次问题。
 
-先修复 rebuild problem，再等待下一次成功 rebuild。页面刷新本身不会绕过这个边界，也不会让旧 execution 重新读取 Record。
+先修复 rebuild problem，再等待下一次成功 rebuild。页面刷新本身不会绕过这个边界，也不会让旧站点重新读取结果。
 
 ## JSON 中没有 receipt
 
@@ -71,8 +70,8 @@ npx niceeval exp checkout --dry
 
 ## 静态报告站无法导出
 
-`view --out` 只导出一个已经完成的 `ReportExecution`。recorded-data problem 可以进入导出站并保持可见；projector 或作者 callback defect、非法 semantic tree 和 route conflict 会让导出停止。
+`view --out` 只导出已经完成的完整站点。Analysis 问题可以进入导出站并保持可见；作者 callback 抛错、参数实例不合法、路由冲突或资源冲突会让导出停止。
 
-目标目录必须不存在。写入在最后留下 `complete` marker；失败或中断可能留下没有 marker 的目录。删除那个未完成目录后重试。
+目标目录必须不存在。失败或中断后请使用新的输出目录，再重新导出。
 
 更多操作步骤见[查看结果](/zh/tutorials/viewing-results)和[发布静态报告](/zh/tutorials/publish-report)。

package/docs-site/zh/tutorials/agent-feedback-loop.mdx

@@ -53,7 +53,7 @@ npx niceeval show --run 01J9ZK3M6P4T7V9X2C5N8QW0RY
 npx niceeval view --run 01J9ZK3M6P4T7V9X2C5N8QW0RY --no-open
 ```
 
-`show` 与 `view` 选择 Sample，投影需要的 `RecordAttachment`，并形成固定的 `ReportExecution`。Agent 应区分以下状态：
+`show` 与 `view` 选择 Sample，再取得当前目标需要的闭合分析值。`show` 只执行一个 Page；`view` 构建完整站点。Agent 应区分以下状态：
 
 | 看到的状态 | 下一步 |
 | --- | --- |
@@ -61,9 +61,9 @@ npx niceeval view --run 01J9ZK3M6P4T7V9X2C5N8QW0RY --no-open
 | `errored` | 检查诊断、Adapter、Sandbox 或凭据。 |
 | `not-recorded` | 检查该 expected slot 为什么没有 Member。 |
 | `core-invalid` | 阅读具名 Core issue，不要把它当成未采集。 |
-| `unavailable` | 确认 owner 是否应当有这个 Attachment。 |
+| `partial` | 阅读分母和问题，确认哪些成员没有贡献。 |
 | `migration-required` | 运行 `niceeval migrate`。 |
-| `unsupported` 或 `invalid` | 只处理依赖该 Attachment 的查看内容，并阅读具名 issue。 |
+| `unsupported` 或 `failed` | 只处理依赖该分析输入的查看内容，并阅读具名问题。 |
 
 ## 修改后再次运行
 
@@ -73,7 +73,7 @@ npx niceeval view --run 01J9ZK3M6P4T7V9X2C5N8QW0RY --no-open
 npx niceeval exp checkout --rerun all --json
 ```
 
-自动采用已有 Attempt 时，`--dry` 会说明原因。carry 与 accept 的理由位于目标 Run 的 `niceeval.membership-provenance/v1` RecordAttachment；详情见[重跑与沿用](/zh/tutorials/rerun-and-cache)。
+自动采用已有 Attempt 时，`--dry` 会说明原因。carry 与 accept 的理由随目标 Run 保存，并可在结果中查看；详情见[重跑与沿用](/zh/tutorials/rerun-and-cache)。
 
 ## Record 的边界
 

package/docs-site/zh/tutorials/agent-onboarding.mdx

@@ -59,7 +59,7 @@ export default defineConfig({
 三个要提醒用户的点：
 
 - **配错不会假装通过。** 模型或 key 解析不到、网关拒绝鉴权、评估请求超时时，Judge Assertion 记为 `unavailable` 并带上原因；读取面不会把缺失 measurement 伪装成 mismatch 或零分。
-- **配完先验一次。** 写一条带 `judge: true` 的轻量 Pass Eval，调用 `turn.judge.autoevals.closedQA(...).atLeast(0.8)`。跑完 `niceeval show <评估用例 id>`，确认能看到 measurement、threshold、condition 与 Assertion 证据。
+- **配完先验一次。** 写一条带 `judge: true` 的轻量 Pass Eval，调用 `turn.judge.autoevals.closedQA(...).gate(0.8)`。跑完 `niceeval show <评估用例 id>`，确认能看到 measurement、threshold、condition 与 Assertion 证据。
 - **没有用户在场（自治接入）时不要直接跳过 Judge**：先看环境里是否已有可用 key，例如 `OPENAI_API_KEY` 或 `DEEPSEEK_API_KEY`。有就用 `apiKeyEnv` 指向它并验证；没有时先写精确 Match，并在收尾说明 Judge 没有配置。
 - Judge 模型要**与被测 Agent 分离**，避免同一个模型给自己的输出打分。配置按 Eval、Experiment、项目配置逐字段解析；三种 recipe 见 [Judge](/zh/explanation/judge)。
 
@@ -88,7 +88,7 @@ export default defineConfig({
 <包管理器> exec niceeval view                 # 查看器里看对比结果
 ```
 
-按 [Coding Agent 反馈闭环](/zh/tutorials/agent-feedback-loop)用 `niceeval show` 加 `--source`、`--execution`、`--timing`、`--diff` 完成运行、观察、修改和重跑。查看器用法见[查看结果](/zh/tutorials/viewing-results)。没跑通分三类定位：`fetch` 直接抛错 → 应用没起来或 URL 不对。`t.succeeded()` 不过 → 应用回了非成功状态。只有内容断言不过 → 接入已经通了，调断言或调应用。
+按 [Coding Agent 反馈闭环](/zh/tutorials/agent-feedback-loop)用 `niceeval show` 和明确的 `--page <route>` 完成运行、观察、修改和重跑。需要机器读取时使用 `show --json`。查看器用法见[查看结果](/zh/tutorials/viewing-results)。没跑通分三类定位：`fetch` 直接抛错 → 应用没起来或 URL 不对。`t.succeeded()` 不过 → 应用回了非成功状态。只有内容断言不过 → 接入已经通了，调断言或调应用。
 
 ## 第 5 步：收尾，告诉用户做了什么
 

package/docs-site/zh/tutorials/authoring.mdx

@@ -50,14 +50,17 @@ export default defineEval({
 
 ```ts
 import { defineEval } from "niceeval";
-import { includes } from "niceeval/expect";
+import { includes, jsonMatch, toolMatch } from "niceeval/expect";
 
 export default defineEval({
   description: "Brooklyn weather query",
   async test(t) {
     await t.send("What's the weather like in Brooklyn today?");
     t.succeeded();
-    t.calledTool("get_weather", { input: { city: "Brooklyn" }, count: 1 });
+    t.calledTool(
+      toolMatch("get_weather", { input: jsonMatch({ city: "Brooklyn" }) }),
+      { count: 1 },
+    );
     t.check(t.reply, includes("sunny"));
   },
 });
@@ -170,7 +173,7 @@ export default defineEval({
 <Lifecycle
   title="一条 Attempt 从排队到收尾"
   hint="悬停暂停"
-  note={<>收尾段不计入这条 Attempt 的耗时口径。<code>niceeval show</code> 加 <code>--timing</code> 打印的就是这棵树的实测版本。</>}
+  note={<>收尾段不计入这条 Attempt 的耗时口径。用 <code>niceeval show --page &lt;route&gt;</code> 读取对应 Report Page，可查看该 Page 已关闭的运行信息。</>}
   phases={[
     { name: "experiment.setup", what: "起隧道、起共享服务", times: "整场一次" },
     { name: "sandbox.queue", what: "等一个并发位", times: "每 Attempt" },

package/docs-site/zh/tutorials/connect-your-agent.mdx

@@ -90,7 +90,7 @@ export default defineEval({
     turn.succeeded().label("请求成功");
     t.check(turn.message, includes("30")).label("说明退款期限");
     turn.judge.autoevals.closedQA("回答是否说明了退款期限？")
-      .atLeast(0.7)
+      .gate(0.7)
       .label("退款政策质量");
   },
 });
@@ -203,7 +203,7 @@ async send(input, ctx) {
 
 `progress` 是可覆盖的短期状态。`diagnostic` 是运行结束后仍能回顾的有界记录。两者都不能指定 phase 或输出流，也不会自动改变 `Turn.status` 或 Attempt 判定。连接失败、解析无法继续等基础设施错误应抛出异常。正常收到的被测 Agent 失败通过 `Turn.status: "failed"` 表达。
 
-终端只显示错误的一层摘要和 Attempt identity。完整 code、message、cause、stack 与 diagnostics 保存在 Attempt-owned 通道里，使用 `niceeval show --run <runId> --page attempt-<attemptId>` 查看。OTel trace 只补充调用关系和耗时，不是错误数据的前提。
+终端只显示错误的一层摘要和 Attempt identity。完整 code、message、cause、stack 与 diagnostics 保存在 Attempt-owned 通道里，使用 `niceeval show @<attempt-locator>` 查看。OTel trace 只补充调用关系和耗时，不是错误数据的前提。
 
 要分别评估本地和生产环境，创建两个 Experiment 文件，并传入不同的工厂参数：