@migor/cli 0.2.1 → 0.2.2

package/dist/inspector/index.js

@@ -0,0 +1,6 @@
+/* @migor/trace-view —— Agentia trace 调用树渲染器（框架无关、零依赖）。
+ * 官网 playground 与 CLI inspector 共用同一份，避免两处渲染漂移。 */
+
+export { createTraceView, capabilityTypeOf, CAP_ICO, fmtArg, fmtNum, fmtMs } from './view.js';
+export { playTrace } from './fromTrace.js';
+export { summarizeTrace, renderSummary } from './summary.js';

package/dist/inspector/summary.js

@@ -0,0 +1,106 @@
+/* 能力排行（G2）—— 「哪个能力慢 / 贵 / 爱失败」。
+ *
+ * 与 trace 调用树同属**框架无关**的展示层：入参是 duck-typed 的 trace 形状，零依赖。
+ * CLI inspector 与官网 playground 共用同一份实现，避免两处聚合口径漂移。
+ *
+ * 数据来源（与框架侧的具名约定一致）：
+ * - `capability` span（skill / subagent）→ 调用耗时与子孙 usage 聚合（tokens / costUsd）；
+ * - `llm.turn` span 上的 `tool.output` 事件（普通工具不建 span）→ 工具耗时与成败，
+ *   读 `body.durationMs` / `body.ok`。
+ *
+ * ⚠️ 单条 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 降序
+ */
+export 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 && trace.spans) || [];
+  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) {
+        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;
+    }
+    if (span.kind !== 'llm.turn') continue;
+    for (const e of span.events || []) {
+      if (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 提供） */
+export 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],
+  );
+}

package/dist/inspector/trace-view.css

