niceeval 0.11.1 → 0.11.3

package/docs-site/zh/tutorials/custom-reports.mdx

@@ -64,11 +64,11 @@ export default defineReport(
   <Col>
     <ExperimentComparison />
     <Section title="考试成绩单">
-      <Scoreboard
-        rows="agent"
-        questions={["security/sql-injection", "correctness/retry"]}
-        score={examScore}
-      />
+      <Scoreboard score={examScore}>
+        <Rows dimension="agent" />
+        <Question id="security/sql-injection" />
+        <Question id="correctness/retry" />
+      </Scoreboard>
     </Section>
   </Col>,
 );
@@ -146,8 +146,16 @@ niceeval view --report ./reports/exam.tsx   # 本次换成另一份文件
 
 ```tsx
 <Row>
-  <Scoreboard rows="agent" questions={["security/sql-injection", "correctness/retry"]} score={examScore} />
-  <MetricTable rows="agent" columns={[endToEndPassRate, costUSD]} />
+  <Scoreboard score={examScore}>
+    <Rows dimension="agent" />
+    <Question id="security/sql-injection" />
+    <Question id="correctness/retry" />
+  </Scoreboard>
+  <MetricTable>
+    <Rows dimension="agent" />
+    <Column metric={endToEndPassRate} />
+    <Column metric={costUSD} />
+  </MetricTable>
 </Row>
 ```
 
@@ -218,11 +226,12 @@ const changedLines = defineMetric({
 });
 
 export default defineReport(
-  <MetricTable
-    rows="agent"
-    columns={[endToEndPassRate, changedLines, costUSD]}
-    sort={endToEndPassRate}
-  />,
+  <MetricTable>
+    <Rows dimension="agent" sort={endToEndPassRate} />
+    <Column metric={endToEndPassRate} />
+    <Column metric={changedLines} />
+    <Column metric={costUSD} />
+  </MetricTable>,
 );
 ```
 
@@ -264,7 +273,11 @@ const vendor: CustomDimension = {
 };
 
 export default defineReport(
-  <MetricTable rows={vendor} columns={[endToEndPassRate, costUSD]} />,
+  <MetricTable>
+    <Rows dimension={vendor} />
+    <Column metric={endToEndPassRate} />
+    <Column metric={costUSD} />
+  </MetricTable>,
 );
 ```
 
@@ -289,16 +302,23 @@ export default defineExperiment({
 });
 ```
 
-维度槽(`series` / `rows` / `columns` / `points`)用不加 `numeric` 前缀的版本按声明值分组;数值轴(`MetricLine` 的 `x`)必须用 `numericFlag()` / `numericLabel()` / `numericRunConfig()`,因为刻度要求真实数值:
+分组用不加 `numeric` 前缀的版本按声明值分类;当坐标轴用的变量(`<XAxis numeric={...} />`)必须用 `numericFlag()` / `numericLabel()` / `numericRunConfig()`,因为刻度要求真实数值:
 
 ```tsx
