@migor/cli 0.10.2 → 0.10.4

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

@@ -0,0 +1,694 @@
+/* @migor/trace-view —— 单文件 bundle（由 scripts/bundle.mjs 从 src/ 自动生成，请勿手改）。
+ * 用途：`agentia view` 出的单文件自包含 HTML 内联本文件（无外链 / 离线可开 / 可转发）。
+ * 真源仍是 src/；改渲染逻辑请改那里再跑 build。零依赖、纯 ESM。 */
+
+/* ===== src/view.js ===== */
+/* Agentia trace 调用树渲染器 —— 数据无关、零依赖。
+ *
+ * 只认五个动作：reset 开树 / start 开 span / event 记事件 / end 收 span / finish 收 run。
+ * 谁喂它都行：官网 playground 的模拟回放脚本，或 fromTrace.js 的 playTrace（真实 Trace）。
+ *
+ * 视觉语言与语义（逐字取自 packages/website/src/scripts/playground.js，行为不变）：
+ *   - 事件行（tool.input / tool.output）没有状态圈、没有耗时，比 span 行更轻；
+ *   - 事件与子 span 按发生顺序混排（input 先于它触发的 capability span、output 后于它）——
+ *     这个先后本身就是语义，不能拍平成一类；
+ *   - 四类能力标识符（⚙ tool / ◆ skill / ¶ prompt / ⊕ subagent）只靠字形区分、不上类型色。
+ *
+ * 展开：折叠态**一字不变**（省略号收敛，事件行比 span 行更轻），点事件行可展开看**完整正文**。
+ * 展开状态存在渲染之外（每次事件都会全量重建 DOM），否则实时 run 里刚点开的行会在下一条事件
+ * 到来时自己合上。数据侧「行内摘要」与「展开全文」是两个字段：`text` 是摘要（入参经 fmtArg
+ * 砍到 62 字符），`full` 才是原文 —— 只有全文能撑起「调试时看工具结果」这件事。
+ *
+ * 宿主需提供的 CSS 变量：--ice --faint --text（见 trace-view.css）。
+ */
+
+const CAP_ICO = { tool: '⚙', skill: '◆', prompt: '¶', subagent: '⊕' };
+
+/** 能力类型取自名字前缀（tool: / skill: / prompt: / subagent:） */
+function capabilityTypeOf(name) {
+  const t = String(name || '').split(':')[0];
+  return CAP_ICO[t] ? t : '';
+}
+
+const fmtNum = (n) => n.toLocaleString('en-US');
+const fmtMs = (ms) => (ms >= 1000 ? (ms / 1000).toFixed(2) + 's' : ms + 'ms');
+
+/* span 入参摘要：写进 trace 行，否则同名 capability（如两次 tool:get_weather）无法区分 */
+function fmtArg(v) {
+  if (v == null) return '';
+  let s;
+  if (typeof v === 'object') {
+    const keys = Object.keys(v);
+    if (!keys.length) return ''; // 无入参就不显示，避免行里多一个 "{}"
+    s =
+      '{ ' +
+      keys
+        .slice(0, 4)
+        .map((k) => {
+          let sv = typeof v[k] === 'object' ? JSON.stringify(v[k]) : String(v[k]);
+          if (sv.length > 22) sv = sv.slice(0, 21) + '…';
+          return k + ': ' + sv;
+        })
+        .join(', ') +
+      (keys.length > 4 ? ', …' : '') +
+      ' }';
+  } else s = String(v);
+  return s.length > 62 ? s.slice(0, 61) + '…' : s;
+}
+
+/* span 入参**原文** —— fmtArg 的对偶：摘要给折叠态，原文给展开态。
+ * 两者必须定义在同一处：哪个宿主自己搓一个「原文」，「展开」就会在那里退回摘要
+ * （点开什么都没多出来），而两个宿主共用这一份渲染器，正是为了不让这种漂移发生。 */
+function rawArg(v) {
+  if (v == null) return '';
+  if (typeof v === 'string') return v;
+  try {
+    return JSON.stringify(v) ?? String(v);
+  } catch {
+    return String(v);
+  }
+}
+
+function el(tag, cls, text) {
+  const node = document.createElement(tag);
+  if (cls) node.className = cls;
+  if (text !== undefined) node.textContent = text;
+  return node;
+}
+
+/**
+ * 建一个绑定到 rootEl 的 trace 视图。
+ * opts.price   = { input, output }（$/M tokens）或 null（无公开单价则不估算成本）
+ * opts.usage   = { in, out, cost } 三个 DOM 节点（可选；给了才更新计数器）
+ * opts.onUsage = (acc) => void（可选；每次累计后回调，便于宿主自定义展示）
+ */
+function createTraceView(rootEl, opts = {}) {
+  let price = opts.price ?? null;
+  const onUsage = opts.onUsage ?? null;
+  const usageEls = opts.usage ?? null;
+
+  let traceRoot = null;
+  const spanMap = new Map();
+  const usageAcc = { input: 0, output: 0, cacheRead: 0, cacheCreation: 0 };
+  /* 展开态的行 key 集合 + 事件 key 发号器。两者都必须活在 renderTrace 之外：
+     渲染是【全量重建】（rootEl.innerHTML = ''），状态放进 DOM 或渲染过程里就活不过下一次事件。 */
+  const expanded = new Set();
+  let evSeq = 0;
+
+  /** 正在选文本时不要收起/展开 —— 鼠标拖选到行外松手会补一次 click，否则选完就自己合上了 */
+  function hasSelection() {
+    try {
+      return String(globalThis.getSelection?.() ?? '') !== '';
+    } catch {
+      return false;
+    }
+  }
+
+  function toggleExpand(key) {
+    if (expanded.has(key)) expanded.delete(key);
+    else expanded.add(key);
+    renderTrace();
+  }
+
+  function renderTrace() {
+    rootEl.innerHTML = '';
+    const rows = [];
+    /* 每个节点下【事件】与【子 span】按发生顺序混排：tool.input 先于它触发的 capability span、
+       tool.output 后于它，这个先后本身就是语义，不能拍平成一类。 */
+    (function walk(node, prefix, isLast, isRoot) {
+      rows.push({ node, prefix, isRoot, last: isLast, ev: null });
+      const items = node.order || [];
+      items.forEach((it, i) => {
+        const last = i === items.length - 1;
+        const next = isRoot ? '' : prefix + (isLast ? '   ' : '│  ');
+        if (it.t === 'span') walk(it.n, next, last, false);
+        else rows.push({ node, prefix: next, isRoot: false, last, ev: it.e });
+      });
+    })(traceRoot, '', true, true);
+
+    rows.forEach(({ node, prefix, isRoot, last, ev }) => {
+      const branch = isRoot ? '' : prefix + (last ? '└─ ' : '├─ ');
+
+      /* 事件行：没有 status 圈、没有耗时、不参与 usage 计数，只带入参/出参摘要 */
+      if (ev) {
+        const open = expanded.has(ev.key);
+        const row = el('div', 'tr-row tr-ev' + (ev.ok === false ? ' error' : ''));
+        row.dataset.ev = ev.type;
+        row.dataset.capability = capabilityTypeOf(ev.tool);
+        row.appendChild(el('span', 'tr-pre', branch));
+        row.appendChild(el('span', 'tr-evv', ev.type === 'tool.output' ? '◂' : '▸'));
+        row.appendChild(el('span', 'tr-evtype', ev.type));
+        // 非 tool.* 事件（usage.unpriced / llm.retry / budget.* / context.budget）没有工具名 ——
+        // 这一格整个不渲染，别把「无工具」显示成假工具名（.tr-name 是 flex:none，.tr-io 自然占满）
+        if (ev.tool) row.appendChild(el('span', 'tr-name', ev.tool));
+        // 展开态用全文（ev.full），折叠态用摘要（ev.text）—— 折叠态因此与加展开之前逐字一致
+        const io = el('span', 'tr-io', (open ? ev.full : ev.text) || '');
+        // 展开后正文已在行里，再挂一个占满整行的原生 tooltip 只会挡视线
+        io.title = open ? '' : ev.text || '';
+        row.appendChild(io);
+        if (ev.full) {
+          row.dataset.expandable = '1'; // 可展开标记：CSS 靠它出 caret / cursor，测试靠它找行
+          row.appendChild(el('span', 'tr-caret', open ? '▾' : '▸'));
+          if (open) row.className += ' tr-open';
+          row.addEventListener('click', () => {
+            if (!hasSelection()) toggleExpand(ev.key);
+          });
+        }
+        rootEl.appendChild(row);
+        return;
+      }
+
+      const bad = node.done && node.status === 'error';
+      const row = el('div', 'tr-row' + (node.done ? '' : ' running') + (bad ? ' error' : ''));
+      row.dataset.kind = node.kind;
+      const ut = node.kind === 'capability' ? capabilityTypeOf(node.name) : '';
+      if (ut) row.dataset.capability = ut;
+      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]));
+      row.appendChild(el('span', 'tr-name', node.name));
+      if (node.arg) {
+        const arg = el('span', 'tr-arg', node.arg);
+        arg.title = node.arg;
+        row.appendChild(arg);
+      }
+      let meta;
+      if (node.done) {
+        const parts = [fmtMs(node.ms)];
+        if (node.usage) {
+          parts.push(fmtNum(node.usage.input + node.usage.output) + ' tok');
+          const cr = node.usage.cacheRead || 0;
+          const cc = node.usage.cacheCreation || 0;
+          if (cr || cc) parts.push('cache ↑' + fmtNum(cr) + ' ↓' + fmtNum(cc));
+        }
+        if (bad) parts.push(node.error?.type || 'error');
+        meta = parts.join(' · ');
+      } else meta = '…';
+      const metaEl = el('span', 'tr-meta', meta);
+      if (bad && node.error?.message) metaEl.title = node.error.message;
+      row.appendChild(metaEl);
+      rootEl.appendChild(row);
+      // 失败原文必须**看得见** —— 只塞进 title（hover 才显）等于没显示。首次运行最常见的失败
+      // （没配 API key）就靠这一行定位；单起一行，不去挤占 nowrap 的 span 行。
+      if (bad && node.error?.message) {
+        const errLine = el('div', 'tr-errm');
+        errLine.appendChild(el('span', 'tr-pre', branch + '  '));
+        errLine.appendChild(el('span', 'tr-errm-msg', node.error.message));
+        rootEl.appendChild(errLine);
+      }
+    });
+  }
+
+  function renderUsage(acc) {
+    if (onUsage) onUsage(acc);
+    if (!usageEls) return;
+    if (usageEls.in) usageEls.in.textContent = fmtNum(acc.input);
+    if (usageEls.out) usageEls.out.textContent = fmtNum(acc.output);
+    if (!usageEls.cost) return;
+    if (price == null || price.input == null || price.output == null) {
+      usageEls.cost.textContent = '—'; // 无公开单价的端点不做估算（如 DeepSeek）
+      return;
+    }
+    const cost = (acc.input * price.input + acc.output * price.output) / 1e6;
+    usageEls.cost.textContent = '$' + cost.toFixed(4);
+  }
+
+  /** 开树。rootName 为 run 根显示名（如 'run · 审查一份文档'） */
+  function reset(rootName) {
+    traceRoot = {
+      id: 'root',
+      kind: 'run',
+      name: rootName || 'run',
+      children: [],
+      events: [],
+      order: [],
+      done: false,
+      ms: 0,
+      usage: { input: 0, output: 0 },
+    };
+    spanMap.clear();
+    spanMap.set('root', traceRoot);
+    expanded.clear(); // 展开态属于上一棵树：reset 开新树时一并清掉
+    usageAcc.input = 0;
+    usageAcc.output = 0;
+    usageAcc.cacheRead = 0;
+    usageAcc.cacheCreation = 0;
+    renderTrace();
+  }
+
+  function start(s) {
+    const node = {
+      id: s.id,
+      kind: s.kind,
+      name: s.name,
+      arg: s.arg || '',
+      children: [],
+      events: [],
+      order: [],
+      done: false,
+      ms: 0,
+      status: 'ok',
+      error: null,
+      usage: null,
+    };
+    spanMap.set(s.id, node);
+    const parent = spanMap.get(s.parent) || traceRoot;
+    parent.children.push(node);
+    parent.order.push({ t: 'span', n: node });
+    renderTrace();
+  }
+
+  /* span 事件：框架把普通工具 / @Prompt 调用记成【turn 上的事件】，不给它们建 capability span
+     （只有 skill / subagent 会 recorder.begin('capability', …)，见 engine/loop.ts）。
+     events 与 order 并存：events 是数据、order 负责与子 span 的先后顺序。
+
+     `text` = 行内摘要，`full` = 展开看的原文（省略时同 text —— 出参与多数事件本来就是原文，
+     只有 tool.input 的摘要被 fmtArg 砍过，调用方需要显式给 full）。
+     `key` 是展开状态的稳定标识：事件对象跨全量重建存活，所以键也稳定。 */
+  function event(id, type, tool, text, ok, full) {
+    const node = spanMap.get(id);
+    if (!node) return;
+    const e = {
+      type,
+      tool,
+      text,
+      ok: ok !== false,
+      full: full === undefined ? text : full,
+      key: 'ev' + ++evSeq,
+    };
+    node.events.push(e);
+    node.order.push({ t: 'ev', e });
+    renderTrace();
+  }
+
+  function end(s) {
+    const node = spanMap.get(s.id);
+    if (!node) return;
+    node.done = true;
+    node.ms = s.ms || 0;
+    node.status = s.status || 'ok';
+    node.error = s.error || null;
+    if (s.arg) node.arg = s.arg;
+    node.usage = s.usage
+      ? {
+          input: s.usage.input || 0,
+          output: s.usage.output || 0,
+          cacheRead: s.usage.cacheRead || 0,
+          cacheCreation: s.usage.cacheCreation || 0,
+        }
+      : null;
+    // 计数器只累加 llm.turn（capability span 的 usage 是子 span 聚合，重复计入会双算）
+    if (s.usage && node.kind === 'llm.turn') {
+      usageAcc.input += node.usage.input;
+      usageAcc.output += node.usage.output;
+      usageAcc.cacheRead += node.usage.cacheRead;
+      usageAcc.cacheCreation += node.usage.cacheCreation;
+      renderUsage(usageAcc);
+    }
+    renderTrace();
+  }
+
+  function finish(ms, status, error) {
+    if (!traceRoot) return;
+    traceRoot.done = true;
+    traceRoot.ms = ms;
+    // run 失败时根 span 也要标红：原先 status 恒为 ok，错误只体现在子 span 上
+    traceRoot.status = status || 'ok';
+    traceRoot.error = error || null;
+    traceRoot.usage = { input: usageAcc.input, output: usageAcc.output };
+    renderTrace();
+  }
+
+  return {
+    reset,
+    start,
+    event,
+    end,
+    finish,
+    render: renderTrace,
+    setUsage: renderUsage,
+    /** 换单价（如真实模式切服务商）：null 表示无公开单价 → 成本显示为 — */
+    setPrice(p) {
+      price = p ?? null;
+      renderUsage(usageAcc);
+    },
+    get usage() {
+      return usageAcc;
+    },
+  };
+}
+
+/* ===== src/fromTrace.js ===== */
+/* 把框架的 Trace.spans[] 归一成渲染动作，喂给 createTraceView 建出的视图。
+ *
+ * 框架的 trace 是【扁平 spans[] + parentSpanId】，渲染器要的是【嵌套树 + 每个节点内
+ * 事件与子 span 按发生顺序混排的 order】。本文件就是那座桥 —— 同一份渲染器因此
+ * 既能吃官网的模拟回放，也能吃真实 run 的 trace。
+ *
+ * 归一规则：
+ *   1. 全局时间线：每个 span 的 start / end 与它的每个 event 汇到一起，按时间排序。
+ *      tie-break：同一毫秒 start(0) → event(1) → end(2)，且 start 按深度浅的在前 ——
+ *      保证父 span 先于子 span 打开、tool.input 落在它所属 turn 打开之后。
+ *   2. 显示名合成：框架的 capability span 名是【裸名】（类型记在 attributes，如 {subagent:'x'}），
+ *      这里补成 `type:name`，与渲染器的四类标识符对齐；事件里的工具名若是某个 capability span
+ *      的裸名，同样补前缀（否则回落 tool:）。
+ *   3. usage 只由 llm.turn 累计（capability span 的 usage 是子 span 聚合，计入会双算）。
+ */
+
+
+
+/** 从 span.attributes 认能力类型（框架用 `setAttribute(capabilityId, 'subagent', name)` 记类型） */
+function spanType(s) {
+  const attrs = s.attributes || {};
+  for (const t of Object.keys(CAP_ICO)) {
+    if (attrs[t] != null) return t;
+  }
+  return '';
+}
+
+/** 显示名：capability span 补 `type:` 前缀（已是 type:name 形态则原样保留） */
+function displayName(s) {
+  const raw = String(s.name || '');
+  const t = spanType(s);
+  if (!raw) return t || s.kind || '';
+  if (capabilityTypeOf(raw)) return raw; // 已带前缀
+  return t ? `${t}:${raw}` : raw;
+}
+
+function usageOf(s) {
+  if (!s.usage) return null;
+  return {
+    input: s.usage.inputTokens || 0,
+    output: s.usage.outputTokens || 0,
+    cacheRead: s.usage.cacheReadTokens || 0,
+    cacheCreation: s.usage.cacheCreationTokens || 0,
+  };
+}
+
+/** 事件工具名：**只有 `tool.*` 事件带工具名**。
+ *  框架的事件里 `usage.unpriced` / `llm.retry` / `budget.exceeded` / `context.budget` 的事件体
+ *  根本没有 `tool` 字段 —— 一律套前缀只会得到 `tool:?` 这种把「无工具」显示成「名字叫 ? 的工具」
+ *  的误导标签（面板与官网 playground 共用本渲染器，等于把假工具摆给使用者看）。
+ *  工具裸名靠兄弟 capability span 反查类型，找不到按 tool 算。 */
+function eventToolName(evName, bodyTool, typeMap) {
+  if (!String(evName || '').startsWith('tool.')) return '';
+  const raw = String(bodyTool || '?');
+  if (capabilityTypeOf(raw)) return raw;
+  return `${typeMap.get(raw) || 'tool'}:${raw}`;
+}
+
+/** 事件摘要：input 走 fmtArg（与 span 入参同一形态），output 走文本内容 */
+function eventText(ev) {
+  const body = ev.body;
+  if (ev.name === 'tool.input') return fmtArg(body?.input);
+  if (ev.name === 'tool.output') {
+    const c = body?.content;
+    return typeof c === 'string' ? c : c == null ? '' : JSON.stringify(c);
+  }
+  return body == null ? '' : typeof body === 'string' ? body : JSON.stringify(body);
+}
+
+/**
+ * 事件全文（展开态用）。
+ *
+ * 只有 `tool.input` 需要单独取：`fmtArg` 把入参摘要**砍到 4 个键 / 每值 21 字符 / 整串 62 字符**，
+ * 直接拿摘要当全文就是「假展开」—— 点开看到的还是那 62 个字符。出参与其他事件本身就是原文
+ * （`eventText` 原样返回 content），无需二次处理。
+ * 原文口径统一在 view.js 的 `rawArg`：官网 playground 的模拟回放也要用它，两处一处定义。
+ */
+function eventFull(ev) {
+  if (ev.name === 'tool.input') return rawArg(ev.body?.input);
+  return eventText(ev);
+}
+
+/**
+ * 把真实 Trace 线性回放给视图（同步、一次性）。
+ *
+ * 两种用途共用本函数（这也是它必须呆在 trace-view 里、不进 CLI 的理由）：
+ * - **收尾的整棵 trace**（run 结束后一次画完）；
+ * - **在飞的那棵树**（CLI inspector 的实时右栏：每收到一条增量记账事件就整体重画一次，
+ *   见 `packages/cli/src/panel-logic.ts` 的 `applyTraceEvent`）。重画是幂等的 ——
+ *   同一棵 spans 交给它多少次，画出来的都是同一棵树。
+ *
+ * 返回 false 表示 trace 空、未做任何渲染。
+ */
+function playTrace(view, trace) {
+  const spans = Array.isArray(trace?.spans) ? trace.spans : [];
+  // ⚠️ 空 spans 也**必须 reset**：playTrace 的契约是「把这个 view 变成这棵树」——
+  // 直接 return 会把**上一条 trace 的树**留在页面上，而下拉里选中的是这一条
+  // （切换后看到别人的数据，比看到空白更坏；2026-10-21 在 `agentia view` 的多 trace
+  // 下拉里实测到：先选一个正常 trace，再选一个 0 spans 的，树原样不动）。
+  if (!spans.length) {
+    const label = trace?.traceId ? String(trace.traceId) : '空 trace';
+    view.reset(`run · ${label}（无 spans）`);
+    return false;
+  }
+
+  const byId = new Map(spans.map((s) => [s.spanId, s]));
+  const root = spans.find((s) => s.kind === 'run') || spans[0];
+
+  // 裸名 → 能力类型（供事件补前缀）
+  const typeMap = new Map();
+  for (const s of spans) {
+    const t = spanType(s);
+    if (s.kind === 'capability' && t) typeMap.set(String(s.name || ''), t);
+  }
+
+  const depthOf = (s) => {
+    let d = 0;
+    let cur = s;
+    const seen = new Set();
+    while (cur?.parentSpanId && byId.has(cur.parentSpanId) && !seen.has(cur.spanId)) {
+      seen.add(cur.spanId);
+      d += 1;
+      cur = byId.get(cur.parentSpanId);
+    }
+    return d;
+  };
+
+  const items = [];
+  let seq = 0; // 出现顺序：时间缺失 / 并列时的确定性回退（NaN 参与比较会让排序结果随引擎不定）
+  const timeOf = (v, fallback) => (typeof v === 'number' && Number.isFinite(v) ? v : fallback);
+  for (const s of spans) {
+    const start = timeOf(s.startedAt, 0);
+    items.push({ t: start, ord: 0, d: depthOf(s), s, kind: 'start', seq: seq++ });
+    if (s.endedAt != null)
+      items.push({ t: timeOf(s.endedAt, start), ord: 2, d: 0, s, kind: 'end', seq: seq++ });
+    for (const ev of s.events || [])
+      items.push({ t: timeOf(ev.time, start), ord: 1, d: 0, s, kind: 'event', ev, seq: seq++ });
+  }
+  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: '',
+      });
+    }
+  }
+
+  // 根 span 还没结束（`span.end` 尚未到达）⇒ **不收尾**：`finish()` 会把根标成已完成
+  // （● + 耗时），而这棵树其实还在长 —— 在飞时看到「已完成」是假事实。留 ◌ 才对。
+  // 收尾的整棵 trace 根必有 `endedAt`，所以这条分支只对「在飞 / 截断」的树生效。
+  if (root.endedAt != null) view.finish(root.endedAt - root.startedAt, root.status, root.error);
+  return true;
+}
+
+/* ===== src/summary.js ===== */
+/* 能力排行（G2）—— 「哪个能力慢 / 贵 / 爱失败」。
+ *
+ * 与 trace 调用树同属**框架无关**的展示层：入参是 duck-typed 的 trace 形状，零依赖。
+ * CLI inspector 与官网 playground 共用同一份实现，避免两处聚合口径漂移。
+ *
+ * 数据来源（与框架侧的具名约定一致）：
+ * - `capability` span（skill / subagent）→ 调用耗时与子孙 usage 聚合（tokens / costUsd）。
+ *   ⚠️ **usage 只认顶层 capability**（没有 capability 祖先的）：框架侧 capability.usage
+ *   是其**子孙 llm.turn 的聚合**（`src/engine/tracer.ts`），嵌套时（`@SubAgent` 套
+ *   `@Skill`）外层与内层带着同一批 token ⇒ 逐行累加会重复计数。嵌套行仍计
+ *   calls / errors / 耗时（那是它自己这次调用的真账，不重复），tokens / costUsd
+ *   留给顶层行 —— 各行可加总，与 `src/core/trace.ts`「capability 聚合不进
+ *   totalUsage（避免重复计数）」同一条纪律。没选「从 llm.turn 重新归账」：
+ *   手写 / 外来的 trace 可能只在 capability span 上带 usage（没有嵌套的 llm.turn
+ *   子孙），重算会把这类成本静默清零。
+ * - `llm.turn` span 上的 `tool.output` 事件（普通工具不建 span）→ 工具耗时与成败，
+ *   读 `body.durationMs` / `body.ok`；
+ * - `approval.decided` 事件（**审批不建 span**，G7 护栏）→ `guardrail:<工具名>` 一类的
+ *   等审批时长与被拒次数，读 `body.tool` / `body.approved` / `body.waitedMs`。
+ *   扫面**不限 span kind**：落点因段而异（首段 llm.turn、恢复段 run 根 —— 续跑入口把
+ *   run 根 id 当 turnId），限 kind = 真实 HITL 主流程（挂起 → 人批 → 恢复）零产出；
+ *   不双计：记账点只有一处（executeOneTool），一次决定只记一笔。
+ *
+ * ⚠️ 单条 run 内样本常 < 5，分位没有意义 —— 排行以 total/max 为主，不给 p50/p95
+ * （要看分位请用框架的 `buildRunReport` + `mergeRunReports`）。
+ */
+
+function kindOf(span) {
+  if (span.attributes && span.attributes.skill !== undefined) return 'skill';
+  if (span.attributes && span.attributes.subagent !== undefined) return 'subagent';
+  return 'capability';
+}
+
+/**
+ * 从一条 trace 算能力排行。
+ * @param {any} trace Trace 形状（spans[] / events[] / usage?）
+ * @returns {Array<{capability:string,calls:number,errors:number,totalMs:number,maxMs:number,tokens:number|null,costUsd:number|null}>}
+ *          按 totalMs 降序
+ */
+function summarizeTrace(trace) {
+  const acc = new Map();
+  const get = (capability) => {
+    let a = acc.get(capability);
+    if (!a) {
+      a = { capability, calls: 0, errors: 0, totalMs: 0, maxMs: 0, tokens: null, costUsd: null };
+      acc.set(capability, a);
+    }
+    return a;
+  };
+  const addMs = (a, ms) => {
+    const v = Number.isFinite(ms) && ms > 0 ? ms : 0;
+    a.totalMs += v;
+    if (v > a.maxMs) a.maxMs = v;
+  };
+
+  const spans = trace?.spans || [];
+  const byId = new Map();
+  for (const s of spans) if (s && s.spanId != null) byId.set(s.spanId, s);
+  // 该 span 是否嵌套在另一个 capability 之下（沿 parentSpanId 上爬；seen 防手写 trace 的环）
+  const hasCapabilityAncestor = (span) => {
+    let p = span.parentSpanId;
+    const seen = new Set();
+    while (p != null && !seen.has(p)) {
+      seen.add(p);
+      const ps = byId.get(p);
+      if (!ps) return false;
+      if (ps.kind === 'capability') return true;
+      p = ps.parentSpanId;
+    }
+    return false;
+  };
+  for (const span of spans) {
+    if (span.kind === 'capability') {
+      const a = get(`${kindOf(span)}:${span.name}`);
+      a.calls += 1;
+      if (span.status === 'error') a.errors += 1;
+      if (span.endedAt != null) addMs(a, span.endedAt - span.startedAt);
+      const u = span.usage;
+      if (u && !hasCapabilityAncestor(span)) {
+        a.tokens =
+          (a.tokens || 0) +
+          (u.inputTokens || 0) +
+          (u.outputTokens || 0) +
+          (u.cacheReadTokens || 0) +
+          (u.cacheCreationTokens || 0);
+        if (u.costEstimate != null) a.costUsd = (a.costUsd || 0) + u.costEstimate;
+      }
+      continue;
+    }
+    // approval.decided **不限 span kind**（落点因段而异：首段 llm.turn、恢复段 run 根 ——
+    // 续跑入口把 run 根 id 当 turnId，见头注）；tool.output 只在 llm.turn 上。
+    const isTurn = span.kind === 'llm.turn';
+    for (const e of span.events || []) {
+      if (e.name === 'approval.decided') {
+        // G7 护栏 —— 审批**只是事件**（刻意不建 span），所以它天然不在任何 span 聚合里，
+        // 此前「哪个工具卡在审批上、被拒了几次」在排行上完全看不见。这一类补上它：
+        //   calls     = 走到「决定」这一步的次数（批准或被拒都算）；
+        //   errors    = **被拒**次数（护栏真挡下了几次 —— 它不是系统错误，但那次工具确实没跑）；
+        //   total/max = 等审批时长（事件的 `waitedMs`）。⚠️ 只有宿主回填了 `requestedAt`
+        //               才有这个数 ⇒ 缺就记 0，**不编造**（框架侧刻意不记「没数据」的 0）。
+        // ⚠️ 口径边界：只聚 `approval.decided`。只有 `approval.requested` 而始终没恢复的
+        //   挂起**不产出** guardrail 行 —— 它没有结论、也没有时长，硬记一格等于编账。
+        const b = e.body;
+        if (!b || typeof b !== 'object' || typeof b.tool !== 'string') continue;
+        const ga = get(`guardrail:${b.tool}`);
+        ga.calls += 1;
+        if (b.approved === false) ga.errors += 1;
+        addMs(ga, typeof b.waitedMs === 'number' ? b.waitedMs : 0);
+        continue;
+      }
+      if (!isTurn || e.name !== 'tool.output') continue;
+      const b = e.body;
+      if (!b || typeof b !== 'object' || typeof b.tool !== 'string') continue;
+      const a = get(`tool:${b.tool}`);
+      a.calls += 1;
+      if (b.ok === false) a.errors += 1;
+      addMs(a, typeof b.durationMs === 'number' ? b.durationMs : 0);
+    }
+  }
+
+  return [...acc.values()].sort((x, y) => y.totalMs - x.totalMs || y.calls - x.calls);
+}
+
+/** 把排行渲染成一个小表格（返回 HTML 字符串；样式由 trace-view.css 提供） */
+function renderSummary(rows) {
+  if (!rows || rows.length === 0) {
+    return '<div class="tv-sum-empty">// 没有可归因的能力（没有 capability span，也没有 tool.output 事件）</div>';
+  }
+  const fmtMs = (ms) => (ms >= 1000 ? (ms / 1000).toFixed(2) + 's' : ms + 'ms');
+  const body = rows
+    .map((r) => {
+      const err = r.errors > 0 ? `<span class="tv-sum-err">${r.errors}</span>` : '0';
+      const cost =
+        r.costUsd != null
+          ? r.costUsd < 0.000001
+            ? r.costUsd.toExponential(2)
+            : r.costUsd.toFixed(6)
+          : '-';
+      return `<tr><td class="tv-sum-capability">${escapeHtml(r.capability)}</td><td>${r.calls}</td><td>${err}</td><td>${fmtMs(r.totalMs)}</td><td>${fmtMs(r.maxMs)}</td><td>${r.tokens != null ? r.tokens : '-'}</td><td>${cost}</td></tr>`;
+    })
+    .join('');
+  return (
+    '<table class="tv-sum"><thead><tr><th>capability</th><th>calls</th><th>err</th><th>total</th><th>max</th><th>tokens</th><th>cost</th></tr></thead>' +
+    `<tbody>${body}</tbody></table>`
+  );
+}
+
+function escapeHtml(s) {
+  return String(s).replace(
+    /[&<>"']/g,
+    (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c],
+  );
+}
+
+/* ===== src/index.js ===== */
+/* @migor/trace-view —— Agentia trace 调用树渲染器（框架无关、零依赖）。
+ * 官网 playground 与 CLI inspector 共用同一份，避免两处渲染漂移。 */
+
+export {
+  CAP_ICO,
+  capabilityTypeOf,
+  createTraceView,
+  fmtArg,
+  fmtMs,
+  fmtNum,
+  playTrace,
+  rawArg,
+  renderSummary,
+  summarizeTrace,
+};