@migor/cli 0.9.0 → 0.9.1

package/CHANGELOG.md

@@ -5,6 +5,49 @@
 （0.x 阶段：minor 可含破坏性变更，每个破坏性变更都在对应版本的「迁移」小节里写明）。
 决策的完整证据链在 `docs/spec.md` §10（带时间线的决策日志）。
 
+## [Unreleased]
+
+## [0.9.1] - 2026-09-22
+
+### 新增 · dev 面板的实时右栏（在飞就看得到调用树）
+
+- **右栏从「收尾才有」变成「一个个长出来」**：runner 订阅框架的增量记账出口
+  （`onTraceEvent`，0.8.3 已落地）逐笔 `POST /ingest-event` → 父进程**原样**广播
+  （SSE 的 `dev` 命名事件多一类 `trace-event`）→ 面板按 `seq` 折回一棵**临时**的树。
+  收尾那份整棵 trace 回来时**覆盖**它（缺的 span 由那份补齐）。纪律与框架同名出口一致：
+  **不保证送达**，所以刷新页面之后早先那些 span 不会回来（收尾那份会补）。
+  计划 §D7 的评审补充点名要求的那条（P1b 面板侧工作）这轮落地。
+  折回逻辑是**纯逻辑 + 单测**（`panel-logic.ts` 的 `applyTraceEvent`），e2e-dev 另有一条
+  「帧必须先于 run-done 到达，且折回逐字等于收尾的整棵 trace」的真进程断言。
+
+### 变更 · 工作目录选择器：文件可选、隐藏目录可达、`浏览…` 不再是开关
+
+- **文件也能选**：`GET /api/fs` 现在分三类回（`dirs` / `dotDirs` / `files`；文件有上限，
+  超限时回 `filesTruncated`）。点文件名 = 工作目录取它**所在的**目录 + prompt 为空时填文件名
+  （你已经写好的 prompt **一个字不动**）。旧形态只列目录 ⇒「让 agent 看某个文件」只能靠自己打名字。
+- **隐藏目录单列**（不再整批过滤）：`.git` / `~/x/.y` 这类目录以前**根本点不进去**
+  （`..` 只能退到它上面，进不去）。
+- **`浏览…` 不再当开关**：以前面板开着时再点一次只是把它关掉，于是「在输入框敲了路径 → 点浏览」
+  这个最自然的动作是**把面板关掉**。现在点它**总是**按输入框里的路径打开，点面板外面收起。
+
+### 修复
+
+- **跑完的回复被面板自己擦掉（端到端实测 17 ms）**：`run-done` 与「这条 trace 的收尾帧」
+  几乎同毫秒到达，而 `open()`（收尾帧触发的自动打开）**无条件**清回复 ⇒ 刚写上去的那句立刻没了，
+  表现是「run 完成了，但面板上没有回复」。现在按「这条 trace 是不是这段回复的主人」判
+  （`panel-logic.replyBelongsTo`）：打开**别的** run 的 trace 照样清（防张冠李戴），
+  打开**刚跑完那一轮**的不清。
+- **在飞的树被收尾帧骗成「已完成」**：`playTrace` 以前对根 span 没有 `endedAt` 的树也调
+  `finish()`（根被标成 `●` + 耗时），而在飞时那是**假事实**。现在根没结束就不收尾（留 `◌`）——
+  该分支只对「在飞 / 截断」的树生效，收尾的整棵 trace 行为逐字未变。
+
+### 文档
+
+- `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 个影子）。
+
 ## [0.9.0] - 2026-09-22
 
 > 本版主题（窗口 `0.8.3 → 0.9.0`）：**dev 调试环落地** —— `agentia dev` 从「`tsx watch` 跑你的
@@ -1143,7 +1186,8 @@
 首个公开发布：`@migor/agentia` + `@migor/cli`（scope `@migor/*`），两包版本同步。
 框架本体单包；CLI 独立成包（workspaces）。
 
-[Unreleased]: https://github.com/retrychx/agentia/compare/v0.9.0...HEAD
+[Unreleased]: https://github.com/retrychx/agentia/compare/v0.9.1...HEAD
+[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
 [0.8.2]: https://github.com/retrychx/agentia/releases/tag/v0.8.2

package/dist/AGENTS.md

@@ -131,11 +131,20 @@ npx agentia --version            # CLI 版本（= -v）
 |---|---|
 | **prompt** | 输入框 + `↑`/`↓` 调回历史（像 shell）。面板上「点一下 = 一次**真** run」 |
 | **能力** | 多选，缺省全选。收窄的是**菜单**（主 agent 仍在环里），不是「只可能调它」—— 别的能力 `tools` 里的显式引用仍能调到被排除的那个 |
-| **工作目录** | 目录选择器（`浏览…`）。**它是这个环的主控件**：任务型 agent 的 prompt 几乎不变，变的是目录 |
+| **工作目录** | 目录选择器（`浏览…`）。**它是这个环的主控件**：任务型 agent 的 prompt 几乎不变，变的是目录。三个点击语义：点**目录名**进去 / 点 `..` 上一层 / **点文件名** = 把它**所在的**目录当工作目录（prompt 为空时顺手把文件名填进去，你写好的话一个字不动）；`.git` 这类**隐藏目录**单列在选择器末尾（可达但靠后）。`浏览…` **总是**按输入框里的路径打开 —— 敲了路径再点它就是打开那个路径（不是「再点一次关掉」）；点面板外面收起 |
 | **多轮** | 跟能力走：`src/dev.config.ts` 里 `multiTurn: [...]` 声明哪些能力该多轮，混选时取 **OR** 且面板**标出来源**（`多轮·trip-planner`） |
 
 `npm run dev -- "你的问题"` 可以直接把第一句 prompt 带上（等价于启动后在输入框里敲）。
 
+**右栏是实时的（在飞就看得到）**：run 一开跑，右栏就从空树开始，**span 一个个长出来**
+（`◌` = 还没结束，`●` = 已结束），收尾时用**整棵 trace** 覆盖一遍。实现走框架的增量记账出口
+（`onTraceEvent`，0.8.3）：runner 订阅 → 逐笔 `POST /ingest-event` → 父进程广播 → 面板按 `seq` 折回。
+两条边界（与框架同名出口一致，都写在文档里以免被当成缺陷）：
+
+- **不保证送达**：SSE 断了就断了，没有重放。所以「在飞的那棵树」是**临时的** —— 刷新页面之后
+  早先那些 span 不会回来（收尾的整棵 trace 会补齐它们），**收尾那份永远覆盖在飞的这份**。
+- 它只影响「此刻看到什么」，**不影响 run 本身**，也不影响落盘的 trace（那是另一条缝）。
+
 **为什么用 `agentia dev` 而不是 `tsx watch`**：`agentia dev` 自己 import 你的 `src/app.ts` 并驱动它，
 于是**它才是调用方**，四个输入才可能生效。它也**自己管文件监视**（不再叠一层 `tsx watch`）：
 

package/dist/dev-runner.js

@@ -19,7 +19,7 @@ import { existsSync, readdirSync, statSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { join } from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { createInspectSink } from './inspector-sink.js';
+import { createInspectEventSink, createInspectSink, } from './inspector-sink.js';
 import { APP_ENTRY_REL, DEFAULT_BUDGET, DEV_CONFIG_REL, } from './dev-protocol.js';
 const root = process.env.AGENTIA_DEV_ROOT || process.cwd();
 function send(msg) {
@@ -60,6 +60,28 @@ async function registerTraceSink() {
         console.warn(`[agentia] inspector 未挂载：${e.message}`);
     }
 }
+/**
+ * ① 实时右栏：**增量**记账事件的出口（框架 `onTraceEvent` 的落点）。
+ *
+ * 与上面那个 trace sink 是**两条缝**，差别都是刻意的：
+ * - trace sink 走收尾的 `snapshot()`（一次、被 `flushSinks` await、保证送达）；
+ * - 这里走运行期的 `onTraceEvent`（逐笔、同步派发、**不保证送达**）——「此刻看到」。
+ *
+ * 为什么必须有它：此前右栏唯一的画树点在 run **收尾之后**，一次十几秒的 run 期间
+ * 面板上的树是死的（只有一句「正在跑…」）。框架的增量出口本来就是为这类消费者准备的
+ * （`RunInvocationOptions.onTraceEvent`，0.8.3），计划 §D7 的评审补充也点名要求接上。
+ *
+ * 纪律（与框架同名出口一致）：不 await、失败静默、由 sink 自己排 FIFO 链保序
+ * （见 `createInspectEventSink`）。**丢帧只会让树少长一会儿**：收尾那份整棵 trace
+ * 会把面板上折回的临时树覆盖掉，缺的 span 由它补齐 —— 不会让面板看到一棵错的树。
+ */
+function registerEventSink() {
+    const port = Number(process.env.AGENTIA_INSPECT_PORT || 0);
+    if (port <= 0)
+        return;
+    const token = process.env.AGENTIA_INSPECT_TOKEN || undefined;
+    eventSink = createInspectEventSink({ port, ...(token ? { token } : {}) });
+}
 // ---------- dev.config.ts（**数据**，不是逻辑） ----------
 /**
  * 读 `src/dev.config.ts`。
@@ -329,6 +351,8 @@ let currentAbort = null;
 let runInFlight = false;
 /** 窗口内到达的中止请求：建完 controller 立刻补一次 `abort()`（见 `runOnce` 的 await 顺序） */
 let abortRequested = false;