-import { MetricLine, defineReport, endToEndPassRate, flag, numericFlag } from "niceeval/report";
+import {
+  Line, LineChart, XAxis, YAxis,
+  defineReport, endToEndPassRate, flag, numericFlag,
+} from "niceeval/report";
 
 const agents = flag("agents", { label: "并行 agent 数" });
 const latency = numericFlag("latencyMs", { label: "Simulated latency", unit: "ms" });
 
 export default defineReport(
-  <MetricLine x={latency} series={agents} y={endToEndPassRate} />,
+  <LineChart>
+    <XAxis numeric={latency} />
+    <YAxis metric={endToEndPassRate} />
+    <Line metric={endToEndPassRate} by={agents} />
+  </LineChart>,
 );
 ```
 
@@ -326,11 +346,6 @@ const CostBoard = defineComponent(async (_props: {}, ctx) => {
   });
   return (
     <Table
-      columns={[
-        { key: "agent", header: "Agent" },
-        { key: "pass", header: "通过率", align: "right" },
-        { key: "cost", header: "成本", align: "right" },
-      ]}
       rows={board.rows.map((r) => ({
         key: r.key,
         cells: {
@@ -340,7 +355,11 @@ const CostBoard = defineComponent(async (_props: {}, ctx) => {
           cost: r.cells[costUSD.name].value === null ? null : r.cells[costUSD.name].display,
         },
       }))}
-    />
+    >
+      <Column key="agent" header="Agent" />
+      <Column key="pass" header="通过率" align="right" />
+      <Column key="cost" header="成本" align="right" />
+    </Table>
   );
 });
 
@@ -465,6 +484,77 @@ codex   ████████████████░░░░  80%
 - **样式随树带走。** 静态导出不打包你的代码,`className` 引用的 CSS 用内置原语 `<Style>{css}</Style>` 放进页面树——web 面吐 `<style>` 标签,text 面渲染为空,上面的例子就是这么给 `.passbars` 上样式的。
 - **诚实契约同样适用。** 缺数据渲染 `—` 不补 0,截断如实标注剩余数量——上面例子里 `克劳德` 没有样本就是 `—`。
 
+### 让自己的组件和官方组件叫同一个名字、上同一个颜色
+
+同一页里,`compare/with-memory` 在官方榜单上缩成 `with-memory`、配一个蓝色;自己写的组件要显示成同一个样子,用这两个出口,不要自己实现一遍:
+
+```tsx
+import { defineComponent, experimentListData, shortestUniqueLabels } from "niceeval/report";
+
+const MyLegend = defineComponent<{ ids: string[] }>({
+  web({ ids }, ctx) {
+    const labels = shortestUniqueLabels(ids);          // 整组一起传,不逐个调
+    return (
+      <ul>
+        {ids.map((id) => (
+          // 取色用完整 id(键),显示用缩写(名字)
+          <li key={id} className={ctx.seriesColor("experiment", id).className}>
+            {labels.get(id)}
+          </li>
+        ))}
+      </ul>
+    );
+  },
+  text({ ids }) {
+    const labels = shortestUniqueLabels(ids);
+    return ids.map((id) => labels.get(id)).join("  ");  // 终端不上色
+  },
+});
+```
+
+`ctx.seriesColor(维度, 维度值)` 读的是这一页已经分好的色:官方图表的图例、实体列表的行、你这个组件,同一个 id 拿到的是同一个色槽。传进去的必须是完整的维度值,不是缩写后的显示名。
+
+在自己的 React 页面里嵌 `niceeval/report/react` 组件时没有这一页,自己把要上色的键一次交给 `seriesColors(keys)` 拿映射——一次传全集,逐个键调用得不到同页消解撞色的结果。
+
+### 钉住某个值的颜色
+
+自动分配保证同一页里同一个值恒同色,但它不知道你的语义:发布图上「baseline 恒中性、我们的方案恒蓝」是你的判断。写在报告外壳的 `seriesPins` 里:
+
+```tsx
+export default defineReport({
+  title: "MemoryBench",
+  seriesPins: {
+    memory: { baseline: 3, mempal: 1, nowledge: 5 },   // 维度名 → 值 → 色板下标
+  },
+  content: <Leaderboard />,
+});
+```
+
+钉的是六色色板的**下标**,不是颜色——所以深浅外观、对比度和[换主题](/zh/tutorials/theming)全都照常跟随;要改颜色本身,改的是主题的 `series` 六色。被钉住的值原样占位,其余值在剩下的槽里自动分配。
+
+钉色写在报告里而不是主题里,是因为它说的是数据含义:换一套配色不该让基线和候选方案对调身份。它也是整站字段,所以同一个记忆机制在总览页和分科页必须同色。
+
+### 让自己的组件跟随任何主题
+
+自己写的组件要能装上任何一份主题——包括别人分发给你的那一份。颜色只有三个来源,没有第四条路:
+
+| 要表达 | 用什么 |
+|---|---|
+| 好 / 坏 / 警告 | `Stat` 的 `tone`,或 `var(--nre-positive)` / `var(--nre-negative)` / `var(--nre-warning)` |
+| 某个维度值的分类身份 | `ctx.seriesColor(维度, 维度值)` |
+| 其余一切(文字、表面、分隔、圆角、字体) | `var(--nre-*)` 令牌 |
+
+```css
+.nre .acme-panel {
+  background: var(--nre-surface);
+  border: 1px solid var(--nre-border);
+  border-radius: var(--nre-radius);   /* 零圆角主题下自动变直角 */
+  color: var(--nre-text);
+}
+```
+
+三条纪律:写死的颜色值在深色分支会失灵、换主题不跟随;自己的 class 用自己的前缀,不占 `nre-`(那是主题瞄准的公开语义面);宽度、位置这类由数据算出来的几何量可以写成行内样式,颜色不行。令牌全集与更多写法见[给报告换主题](/zh/tutorials/theming)。
+
 ## 发布:导出即静态站
 
 发布自定义报告和发布官方查看器是同一个动作——`--out` 加上 `--report`:

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

@@ -53,17 +53,16 @@ npx niceeval exp local fixtures/button --runs 10
 ```ts
 import { codexAgent } from "niceeval/adapter";
 import { e2bSandbox } from "niceeval/sandbox";
