@migor/cli 0.9.1 → 0.9.2

package/CHANGELOG.md

@@ -5,7 +5,64 @@
 （0.x 阶段：minor 可含破坏性变更，每个破坏性变更都在对应版本的「迁移」小节里写明）。
 决策的完整证据链在 `docs/spec.md` §10（带时间线的决策日志）。
 
-## [Unreleased]
+## [0.9.2] - 2026-09-22
+
+> 本版主题（窗口 `0.9.1 → 0.9.2`）：**dev 面板的可读性** —— 模型正文按 Markdown 渲染、
+> 滚动分层（整页不滚、只滚该滚的那块）、长正文默认折叠。
+> **无破坏性变更**：框架公共 API 与脚手架模板形态逐字未变。
+
+### 新增 · dev 面板的正文 Markdown 渲染
+
+- **模型正文按 Markdown 渲染**（最终回复 + 对话视图的助手轮）：标题 / 粗斜体 / 行内码 /
+  围栏码（带语言标注）/ 列表 / 引用 / 分隔线 / 链接。此前是一整块 `<pre>` 纯文本，
+  长回复里的列表与代码块糊成一坨。
+- 解析器是**自己写的**（`packages/cli/src/markdown.ts`，纯逻辑、零依赖、带单测）：
+  引 `marked` + `DOMPurify` 等于把两份第三方产物塞进 dev 链路，而且它们**没法被本仓单测验证**；
+  这套子集不到 200 行，每条规则都有用例。安全前提是**按构造不产生 HTML** —— 解析器只产出
+  token 树（没有「HTML 透传」这一类），渲染层只准用 `createElement` / `textContent`
+  ⇒ 模型输出里的 `<script>` 只会是字面文本。链接协议过白名单（`http` / `https` / `mailto`），
+  不合法（`javascript:` 等）**整条降级成字面文本**（连 `[]()` 一起显示）。用户轮保持字面 ——
+  那是「我打的字」，按 Markdown 重排会像面板改过我的输入。
+
+### 变更 · 面板滚动分层：整页不滚，只滚该滚的那块
+
+- 此前右栏没有高度上限 ⇒ 内容一长就是**整页滚动**，而 `footer` 还粘在底部盖住内容。
+  现在改成应用外壳：`html/body` 卡 100vh、`body` 不滚；左栏页签固定、列表自己滚；
+  右栏**只有调用树是滚动区**（它随 span 数无界增长），回复 / 能力排行 / 用量固定在下方、
+  各有上限（回复很长时在**它自己那块**里滚，而不是把树推出屏幕）。
+- 窄屏（≤860px）回落成单列 + 整页滚动 —— 两栏并排在那个宽度下都不可用。
+
+### 变更 · 长消息折叠：明确的「展开 / 收起」
+
+- 超过 12 行或 1200 字符的正文默认折叠（卡 216px + 底部渐隐），下方左对齐一个
+  「展开全文（共 N 行）▾」按钮，展开后变「收起 ▴」。**短正文不挂控件**（挂一个是噪声）。
+- 判定走纯逻辑 `collapseDecision`（带单测）：按**行数 + 字符数**，不量像素 —— 像素阈值在
+  字体 / 缩放 / 窄屏下会漂，同一个回复在不同机器上折叠与否都不一样。展开态活在渲染之外
+  （面板每次全量重画，状态留在 DOM 里会被下一次重画合上）。
+
+### 修复
+
+- **CLI 套件里两条文件监视用例在全链下稳定假红**（`packages/cli/test/panel-logic.test.mjs`）：
+  夹具原来「**写一次**、然后轮询等满 15 秒」，而真 fs 的监视器**建立是异步的**（`fs.watch`
+  返回 ≠ 底下 FSEvents 流已开始投递）—— 那一次写整个漏掉时，**等多久都没用**。复现条件最后
+  定位到 **stdout 被管道捕获**（`verify-all.sh` 的 `out=$(bash -c …)` 与 CI 都是这么跑的）：
+  管道下稳定红、重定向到文件稳定绿；单跑套件也是绿的。改成 `writeUntilSeen`（反复写、直到
+  回调真的来，上限 15 秒）—— **断言没放宽**（那个路径仍必须触发一次回调，只是不再要求
+  「第一次写就被看见」），四条「不该触发」的负向用例一条未动。
+  ⚠️ **仅测试侧，无使用者可见行为**：生产里 dev 环**先建立监视、再对外服务**，不存在
+  「`watchTree()` 一返回用户就改文件」这个窗口。
+
+### 文档
+
+- `docs/usage-guide.md` §2.2：按使用者口吻补三段 —— Markdown 渲染口径（含协议白名单与
+  「用户轮保持字面」）、滚动三层各管一段、长正文折叠阈值与展开控件位置。
+- `docs/guards.md` §1.4：新增 `markdown.test.mjs` 一行（两条安全断言：按构造不产生 HTML、
+  链接协议白名单 + 两条反向验证），并把 `inspector.test.mjs` 那行的反向全覆盖**扩面**记上
+  （覆盖所有自建模块 + 四条页面级不变量）—— 是**扩面**，别读成「多了五条守卫」。
+- `docs/spec.md` §10 2026-09-22 **⑨**：本轮三处可读性改动的现场证据与修法，外加两条踩坑
+  （反向验证的变异体**必须能编译**，否则构建先失败、门禁空跑；对被格式化过的文件做 patch
+  时 `old_string` 用了格式化**前**的版本，靠「改完立刻回读」才发现）。
+- `docs/plans/2026-09-22-dev-debug-loop.md`：补本轮三处的落地记录。
 
 ## [0.9.1] - 2026-09-22
 
