@migor/cli 0.10.8 → 0.10.10

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

@@ -25,6 +25,11 @@
  *    序列化后又塞回 `content` 的工具 —— 这些值的类型是**字符串**，此前只显示成一串
  *    `{\"a\":1` 的反斜杠汤，比无缩进的 JSON 更难读。现在首尾是 `{`…`}` / `[`…`]` 且解析成功的
  *    字符串按容器铺开，并在行里打 `str→json` 标记 —— 不标出来，读者会以为工具真的返回了对象。
+ * 5. **一整篇 Markdown 的字符串正文**（2026-11-12 晚）：工具出参的另一种常见形态就是一份
+ *    SKILL.md / 错误汇总报告，类型仍是字符串 ⇒ 展开后是 `# 标题`、`|---|---|`、
+ *    `<!-- 迁移自 … -->` 的源文。本件**不**自带解析器 —— 那会是仓库里的第二份，必然与宿主
+ *    那份漂移，所以只接受宿主渲染好的元素（`opts.body`），自己负责头部
+ *    （`string · N 字符 · md` + `md` 标记）与「复制取原文」。
  *
  * ## 边界（都是「不这么做就会坏」的地方，不是口味）
  *
@@ -49,6 +54,8 @@
  *   数字/空值/布尔就是**改写工具返回的事实**。解析结果内部的字符串**不再二次解析**：
  *   一层套一层是业务里的真实现象（SSE data 里再套 JSON），逐层展开会让 10KB 变成十万个节点。
  *   表格单元格也不解析 —— 同构表已经放弃了逐层展开，单元格里放不下嵌套块。
+ * - **宿主正文不再解析**：`opts.body` 给了就**原样用**。同一段内容既渲染又铺树，读者会看到
+ *   两套互相矛盾的呈现 —— 那比不做这一档更糟。所以这条判据只有一处（`createFullView`）。
  *
  * 零依赖、纯 DOM 构造（只用 createElement / appendChild / textContent / className /
  * dataset / innerHTML=''），与 view.js 共用同一套 DOM stub 跑测试。
@@ -175,6 +182,14 @@ function jsonBadge() {
   return b;
 }
 
