niceeval 0.9.1 → 0.10.0

package/INDEX.md

@@ -4,9 +4,9 @@
 
 以下路径都相对于包根 `node_modules/niceeval/`。文档位于 `docs-site/zh/`，与当前安装的 NiceEval 版本一起发布。下面的树列出全部随包页面，每行是「路径 — 标题:一句话自述」。分区含义：
 
-- `tutorials/` 第一次跑通；`explanation/` 概念、边界与原理；`how-to/` 按任务的操作步骤；`reference/` API、CLI 与数据形状的精确事实；`troubleshooting/` 按症状排查失败；`examples/` 真实项目的接入案例。
+- `tutorials/` 第一次跑通和按任务操作；`explanation/` 概念、边界与原理；`reference/` API、CLI 与数据形状的精确事实；`troubleshooting/` 按症状排查失败；`examples/` 真实项目的接入案例。
 
-按当前任务从树里挑 1–3 页读取（通常是一页 how-to 或 explanation 搭一页 reference）；页面再引用其它概念或参考时，继续读取包内文件。
+按当前任务从树里挑 1–3 页读取（通常是一页 tutorial 或 explanation 搭一页 reference）；页面再引用其它概念或参考时，继续读取包内文件。
 
 <!-- GENERATED:BEGIN bundled-docs-tree -->
 
@@ -14,66 +14,64 @@
 
 ## `docs-site/zh/tutorials/`
 
-- `docs-site/zh/tutorials/quickstart.mdx` — 为你的 Agent 项目设置评估:安装 NiceEval，写三个文件，10 分钟内对你自己的应用跑通第一条 eval。
+- `docs-site/zh/tutorials/agent-feedback-loop.mdx` — 用 Coding Agent 编写评估用例并迭代程序:让 Coding Agent 读取随包文档，用 Bash 运行实验、查看结果、定位失败并持续迭代，最后通过全量重跑确认结果。
+- `docs-site/zh/tutorials/agent-onboarding.mdx` — Coding Agent 从零接入项目:给 Coding Agent 的完整接入流程：探索项目、与用户确认路径、配置 Judge、写出 Adapter / Experiment / 评估用例并跑通第一个实验。
+- `docs-site/zh/tutorials/authoring.mdx` — 编写评估用例: 单轮、多轮和数据集模式:用 defineEval 编写评估用例，包括单轮对话、多轮对话、数据驱动测试、Sandbox Workspace 和评估的生命周期与 Fixture。
+- `docs-site/zh/tutorials/ci-integration.mdx` — 在 GitHub Actions 和 CI 中运行 NiceEval:把 NiceEval 接入 GitHub Actions 或任意 CI。评估用例失败时非零退出，输出 JUnit XML，并通过缓存加速重复运行。
+- `docs-site/zh/tutorials/connect-otel.mdx` — OTel 接入:把应用已有的 OTel span 发送给 NiceEval，在 niceeval view 中查看每轮调用瀑布图；评估用例断言仍以 Send 返回的事件和用量为准。
+- `docs-site/zh/tutorials/connect-your-agent.mdx` — 接入你的 Agent:写一个 Adapter、配置一个 Experiment，并运行第一条评估用例；再把配置和参数从 Experiment 传给 Adapter 与被测应用。
+- `docs-site/zh/tutorials/custom-reports.mdx` — 编写自定义报告:用 defineReport、内置报告组件和双面组件编写一份同时用于 niceeval show 与 niceeval view 的自定义报告。
+- `docs-site/zh/tutorials/dataset-fanout.mdx` — 数据驱动测试（dataset fan-out）：用多份数据运行同一套评估用例:从 .eval.ts 文件导出数组或 keyed record，将一套评估逻辑展开为多个 case。用 loadYaml 或 loadJson 读取外部数据集，并获得稳定 ID。
+- `docs-site/zh/tutorials/experiments.mdx` — 实验矩阵：用运行矩阵比较 agents 和 models:使用 NiceEval experiments 让同一批评估用例横跨多个 agents、models 和 flags，比较 pass rate、成本和延迟。
+- `docs-site/zh/tutorials/fixtures.mdx` — Sandbox Fixture：用任务评估 coding agents:用 .eval.ts 给 coding agent 准备隔离 workspace、发送真实任务，并用 Sandbox 文件、命令、diff 和 judge 验证结果。
+- `docs-site/zh/tutorials/publish-report.mdx` — 通过 CI 发布报告:把经过 copySnapshots 大小预检的结果目录提交进仓库,CI 用一行 view --results 导出报告站;超大文件在 commit 前就会得到可执行错误。
+- `docs-site/zh/tutorials/quickstart.mdx` — 为你的 Agent 项目设置评估:安装 NiceEval，写三个文件，10 分钟内对你自己的应用跑通第一条评估用例。
+- `docs-site/zh/tutorials/reporters.mdx` — 把结果上报到 Braintrust 与其它目的地:用内置 reporters 把评估用例结果送到 Braintrust 实验、JUnit XML 或自定义目的地。
+- `docs-site/zh/tutorials/sandbox-agent.mdx` — Sandbox Agent：评估 Claude Code、Codex 和 bub:使用 NiceEval 内置 agents 或自定义 adapter，在 Docker 或云端 sandbox 中运行 coding-agent CLI。
+- `docs-site/zh/tutorials/sandbox-providers.mdx` — Sandbox:官方 Sandbox Docker、Vercel 或 E2B Provider。通过预制快照加速评估
+- `docs-site/zh/tutorials/scoring-guide.mdx` — 断言、judge 和成本限制:值断言、作用域断言、LLM-as-judge、test-as-scoring 和效率检查。
+- `docs-site/zh/tutorials/viewing-results.mdx` — 查看 NiceEval 结果并调试 agent 行为:用 niceeval show 在终端按 @<locator> 查看 Attempt 的评估用例源码、执行记录与 diff，或用 niceeval view 在网页中查看同一份证据。
+- `docs-site/zh/tutorials/write-experiment.mdx` — 实验与生命周期:如何写好实验。选择 Agent、传递 model 和 flags，设置 runs、预算、并发与 Sandbox，并用 setup / teardown 起停实验级共享服务。
+- `docs-site/zh/tutorials/write-send.mdx` — 编写 Send:分七步编写 Adapter 的 send 函数：发送消息、续接会话、记录用量、映射工具事件、处理人工介入（HITL）、接入 OTel trace，并透传 Experiment flags。
 
 ## `docs-site/zh/explanation/`
 
 - `docs-site/zh/explanation/adapter.mdx` — Adapter：把 Agent 接入 NiceEval:Adapter 是你写的适配器。本文讲清楚 send 函数传入什么返回什么、被测系统配置怎么传、三个接入等级，以及 t 上的能力从哪来。
 - `docs-site/zh/explanation/assert.mdx` — NiceEval 断言：值、作用域事实、测试与成本:NiceEval 的断言词汇——值断言、作用域断言、test-as-scoring 和效率断言——以及 gate / soft 严重度和判定 verdict 的规则。
 - `docs-site/zh/explanation/drive.mdx` — NiceEval 里怎么驱动 agent：send、session 与 HITL:t.send() 和它返回的 Turn、t.sendFile()、多轮对话、t.newSession()，以及 respond() 处理的人工介入(HITL)。
