@migor/cli 0.3.0 → 0.4.0

package/dist/AGENTS.md

@@ -162,6 +162,7 @@ npx @migor/cli doctor            # 静态体检（未登记/悬空/命名/重复
 | `onUnpricedModel` | 遇到价格表外的模型时回调（`{ model, spanId }`，每个循环作用域内每模型一次）；抛错被吞，**不改变 run 结局**（定价缺失是宿主配置问题）。用它接告警 |
 | `toolTimeoutMs` | 缺省单工具超时（毫秒）；超时该条 tool_result 记 is_error，不杀 run |
 | `maxToolConcurrency` | 缺省同回合并行工具上限；不设 = 不限（全并行） |
+| `maxEventChars` | 缺省 trace 事件正文截断上限（可被单次 run 覆盖）：数字 = 入参/出参统一用该上限，`false` = **不截断**（完整正文进 trace，面板里能展开看全文）；不设 = 框架缺省 |
 
 ### `app.run(messages, opts?: RunAppOptions)`
 
@@ -185,6 +186,7 @@ npx @migor/cli doctor            # 静态体检（未登记/悬空/命名/重复
 | `onUnpricedModel` | 单次覆盖未定价回调（**是函数，因此不在 transport 的 `RunInvocationOptions` 里** —— 异步宿主不会替你传） |
 | `toolTimeoutMs` | 单个工具执行超时（毫秒）；超时该条 tool_result 记 is_error，run 继续 |
 | `maxToolConcurrency` | 同回合并行工具上限；缺省不限 |
+| `maxEventChars` | trace 事件正文截断上限（字符）：数字 = 入参/出参统一用该上限，`false` = **不截断**；缺省按类型收敛（入参/成功出参 2000、失败出参 1000）。**透传给子 agent/skill 的子循环** —— 同一棵调用树上口径一致。只影响**记账**，回给模型的 tool_result 永远完整 |
 | `session` | 会话持久化 `{ store, id }`：run 前拼历史、成功收尾追加本轮（见 `SessionStore`） |
 
 返回 `AgentRunOutput`：`{ run, result }`。`result` 含 `trace` / `stopReason` / `finalText` / `iterations` / `error` / `typed`。
@@ -613,6 +615,18 @@ if (!report.ok) console.error(report.cases.filter((c) => !c.ok));
 - **内存上限** ≈ `(1 + 能力数 + 模型数) × windowSize` —— 能力数由 `maxCapabilities` 封顶，长跑宿主不会被拖住。
 - `costUsd` 依赖模型在价格表内（不在表里时不计、并计入 `unpricedTurns` 与 `usage.unpriced` 事件）；根 span 未收尾（如失败路径的半截 trace）的 run 不进延迟样本。
 
+### 调用树面板（`agentia dev` 的本地面板 / 官网 Playground）
+
+同一份 `@migor/trace-view` 渲染器，**面板 / Playground / `report` 的能力排行三处共用**，不各写一套。
+
+- **折叠态是「一行一件事」**：事件行（`tool.input` / `tool.output`）只显示省略号收敛的摘要。
+- **点事件行展开看完整正文**（正文可选中复制），再点收起。展开的正文**默认仍与标签同一行**，
+  只有在放不下时才整段换到下一行 —— 官网 Playground 的 trace 列（约 320px）就属于放不下。
+- **可展开的行右端常显一个 caret**（`▸` / `▾`）：这一行能不能展开随时看得见，不必先悬停才发现。
+- **展开只能展开 trace 里存着的正文** —— 想看到被截断掉的部分，得在**记账时**就别截：`maxEventChars: false`（见 §4）。缺省截到 2000 字符，展开了也只有那 2000 字符。
+- 入参折叠态的摘要被砍到 62 字符（4 个键 / 每值 21 字符）；**展开拿到的是原文**，不是那份摘要 ——
+  本地面板与官网 Playground 两个宿主都是如此（两个宿主都不该只喂摘要，否则点开什么都没多出来）。
+
 ### 调优报告（**哪个能力慢 / 贵 / 爱失败**）
 
 指标回答「整体怎么样」，报告回答「**该拧哪个旋钮**」：
@@ -659,9 +673,13 @@ const app = await createApp({ /* … */ sinks: [jsonl] });
 ### 生效配置快照（「这条 run 用了哪套旋钮」）
 
 每个 run 的**根 span** 都带一组 `config.*` attributes（`config.maxTokens` / `config.maxCostUsd` /