+/** ① 增量记账事件的出口（`registerEventSink()` 建；端口没给就是 null —— 面板没开） */
+let eventSink = null;
 async function runOnce(msg) {
     const { request } = msg;
     send({ type: 'run-start' });
@@ -350,6 +374,11 @@ async function runOnce(msg) {
         maxTotalTokens: budget.maxTotalTokens,
         signal: ac.signal,
     };
+    // ① 实时右栏：**在 run 之前**挂上（框架只在运行期派发 —— 晚一步就等于整轮都收不到）。
+    // 单次 run 的 `onTraceEvent` 与应用级缺省是**叠加**的（不是覆盖），所以这里挂上
+    // 不会把用户在 `createApp` 里配的那个挤掉。
+    if (eventSink)
+        opts.onTraceEvent = (e) => eventSink?.send(e);
     try {
         if (request.multiTurn) {
             const mod = await importAppModule();
@@ -393,6 +422,8 @@ async function runOnce(msg) {
 async function main() {
     // ⚠️ 顺序不能换：sink 必须早于用户 app 的 import（createApp 构造期对 defaultSinks 快照）
     await registerTraceSink();
+    // 增量出口只是个 HTTP 出口（不碰框架注册表），但同样在这里建：一个进程一次。
+    registerEventSink();
     let built;
     try {
         built = await build();

package/dist/dev.js

@@ -916,6 +916,14 @@ export function devServer(argv = []) {
                     session: readSession,
                     abort: abortRun,
                     clearSession,
+                    /**
+                     * ① 实时右栏：runner 逐笔 POST 上来的增量记账事件**原样广播**给面板。
+                     *
+                     * 父进程在这一层**不做任何解释**（不折回、不缓存、不裁剪）：折回是面板的活
+                     * （它有 `panel-logic.applyTraceEvent` 与单测），而父进程插一手就多一处会漂的口径。
+                     * 这里只保证「按收到的顺序、同步转发」—— SSE 写入本身是有序的。
+                     */
+                    traceEvent: (e) => emit({ kind: 'trace-event', event: e }),
                 },
             });
             console.log(`Inspector: http://127.0.0.1:${inspector.port}/?t=${token}\n` +

package/dist/inspector/fromTrace.js

@@ -81,7 +81,14 @@ function eventFull(ev) {
 }
 
 /**
- * 把真实 Trace 线性回放给视图（同步、一次性；用于 run 结束后的静态展示）。
+ * 把真实 Trace 线性回放给视图（同步、一次性）。
+ *
+ * 两种用途共用本函数（这也是它必须呆在 trace-view 里、不进 CLI 的理由）：
+ * - **收尾的整棵 trace**（run 结束后一次画完）；
+ * - **在飞的那棵树**（CLI inspector 的实时右栏：每收到一条增量记账事件就整体重画一次，
+ *   见 `packages/cli/src/panel-logic.ts` 的 `applyTraceEvent`）。重画是幂等的 ——
+ *   同一棵 spans 交给它多少次，画出来的都是同一棵树。
+ *
  * 返回 false 表示 trace 空、未做任何渲染。
  */
 export function playTrace(view, trace) {
@@ -158,6 +165,9 @@ export function playTrace(view, trace) {
     }
   }
 
-  view.finish(root.endedAt != null ? root.endedAt - root.startedAt : 0, root.status, root.error);
+  // 根 span 还没结束（`span.end` 尚未到达）⇒ **不收尾**：`finish()` 会把根标成已完成
+  // （● + 耗时），而这棵树其实还在长 —— 在飞时看到「已完成」是假事实。留 ◌ 才对。
+  // 收尾的整棵 trace 根必有 `endedAt`，所以这条分支只对「在飞 / 截断」的树生效。
+  if (root.endedAt != null) view.finish(root.endedAt - root.startedAt, root.status, root.error);
   return true;
 }

package/dist/inspector-page.html

@@ -151,6 +151,11 @@
       .fs-head span { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; color: var(--faint); }
       .fs-item { display: block; width: 100%; text-align: left; background: none; border: 0; color: var(--text); padding: 4px 6px; border-radius: 4px; font: inherit; font-family: var(--mono); font-size: 12px; cursor: pointer; }
       .fs-item:hover { background: #202024; }
+      /* 隐藏目录：可达但不可眼（旧实现直接过滤掉，于是 .y 这类目录根本点不进去） */
+      .fs-dot { color: var(--faint); }
+      /* 文件行：点它 = 选它所在的目录（不是选文件本身当工作目录 —— 工作目录只能是目录） */
+      .fs-file { color: var(--text); }
+      .fs-sep { padding: 8px 6px 2px; margin-top: 6px; border-top: 1px solid var(--border); font-family: var(--mono); font-size: 10.5px; color: var(--faint); }
       .fs-foot { padding-top: 8px; border-top: 1px solid var(--border); margin-top: 6px; }
       .mini { background: var(--card); border: 1px solid var(--border); border-radius: 4px; color: var(--text); padding: 5px 9px; font: inherit; font-size: 11.5px; cursor: pointer; }
       .mini:hover { border-color: var(--ice); }
@@ -227,7 +232,10 @@
           <span id="fs-path"></span>
         </div>
         <div id="fs-list"></div>
-        <div class="fs-foot"><button class="mini" id="fs-use" type="button">选这个目录</button></div>
+        <div class="fs-foot">
+          <button class="mini" id="fs-use" type="button">选这个目录</button>
+          <span class="hint"> 点文件名 = 选它所在的目录（prompt 为空时填文件名）</span>
+        </div>
       </div>
     </footer>
 
@@ -235,14 +243,20 @@
       import { createTraceView, playTrace, summarizeTrace, renderSummary } from './index.js';
       import {
         HISTORY_DRAFT,
+        applyTraceEvent,
+        browseTarget,
         capabilityBadge,
+        emptyTraceAccumulator,
         historyStep,
         historyText,
         mergeConversation,
         multiTurnDefault,
         multiTurnLabel,
         normalizeToolSources,
+        partialTrace,
+        promptAfterFilePick,
         pushPromptHistory,
+        replyBelongsTo,
         runDoneNotice,
         runIsFailure,
         shortenPath,
@@ -298,6 +312,17 @@
         list: [],
         current: null,
         reply: '',
+        /**
+         * 这段回复是**哪个 traceId** 的（`run-done` 带回来的）。`open()` 靠它判断
+         * 「现在打开的就是这条回复的主人」⇒ 不清。见 panel-logic 的 `replyBelongsTo`。
+         */
+        replyFor: null,
+        /**
+         * 在飞 run 的增量 trace 累加器（null = 没有在飞的 run）。
+         * 收到 `trace-event` 就折回并重画；收尾那份整棵 trace 回来时把它清掉
+         * （**收尾那份永远覆盖在飞的这份**，缺的 span 由它补齐）。
+         */
+        live: null,
         notice: '',           // 面板自己发的操作反馈（已接受 / 重启了 runner / 出错）
         noticeErr: false,
       };
@@ -536,6 +561,52 @@
         renderChat();
       }
 
+      // ---------- 在飞 run 的实时右栏（①） ----------
+
+      /**
+       * run 开跑：把右栏切成「这一轮的空树」。
+       *
+       * 为什么必须在 run-start 就切（而不是等第一条 span）：不切的话右栏留着**上一轮**那棵树，
+       * 一次十几秒的 run 期间它看起来就是「这次的结果」。同理清掉上一轮的回复 / 排行 / 用量 ——
+       * 它们都是**上一轮**的账，与在飞的这一轮无关（历史 run 在左栏列表里随时能点回来）。
+       */
+      function beginLiveRender() {
+        state.live = emptyTraceAccumulator();
+        state.reply = '';
+        state.replyFor = null;
+        replyEl.hidden = true;
+        replyEl.textContent = '';
+        summaryEl.replaceChildren();
+        usageEl.hidden = true;
+        ttlEl.textContent = '';
+        const ph = document.createElement('div');
+        ph.className = 'tr-empty';
+        ph.textContent = '// 这一轮在飞 —— span 会一个个长出来（收尾时用整棵 trace 覆盖）';
+        traceEl.replaceChildren(ph);
+      }
+
+      /**
+       * 增量事件 → 折回 → 重画整棵树。
+       *
+       * `playTrace` 是**幂等全量重画**（自己拆好树再画），所以这里不需要「局部更新」那套：
+       * 每次把当前已知的 spans 交回去就行。用 rAF 合帧是必要的 —— 一次 run 可能有几百条
+       * 记账事件，逐条重绘是白烧 CPU（而人眼只看得见一帧）。
+       */
+      let liveFrame = 0;
+      function renderLive() {
+        if (liveFrame) return;
+        liveFrame = requestAnimationFrame(() => {
+          liveFrame = 0;
+          if (!state.live) return;
+          const t = partialTrace(state.live);
+          // 空树不交给 playTrace（它对空 spans 直接返回 false，右栏会留着占位那行 —— 那正是我们要的）
+          if (t.spans.length === 0) return;
+          if (!playTrace(view, t)) return;
+          ttlEl.textContent = `${t.traceId}（在飞）`;
+          usageEl.hidden = false;
+        });
+      }
+
       // ---------- 拉数据 ----------
       async function refreshDev() {
         try {
@@ -546,6 +617,9 @@
         }
         // 会话 id 由 dev 环持有（清空对话会换它）—— 面板不自己造，只跟着走
         state.sessionId = state.dev?.sessionId ?? '';
+        // 页面**在 run 在飞时**才加载（刷新 / 新开标签）⇒ 补一个累加器，好接住后续的增量帧。
+        // 之前那些 span 收不到（SSE 不重放）—— 它们会随收尾那份整棵 trace 一起补齐。
+        if (state.dev?.running && !state.live) state.live = emptyTraceAccumulator();
         renderControls();
         renderChat();
         renderBanner();
@@ -590,10 +664,17 @@
         playTrace(view, trace);
         summaryEl.innerHTML = renderSummary(summarizeTrace(trace));
         // 回复正文只对**刚跑完的那一轮**有意义（trace 上没有它 —— 它是 run-done 事件带的）
-        // ⇒ 打开历史 run 必须清掉，否则它挂在别人的 trace 底下（张冠李戴）
-        state.reply = '';
-        replyEl.hidden = true;
-        replyEl.textContent = '';
+        // ⇒ 打开**别的** run 时必须清掉，否则它挂在别人的 trace 底下（张冠李戴）。
+        //
+        // ⚠️ 但不能**无条件**清：`run-done` 与「这条 trace 的收尾帧」几乎同毫秒到达，
+        // 而这条 handler 的链更长（refresh → refreshSession → renderChat → open）——
+        // 无条件清会把刚写上去的那句回复擦掉（端到端实测 17 ms，现象是「跑完了但没回复」）。
+        if (!replyBelongsTo(id, state.replyFor)) {
+          state.reply = '';
+          state.replyFor = null;
+          replyEl.hidden = true;
+          replyEl.textContent = '';
+        }
         renderList();
       }
 
@@ -602,10 +683,20 @@
         if (state.list.length && !state.current) await open(state.list[0].traceId);
       }
 
-      // ---------- 目录浏览 ----------
+      // ---------- 目录浏览 / 选文件（③） ----------
       // 浏览器拿不到用户选的文件夹的绝对路径（webkitdirectory 只给相对路径、
       // File System Access 只给 handle.name），而 dev 环要的是绝对路径 ⇒ 服务端列目录。
+      //
+      // 三个控件语义（2026-09-22 复核后定，前两条是实测出来的缺口）：
+      // - 点**目录名** ⇒ 进去；点 `..` ⇒ 上一层；「选这个目录」⇒ 把当前位置当工作目录。
+      // - 点**文件名** ⇒ 工作目录 = 它**所在的**目录（就是当前这一层），prompt 为空时填文件名。
+      //   只列目录的旧形态下，「让 agent 看某个文件」只能靠用户自己把名字打进 prompt。
+      // - 隐藏目录（`.git` / `~/x/.y`）单列在正常目录之后 —— 旧实现整批过滤掉，
+      //   于是那些目录**根本点不进去**（`..` 只能退到它上面，进不去）。
       let fsPath = '';
+      function closeFs() {
+        fsEl.hidden = true;
+      }
       async function openFs(at) {
         const res = await fetch('/api/fs?path=' + encodeURIComponent(at));
         if (!res.ok) {
@@ -617,30 +708,67 @@
         fsPath = body.path;
         fsPathEl.textContent = body.path;
         fsListEl.replaceChildren();
-        for (const name of body.dirs) {
+
+        const row = (text, cls, title, onClick) => {
           const b = document.createElement('button');
           b.type = 'button';
-          b.className = 'fs-item';
-          b.textContent = name + '/';
-          b.addEventListener('click', () => openFs(fsPath + '/' + name));
+          b.className = cls;
+          b.textContent = text;
+          if (title) b.title = title;
+          b.addEventListener('click', onClick);
           fsListEl.appendChild(b);
+        };
+        const enterDir = (name) => () => void openFs(`${fsPath}/${name}`);
+        /** 选一个文件：工作目录取**当前这一层**（它所在的目录），prompt 只在空时被填 */
+        const useFile = (name) => () => {
+          workdirEl.value = fsPath;
+          state.workdir = fsPath;
+          const picked = promptAfterFilePick(promptEl.value, name);
+          if (picked.filled) promptEl.value = picked.prompt;
+          closeFs();
+          setNotice(
+            picked.filled
+              ? `工作目录：${short(fsPath)}（prompt 已填「${name}」）`
+              : `工作目录：${short(fsPath)}（prompt 里已有内容，一个字没动）`,
+            false,
+          );
+        };
+
+        for (const name of body.dirs) row(name + '/', 'fs-item', '', enterDir(name));
+        for (const name of body.dotDirs ?? []) {
+          row(name + '/', 'fs-item fs-dot', '隐藏目录', enterDir(name));
+        }
+        const files = body.files ?? [];
+        if (files.length > 0) {
+          const sep = document.createElement('div');
+          sep.className = 'fs-sep';
+          sep.textContent = '文件';
+          fsListEl.appendChild(sep);
+          for (const name of files) {
+            row(name, 'fs-item fs-file', '选这个文件：工作目录设成它所在的目录，prompt 为空时填文件名', useFile(name));
+          }
+        }
+        if (body.filesTruncated) {
+          const more = document.createElement('div');
+          more.className = 'hint';
+          more.textContent = `（文件只列了前 ${files.length} 个）`;
+          fsListEl.appendChild(more);
         }
         fsEl.hidden = false;
         fsEl.dataset.parent = body.parent;
       }
-      $('fs-up').addEventListener('click', () => openFs(fsEl.dataset.parent || fsPath));
+      $('fs-up').addEventListener('click', () => void openFs(fsEl.dataset.parent || fsPath));
       $('fs-use').addEventListener('click', () => {
         workdirEl.value = fsPath;
         state.workdir = fsPath;
-        fsEl.hidden = true;
+        closeFs();
         setNotice(`工作目录：${short(fsPath)}`, false);
       });
+      // ⚠️ 这里**不是**开关：旧实现「面板开着时再点一次把它关掉」，于是
+      // 「在输入框敲了目标路径 → 点浏览…」这个最自然的动作是把面板关掉，
+      // 用户就以为「选不了别的目录」。现在点它**总是**按当前输入打开。
       $('browse').addEventListener('click', () => {
-        if (!fsEl.hidden) {
-          fsEl.hidden = true;
-          return;
-        }
-        void openFs(workdirEl.value.trim() || (state.dev ? state.dev.defaultWorkdir : '.'));
+        void openFs(browseTarget(workdirEl.value, state.dev ? state.dev.defaultWorkdir : '.'));
       });
 
       // ---------- 控件接线（只做「取值 → 调 panel-logic → 写回」） ----------
@@ -654,6 +782,9 @@
       });
       document.addEventListener('click', (e) => {
         if (capsEl.open && !capsEl.contains(e.target)) capsEl.open = false;
+        // 目录浏览器：点面板外面收起。`浏览…` 不再是开关之后，这是主要的收起方式
+        // （按钮自己那一支要排除，否则点它就会「开完立刻被这里收掉」）。
+        if (!fsEl.hidden && !fsEl.contains(e.target) && !$('browse').contains(e.target)) closeFs();
       });
 
       promptEl.addEventListener('keydown', (e) => {
@@ -758,6 +889,9 @@
         const nameEl = document.createElement('b');
         nameEl.textContent = s.name;
         liveEl.append(nameEl, ` · ${fmtMs(s.ms)}`);
+        // 收尾那份整棵 trace 到了 ⇒ 在飞的那份**作废**：`open()` 画的是权威版本，
+        // 而且此后不该再让迟到的增量帧把它重画成残缺的一棵（见 dev-protocol 的 DevEvent）
+        state.live = null;
         await refresh();
         await refreshSession();
         renderChat();
@@ -767,6 +901,8 @@
         const ev = JSON.parse(m.data);
         if (ev.kind === 'run-start') {
           liveEl.textContent = '正在跑…';
+          // 右栏从这一轮的空树开始（① 实时）：不这么做的话它留着上一轮那棵树
+          beginLiveRender();
           setNotice(
             `运行中：${short(ev.workdir)} · ${ev.toolSources === null ? '全量' : ev.toolSources.join(',')}` +
               `${ev.multiTurn ? ' · 多轮' : ''}`,
@@ -774,8 +910,16 @@
           );
           // run-start 是「确实开跑了」的权威信号 ⇒ 中止按钮在这里出现（不看面板自己的乐观状态）
           await refreshDev();
+        } else if (ev.kind === 'trace-event') {
+          // 在飞的一笔记账（①）：折回 + 合帧重画。`state.live` 为空说明收尾那份已经到了
+          // （或这一轮不是面板起的）⇒ 丢掉 —— 权威版本已经在屏幕上，别用残缺的覆盖它。
+          if (state.live && applyTraceEvent(state.live, ev.event)) renderLive();
         } else if (ev.kind === 'run-done') {
           state.reply = ev.finalText || '';
+          // 记下这条回复的**主人**：紧随其后的收尾帧会 open() 同一条 traceId，
+          // 那时不能把回复当「别人的」擦掉（见 panel-logic 的 replyBelongsTo）
+          state.replyFor = ev.traceId;
+          state.live = null;
           replyEl.hidden = state.reply.length === 0;
           replyEl.textContent = state.reply;
           // 判别顺序（先 stopReason 后 ok）是**语义**，抽在 panel-logic 里并带单测 ——
@@ -789,6 +933,8 @@
           renderChat();
         } else if (ev.kind === 'runner-restart') {
           setNotice(`重启 runner：${ev.reason}`, false);
+          // 重启前的在飞 run 已经不存在了（它的 trace 会丢，面板在别处明说）⇒ 别留一棵半截树
+          state.live = null;
           // 重启期间菜单是过期的（旧 runner 的能力）—— 先刷一次，等 runner-ready 再刷一次。
           await refreshDev();
         } else if (ev.kind === 'runner-ready') {
@@ -797,6 +943,7 @@
           await refreshDev();
         } else if (ev.kind === 'runner-error') {
           setNotice(ev.message, true);
+          state.live = null;
           await refreshDev();
         }
       });

package/dist/inspector-sink.js

@@ -15,3 +15,22 @@ export function createInspectSink(opts) {
         },
     };
 }
+export function createInspectEventSink(opts) {
+    const url = `http://${opts.host ?? '127.0.0.1'}:${opts.port}/ingest-event`;
+    const headers = { 'content-type': 'application/json' };
+    if (opts.token)
+        headers['x-agentia-token'] = opts.token;
+    let chain = Promise.resolve();
+    return {
+        send(event) {
+            chain = chain.then(async () => {
+                try {
+                    await fetch(url, { method: 'POST', headers, body: JSON.stringify(event) });
+                }
+                catch {
+                    /* 面板未开 / 已关 / 连接被拒：静默（观测失败不击穿 dev） */
+                }
+            });
+        },
+    };
+}

package/dist/inspector.js

@@ -60,6 +60,68 @@ function validateTrace(t) {
     }
     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)
