# 终端等待 banner(wait banner + 跳过)设计 > 2026-09-09 · 目标 v0.18.2 ## 背景 `terminal_wait_for`(v0.18.1,PR #595 起 needle 支持 regex)会阻塞 agent 的工具调用直到 needle 出现 / 超时 / 终端退出。等待期间用户在侧边栏看不到任何"agent 正在等什么"的信号, 也无法干预——只能等 agent 自己超时(默认 10s,长等待可设到分钟级)。 需求: 1. agent 开始 `wait for needle` 时,在对应终端的顶部显示 banner: **「Agent 正在等待 {needle}」**,右侧「跳过等待」按钮; 2. 点击跳过后,`terminal_wait_for` 立即返回,agent 明确知道是用户跳过(而非超时); 3. 终端 tab 未激活时也能感知等待 → tab 标题加 ⏳ 徽章。 ## 方案对比 | 方案 | 思路 | 取舍 | |---|---|---| | **A. 搭现有推送车(采纳)** | 等待状态并入 `AgentTerminalSnapshot`,经现有 `/sidebar/ws/agent-terminals` 推送;跳过走新 `/sidebar/api` 方法 | 改动集中;零新 WS 生命周期;推送时机由 registry `notify()` 天然覆盖 | | B. 独立 waits 推送 WS | 新开 `/sidebar/ws/agent-waits` | 重连/订阅/teardown 全套翻倍,YAGNI | | C. 客户端轮询 | 定时拉 terminal 列表 | 延迟与开销差,违背现有推送架构 | 已确认的两个决策: - **skip 语义 = 新增第四种返回 `kind:'skipped'`**(不复用 timeout、不走 abort——abort 语义属于工具调用取消,用户语义只是"不等了"); - **banner 主体在终端卡片顶部 + tab 标题 ⏳ 徽章**(复用 v0.12+ 的 `TabDescriptor.badge` 通道,git tab 有先例)。 ## 设计 ### 1. Host:`AgentPtyRegistry`(src/agent-pty.ts) - `AgentTerminalHandle` 增活动等待记录数组 `waits: Array<{ needle, since, skipped }>`; 并发 `wait_for` 同 uuid 时各登记一条。 - `waitFor()`:快速路径(已 exited / needle 已在 transcript)不登记、不推 banner; 进入轮询前登记记录并 `notify()`(banner 出现),`finally` 移除记录并 `notify()`(banner 消失——found/timeout/exited/skipped/工具 abort 五条出路统一走 finally)。 - 轮询每圈检查本记录的 `skipped` → 返回 `{ kind:'skipped', needle }`;50ms 轮询 天然承载跳过延迟,无需事件唤醒。与终端退出在同一 tick 竞争时**退出优先**(见实施 偏差记录)。 - 新方法 `skipWait(uuid): number`:标记该 uuid 全部活动记录并返回条数;uuid 未知 → `not-found` 404(与 `expect` 一致)。 - `AgentTerminalSnapshot` 增 `waiting?: { needle: string; since: number }`(取最新登记 的一条;并发等待显示最新 needle,跳过跳过全部)。 - `AgentTerminalWaitResult` 增 `skipped` 变体。 ### 2. 工具层:`terminal_wait_for`(src/tools.ts) - output schema `oneOf` 增 `{ kind: 'skipped', needle }` 分支; - render:`Skipped by user while waiting for "" — the wait ended early; call terminal_read to inspect the transcript if needed.`; - 工具描述补一句:用户可从侧栏 banner 跳过等待(返回 `skipped`)。 ### 3. API:`buildApi`(src/index.ts) - 新方法 `'agent-pty.skip-wait'`(命名对齐现有 `'agent-pty.close'`): `requireString uuid` → `registry.skipWait(uuid)`;degraded 模式(registry 为 null) 幂等返回 `{ ok: true, skipped: 0 }`。 ### 4. 推送零改动 `attachAgentList` 发的就是 `registry.list(sessionId)`,snapshot 新增的 `waiting` 字段 自动随车;等待开始/结束由 `notify()` 触发推送。兼容性: - 旧客户端 + 新 host:多余字段被忽略; - 新客户端 + 旧 host:永远收不到 `waiting` → 无 banner,安全降级。 ### 5. 客户端状态(src/client/state.ts) - `SidebarState` 增 `agentWaits: Record`(默认 `{}`;等待结束即删除键); - `reconcileAgentTerminals` 从同一推送同步该映射——需解除"无 tab 增删即早退"的短路 (仅 waiting 变化也要产出新状态); - **不持久化**:`sanitizeState` 逐字段重建、不恢复该字段 → 刷新后自然清空;WS attach 即发首条推送,立刻纠正。 ### 6. Banner(src/client/TerminalView.tsx) - 仅 `agent:` tab 渲染;位置在终端区顶部(现有 fatal/deps banner 之上); - 内容:`t('terminalWaitBanner', { needle })`(zh「Agent 正在等待 {needle}」)+ 右侧 `t('terminalSkipWait')`(zh「跳过等待」)按钮 → `api.agentSkipWait(uuid)`; - needle 超 ~80 字符截断显示,`title` 悬浮显全文; - banner 消失完全由推送驱动(skipped/exited/abort 均经 `notify`),点击不做乐观更新。 ### 7. Tab ⏳ 徽章(src/client/builtins/tabs.tsx) - terminal 描述符增 `badge: (_ctx, scope, state) => ...`:`agent:` tab 且 `state.agentWaits[uuid]` 存在时返回 `'⏳'`,否则 null——复用 v0.12+ 徽章通道 (git changes tab 先例),不碰 `TabBar`。 ### 8. i18n / 样式 - 词典键:`terminalWaitBanner`、`terminalSkipWait`;zh/en 同步,**ja 翻译必须同步 `src/client/locales-ja.ts`**(仓库规则); - `.terminalWaitBanner` 全部消费 `--dsw-alias-*` / `--ds-*` 令牌,无硬编码颜色 (皮肤契约,`tests/theme.spec.ts` 守护)。 ### 9. 测试 - `tests/agent-pty.spec.ts`:跳过返回 `skipped`;活动等待期间 snapshot 含 `waiting`、 结束后消失;`skipWait` 未知 uuid → 404、无活动等待 → 0;等待开始/结束触发 `notify`; - `tests/tools.spec.ts`:FakeRegistry 增 skipped 形状;schema/render 断言; - `tests/agent-terminal-reconcile.spec.ts`:`agentWaits` 设置/清除、仅 waiting 变化也 触发状态更新; - badge / banner 组件测试视现有 jsdom 基建可行性补齐。 ## 边缘情况 - **并发多个 `wait_for` 同一 uuid**:banner/⏳ 显示最新登记的 needle;跳过一次跳过全部; - **工具调用取消(abort)**:`finally` 移除记录 → banner 消失并推送; - **终端退出 / 用户关 tab(close frame 杀 pty)**:轮询下一圈返回 `exited`,记录移除; - **UI-tab 终端**:无等待概念,`agentWaits` 永不含有其条目。 ## 不做的事 - 不新增独立 waits WebSocket(方案 B 否决); - 不改 `ctx.betterSidebar` 服务面(`external-plugin-guide.md` 无需同步); - 不做乐观 UI(banner 消失以服务端推送为准)。 ## 实施偏差记录 - **⏳ tab 徽章不走 `TabDescriptor.badge`**:实现时核实该 API 是 type-keyed (`badge(ctx, scope, state)`,无 tab 参数、external 插件共享),无法定位单个 tab。改为 Sidebar 壳层 `tabBadgeOf` 的 sidebar-internal 特例(agent: 前缀判断 + `state.agentWaits` 查表),`service.ts` 与 external-plugin-guide.md 零改动。 - **banner 抽为独立组件 `TerminalWaitBanner.tsx`**:设计原文写在 TerminalView 内;抽出后无 xterm 依赖,jsdom 单测可直接渲染(TerminalView 仍负责订阅 store 并把 onSkip 接到 `api.agentSkipWait`)。 - **词典同步扩到全部 21 个语言文件**:设计只写了 zh/en/ja,但 `tests/locales.spec.ts` 断言每个第三方词典与 zh 键集相等——只同步三语会让该 守护测试挂掉。按仓库惯例(全语言同步,如 e8761ee)补齐其余 18 语言同两键。 - **banner 配色**:仓库 CSS 无 state-info 令牌,沿用 `.terminalBanner` 的 warn 对(`--dsw-alias-state-warn-label/-tertiary`),符合皮肤契约。 - **设计文档与计划随 feat 分支进 PR**:main 受分支保护,纯文档直推被 hook 拒绝 (`4a6a77a` / `2448068` 随本分支合并)。 - **测试断言以文本计数取代 CSS 类名**:CSS module 类名在测试变换下不稳定, ⏳ 数量断言改从 `textContent` 计数;长 needle 截断断言改为计量 needle 自身 贡献字符数(本地化句子包裹 needle,整体长度断言与语言相关,原计划内部矛盾)。 - **新测试的 localStorage 兜底**:Node 26 + jsdom 29 组合下测试环境可能无全局 `localStorage`(上游 `bottom-auto-terminal.spec.tsx` 在同环境即失败,属已知 win32/环境非回归类);新 spec 的 afterEach 加守卫 + try/catch(jsdom opaque origin 下 localStorage 可以是 throwing accessor,裸 typeof 也会炸), 上游测试一律未动。 - **已知限制:跨会话 pinned 虚拟 tab 收不到实时 banner/⏳**(Copilot review 指出):等待状态 feed 按 viewer 会话订阅(`/sidebar/ws/agent-terminals` 按 当前 sessionId 连接),钉到其他会话的 pinned 虚拟 agent tab (`pinned::agent:`)在其 home 会话非当前会话时收不到 实时等待状态。修复需跨会话 wait feed 多路复用(连 home 会话推送或聚合 推送),超出本特性范围,留待后续设计;跳过 API 按 uuid 全局寻址,跨会话 跳过本身可达。 - **Copilot review 第三轮修复(合并 rc.1 后扫描)**: 1. `truncateNeedle` 改按 Unicode 码点截断(`Array.from`),原 UTF-16 码元 截断会在截断点劈开代理对(emoji 渲染为替换字符); 2. banner 消息加 `role="status"` + `aria-live="polite"`,完整未截断的 本地化消息经 `aria-label` 提供给读屏器(不新增词典键); 3. `terminal` tab 类型禁用时推送处理从整体跳过改为 `mirrorAgentWaits` ——仍镜像权威 `waiting` map(等在禁用窗口内 resolve 也清 banner 状态), 只跳过 tab 增删 reconcile,否则重启用后已开终端残留 stale banner/⏳ 直到无关推送到达; 4. badge 测试跟踪挂载的 root 并在 `afterEach` 里先 unmount 再清 DOM (裸 `innerHTML = ''` 不触发 React effect 清理,store 订阅/host-feed effect 会泄漏进后续测试); 5. 补并发双 `waitFor` 同 uuid 测试:快照显示最新 needle(`waits.at(-1)`)、 `skipWait` 返回 2、两个 promise 都以各自 needle `skipped` 收敛、快照 清空且 skipWait 幂等归零。 - **轮询优先级:终端退出优先于用户跳过**(v0.19.0 发版前 review 发现):设计原文 写「每圈优先检查 `skipped`」,实现是 `aborted → handle.exited → record.skipped`, 即 pty 退出与用户点跳过落进同一个 50ms tick 时返回 `exited`。**维持实现现状**, 设计原文已同步为「退出优先」:两种顺序下用户可见结果完全相同(banner 消失、 `skipWait` 返回 0、等待结束),只有工具结果的 `kind` 文案不同;而进程已死是 客观事实,报 `exited` 不撒谎,工具结果本身也引导 agent 用 `terminal_read` 复核。 若日后要让「用户意图优先」,改动点是循环内两行先后 + 一条同 tick 竞态测试。 - **两个已知限制的补充记录**(同一次 review): 1. **pinned tab 的 banner 与 ⏳ 不对称**:pinned 虚拟 id 是 `pinned::agent:`,`isAgentTabId` 只认 `agent:` 前缀,因此 钉住的 agent tab **不会误挂 ⏳**(比"收不到"更强的保证);但 Workbench 渲染 pinned tab 时给 TerminalView 传的是**原 tab id + home 作用域**,所以 home 会话 正在等待时该视图**会**显示 banner,而它的 strip 徽章仍不出现。两个信号数据源 不同(banner 读 home store,徽章读 viewer 的 `agentWaits`)。 2. **⏳ 到不了 DSH 原生右侧栏**:徽章经 `getTabBadge` 渲染,唯一消费点是插件 自绘的 `TabBar`;原生栏的 `NativeTabTitle` 契约只带 title,不带 badge。agent 终端标签页走 `openTabInBottomPane`(底部工作台),故 agent 流程可见;这是原生 承载面契约决定的上限,非本特性缺陷。 - **注释随实现同步**(v0.19.0 发版前 review):`use-host-feeds.ts` effect 头部原写 「terminal tab 类型禁用时 pushes are ignored」,与上面第 3 项的 `mirrorAgentWaits` 改法矛盾,已改为「不增删 tab,但仍镜像权威 wait map」;`src/index.ts` 的 `agent-pty.skip-wait` 注释原文把「无活动等待 → 0」泛化成了「幂等」,已收窄为 「无活动等待返回 `{skipped:0}`;未知 uuid 走 `expect` → 404(已退出的终端即属此 列),客户端 `.catch` 容忍并等下一次推送收敛」。