niceeval 0.11.2 → 0.11.3

package/src/o11y/parsers/opencode.ts

@@ -0,0 +1,295 @@
+// OpenCode `run --format json` / `opencode export` 解析器。方言只住这里,不进 core
+// (契约见 docs/feature/adapters/sdk/opencode/README.md)。
+
+import type { StreamEvent, Usage, ToolName, JsonValue } from "../../types.ts";
+import type { ParsedTranscript } from "./index.ts";
+import { GENERIC_VERB_ALIASES, normalizeToolName as normalizeShared } from "../tool-names.ts";
+
+export const OPENCODE_TOOL_ALIASES: Record<string, ToolName> = {
+  ...GENERIC_VERB_ALIASES,
+  read: "file_read",
+  write: "file_write",
+  create: "file_write",
+  edit: "file_edit",
+  patch: "file_edit",
+  // OpenCode 写文件主路径是 apply_patch;Add File 在下方按 patch 内容升成 file_write。
+  apply_patch: "file_edit",
+  bash: "shell",
+  shell: "shell",
+  webfetch: "web_fetch",
+  websearch: "web_search",
+};
+
+/** 从 apply_patch 的 patchText 抠 path,并把 Add File 升成 file_write。 */
+function enrichApplyPatchInput(input: JsonValue): { input: JsonValue; tool: ToolName } {
+  const obj = input && typeof input === "object" && !Array.isArray(input)
+    ? { ...(input as Record<string, unknown>) }
+    : ({ patchText: input } as Record<string, unknown>);
+  const patchText = typeof obj.patchText === "string" ? obj.patchText : typeof obj.patch === "string" ? obj.patch : "";
+  const add = patchText.match(/\*\*\*\s*Add File:\s*(.+)/);
+  const update = patchText.match(/\*\*\*\s*(?:Update|Delete) File:\s*(.+)/);
+  const path = (add?.[1] ?? update?.[1] ?? "").trim();
+  if (path) obj.path = path;
+  return {
+    input: obj as JsonValue,
+    tool: add ? "file_write" : "file_edit",
+  };
+}
+
+function normalizeToolName(name: string): ToolName {
+  return normalizeShared(name, OPENCODE_TOOL_ALIASES);
+}
+
+function get(obj: unknown, key: string): unknown {
+  return obj && typeof obj === "object" ? (obj as Record<string, unknown>)[key] : undefined;
+}
+
+function str(v: unknown): string | undefined {
+  return typeof v === "string" && v ? v : undefined;
+}
+
+function num(obj: unknown, ...keys: string[]): number {
+  for (const k of keys) {
+    const v = get(obj, k);
+    if (typeof v === "number" && Number.isFinite(v)) return v;
+  }
+  return 0;
+}
+
+function coerceArgs(value: unknown): JsonValue {
+  if (typeof value === "string") {
+    try {
+      return JSON.parse(value) as JsonValue;
+    } catch {
+      return value;
+    }
+  }
+  return (value ?? {}) as JsonValue;
+}
+
+/**
+ * 从 stdout / export 的 JSONL(或夹杂日志的文本)里抽出 JSON 对象行。
+ */
+export function extractOpenCodeJsonl(raw: string | undefined): string | undefined {
+  if (!raw?.trim()) return undefined;
+  const lines = raw.split("\n").filter((line) => {
+    const t = line.trim();
+    return t.startsWith("{") && t.endsWith("}");
+  });
+  return lines.length ? lines.join("\n") : undefined;
+}
+
+/** 事件行上的 sessionID / sessionId。 */
+export function sessionIdFromOpenCodeTranscript(raw: string | undefined): string | undefined {
+  const jsonl = extractOpenCodeJsonl(raw) ?? raw;
+  if (!jsonl) return undefined;
+  for (const line of jsonl.split("\n")) {
+    const t = line.trim();
+    if (!t) continue;
+    try {
+      const obj = JSON.parse(t) as Record<string, unknown>;
+      const id = str(obj.sessionID) ?? str(obj.sessionId) ?? str(get(obj, "session_id"));
+      if (id) return id;
+    } catch {
+      // skip
+    }
+  }
+  return undefined;
+}
+
+/**
+ * OpenCode JSON 事件流 → 标准事件 + usage。
+ * 认 `tool_use` / `text` / `step_finish` 主路径,并兼容少量 legacy 形状。
+ */
+export function parseOpenCodeTranscript(raw: string | undefined): ParsedTranscript {
+  const events: StreamEvent[] = [];
+  let inputTokens = 0;
+  let outputTokens = 0;
+  let cacheReadTokens = 0;
+  let cacheCreationTokens = 0;
+  let costUSD = 0;
+  let requests = 0;
+  let parseSuccess = true;
+  let synth = 0;
+  const nextSynthId = (): string => `oc_${++synth}`;
+  const pending: string[] = [];
+
+  const jsonl = extractOpenCodeJsonl(raw) ?? raw;
+  if (!jsonl?.trim()) {
+    return { events, usage: {}, compactions: 0, parseSuccess: true };
+  }
+
+  const addUsage = (usage: unknown): void => {
+    if (!usage || typeof usage !== "object") return;
+    const rawInput = num(usage, "input", "input_tokens", "inputTokens", "prompt_tokens");
+    const output = num(usage, "output", "output_tokens", "outputTokens", "completion_tokens");
+    let cacheRead = num(usage, "cacheRead", "cache_read", "cache_read_input_tokens", "cacheReadTokens");
+    if (cacheRead === 0) cacheRead = num(get(usage, "prompt_tokens_details"), "cached_tokens");
+    const cacheCreation = num(usage, "cacheWrite", "cache_write", "cache_creation_input_tokens");
+    const cost = num(usage, "cost", "costUSD", "total_cost");
+    if (rawInput === 0 && output === 0 && cacheRead === 0 && cacheCreation === 0 && cost === 0) return;
+    // Chat Completions 口径的 prompt_tokens 可能含缓存命中
+    const input = Math.max(0, rawInput - cacheRead);
+    inputTokens += input;
+    outputTokens += output;
+    cacheReadTokens += cacheRead;
+    cacheCreationTokens += cacheCreation;
+    costUSD += cost;
+    requests += 1;
+  };
+
+  for (const line of jsonl.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    let data: Record<string, unknown>;
+    try {
+      data = JSON.parse(trimmed) as Record<string, unknown>;
+    } catch {
+      parseSuccess = false;
+      continue;
+    }
+
+    try {
+      const eventType = str(data.type) ?? str(data.kind) ?? str(data.event);
+      const part = get(data, "part") as Record<string, unknown> | undefined;
+      const state = part ? (get(part, "state") as Record<string, unknown> | undefined) : undefined;
+
+      if (eventType === "tool_use" && part && str(get(part, "tool"))) {
+        const name = str(get(part, "tool"))!;
+        let input = coerceArgs(get(state, "input") ?? get(part, "input"));
+        let tool = normalizeToolName(name);
+        if (name.toLowerCase() === "apply_patch" || name.toLowerCase() === "patch") {
+          const enriched = enrichApplyPatchInput(input);
+          input = enriched.input;
+          tool = enriched.tool;
+        }
+        const callId =
+          str(get(part, "callID")) ??
+          str(get(part, "callId")) ??
+          str(get(part, "id")) ??
+          str(get(data, "id")) ??
+          nextSynthId();
+        if (!str(get(part, "callID")) && !str(get(part, "callId")) && !str(get(part, "id"))) {
+          pending.push(callId);
+        }
+        events.push({
+          type: "action.called",
+          callId,
+          name,
+          input,
+          tool,
+        });
+        const status = str(get(state, "status"));
+        if (status === "completed" || status === "error" || get(state, "output") !== undefined) {
+          const output = (get(state, "output") ?? get(state, "error") ?? null) as JsonValue;
+          const metadata = get(state, "metadata") as Record<string, unknown> | undefined;
+          const exitCode = typeof get(metadata, "exit") === "number" ? (get(metadata, "exit") as number) : undefined;
+          const isShell = ["bash", "shell", "exec"].includes(name.toLowerCase());
+          const success = isShell
+            ? exitCode === 0 || exitCode === undefined
+            : status !== "error" && !get(state, "error");
+          events.push({
+            type: "action.result",
+            callId,
+            output,
+            status: success ? "completed" : "failed",
+          });
+        }
+        continue;
+      }
+
+      if (eventType === "text") {
+        const text = str(get(part, "text")) ?? str(data.text) ?? str(data.content);
+        if (text?.trim()) events.push({ type: "message", role: "assistant", text });
+        continue;
+      }
+
+      if (eventType === "step_finish" || eventType === "step_start") {
+        // OpenCode 1.18 把用量放在 part.tokens({input,output,...}) + part.cost。
+        const tokens = get(part, "tokens") ?? get(data, "tokens");
+        if (tokens && typeof tokens === "object") {
+          addUsage({
+            ...(tokens as Record<string, unknown>),
+            cost: get(part, "cost") ?? get(data, "cost"),
+          });
+        } else {
+          addUsage(get(data, "usage") ?? get(part, "usage") ?? get(state, "usage"));
+        }
+        continue;
+      }
+
+      if (eventType === "message" || eventType === "assistant" || eventType === "response") {
+        const text =
+          str(get(get(data, "message"), "content")) ?? str(data.content) ?? str(data.text);
+        if (text?.trim()) events.push({ type: "message", role: "assistant", text });
+        addUsage(get(data, "usage"));
+        continue;
+      }
+
+      if (eventType === "error") {
+        const message =
+          str(get(get(data, "error"), "message")) ?? str(data.message) ?? str(data.content) ?? "opencode error";
+        events.push({ type: "error", message });
+        continue;
+      }
+
+      // export 形态:顶层 messages[]
+      const messages = get(data, "messages");
+      if (Array.isArray(messages)) {
+        for (const msg of messages) {
+          const info = get(msg, "info") as Record<string, unknown> | undefined;
+          const role = str(get(info, "role")) ?? str(get(msg, "role"));
+          const parts = get(msg, "parts");
+          if (Array.isArray(parts)) {
+            for (const p of parts) {
+              const pType = str(get(p, "type"));
+              if (pType === "text") {
+                const text = str(get(p, "text"));
+                if (text?.trim() && role !== "user") {
+                  events.push({ type: "message", role: "assistant", text });
+                }
+              } else if (pType === "tool" || pType === "tool_use") {
+                const name = str(get(p, "tool")) ?? str(get(p, "name")) ?? "unknown";
+                const callId = str(get(p, "callID")) ?? str(get(p, "id")) ?? nextSynthId();
+                events.push({
+                  type: "action.called",
+                  callId,
+                  name,
+                  input: coerceArgs(get(get(p, "state"), "input") ?? get(p, "input")),
+                  tool: normalizeToolName(name),
+                });
+                const st = get(p, "state") as Record<string, unknown> | undefined;
+                if (st && (str(get(st, "status")) === "completed" || get(st, "output") !== undefined)) {
+                  events.push({
+                    type: "action.result",
+                    callId,
+                    output: (get(st, "output") ?? null) as JsonValue,
+                    status: str(get(st, "status")) === "error" ? "failed" : "completed",
+                  });
+                }
+              }
+            }
+          } else {
+            const text = str(get(msg, "content")) ?? str(get(msg, "text"));
+            if (text?.trim() && role !== "user") {
+              events.push({ type: "message", role: "assistant", text });
+            }
+          }
+          addUsage(get(info, "usage") ?? get(msg, "usage"));
+        }
+      }
+    } catch {
+      parseSuccess = false;
+    }
+  }
+
+  const usage: Usage = {};
+  if (inputTokens) usage.inputTokens = inputTokens;
+  if (outputTokens) usage.outputTokens = outputTokens;
+  if (cacheReadTokens) usage.cacheReadTokens = cacheReadTokens;
+  if (cacheCreationTokens) usage.cacheCreationTokens = cacheCreationTokens;
+  if (costUSD) usage.costUSD = costUSD;
+  if (requests) usage.requests = requests;
+
+  return { events, usage, compactions: 0, parseSuccess };
+}