-`config.retry.maxAttempts` / `config.contextPolicy.budgetTokens` / `config.priceOverrides` …），
-缺省值也记 —— 这样「没配」「配了缺省值」「配了别的值」三者可区分。换参数前后对比、复现线上行为都有据可查。
+`config.retry.maxAttempts` / `config.contextPolicy.budgetTokens` / `config.priceOverrides` /
+`config.maxEventChars` …）。
+带缺省值的那几项（`maxTokens` / `maxIterations` / `contextPolicy` / `retry`）**缺省值也记**——
+「没配」与「配了缺省值」因此可区分；可选项（`toolTimeoutMs` / `maxToolConcurrency` /
+`maxEventChars`）只在设了才记。换参数前后对比、复现线上行为都有据可查。
 函数型选项（`summarize` / `confirm` 之类）只记「配没配」，不记函数体。
+截断关掉时记的是 `'off'` 而不是 `false` —— 后者在日志/看板里会被读成「上限为 0」。
 
 ### 提示词版本化
 

package/dist/inspector/fromTrace.js

@@ -14,7 +14,7 @@
  *   3. usage 只由 llm.turn 累计（capability span 的 usage 是子 span 聚合，计入会双算）。
  */
 
-import { fmtArg, capabilityTypeOf, CAP_ICO } from './view.js';
+import { fmtArg, rawArg, capabilityTypeOf, CAP_ICO } from './view.js';
 
 /** 从 span.attributes 认能力类型（框架用 `setAttribute(capabilityId, 'subagent', name)` 记类型） */
 function spanType(s) {
@@ -67,6 +67,19 @@ function eventText(ev) {
   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 && ev.body.input);
+  return eventText(ev);
+}
+
 /**
  * 把真实 Trace 线性回放给视图（同步、一次性；用于 run 结束后的静态展示）。
  * 返回 false 表示 trace 空、未做任何渲染。
@@ -126,6 +139,7 @@ export function playTrace(view, trace) {
         eventToolName(it.ev.name, it.ev.body && it.ev.body.tool, typeMap),
         eventText(it.ev),
         !it.ev.body || it.ev.body.ok !== false,
+        eventFull(it.ev),
       );
     } else {
       view.end({

package/dist/inspector/index.js

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

package/dist/inspector/trace-view.css

@@ -104,6 +104,57 @@
   color: #f7768e;
 }
 
+/* —— 行展开：折叠时「一行一个语义单元」，点开的那一行改为显示**完整正文** ——
+   caret 绝对定位在行右端，不占 flex 宽度，所以行内其它元素的排版不受它影响。
+   **常显，并且是满不透明度的 `--faint`**：它是个**交互指示器**，不是装饰 ——
+   caret 用 0.75 的透明度试过，量出来是缺陷而非口味：WCAG 1.4.11 对非文本 UI 组件
+   要求 ≥3:1，而 0.75 的 `--faint`(#71717a) 在官网 #0c0c0e 面板上实际绘制成 #58585f，
+   只有 **2.77:1**（满不透明度 4.04:1）。
+   所以没有「hover 才变亮」这一档：静止时它已经是最亮的那一档了。 */
+.tr-row[data-expandable] {
+  position: relative;
+  cursor: pointer;
+}
+.tr-caret {
+  position: absolute;
+  right: 0;
+  top: 3px; /* 对齐 .tr-row 的 padding: 3px 0 */
+  color: var(--faint);
+  font-size: 10px;
+}
+/* caret 常显 ⇒ 右端要给它留一条窄槽。不留的话，被截断的正文省略号「…」正好落在 caret 底下，
+   ▸ 与 … 糊成一个字形。给正文加右内边距 = 内容盒右缘左移，省略号自行退到槽的左边。 */
+.tr-row[data-expandable] .tr-io {
+  padding-right: 12px;
+}
+/* 只有点开的那一行换行；树的其余部分保持 nowrap 的列对齐 */
+.tr-row.tr-open {
+  white-space: normal;
+  align-items: flex-start;
+  /* 允许正文换到下一行 —— 但**只在它真的放不下时**（判据是下面那条 min-width，不是无条件换行） */
+  flex-wrap: wrap;
+}
+/* 展开的正文**有高度上限**：工具出参动辄上千行（实测一条 60 行的出参就有 17878px 的
+   scrollWidth），不限高会把整个调用树推到屏幕之外，「看下一行」比「看全文」更常用。
+   超出部分在行内滚动 —— 正文仍在 DOM 里，选中复制不受影响。 */
+.tr-row.tr-open .tr-io {
+  /* 正文与标签**同一行**（既定的阅读节奏：一行一个语义单元）。换行只发生在**放不下时**，
+     而这条线由 min-width 划 —— 所以 flex-basis 必须是 0：
+       · basis: auto ⇒ 换行判据是 max-content（正文动辄上百字符 ⇒ 几乎必然换行，等于无条件换行）；
+       · basis: 0    ⇒ 判据回到 min-width，放得下就同排、放不下才整段换行。
+     为什么 min-width 不能省：正文用 overflow-wrap: anywhere，min-content 只有 1 个字符宽 ——
+     没有它时 flex 会心安理得地把正文压成一条 16px 的窄缝（59 个字符挤成 34 行、行高顶到上限），
+     而页面 scrollWidth === clientWidth 一切「干净」，只是读不了。
+     窄面板（官网 Playground 296px）里那行固定项本身就要 ~246px，所以那里它会如实地换行。 */
+  flex-basis: 0;
+  min-width: 22ch;
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+  max-height: 60vh;
+  overflow: auto;
+  text-overflow: clip;
+}
+
 @keyframes tr-blink {
   0%,
   100% {

package/dist/inspector/view.js

@@ -9,6 +9,11 @@
  *     这个先后本身就是语义，不能拍平成一类；
  *   - 四类能力标识符（⚙ tool / ◆ skill / ¶ prompt / ⊕ subagent）只靠字形区分、不上类型色。
  *
+ * 展开：折叠态**一字不变**（省略号收敛，事件行比 span 行更轻），点事件行可展开看**完整正文**。
+ * 展开状态存在渲染之外（每次事件都会全量重建 DOM），否则实时 run 里刚点开的行会在下一条事件
+ * 到来时自己合上。数据侧「行内摘要」与「展开全文」是两个字段：`text` 是摘要（入参经 fmtArg
+ * 砍到 62 字符），`full` 才是原文 —— 只有全文能撑起「调试时看工具结果」这件事。
+ *
  * 宿主需提供的 CSS 变量：--ice --faint --text（见 trace-view.css）。
  */
 
@@ -46,6 +51,19 @@ export function fmtArg(v) {
   return s.length > 62 ? s.slice(0, 61) + '…' : s;
 }
 
+/* span 入参**原文** —— fmtArg 的对偶：摘要给折叠态，原文给展开态。
+ * 两者必须定义在同一处：哪个宿主自己搓一个「原文」，「展开」就会在那里退回摘要
+ * （点开什么都没多出来），而两个宿主共用这一份渲染器，正是为了不让这种漂移发生。 */
+export 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;
@@ -67,6 +85,25 @@ export function createTraceView(rootEl, opts = {}) {
   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 = '';
@@ -89,6 +126,7 @@ export function createTraceView(rootEl, opts = {}) {
 
       /* 事件行：没有 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);
@@ -98,9 +136,19 @@ export function createTraceView(rootEl, opts = {}) {
         // 非 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 || '';
+        // 展开态用全文（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;
       }
@@ -175,6 +223,7 @@ export function createTraceView(rootEl, opts = {}) {
     };
     spanMap.clear();
     spanMap.set('root', traceRoot);
+    expanded.clear(); // 展开态属于上一棵树：reset 开新树时一并清掉
     usageAcc.input = 0;
     usageAcc.output = 0;
     usageAcc.cacheRead = 0;
@@ -206,11 +255,22 @@ export function createTraceView(rootEl, opts = {}) {
 
   /* 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) {
+     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 };
+    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();

package/dist/templates.js

@@ -60,7 +60,7 @@ export function projectPackageJson(name) {
             dev: 'tsx src/main.ts',
             typecheck: 'tsc --noEmit -p tsconfig.json',
         },
-        dependencies: { '@migor/agentia': '^0.3.0' },
+        dependencies: { '@migor/agentia': '^0.4.0' },
         devDependencies: {
             tsx: '^4.19.0',
             typescript: '^7.0.2',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@migor/cli",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Agentia 框架命令行工具：create 脚手架 + g 能力生成 + dev 本地可观测面板（trace inspector）",
   "type": "module",
   "bin": {