@@ -0,0 +1,166 @@
+/* Agentia trace 调用树样式 —— 从 packages/website/src/styles/global.css 的 .tr-* 段原样抽出。
+ * 宿主需提供这些 CSS 变量：--ice（accent）--faint（次要文本）--text（主文本）。
+ * 官网用站点调色板；CLI inspector 页面自带同名变量，视觉一致。 */
+
+.tr-row {
+  display: flex;
+  align-items: baseline;
+  gap: 8px;
+  padding: 3px 0;
+  white-space: nowrap;
+}
+.tr-pre {
+  color: var(--faint);
+  white-space: pre;
+}
+.tr-dot {
+  color: var(--ice);
+}
+.tr-row.running .tr-dot {
+  animation: tr-blink 0.9s steps(1) infinite;
+}
+.tr-name {
+  color: #d4d4d8;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+/* span 入参摘要：让同名调用（如两次 tool:get_weather）可区分 */
+.tr-arg {
+  color: var(--faint);
+  font-size: 11.5px;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  min-width: 0;
+}
+/* 失败 span：点变红、名字与 meta 走告警色 */
+.tr-row.error .tr-dot {
+  color: #f7768e;
+}
+.tr-row.error .tr-name {
+  color: #f7768e;
+}
+.tr-row.error .tr-meta {
+  color: rgba(247, 118, 142, 0.9);
+}
+.tr-row[data-kind="run"] .tr-name {
+  color: var(--text);
+  font-weight: 500;
+}
+.tr-row[data-kind="llm.turn"] .tr-name {
+  color: var(--ice);
+}
+.tr-meta {
+  margin-left: auto;
+  color: var(--faint);
+  font-size: 11px;
+  padding-left: 10px;
+}
+.tr-empty {
+  color: var(--faint);
+}
+
+/* 四类能力标识符（⚙ tool / ◆ skill / ¶ prompt / ⊕ subagent）：只靠字形区分，
+   不上类型色 —— 站点只有一支青色 accent，加四种颜色会打散近黑钛银的克制感。
+   有内部结构的 skill / subagent 用 accent 点亮，工具类保持灰，层级一眼可辨。 */
+.tr-ico {
+  flex: none;
+  color: var(--faint);
+  font-size: 10px;
+}
+.tr-row[data-capability="skill"] .tr-ico,
+.tr-row[data-capability="subagent"] .tr-ico {
+  color: var(--ice);
+}
+
+/* span 事件行：普通工具 / @Prompt 调用是 turn 上的【事件】而非 span ——
+   没有状态圈与耗时，视觉上比 span 行更轻，入参/出参摘要靠省略号收敛。 */
+.tr-ev {
+  gap: 6px;
+  font-size: 11.5px;
+}
+.tr-ev .tr-evv {
+  flex: none;
+  color: var(--ice);
+}
+.tr-ev .tr-evtype {
+  flex: none;
+  color: var(--faint);
+  font-size: 10.5px;
+}
+.tr-ev .tr-name {
+  flex: none;
+  color: #a1a1aa;
+}
+.tr-io {
+  flex: 1 1 auto;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  color: var(--faint);
+}
+.tr-ev.error .tr-evv,
+.tr-ev.error .tr-name,
+.tr-ev.error .tr-io {
+  color: #f7768e;
+}
+
+@keyframes tr-blink {
+  0%,
+  100% {
+    opacity: 1;
+  }
+  50% {
+    opacity: 0.25;
+  }
+}
+
+/* —— 能力排行（G2）：哪个能力慢 / 贵 / 爱失败 —— */
+.tv-sum {
+  width: 100%;
+  border-collapse: collapse;
+  font-family: var(--tv-mono, ui-monospace, SFMono-Regular, Menlo, monospace);
+  font-size: 11.5px;
+  margin-top: 10px;
+}
+.tv-sum th {
+  text-align: left;
+  color: #71717a;
+  font-weight: 500;
+  border-bottom: 1px solid #27272a;
+  padding: 4px 8px 4px 0;
+  white-space: nowrap;
+}
+.tv-sum td {
+  padding: 3px 8px 3px 0;
+  color: #a1a1aa;
+  white-space: nowrap;
+}
+.tv-sum td.tv-sum-capability {
+  color: #e4e4e7;
+}
+.tv-sum tbody tr:hover td {
+  background: #17171a;
+}
+.tv-sum-err {
+  color: #f7768e;
+}
+.tv-sum-empty {
+  color: #71717a;
+  margin-top: 10px;
+  font-size: 11.5px;
+}
+
+/* 失败行的错误原文：单起一行（.tr-row 是 nowrap，挤在同一行会把行撑爆） */
+.tr-errm {
+  display: flex;
+  gap: 8px;
+  padding: 1px 0 4px;
+  white-space: normal;
+}
+.tr-errm-msg {
+  color: #f7768e;
+  font-size: 11.5px;
+  white-space: pre-wrap;
+  word-break: break-word;
+  min-width: 0;
+}

package/dist/inspector/view.js

@@ -0,0 +1,274 @@
+/* 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）只靠字形区分、不上类型色。
+ *
+ * 宿主需提供的 CSS 变量：--ice --faint --text（见 trace-view.css）。
+ */
+
+export const CAP_ICO = { tool: '⚙', skill: '◆', prompt: '¶', subagent: '⊕' };
+
+/** 能力类型取自名字前缀（tool: / skill: / prompt: / subagent:） */
+export function capabilityTypeOf(name) {
+  const t = String(name || '').split(':')[0];
+  return CAP_ICO[t] ? t : '';
+}
+
+export const fmtNum = (n) => n.toLocaleString('en-US');
+export const fmtMs = (ms) => (ms >= 1000 ? (ms / 1000).toFixed(2) + 's' : ms + 'ms');
+
+/* span 入参摘要：写进 trace 行，否则同名 capability（如两次 tool:get_weather）无法区分 */
+export 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;
+}
+
+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（可选；每次累计后回调，便于宿主自定义展示）
+ */
+export 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 };
+
+  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 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));
+        const io = el('span', 'tr-io', ev.text || '');
+        io.title = ev.text || '';
+        row.appendChild(io);
+        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 && node.error.type) || 'error');
+        meta = parts.join(' · ');
+      } else meta = '…';
+      const metaEl = el('span', 'tr-meta', meta);
+      if (bad && node.error && node.error.message) metaEl.title = node.error.message;
+      row.appendChild(metaEl);
+      rootEl.appendChild(row);
+      // 失败原文必须**看得见** —— 只塞进 title（hover 才显）等于没显示。首次运行最常见的失败
+      // （没配 API key）就靠这一行定位；单起一行，不去挤占 nowrap 的 span 行。
+      if (bad && node.error && 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);
+    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 的先后顺序。 */
+  function event(id, type, tool, text, ok) {
+    const node = spanMap.get(id);
+    if (!node) return;
+    const e = { type, tool, text, ok: ok !== false };
+    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;
+    },
+  };
+}