@@ -44,9 +101,12 @@
 ### 文档
 
 - `docs/usage-guide.md` §2.2：补「右栏是实时的」（含两条边界）与工作目录的三个点击语义。
-- `docs/guards.md` §1.4：新增五条守卫登记（见该节）。
-- `docs/plans/2026-09-22-dev-debug-loop.md`：§D7 那条评审补充标注 **P1b 已落地**。
-- `docs/spec.md` §10 2026-09-22 ⑦：本轮三个缺陷的现场证据与修法（含「同一条事实两个表面」的第 N 个影子）。
+- `docs/guards.md` §1.4：本轮在**既有三行**登记上扩面（`panel-logic.test.mjs` 增四组折回 / 归属 /
+  浏览目标 / 选文件后的 prompt，`inspector.test.mjs` 增三项 HTTP 面，`e2e-dev.ts` 增第 7-bis 步），
+  见该节 —— 是**扩面**不是新增行，别把它读成「多了五条守卫」。
+- `docs/plans/2026-09-22-dev-debug-loop.md`：§D7 那条评审补充标注 **P1b 已落地**（增量出口接线）。
+- `docs/spec.md` §10 2026-09-22 **⑧**：本轮三处体验缺陷的现场证据与修法（右栏实时 / 回复被擦 /
+  选择器），外加一条发版流程教训（反向验证脚本必须先 commit）。
 
 ## [0.9.0] - 2026-09-22
 
@@ -1186,7 +1246,8 @@
 首个公开发布：`@migor/agentia` + `@migor/cli`（scope `@migor/*`），两包版本同步。
 框架本体单包；CLI 独立成包（workspaces）。
 
-[Unreleased]: https://github.com/retrychx/agentia/compare/v0.9.1...HEAD
+[Unreleased]: https://github.com/retrychx/agentia/compare/v0.9.2...HEAD
+[0.9.2]: https://github.com/retrychx/agentia/releases/tag/v0.9.2
 [0.9.1]: https://github.com/retrychx/agentia/releases/tag/v0.9.1
 [0.9.0]: https://github.com/retrychx/agentia/releases/tag/v0.9.0
 [0.8.3]: https://github.com/retrychx/agentia/releases/tag/v0.8.3

package/dist/AGENTS.md

@@ -145,6 +145,19 @@ npx agentia --version            # CLI 版本（= -v）
   早先那些 span 不会回来（收尾的整棵 trace 会补齐它们），**收尾那份永远覆盖在飞的这份**。
 - 它只影响「此刻看到什么」，**不影响 run 本身**，也不影响落盘的 trace（那是另一条缝）。
 
+**模型正文按 Markdown 渲染**（最终回复 + 对话视图的助手轮）：标题 / 粗斜体 / 行内码 / 围栏码 /
+列表 / 引用 / 分隔线 / 链接。解析器是本仓自己写的（零依赖），**只产出 token 树、不碰 HTML** ——
+模型输出里的 `<script>` 只会显示成字面文本；链接只认 `http` / `https` / `mailto`，其余协议
+（`javascript:` 等）**整条降级成字面文本**（连 `[]()` 一起显示）。你自己那一轮保持字面 ——
+那是你打的字，面板不改写它。
+
+**长正文默认折叠**：超过 12 行或 1200 字符的正文卡在 216px + 底部渐隐，下方左对齐一个
+「展开全文（共 N 行）▾」，展开后变「收起 ▴」。**短正文不挂控件**。
+
+**滚动分三层，各管一段**：整页**不滚**（输入条永远贴在底部，不会被内容推走）；左栏列表自己滚；
+右栏**只有调用树是滚动区** —— 它随 span 数无界增长，而回复 / 能力排行 / 用量固定在下方、
+各有上限（回复很长时在**它自己那块**里滚，不会把树挤出屏幕）。窄屏（≤860px）回落成单列 + 整页滚动。
+
 **为什么用 `agentia dev` 而不是 `tsx watch`**：`agentia dev` 自己 import 你的 `src/app.ts` 并驱动它，
 于是**它才是调用方**，四个输入才可能生效。它也**自己管文件监视**（不再叠一层 `tsx watch`）：
 