-- `docs-site/zh/explanation/evals.mdx` — NiceEval 中的 eval：生命周期、verdict 与文件:eval 是一个测试用例：描述和 test 函数，agent-neutral。了解 eval 如何被发现、调度、评分和报告。
-- `docs-site/zh/explanation/experiment.mdx` — 实验（Experiment）：评谁、怎么跑:Experiment 是可签入的运行配置：同一批 eval 对着哪个 agent、哪个模型、开哪些 flags、跑几次。eval 与 experiment 分开的原因——晚绑定，让同一份 eval 换着对象跑。
+- `docs-site/zh/explanation/evals.mdx` — NiceEval 中的评估用例：生命周期、verdict 与文件:评估用例是一个测试用例：描述和 test 函数，agent-neutral。了解评估用例如何被发现、调度、评分和报告。
+- `docs-site/zh/explanation/experiment.mdx` — 实验（Experiment）：评谁、怎么跑:Experiment 是可签入的运行配置：同一批评估用例对着哪个 agent、哪个模型、开哪些 flags、跑几次。评估用例与 experiment 分开的原因——晚绑定，让同一份评估用例换着对象跑。
 - `docs-site/zh/explanation/hitl.mdx` — 人工介入（HITL）：停轮、回答、继续:什么是 Human-in-the-loop，Claude Code / Codex / AI SDK 应用里它长什么样；NiceEval 如何把它变成可评的路径——waiting 停轮、input.requested 说明在等什么、t.respond 替人回答后同一轮继续。
 - `docs-site/zh/explanation/judge.mdx` — NiceEval 里的 LLM-as-judge: 给开放式输出打分:t.judge / session.judge / turn.judge 如何用独立裁判模型评估事实性、闭合式质量和摘要忠实度，以及模型解析优先级和严重度。
-- `docs-site/zh/explanation/overview.mdx` — NiceEval 架构：evals、agents 与 sandboxes:理解 NiceEval、Adapter 和 Sandbox Provider 如何配合，用统一 API 评估任意 AI Agent。
-- `docs-site/zh/explanation/runner.mdx` — NiceEval runner 如何调度和执行 eval:NiceEval runner 发现 eval，用有界并发调度，缓存结果，重试脆弱基础设施，并执行预算保护。
+- `docs-site/zh/explanation/overview.mdx` — NiceEval 架构：评估用例、agents 与 sandboxes:理解 NiceEval、Adapter 和 Sandbox Provider 如何配合，用统一 API 评估任意 AI Agent。
+- `docs-site/zh/explanation/runner.mdx` — NiceEval runner 如何调度和执行评估用例:NiceEval runner 发现评估用例，用有界并发调度，缓存结果，重试脆弱基础设施，并执行预算保护。
 - `docs-site/zh/explanation/tier.mdx` — 接入等级（Tier）：三级投入，三组能力:按「Adapter 接到哪里、额外拿到什么观测数据」接入分三级：Tier 1 只接 send，Tier 2 加 OTel，Tier 3 侵入改造暴露 experiment flags。每档买到什么、什么时候升级。
 
-## `docs-site/zh/how-to/`
-
-- `docs-site/zh/how-to/agent-feedback-loop.mdx` — 让 AI 写 Eval 并自主优化:让 coding agent 读取随包文档，用 bash 运行实验、下钻结果、定位失败并持续迭代，最后用全量重跑确认收敛。
-- `docs-site/zh/how-to/authoring.mdx` — 编写 eval: 单轮、多轮和数据集模式:学习如何用 defineEval 编写 NiceEval eval，包括单轮断言、多轮对话、数据驱动测试和 sandbox workspace。
-- `docs-site/zh/how-to/ci-integration.mdx` — 在 GitHub Actions 和 CI 中运行 NiceEval:把 NiceEval 接入 GitHub Actions 或任意 CI。eval 失败时非零退出，输出 JUnit XML，并通过缓存加速重复运行。
-- `docs-site/zh/how-to/connect-otel.mdx` — OTel 接入:把应用已经在发的 OTel span 也发给 NiceEval 一份，niceeval view 里就有每轮的调用瀑布图。断言不从这里来——接好 send 那一刻断言就齐了。
-- `docs-site/zh/how-to/connect-your-agent.mdx` — 接入你的 Agent:接入的全景：写一个 adapter、配一个 experiment、跑通第一条 eval；配置和参数怎么在 experiment 里声明、在 Adapter 里消费。事件流、多轮、HITL、tracing 是增量，各有专章。
-- `docs-site/zh/how-to/custom-reports.mdx` — 用报告积木搭自己的口径:一份报告就是一个报告文件：官方宿主打开结果、注入数据，双面组件让同一份自定义报告同时用于 niceeval show 与 niceeval view。
-- `docs-site/zh/how-to/dataset-fanout.mdx` — 数据驱动测试（dataset fan-out）：用多份数据运行同一套 eval:从 .eval.ts 文件导出数组或 keyed record，将一套 eval 逻辑展开为多个 case。用 loadYaml 或 loadJson 读取外部数据集，并获得稳定 ID。
-- `docs-site/zh/how-to/experiments.mdx` — 实验矩阵：用运行矩阵比较 agents 和 models:使用 NiceEval experiments 让同一批 eval 横跨多个 agents、models 和 flags，比较 pass rate、成本和延迟。
-- `docs-site/zh/how-to/fixtures.mdx` — 沙箱 Fixture：用任务评估 coding agents:用 .eval.ts 给 coding agent 准备隔离 workspace、发送真实任务，并用 sandbox 文件、命令、diff 和 judge 验证结果。
-- `docs-site/zh/how-to/publish-report.mdx` — 通过 CI 发布报告:把经过 copySnapshots 大小预检的结果目录提交进仓库,CI 用一行 view --results 导出报告站;超大文件在 commit 前就会得到可执行错误。
-- `docs-site/zh/how-to/reporters.mdx` — 把结果上报到 Braintrust 与其它目的地:用内置 reporters 把 eval 结果送到 Braintrust 实验、JUnit XML 或自定义目的地。
-- `docs-site/zh/how-to/sandbox-agent.mdx` — 沙箱 Agent：评估 Claude Code、Codex 和 bub:使用 NiceEval 内置 agents 或自定义 adapter，在 Docker 或云端 sandbox 中运行 coding-agent CLI。
-- `docs-site/zh/how-to/sandbox-providers.mdx` — Sandbox provider：Docker、Vercel 与第三方:NiceEval 在 Docker 或 Vercel sandbox 中运行 coding agents。了解如何选择 provider、配置权限，并通过 warm pools 改善性能。
-- `docs-site/zh/how-to/scoring-guide.mdx` — 评分指南: 断言、judge 和成本限制:用 NiceEval 的五种评分机制评估任意 eval：值断言、作用域断言、LLM-as-judge、test-as-scoring 和效率检查。
-- `docs-site/zh/how-to/viewing-results.mdx` — 查看 NiceEval 结果并调试 agent 行为:每次运行写入 .niceeval/ 的结构化 artifact 有两扇门：niceeval show 在终端用 @<locator> 精确定位一次 Attempt，逐级下钻 Eval 源码、执行记录与 diff；niceeval view 在网页看同一份证据。
-- `docs-site/zh/how-to/write-experiment.mdx` — 写实验：用 defineExperiment 固定运行配置:学习如何在 experiments/ 里用 defineExperiment 选择 agent、传 model 和 flags、设置 runs、预算、并发与 sandbox。
-- `docs-site/zh/how-to/write-send.mdx` — 如何写好 Send:手写 Adapter 的 send 函数，一条主线七步走：发消息拿回复、接上之前的消息、记录消费、把工具解析成事件、人工介入（HITL）、接上 OTel trace、透传 experiment 的 flags。每一步只在上一步的代码上多几行，每一步解锁一组断言。
-
 ## `docs-site/zh/reference/`
 
 - `docs-site/zh/reference/builtin-agents.mdx` — 内置 Agent 能力参考:NiceEval 内置的 claude-code、codex、bub 适配器分别做到了哪些能力，对应哪些断言，以及已知限制。
 - `docs-site/zh/reference/capabilities.mdx` — 能力位参考:NiceEval 怎么知道你的 adapter 做到了什么：没有声明式能力位，全部由构造和实际行为证明。
