@migor/cli 0.10.9 → 0.10.10

package/dist/inspector-routes.js

@@ -349,7 +349,10 @@ function handleRunDetail(ctx) {
         ctx.json(ctx.res, 404, { error: 'run 不存在（可能已被淘汰）' });
         return;
     }
-    ctx.json(ctx.res, 200, t);
+    // 明细**带上 CLI 侧记账**（顶层 `note`）：`finalText` 只活在那里 —— trace 上没有它。
+    // 不带的话，面板一离开这一轮就再也拿不回回复（见 `RunNote.finalText`）。
+    // 形状是 `Trace + { note }`，`playTrace` 只读 `spans` / `traceId`，多一个键无影响。
+    ctx.json(ctx.res, 200, { ...t, note: ctx.state.notes.get(id) ?? null });
 }
 /**
  * 并排 A/B：`GET /api/runs/compare?a=<id>&b=<id>` → `{ diff, comparability }`。

package/dist/panel-logic.js

@@ -119,6 +119,45 @@ export function historyText(history, cursor, draft) {
         return draft;
     return history[history.length - 1 - cursor] ?? draft;
 }
+export function stopReasonClass(r) {
+    const sr = r.stopReason ?? null;
+    if (sr === 'aborted')
+        return 'aborted';
+    // suspended 先于 ok 判：引擎的 `isSuccessStopReason` 不把它算成功，而 trace 状态记 ok
+    // （挂起段本身执行无误）⇒ 只看 ok 就漏了「这一轮其实还等着人」。
+    if (sr === 'suspended')
+        return 'suspended';
+    return r.ok ? 'ok' : 'failed';
+}
+/**
+ * 收尾原因的**中文短语**（面板显示用）。
+ *
+ * 未知串**原样返回**（不回落成「完成」、也不回落成空串）：面板不认识的
+ * `stop_reason` 只能说明面板落后于框架，把原文亮出来才能一眼看出是哪个新原因。
+ * 要覆盖的成员由 `test/stop-reason.test.mjs` 对着 `src/engine/types.ts` 的
+ * `AgentStopReason` 逐个数 —— 框架加了成员而这里没表态，那条守卫就红。
+ */
+const STOP_REASON_TEXT = {
+    end_turn: '模型自然收尾',
+    stop_sequence: '命中停止序列',
+    max_tokens: '撞到输出上限',
+    model_context_window_exceeded: '撞到上下文窗口',
+    refusal: '模型拒绝回答',
+    pause_turn: '模型请求暂停',
+    max_iterations: '撞到迭代上限',
+    result_missing: '没提交结构化结果',
+    budget_exceeded: '撞到预算护栏',
+    aborted: '已中止',
+    tool_use_no_blocks: '回合里没有可执行块',
+    suspended: '等人审批',
+    unknown_stop_reason: '未识别的收尾原因',
+    error: '出错',
+};
+export function stopReasonText(sr) {
+    if (!sr)
+        return '';
+    return STOP_REASON_TEXT[sr] ?? sr;
+}
 /**
  * 这个 run 算不算**失败**？
  *
@@ -128,12 +167,12 @@ export function historyText(history, cursor, draft) {
  * - run 列表把它标成红点（用户会以为是自己把工程改坏了）；
  * - 对话视图给这一轮打红边「（这一轮失败了…）」，而同一个 run 的通知条写着「已中止」。
  *
- * 判别顺序（**先 stopReason 后 ok**）与 `runDoneNotice` 是同一条语义，钉在单测里。
+ * 判别顺序归 `stopReasonClass`（**先 stopReason 后 ok**），与 `runDoneNotice` 同一条语义。
+ * 这里只是它的一元投影 —— 别在两处各写一遍：
+ * `suspended` 也不是失败（挂着等人，`ok` 同样可能是 false），旧实现漏掉它。
  */
 export function runIsFailure(r) {
-    if (r.stopReason === 'aborted')
-        return false;
-    return !r.ok;
+    return stopReasonClass(r) === 'failed';
 }
 /** `MessageParam.content` 可能是 string，也可能是 content block 数组 —— 只取文本块 */
 export function textOfContent(content) {
@@ -194,7 +233,7 @@ export function mergeConversation(messages, runs, sessionId) {
             continue;
         if ((r.sessionId ?? null) !== sessionId)
             continue;
-        const prompt = (r.prompt ?? '').trim();
+        const prompt = (r.note?.prompt ?? '').trim();
         if (prompt.length === 0 || seen.has(prompt))
             continue;
         seen.add(prompt);
@@ -402,16 +441,192 @@ export function comparability(a, b) {
  * 但原因要可查）⇒ 中止时 `ok` 也是 **false**。所以必须**先**认 `stopReason`：
  * 反过来先看 `ok`，用户按的「中止」就会被显示成一句吓人的「run 失败」。
  * 这个顺序错一次很难在 code review 里看出来，所以钉在单测里。
+ *
+ * 四类模板（`stopReasonClass`）：原文一起给 —— 「撞到预算护栏」是给人读的，
+ * `budget_exceeded` 是给人 grep 的，两者都要。
  */
 export function runDoneNotice(ev) {
-    if (ev.stopReason === 'aborted') {
+    const cls = stopReasonClass(ev);
+    const text = stopReasonText(ev.stopReason);
+    // 中文短语与标识符不同才拼（未识别的串 `text === sr`，只显示一次）
+    const why = text && text !== ev.stopReason ? `${text} · ${ev.stopReason}` : ev.stopReason;
+    if (cls === 'aborted') {
         return { text: 'run 已中止（trace 保住了）', isError: false };
     }
-    if (!ev.ok) {
-        return { text: `run 失败（${ev.stopReason}）：${ev.error || '未知原因'}`, isError: true };
+    if (cls === 'suspended') {
+        // 挂起不是结束：run 带着完整消息历史等人裁决，之后从原处继续。
+        // 旧文案把它写成「run 完成（suspended）」—— 那是在说一件没发生的事。
+        return { text: `run 停在审批（${why}）：裁决之后从挂起处继续`, isError: false };
+    }
+    if (cls === 'failed') {
+        return { text: `run 失败（${why}）：${ev.error || '未知原因'}`, isError: true };
     }
     return { text: `run 完成（${ev.stopReason}）`, isError: false };
 }
+function ledNum(n) {
+    return typeof n === 'number' && Number.isFinite(n) && n > 0 ? n : 0;
+}
+/**
+ * 一条 run 的账：`3 轮 · 7 次工具 · 2 失败 · in 8.1k / out 1.5k · cache 6.2k · 77% · $0.014`。
+ *
+ * 为什么值得单独一条纯函数：这五个数此前**一个都没有**（页面上只有 footer 的 in / out），
+ * 而它们全都在 `Trace.totalUsage` 与 span 上。其中**cache 命中率**是这类面板最该给、又最常
+ * 缺的一个数 —— 它直接对应账单（缓存读的单价通常只有未命中的 1/10）。
+ *
+ * 三条口径（都是「不给假读数」）：
+ * - 分母为 0 / 字段缺失的那一项**整项不出现**，不显示 `0%` / `$0.0000`。
+ *   「成本是 0」与「没有单价表」是两件事，折成同一个 `$0` 就是在说谎。
+ * - cache 命中率 = 读 /(读 + 写 + 未命中输入)。**分母含缓存写入**：只算读除以输入会让
+ *   「刚写了一大块缓存」的那次 run 显示成 100% 命中 —— 那正是最容易误读的时刻。
+ * - 轮次/工具数**从 span 与事件里数**，不读 `AgentRunResult.iterations`：后者不在 trace 上
+ *   （`engine/loop.ts` 只把它写进返回值），而面板手上只有 trace。数出来的口径写在 title 里。
+ */
+export function runLedger(trace, budget) {
+    const items = [];
+    if (!trace)
+        return items;
+    const spans = Array.isArray(trace.spans) ? trace.spans : [];
+    const turns = spans.filter((s) => s && s.kind === 'llm.turn').length;
+    if (turns > 0)
+        items.push({
+            key: '轮次',
+            value: `${turns} 轮`,
+            title: '按 llm.turn span 数（一次模型往返 = 一轮）',
+        });
+    let toolCalls = 0;
+    for (const s of spans) {
+        for (const ev of s?.events ?? []) {
+            if (ev && ev.name === 'tool.input')
+                toolCalls += 1;
+        }
+    }
+    if (toolCalls > 0) {
+        items.push({
+            key: '工具',
+            value: `${fmtCount(toolCalls)} 次`,
+            title: '按 tool.input 事件数（普通工具不建 span）',
+        });
+    }
+    const errors = spans.filter((s) => s && s.status === 'error').length;
+    if (errors > 0) {
+        items.push({ key: '失败', value: `${fmtCount(errors)} 个 span`, tone: 'err' });
+    }
+    const u = trace.totalUsage ?? null;
+    if (u) {
+        const inTok = ledNum(u.inputTokens);
+        const outTok = ledNum(u.outputTokens);
+        if (inTok + outTok > 0) {
+            items.push({ key: 'in / out', value: `${fmtCount(inTok)} / ${fmtCount(outTok)}` });
+        }
+        const cr = ledNum(u.cacheReadTokens);
+        const cc = ledNum(u.cacheCreationTokens);
+        const miss = inTok;
+        const base = cr + cc + miss;
+        if (cr + cc > 0 && base > 0) {
+            const rate = Math.round((cr / base) * 100);
+            items.push({
+                key: 'cache',
+                value: `${fmtCount(cr)} 读 · ${rate}% 命中`,
+                title: `缓存读 ${cr} / 缓存写 ${cc} / 未命中输入 ${miss}；命中率 = 读 ÷（读 + 写 + 未命中）`,
+            });
+        }
+        // 成本：只有框架给得出估算时才显示（无公开单价的服务商给不出 —— 那是「不知道」，
+        // 不是「花了 0 元」）
+        if (typeof u.costEstimate === 'number' && Number.isFinite(u.costEstimate)) {
+            const cap = ledNum(budget?.maxCostUsd);
+            items.push({
+                key: '成本',
+                value: cap > 0 ? `$${u.costEstimate.toFixed(4)} / $${cap}` : `$${u.costEstimate.toFixed(4)}`,
+                title: '由 token × 单价估算（框架的总账，不是账单）',
+            });
+        }
+    }
+    const root = spans.find((s) => s && s.kind === 'run') ?? spans[0];
+    const model = root?.attributes?.model;
+    if (typeof model === 'string' && model.length > 0)
+        items.push({ key: '模型', value: model });
+    return items;
+}
+/**
+ * 一条 run 是否命中关键词。大小写不敏感、纯子串（不做正则：`(` 之类会让输入直接炸）。
+ *
+ * 搜的字段包含 `stopReasonText`（中文短语）—— 用户想找「撞预算那条」时会打「预算」，
+ * 而数据里存的是 `budget_exceeded`。只搜原文等于逼人记住标识符。
+ */
+export function matchRunQuery(r, q) {
+    const needle = q.trim().toLowerCase();
+    if (needle.length === 0)
+        return true;
+    const fields = [
+        r.note?.prompt ?? '',
+        r.name ?? '',
+        r.note?.workdir ?? '',
+        r.stopReason ?? '',
+        stopReasonText(r.stopReason ?? null),
+        r.traceId,
+    ];
+    return fields.some((f) => String(f).toLowerCase().includes(needle));
+}
+/**
+ * 列表过滤：关键词 **且**（可选）「只看异常」。
+ *
+ * 「异常」= `stopReasonClass !== 'ok'`（失败 / 中止 / 等审批三种都算）。为什么这三种都算：
+ * 用户点「只看异常」时想找的是「没正常跑完的那些」，而中止与挂起恰恰是最需要回看的两类 ——
+ * 只过滤 `ok === false` 会把挂起的 run（trace 状态是 ok）漏掉。
+ */
+export function filterRuns(runs, q, opts = {}) {
+    const onlyAbnormal = opts.onlyAbnormal === true;
+    return runs.filter((r) => {
+        if (onlyAbnormal && stopReasonClass({ ok: r.ok, stopReason: r.stopReason ?? null }) === 'ok') {
+            return false;
+        }
+        return matchRunQuery(r, q);
+    });
+}
+// ---------- ⑦ 深链 / 重跑 ----------
+/**
+ * `location.search` → 要打开的 run id（`?run=<traceId>`）。
+ *
+ * 解析失败 / 没有这个参数 / 空串一律 `null`（= 照旧打开最新那条）。不抛：一个手改坏的
+ * URL 不该让面板白屏。
+ */
+export function runIdFromSearch(search) {
+    const s = String(search ?? '').trim();
+    if (s.length === 0)
+        return null;
+    let params;
+    try {
+        params = new URLSearchParams(s.startsWith('?') ? s.slice(1) : s);
+    }
+    catch {
+        return null;
+    }
+    const id = (params.get('run') ?? '').trim();
+    return id.length > 0 ? id : null;
+}
+/**
+ * 「重跑」要回填的那四个输入（`RunNote` 里全都有 —— 这正是它值得存的原因）。
+ *
+ * 三条口径：
+ * - **不自动提交**：回填之后由用户按运行。一个自己跑起来的按钮会在误触时花钱。
+ * - 能力选择**过滤掉已失效的 token**（能力被删过），过滤后为空则回落全量 ——
+ *   `toolSources: []` 在框架侧是「每个 provider 都成了孤儿」的纯陷阱值。
+ * - `note` 缺失（trace 不是 dev 环起的 / 已被淘汰）⇒ `null`，调用方负责说「这条 run 没有
+ *   开发期元信息，重跑不了」。不猜一个空的 prompt 出来。
+ */
+export function rerunFromNote(note, all) {
+    if (!note)
+        return null;
+    const picked = note.toolSources === null || note.toolSources === undefined
+        ? [...all]
+        : filterSelected(note.toolSources, all);
+    return {
+        prompt: typeof note.prompt === 'string' ? note.prompt : '',
+        workdir: typeof note.workdir === 'string' ? note.workdir : '',
+        toolSources: picked.length > 0 ? picked : [...all],
+        multiTurn: note.multiTurn === true,
+    };
+}
 // ---------- 路径显示 ----------
 /**
  * 把绝对路径压短给面板看（`~/proj/a`）。
@@ -597,3 +812,55 @@ export function collapseDecision(text, opts = {}) {
         : '';
     return { collapsed, lines, chars, hint };
 }
+// ---------- ④ 右栏三块的标题栏读数：**收起不等于失明** ----------
+/**
+ * 右栏三块（调用树 / 能力排行 / 回复）都能折叠（2026-11-12 ref-panel-panes）。
+ *
+ * 折叠后标题栏是这一块**唯一**还看得见的东西 ⇒ 它必须自己回答「值不值得展开」。
+ * 这不是装饰：把整块收起来却一个数都不留，用户就只能在「占屏」与「失明」之间二选一 ——
+ * 那恰好是这次改动之前的状态（三块挤在一列，谁都不够高）。
+ *
+ * 三条都是**纯格式化**（不量 DOM、不读时钟、不看窗口），所以它们进得了单测；
+ * 面板那边只负责把返回值写进 `textContent`。
+ */
+function fmtCount(n) {
+    const v = Number.isFinite(n) && n > 0 ? n : 0;
+    if (v < 1000)
+        return String(v);
+    const k = v / 1000;
+    // 一万以上不保留小数：标题栏只有一行，`12.3k` 比 `12k` 多不出信息
+    return `${k < 10 ? k.toFixed(1) : String(Math.round(k))}`.replace(/\.0$/, '') + 'k';
+}
+/** 调用树：`58 span`。span 数是这一块「有没有东西看」的最小信号，也随在飞帧增长 */
+export function traceMeta(spanCount) {
+    return `${fmtCount(spanCount)} span`;
+}
+/**
+ * 能力排行：`7 项 · 24 次 · 2 失败`。
+ *
+ * 失败数**只在真的有人失败时**出现 —— 恒挂一个「0 失败」等于给每一行加噪声，
+ * 与 `collapseDecision` 的 `hint` 同一条纪律（空的话就别占位置）。
+ * `errors` 的语义是**工具/护栏报错次数**（`summarizeTrace` 的账），不是「有几个能力出错」。
+ */
+export function summaryMeta(rows) {
+    if (!Array.isArray(rows) || rows.length === 0)
+        return '0 项';
+    let calls = 0;
+    let errors = 0;
+    for (const r of rows) {
+        calls += Number.isFinite(r?.calls) ? r.calls : 0;
+        errors += Number.isFinite(r?.errors) ? r.errors : 0;
+    }
+    const head = `${rows.length} 项 · ${fmtCount(calls)} 次`;
+    return errors > 0 ? `${head} · ${fmtCount(errors)} 失败` : head;
+}
+/**
+ * 回复：`32 行 · 1.4k 字符`。
+ *
+ * 行/字符数的算法**复用 `collapseDecision`**（同一个 `split('\n')` 口径）——
+ * 标题栏说「32 行」而正文折叠控件说「共 31 行」是最难查的一类不一致。
+ */
+export function replyMeta(text) {
+    const d = collapseDecision(text);
+    return d.lines > 1 ? `${d.lines} 行 · ${fmtCount(d.chars)} 字符` : `${fmtCount(d.chars)} 字符`;
+}

package/dist/templates/package.json

@@ -11,10 +11,10 @@
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@migor/agentia": "^0.10.9"
+    "@migor/agentia": "^0.10.10"
   },
   "devDependencies": {
-    "@migor/cli": "^0.10.9",
+    "@migor/cli": "^0.10.10",
     "tsx": "^4.19.0",
     "typescript": "^7.0.2",
     "@types/node": "^22.0.0"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@migor/cli",
-  "version": "0.10.9",
+  "version": "0.10.10",
   "description": "CLI for the Agentia framework: scaffold a project, generate a capability, and open a local trace inspector for runs.",
   "type": "module",
   "bin": {