package/dist/inspector-page.html

@@ -43,15 +43,46 @@
       }
       #banner.err { border-color: var(--err); background: #1d1416; color: var(--err); }
 
+      /* 应用外壳：**整页不滚**，滚动交给各自的栏。
+         为什么：内容一长就整页滚的话，「我正在看调用树」与「我在读回复」会互相把对方推走，
+         而且 footer 还粘在底部盖住内容 —— 三个滚动条（页面 / 树 / 展开的行）叠在一起最难用。 */
+      html, body { height: 100%; }
+      body { overflow: hidden; display: flex; flex-direction: column; }
+      header, #banner, footer { flex: none; }
       main {
+        flex: 1 1 auto; min-height: 0;
         display: grid; grid-template-columns: 300px minmax(0, 1fr); gap: 14px;
         padding: 14px 20px;
       }
       aside, section {
         background: var(--card); border: 1px solid var(--border); border-radius: 6px;
+        min-height: 0;
+      }
+      /* 左栏：页签/清空条固定，列表自己滚 */
+      aside { display: flex; flex-direction: column; overflow: hidden; }
+      #tabs, #chat-bar { flex: none; }
+      #runs, #chat { flex: 1 1 auto; min-height: 0; overflow: auto; }
+      /* 右栏分层：`#trace` 是**唯一**无界增长的部分（它随 span 数长）⇒ 只有它 flex 撑开并滚；
+         回复 / 能力排行 / 用量固定在下方，各自有上限（回复很长时在**它自己那块**里滚，
+         而不是把树推出屏幕 —— 这与「看树」和「读回复」两个动作各自独立是一致的）。 */
+      section {
+        padding: 14px; font-family: var(--mono); font-size: 12px;
+        display: flex; flex-direction: column; overflow: hidden;
+      }
+      #ttl { flex: none; }
+      #trace { flex: 1 1 auto; min-height: 140px; overflow: auto; }
+      #summary, #reply, .usage { flex: none; max-height: 38vh; overflow: auto; }
+      /* 窄屏：两栏并排已经太窄 ⇒ 回到单列 + 整页滚动（此时「整页滚」才是唯一合理的形态） */
+      @media (max-width: 860px) {
+        html, body { height: auto; }
+        body { overflow: visible; }
+        main { grid-template-columns: minmax(0, 1fr); }
+        aside { overflow: visible; }
+        section { overflow: visible; }
+        #runs, #chat, #trace { overflow: visible; }
+        #trace { min-height: 320px; }
+        #summary, #reply, .usage { max-height: none; }
       }
-      aside { overflow: hidden auto; max-height: calc(100vh - 200px); }
-      section { padding: 14px; min-height: 240px; font-family: var(--mono); font-size: 12px; overflow: auto; }
       .run {
         display: block; width: 100%; text-align: left; cursor: pointer;
         background: none; border: 0; border-bottom: 1px solid var(--border);
@@ -102,10 +133,50 @@
 
       #reply {
         margin: 14px 0 0; padding: 10px; border: 1px solid var(--border); border-radius: 4px;
-        background: #0e0e10; white-space: pre-wrap; word-break: break-word; color: var(--muted);
+        background: #0e0e10; word-break: break-word; color: var(--muted);
       }
       #reply[hidden] { display: none; }
 