-- `docs-site/zh/reference/cli.mdx` — NiceEval CLI：命令、flags 和退出码参考:NiceEval CLI 参考：exp、show、view、init、list 和 clean 命令，以及结果下钻、experiment、eval 过滤、并发、预算和 CI 输出。
+- `docs-site/zh/reference/cli.mdx` — NiceEval CLI：命令、flags 和退出码参考:NiceEval CLI 参考：exp、show、view、init、list 和 clean 命令，以及结果下钻、experiment、评估用例过滤、并发、预算和 CI 输出。
 - `docs-site/zh/reference/define-agent.mdx` — defineAgent 和 defineSandboxAgent：adapter 参考:defineAgent 和 defineSandboxAgent 参考：AgentContext、AgentSession、Sandbox 接口和共享 sandbox helpers。
 - `docs-site/zh/reference/define-config.mdx` — defineConfig：项目默认配置:defineConfig 参考：judge、reporters、并发、超时和 sandbox 默认值。
-- `docs-site/zh/reference/define-eval.mdx` — defineEval：声明、配置并运行 NiceEval eval:defineEval 参考：选项、test context t、Turn 返回值、sandbox helper，以及数组和 keyed record 数据集导出。
+- `docs-site/zh/reference/define-eval.mdx` — defineEval：声明、配置并运行 NiceEval 评估用例:defineEval 参考：选项、test context t、Turn 返回值、Sandbox helper，以及数组和 keyed record 数据集导出。
 - `docs-site/zh/reference/events.mdx` — 标准事件流参考:StreamEvent 的十种事件：每种的字段、什么时候吐、哪些断言消费它。adapter 的核心工作就是产出这条流。
 - `docs-site/zh/reference/expect.mdx` — niceeval/expect matchers 与自定义断言参考:niceeval/expect 参考：includes、equals、matches、similarity、satisfies。可链式调用 .gate() 或 .atLeast(0.7)，也可以用 makeAssertion 构建自定义 matcher。
 - `docs-site/zh/reference/official-adapters.mdx` — 官方适配器一览:NiceEval 内置的 Sandbox 和非 Sandbox 适配器分别是什么、怎么鉴权，Sandbox 型里怎么装 MCP server、Skill、插件，怎么使用 Agent 官方配置文件。
 - `docs-site/zh/reference/report-components.mdx` — 报告组件一览:报告文件里能摆的全部官方双面组件：每个组件回答什么问题、怎么调用、网页面长什么样、终端字符输出长什么样。
-- `docs-site/zh/reference/results-data.mdx` — 用 niceeval/results 直接读写结果数据:报告积木脚下的数据层：openResults 把 .niceeval/ 的落盘 artifact parse 成「实验 → 结果快照 → eval → attempt」的类型化层次，createResultsWriter 把别家结果写成 NiceEval 格式，copySnapshots 负责发布瘦身。
+- `docs-site/zh/reference/results-data.mdx` — 用 niceeval/results 直接读写结果数据:报告积木脚下的数据层：openResults 把 .niceeval/ 的落盘 artifact parse 成「实验 → 结果快照 → 评估 → attempt」的类型化层次，createResultsWriter 把别家结果写成 NiceEval 格式，copySnapshots 负责发布瘦身。
 
 ## `docs-site/zh/troubleshooting/`
 
-- `docs-site/zh/troubleshooting/debug-sandbox.mdx` — 保留沙箱现场排查问题:用 --keep-sandbox 把失败 Attempt 的沙箱保留成可随时唤醒的现场，用 niceeval sandbox enter 进去手动排查，用 sandbox list / stop 查看和清理。
-- `docs-site/zh/troubleshooting/debugging.mdx` — 排查失败与复盘历史运行:一份按场景组织的排查手册：断言失败怎么定位、环境错误怎么进沙箱、agent 改了什么怎么看、旧的运行怎么翻出来复盘——每一步都有命令顺序和输出示例。
+- `docs-site/zh/troubleshooting/debug-sandbox.mdx` — 保留 Sandbox 现场排查问题:用 --keep-sandbox 把失败 Attempt 的 Sandbox 保留成可随时唤醒的现场，用 niceeval sandbox enter 进去手动排查，用 sandbox list / stop 查看和清理。
+- `docs-site/zh/troubleshooting/debugging.mdx` — 排查失败与复盘历史运行:一份按场景组织的排查手册：断言失败怎么定位、环境错误怎么进 Sandbox、agent 改了什么怎么看、旧的运行怎么翻出来复盘——每一步都有命令顺序和输出示例。
 
 ## `docs-site/zh/examples/`
 
 - `docs-site/zh/examples/ai-agent-application.mdx` — 自写 Adapter 评估 AI Agent 应用:一个可运行的 AI SDK v6 Web Agent 评测项目，覆盖自写 Adapter、工具调用、图片理解、多轮会话、模型对比和双路可观测。
 - `docs-site/zh/examples/coding-agent-extensions.mdx` — 评估 Coding Agent 扩展:用真实 Workspace、基线实验和自定义报告，评估 Skill、提示词与 Plugin Benchmark 是否改善 Coding Agent 的任务结果。
 - `docs-site/zh/examples/integrations/ai-sdk-v7.mdx` — AI SDK v7 如何非侵入式接入 NiceEval:一个 AI SDK v7 聊天应用，对着它的 HTTP 接口无侵入接入 NiceEval 前后的完整代码 diff：应用侧一行没改。
