@migor/cli 0.10.9 → 0.10.10

package/CHANGELOG.md

@@ -5,6 +5,66 @@
 （0.x 阶段：minor 可含破坏性变更，每个破坏性变更都在对应版本的「迁移」小节里写明）。
 决策的完整证据链在 `docs/spec.md` §10（带时间线的决策日志）。
 
+## [0.10.10] - 2026-11-12
+
+### 变更
+
+调试面板从「**看得见一棵树**」推进到「**看得到这一趟 run 的账、找得到那一条、带得走**」。
+三批改动（#304 布局 / #305 说真话 / #306 补账与检索），无破坏性变更、无迁移动作。
+两包同步 0.10.9 → 0.10.10；`src/` 一行未动（`git diff v0.10.9..HEAD -- src/` 为空），
+框架包此次只有版本常量变化，实际改动全在 CLI 面板与 trace-view 渲染件。
+评审依据：`docs/reviews/2026-11-12/inspector-board-gap.md`。
+
+- **#304 · 右栏三块都能折叠**：调用树 / 能力排行 / 回复原先高度写死（树 `flex: 1`、下面两块
+  各 `38vh`），三块同开时谁都不够读；现在标题栏可点，`data-open` 与 `aria-expanded` 由
+  `applyPane` **一处**写入，收起后剩下的块按份分同一个剩余空间（树 1、回复 1.5、排行按内容
+  上限 45%）。收起不等于失明：标题栏仍留规模读数。折叠态是布局偏好，进 localStorage。
+  ⚠️ 第一版踩过一处**状态全对、画面全错**：`#pane-trace > .pane-body` 的 `display: flex`
+  挂在 id 选择器上，特异性压过折叠规则 ⇒ 折叠后树照样铺满；无头 Chrome 截图才看得见。
+- **#305 · 修掉五处在说谎的地方**（只治这五处，不新增视图）：
+
+  | 症状 | 根因 |
+  |---|---|
+  | 回复切走 / 刷新后就消失 | `finalText` 只接在 `run-done` 那一帧 SSE 上，trace 上根本没有它 |
+  | 失败 / 中止轮进不了对话视图 | `mergeConversation` 读 `r.prompt`，生产形状是 `note.prompt`；**单测喂的正是那个不存在的形状** |
+  | 根 span 上的事件整类丢失 | `reset()` 把根登记成 `'root'`，事件按真 `spanId` 投递 ⇒ 静默 return |
+  | 每条 run 都叫 `agent.run` | dev 环不传 `runName`，而 `note.prompt` 一直有货、一直没被用 |
+  | 14 种收尾原因只呈现 3 种（`suspended` 显示成「正常跑完」） | 只分辨中止 / 失败 / 正常，而挂起的 trace 状态是 **ok** |
+
+  改法：`RunNote` 落 `finalText` 且 `/api/runs/:id` 带顶层 `note`（空回复**不写这个键** ——
+  面板要能区分「本来没回复」与「回复丢了」）；`reset(rootName, rootId)` 收下框架真 `spanId`；
+  列表首行给 prompt；`stopReasonClass` 四类终态走「**白名单 + 未知落被拦住**」，框架新增成员时
+  宁可显示成被拦住并露出原文，也不谎报正常收尾。
+- **#306 · 先修地基，再补八件事**：`renderTrace()` 此前「每个动作 = 一次全树重建」，
+  600 span 实测 **1801 次**重建（在飞时每帧还再来一次）；拆成调度层 + `drawTree`，
+  `playTrace` 把 reset + 回放 + finish **整块**包进 `view.batch()` ⇒ 50 span 只重建 1 次。
+  在此基础上补：run 级总账（轮次 / 工具 / 失败 / in-out / cache / 成本带预算上限 / 模型）、
+  span attributes 可见**含根**（`model` / `system.version` / `tools.names` 只写在根上）、
+  时间轴（按 run 总时长归一化）、树内检索（只高亮跳转、不改结构）、列表检索（关键词 +
+  只看异常，异常**含挂起**）、深链 `?run=`（`replaceState` 不堆历史）、重跑（**回填四个输入，
+  不自动跑** —— 自动跑会在误触时花钱）、导出（复制这条 trace 的 JSONL，去掉 CLI 侧 `note`）。
+- **三条「不给假读数」的口径**：① 总账缺字段的那一项**整项不出现**，不显示 `0%` / `$0.0000`
+  ——「成本是 0」与「没有单价表」是两件事；② cache 分母**含缓存写入**，否则刚写了一大块缓存
+  的那次 run 会显示成 100% 命中，正是最容易误读的时刻；③ 时间轴**缺时间戳就整棵不画** ——
+  手写 trace / 官网模拟回放画一条人人占满的条，比不画更误导。
+- **顺手修的实拍发现**：三块同开时调用树只分到 134px ≈ 三行（夹具 23 行只看得见 3 行），
+  `flex-grow: 2` ⇒ 191px。取 2 不是更极端：回复仍要比它大，结论优先。
+
+### 新增：面板从「看树」到「看账」的三批收口
+
+- 决策见 `docs/spec.md` §10 2026-11-12 ref-panel-panes、2026-11-12 ref-inspector-truth、
+  2026-11-13 ref-inspector-board；守卫登记见 `docs/guards.md` §1。
+- **新增守卫**：CLI `structure.test.mjs` 的 **W6**（折叠态只许在 `applyPane` 里写，
+  `data-open` 与 `aria-expanded` 必须一起改）；`stop-reason.test.mjs` **跨包口径**
+  （框架每加一个 `AgentStopReason`，面板都得给出中文说法；只按行首 `|` 摘成员，
+  注释里散落的例子不算）；trace-view `render-batch.test.js`（批量 / 属性含根 / 时间轴 /
+  树内检索）；`panel-logic.test.mjs` + `inspector.test.mjs`（总账 / 检索 / 深链 / 回填接线）。
+- **验证**：CLI **257 → 278**、trace-view **96 → 113**（两侧读数都在本机各跑一遍核过）。
+  三批共 25 条变异各自咬住；#305 / #306 另用无头 Chrome 实拍四条 run 覆盖四态
+  （列表四个圆点、根行七项属性、`?run=demo-2` 直达、回填后**没有**提交、
+  **不推** `run-done` 时切走再切回来回复仍在）。
+- ⚠️ `/api/runs/:id` 的响应多一个顶层 `note`（additive，`playTrace` 只读 `spans` / `traceId`）。
+
 ## [0.10.9] - 2026-11-12
 
 ### 变更