@@ -142,6 +204,11 @@ 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');
@@ -352,6 +419,42 @@ export function startInspector(opts = {}) {
                 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()
@@ -374,14 +477,25 @@ export function startInspector(opts = {}) {
                 return;
             }
             /**
-             * 目录浏览器：`GET /api/fs?path=<绝对路径>` → 该目录下的**子目录名**（不含文件）。
+             * 目录浏览器：`GET /api/fs?path=<绝对路径>` →
+             * `{ path, parent, dirs, dotDirs, files, filesTruncated }`。
              *
              * 为什么需要它：浏览器**拿不到**用户选的文件夹的绝对路径 —— `<input webkitdirectory>`
              * 只给相对路径，File System Access API 只给 handle.name。而 dev 环要的是绝对路径
              * （工具按它解析）。⇒ 要么让用户手打路径，要么服务端列目录。后者才是「工作目录是
              * 主控件」（D3/D7）该有的手感。
              *
-             * 只列**目录**、不读文件内容；且只在 dev 钩子在场时开放（只读面板不暴露文件树）。
+             * 三条口径（2026-09-22 复核后改，前两条是实测出来的缺口）：
+             * - **文件也列**（`files`，只给名字、不读内容）：面板据此提供「选这个文件」——
+             *   工作目录取它所在目录、prompt 空时填文件名。只列目录时，「让 agent 看某个文件」
+             *   只能靠用户自己把文件名打进 prompt。
+             * - **隐藏目录单列**（`dotDirs`，不在 `dirs` 里）：以前一批过滤掉，于是
+             *   `~/xxx/.yyy` 这类目录**根本点不进去**（`..` 只能退到它上面，进不去）。
+             *   单列是为了不把 `.git` / `.cache` 混进正常浏览，同时保证**可达**。
+             * - `files` 有上限（`FILE_LIMIT`）并回 `filesTruncated`：一次列几千个文件的名
+             *   没有意义，但**必须明示**截断（本仓纪律：不许静默少给）。
+             *
+             * 只列名字、**不读文件内容**；且只在 dev 钩子在场时开放（只读面板不暴露文件树）。
              * 越界不是威胁（本机 dev 工具，token 已经挡住了其它进程），但**不存在 / 不是目录**
              * 要响亮报错 —— 静默回退到项目根会让 agent 对着错的目录乱写（D5）。
              */
@@ -408,11 +522,26 @@ export function startInspector(opts = {}) {
                     json(res, 400, { error: `读不了这个目录：${e.message}` });
                     return;
                 }
-                const dirs = entries
-                    .filter((e) => !e.name.startsWith('.') && isDirLikeEntry(join(abs, e.name), e))
-                    .map((e) => e.name)
-                    .sort();
-                json(res, 200, { path: abs, parent: dirname(abs), dirs });
+                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') {

package/dist/panel-logic.js

@@ -246,3 +246,138 @@ export function shortenPath(abs, opts = {}) {
         return `.${abs.slice(cwd.length)}`;
     return abs;
 }
+/** 空累加器：`state.live` 的初值，也是 e2e 折回的起点 */
+export function emptyTraceAccumulator() {
+    return { lastSeq: 0, traceId: '', spans: [] };
+}
+/**
+ * 应用一条增量记账事件。返回**它有没有被用上**（false = 丢了）。
+ *
+ * 丢的三种情形都是刻意的、**都不抛**：
+ * - `seq` 不前进（重复投递、迟到的旧帧）—— SSE 不保证送达，但送达的只能应用一次；
+ * - 指向**没见过的 `spanId`**（面板连上得晚，那个 `span.begin` 没收到）—— 绝不能凭空建
+ *   节点：那会造出一棵缺了上半截的假树。收尾那份会补齐；
+ * - 形状不认识（框架将来加了新事件类型）—— 静默放过，别让整个右栏停摆。
+ */
+export function applyTraceEvent(acc, ev) {
+    // 先卡 seq：它同时挡住「重复投递」与「乱序的旧帧」
+    if (!ev || typeof ev.seq !== 'number' || ev.seq <= acc.lastSeq)
+        return false;
+    const find = (spanId) => acc.spans.find((s) => s.spanId === spanId);
+    switch (ev.type) {
+        case 'span.begin': {
+            const src = ev.span;
+            // 拷一份：折回不该持有（更不该改写）协议对象 —— 面板会重画很多次
+            const copy = {
+                ...src,
+                attributes: { ...src.attributes },
+                events: (src.events ?? []).map((e) => ({ ...e })),
+            };
+            const seen = find(src.spanId);
+            // 同一个 `spanId` 再来一次 ⇒ **原地刷新**（重放幂等），不再挂一个同 id 的节点
+            if (seen)
+                Object.assign(seen, copy);
+            else {
+                acc.spans.push(copy);
+                if (!acc.traceId)
+                    acc.traceId = src.traceId;
+            }
+            break;
+        }
+        case 'span.end': {
+            const s = find(ev.spanId);
+            if (!s)
+                return false;
+            s.endedAt = ev.endedAt;
+            s.status = ev.status;
+            if (ev.error)
+                s.error = { ...ev.error };
+            if (ev.usage)
+                s.usage = { ...ev.usage };
+            break;
+        }
+        case 'span.event': {
+            const s = find(ev.spanId);
+            if (!s)
+                return false;
+            s.events.push({ ...ev.event });
+            break;
+        }
+        case 'span.attribute': {
+            const s = find(ev.spanId);
+            if (!s)
+                return false;
+            s.attributes = { ...s.attributes, [ev.key]: ev.value };
+            break;
+        }
+        case 'span.link': {
+            const s = find(ev.spanId);
+            if (!s)
+                return false;
+            s.links = [...(s.links ?? []), ev.link];
+            break;
+        }
+        default:
+            return false;
+    }
+    acc.lastSeq = ev.seq;
+    return true;
+}
+/**
+ * 当前已知的这棵树（交给 `playTrace` 画）。返回的是**副本** —— 渲染层拿它排序 / 展开，
+ * 不该回头改到累加器（下一次重画还要用同一份账）。
+ *
+ * `status` 只区分**在飞**与**已收尾**：根 span 还没有 `endedAt` 就是「在飞」，渲染层据此
+ * **不收尾**（否则根会被画成「已在某一刻完成」，那是个假事实）。收尾后取根自己的状态
+ * （`ok` / `error`），与框架口径一致。
+ */
+export function partialTrace(acc) {
+    const spans = acc.spans.map((s) => ({
+        ...s,
+        attributes: { ...s.attributes },
+        events: s.events.map((e) => ({ ...e })),
+    }));
+    const root = spans.find((s) => s.parentSpanId === null);
+    const status = root && root.endedAt === undefined ? 'running' : (root?.status ?? 'running');
+    return { traceId: acc.traceId, spans, status };
+}
+// ---------- ② 回复正文的归属 ----------
+/**
+ * 「`open(id)` 该不该**保留**屏幕上这条回复」。
+ *
+ * 背景：`run-done` 把回复正文写上去之后，面板会**自动 open 刚跑完的那一轮** ——
+ * 而 `open()` 原本无条件清掉回复区，于是那句回复在十几毫秒后被自己擦掉（看起来像「没回复」）。
+ *
+ * 口径与 `open()` 的原意图对齐：只有「现在打开的就是这条回复的主人」才保留；其余一律清
+ * （打开一条历史 run 时若还挂着**别人**的回复，那是张冠李戴 —— 比空白更糟）。
+ * `replyFor` 为 null（还没跑过 / 已清）**不等于**「谁都对」：默认清。
+ */
+export function replyBelongsTo(openId, replyFor) {
+    if (!openId || !replyFor)
+        return false;
+    return openId === replyFor;
+}
+// ---------- ③ 目录浏览 / 选文件 ----------
+/**
+ * 点「浏览…」时该打开哪个目录：**总是**按输入框的值。
+ *
+ * 旧实现把它当**开关**（面板开着时再点一次就关掉），于是「在输入框敲了目标路径 → 点浏览…」
+ * 这个最自然的动作反而是把面板关掉，用户就以为「选不了别的目录」。空值才回落到缺省工作目录；
+ * 首尾空白不该让路径读错。
+ */
+export function browseTarget(value, defaultDir) {
+    const v = value.trim();
+    return v.length > 0 ? v : defaultDir;
+}
+/**
+ * 点一个**文件**之后的 prompt 该是什么。
+ *
+ * 口径：**只在 prompt 为空时**填文件名（省一次打字）；用户已经写好的话**一个字都不动** ——
+ * 悄悄改写用户输入比少填一次糟得多。`filled` 是给面板回话用的（提示文案不同）。
+ * 工作目录的切换（取该文件**所在的**目录）由调用方做，不在这个纯判定里。
+ */
+export function promptAfterFilePick(current, name) {
+    if (current.trim().length > 0)
+        return { prompt: current, filled: false };
+    return { prompt: name, filled: true };
+}

package/dist/templates/package.json

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