-- `docs-site/zh/examples/integrations/claude-sdk.mdx` — Claude Agent SDK 如何非侵入式接入 NiceEval:一个 Claude Agent SDK 助手后端，接入 NiceEval 前后的完整代码 diff：应用侧一行没改，全部新增在 eval 侧。
+- `docs-site/zh/examples/integrations/claude-sdk.mdx` — Claude Agent SDK 如何非侵入式接入 NiceEval:一个 Claude Agent SDK 助手后端，接入 NiceEval 前后的完整代码 diff：应用侧一行没改，全部新增在评估用例侧。
 - `docs-site/zh/examples/integrations/codex-sdk.mdx` — Codex SDK 如何非侵入式接入 NiceEval:一个 Codex SDK（目录里的编码 agent）后端，接入 NiceEval 前后的完整代码 diff：应用侧一行没改。
 - `docs-site/zh/examples/integrations/langgraph.mdx` — LangGraph 如何非侵入式接入 NiceEval:一个纯 Python LangGraph + LangSmith OTel 导出的应用，接入 NiceEval 前后的完整代码 diff。
 - `docs-site/zh/examples/integrations/pi-sdk.mdx` — pi-agent-core 如何非侵入式接入 NiceEval:一个 pi-agent-core(@earendil-works)助手后端，接入 NiceEval 前后的完整代码 diff：应用侧只加了一个 devDependency。

package/dist/agents/types.d.ts

@@ -1,4 +1,4 @@
-import type { Cleanup, DiagnosticInput, ProgressUpdate } from "../shared/types.ts";
+import type { DiagnosticInput, ProgressUpdate } from "../shared/types.ts";
 import type { StreamEvent, TraceSpan, Usage } from "../o11y/types.ts";
 import type { Sandbox } from "../sandbox/types.ts";
 /**
@@ -266,10 +266,10 @@ export interface AgentSession {
 }
 export interface AgentContext {
     /**
-     * 软取消信号:合并了 attempt 超时、run 级中断(用户 Ctrl+C)与 eval 自身的中断请求
+     * 软取消信号:合并了 attempt 超时、run 级中断(用户 Ctrl+C)与评估用例自身的中断请求
      * (见 src/runner/attempt.ts)。adapter 可以选择性检查它(或直接传给 `fetch`)以提前
      * 优雅退出,但这不是唯一的硬边界——即便 adapter 完全忽略它,运行器也会用
-     * `Effect.timeoutTo` 兜底强制收尾(停沙箱容器)。
+     * `Effect.timeoutTo` 兜底强制收尾(停 Sandbox 容器)。
      */
     readonly signal: AbortSignal;
     /** 本次 attempt 用的模型名,透传自 experiment 的 `model` 字段。sandbox 型 agent 通常在 setup 里用它写配置,remote 型通常在 send 里用它选模型。 */