@@ -4561,7 +4621,8 @@ toolkit 142 / runtime 55 / engine 403 / container 10 / store 55 —— 全绿。
 首个公开发布：`@migor/agentia` + `@migor/cli`（scope `@migor/*`），两包版本同步。
 框架本体单包；CLI 独立成包（workspaces）。
 
-[Unreleased]: https://github.com/migoric/agentia/compare/v0.10.9...HEAD
+[Unreleased]: https://github.com/migoric/agentia/compare/v0.10.10...HEAD
+[0.10.10]: https://github.com/migoric/agentia/releases/tag/v0.10.10
 [0.10.9]: https://github.com/migoric/agentia/releases/tag/v0.10.9
 [0.10.8]: https://github.com/migoric/agentia/releases/tag/v0.10.8
 [0.10.7]: https://github.com/migoric/agentia/releases/tag/v0.10.7

package/dist/dev-machine.js

@@ -234,7 +234,14 @@ export function update(state, ev) {
                 lastError = null;
             const effects = [{ kind: 'disarm-abort-timer' }];
             if (ev.traceId !== null && note !== null) {
-                effects.push({ kind: 'note-run', traceId: ev.traceId, note });
+                // 回复（`finalText`）只有这一帧带 ⇒ 必须与 note 一起落账，否则面板切走再切回来
+                // 就再也取不到了（它不在 trace 上）。新建对象而不是改 `note`：pendingNote 是
+                // 上一事件的 state，就地改会让「同一份 note 被两条 run 共享」成为可能。
+                effects.push({
+                    kind: 'note-run',
+                    traceId: ev.traceId,
+                    note: ev.finalText ? { ...note, finalText: ev.finalText } : note,
+                });
             }
             effects.push({
                 kind: 'emit',

package/dist/inspector/fromTrace.js

@@ -147,44 +147,71 @@ export function playTrace(view, trace) {
   }
   items.sort((a, b) => a.t - b.t || a.ord - b.ord || a.d - b.d || a.seq - b.seq);
 
-  const rootRaw = String(root.name || 'run');
-  // 框架的 run 根名可能是 runName（如 'app'）或已是 'run · x' 形态，避免重复前缀
-  view.reset(rootRaw.startsWith('run') ? rootRaw : 'run · ' + rootRaw);
-
-  for (const it of items) {
-    if (it.kind === 'start') {
-      if (it.s === root) continue; // 根由 reset 建，不重复开
-      view.start({
-        id: it.s.spanId,
-        parent: it.s.parentSpanId,
-        kind: it.s.kind,
-        name: displayName(it.s),
-        arg: '',
-      });
-    } else if (it.kind === 'event') {
-      view.event(
-        it.s.spanId,
-        it.ev.name,
-        eventToolName(it.ev.name, it.ev.body?.tool, typeMap),
-        eventText(it.ev),
-        it.ev.body?.ok !== false,
-        eventFull(it.ev),
-      );
-    } else {
-      view.end({
-        id: it.s.spanId,
-        ms: it.s.endedAt - it.s.startedAt,
-        usage: usageOf(it.s),
-        status: it.s.status,
-        error: it.s.error,
-        arg: '',
-      });
+  /** 把归一好的动作逐条喂给视图（不含 reset / finish —— 那两个由外层一起包进批里） */
+  const replay = () => {
+    for (const it of items) {
+      if (it.kind === 'start') {
+        if (it.s === root) continue; // 根由 reset 建，不重复开
+        view.start({
+          id: it.s.spanId,
+          parent: it.s.parentSpanId,
+          kind: it.s.kind,
+          name: displayName(it.s),
+          arg: '',
+          startedAt: it.s.startedAt,
+          // 属性（model / system.version / tools.names / retry.attempt / handoff.* / …）：
+          // 树上一格都不显示的话，「这次是不是提示词版本没换」只能靠猜（2026-11-13）
+          attributes: it.s.attributes,
+        });
+      } else if (it.kind === 'event') {
+        view.event(
+          it.s.spanId,
+          it.ev.name,
+          eventToolName(it.ev.name, it.ev.body?.tool, typeMap),
+          eventText(it.ev),
+          it.ev.body?.ok !== false,
+          eventFull(it.ev),
+        );
+      } else {
+        view.end({
+          id: it.s.spanId,
+          ms: it.s.endedAt - it.s.startedAt,
+          endedAt: it.s.endedAt,
+          usage: usageOf(it.s),
+          status: it.s.status,
+          error: it.s.error,
+          arg: '',
+        });
+      }
     }
-  }
+  };
 
-  // 根 span 还没结束（`span.end` 尚未到达）⇒ **不收尾**：`finish()` 会把根标成已完成
-  // （● + 耗时），而这棵树其实还在长 —— 在飞时看到「已完成」是假事实。留 ◌ 才对。
-  // 收尾的整棵 trace 根必有 `endedAt`，所以这条分支只对「在飞 / 截断」的树生效。
-  if (root.endedAt != null) view.finish(root.endedAt - root.startedAt, root.status, root.error);
+  const rootRaw = String(root.name || 'run');
+  /* 整个回放（含 reset 与收尾）包在**一次**重画里（2026-11-13）：此前每个动作都触发整树
+     重建 ⇒ O(N²)（实测 600 span = 1801 次全树重建、假 DOM 就 172ms）。语义不变 ——
+     渲染仍是全量重建（那是折叠态必须外部持有的原因），只是把 N 次压成 1 次。
+     ⚠️ `reset` 也必须在批内：它在批外会先白画一遍空树，收尾再画一遍 ⇒ 2 次。
+     没有 `batch` 的宿主（自定义 view 对象 / 老版本）退回逐条画，行为不变。 */
+  const replayWithFinish = () => {
+    // 框架的 run 根名可能是 runName（如 'app'）或已是 'run · x' 形态，避免重复前缀。
+    // 第二个参数是**真 spanId**：根上的事件（score / trace.truncated / approval.decided）
+    // 按 spanId 投递，只登记字面量 'root' 会让它们全部静默丢失（见 view.js 的 reset）。
+    // 第三个是**根起点**：时间轴按它归一化（缺了就整棵树不画条）。
+    // 第四个是**根的 attributes**：`model` / `system.version` / `tools.names` 只写在根上，
+    // 而根行由 reset 建、不走 `view.start()` —— 不在这里递进去，这些键树上一格都没有。
+    view.reset(
+      rootRaw.startsWith('run') ? rootRaw : 'run · ' + rootRaw,
+      String(root.spanId || ''),
+      typeof root.startedAt === 'number' ? root.startedAt : undefined,
+      root.attributes,
+    );
+    replay();
+    /* 根 span 还没结束（`span.end` 尚未到达）⇒ **不收尾**：`finish()` 会把根标成已完成
+       （● + 耗时），而这棵树其实还在长 —— 在飞时看到「已完成」是假事实。留 ◌ 才对。
+       收尾的整棵 trace 根必有 `endedAt`，所以这条分支只对「在飞 / 截断」的树生效。 */
+    if (root.endedAt != null) view.finish(root.endedAt - root.startedAt, root.status, root.error);
+  };
+  if (typeof view.batch === 'function') view.batch(replayWithFinish);
+  else replayWithFinish();
   return true;
 }

package/dist/inspector/trace-view.bundle.js

@@ -586,6 +586,24 @@ function createTraceView(rootEl, opts = {}) {
   let traceRoot = null;
   const spanMap = new Map();
   const usageAcc = { input: 0, output: 0, cacheRead: 0, cacheCreation: 0 };
+  /* 批量渲染（2026-11-13）。此前每来一条 span 动作就整树重建一次 ⇒ `playTrace` 是 O(N²)：
+     实测 50 span 触发 151 次全树重建、600 span 触发 1801 次（假 DOM 就 172ms），而在飞时
+     `renderLive` 每个 rAF 还会再调一次 `playTrace`。这不是「慢一点」，是长跑时面板直接卡死。
+     语义不变：**渲染仍是全量重建**（那是折叠态必须外部持有的原因），只是把「一批动作之间
+     的 N 次重建」压成「结束后一次」。
+     ⚠️ 嵌套是安全的（计数器），且批内抛错也会在 finally 里补画 —— 否则异常路径之后整棵树
+     停在中间状态，而下一条事件又会被 `dirty` 吞掉。 */
+  let batchDepth = 0;
+  let batchDirty = false;
+  /* 树内检索（2026-11-13）：**不改结构**，只给命中的行加类 + 提供「跳到下一处」。
+     为什么不裁剪节点：树形是「谁挂在谁下面」的事实，隐藏父节点会让子节点看起来属于别人；
+     而裁剪后「有多少条被藏起来了」又要另一处交代。高亮 + 跳转在不改事实的前提下解决
+     「一百个 span 里找那一条」。 */
+  let query = '';
+  let hitIndex = -1;
+  /* 时间轴开关（2026-11-13）：轨道占 72px，窄面板里是从名字里抢的 ⇒ 允许关掉。
+     默认开 —— 它是「谁和谁并行 / 8 秒被谁吃掉」唯一的落点，而那条信息此前完全没有。 */
+  let timeline = true;
   /* 展开态的行 key 集合 + 事件 key 发号器。两者都必须活在 renderTrace 之外：
      渲染是【全量重建】（rootEl.innerHTML = ''），状态放进 DOM 或渲染过程里就活不过下一次事件。 */
   const expanded = new Set();
@@ -620,8 +638,55 @@ function createTraceView(rootEl, opts = {}) {
     }
   }
 
+  /** 把一批渲染动作压成一次重画（见 `batchDepth` 的头注）。没在批里就直接画。 */
   function renderTrace() {
+    if (batchDepth > 0) {
+      batchDirty = true;
+      return;
+    }
+    drawTree();
+  }
+
+  function batch(fn) {
+    batchDepth += 1;
+    try {
+      fn();
+    } finally {
+      batchDepth -= 1;
+      // 批内一次都没标脏（例如只读了状态）⇒ 不白画一遍
+      if (batchDepth === 0 && batchDirty) {
+        batchDirty = false;
+        drawTree();
+      }
+    }
+  }
+
+  /** 检索：这一行的文本是否命中。空查询恒 false（「没在搜」不等于「全都命中」） */
+  function hits(texts) {
+    if (!query) return false;
+    const q = query.toLowerCase();
+    for (const t of texts) if (t && String(t).toLowerCase().includes(q)) return true;
+    return false;
+  }
+
+  function drawTree() {
     rootEl.innerHTML = '';
+    hitIndex = -1;
+    // 还没 reset 过（视图刚建出来）：清空即返回。setTimeline / setQuery 可能先于第一棵树
+    // 被调用 —— 没有这一条，`traceRoot.order` 会抛，而调用方只是在设一个开关。
+    if (!traceRoot) return;
+    /* 时间轴的归一化基准：根 span 的起点与整棵树的终点。两者缺一就**不画条**
+       （手写 trace / 官网模拟回放没有时间戳 —— 画一条人人占满的条比不画更误导）。 */
+    const t0 = traceRoot && typeof traceRoot.startedAt === 'number' ? traceRoot.startedAt : null;
+    let tMax = t0;
+    if (t0 !== null) {
+      for (const n of spanMap.values()) {
+        const e = typeof n.endAt === 'number' ? n.endAt : n.startedAt;
+        if (typeof e === 'number' && e > tMax) tMax = e;
+      }
+    }
+    const total = t0 !== null && tMax !== null ? Math.max(0, tMax - t0) : 0;
+
     const rows = [];
     /* 每个节点下【事件】与【子 span】按发生顺序混排：tool.input 先于它触发的 capability span、
        tool.output 后于它，这个先后本身就是语义，不能拍平成一类。 */
@@ -644,6 +709,11 @@ function createTraceView(rootEl, opts = {}) {
         const open = expanded.has(ev.key);
         const row = el('div', 'tr-row tr-ev' + (ev.ok === false ? ' error' : ''));
         row.dataset.ev = ev.type;
+        /* 检索只扫摘要与类型/工具名，**不扫完整正文**：`full` 常见 10KB 级，每帧每行
+             indexOf 一遍会让「搜索」本身成为掉帧的原因（600 行 × 10KB ≈ 6MB/帧）。
+             2000 字符以内才扫 —— 那个尺度上全文搜索才有意义（再长就是文档，不是一行）。 */
+        const fullShort = typeof ev.full === 'string' && ev.full.length <= 2000 ? ev.full : '';
+        if (hits([ev.type, ev.tool, ev.text, fullShort])) row.className += ' tr-hit';
         row.dataset.capability = capabilityTypeOf(ev.tool);
         row.appendChild(el('span', 'tr-pre', branch));
         row.appendChild(el('span', 'tr-evv', ev.type === 'tool.output' ? '◂' : '▸'));
@@ -693,6 +763,18 @@ function createTraceView(rootEl, opts = {}) {
       row.dataset.kind = node.kind;
       const ut = node.kind === 'capability' ? capabilityTypeOf(node.name) : '';
       if (ut) row.dataset.capability = ut;
+      const attrKeys = node.attributes ? Object.keys(node.attributes) : [];
+      const attrKey = 'sp:' + node.id;
+      const attrOpen = attrKeys.length > 0 && expanded.has(attrKey);
+      /* 命中面：名字 / 入参摘要 / 错误原文 / **已展开的**属性值。
+         属性只在展开时才算：折叠态那些值本来就没显示 —— 高亮一个看不见的东西只会让
+         「N 处匹配」对不上眼睛看到的。 */
+      const attrVals = attrOpen
+        ? Object.values(node.attributes).map((v) => (typeof v === 'string' ? v : String(v)))
+        : [];
+      if (hits([node.name, node.arg, bad ? node.error?.message : '', ...attrVals])) {
+        row.className += ' tr-hit';
+      }
       row.appendChild(el('span', 'tr-pre', branch));
       row.appendChild(el('span', 'tr-dot', node.done ? (bad ? '✕' : '●') : '◌'));
       if (ut) row.appendChild(el('span', 'tr-ico', CAP_ICO[ut]));
@@ -714,10 +796,46 @@ function createTraceView(rootEl, opts = {}) {
         if (bad) parts.push(node.error?.type || 'error');
         meta = parts.join(' · ');
       } else meta = '…';
+      /* 时间轴条（2026-11-13）：按 run 的总时长归一化 —— 「8 秒被谁吃掉 / 谁和谁并行」
+         只有结构视角是看不见的。放在 meta **之前**并自己吃掉 `margin-left: auto`，
+         让「耗时读数 — 轨道」贴在一起（两者说的是同一件事）。根行不画：它恒占满全宽。 */
+      if (!isRoot && timeline && t0 !== null && total > 0 && typeof node.startedAt === 'number') {
+        const offset = node.startedAt - t0;
+        const left = Math.min(1, Math.max(0, offset / total));
+        const dur = node.done && node.ms > 0 ? node.ms : Math.max(total - offset, 0);
+        const width = Math.min(1 - left, dur / total);
+        const track = el('span', 'tr-tl');
+        const bar = el('span', 'tr-tl-bar');
+        // 几何只能走 style（宽度是**数据**，不是样式选择）；两端都 clamp 过 ⇒ 不会溢出轨道
+        bar.style.cssText = `left:${(left * 100).toFixed(2)}%;width:${Math.max(width * 100, 0.6).toFixed(2)}%`;
+        track.appendChild(bar);
+        track.title = `起点 ${Math.round(offset)}ms · 时长 ${Math.round(dur)}ms`;
+        row.dataset.tl = '1';
+        row.appendChild(track);
+      }
       const metaEl = el('span', 'tr-meta', meta);
       if (bad && node.error?.message) metaEl.title = node.error.message;
       row.appendChild(metaEl);
+      /* span 属性（2026-11-13）：`model` / `system.version` / `tools.names` / `retry.attempt` /
+         `handoff.*` / `guardrail.*` 全在 attributes 里，此前树上一格都不显示 ——
+         「这次是不是提示词版本没换」「是不是重试了三次」只能靠猜。
+         块体复用 `full-view.js`（纯 DOM 构造，不再写第二套渲染）。 */
+      if (attrKeys.length > 0) {
+        row.dataset.expandable = '1';
+        row.appendChild(el('span', 'tr-caret', attrOpen ? '▾' : '▸'));
+        row.addEventListener('click', () => {
+          if (!hasSelection()) toggleExpand(attrKey);
+        });
+      }
       rootEl.appendChild(row);
+      if (attrOpen) {
+        let fold = folds.get(attrKey);
+        if (!fold) {
+          fold = new Map();
+          folds.set(attrKey, fold);
+        }
+        rootEl.appendChild(createFullView(node.attributes, { fold }));
+      }
       // 失败原文必须**看得见** —— 只塞进 title（hover 才显）等于没显示。首次运行最常见的失败
       // （没配 API key）就靠这一行定位；单起一行，不去挤占 nowrap 的 span 行。
       if (bad && node.error?.message) {
@@ -743,10 +861,19 @@ function createTraceView(rootEl, opts = {}) {
     usageEls.cost.textContent = '$' + cost.toFixed(4);
   }
 
-  /** 开树。rootName 为 run 根显示名（如 'run · 审查一份文档'） */
-  function reset(rootName) {
+  /**
+   * 开树。rootName 为 run 根显示名（如 'run · 审查一份文档'）。
+   *
+   * `rootId` = **框架给这个根 span 的真 `spanId`**（`fromTrace.js` 的 `playTrace` 会传）。
+   * 为什么必须传：根节点上的事件（`score` / `trace.truncated` / `approval.decided`）由
+   * `event(span.spanId, …)` 投递，而旧实现只把根登记在字面量 `'root'` 上 ⇒ `spanMap.get`
+   * 落空 ⇒ `event()` 静默 return。症状不是报错，是**评估结论与截断警告整类消失**，而子 span
+   * 的事件一切正常（排查时最容易被判成「框架没记」）。字面量 `'root'` 仍登记：官网
+   * playground 的模拟脚本用它当根 id，两个键指向同一节点，零成本。
+   */
+  function reset(rootName, rootId, startedAt, attributes) {
     traceRoot = {
-      id: 'root',
+      id: rootId || 'root',
       kind: 'run',
       name: rootName || 'run',
       children: [],
@@ -754,10 +881,23 @@ function createTraceView(rootEl, opts = {}) {
       order: [],
       done: false,
       ms: 0,
+      /* 时间轴的基准（2026-11-13）：根 span 的起点。缺省 null ⇒ 整棵树不画条
+         （手写 trace / 官网模拟回放没有时间戳，画一条人人占满的条比不画更误导）。 */
+      startedAt: typeof startedAt === 'number' ? startedAt : null,
+      endAt: null,
+      /* 根 span 的属性（2026-11-13）：`model` / `system.version` / `tools.names` /
+         `prompts.versions` / `stop_reason` **只写在根上**。根行不经过 `start()`
+         （它由 reset 建），所以不在这里接一手，这些键在面板上就一格都看不到 ——
+         「这次是不是提示词版本没换」只能去翻 JSON。空对象当没有。 */
+      attributes:
+        attributes && typeof attributes === 'object' && Object.keys(attributes).length > 0
+          ? attributes
+          : null,
       usage: { input: 0, output: 0 },
     };
     spanMap.clear();
     spanMap.set('root', traceRoot);
+    if (rootId && rootId !== 'root') spanMap.set(rootId, traceRoot);
     expanded.clear(); // 展开态属于上一棵树：reset 开新树时一并清掉
     folds.clear(); // 块内折叠同理：留着只会在下一次点开时出现"莫名已折叠"的状态
     usageAcc.input = 0;
@@ -778,6 +918,9 @@ function createTraceView(rootEl, opts = {}) {
       order: [],
       done: false,
       ms: 0,
+      startedAt: typeof s.startedAt === 'number' ? s.startedAt : null,
+      endAt: null,
+      attributes: s.attributes && typeof s.attributes === 'object' ? s.attributes : null,
       status: 'ok',
       error: null,
       usage: null,
@@ -817,6 +960,14 @@ function createTraceView(rootEl, opts = {}) {
     if (!node) return;
     node.done = true;
     node.ms = s.ms || 0;
+    /* 终点优先取框架的真 `endedAt`（时间轴的右端）；没有就按起点 + 时长推。
+       两者都没有（手写 trace）⇒ 留 null，那一段不画条。 */
+    node.endAt =
+      typeof s.endedAt === 'number'
+        ? s.endedAt
+        : typeof node.startedAt === 'number'
+          ? node.startedAt + node.ms
+          : null;
     node.status = s.status || 'ok';
     node.error = s.error || null;
     if (s.arg) node.arg = s.arg;
@@ -843,6 +994,9 @@ function createTraceView(rootEl, opts = {}) {
     if (!traceRoot) return;
     traceRoot.done = true;
     traceRoot.ms = ms;
+    if (typeof traceRoot.startedAt === 'number' && typeof ms === 'number') {
+      traceRoot.endAt = traceRoot.startedAt + ms;
+    }
     // run 失败时根 span 也要标红：原先 status 恒为 ok，错误只体现在子 span 上
     traceRoot.status = status || 'ok';
     traceRoot.error = error || null;
@@ -850,14 +1004,76 @@ function createTraceView(rootEl, opts = {}) {
     renderTrace();
   }
 
+  /** 当前命中行（`.tr-hit`）。宿主没有 `querySelectorAll`（stub / 极简 DOM）时返回空集 */
+  function hitRows() {
+    try {
+      if (typeof rootEl.querySelectorAll !== 'function') return [];
+      return Array.from(rootEl.querySelectorAll('.tr-hit'));
+    } catch {
+      return [];
+    }
+  }
+
+  /** 加/去一个类名（不依赖 classList：stub DOM 未必实现它） */
+  function setFlag(node, cls, on) {
+    const parts = String(node.className || '')
+      .split(/\s+/)
+      .filter((c) => c && c !== cls);
+    if (on) parts.push(cls);
+    node.className = parts.join(' ');
+  }
+
   return {
     reset,
     start,
     event,
     end,
     finish,
+    /** 把一批动作压成一次重画（`playTrace` 必用；宿主自己批量喂时也可以用） */
+    batch,
     render: renderTrace,
+    /**
+     * 树内检索：**只高亮 + 跳转，不改结构**（理由见 `query` 的头注）。返回命中行数。
+     * 空串 = 结束检索（清掉所有高亮）。
+     */
+    setQuery(q) {
+      const next = typeof q === 'string' ? q.trim() : '';
+      if (next === query) return hitRows().length;
+      query = next;
+      renderTrace();
+      return hitRows().length;
+    },
+    get hitCount() {
+      return hitRows().length;
+    },
+    /**
+     * 跳到下一处命中（`dir < 0` 向上），返回 **1 基序号**；没有命中返回 0。
+     * 越界绕回：搜索框里按 Enter 一路按到底再回到第一处，比「按不动了」更符合预期。
+     */
+    nextHit(dir = 1) {
+      const list = hitRows();
+      if (list.length === 0) return 0;
+      hitIndex = (hitIndex + (dir > 0 ? 1 : -1) + list.length) % list.length;
+      const cur = list[hitIndex];
+      for (const r of list) setFlag(r, 'tr-hit-cur', r === cur);
+      try {
+        cur.scrollIntoView?.({ block: 'center' });
+      } catch {
+        /* 没有滚动能力（stub / 老浏览器）：序号仍然对，只是没把行带进视野 */
+      }
+      return hitIndex + 1;
+    },
     setUsage: renderUsage,
+    /** 时间轴开关（默认开）。关掉只是不画轨道，数据与命中都不受影响 */
+    setTimeline(on) {
+      const next = on !== false;
+      if (next === timeline) return;
+      timeline = next;
+      renderTrace();
+    },
+    get timeline() {
+      return timeline;
+    },
     /** 换单价（如真实模式切服务商）：null 表示无公开单价 → 成本显示为 — */
     setPrice(p) {
       price = p ?? null;
@@ -1019,45 +1235,72 @@ function playTrace(view, trace) {
   }
   items.sort((a, b) => a.t - b.t || a.ord - b.ord || a.d - b.d || a.seq - b.seq);
 
-  const rootRaw = String(root.name || 'run');
-  // 框架的 run 根名可能是 runName（如 'app'）或已是 'run · x' 形态，避免重复前缀
-  view.reset(rootRaw.startsWith('run') ? rootRaw : 'run · ' + rootRaw);
-
-  for (const it of items) {
-    if (it.kind === 'start') {
-      if (it.s === root) continue; // 根由 reset 建，不重复开
-      view.start({
-        id: it.s.spanId,
-        parent: it.s.parentSpanId,
-        kind: it.s.kind,
-        name: displayName(it.s),
-        arg: '',
-      });
-    } else if (it.kind === 'event') {
-      view.event(
-        it.s.spanId,
-        it.ev.name,
-        eventToolName(it.ev.name, it.ev.body?.tool, typeMap),
-        eventText(it.ev),
-        it.ev.body?.ok !== false,
-        eventFull(it.ev),
-      );
-    } else {
-      view.end({
-        id: it.s.spanId,
-        ms: it.s.endedAt - it.s.startedAt,
-        usage: usageOf(it.s),
-        status: it.s.status,
-        error: it.s.error,
-        arg: '',
-      });
+  /** 把归一好的动作逐条喂给视图（不含 reset / finish —— 那两个由外层一起包进批里） */
+  const replay = () => {
+    for (const it of items) {
+      if (it.kind === 'start') {
+        if (it.s === root) continue; // 根由 reset 建，不重复开
+        view.start({
+          id: it.s.spanId,
+          parent: it.s.parentSpanId,
+          kind: it.s.kind,
+          name: displayName(it.s),
+          arg: '',
+          startedAt: it.s.startedAt,
+          // 属性（model / system.version / tools.names / retry.attempt / handoff.* / …）：
+          // 树上一格都不显示的话，「这次是不是提示词版本没换」只能靠猜（2026-11-13）
+          attributes: it.s.attributes,
+        });
+      } else if (it.kind === 'event') {
+        view.event(
+          it.s.spanId,
+          it.ev.name,
+          eventToolName(it.ev.name, it.ev.body?.tool, typeMap),
+          eventText(it.ev),
+          it.ev.body?.ok !== false,
+          eventFull(it.ev),
+        );
+      } else {
+        view.end({
+          id: it.s.spanId,
+          ms: it.s.endedAt - it.s.startedAt,
+          endedAt: it.s.endedAt,
+          usage: usageOf(it.s),
+          status: it.s.status,
+          error: it.s.error,
+          arg: '',
+        });
+      }
     }
-  }
+  };
 
-  // 根 span 还没结束（`span.end` 尚未到达）⇒ **不收尾**：`finish()` 会把根标成已完成
-  // （● + 耗时），而这棵树其实还在长 —— 在飞时看到「已完成」是假事实。留 ◌ 才对。
-  // 收尾的整棵 trace 根必有 `endedAt`，所以这条分支只对「在飞 / 截断」的树生效。
-  if (root.endedAt != null) view.finish(root.endedAt - root.startedAt, root.status, root.error);
+  const rootRaw = String(root.name || 'run');
+  /* 整个回放（含 reset 与收尾）包在**一次**重画里（2026-11-13）：此前每个动作都触发整树
+     重建 ⇒ O(N²)（实测 600 span = 1801 次全树重建、假 DOM 就 172ms）。语义不变 ——
+     渲染仍是全量重建（那是折叠态必须外部持有的原因），只是把 N 次压成 1 次。
+     ⚠️ `reset` 也必须在批内：它在批外会先白画一遍空树，收尾再画一遍 ⇒ 2 次。
+     没有 `batch` 的宿主（自定义 view 对象 / 老版本）退回逐条画，行为不变。 */
+  const replayWithFinish = () => {
+    // 框架的 run 根名可能是 runName（如 'app'）或已是 'run · x' 形态，避免重复前缀。
+    // 第二个参数是**真 spanId**：根上的事件（score / trace.truncated / approval.decided）
+    // 按 spanId 投递，只登记字面量 'root' 会让它们全部静默丢失（见 view.js 的 reset）。
+    // 第三个是**根起点**：时间轴按它归一化（缺了就整棵树不画条）。
+    // 第四个是**根的 attributes**：`model` / `system.version` / `tools.names` 只写在根上，
+    // 而根行由 reset 建、不走 `view.start()` —— 不在这里递进去，这些键树上一格都没有。
+    view.reset(
+      rootRaw.startsWith('run') ? rootRaw : 'run · ' + rootRaw,
+      String(root.spanId || ''),
+      typeof root.startedAt === 'number' ? root.startedAt : undefined,
+      root.attributes,
+    );
+    replay();
+    /* 根 span 还没结束（`span.end` 尚未到达）⇒ **不收尾**：`finish()` 会把根标成已完成
+       （● + 耗时），而这棵树其实还在长 —— 在飞时看到「已完成」是假事实。留 ◌ 才对。
+       收尾的整棵 trace 根必有 `endedAt`，所以这条分支只对「在飞 / 截断」的树生效。 */
+    if (root.endedAt != null) view.finish(root.endedAt - root.startedAt, root.status, root.error);
+  };
+  if (typeof view.batch === 'function') view.batch(replayWithFinish);
+  else replayWithFinish();
   return true;
 }