@migor/cli 0.9.2 → 0.9.4

package/dist/inspector.js

@@ -13,6 +13,13 @@
  * 服务同时是**面板 → dev 环**的入口（`POST /run`）：具体怎么驱动用户代码由 `dev.ts`
  * 经 `DevHooks` 注入 —— 本文件不认识子进程、不认识 tsx，只做 HTTP 与校验。
  *
+ * ## 本文件管什么（2026-09-23 拆分后）
+ *
+ * **服务**：监听、三道鉴权闸、应答/请求原语（`json` / `text` / `readBody` /
+ * `parseRunRequest`）、对外类型（`DevHooks` / `InspectorServer` / `TraceLike` /
+ * `RunSummary`）、`HttpError`。**路由表不在这里** —— 已切到 `inspector-routes.ts`
+ * （`handleRoutes`），理由与边界见那个文件的头注。
+ *
  * ## 鉴权（D0）
  *
  * 两道，都零依赖：
@@ -29,99 +36,8 @@
  */
 import { timingSafeEqual } from 'node:crypto';
 import { createServer } from 'node:http';
-import { readFile } from 'node:fs/promises';
-import { readdirSync, statSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { DEFAULT_BUDGET, } from './dev-protocol.js';
+import { handleRoutes, TOKEN_COOKIE, TOKEN_HEADER, } from './inspector-routes.js';
 import { rememberNote } from './panel-logic.js';
-/** 入站校验：结构不符的 trace 直接拒（400），不让 NaN 之类的坏数据流进面板与 SSE 广播 */
-function validateTrace(t) {
-    if (!t || typeof t !== 'object' || Array.isArray(t))
-        return 'trace 必须是对象';
-    const trace = t;
-    if (typeof trace.traceId !== 'string' || trace.traceId.length === 0)
-        return 'traceId 缺失';
-    if (trace.spans !== undefined && !Array.isArray(trace.spans))
-        return 'spans 必须是数组';
-    for (const s of trace.spans ?? []) {
-        if (!s || typeof s !== 'object')
-            return 'span 必须是对象';
-        if (typeof s.spanId !== 'string' || s.spanId.length === 0)
-            return 'span.spanId 缺失';
-        if (typeof s.name !== 'string')
-            return `span ${s.spanId} 缺 name`;
-        if (typeof s.startedAt !== 'number' || !Number.isFinite(s.startedAt)) {
-            return `span ${s.spanId} 缺 startedAt（必须是有穷 number）`;
-        }
-        if (s.endedAt !== undefined && (typeof s.endedAt !== 'number' || !Number.isFinite(s.endedAt))) {
-            return `span ${s.spanId} 的 endedAt 非法`;
-        }
-    }
-    return null;
-}
-/**
- * 入站校验：**增量记账事件**的形状（`POST /ingest-event`，① 实时右栏）。
- *
- * 为什么卡得比 `validateTrace` 还细：面板拿这些字段**直接建树**，而坏帧的报错现场在
- * 浏览器里（最难查的地方）。缺一个 `spanId` 的表现是「树上少一个节点」而不是任何报错 ——
- * 所以宁可在这里响亮拒（400 会被 runner 的 event sink 静默吞掉，但至少不会污染面板）。
- */
-function validateTraceEvent(e) {
-    if (!e || typeof e !== 'object' || Array.isArray(e))
-        return '事件必须是对象';
-    const ev = e;
-    if (typeof ev.seq !== 'number' || !Number.isFinite(ev.seq))
-        return 'seq 必须是有穷 number';
-    switch (ev.type) {
-        case 'span.begin': {
-            const s = ev.span;
-            if (!s || typeof s !== 'object')
-                return 'span.begin 缺 span';
-            if (typeof s.spanId !== 'string' || s.spanId.length === 0)
-                return 'span.begin 的 span.spanId 缺失';
-            if (typeof s.traceId !== 'string' || s.traceId.length === 0) {
-                return 'span.begin 的 span.traceId 缺失';
-            }
-            if (typeof s.name !== 'string')
-                return 'span.begin 的 span.name 缺失';
-            if (typeof s.startedAt !== 'number' || !Number.isFinite(s.startedAt)) {
-                return 'span.begin 的 span.startedAt 非法';
-            }
-            return null;
-        }
-        case 'span.end': {
-            if (typeof ev.spanId !== 'string' || ev.spanId.length === 0)
-                return 'span.end 缺 spanId';
-            if (typeof ev.endedAt !== 'number' || !Number.isFinite(ev.endedAt))
-                return 'span.end 的 endedAt 非法';
-            if (typeof ev.status !== 'string')
-                return 'span.end 的 status 缺失';
-            return null;
-        }
-        case 'span.event': {
-            if (typeof ev.spanId !== 'string' || ev.spanId.length === 0)
-                return 'span.event 缺 spanId';
-            if (!ev.event || typeof ev.event.name !== 'string')
-                return 'span.event 缺 event.name';
-            return null;
-        }
-        case 'span.attribute': {
-            if (typeof ev.spanId !== 'string' || ev.spanId.length === 0)
-                return 'span.attribute 缺 spanId';
-            if (typeof ev.key !== 'string' || ev.key.length === 0)
-                return 'span.attribute 缺 key';
-            return null;
-        }
-        case 'span.link': {
-            if (typeof ev.spanId !== 'string' || ev.spanId.length === 0)
-                return 'span.link 缺 spanId';
-            return null;
-        }
-        default:
-            return `不认识的事件类型：${String(ev.type)}`;
-    }
-}
 /** 防 DNS rebinding：面板只服务本机，Host 不是 localhost/127.0.0.1/[::1] 的一律拒 */
 function isLocalHostHeader(host) {
     if (!host)
@@ -135,8 +51,8 @@ function isLocalHostHeader(host) {
 /**
  * `Origin` 校验（D0 的第一道）。
  *
- * 缺省 = 放行：同源导航与**非浏览器客户端**（`curl`、preload 的 `fetch`）都不带
- * `Origin`，把它们拦掉等于把 dev 环弄坏。带 `Origin` 的一定是浏览器跨源/同源请求
+ * 缺省 = 放行：同源导航与**非浏览器客户端**（`curl`、runner 里 trace sink 的 `fetch`）
+ * 都不带 `Origin`，把它们拦掉等于把 dev 环弄坏。带 `Origin` 的一定是浏览器跨源/同源请求
  * —— 那时只放行本机 origin。
  *
  * 注意 `Origin: null`（sandboxed iframe / file:// 页面）**不是**「缺省」：它是浏览器
@@ -157,10 +73,6 @@ function isAllowedOrigin(origin) {
     const host = url.hostname.replace(/^\[|\]$/g, '').toLowerCase();
     return host === 'localhost' || host === '127.0.0.1' || host === '::1';
 }
-/** token 的 cookie 名（面板首帧带 `?t=` 拿到它之后，后续请求自动带上） */
-const TOKEN_COOKIE = 'agentia_dev_token';
-/** token 的自定义头名（非浏览器客户端 / 脚本用；不进 URL、不留痕） */
-const TOKEN_HEADER = 'x-agentia-token';
 /** 定长比较：长度不同直接否（`timingSafeEqual` 对不等长会抛） */
 function tokenEquals(a, b) {
     const x = Buffer.from(a, 'utf8');
@@ -181,22 +93,6 @@ function cookieValue(header, name) {
     }
     return null;
 }
-/**
- * 目录判定要**解引用软链**：pnpm store / monorepo 里 `src/tools/foo` 常是软链，
- * 它的 `isDirectory()` 为 false —— 直接用会把真目录静默漏掉（discover.ts 同一条教训）。
- */
-function isDirLikeEntry(full, e) {
-    if (e.isDirectory())
-        return true;
-    if (!e.isSymbolicLink())
-        return false;
-    try {
-        return statSync(full).isDirectory();
-    }
-    catch {
-        return false;
-    }
-}
 /** 环形缓冲上限：面板只保证「回看最近 N 条」，不做历史归档 */
 const MAX_RUNS = 50;
 /**
@@ -204,74 +100,6 @@ const MAX_RUNS = 50;
  * （见 `rememberNote`），所以它有自己的一条淘汰线。
  */
 const MAX_NOTES = MAX_RUNS;
-/**
- * `GET /api/fs` 一次最多回多少个**文件**名（目录不设限：一个位置要列几百个目录，本身就
- * 说明位置选错了）。超限回 `filesTruncated: true` —— 截断必须**明示**，不许静默少给。
- */
-const FILE_LIMIT = 200;
-/** 静态资源目录（构建期由 scripts/copy-assets.mjs 就位） */
-const HERE = dirname(fileURLToPath(import.meta.url));
-const ASSETS = join(HERE, 'inspector');
-const PAGE = join(HERE, 'inspector-page.html');
-/**
- * 静态资源白名单：**只有这里列出的名字**能被读出来。
- *
- * `panel-logic.js` 是 CLI 自己编译出来的模块（面板纯逻辑，单测直接 import 它），
- * 落在 dist 根而不是 dist/inspector/ —— 与 `inspector-page.html` 同处一层。
- */
-const STATIC = new Map([
-    ['index.js', join(ASSETS, 'index.js')],
-    ['view.js', join(ASSETS, 'view.js')],
-    ['fromTrace.js', join(ASSETS, 'fromTrace.js')],
-    ['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() {
-    return {
-        available: false,
-        projectRoot: '',
-        home: '',
-        capabilities: [],
-        multiTurn: [],
-        warning: null,
-        defaultWorkdir: '',
-        budget: { ...DEFAULT_BUDGET },
-        running: false,
-        lastError: null,
-        // 没有 dev 环 ⇒ 没有会话可谈（面板只在 available 时才读它）
-        sessionId: '',
-    };
-}
-function summarize(t, note) {
-    const spans = t.spans || [];
-    const root = spans.find((s) => s.kind === 'run') || spans[0];
-    const startedAt = root ? root.startedAt : 0;
-    const endedAt = root && root.endedAt != null ? root.endedAt : startedAt;
-    const u = t.totalUsage || {};
-    const status = t.status || root?.status || 'ok';
-    const sid = root?.attributes?.['session.id'];
-    // 收尾原因由引擎写在 run 根 span 的 `stop_reason` 上（`engine/loop.ts` 的
-    // `recorder.setAttribute(rootId, 'stop_reason', …)`）—— 面板判中止**必须**看它，
-    // 因为 `aborted` 的 `ok` 也是 false（见 `RunSummary.stopReason`）
-    const sr = root?.attributes?.stop_reason;
-    return {
-        traceId: t.traceId,
-        status,
-        name: root ? root.name : 'run',
-        startedAt,
-        ms: endedAt - startedAt,
-        tokens: (u.inputTokens || 0) + (u.outputTokens || 0),
-        ok: status !== 'error',
-        stopReason: typeof sr === 'string' && sr.length > 0 ? sr : null,
-        sessionId: typeof sid === 'string' && sid.length > 0 ? sid : null,
-        note,
-    };
-}
 /** 带 statusCode 的错误：让 handler 的 catch 回对应的码而不是一律 500 */
 export class HttpError extends Error {
     statusCode;
@@ -290,20 +118,24 @@ export class HttpError extends Error {
  */
 export function startInspector(opts = {}) {
     const host = opts.host ?? '127.0.0.1';
-    const runs = new Map();
-    const order = []; // 到达顺序，用于淘汰与列表排序
-    const notes = new Map(); // CLI 侧记账（**有自己的上限**，见 rememberNote）
-    const clients = new Set(); // SSE 订阅者
+    // 环形缓冲 + SSE 订阅者。整体一个对象是为了**原样**交给路由层（`RouteCtx.state`），
+    // 路由拿到的就是这里的引用 —— 两边看到的是同一份，不存在「路由改了服务不知道」。
+    const state = {
+        runs: new Map(),
+        order: [], // 到达顺序，用于淘汰与列表排序
+        notes: new Map(), // CLI 侧记账（**有自己的上限**，见 rememberNote）
+        clients: new Set(), // SSE 订阅者
+    };
     const token = opts.token;
     const broadcast = (s) => {
         const chunk = `data: ${JSON.stringify(s)}\n\n`;
-        for (const c of clients)
+        for (const c of state.clients)
             c.write(chunk);
     };
     /** 命名事件 `dev`：run 生命周期与 runner 状态 —— 面板靠它显示「在跑 / 失败 / 重启」 */
     const emitDev = (ev) => {
         const chunk = `event: dev\ndata: ${JSON.stringify(ev)}\n\n`;
-        for (const c of clients)
+        for (const c of state.clients)
             c.write(chunk);
     };
     const json = (res, code, body) => {
@@ -338,7 +170,13 @@ export function startInspector(opts = {}) {
         req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
         req.on('error', reject);
     });
-    /** 校验 `RunRequest`：形状不对就 400，且说清是哪一项 —— 面板据此把原因显示给用户 */
+    /**
+     * 校验 `RunRequest`：形状不对就 400，且说清是哪一项 —— 面板据此把原因显示给用户。
+     *
+     * 为什么留在本文件而不是随路由搬走：它要构造 `HttpError`，而 `HttpError` 定义在这里
+     * （`dev.ts` 也从 `dist/inspector.js` 取它）。把它搬去 `inspector-routes.ts` 会让两个
+     * 模块**互相 import 值** ⇒ 运行期成环。这条边界比「按职责归类」更重要。
+     */
     const parseRunRequest = (raw) => {
         if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
             throw new HttpError(400, 'body 必须是对象');
@@ -367,6 +205,18 @@ export function startInspector(opts = {}) {
             ...(b.multiTurn === undefined ? {} : { multiTurn: b.multiTurn }),
         };
     };
+    // **每服务**一份的路由依赖（路由拿到的是这些引用本身）；每请求只叠 req/res/url/path/queryToken。
+    const baseCtx = {
+        dev: opts.dev,
+        state,
+        maxRuns: MAX_RUNS,
+        token,
+        json,
+        text,
+        readBody,
+        parseRunRequest,
+        broadcast,
+    };
     const handler = async (req, res) => {
         const url = new URL(req.url || '/', `http://${host}`);
         const path = url.pathname;
@@ -393,235 +243,8 @@ export function startInspector(opts = {}) {
                 });
                 return;
             }
-            if (req.method === 'POST' && path === '/ingest') {
-                const body = await readBody(req); // 超 413 走外层 catch
-                let trace;
-                try {
-                    trace = JSON.parse(body);
-                }
-                catch {
-                    json(res, 400, { error: 'body 不是合法 JSON' });
-                    return;
-                }
-                const problem = validateTrace(trace);
-                if (problem) {
-                    json(res, 400, { error: problem });
-                    return;
-                }
-                const valid = trace;
-                if (!runs.has(valid.traceId)) {
-                    order.push(valid.traceId);
-                    if (order.length > MAX_RUNS) {
-                        const evicted = order.shift();
-                        runs.delete(evicted);
-                        notes.delete(evicted);
-                    }
-                }
-                runs.set(valid.traceId, valid);
-                broadcast(summarize(valid, notes.get(valid.traceId) ?? null));
-                json(res, 200, { ok: true });
-                return;
-            }
-            /**
-             * **在飞 run 的增量记账事件**（① 实时右栏）：`POST /ingest-event`。
-             *
-             * 与 `POST /ingest` 的分工是刻意的两条缝（框架侧同名区分）：
-             * - 这条 = **此刻看到**：高频、逐笔、不落库、**不保证送达**；
-             * - 那条 = **最终账**：收尾一次、进 run 列表、被 `/api/runs` 读。
-             *
-             * 所以这里**只广播**、不建 run 记录：面板拿它把树「长」出来，收尾那份整棵 trace
-             * 回来时覆盖（`open()` 的渲染永远以收尾那份为准）。
-             *
-             * 202 而不是 200：已经广播出去了，但面板收没收到不归这里管（SSE 是单向流）。
-             * 没有 dev 钩子时回 503 —— 与 `/run` / `/run/abort` 同一口径（没有面板消费它）。
-             */
-            if (req.method === 'POST' && path === '/ingest-event') {
-                if (!opts.dev) {
-                    json(res, 503, { error: '这个 inspector 不是 agentia dev 起的（没有 runner）' });
-                    return;
-                }
-                const body = await readBody(req);
-                let ev;
-                try {
-                    ev = JSON.parse(body);
-                }
-                catch {
-                    json(res, 400, { error: 'body 不是合法 JSON' });
-                    return;
-                }
-                const problem = validateTraceEvent(ev);
-                if (problem) {
-                    json(res, 400, { error: problem });
-                    return;
-                }
-                opts.dev.traceEvent(ev);
-                json(res, 202, { ok: true });
-                return;
-            }
-            if (req.method === 'GET' && path === '/api/runs') {
-                json(res, 200, order
-                    .slice()
-                    .reverse()
-                    .map((id) => summarize(runs.get(id), notes.get(id) ?? null)));
-                return;
-            }
-            if (req.method === 'GET' && path.startsWith('/api/runs/')) {
-                const id = decodeURIComponent(path.slice('/api/runs/'.length));
-                const t = runs.get(id);
-                if (!t) {
-                    json(res, 404, { error: 'run 不存在（可能已被淘汰）' });
-                    return;
-                }
-                json(res, 200, t);
-                return;
-            }
-            if (req.method === 'GET' && path === '/api/dev') {
-                json(res, 200, opts.dev ? opts.dev.state() : unavailableDevState());
-                return;
-            }
-            /**
-             * 目录浏览器：`GET /api/fs?path=<绝对路径>` →
-             * `{ path, parent, dirs, dotDirs, files, filesTruncated }`。
-             *
-             * 为什么需要它：浏览器**拿不到**用户选的文件夹的绝对路径 —— `<input webkitdirectory>`
-             * 只给相对路径，File System Access API 只给 handle.name。而 dev 环要的是绝对路径
-             * （工具按它解析）。⇒ 要么让用户手打路径，要么服务端列目录。后者才是「工作目录是
-             * 主控件」（D3/D7）该有的手感。
-             *
-             * 三条口径（2026-09-22 复核后改，前两条是实测出来的缺口）：
-             * - **文件也列**（`files`，只给名字、不读内容）：面板据此提供「选这个文件」——
-             *   工作目录取它所在目录、prompt 空时填文件名。只列目录时，「让 agent 看某个文件」
-             *   只能靠用户自己把文件名打进 prompt。
-             * - **隐藏目录单列**（`dotDirs`，不在 `dirs` 里）：以前一批过滤掉，于是
-             *   `~/xxx/.yyy` 这类目录**根本点不进去**（`..` 只能退到它上面，进不去）。
-             *   单列是为了不把 `.git` / `.cache` 混进正常浏览，同时保证**可达**。
-             * - `files` 有上限（`FILE_LIMIT`）并回 `filesTruncated`：一次列几千个文件的名
-             *   没有意义，但**必须明示**截断（本仓纪律：不许静默少给）。
-             *
-             * 只列名字、**不读文件内容**；且只在 dev 钩子在场时开放（只读面板不暴露文件树）。
-             * 越界不是威胁（本机 dev 工具，token 已经挡住了其它进程），但**不存在 / 不是目录**
-             * 要响亮报错 —— 静默回退到项目根会让 agent 对着错的目录乱写（D5）。
-             */
-            if (req.method === 'GET' && path === '/api/fs') {
-                if (!opts.dev) {
-                    json(res, 403, { error: '这个 inspector 不是 agentia dev 起的，不提供目录浏览' });
-                    return;
-                }
-                const target = url.searchParams.get('path');
-                if (!target) {
-                    json(res, 400, { error: '缺少 path 参数' });
-                    return;
-                }
-                const abs = resolve(target);
-                let entries;
-                try {
-                    if (!statSync(abs).isDirectory()) {
-                        json(res, 400, { error: `不是文件夹：${abs}` });
-                        return;
-                    }
-                    entries = readdirSync(abs, { withFileTypes: true });
-                }
-                catch (e) {
-                    json(res, 400, { error: `读不了这个目录：${e.message}` });
-                    return;
-                }
-                const dirs = [];
-                const dotDirs = [];
-                const files = [];
-                for (const e of entries) {
-                    if (isDirLikeEntry(join(abs, e.name), e)) {
-                        (e.name.startsWith('.') ? dotDirs : dirs).push(e.name);
-                        continue;
-                    }
-                    // 读不了内容的条目（管道 / socket / 权限）也当文件列出来 —— 列名字不需要读它
-                    if (!e.name.startsWith('.'))
-                        files.push(e.name);
-                }
-                json(res, 200, {
-                    path: abs,
-                    parent: dirname(abs),
-                    dirs: dirs.sort(),
-                    dotDirs: dotDirs.sort(),
-                    files: files.sort().slice(0, FILE_LIMIT),
-                    filesTruncated: files.length > FILE_LIMIT,
-                });
-                return;
-            }
-            if (req.method === 'POST' && path === '/run') {
-                if (!opts.dev) {
-                    json(res, 503, {
-                        error: '这个 inspector 不是 agentia dev 起的（没有 runner），不能驱动 run',
-                    });
-                    return;
-                }
-                const body = await readBody(req);
-                let raw;
-                try {
-                    raw = JSON.parse(body);
-                }
-                catch {
-                    json(res, 400, { error: 'body 不是合法 JSON' });
-                    return;
-                }
-                const ack = await opts.dev.run(parseRunRequest(raw));
-                json(res, 202, ack);
-                return;
-            }
-            if (req.method === 'POST' && path === '/run/abort') {
-                if (!opts.dev) {
-                    json(res, 503, { error: '这个 inspector 不是 agentia dev 起的（没有 runner）' });
-                    return;
-                }
-                // 202 而不是 200：中止是**请求已受理**，run 真正收尾要走 SSE 的 `run-done`
-                // （优雅路径要在回合边界才生效，不是同步的）。
-                json(res, 202, await opts.dev.abort());
-                return;
-            }
-            if (req.method === 'POST' && path === '/session/clear') {
-                if (!opts.dev) {
-                    json(res, 503, { error: '这个 inspector 不是 agentia dev 起的（没有 runner）' });
-                    return;
-                }
-                json(res, 200, await opts.dev.clearSession());
-                return;
-            }
-            if (req.method === 'GET' && path === '/api/session') {
-                if (!opts.dev) {
-                    json(res, 200, { session: null });
-                    return;
-                }
-                json(res, 200, { session: await opts.dev.session() });
-                return;
-            }
-            if (req.method === 'GET' && path === '/stream') {
-                res.writeHead(200, {
-                    'content-type': 'text/event-stream',
-                    'cache-control': 'no-cache',
-                    connection: 'keep-alive',
-                });
-                res.write(': connected\n\n');
-                clients.add(res);
-                req.on('close', () => clients.delete(res));
-                return;
-            }
-            if (req.method === 'GET' && (path === '/' || path === '/index.html')) {
-                // 首帧带了合法 token ⇒ 种进 cookie（SameSite=Strict + HttpOnly）：
-                // 之后面板自己的 fetch / EventSource 自动带上，token 不进 URL 历史、不进截图。
-                const headers = token !== undefined && queryToken !== null
-                    ? { 'set-cookie': `${TOKEN_COOKIE}=${token}; Path=/; HttpOnly; SameSite=Strict` }
-                    : {};
-                text(res, 200, 'text/html; charset=utf-8', await readFile(PAGE, 'utf8'), headers);
-                return;
-            }
-            if (req.method === 'GET' && STATIC.has(path.slice(1))) {
-                const name = path.slice(1);
-                const type = name.endsWith('.css')
-                    ? 'text/css; charset=utf-8'
-                    : 'text/javascript; charset=utf-8';
-                text(res, 200, type, await readFile(STATIC.get(name), 'utf8'));
-                return;
-            }
-            json(res, 404, { error: 'not found' });
+            // 闸已过 ⇒ 交给路由表（它假定自己只在已放行的请求上被调用）
+            await handleRoutes({ ...baseCtx, req, res, url, path, queryToken });
         }
         catch (e) {
             const status = e instanceof HttpError ? e.statusCode : (e.statusCode ?? 500);
@@ -640,12 +263,12 @@ export function startInspector(opts = {}) {
                 port,
                 emitDev,
                 noteRun: (traceId, note) => {
-                    rememberNote(notes, traceId, note, MAX_NOTES);
+                    rememberNote(state.notes, traceId, note, MAX_NOTES);
                 },
                 close: () => new Promise((done) => {
-                    for (const c of clients)
+                    for (const c of state.clients)
                         c.end();
-                    clients.clear();
+                    state.clients.clear();
                     server.close(() => done());
                 }),
             });

package/dist/markdown.js

@@ -23,6 +23,7 @@
  * - 不做表格 / 任务列表 / 嵌套列表 / 脚注 / 数学 —— 面板是调试视图，不是文档站
  * - 不做 setext 标题（`===` 下划线式）—— 与分隔线歧义大、收益小
  * - 不做图片（`![]()`）—— 面板**不去外网取图**：一次 run 的正文不该触发网络请求
+ * - 不做**词内** `_` 强调（`read_file_tool` 原样显示）—— 与 CommonMark 同口径，见 `parseInline`
  */
 /**
  * 链接协议白名单。**这是安全边界，不是风格选择**：
@@ -42,6 +43,12 @@ const QUOTE = /^\s{0,3}>\s?(.*)$/;
 const UL = /^(\s*)([-*+])\s+(.*)$/;
 const OL = /^(\s*)(\d{1,9})[.)]\s+(.*)$/;
 const BLANK = /^\s*$/;
+/** 「单词字符」：`_` 的词内排除用它判边界（与 CommonMark 的 intraword 规则同口径） */
+const WORD_CHAR = /[A-Za-z0-9_]/;
+/** 下标可能越界（`text[-1]` / `text[len]` 都是 `undefined`）⇒ 越界一律当「不是单词字符」 */
+function isWordChar(ch) {
+    return ch !== undefined && WORD_CHAR.test(ch);
+}
 /**
  * 把一段 Markdown 文本解析成块序列。
  *
@@ -226,7 +233,19 @@ export function parseInline(text, depth) {
             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(' ')) {
+                /**
+                 * `_` 的**词内排除**（CommonMark 的 intraword 规则）：两侧只要有一边紧贴单词字符，
+                 * 就不构成强调。
+                 *
+                 * 没有这条，`read_file_tool` 会被切成 `read` + <em>file</em> + `tool`、
+                 * `src/my_dir/my_file.ts` 同理 —— 而面板渲染的正是**模型正文**，标识符是那里最常见的东西。
+                 * 单下划线（`read_file`）本来就不配对、不受影响；真正被切开的是有两个及以上 `_` 的标识符。
+                 *
+                 * ⚠️ `*` **不做**这条限制：CommonMark 里 `a*b*c` **就是** `a<em>b</em>c`。
+                 * 只修 `_`、不修 `*`，是照口径修，不是照直觉修。
+                 */
+                const intraword = c === '_' && (isWordChar(text[i - 1]) || isWordChar(text[end + mark.length]));
+                if (!intraword && 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 });