@@ -286,13 +286,13 @@ export interface AgentContext {
     /**
      * 路径推导出的实验 id(与结果归属 `runWho` / `AgentRun.experimentId` 同源);不经
      * experiment 跑(如脱离 CLI、直接构造 `AgentRun` 的场景)时为 undefined。典型用途:
-     * `SandboxSpec.setup` 钩子按实验隔离跨 attempt 的状态(缓存目录名、快照 tag 等按
+     * `SandboxSpec.setup` Hook 按实验隔离跨 attempt 的状态(缓存目录名、快照 tag 等按
      * `ctx.experimentId` 分区),或 adapter 按实验切换鉴权 / 路由。与 `flags`(实验条件的
      * 具体取值)是两个维度——这里只是「跑的是哪个实验」的稳定标识,不携带条件内容。
      */
     readonly experimentId?: string;
     /**
-     * 所有 agent 都有:沙箱型是运行器按项目/experiment 配置备好的真实沙箱句柄,remote 型是
+     * 所有 agent 都有:Sandbox 型是运行器按项目/experiment 配置备好的真实 Sandbox 句柄,remote 型是
      * `createRemoteSandbox()` 产出的 stub(仅含 `workdir`/`sandboxId`/`otlpHost`/`stop` 等
      * 元信息,其余方法调用即抛错)。
      */
@@ -330,10 +330,12 @@ export interface AgentContext {
  * agent 自己的沙箱生命周期(每个沙箱一次,与「每轮 send」分开):
  * `setup` 装 CLI、写配置(model/base/auth 等本轮内不变的东西),`send` 只管把一轮 prompt
  * 跑起来(第一次 fresh / 后续 resume)+ 解析 transcript,`teardown` 清理。
- * 运行器在备好沙箱(上传 / 基线 / eval.setup)后、第一次 send 前调一次 `setup`;
- * `setup` 可返回 cleanup 闭包,与 `teardown` 都在 finally 跑。
+ * 运行器在备好沙箱(上传 / 基线 / eval.setup)后、第一次 send 前调一次 `setup`,不返回值;
+ * `teardown` 当且仅当本 attempt 走到过 `setup` 时点才执行(`setup` 抛错不豁免——半初始化
+ * 的现场同样要扫尾),在 finally 里跑。要把 `setup` 里创建的句柄传给 `teardown`,以
+ * `sandbox` 实例为键存取(同一个 Agent 实例服务并发 attempt,不要用实例字段或模块变量)。
  */
-export type AgentSetup = (sandbox: Sandbox, ctx: AgentContext) => Promise<void | Cleanup> | void | Cleanup;
+export type AgentSetup = (sandbox: Sandbox, ctx: AgentContext) => Promise<void> | void;
 export type AgentTeardown = (sandbox: Sandbox, ctx: AgentContext) => Promise<void> | void;
 /**
  * 本 agent 的原生 OTLP span → canonical GenAI semconv 的薄 mapper。
@@ -367,18 +369,19 @@ export interface SandboxAgentDef {
     /** 该 Adapter 的常态证据覆盖声明(完整采集的用 `completeCoverage` 常量);省略 = 全通道 unknown。 */
     coverage?: EvidenceCoverage;
     /**
-     * 每个沙箱一次(不是每轮一次):装 CLI、写 config.toml / 鉴权配置(model/base/auth 等
-     * 本轮内不变的东西)。运行器在沙箱备好(上传/基线/eval.setup 之后)、第一次 send 前
-     * 调用一次。可返回一个 cleanup 闭包,与 `teardown` 一起在 finally 里跑。
+     * 每个 Sandbox 一次(不是每轮一次):装 CLI、写 config.toml / 鉴权配置(model/base/auth 等
+     * 本轮内不变的东西)。运行器在 Sandbox 备好(上传/基线/eval.setup 之后)、第一次 send 前
+     * 调用一次,不返回值。
      */
     setup?: AgentSetup;
-    /** OTLP 导出配置:沙箱里怎么让 CLI 把 trace 发到 endpoint(env / 配置文件),从 setup 拆出。 */
+    /** OTLP 导出配置:Sandbox 里怎么让 CLI 把 trace 发到 endpoint(env / 配置文件),从 setup 拆出。 */
     tracing?: AgentTracing;
     /** 原生 span → canonical 的薄 mapper;省略走通用 heuristic。只影响瀑布图。 */
     spanMapper?: SpanMapper;
     /** 每轮一次:跑 prompt(fresh / resume)+ 解析成 events。 */
     send(input: TurnInput, ctx: AgentContext): Promise<Turn>;
-    /** 沙箱销毁前的清理(与 setup 返回的 cleanup 一起、都在 finally 里跑一次)。 */
+    /** Sandbox 销毁前的清理,当且仅当本 attempt 走到过 `setup` 时点才执行(`setup` 抛错不豁免),
+     * 在 finally 里跑一次。 */
     teardown?: AgentTeardown;
 }
 /** `defineAgent()` 的入参形状(见 src/define.ts)——`kind: "remote"` 由 define 固定填入,不由用户声明。 */
@@ -388,10 +391,9 @@ export interface RemoteAgentDef {
     /** 该 Adapter 的常态证据覆盖声明(完整采集的用 `completeCoverage` 常量);省略 = 全通道 unknown。 */
     coverage?: EvidenceCoverage;
     /**
-     * 每个 attempt 一次(remote agent 没有真实沙箱,运行器会传入一个仅含 `workdir`/`sandboxId`/
+     * 每个 attempt 一次(remote agent 没有真实 Sandbox,运行器会传入一个仅含 `workdir`/`sandboxId`/
      * `otlpHost`/`stop` 等元信息的 stub `Sandbox`,其余方法调用即抛错——不要在这里调用
-     * 文件/命令类沙箱方法)。常用于建立连接、鉴权等一次性准备。可返回一个 cleanup 闭包,
-     * 与 `teardown` 都在 finally 里跑。
+     * 文件/命令类 Sandbox 方法)。常用于建立连接、鉴权等一次性准备,不返回值。
      */
     setup?: AgentSetup;
     /** OTLP 导出配置:远程被测对象怎么把 trace 发到 endpoint(env-based 注入 / file-based 配置)。 */
@@ -400,6 +402,7 @@ export interface RemoteAgentDef {
     spanMapper?: SpanMapper;
     /** 每轮一次:把一轮 prompt 发给远程被测对象(HTTP/SDK 等),解析响应成 events。 */
     send(input: TurnInput, ctx: AgentContext): Promise<Turn>;
-    /** 运行结束前的清理(与 setup 返回的 cleanup 一起、都在 finally 里跑一次)。 */
+    /** 运行结束前的清理,当且仅当本 attempt 走到过 `setup` 时点才执行(`setup` 抛错不豁免),
+     * 在 finally 里跑一次。 */
     teardown?: AgentTeardown;
 }

package/dist/context/types.d.ts

@@ -135,37 +135,37 @@ export interface RespondAnswer {
     readonly optionId?: string;
     readonly text?: string;
 }
-/** eval 作者可见的受限沙箱视图:能执行命令 / 文件 IO / 读最终 diff,但不能 stop。 */
+/** 评估用例作者可见的受限 Sandbox 视图:能执行命令 / 文件 IO / 读最终 diff,但不能 stop。 */
 export interface SandboxHandle {
-    /** 沙箱内的工作目录绝对路径。 */
+    /** Sandbox 内的工作目录绝对路径。 */
     readonly workdir: string;
-    /** 在沙箱里执行一条命令(argv 形式,不经 shell)。装系统依赖等需要 root 时传 `{ root: true }`。 */
+    /** 在 Sandbox 里执行一条命令(argv 形式,不经 shell)。装系统依赖等需要 root 时传 `{ root: true }`。 */
     runCommand(cmd: string, args?: string[], opts?: CommandOptions): Promise<CommandResult>;
-    /** 在沙箱里执行一段 shell 脚本(经 shell 解释,支持管道 / 重定向)。 */
+    /** 在 Sandbox 里执行一段 shell 脚本(经 shell 解释,支持管道 / 重定向)。 */
     runShell(script: string, opts?: CommandOptions): Promise<CommandResult>;
-    /** 读沙箱内某文件此刻的文本内容(实时读,不是 diff 快照)。 */
+    /** 读 Sandbox 内某文件此刻的文本内容(实时读,不是 diff 快照)。 */
     readFile(path: string): Promise<string>;
-    /** 沙箱内某路径此刻是否存在。 */
+    /** Sandbox 内某路径此刻是否存在。 */
     fileExists(path: string): Promise<boolean>;
-    /** 按选项批量读回沙箱里的源文件,供比对 / judge 用材料。 */
+    /** 按选项批量读回 Sandbox 里的源文件,供比对 / judge 用材料。 */
     readSourceFiles(opts?: ReadSourceFilesOptions): Promise<SourceFiles>;
-    /** 把一组内容写进沙箱(路径相对 targetDir,默认 workdir)。 */
+    /** 把一组内容写进 Sandbox(路径相对 targetDir,默认 workdir)。 */
     writeFiles(files: Record<string, string>, targetDir?: string): Promise<void>;
-    /** 把一批内存中的文件上传进沙箱。 */
+    /** 把一批内存中的文件上传进 Sandbox。 */
     uploadFiles(files: SandboxFile[], targetDir?: string): Promise<void>;
-    /** 把本地目录整体上传进沙箱;`opts.ignore` 排除指定路径。 */
+    /** 把本地目录整体上传进 Sandbox;`opts.ignore` 排除指定路径。 */
     uploadDirectory(localDir: string, targetDir?: string, opts?: {
         ignore?: string[];
     }): Promise<void>;
-    /** 从沙箱下载某文件内容。 */
+    /** 从 Sandbox 下载某文件内容。 */
     downloadFile(path: string): Promise<Buffer>;
-    /** 把一段内容上传成沙箱里的单个文件。 */
+    /** 把一段内容上传成 Sandbox 里的单个文件。 */
     uploadFile(path: string, content: Buffer): Promise<void>;
-    /** 沙箱 provider 分配的实例 id,用于排查 / 关联日志。 */
+    /** Sandbox provider 分配的实例 id,用于排查 / 关联日志。 */
     readonly sandboxId: string;
     /** 相对 git 基线的最终 diff 视图(test() 跑完、finalize 前才落定)。 */
     readonly diff: DiffView;
-    /** 取沙箱内某文件的最终内容,占位延迟到 finalize 才真正读取;只能配合 t.check 使用。 */
+    /** 取 Sandbox 内某文件的最终内容,占位延迟到 finalize 才真正读取;只能配合 t.check 使用。 */
     file(path: string): string;
     /** 断言 diff 里某路径发生了变化(新增或修改)。 */
     fileChanged(path: string): AssertionHandle;
@@ -173,7 +173,7 @@ export interface SandboxHandle {
     fileDeleted(path: string): AssertionHandle;
     /** 断言 diff 的路径与内容都不匹配给定正则(常用来否定式检查不该出现的改动)。 */
     notInDiff(re: RegExp): AssertionHandle;
-    /** 断言沙箱里执行过的命令都没有失败退出。 */
+    /** 断言 Sandbox 里执行过的命令都没有失败退出。 */
     noFailedShellCommands(): AssertionHandle;
 }
 /**
@@ -279,7 +279,7 @@ export interface TestContext {
     /** 本次 attempt 生效的实验 flags(experiment.flags 的只读视图;实验条件,非命令行开关)。 */
     readonly flags: Readonly<Record<string, unknown>>;
     /**
-     * 作用域反馈:报告 eval 自己执行的长步骤(上传 fixture、跑构建……)。短命状态,scope 固定
+     * 作用域反馈:报告评估用例自己执行的长步骤(上传 Fixture、跑构建……)。短命状态,scope 固定
      * 为 `eval.run`;只报告不断言(见 docs/feature/eval/library/context.md「向运行反馈长步骤」)。
      */
     progress(update: ProgressUpdate): void;
@@ -290,16 +290,16 @@ export interface TestContext {
     diagnostic(input: DiagnosticInput): void;
     /** `progress({ message: msg })` 的别名(调试日志),不出现在最终结果里。 */
     log(msg: string): void;
-    /** 立即中止本 eval 并标记为 skipped(verdict / EvalResult.skipReason),reason 不能为空。 */
+    /** 立即中止本评估用例并标记为 skipped(verdict / EvalResult.skipReason),reason 不能为空。 */
     skip(reason: string): never;
     /**
      * 对任意值跑一个 ValueAssertion,返回可链 `.gate()` / `.atLeast()` 的 AssertionHandle。
-     * 打分延迟到 eval 结束后统一 finalize,调用本身同步、不抛错——不通过只是记一条失败断言,
-     * 不会中止后续代码。要「不满足就立即中止 eval」用 require。
+     * 打分延迟到评估用例结束后统一 finalize,调用本身同步、不抛错——不通过只是记一条失败断言,
+     * 不会中止后续代码。要「不满足就立即中止评估用例」用 require。
      */
     check(value: unknown, assertion: ValueAssertion): AssertionHandle;
     /**
-     * 对任意值跑一个 ValueAssertion,立即(await 时)求值;不满足就抛错中止整个 eval 剩余步骤
+     * 对任意值跑一个 ValueAssertion,立即(await 时)求值;不满足就抛错中止整个评估用例剩余步骤
      * (仍会把这条断言计入报告,不影响已记录的其它断言)。跟 check 的区别:check 只记录、
      * 从不抛错,打分留到最后统一算;require 当场判定、失败即中止,适合「前置条件不满足,
      * 后面写了也没意义」的场景。
@@ -342,7 +342,7 @@ export interface TestContext {
     eventOrder(types: StreamEvent["type"][]): AssertionHandle;
     /** 用自定义谓词对默认会话累计的整段事件流断言;label 必填、进断言标题。 */
     eventsSatisfy(label: string, predicate: (events: readonly StreamEvent[]) => boolean): AssertionHandle;
-    /** 受限沙箱视图:能执行命令 / 读写文件 / 看最终 diff,不能 stop 沙箱本身(见 SandboxHandle)。 */
+    /** 受限 Sandbox 视图:能执行命令 / 读写文件 / 看最终 diff,不能 stop Sandbox 本身(见 SandboxHandle)。 */
     readonly sandbox: SandboxHandle;
     /** 默认会话累计的 token 用量与估算成本。 */
     readonly usage: Usage;

package/dist/i18n/en.d.ts

@@ -46,6 +46,10 @@ export declare const en: {
     "cli.flag.invalidNumber": string;
     "cli.flag.invalidOutput": string;
     "runner.budgetUnenforceable": string;
+    "runner.experimentTeardownFailed": string;
+    "runner.cleanupTimeout": string;
+    "runner.setupReturnedCleanup": string;
+    "runner.experimentTeardownLate": string;
     "judge.modelMissing": string;
     "loaders.yamlMissing": string;
     "cli.flag.parseError": string;
@@ -96,6 +100,8 @@ export declare const en: {
     "define.evalTestRequired": string;
     "define.experimentAgentRequired": string;
     "define.experimentFlagNotJson": string;
+    "define.experimentLabelInvalid": string;
+    "define.experimentSetupNotFunction": string;
     "define.experimentIdRejected": string;
     "define.sandboxAgentNameRequired": string;
     "define.sandboxCreateRequired": string;
@@ -133,6 +139,10 @@ export declare const en: {
     "feedback.phase.evalSetup": string;
     "feedback.phase.sandboxCreate": string;
     "feedback.phase.sandboxQueue": string;
+    "feedback.phase.experimentSetup": string;
+    "feedback.phase.experimentTeardown": string;
+    "feedback.human.hookDone": string;
+    "feedback.human.hookFailed": string;
     "feedback.phase.sandboxSetup": string;
     "feedback.phase.scoring": string;
     "feedback.phase.teardown": string;
@@ -212,8 +222,6 @@ export declare const en: {
     "runner.startSandboxTeardown": string;
     "runner.timeout": string;
     "runner.traceSelected": string;
-    "runner.resumeCarry": string;
-    "runner.resumeCarryDetail": string;
     "runner.useRemoteAgent": string;
     "sandbox.providerNotImplemented": string;
     "sandbox.missingSpec": string;

package/dist/i18n/zh-CN.d.ts

@@ -46,6 +46,10 @@ export declare const zhCN: {
     readonly "cli.flag.invalidNumber": "标志 --{{flag}} 需要数字,收到 \"{{value}}\"。\n";
     readonly "cli.flag.invalidOutput": "标志 --output 需要 auto|human|agent|ci 之一,收到 \"{{value}}\"。\n";
     readonly "runner.budgetUnenforceable": "{{budgetKey}} 的 budget:连续多个 attempt 完成后都拿不到成本数据(agent 不上报用量且模型不在价格表)——该 agent 的 budget 无法执行,取消护栏继续跑。\n";
+    readonly "runner.experimentTeardownFailed": "实验 {{experimentId}} 的 teardown 执行失败:{{message}}。结果不受影响,但该实验起的宿主机资源可能没有回收,请手动检查。\n";
+    readonly "runner.cleanupTimeout": "cleanup 执行超过 {{timeoutMs}}ms 清理超时\n";
+    readonly "runner.setupReturnedCleanup": "{{layer}} 返回了一个函数。setup 不承载收尾,返回值不会被执行——收尾写在同层成对的 teardown 里({{hint}});见 docs-site 的实验教程或 docs/runner.md「环境预置」。\n";
+    readonly "runner.experimentTeardownLate": "实验 {{experimentId}} 的 teardown 未被正常计数路径触发,已在运行收尾兜底执行。结果不受影响;这行出现说明命中了一个未定位的调度间歇问题,请把本次运行信息记入 memory 台账。\n";
     readonly "judge.modelMissing": string;
     readonly "loaders.yamlMissing": "loadYaml(\"{{path}}\") 需要 YAML 解析器:请先 `pnpm add yaml`(或改用 loadJson + JSON 数据集)。";
     readonly "cli.flag.parseError": "{{message}}\n运行 `niceeval --help` 查看用法。\n";
@@ -64,10 +68,10 @@ export declare const zhCN: {
     readonly "cli.eval.noMatchKnown": "已发现 {{count}} 个 eval:{{evals}}\n";
     readonly "cli.exp.agentModelFlagUnsupported": "experiment 运行不支持 --agent / --model。请新增或复制一个 experiment 文件并修改 model。\n";
     readonly "cli.exp.viewerFlagUnsupported": "`{{flag}}` 只适用于 niceeval {{command}},不能用于 niceeval exp。\n";
-    readonly "cli.experiment.noMatch": "没有匹配的实验:{{arg}}。已发现:{{experiments}}\n";
+    readonly "cli.experiment.noMatch": string;
     readonly "cli.experiment.viewerCommandHint": "你可能想运行:niceeval {{command}}{{args}}\n";
-    readonly "cli.experiment.noEvalsSelected": "未选择任何 eval:{{selection}} 匹配到 0 个 eval。可用实验:{{experiments}}。\n";
-    readonly "cli.experimentGroup": "组";
+    readonly "cli.experiment.noEvalsSelected": string;
+    readonly "cli.experimentGroup": "路径";
     readonly "cli.fallbackCleanupTimeout": "\ngraceful 清理超时,强制清理沙箱…\n";
     readonly "cli.forceCleanupExit": "\n强制清理沙箱并退出…\n";
     readonly "cli.init.done": "已就绪:evals/、niceeval.config.ts,以及 AGENTS.md 里的 niceeval agent 指引区块(指向 node_modules/niceeval/docs-site/zh)。\n";
@@ -96,6 +100,8 @@ export declare const zhCN: {
     readonly "define.evalTestRequired": "defineEval 需要一个 async test(t) 函数。";
     readonly "define.experimentAgentRequired": "defineExperiment 需要 agent。";
     readonly "define.experimentFlagNotJson": "experiment.flags.{{key}} 不是可 JSON 序列化的值(函数 / undefined / 循环引用 / bigint 不允许);flags 会原样进入结果快照,必须是纯 JSON。";
+    readonly "define.experimentLabelInvalid": "experiment.labels.{{key}} 必须是字符串或有限数字;labels 是报告侧的归类坐标,会原样进入结果快照。";
+    readonly "define.experimentSetupNotFunction": "experiment.setup 必须是函数((ctx) => void);要清理请挂 experiment.teardown;要按实验准备沙箱内环境请挂 sandbox spec 的 .setup() 钩子链。";
     readonly "define.experimentIdRejected": "defineExperiment 不接受 id —— id 由文件路径推导。";
     readonly "define.sandboxAgentNameRequired": "defineSandboxAgent 需要 name。";
     readonly "define.sandboxCreateRequired": "defineSandbox 需要一个 create() 函数。";
@@ -108,7 +114,7 @@ export declare const zhCN: {
     readonly "docker.unsupportedRuntime": "Unsupported runtime: {{runtime}}";
     readonly "feedback.human.active": "ACTIVE";
     readonly "feedback.human.budgetExhausted": "{{experimentId}} 预算已耗尽(已花 {{spent}},未跑 {{unstarted}})";
-    readonly "feedback.human.compare": "Compare: niceeval view {{group}}";
+    readonly "feedback.human.compare": "Compare: niceeval view";
     readonly "feedback.human.counts": "共 {{total}} · 复用 {{reused}} · 运行中 {{running}} · 排队 {{queued}} · 已完成 {{completed}}";
     readonly "feedback.human.diffHint": "Diff:    niceeval show {{locator}} --diff";
     readonly "feedback.human.evalHint": "Eval:    niceeval show {{locator}} --source";
@@ -133,6 +139,10 @@ export declare const zhCN: {
     readonly "feedback.phase.evalSetup": "eval 预置";
     readonly "feedback.phase.sandboxCreate": "创建沙箱";
     readonly "feedback.phase.sandboxQueue": "排队等沙箱";
+    readonly "feedback.phase.experimentSetup": "实验预置";
+    readonly "feedback.phase.experimentTeardown": "实验收尾";
+    readonly "feedback.human.hookDone": "完成";
+    readonly "feedback.human.hookFailed": "失败";
     readonly "feedback.phase.sandboxSetup": "沙箱预置";
     readonly "feedback.phase.scoring": "评分";
     readonly "feedback.phase.teardown": "清理中";
@@ -212,8 +222,6 @@ export declare const zhCN: {
     readonly "runner.startSandboxTeardown": "sandbox teardown(环境预置钩子)…";
     readonly "runner.timeout": "attempt 超时({{timeoutMs}}ms)\n最近进度:\n{{recentLogs}}";
     readonly "runner.traceSelected": " → 留 {{count}}(按语义)";
-    readonly "runner.resumeCarry": "  · 复用上次 {{carried}} 个已判定的结果,重跑 {{retry}} 个 eval\n";
-    readonly "runner.resumeCarryDetail": "      复用 [{{experiment}}] {{evals}}\n";
     readonly "runner.useRemoteAgent": "使用 remote agent(不创建沙箱)…";
     readonly "sandbox.providerNotImplemented": "{{provider}} sandbox provider not implemented; use docker, vercel, or e2b";
     readonly "sandbox.missingSpec": string;

package/dist/o11y/execution-tree.d.ts

@@ -0,0 +1,103 @@
+import type { InputRequest, JsonValue, StreamEvent, ToolName, TraceSpan } from "../types.ts";
+interface ExecutionNodeBase {
+    /** 本函数内确定性生成,同一份 (events, spans) 输入永远产出同一批 id(不是全局稳定 id,
+     * 不跨调用持久化——目前没有下游需要跨次运行比对同一个节点)。 */
+    id: string;
+    /** 唯一关联上的 OTel span(供下钻;渲染层用 endMs - startMs 算耗时)。action 节点的
+     * span.attributes 额外补了 io.tool/io.input/io.output/io.status(见 withIoAttributes);
+     * 其余节点原样保留。缺失 = timing unavailable——要么这次运行没有 OTel 接入,要么有 span
+     * 但没能唯一关联到这个节点上;两种情况都不是「假装有耗时」,统一表现为字段不存在。 */
+    span?: TraceSpan;
+}
+export interface ExecutionMessageNode extends ExecutionNodeBase {
+    kind: "message";
+    role: "assistant" | "user";
+    text: string;
+}
+export interface ExecutionThinkingNode extends ExecutionNodeBase {
+    kind: "thinking";
+    text: string;
+}
+/** Skill 加载节点——一等,直接来自 StreamEvent 的 "skill.loaded",不靠工具名/文本猜。 */
+export interface ExecutionSkillNode extends ExecutionNodeBase {
+    kind: "skill.loaded";
+    skill: string;
+    /**
+     * 仅当原生协议把 Skill 加载表达成可关联的工具调用时才有,和 StreamEvent 同名字段同一含义。
+     * 存在时参与和 action/subagent 节点同一套 callId 关联(见主函数 nodeByCallId):Claude Code
+     * 的 Skill 调用本身就是一次 tool_use,OTel mapper 同样会把它的 tool_use_id 复制成
+     * span.attributes.call_id,唯一命中时这个节点也应该拿到 timing,不因为节点 kind 是
+     * skill.loaded 就被排除在 enrichment 之外。
+     */
+    callId?: string;
+}
+/**
+ * action.called + action.result 按 callId 合并成一个节点。`status` 多了 "pending"
+ * (StreamEvent 的 action.result.status 没有这一档)——这是 ExecutionTree 独有的中间态,
+ * 表示这次运行结束时结果始终没有回来(如超时截断的 transcript),诚实地区分「还没完成」
+ * 和「跑完但失败/被拒绝」。
+ */
+export interface ExecutionActionNode extends ExecutionNodeBase {
+    kind: "action";
+    callId: string;
+    /** 原始工具名(未归一化),对齐 StreamEvent.action.called.name。 */
+    name: string;
+    /** 归一化后的规范工具名,省略表示 adapter 没能归一(等同 ToolCall.name 缺省为 "unknown")。 */
+    tool?: ToolName;
+    input: JsonValue;
+    output?: JsonValue;
+    status: "pending" | "completed" | "failed" | "rejected";
+}
+/** subagent.called + subagent.completed 按 callId 合并;pending 语义同 ExecutionActionNode。 */
+export interface ExecutionSubagentNode extends ExecutionNodeBase {
+    kind: "subagent";
+    callId: string;
+    name: string;
+    remoteUrl?: string;
+    output?: JsonValue;
+    status: "pending" | "completed" | "failed";
+}
+export interface ExecutionInputRequestedNode extends ExecutionNodeBase {
+    kind: "input.requested";
+    request: InputRequest;
+}
+export interface ExecutionCompactionNode extends ExecutionNodeBase {
+    kind: "compaction";
+    reason?: string;
+}
+export interface ExecutionErrorNode extends ExecutionNodeBase {
+    kind: "error";
+    message: string;
+}
+/**
+ * span 存在、有意义,但唯一关联不到任何骨架节点——原样保留成独立节点,清楚标注「只有遥测、
+ * 没有对应事件」,不悄悄猜着并进某个骨架节点。`span` 是必填字段:这类节点的全部内容就是
+ * 这一条 span 本身,没有骨架事件可以叠加。
+ */
+export interface ExecutionTelemetryNode {
+    kind: "telemetry";
+    id: string;
+    span: TraceSpan;
+}
+export type ExecutionNode = ExecutionMessageNode | ExecutionThinkingNode | ExecutionSkillNode | ExecutionActionNode | ExecutionSubagentNode | ExecutionInputRequestedNode | ExecutionCompactionNode | ExecutionErrorNode | ExecutionTelemetryNode;
+export interface ExecutionTree {
+    /**
+     * 骨架节点在前,顺序 = 事件出现顺序;telemetry-only 节点(未能唯一关联的 span)
+     * 按 span.startMs 追加在骨架之后——它们不属于骨架,不改变骨架的节点/顺序/内容,
+     * 只是叠加在末尾的额外证据。
+     */
+    nodes: ExecutionNode[];
+    /**
+     * 这次运行是否提供过任何 span——不代表关联成功,只代表「OTel 接入过」。供渲染层区分
+     * 两种不同的诚实提示:整体没有 OTel 接入(该字段为 false,所有节点自然都没有 span),
+     * 和 OTel 接入了但这一个节点恰好关联不上(该字段为 true,该节点的 span 仍缺失)。
+     */
+    timingAvailable: boolean;
+}
+/**
+ * 纯函数:把标准事件流(骨架)与一批已挑选好的 OTel span(可选 enrichment)合成一棵
+ * ExecutionTree。events 决定节点的存在、顺序与内容;spans 只能给已存在的节点补时间,
+ * 从不新增、删除或重排骨架节点。
+ */
+export declare function buildExecutionTree(events: readonly StreamEvent[], spans: readonly TraceSpan[]): ExecutionTree;
+export {};

package/dist/o11y/otlp/select.d.ts

@@ -0,0 +1,22 @@
+import type { ToolCall, TraceSpan } from "../../types.ts";
+/**
+ * 选出要保留并落盘的 span。
+ * 小 trace 原样返回;大 trace 按 canonical kind 过滤(kind ≠ "other" 留);
+ * 没 mapper(kind 全 "other")则回落到 firehose 频率过滤;仍过多再按耗时硬截断。
+ * 最后一律按起点排序,view 直接当瀑布图渲染。
+ */
+export declare function selectTraceSpans(spans: TraceSpan[]): TraceSpan[];
+/**
+ * I/O 文本上限:文件内容/命令输出可能很大,截一下别把 trace 撑爆。导出给
+ * `execution-tree.ts` 复用——ExecutionTree 的 action 节点给合并上去的 span 补同一份
+ * io.* attributes,必须和这里同一个截断预算,不能另立一个数字。
+ */
+export declare const IO_MAX = 4000;
+export declare function ioText(v: unknown): string;
+/**
+ * 给工具执行 span 补上真实「入参/出参」:codex 等的 OTLP span 只带 tool_name/call_id,
+ * 命令文本与输出在 stdout transcript(events)里 —— 按 call_id 把 deriveRunFacts 的
+ * ToolCall.input/output join 到对应 span 的 attributes(io.input / io.output / io.tool)。
+ * 没匹配上的 span 原样返回。
+ */
+export declare function enrichTraceWithIO(spans: TraceSpan[], toolCalls: readonly ToolCall[]): TraceSpan[];

package/dist/report/{react → assets}/colors.d.ts

@@ -3,6 +3,14 @@ export declare const NRE_PALETTE: readonly ["#2a78d6", "#1baf7a", "#eda100", "#0
 export declare const NRE_PALETTE_SIZE: 6;
 /** FNV-1a 32 位散列:输入相同永远得到相同下标,与运行顺序无关。 */
 export declare function colorIndexForKey(key: string): number;
+/**
+ * 同一张图内 series 键集合的配色:每个键仍以稳定散列为起点(无冲突时与跨图配色一致),
+ * 图内撞色时按传入顺序(图例顺序)线性探测下一个空色格——跨图稳定让位给图内可辨;
+ * 键数超过色板后无空格可探,回落散列格(复用不可避免)。返回键 → 色板下标。
+ * 契约见 docs/feature/reports/library/metric-views.md「MetricScatter」;
+ * 修法台账见 memory/scatter-series-color-collision.md。
+ */
+export declare function colorIndicesForKeys(keys: readonly string[]): Map<string, number>;
 /** 键对应的稳定 class 名("nre-c3"),配 styles.css 的 .nre-cN 上文字色。 */
 export declare function colorClassForKey(key: string): string;
 /**

package/dist/report/{react → assets}/colors.js

@@ -28,6 +28,29 @@ export function colorIndexForKey(key) {
     }
     return hash % NRE_PALETTE_SIZE;
 }
+/**
+ * 同一张图内 series 键集合的配色:每个键仍以稳定散列为起点(无冲突时与跨图配色一致),
+ * 图内撞色时按传入顺序(图例顺序)线性探测下一个空色格——跨图稳定让位给图内可辨;
+ * 键数超过色板后无空格可探,回落散列格(复用不可避免)。返回键 → 色板下标。
+ * 契约见 docs/feature/reports/library/metric-views.md「MetricScatter」;
+ * 修法台账见 memory/scatter-series-color-collision.md。
+ */
+export function colorIndicesForKeys(keys) {
+    const used = new Set();
+    const out = new Map();
+    for (const key of keys) {
+        if (out.has(key))
+            continue;
+        let idx = colorIndexForKey(key);
+        if (used.size < NRE_PALETTE_SIZE) {
+            while (used.has(idx))
+                idx = (idx + 1) % NRE_PALETTE_SIZE;
+        }
+        used.add(idx);
+        out.set(key, idx);
+    }
+    return out;
+}
 /** 键对应的稳定 class 名("nre-c3"),配 styles.css 的 .nre-cN 上文字色。 */
 export function colorClassForKey(key) {
     return `nre-c${colorIndexForKey(key)}`;

package/dist/report/built-in/index.d.ts

@@ -1,3 +1,3 @@
-import { standard } from "./standard.tsx";
-export { standard };
+import { standard, standardAttemptPage } from "./standard.tsx";
+export { standard, standardAttemptPage };
 export default standard;