package/src/o11y/types.ts

@@ -8,7 +8,7 @@ import type { JsonValue, SourceLoc } from "../shared/types.ts";
  * send 的 `Turn.usage` 直接返回)。每个字段只在协议真实提供该值时存在——原始协议没有 usage 时
  * 省略,不编造数值;不存在「默认 0」或「默认 1」的字段。三个输入侧桶恒互斥:相加才是送进模型的
  * 完整上下文量;把协议原生口径归一到互斥是 adapter 的落值义务——OpenAI 系报「含缓存的输入总量 +
- * 缓存命中子集」,落 inputTokens 前先扣掉子集(docs/feature/results/architecture.md#usage,
+ * 缓存命中子集」,落 inputTokens 前先扣掉子集(docs/feature/record/architecture.md#usage,
  * 各协议明细见 docs/feature/adapters/sdk/<name>/cost.md)。
  */
 export interface Usage {
@@ -64,7 +64,7 @@ export interface InputRequest {
 }
 
 /**
- * 落盘截断的结构化标记(见 docs/feature/results/architecture.md「大值截断」):
+ * 落盘截断的结构化标记(见 docs/feature/record/architecture.md「大值截断」):
  * `path` 是被截断的位置(事件里是字段名,如 "output";span 里是 attribute key,如 "output.value"),
  * `originalBytes` 是截断前的 UTF-8 字节数。view 显示「输出过大,已截断」靠它,不正则匹配 marker。
  */
@@ -188,7 +188,7 @@ export interface TraceSpan {
  * 给人 / 给 EVAL.ts 看的 o11y 摘要(注入沙箱 __niceeval__/results.json)。从 `events.json` 派生的
  * 行为计数缓存,不是权威——同一 niceeval 版本写读,删除后可从 `events.json` 重算。token 用量、
  * 成本与耗时不在这里:权威唯一在 `result.json` 的 `Usage` / `estimatedCostUSD` 与 `durationMs`
- * / `phases`(见 docs/feature/results/architecture.md「o11y.json」)。
+ * / `phases`(见 docs/feature/record/architecture.md「o11y.json」)。
  */
 export interface O11ySummary {
   totalTurns: number;

package/src/report/assets/colors.ts

@@ -36,7 +36,7 @@ export function colorIndexForKey(key: string): number {
  * 同一张图内 series 键集合的配色:每个键仍以稳定散列为起点(无冲突时与跨图配色一致),
  * 图内撞色时按传入顺序(图例顺序)线性探测下一个空色格——跨图稳定让位给图内可辨;
  * 键数超过色板后无空格可探,回落散列格(复用不可避免)。返回键 → 色板下标。
- * 契约见 docs/feature/reports/library/metric-views.md「MetricScatter」;
+ * 契约见 docs/feature/reports/components/README.md「系列色:分配单位是页」;
  * 修法台账见 memory/scatter-series-color-collision.md。
  */
 export function colorIndicesForKeys(keys: readonly string[]): Map<string, number> {

package/src/report/assets/styles.css

@@ -1064,7 +1064,7 @@ table.nre,
 }
 
 /* Source:GitHub diff 式整块横向滚动;与产品站示例卡同一套视觉语言(整行 8% 浅染 + 2px 左缘 +
-   行号位图标,规范见 docs/feature/reports/library/attempt-detail.md)。普通行只是 div,
+   行号位图标,规范见 docs/feature/reports/components/attempt-detail/attempt-source.md)。普通行只是 div,
    只有有证据的行才是可点击 details。 */
 .nre-attempt-source {
   overflow: hidden;

package/src/report/components/attempt-detail/AttemptAssertions.tsx

@@ -1,5 +1,5 @@
 // AttemptAssertions:全量 assertion,非 passed 默认展开、passed 按 group 折叠计数。
-// 没有 assertion 时零输出(docs/feature/reports/library/attempt-detail.md)。
+// 没有 assertion 时零输出(docs/feature/reports/components/attempt-detail/README.md)。
 
 import type { ReactElement } from "react";
 import type { AttemptAssertionsData } from "../../model/types.ts";

package/src/report/components/attempt-detail/AttemptConversation.tsx

@@ -1,5 +1,5 @@
 // AttemptConversation:标准事件流按轮组织的完整分轮事件卡。没有 events 时零输出
-// (docs/feature/reports/library/attempt-detail.md)。
+// (docs/feature/reports/components/attempt-detail/README.md)。
 
 import type { ReactElement, ReactNode } from "react";
 import type { AttemptConversationData, AttemptConversationReply, AttemptConversationRound } from "../../model/types.ts";

package/src/report/components/attempt-detail/AttemptDiagnostics.tsx

@@ -1,5 +1,5 @@
 // AttemptDiagnostics:lifecycle 分组的 diagnostics。没有 diagnostics 时零输出
-// (docs/feature/reports/library/attempt-detail.md)。
+// (docs/feature/reports/components/attempt-detail/README.md)。
 
 import type { ReactElement } from "react";
 import type { AttemptDiagnosticsData } from "../../model/types.ts";

package/src/report/components/attempt-detail/AttemptDiff.tsx

@@ -1,5 +1,5 @@
 // AttemptDiff:generated / modified / deleted 文件摘要与展开的行变化统计。没有变更时零输出
-// (docs/feature/reports/library/attempt-detail.md)。
+// (docs/feature/reports/components/attempt-detail/README.md)。
 
 import type { ReactElement } from "react";
 import type { AttemptDiffData, AttemptDiffFileEntry } from "../../model/types.ts";

package/src/report/components/attempt-detail/AttemptError.tsx

@@ -1,4 +1,4 @@
-// AttemptError:结构化 error 明细。没有 error 时零输出(docs/feature/reports/library/attempt-detail.md)。
+// AttemptError:结构化 error 明细。没有 error 时零输出(docs/feature/reports/components/attempt-detail/README.md)。
 // 字段标签是低层技术标识,与终端 `niceeval show` 一样保持英文,不进 view 的 i18n 词典。
 
 import type { ReactElement } from "react";

package/src/report/components/attempt-detail/AttemptFixPrompt.tsx

@@ -1,5 +1,5 @@
 // AttemptFixPrompt:单条 attempt 的复制修复 prompt。passed 或没有可操作失败时零输出
-// (docs/feature/reports/library/attempt-detail.md)。与 CopyFixPrompt 同一套增强约定:
+// (docs/feature/reports/components/attempt-detail/README.md)。与 CopyFixPrompt 同一套增强约定:
 // prompt 在 resolve 阶段算好、烘进静态 HTML,复制按钮是 enhance.js 的增强行为。
 
 import type { ReactElement } from "react";

package/src/report/components/attempt-detail/AttemptSource.tsx

@@ -1,6 +1,6 @@
 // AttemptSource:GitHub diff 式带标注 eval 源码。send / assertion 行按状态着色，点击
 // 原生 details 在调用点展开完整回复与 assertion 细节。没有 source 时零输出
-// (docs/feature/reports/library/attempt-detail.md)。
+// (docs/feature/reports/components/attempt-detail/attempt-source.md)。
 
 import type { ReactElement, ReactNode } from "react";
 import type { AttemptSourceData, AttemptSourceLineData, AttemptSourceTurn } from "../../model/types.ts";
@@ -192,8 +192,7 @@ function AssertionDetail({ assertion, locale }: { assertion: AssertionResult & {
 }
 
 /** `t.score(label, n)` 调用行的展开区:给分记录本体(label、挣分、分组路径),不着判定色——
- *  给分是分数面事实,不是判定(docs/feature/reports/library/attempt-detail.md「AttemptSource
- *  web 面视觉规范」给分行)。 */
+ *  给分是分数面事实,不是判定(docs/feature/reports/components/attempt-detail/attempt-source.md「给分行」)。 */
 function ScoreEntryDetail({ entry }: { entry: ScoreEntry }): ReactElement {
   return (
     <div className="nre-score-entry-row">

package/src/report/components/attempt-detail/AttemptSummary.tsx

@@ -1,4 +1,4 @@
-// AttemptSummary:恒非空的身份/verdict/时间/成本卡(docs/feature/reports/library/attempt-detail.md)。
+// AttemptSummary:恒非空的身份/verdict/时间/成本卡(docs/feature/reports/components/attempt-detail/README.md)。
 
 import type { ReactElement } from "react";
 import type { AttemptSummaryData } from "../../model/types.ts";

package/src/report/components/attempt-detail/AttemptTimeline.tsx

@@ -1,6 +1,6 @@
 // AttemptTimeline:runner phases 主链 + 收尾段,children(hook/command/turn)默认收合、
 // 失败节点带标记;turn 节点按 traceId 关联同一轮的 agent/model/tool span。没有 phase 时
-// 零输出(docs/feature/reports/library/attempt-detail.md)。
+// 零输出(docs/feature/reports/components/attempt-detail/README.md)。
 
 import type { ReactElement } from "react";
 import type { AttemptTimelineData } from "../../model/types.ts";

package/src/report/components/attempt-detail/AttemptTrace.tsx

@@ -1,5 +1,5 @@
 // AttemptTrace:不与 runner 节点混合的原始 OTel span 树。没有 trace 时零输出
-// (docs/feature/reports/library/attempt-detail.md)。
+// (docs/feature/reports/components/attempt-detail/README.md)。
 
 import type { ReactElement } from "react";
 import type { AttemptTraceData } from "../../model/types.ts";

package/src/report/components/attempt-detail/UsageTable.tsx

@@ -1,5 +1,5 @@
 // UsageTable:判定、轮数、工具调用数、token 拆分与成本摊成的用量明细。没有 usage 时零输出
-// (docs/feature/reports/library/attempt-detail.md#usagetable-组装口径单源)。web 面与 text 面
+// (docs/feature/reports/components/attempt-detail/usage-table.md#组装口径单源)。web 面与 text 面
 // 单行摘要(usageTableText)是同一份 UsageTableData 的两种呈现,不重复组装口径。
 
 import type { ReactElement } from "react";

package/src/report/components/attempt-detail/attempt-components.test.tsx

@@ -423,7 +423,7 @@ describe("Attempt 详情组件族:非空/空证据矩阵", () => {
   });
 
   it("UsageTable:桶恒互斥,inputTokens 落盘原样透传,不派生第二个输入字段", () => {
-    // inputTokens 本身就是未缓存输入(docs/feature/results/architecture.md#usage),
+    // inputTokens 本身就是未缓存输入(docs/feature/record/architecture.md#usage),
     // "uncached in" 只是 face 层在 cacheReadTokens 在场时给的标注,data 不多一个字段。
     const both = usageTableData(evidenceOf({ result: resultOf({ usage: { inputTokens: 100, outputTokens: 1, cacheReadTokens: 40 } }) }))!;
     expect(both.usage?.inputTokens).toBe(100);

package/src/report/components/attempt-detail/compute.ts

@@ -1,4 +1,4 @@
-// Attempt 详情组件族的计算函数(docs/feature/reports/library/attempt-detail.md)。每个
+// Attempt 详情组件族的计算函数(docs/feature/reports/components/attempt-detail/README.md)。每个
 // `attempt*Data(evidence)` 都是纯同步派生:evidence 已经由 loadAttemptEvidence 一次性
 // 装配好全部证据,这里只做适合展示与序列化的取舍,不读文件、不 fetch、不重复调用
 // attempt.events() / trace() / diff()。
@@ -263,7 +263,7 @@ export function attemptSourceData(evidence: AttemptEvidence): AttemptSourceData
 
 /**
  * 单条 attempt 版的批量修复 prompt(与 CopyFixPrompt 的多条版本同一份步骤文案)。三态
- * (docs/feature/reports/library/attempt-detail.md「`AttemptFixPrompt`」):计分制丢分或中止 →
+ * (docs/feature/reports/components/attempt-detail/README.md「`AttemptFixPrompt`」):计分制丢分或中止 →
  * 非 null(围绕丢分检查点组装);计分制挣满且未中止、或通过制 passed → null;skipped 恒 null。
  */
 export function attemptFixPromptData(evidence: AttemptEvidence): AttemptFixPromptData | null {
@@ -303,7 +303,7 @@ export function attemptFixPromptData(evidence: AttemptEvidence): AttemptFixPromp
 
 // ───────────────────────── AttemptTimeline ─────────────────────────
 
-/** 收尾段的阶段名(见 docs/feature/results/architecture.md);两面渲染都把这些单列在主链之后,不计入主链总耗时。 */
+/** 收尾段的阶段名(见 docs/feature/record/architecture.md);两面渲染都把这些单列在主链之后,不计入主链总耗时。 */
 export const TIMELINE_CLOSING_PHASES: ReadonlySet<string> = new Set([
   "eval.teardown",
   "agent.teardown",
@@ -340,7 +340,7 @@ function commandStartOffsetMs(phases: readonly PhaseTiming[] | undefined, timing
 }
 
 /**
- * 失败命令按关联 timing 节点的 `startOffsetMs` 排序(docs/feature/results/architecture.md
+ * 失败命令按关联 timing 节点的 `startOffsetMs` 排序(docs/feature/record/architecture.md
  * 「commandsjson」);关联不到 timing 节点的排在最后,组内保持 `commands.json` 原始顺序作稳定
  * tie-break,不按数组偶然顺序猜时间。
  */
@@ -355,7 +355,7 @@ function sortFailedCommands(
 }
 
 /**
- * 标准事件流按 `loc` 分轮(docs/feature/reports/library/attempt-detail.md「Attempt 详情组件」):
+ * 标准事件流按 `loc` 分轮(docs/feature/reports/components/attempt-detail/README.md「Attempt 详情组件」):
  * 带 loc 的 user 消息开一轮;无 loc 的 user 消息不开新轮——与当前轮 sent 同文本的回显直接
  * 吃掉,其它(stop-hook 反馈、skill 注入等轮内注入)作为回复条目留在当前轮。流首出现无 loc
  * 的 user 消息(没有当前轮可归入)时退化开一条 loc 缺省的兜底轮,不丢弃。未识别的事件类型
@@ -482,7 +482,7 @@ export function attemptDiagnosticsData(evidence: AttemptEvidence): AttemptDiagno
 // ───────────────────────── UsageTable ─────────────────────────
 
 /**
- * 组装口径单源:docs/feature/reports/library/attempt-detail.md#usagetable-组装口径单源。
+ * 组装口径单源:docs/feature/reports/components/attempt-detail/usage-table.md#组装口径单源。
  * identity 字段(locator/experimentId/evalId/attempt/verdict)恒有;turns/toolCalls 是 events
  * 派生(与 o11y.json 行为摘要同源,buildO11ySummary 与 o11y.json 落盘走同一份纯函数),没有
  * events 就整对省略——不因为其中一个恰好是 0 就当作"缺失"处理,0 是观测到的事实。

package/src/report/components/attempt-detail/faces.ts

@@ -1,4 +1,4 @@
-// Attempt 详情组件族的 text 面(docs/feature/reports/library/attempt-detail.md「在 show 与
+// Attempt 详情组件族的 text 面(docs/feature/reports/components/attempt-detail/README.md「在 show 与
 // view 怎样渲染」):与 web 面共享同一次 resolve 产出的 data 事实(verdict、计数、能力位、
 // 引用),允许把大块内容折成摘要 + 专用证据命令,但不得改变判定、计数或引用。
 // 零 react、零 IO、纯同步——text 宿主不需要 react-dom 的那一半。
@@ -304,7 +304,7 @@ export function attemptDiagnosticsText(data: AttemptDiagnosticsData | null, _ctx
 // ───────────────────────── UsageTable ─────────────────────────
 
 /**
- * 单行装配形态,与 docs/feature/reports/library/attempt-detail.md#usagetable-组装口径单源
+ * 单行装配形态,与 docs/feature/reports/components/attempt-detail/usage-table.md#组装口径单源
  * 的示例行文案是同一形态本身,不是它的近似摘要:
  *   `usage: 6 turns · 21 tool calls · 62.3k uncached in + 942.6k cache read / 6.7k out · 24 requests · $1.14`
  * 每个片段独立地只在对应事实存在时出现,顺序保持不变;全部缺失时整行不出现(返回 ""),
@@ -332,7 +332,7 @@ export function usageTableText(data: UsageTableData | null, _ctx: TextContext):
     data.toolCalls !== undefined ? `${data.toolCalls} tool call${data.toolCalls === 1 ? "" : "s"}` : undefined,
     tokenSegment || undefined,
     // requests 只在协议真实提供时显示——协议不提供就整段省略,绝不凑一个 1
-    // (docs/feature/reports/library/attempt-detail.md#usagetable-组装口径单源)。
+    // (docs/feature/reports/components/attempt-detail/usage-table.md#组装口径单源)。
     usage?.requests !== undefined ? `${usage.requests} requests` : undefined,
     data.estimatedCostUSD !== undefined ? formatUSD(data.estimatedCostUSD) : undefined,
   ].filter((s): s is string => s !== undefined);

package/src/report/components/attempt-detail/index.tsx

@@ -1,4 +1,4 @@
-// Attempt 详情组件族的装配点(docs/feature/reports/library/attempt-detail.md)。11 个叶子
+// Attempt 详情组件族的装配点(docs/feature/reports/components/attempt-detail/README.md)。11 个叶子
 // 组件都是同一份 spec/data 判别联合(AttemptSectionProps<Data>):省略 input 时取当前
 // attempt-input page 注入的 evidence;放在 scope-input page 且未显式传 input/data 时
 // resolve 报完整用户反馈并指引移到 attempt-input page 或传入 evidence。

package/src/report/components/entity-lists/AttemptList.tsx

@@ -15,7 +15,7 @@ import { cx } from "../shared.ts";
 
 /**
  * 时效标注(`↩` + 紧凑时距):历史执行(携带,或跨快照拼入)才渲染,新执行不标——subdued
- * 行内事实,不占框、不用警示色(docs/feature/reports/library/entity-lists.md「时效标注」)。
+ * 行内事实,不占框、不用警示色(docs/feature/reports/components/entity-lists/README.md「时效标注」)。
  * web 面 hover 显示完整执行时刻;ExperimentList / EvalList / AttemptList 三处共用。
  */
 export function HistoricalMark({
@@ -35,7 +35,7 @@ export function HistoricalMark({
 
 /**
  * Eval 父行的时效标注:全部 attempt 均为历史执行时,标最近一次执行(startedAt 最大)的时距;
- * 新旧混合时父行不标,子行各自可见(docs/feature/reports/library/entity-lists.md「时效标注」)。
+ * 新旧混合时父行不标,子行各自可见(docs/feature/reports/components/entity-lists/README.md「时效标注」)。
  * EvalList 与 ExperimentList 的 Eval 父行共用。
  */
 export function EvalHistoricalMark({
@@ -79,7 +79,7 @@ export function AttemptLocatorBadge({
 /**
  * failureSummary + moreFailures 的展示形态:摘要原样,+N 计数由 moreFailures 驱动。计分制
  * passed attempt 的非 null 摘要只可能来自丢分得分点(规则 6)——"+N more lost points",不是
- * "+N more failures":丢分不是失败,措辞分开(docs/feature/reports/library/entity-lists.md
+ * "+N more failures":丢分不是失败,措辞分开(docs/feature/reports/components/entity-lists/README.md
  * `AttemptListItem.moreFailures` 字段注释)。
  */
 export function failureSummaryText(item: Pick<AttemptListItem, "failureSummary" | "moreFailures" | "verdict">, locale: ReportLocale): string | null {

package/src/report/components/entity-lists/ExperimentList.tsx

@@ -136,7 +136,7 @@ function EvalAttempts({
 /**
  * 覆盖缺口的占位行:状态列为 —,结果列为「当前配置下无结果」+ 可复制的补跑命令,无 attempt
  * 子行,不参与任何指标聚合——只把分母缺口摆进读者正在看的表里
- * (docs/feature/reports/library/entity-lists.md「ExperimentList」)。
+ * (docs/feature/reports/components/entity-lists/experiment-list.md)。
  */
 function MissingEvalRow({
   evalId,
@@ -279,7 +279,7 @@ export function ExperimentList({
 }): ReactElement {
   const experimentLabels = shortestUniqueLabels(data.map((item) => item.experimentId));
   // 主读数列按列表内题型构成选择;web/text 共用同一份判据,不各自重新判断
-  // (docs/feature/reports/library/entity-lists.md「ExperimentList」)。
+  // (docs/feature/reports/components/entity-lists/experiment-list.md)。
   const composition = experimentListScoringComposition(data);
   const showPassRate = composition !== "points";
   const showTotalScore = composition !== "pass";

package/src/report/components/entity-lists/compute.ts

@@ -1,5 +1,5 @@
 // 计算函数(*Data):ReportInput → 一份组件数据。实体列表族(ExperimentList / EvalList /
-// AttemptList / FailureList)的 *Data 都住在这里(docs/feature/reports/library/entity-lists.md)。
+// AttemptList / FailureList)的 *Data 都住在这里(docs/feature/reports/components/entity-lists/README.md)。
 //
 // 共同约定(docs/feature/reports/architecture.md「指标聚合不变量」):
 // - 第一参收 ReportInput = Scope | readonly Snapshot[];warnings 不进组件数据(宿主统一显示);

package/src/report/components/entity-lists/faces.ts

@@ -34,7 +34,7 @@ function locatorBadge(item: { locator: string; verdict: AttemptListItem["verdict
 /**
  * 时效标注(`↩` + 紧凑时距)的 text 面:历史执行(携带,或跨快照拼入)才输出,新执行为
  * 空串;三面(ExperimentList / EvalList / AttemptList)共用
- * (docs/feature/reports/library/entity-lists.md「时效标注」)。
+ * (docs/feature/reports/components/entity-lists/README.md「时效标注」)。
  */
 function historicalSuffix(item: Pick<AttemptListItem, "startedAt" | "historical">): string {
   return item.historical ? `   ↩ ${formatHistoricalGap(item.startedAt)}` : "";

package/src/report/components/entity-lists/index.tsx

@@ -220,7 +220,7 @@ export interface FailureListProps {
 
 /**
  * 「现在有哪些失败要处理」的成品组合件:内部就是 attemptListData → 过滤 → AttemptList
- * data 形态,与手写组合严格等价、没有私有能力(docs/feature/reports/library/entity-lists.md)。
+ * data 形态,与手写组合严格等价、没有私有能力(docs/feature/reports/components/entity-lists/README.md)。
  * verdict ∈ failed / errored,按 attempt 开始时间降序(同刻按 locator 字典序),
  * 截断到 limit(默认 20),total 报告截断前总数。
  */

package/src/report/components/metric-views/DeltaTable.tsx

@@ -1,7 +1,6 @@
 // DeltaTable:对照矩阵。每行一道 eval,每组列一个条件(首个是基准),尾部对基准的 Δ 列组;
 // 通过制显示 verdict、计分制在同一位置显示挣分,tokens / 成本恒显示;翻转标记 ⇄ 只在该行各
-// 条件判定不一致时出现;历史执行叠加 ↩ 标注(docs/feature/reports/library/metric-views.md
-// 「DeltaTable」)。任一侧缺数据时对应分量各自显示缺,不硬算成 0。
+// 条件判定不一致时出现;历史执行叠加 ↩ 标注(docs/feature/reports/components/tables/delta-table.md)。任一侧缺数据时对应分量各自显示缺,不硬算成 0。
 
 import type { ReactElement } from "react";
 import type { DeltaData } from "../../model/types.ts";

package/src/report/components/metric-views/StabilityMatrix.tsx

@@ -1,6 +1,6 @@
 // StabilityMatrix:历史全执行的稳定性矩阵。行 = eval,列 = by 维度取值,格是该组合全部历史
 // 执行(跨快照按身份键去重、不设可比性门槛)的判定计数——回答「这道题历史上稳不稳」,不是
-// 现刻水位下「现在算不算过」(docs/feature/reports/library/metric-views.md「StabilityMatrix」)。
+// 现刻水位下「现在算不算过」(docs/feature/reports/components/tables/stability-matrix.md)。
 // 稀疏格子:没有样本的格子不出现,不编三个 0 冒充跑过。
 
 import type { ReactElement } from "react";