+      /* —— 模型正文：Markdown 渲染 ——
+         `.md` 里所有元素都是 createElement 造出来的（解析器不产生 HTML，渲染器不用 innerHTML），
+         所以这里可以有排版规则，但没有一处「把字符串塞进 DOM」。 */
+      .md { white-space: normal; word-break: break-word; line-height: 1.6; }
+      .md-p { margin: 0 0 6px; }
+      .md-p:last-child, .md-list:last-child, .md-pre:last-child { margin-bottom: 0; }
+      .md-h { margin: 10px 0 4px; font-size: 12.5px; color: var(--text); }
+      .md-h:first-child { margin-top: 0; }
+      .md-list { margin: 0 0 6px; padding-left: 18px; }
+      .md-list li { margin: 1px 0; }
+      .md-pre {
+        position: relative; margin: 0 0 6px; padding: 8px; background: #0e0e10;
+        border: 1px solid var(--border); border-radius: 4px; overflow: auto;
+      }
+      .md-pre code { font-family: var(--mono); font-size: 11.5px; white-space: pre; }
+      .md-lang { position: absolute; top: 3px; right: 7px; color: var(--faint); font-size: 9.5px; }
+      .md-c { background: #1b1b1f; border-radius: 3px; padding: 0 3px; font-family: var(--mono); }
+      .md blockquote { margin: 0 0 6px; padding-left: 9px; border-left: 2px solid var(--border); color: var(--muted); }
+      .md a { color: var(--ice); }
+      .md hr { border: 0; border-top: 1px solid var(--border); margin: 8px 0; }
+      /* 正文用无衬线正文栈（模型输出是散文，等宽栈读它更累）；码块与行内码仍是等宽。
+         挂在 `.md-wrap`（渲染器的包装节点）而不是 `#reply .md, .turn .md`：单一类选择器
+         既不用管特异性排序，也让「哪块是模型正文」只由一处决定。 */
+      .md-wrap {
+        font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", sans-serif;
+        font-size: 12px;
+      }
+      /* 折叠态：卡高度 + 底部渐隐（渐隐是「下面还有」的视觉提示；用 mask 所以不影响选中复制） */
+      .md-clamped {
+        max-height: 216px; overflow: hidden;
+        -webkit-mask-image: linear-gradient(180deg, #000 78%, transparent 100%);
+        mask-image: linear-gradient(180deg, #000 78%, transparent 100%);
+      }
+      /* 展开控件：正文**下方**左对齐（长正文里没人会去右上角找一个 10px 的箭头） */
+      .md-toggle {
+        margin-top: 6px; background: var(--card); border: 1px solid var(--border); border-radius: 4px;
+        color: var(--text); padding: 4px 9px; font: inherit; font-size: 11px; cursor: pointer;
+      }
+      .md-toggle:hover { border-color: var(--ice); }
+
       /* 输入条：固定在底部、横跨两栏、分两行（四个控件挤一行会太窄） */
       footer {
         position: sticky; bottom: 0; margin-top: 4px;
@@ -241,11 +312,13 @@
 
     <script type="module">
       import { createTraceView, playTrace, summarizeTrace, renderSummary } from './index.js';
+      import { parseMarkdown } from './markdown.js';
       import {
         HISTORY_DRAFT,
         applyTraceEvent,
         browseTarget,
         capabilityBadge,
+        collapseDecision,
         emptyTraceAccumulator,
         historyStep,
         historyText,
@@ -487,6 +560,123 @@
         }
       }
 
+      // ---------- 模型正文的渲染（Markdown + 长了就折叠） ----------
+
+      /**
+       * 展开态**活在渲染之外**（与 trace-view 的 `expanded` 同一个理由）：面板每次全量重画，
+       * 状态留在 DOM 里就会被下一次重画合上 —— 而「刚点开的那段自己收起来了」是最烦人的那种 bug。
+       * 键要**跨重画稳定**：回复用 traceId、对话轮用下标（会话是只追加的，下标稳定）。
+       */
+      const expandedMsgs = new Set();
+
+      /** 行内 token → DOM。只走 createElement / textContent —— 见 markdown.ts 的安全前提 */
+      function appendInline(parent, inline) {
+        for (const n of inline) {
+          if (n.type === 'text') {
+            parent.appendChild(document.createTextNode(n.text));
+          } else if (n.type === 'code') {
+            const c = document.createElement('code');
+            c.className = 'md-c';
+            c.textContent = n.text;
+            parent.appendChild(c);
+          } else if (n.type === 'link') {
+            // href 已在解析层过白名单（isSafeHref）；target/rel 防止把这面板当跳板
+            const a = document.createElement('a');
+            a.href = n.href;
+            a.textContent = n.text;
+            a.target = '_blank';
+            a.rel = 'noopener noreferrer';
+            parent.appendChild(a);
+          } else {
+            const w = document.createElement(n.type === 'strong' ? 'strong' : 'em');
+            appendInline(w, n.children);
+            parent.appendChild(w);
+          }
+        }
+      }
+
+      /** Markdown → DOM。块级只认 markdown.ts 的那六种；这里**没有** innerHTML —— 一个都没有 */
+      function renderMarkdownInto(el, text) {
+        for (const b of parseMarkdown(text)) {
+          if (b.type === 'hr') {
+            el.appendChild(document.createElement('hr'));
+          } else if (b.type === 'code') {
+            const pre = document.createElement('pre');
+            pre.className = 'md-pre';
+            if (b.lang) {
+              const tag = document.createElement('span');
+              tag.className = 'md-lang';
+              tag.textContent = b.lang;
+              pre.appendChild(tag);
+            }
+            const code = document.createElement('code');
+            code.textContent = b.text;
+            pre.appendChild(code);
+            el.appendChild(pre);
+          } else if (b.type === 'list') {
+            const list = document.createElement(b.ordered ? 'ol' : 'ul');
+            list.className = 'md-list';
+            for (const item of b.items) {
+              const li = document.createElement('li');
+              appendInline(li, item);
+              list.appendChild(li);
+            }
+            el.appendChild(list);
+          } else if (b.type === 'quote') {
+            const q = document.createElement('blockquote');
+            appendInline(q, b.inline);
+            el.appendChild(q);
+          } else {
+            const isH = b.type === 'h';
+            const node = document.createElement(isH ? `h${Math.min(6, Math.max(1, b.level))}` : 'p');
+            node.className = isH ? 'md-h' : 'md-p';
+            appendInline(node, b.inline);
+            el.appendChild(node);
+          }
+        }
+      }
+
+      /**
+       * 一段**模型正文**（最终回复 / 助手轮）→ 填进 `wrap`。
+       *
+       * 折叠控件放在正文**下方、左对齐**，不在行尾悬 caret：trace-view 那边 caret 靠右是因为
+       * 行是 nowrap 的表格状布局，「右端」本来就是「这一行结束了」的位置；正文块不是那个形态，
+       * 一个 10px 的箭头挂在右上角没人会去找。判定走 `collapseDecision`（纯逻辑、带单测）。
+       */
+      function renderMessage(wrap, text, key) {
+        wrap.classList.add('md-wrap');
+        const body = document.createElement('div');
+        body.className = 'md';
+        const d = collapseDecision(text);
+        const open = expandedMsgs.has(key);
+        if (d.collapsed && !open) body.classList.add('md-clamped');
+        renderMarkdownInto(body, text);
+        wrap.appendChild(body);
+        if (!d.collapsed) return; // 短正文不挂控件（挂一个「展开」是噪声）
+        const btn = document.createElement('button');
+        btn.type = 'button';
+        btn.className = 'md-toggle';
+        btn.textContent = open ? '收起 ▴' : `${d.hint} ▾`;
+        btn.addEventListener('click', () => {
+          if (expandedMsgs.has(key)) expandedMsgs.delete(key);
+          else expandedMsgs.add(key);
+          renderChat();
+          renderReply();
+        });
+        wrap.appendChild(btn);
+      }
+
+      /** 右栏底部那块回复正文。key 带 traceId ⇒ 换一轮就是一个新的折叠态 */
+      function renderReply() {
+        replyEl.replaceChildren();
+        if (!state.reply) {
+          replyEl.hidden = true;
+          return;
+        }
+        replyEl.hidden = false;
+        renderMessage(replyEl, state.reply, `reply:${state.replyFor ?? ''}`);
+      }
+
       // ---------- 对话流（只在多轮开 + 有会话文件时出现） ----------
       function renderChat() {
         const dev = state.dev;
@@ -514,7 +704,10 @@
           d.textContent = '会话文件还是空的。跑一次多轮 run 就有了。';
           chatEl.appendChild(d);
         }
+        // 下标当折叠态的键：会话只追加 ⇒ 下标跨重画稳定
+        let ti = -1;
         for (const t of turns) {
+          ti++;
           const box = document.createElement('div');
           box.className = 'turn' + (t.failed ? ' failed' : t.aborted ? ' aborted' : '');
           const who = document.createElement('div');
@@ -530,7 +723,10 @@
             who2.textContent = 'assistant';
             const a = document.createElement('div');
             a.className = 'msg';
-            a.textContent = t.assistant;
+            // 助手轮是**模型正文** ⇒ Markdown 渲染 + 长了折叠。
+            // 用户轮保持字面（`u.textContent = t.user` 上面那两行没动）—— 那是「我打的字」，
+            // 把它按 Markdown 重排会让面板看起来像改过我的输入。
+            renderMessage(a, t.assistant, `turn:${ti}`);
             box.append(who2, a);
           } else if (t.failed) {
             // 失败轮**标失败**，不假装那轮没发生（它没回写会话文件，靠 run 列表 join 出来）
@@ -574,8 +770,7 @@
         state.live = emptyTraceAccumulator();
         state.reply = '';
         state.replyFor = null;
-        replyEl.hidden = true;
-        replyEl.textContent = '';
+        renderReply();
         summaryEl.replaceChildren();
         usageEl.hidden = true;
         ttlEl.textContent = '';
@@ -672,8 +867,7 @@
         if (!replyBelongsTo(id, state.replyFor)) {
           state.reply = '';
           state.replyFor = null;
-          replyEl.hidden = true;
-          replyEl.textContent = '';
+          renderReply();
         }
         renderList();
       }
@@ -920,8 +1114,8 @@
           // 那时不能把回复当「别人的」擦掉（见 panel-logic 的 replyBelongsTo）
           state.replyFor = ev.traceId;
           state.live = null;
-          replyEl.hidden = state.reply.length === 0;
-          replyEl.textContent = state.reply;
+          // Markdown 渲染 + 长了折叠（渲染层不认识正文语义，只按 token 建节点）
+          renderReply();
           // 判别顺序（先 stopReason 后 ok）是**语义**，抽在 panel-logic 里并带单测 ——
           // 中止的 run `ok` 也是 false（引擎刻意给 aborted 带结构化 error），
           // 顺序反了就会把「我按了中止」显示成「run 失败」。

package/dist/inspector.js

@@ -226,6 +226,9 @@ const STATIC = new Map([
     ['summary.js', join(ASSETS, 'summary.js')],
     ['trace-view.css', join(ASSETS, 'trace-view.css')],
     ['panel-logic.js', join(HERE, 'panel-logic.js')],
+    // 面板的 Markdown 解析器（零依赖、按构造不产生 HTML —— 见 src/markdown.ts 的头注）。
+    // 与 panel-logic.js 同处 dist 根：两个都是 CLI 自己编译出来的模块，单测直接 import 它们。
+    ['markdown.js', join(HERE, 'markdown.js')],
 ]);
 /** 没有 dev 钩子时的状态（面板据此隐藏输入条） */
 function unavailableDevState() {

package/dist/markdown.js

@@ -0,0 +1,243 @@
+/**
+ * 面板的 **Markdown 最小渲染器** —— 纯逻辑、零 DOM、零依赖。
+ *
+ * 为什么自己写而不引 `marked` / `markdown-it`：
+ * - **零运行时依赖是本 CLI 的硬承诺**（`package.json` 里没有 `dependencies`）。为了面板把一份
+ *   解析器 + 一份消毒器（DOMPurify 之类）塞进 dist，等于在 dev 链路里引入两个第三方供应链面，
+ *   而它们的产物**没法被本仓的单测验证**（我们只能验「我写的那部分」）。
+ * - 面板只需要**模型正文**这一种输入可读：标题 / 粗体 / 斜体 / 行内码 / 围栏码 / 列表 /
+ *   引用 / 分隔线 / 链接。这套子集手写不到 200 行，且**每条规则都能配一条单测**。
+ * - 最要紧的是**它按构造不产生 HTML**：返回值是一棵 token 树（`MdBlock` / `MdInline`），
+ *   没有任何「原样透传的 HTML」这一类。页面的渲染器只准用 `createElement` + `textContent`
+ *   把它变成 DOM ⇒ **模型输出里的 `<script>` 只会是字面文本**，不存在「忘了转义」这条路径。
+ *
+ * ⚠️ 本文件**不许碰 DOM**（不出现 `document` / `window`）—— 它要在 Node 里被直接 import 做单测。
+ *
+ * 支持的子集（刻意不做的都在「不做」里）：
+ * - 块：`#` 标题（1–6 级）、围栏码块（``` / ~~~，带语言标注）、无序/有序列表（**一层**）、
+ *   引用（合并成一段正文）、`---` 分隔线、段落
+ * - 行内：行内码、`**粗**`、`*斜*`、`[文字](链接)`、`<https://…>` 自动链接
+ *
+ * 不做（都是刻意的，不是漏）：
+ * - **不做 HTML 透传**（安全前提，见上）
+ * - 不做表格 / 任务列表 / 嵌套列表 / 脚注 / 数学 —— 面板是调试视图，不是文档站
+ * - 不做 setext 标题（`===` 下划线式）—— 与分隔线歧义大、收益小
+ * - 不做图片（`![]()`）—— 面板**不去外网取图**：一次 run 的正文不该触发网络请求
+ */
+/**
+ * 链接协议白名单。**这是安全边界，不是风格选择**：
+ * 模型输出里的 `[点我](javascript:alert(1))` 若被渲染成可点链接，面板就成了 XSS 的跳板
+ * （`href` 是唯一一处「我们主动写进属性」的值 —— 文本全走 `textContent` 是安全的，
+ * 属性不是）。不合法 ⇒ 这一条**整个降级成字面文本**（连 `[]()` 都照原样显示），
+ * 使用者一眼看得出「这里有个链接我没渲染」，而不是看到一个空链接或点不动的链接。
+ */
+export function isSafeHref(href) {
+    // 允许 http/https/mailto；**不允许** javascript: / data: / vbscript: / file: 等
+    return /^(https?:|mailto:)/i.test(href.trim());
+}
+const FENCE = /^\s{0,3}(`{3,}|~{3,})\s*([^\s`]*)/;
+const HEADING = /^\s{0,3}(#{1,6})\s+(.*?)\s*#*\s*$/;
+const HR = /^\s{0,3}([-*_])(?:\s*\1){2,}\s*$/;
+const QUOTE = /^\s{0,3}>\s?(.*)$/;
+const UL = /^(\s*)([-*+])\s+(.*)$/;
+const OL = /^(\s*)(\d{1,9})[.)]\s+(.*)$/;
+const BLANK = /^\s*$/;
+/**
+ * 把一段 Markdown 文本解析成块序列。
+ *
+ * 三条与「真 Markdown」不同但**刻意**的口径：
+ * - 缩进 ≥2 空格的续行归上一条列表项（列表只解析**一层**：更深一层当正文，不递归建树）；
+ * - 未闭合的围栏码块吃掉到文末（**不静默丢内容** —— 模型被截断时最常见的就是这个形态）；
+ * - 引用（`>`）合并成**一段正文**（面板里引用几乎总是模型在引日志，逐行建块只会更碎）。
+ */
+export function parseMarkdown(text) {
+    const src = String(text ?? '').replace(/\r\n?/g, '\n');
+    const lines = src.split('\n');
+    const blocks = [];
+    let i = 0;
+    let para = [];
+    const flushPara = () => {
+        if (para.length === 0)
+            return;
+        const joined = para.join('\n').trim();
+        para = [];
+        if (joined)
+            blocks.push({ type: 'p', inline: parseInline(joined, 0) });
+    };
+    while (i < lines.length) {
+        const line = lines[i];
+        // —— 围栏码块 ——
+        const fence = FENCE.exec(line);
+        if (fence) {
+            flushPara();
+            const marker = fence[1][0];
+            const min = fence[1].length;
+            const lang = fence[2] ?? '';
+            const body = [];
+            i++;
+            while (i < lines.length) {
+                const cur = lines[i];
+                const close = new RegExp(`^\\s{0,3}${marker === '`' ? '`' : '~'}{${min},}\\s*$`);
+                if (close.test(cur)) {
+                    i++;
+                    break;
+                }
+                body.push(cur);
+                i++;
+            }
+            blocks.push({ type: 'code', lang, text: body.join('\n') });
+            continue;
+        }
+        // —— 空行：段落到此为止 ——
+        if (BLANK.test(line)) {
+            flushPara();
+            i++;
+            continue;
+        }
+        // —— 分隔线（必须在列表之前判：`---` 也是无序列表的标记） ——
+        if (HR.test(line)) {
+            flushPara();
+            blocks.push({ type: 'hr' });
+            i++;
+            continue;
+        }
+        // —— 标题 ——
+        const h = HEADING.exec(line);
+        if (h) {
+            flushPara();
+            blocks.push({
+                type: 'h',
+                level: h[1].length,
+                inline: parseInline(h[2].trim(), 0),
+            });
+            i++;
+            continue;
+        }
+        // —— 引用：连续 `>` 行合成一段 ——
+        if (QUOTE.test(line)) {
+            flushPara();
+            const quoted = [];
+            while (i < lines.length && QUOTE.test(lines[i])) {
+                quoted.push(QUOTE.exec(lines[i])[1]);
+                i++;
+            }
+            const joined = quoted.join('\n').trim();
+            blocks.push({ type: 'quote', inline: parseInline(joined, 0) });
+            continue;
+        }
+        // —— 列表（无序 / 有序，各收一段连续的） ——
+        const ul = UL.exec(line);
+        const ol = olAt(line);
+        if (ul || ol) {
+            flushPara();
+            const ordered = ol !== null;
+            const items = [];
+            while (i < lines.length) {
+                const cur = lines[i];
+                const m = ordered ? olAt(cur) : UL.exec(cur);
+                if (m) {
+                    items.push(parseInline(m[3].trim(), 0));
+                    i++;
+                    continue;
+                }
+                // 续行：缩进 ≥2 且不是新的一条 ⇒ 并进上一项
+                if (items.length > 0 && /^\s{2,}\S/.test(cur) && !BLANK.test(cur)) {
+                    const last = items[items.length - 1];
+                    last.push(...parseInline(cur.trim(), 0));
+                    i++;
+                    continue;
+                }
+                break;
+            }
+            blocks.push({ type: 'list', ordered, items });
+            continue;
+        }
+        // —— 其余：段落（连续非空行合并，行内换行保留） ——
+        para.push(line.trim());
+        i++;
+    }
+    flushPara();
+    return blocks;
+}
+/** 有序列表标记（`1.` / `1)`），返回与 UL 同形的三组：缩进 / 标记 / 正文 */
+function olAt(line) {
+    const m = OL.exec(line);
+    return m ? m : null;
+}
+/**
+ * 行内解析。`depth` 是**递归上限**：`**a *b* c**` 这类嵌套只展开到第 3 层，
+ * 再深就按字面留着 —— 递归无上限时，一条构造出来的正文就能把面板卡死。
+ */
+export function parseInline(text, depth) {
+    const out = [];
+    let buf = '';
+    let i = 0;
+    const pushText = () => {
+        if (buf)
+            out.push({ type: 'text', text: buf });
+        buf = '';
+    };
+    while (i < text.length) {
+        const c = text[i];
+        // 行内码：`...`（不跨行；两端各去掉一个空格 —— 与 CommonMark 同款）
+        if (c === '`') {
+            const end = text.indexOf('`', i + 1);
+            if (end > i + 1) {
+                pushText();
+                let inner = text.slice(i + 1, end);
+                if (inner.startsWith(' ') && inner.endsWith(' ') && inner.trim())
+                    inner = inner.slice(1, -1);
+                out.push({ type: 'code', text: inner });
+                i = end + 1;
+                continue;
+            }
+        }
+        // 链接：[文字](地址) —— 地址不过白名单就整条降级成字面文本（见 isSafeHref）
+        if (c === '[') {
+            const m = /^\[([^\]]*)\]\(([^)\s]*)\)/.exec(text.slice(i));
+            if (m) {
+                const raw = text.slice(i, i + m[0].length);
+                const href = m[2].trim();
+                if (isSafeHref(href)) {
+                    pushText();
+                    out.push({ type: 'link', href, text: m[1].trim() });
+                }
+                else {
+                    buf += raw; // 字面保留（连 []() 一起）—— 让使用者看见「这里有个链接我没渲染」
+                }
+                i += m[0].length;
+                continue;
+            }
+        }
+        // 自动链接：<https://…>（裸的 `<` 一律当文本 —— 这正是「不做 HTML 透传」的落点）
+        if (c === '<') {
+            const m = /^<(https?:\/\/[^\s>]+)>/.exec(text.slice(i));
+            if (m) {
+                pushText();
+                out.push({ type: 'link', href: m[1], text: m[1] });
+                i += m[0].length;
+                continue;
+            }
+        }
+        // 强调：**粗** / *斜*（`__` / `_` 同义）
+        if (c === '*' || c === '_') {
+            const strong = text.startsWith(c + c, i);
+            const mark = strong ? c + c : c;
+            const end = text.indexOf(mark, i + mark.length);
+            if (end > i + mark.length) {
+                const inner = text.slice(i + mark.length, end);
+                if (inner.trim() && !inner.startsWith(' ') && !inner.endsWith(' ')) {
+                    pushText();
+                    const children = depth < 3 ? parseInline(inner, depth + 1) : [{ type: 'text', text: inner }];
+                    out.push(strong ? { type: 'strong', children } : { type: 'em', children });
+                    i = end + mark.length;
+                    continue;
+                }
+            }
+        }
+        buf += c;
+        i++;
+    }
+    pushText();
+    return out;
+}

package/dist/panel-logic.js

@@ -381,3 +381,35 @@ export function promptAfterFilePick(current, name) {
         return { prompt: current, filled: false };
     return { prompt: name, filled: true };
 }
+// ---------- ③ 消息折叠：长正文默认收起，短的不加控件 ----------
+/**
+ * 超过这么多行就默认折叠。12 行是「一屏大致读得完」的量级 —— 面板右栏在 1223px 下正文行高
+ * 约 18px，12 行 ≈ 216px，正好是不把调用树挤出去的上限。
+ */
+export const COLLAPSE_MAX_LINES = 12;
+/** 单行长正文的兜底阈值：一行 2000 字符（模型不换行时很常见）同样该收起来 */
+export const COLLAPSE_MAX_CHARS = 1200;
+/**
+ * 「这段正文要不要折叠」。**判定是纯逻辑** —— 渲染层只管按结果挂控件，
+ * 不自己量高度（量高度依赖布局与字体，单测里量不出来，等于把规则藏进浏览器）。
+ *
+ * 为什么不按像素量：像素阈值在字体/缩放/窄屏下会漂，同一个回复在不同机器上折叠与否都不一样；
+ * 行数 + 字符数是**输入本身的属性**，可复现、可断言。
+ *
+ * `hint` 是给展开控件用的文案（面板拿它当按钮标题，再加个 caret）；不折叠时是空串 ——
+ * **短消息上挂一个「展开」是噪声**，所以控件只在真的长时出现。
+ */
+export function collapseDecision(text, opts = {}) {
+    const t = String(text ?? '');
+    const lines = t.length === 0 ? 0 : t.split('\n').length;
+    const chars = t.length;
+    const maxLines = opts.maxLines ?? COLLAPSE_MAX_LINES;
+    const maxChars = opts.maxChars ?? COLLAPSE_MAX_CHARS;
+    const collapsed = lines > maxLines || chars > maxChars;
+    const hint = collapsed
+        ? lines > 1
+            ? `展开全文（共 ${lines} 行）`
+            : `展开全文（共 ${chars} 字符）`
+        : '';
+    return { collapsed, lines, chars, hint };
+}

package/dist/templates/package.json

@@ -9,10 +9,10 @@
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@migor/agentia": "^0.9.1"
+    "@migor/agentia": "^0.9.2"
   },
   "devDependencies": {
-    "@migor/cli": "^0.9.1",
+    "@migor/cli": "^0.9.2",
     "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.9.1",
+  "version": "0.9.2",
   "description": "Agentia 框架命令行工具：create 脚手架 + g 能力生成 + dev 本地可观测面板（trace inspector）",
   "type": "module",
   "bin": {