+/** 「这段正文被渲染过」的标记。同样**必须显眼**：Markdown 源文与渲染结果差得很远，
+ *  不标出来，读者会以为工具返回的就是排好版的样子（而它返回的是一串 `#` 与 `|`）。 */
+function mdBadge() {
+  const b = fvEl('span', 'tr-full-md', 'md');
+  b.title = '这个字符串按 Markdown 渲染（原文仍在 .tr-io 与「复制」里，一字未改）';
+  return b;
+}
+
 /** 子键的 JSON 路径：对象用 `.key`，数组用 `[i]`。根是空串，所以 `[0]` 不会变成 `.[0]` */
 function pathOf(parent, key, isArr) {
   return isArr ? `${parent}[${key}]` : parent ? `${parent}.${key}` : key;
@@ -406,48 +421,62 @@ function renderInto(ctx, v, depth, path, allowParse = true) {
 /**
  * 建一个结构化正文块。
  * @param {any} value  `ev.full` 的**原值**（不是序列化后的字符串）
- * @param {{fold?: Map<string, boolean>}} [opts]
+ * @param {{fold?: Map<string, boolean>, body?: Element}} [opts]
  *   `fold` 是**调用方持有**的折叠状态（路径 → 是否展开）。省略时本块自建一份，
  *   此时折叠状态活不过下一次「全量重建」—— 只对一次性渲染（测试、静态快照）够用。
+ *   `body` 是**宿主已经渲染好的正文**（如 Markdown）：给了就原样用，不再走缩进/折叠，
+ *   本件只负责头部（类型 / `md` 标记 / 复制）与挂载位置。
  * @returns {Element}  `.tr-full` 块；调用方负责 append 到展开行之后
  */
 function createFullView(value, opts = {}) {
   const fold = opts.fold instanceof Map ? opts.fold : new Map();
-
-  // 根是字符串 ⇒ 只有「里面装着 JSON」才会进来（调用方用 hasStructuredBody 先筛过）。
-  // 头部同时写出**两件事**：它原本是字符串（字符数）、解析后是什么规模 —— 只写后者，
-  // 读者会以为工具真的返回了对象。
-  const parsedRoot = jsonInString(value);
+  /* 宿主渲染好的正文。**判据只此一处**：给了它就不解析、不铺树 —— 否则会同时出现
+     两套呈现（宿主渲染的正文 + 本件又在旁边铺一遍原值），那比不渲染更糟。 */
+  const injected = opts.body && typeof opts.body === 'object' ? opts.body : null;
+
+  // 根是字符串 ⇒ 只有「里面装着 JSON」或「宿主认得的正文」才会进来。
+  // 头部同时写出**两件事**：它原本是字符串（字符数）、以及它是怎么被展示的 —— 只写后者，
+  // 读者会以为工具真的返回了对象 / 排好版的正文。
+  const parsedRoot = injected ? null : jsonInString(value);
   const root = parsedRoot ?? value;
   const fromJson = parsedRoot !== null;
 
   const box = fvEl('div', 'tr-full');
-  box.dataset.kind = Array.isArray(root) ? 'array' : 'object';
+  box.dataset.kind = injected ? 'md' : Array.isArray(root) ? 'array' : 'object';
 
   const head = fvEl('div', 'tr-full-head');
   const label = typeLabelOf(root);
-  head.appendChild(
-    fvEl('span', 'tr-full-type', fromJson ? `string · ${value.length} 字符 → ${label}` : label),
-  );
+  let typeText = label;
+  if (fromJson) typeText = `string · ${value.length} 字符 → ${label}`;
+  // 注入正文时不写「→ md」：紧跟其后的 `md` 标记已经说了这件事，
+  // 同一行说两遍只会让人以为其中一个另有含义（字符数才是头部真正要补的信息）
+  else if (injected) typeText = `string · ${value.length} 字符`;
+  head.appendChild(fvEl('span', 'tr-full-type', typeText));
   if (fromJson) head.appendChild(jsonBadge());
+  if (injected) head.appendChild(mdBadge());
   const copy = fvEl('span', 'tr-full-copy', '复制');
   copy.dataset.copy = '1';
-  // 字符串根复制的是**原文**（拿到手能直接喂 jq）；容器根复制的是缩进后的 JSON
+  // 字符串根复制的是**原文**（拿到手能直接喂 jq / 贴回上游）；容器根复制的是缩进后的 JSON
   copy.addEventListener('click', () =>
-    copyInto(copy, fromJson ? String(value) : safeStringify(root), '已复制'),
+    copyInto(copy, fromJson || injected ? String(value) : safeStringify(root), '已复制'),
   );
   head.appendChild(copy);
   box.appendChild(head);
 
   const body = fvEl('div', 'tr-full-body');
-  const ctx = { body, fold, repaint: null };
-  // 只重画正文（不动头部）：折叠不需要重建整棵树，滚动位置与头部反馈都留着
-  ctx.repaint = () => {
-    body.innerHTML = '';
-    // 根若是从字符串解析来的，它的子树不再二次解析（只解析一层，防嵌套放大）
-    renderInto(ctx, root, 0, '', !fromJson);
-  };
-  ctx.repaint();
+  if (injected) {
+    // 宿主正文自带排版；本件的缩进/折叠那一套对散文没有意义（它也没有「路径」可复制）
+    body.appendChild(injected);
+  } else {
+    const ctx = { body, fold, repaint: null };
+    // 只重画正文（不动头部）：折叠不需要重建整棵树，滚动位置与头部反馈都留着
+    ctx.repaint = () => {
+      body.innerHTML = '';
+      // 根若是从字符串解析来的，它的子树不再二次解析（只解析一层，防嵌套放大）
+      renderInto(ctx, root, 0, '', !fromJson);
+    };
+    ctx.repaint();
+  }
 
   box.appendChild(body);
   return box;
@@ -473,11 +502,14 @@ function createFullView(value, opts = {}) {
  * 宿主需提供的 CSS 变量：--ice --faint --text（见 trace-view.css）。
  */
 
-/* 展开态的正文有两种形状，由 `full` 的类型决定（2026-11-11，2026-11-12 扩了一档）：
+/* 展开态的正文有三种形状（2026-11-11，2026-11-12 扩了两档）：
  *   - 纯文本字符串 → 老路：`.tr-io` 里放原文，靠 `.tr-open` 换行（纯文本正文、官网模拟回放）；
  *   - 对象/数组 → 追加一个 `.tr-full` 结构化块（折叠 / 成表 / 路径复制），`.tr-io` 由 CSS 隐藏；
  *   - **装着 JSON 的字符串**（`content: "{\"rows\":[...]}"`，工具把结构序列化后塞回文本字段）
- *     → 同上一档，块头写明「string · N 字符 → object · M 项」并打 `str→json` 标记。
+ *     → 同上一档，块头写明「string · N 字符 → object · M 项」并打 `str→json` 标记；
+ *   - **一整篇 Markdown 的字符串**（工具出参就是一份 SKILL.md / 报告）→ 由宿主注入的
+ *     `opts.textBody(text)` 渲染成正文块，块头打 `md` 标记。注入是刻意的：本包是独立
+ *     发布单元，解析器只有一份（在宿主里），两边各带一份必然漂移。
  * 判据与块内完全同源（`hasStructuredBody`），「挂不挂块」与「块里画什么」因此不会跑偏。
  * 前两档并存是刻意的：纯文本那条路有 test/style.test.js 的两个不变量守着（最小宽度、caret 常显），
  * 全换成本件会让那两个守卫失去落点。 */
@@ -547,10 +579,31 @@ function createTraceView(rootEl, opts = {}) {
   let price = opts.price ?? null;
   const onUsage = opts.onUsage ?? null;
   const usageEls = opts.usage ?? null;
+  /* 字符串正文的宿主渲染器（可选）：`(text) => Element | null`。返回 null = 「不是那种
+     正文，保持原文」。本包不自带 Markdown 解析器 —— 见文件头注。 */
+  const textBody = typeof opts.textBody === 'function' ? opts.textBody : null;
 
   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();
@@ -574,8 +627,66 @@ function createTraceView(rootEl, opts = {}) {
     renderTrace();
   }
 
+  /** 宿主渲染器包一层：**只在展开时调用**（折叠态每条事件都会重画，挂在那儿等于白解析
+   *  一遍所有历史正文）；宿主抛错也不许让整棵树白屏 —— 回落原文即可。 */
+  function textBodyOf(v) {
+    if (!textBody || typeof v !== 'string') return null;
+    try {
+      return textBody(v) || null;
+    } catch {
+      return null;
+    }
+  }
+
+  /** 把一批渲染动作压成一次重画（见 `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 后于它，这个先后本身就是语义，不能拍平成一类。 */
@@ -598,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' ? '◂' : '▸'));
@@ -606,11 +722,13 @@ function createTraceView(rootEl, opts = {}) {
         // 这一格整个不渲染，别把「无工具」显示成假工具名（.tr-name 是 flex:none，.tr-io 自然占满）
         if (ev.tool) row.appendChild(el('span', 'tr-name', ev.tool));
         // 展开态用全文（ev.full），折叠态用摘要（ev.text）—— 折叠态因此与加展开之前逐字一致。
-        // `full` 是对象/数组、或**装着 JSON 的字符串**时（2026-11-11 / 2026-11-12）：`.tr-io`
-        // 仍放**原文**（结构化块挂在行后、由 CSS 隐藏本格），所以「展开拿到的是原文而不是
-        // 62 字符摘要」这条不变量原样成立。
+        // `full` 是对象/数组、装着 JSON 的字符串、或宿主认得的正文（Markdown）时
+        // （2026-11-11 / 2026-11-12）：`.tr-io` 仍放**原文**（结构化块挂在行后、由 CSS 隐藏本格），
+        // 所以「展开拿到的是原文而不是 62 字符摘要」这条不变量原样成立。
         const structured = hasStructuredBody(ev.full);
-        const fullText = structured ? rawArg(ev.full) : ev.full || '';
+        const mdBody = open && !structured ? textBodyOf(ev.full) : null;
+        const blocked = structured || mdBody !== null;
+        const fullText = blocked ? rawArg(ev.full) : ev.full || '';
         const io = el('span', 'tr-io', (open ? fullText : ev.text) || '');
         // 展开后正文已在行里，再挂一个占满整行的原生 tooltip 只会挡视线
         io.title = open ? '' : ev.text || '';
@@ -618,7 +736,7 @@ function createTraceView(rootEl, opts = {}) {
         if (ev.full) {
           row.dataset.expandable = '1'; // 可展开标记：CSS 靠它出 caret / cursor，测试靠它找行
           row.appendChild(el('span', 'tr-caret', open ? '▾' : '▸'));
-          if (open) row.className += ' tr-open' + (structured ? ' tr-structured' : '');
+          if (open) row.className += ' tr-open' + (blocked ? ' tr-structured' : '');
           row.addEventListener('click', () => {
             if (!hasSelection()) toggleExpand(ev.key);
           });
@@ -627,13 +745,15 @@ function createTraceView(rootEl, opts = {}) {
         // 结构化正文是**兄弟块**而不是 `.tr-io` 的子节点：行是 flex + nowrap，
         // 塞进去会把树的列对齐打乱；独立成块才能自己换行、自己缩进。
         // 折叠状态按事件键取一份带进去（2026-11-11 晚）：块每次重建都 new，状态不能放块里。
-        if (open && structured) {
+        // `body` 是宿主渲染好的正文（Markdown），交给同一条挂载路径：块头、复制、`.tr-io`
+        // 隐藏这些行为必须一致，否则「哪种正文」会从**外观**上分叉成两套。
+        if (open && blocked) {
           let fold = folds.get(ev.key);
           if (!fold) {
             fold = new Map();
             folds.set(ev.key, fold);
           }
-          rootEl.appendChild(createFullView(ev.full, { fold }));
+          rootEl.appendChild(createFullView(ev.full, { fold, body: mdBody }));
         }
         return;
       }
@@ -643,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]));
@@ -664,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) {
@@ -693,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: [],
@@ -704,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;
@@ -728,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,
@@ -767,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;
@@ -793,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;
@@ -800,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;
@@ -969,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;
 }