apes-sidebar/docs/plans/2026-09-09-terminal-wait-banner-design.md

终端等待 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 "<needle>" — 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<uuid, { needle: string; since: number }>（默认 {}；等待结束即删除键）；
• 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:<homeSessionId>:agent:<uuid>）在其 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:<homeSessionId>:agent:<uuid>，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 容忍并等下一次推送收敛」。