+import { NICEEVAL_CODEX_E2B_TEMPLATE } from "niceeval/sandbox/e2b-template";
 
 export default defineExperiment({
   agent: codexAgent(),
   model: "gpt-5.4",
-  sandbox: e2bSandbox({
-    template: "correctroads-default-team/niceeval-codex:v0.6.1",
-  }),
+  sandbox: e2bSandbox({ template: NICEEVAL_CODEX_E2B_TEMPLATE }),
 });
 ```
 
-Claude Code 使用 `correctroads-default-team/niceeval-claude-code:v0.6.1`，Bub 使用 `correctroads-default-team/niceeval-bub:v0.6.1`。版本 tag 适合 CI；省略 tag 会跟随当前稳定构建。添加系统包、二进制或模型缓存的步骤见 [Sandbox Provider · 从官方基线继续构建以提速](/zh/tutorials/sandbox-providers#从官方基线继续构建以提速)。
+Claude Code 用 `NICEEVAL_CLAUDE_CODE_E2B_TEMPLATE`，Bub 用 `NICEEVAL_BUB_E2B_TEMPLATE`。常量的值是完整、版本钉死的引用，版本跟着模板里那个 Agent 的版本走，你不用跟踪它。添加系统包、二进制或模型缓存的步骤见 [Sandbox Provider · 从官方基线继续构建以提速](/zh/tutorials/sandbox-providers#从官方基线继续构建以提速)。
 
 内置 agent 从 `niceeval/adapter` 导出的是工厂函数。需要配置鉴权、代理、MCP 或 GitHub skill 时，把这些写进工厂参数；模型仍然写在 experiment 的 `model` 字段，sandbox provider 仍然写在 `sandbox` 字段：
 

package/docs-site/zh/tutorials/sandbox-providers.mdx

@@ -154,10 +154,10 @@ Adapter 与 Sandbox 不互相猜配置：Adapter 负责检查所需 CLI，Sandbo
 
 #### E2B：从官方与公共模板派生
 
-E2B 已提供 Claude Code 的 `claude` template 和 Codex 的 `codex` template。NiceEval 提供一个 E2B 专属的薄封装，让你从这两个官方起点继续链原生 E2B API。E2B 暂无 Bub 官方 template，因此 Bub 分支使用 NiceEval 固定到不可变 commit 的安装配方：
+E2B 已提供 Claude Code 的 `claude` template 和 Codex 的 `codex` template。NiceEval 提供一个 E2B 专属的薄封装，让你从这两个官方起点继续链原生 E2B API。E2B 暂无 Bub 官方 template，因此 Bub 分支使用 NiceEval 钉死版本的安装配方（Bub 版本 + 同代 OTel 插件）：
 
-NiceEval 同时发布了三份任何 E2B Team 都能引用的公共模板。完整 namespace 与经过验证的 release
-tag 由 NiceEval 自己维护，下游直接取完整引用：
+NiceEval 同时发布了三份任何 E2B Team 都能引用的公共模板。完整 namespace 与版本由 NiceEval 自己维护，
+下游直接取完整引用：
 
 ```ts
 import {
@@ -171,9 +171,9 @@ e2bSandbox({ template: NICEEVAL_CODEX_E2B_TEMPLATE })
 e2bSandbox({ template: NICEEVAL_BUB_E2B_TEMPLATE })
 ```
 
-这些基线已实际启动验证：Claude Code `2.1.207`、Codex `0.144.1`，Bub 安装指纹 `83770925b77a`。每个值都是带 tag 的完整跨 Team 引用；业务仓库不应复制这些字符串，也不应维护或读取另一份 NiceEval release 常量。派生模板需要记录 base 身份时，直接使用所选的完整 template ref。
+这些基线都实际启动验证过：Claude Code `2.1.207`、Codex `0.144.1`、Bub `0.4.0`（安装指纹随版本与 OTel 插件 pin 一起变）。模板的版本号跟着它装的那个 Agent 走（形如 `0.144.1-r1`：Agent 版本 + NiceEval 配方修订号），三个 Agent 各自独立发版，NiceEval 库自己的版本不参与命名。所以业务仓库直接用常量，不复制这些字符串、也不跟踪版本；派生模板需要记录 base 身份时，同样用常量的值。
 
-当前常量指向的 `v0.6.1` 中，Claude Code 模板沿用 E2B 官方 `/usr` npm prefix，普通用户不能直接写全局模块。需要在运行时追加 pnpm、yarn 等全局 Node 工具时，显式把它们装到两个模板都已加入 PATH 的 `/usr/local`：
+当前这批公共模板中，Claude Code 模板沿用 E2B 官方 `/usr` npm prefix，普通用户不能直接写全局模块。需要在运行时追加 pnpm、yarn 等全局 Node 工具时，显式把它们装到两个模板都已加入 PATH 的 `/usr/local`：
 
 ```ts
 await t.sandbox.runCommand("npm", [
@@ -194,7 +194,7 @@ const template = e2bCodingAgentTemplate("codex")
   .runCmd("corepack enable && pnpm --version")
   .copy("fixtures/toolchain.lock", "/opt/evals/toolchain.lock");
 
-await Template.build(template, "acme-codex-evals:2026-07-13", {
+await Template.build(template, "acme-codex-evals:0.144.1-r1", {
   cpuCount: 2,
   memoryMB: 4096,
 });
@@ -210,7 +210,7 @@ pnpm tsx scripts/build-e2b-template.ts
 ```ts
 import { e2bSandbox } from "niceeval/sandbox";
 
-sandbox: e2bSandbox({ template: "acme-codex-evals:2026-07-13" })
+sandbox: e2bSandbox({ template: "acme-codex-evals:0.144.1-r1" })
 ```
 
 也可以直接从 NiceEval 公共模板继续派生，只支付项目依赖的构建成本：
@@ -240,17 +240,17 @@ e2bCodingAgentTemplate("bub", {
 [`niceeval/claude-code`](https://hub.docker.com/r/niceeval/claude-code)、
 [`niceeval/codex`](https://hub.docker.com/r/niceeval/codex) 或
 [`niceeval/bub`](https://hub.docker.com/r/niceeval/bub)。每个镜像只包含自己的 Agent CLI，并为
-`linux/amd64` 和 `linux/arm64` 发布 manifest；每个 NiceEval release 都有同名 tag。稳定 CI 要固定
-release tag 或 digest，不要依赖会移动的 `latest`：
+`linux/amd64` 和 `linux/arm64` 发布 manifest。tag 与对应的 E2B 公共模板同号——版本位是镜像里那个
+Agent 的版本。稳定 CI 用具名常量或 digest，不要依赖会移动的 `latest`：
 
 ```ts
-import { dockerSandbox } from "niceeval/sandbox";
+import { NICEEVAL_CODEX_DOCKER_IMAGE, dockerSandbox } from "niceeval/sandbox";
 
-sandbox: dockerSandbox({ image: "niceeval/codex:v0.6.1" })
+sandbox: dockerSandbox({ image: NICEEVAL_CODEX_DOCKER_IMAGE })
 ```
 
-这个镜像是 NiceEval 维护的公开镜像，不是 Docker 的 `library/*` Official Image。它随 NiceEval
-release 更新，里面的 Agent CLI 版本由该 release 的构建配方固定。
+这个镜像是 NiceEval 维护的公开镜像，不是 Docker 的 `library/*` Official Image。它在 Agent 版本或
+构建配方变化时发布新 tag，跟 NiceEval 库的发版节奏无关。
 
 如果只需要一个 Agent，或还要加入项目专有依赖，写 Dockerfile 从 Docker 的官方基线
 `node:24-slim` 派生。省略 `image` 时，NiceEval 也会按 runtime 使用该默认镜像：
@@ -266,7 +266,7 @@ RUN npm install -g @openai/codex@0.144.1
 ```
 
 ```bash
-docker build -t acme-codex-evals:2026-07-13 .
+docker build -t acme-codex-evals:0.144.1-r1 .
 ```
 
 然后在 Experiment 里只引用构建结果：
@@ -274,7 +274,7 @@ docker build -t acme-codex-evals:2026-07-13 .
 ```ts
 import { dockerSandbox } from "niceeval/sandbox";
 
-sandbox: dockerSandbox({ image: "acme-codex-evals:2026-07-13" })
+sandbox: dockerSandbox({ image: "acme-codex-evals:0.144.1-r1" })
 ```
 
 Docker Sandbox 默认以非 root 的 `node` 用户（UID 1000）跑命令，并把 `/usr/local/bin` 放进 PATH，所以 `npm install -g` 装的全局二进制天然可见；要装到别处的 Agent（如落在 `~/.local/bin`）记得让它进 PATH。本地快速迭代可以直接省略 `image` 用默认 `node:*-slim`，稳定 CI 引用不可变 tag。

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

@@ -0,0 +1,169 @@
+---
+title: "给报告换一套主题"
+sidebarTitle: "报告主题"
+description: "用 --theme 换报告外观，用 defineTheme 写一份自己的主题，并把它设成项目默认或发成 npm 包。"
+---
+
+报告说这份结果给谁看什么，主题说它长什么样。两者是分开的：一份主题可以套在任何报告上，一份报告也可以换任何主题。所以给结果站换品牌色不必复制报告文件，团队的配色也只写一次。
+
+主题只作用于网页：`niceeval view` 的页面外壳和页内组件读同一份主题，本地查看和 `--out` 导出的静态站是同一套。`niceeval show` 是终端输出，没有主题这一层。
+
+## 换一次外观
+
+不改任何文件，对着同一份报告试装：
+
+```bash
+niceeval view --theme ./themes/acme.ts
+niceeval view --report reports/site.tsx --theme ./themes/acme.ts
+niceeval view --theme basalt                 # 内置主题名，回到官方外观
+```
+
+`--theme` 的裸词查内置主题名（当前只有 `basalt`），带路径的值按文件装载。
+
+每次运行只有一份主题生效，四档，前面没有才用后面：
+
+| 档 | 取值 |
+|---|---|
+| 1 | `--theme <名字\|文件>` |
+| 2 | 报告自己的 `theme` 字段 |
+| 3 | `niceeval.config.ts` 的 `theme` 字段 |
+| 4 | 内置 `basalt` |
+
+生效的那一份里没写的东西取官方值，不会跟下一档拼起来。
+
+## 写一份自己的主题
+
+只换品牌色时，一个字段就是一份完整主题：
+
+```tsx
+// themes/acme.ts
+import { defineTheme } from "niceeval/report";
+
+export default defineTheme({ accent: { light: "#6D28D9", dark: "#C4B5FD" } });
+```
+
+写一个颜色表示浅色深色都用它。品牌色只在某种背景下好看时，两支分别给出——NiceEval 不替你猜另一支长什么样。
+
+做一份认得出来的主题，动的是色板、底色、字体和圆角：
+
+```tsx
+// themes/acme.ts
+import { defineTheme } from "niceeval/report";
+
+export default defineTheme({
+  appearance: "system",
+  accent: { light: "#6D28D9", dark: "#C4B5FD" },
+  positive: { light: "#047857", dark: "#6EE7B7" },
+  negative: { light: "#BE123C", dark: "#FDA4AF" },
+  warning: { light: "#A16207", dark: "#FDE047" },
+  series: [
+    { light: "#2563EB", dark: "#60A5FA" },
+    { light: "#059669", dark: "#34D399" },
+    { light: "#D97706", dark: "#FBBF24" },
+    { light: "#7C3AED", dark: "#C4B5FD" },
+    { light: "#DB2777", dark: "#F472B6" },
+    { light: "#0891B2", dark: "#22D3EE" },
+  ],
+  page: { light: "#FFFBF5", dark: "#120F0C" },
+  surface: { light: "#FFFFFF", dark: "#1C1713" },
+  font: { sans: '"IBM Plex Sans", ui-sans-serif, sans-serif' },
+  radius: "2px",
+  styles: [{ src: "./acme.css" }],
+});
+```
+
+`./acme.css` 按主题文件的位置解析，不是报告文件——把主题连同它的 CSS 搬到别的项目，路径照旧成立。
+
+每个字段说的是含义，不是某个颜色：
+
+| 字段 | 用来表达 |
+|---|---|
+| `accent` | 站点身份、当前导航、链接与 Attempt 定位符 |
+| `positive` / `negative` / `warning` | passed / failed / errored 与截断、覆盖不全 |
+| `series` | 实验、Agent、标签这些分类身份，六个槽 |
+| `page` / `surface` / `border` / `text` 等 | 底色、卡片、分隔线与三级文字 |
+| `font` / `fontSize` / `radius` | 字体栈、正文基准字号、圆角 |
+
+颜色只收 `#RRGGBB`。字体、字号、圆角的值本来就是 CSS，原样写进去。令牌表达不了的效果写在 `styles` 里，那是完整的 CSS 出口。
+
+## 浅色与深色
+
+`appearance` 一个字段同时决定默认哪一支、读者能不能换：
+
+- `system`（默认）：初始跟随浏览器和系统，页头带一个浅 / 深切换，读者选过之后这个站记住。
+- `light` / `dark`：锁定整站，不出现切换控件。主题的 CSS 只为一种背景写过时用这一档。
+
+关掉 JavaScript 打开静态站，看到的就是声明的那一支，所有数值照常可读。
+
+## 设成项目默认
+
+团队里没人应该每次都敲 `--theme`：
+
+```ts
+// niceeval.config.ts
+import { defineConfig } from "niceeval";
+import acme from "./themes/acme";
+import site from "./reports/site";
+
+export default defineConfig({
+  report: site,
+  theme: acme,
+});
+```
+
+之后裸跑 `niceeval view` 就是自己的报告加自己的外观。要给某一份报告钉死外观、不受项目配置影响（例如对外发布的那份必须是品牌色），写进那份报告：
+
+```tsx
+export default defineReport({
+  extends: standard,
+  title: "Acme Evals",
+  theme: acme,
+});
+```
+
+## 发成包，或在别人的主题上改
+
+主题是普通值，发布不需要额外机制：一个 npm 包，默认导出 `defineTheme` 的产物，CSS 和字体随包走。
+
+```tsx
+import acme from "@acme/niceeval-theme";
+
+export default defineConfig({ theme: acme });
+```
+
+在一份主题上改两项，用普通的对象展开；`styles` 是数组，拼接就是数组拼接：
+
+```tsx
+export default defineTheme({
+  ...acme,
+  accent: { light: "#0F766E", dark: "#5EEAD4" },
+  styles: [...(acme.styles ?? []), { inline: ".nre .nre-hero { padding-block: 48px; }" }],
+});
+```
+
+## 发布与嵌入
+
+导出的静态站带着同一份主题，本地看到什么发出去就是什么：
+
+```bash
+niceeval view --report reports/site.tsx --theme ./themes/acme.ts --out site
+```
+
+把报告组件嵌进自己的 React 页面时，同一份主题也能直接用：
+
+```tsx
+import { themeStylesheet } from "niceeval/report";
+import acme from "@acme/niceeval-theme";
+
+<style dangerouslySetInnerHTML={{ __html: themeStylesheet(acme) }} />;
+```
+
+反过来也行：不注入主题，在包住 `.nre` 的容器上声明自己产品的 `--nre-*` 令牌，报告组件就长成产品的样子。
+
+## 边界
+
+- 主题只影响网页。`niceeval show --theme …` 会报错并告诉你改用 `view`。
+- 换主题不改数字：主题不参与取数和计算，改颜色不需要重跑评估。
+- 哪个实验恒用哪个颜色槽写在报告的 `seriesPins` 里，不写在主题里——换配色不该让基线和候选方案对调身份（见[自定义报告](/zh/tutorials/custom-reports#钉住某个值的颜色)）。
+- 自己写的组件要按取色纪律写才跟得上主题，写死的颜色值在深色分支会失灵（见[让自己的组件跟随任何主题](/zh/tutorials/custom-reports#让自己的组件跟随任何主题)）。
+- 页头的 NiceEval 标识和品牌行不从 `accent` 取色，主题不是隐藏它们的开关。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "niceeval",
-  "version": "0.11.1",
+  "version": "0.11.3",
   "description": "Agent-native eval tool — eval agents, services, functions, and coding-agent fixtures",
   "type": "module",
   "license": "MIT",
@@ -175,6 +175,7 @@
     "e2e": "tsx e2e/scripts/run.ts",
     "gen:diff-code": "tsx scripts/gen-diff-code.ts",
     "docs:reference": "tsx scripts/generate-reference.ts",
+    "docs:lint": "tsx scripts/docs-writing-lint.ts",
     "tiers:sync": "node scripts/sync-tiers.mjs sync",
     "tiers:check": "node scripts/sync-tiers.mjs check",
     "view:build": "vite build --config src/view/app/vite.config.ts",

package/src/agents/ai-sdk.test.ts

@@ -1,4 +1,4 @@
-// cases: docs/engineering/testing/unit/results.md
+// cases: docs/engineering/testing/unit/record.md
 // 「Usage、facts 与失败命令证据落盘」桶恒互斥归一:AI SDK 的 inputTokens 是含缓存明细的
 // 输入总量,落桶前扣掉在场的 cacheRead / cacheWrite 明细。
 // bug: memory/estimatecost-openai-inclusive-cache-double-billed.md

package/src/agents/bub-install-spec.ts

@@ -1,32 +1,50 @@
 import { createHash } from "node:crypto";
+import { DEFAULT_BUB_VERSION } from "./coding-cli-versions.ts";
 
-export const DEFAULT_BUB_OVERRIDE =
-  "bub @ git+https://github.com/CorrectRoadH/bub.git@86fbd0febc1665353f5131173554e1f513e66b4c";
-
+/**
+ * Bub 的 OTel tape store 插件——时间轨的来源。插件不发 PyPI，git 依赖是唯一安装方式。
+ *
+ * 插件与 Bub 的 tape 协议同代:这个 pin(bub-contrib#53 之后)从 `bub.tape` 取类型，
+ * 要求 Bub ≥ 0.3.10;更早的 pin 按 republic 的类型校验，配 Bub ≤ 0.3.9。配错代不会安装失败，
+ * 而是 span 全被拒、时间轨静默为空(台账见 memory/bub-tapestore-otel-tapeentry-drift.md)。
+ */
 export const DEFAULT_BUB_OTEL_PLUGIN =
-  "git+https://github.com/bubbuild/bub-contrib.git@add4a6a133c5658aec8f167ef50804d9ee55d22e#subdirectory=packages/bub-tapestore-otel";
+  "git+https://github.com/bubbuild/bub-contrib.git@34715077877041b21472dcca39d91529296a1a9e#subdirectory=packages/bub-tapestore-otel";
+
+/** 装哪一版 Bub：`uv tool install` 的 requirement，版本单源在 `coding-cli-versions.ts`。 */
+export const DEFAULT_BUB_REQUIREMENT = bubRequirement(DEFAULT_BUB_VERSION);
 
 export const BUB_CHECKPOINT_SUBDIRS = [".local"] as const;
 export const BUB_INSTALL_MARKER = ".local/share/niceeval/bub-install-hash";
 
+/**
+ * PyPI requirement for a pinned Bub version.
+ *
+ * 这行同时是安装用的 uv override:OTel 插件所在 workspace 把 `bub` 声明成 git 依赖，
+ * 不覆盖的话每次安装都会去拉 Bub 主干,版本失控。
+ */
+export function bubRequirement(version: string): string {
+  return `bub==${version}`;
+}
+
 export function normalizeBubPackages(packages: readonly string[]): string[] {
   return [...new Set(packages.map((value) => value.trim()).filter(Boolean))].sort();
 }
 
 export function bubInstallSpec(
   packages: readonly string[],
-  override = DEFAULT_BUB_OVERRIDE,
+  requirement = DEFAULT_BUB_REQUIREMENT,
   otelPlugin = DEFAULT_BUB_OTEL_PLUGIN,
 ): string {
   const normalized = normalizeBubPackages(packages);
   const plugins = normalized.length ? ` --with ${normalized.join(" --with ")}` : "";
-  return `bub --override(${override}) --with ${otelPlugin}${plugins} --checkpoint(${BUB_CHECKPOINT_SUBDIRS.join(",")})`;
+  return `${requirement} --with ${otelPlugin}${plugins} --checkpoint(${BUB_CHECKPOINT_SUBDIRS.join(",")})`;
 }
 
 export function bubInstallHash(
   packages: readonly string[],
-  override = DEFAULT_BUB_OVERRIDE,
+  requirement = DEFAULT_BUB_REQUIREMENT,
   otelPlugin = DEFAULT_BUB_OTEL_PLUGIN,
 ): string {
-  return createHash("md5").update(bubInstallSpec(packages, override, otelPlugin)).digest("hex").slice(0, 12);
+  return createHash("md5").update(bubInstallSpec(packages, requirement, otelPlugin)).digest("hex").slice(0, 12);
 }