981 lines
40 KiB
Markdown
981 lines
40 KiB
Markdown
# 终端等待 banner + 跳过等待 Implementation Plan
|
||
|
||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||
|
||
**Goal:** agent 阻塞在 `terminal_wait_for` 时，对应终端卡片顶部显示「Agent 正在等待 {needle}」banner（右侧「跳过等待」按钮），tab 标题加 ⏳ 徽章；跳过后工具返回新增的 `{kind:'skipped'}`。
|
||
|
||
**Architecture:** 等待状态登记在 `AgentPtyRegistry` 的 handle 上，随现有 `/sidebar/ws/agent-terminals` 推送快照（`waiting` 字段）自然下发；跳过走新增 `/sidebar/api/agent-pty.skip-wait` 路由。客户端把推送镜像进 `state.agentWaits`，banner 组件与 tab 徽章从 store 读。
|
||
|
||
**Tech Stack:** TypeScript / React 18 / vitest（node 环境 pty 测试 + jsdom Sidebar 壳测试）/ ws 推送 / CSS Modules（皮肤令牌）。
|
||
|
||
**Spec:** `docs/plans/2026-09-09-terminal-wait-banner-design.md`（与本计划同分支，执行者两份都读）。
|
||
|
||
## Global Constraints
|
||
|
||
- 分支：`feat/wait-banner`（已含设计文档提交 `4a6a77a`）；所有代码改动走该分支 → PR，禁止直推 main（分支保护）。
|
||
- 皮肤契约：新增 CSS 只允许 `--dsw-alias-*` / `--dsw-font-*` / `--ds-*` 令牌；本项目复用现成 warn 对 `--dsw-alias-state-warn-label` / `--dsw-alias-state-warn-tertiary`（仓库 CSS 无 state-info 令牌，已核实）。
|
||
- i18n：新增 zh key 必须同步 en 词典与 `src/client/locales-ja.ts` 的 ja 翻译。
|
||
- client bundle 纯度门：新文件只准 import 本插件模块（locales / css / api），禁止 value-import `@dsh-external/*` 或非白名单 `@deepseek-ai/*`。
|
||
- 不改 `src/client/service.ts` / `docs/external-plugin-guide.md`（⏳ 徽章走 shell 层特例，不动 TabDescriptor API）。
|
||
- 上游测试（含 win32 已知 27 个非回归失败）一律不改。
|
||
- 每个任务用 `pnpm exec vitest run <file>` 验证；最终任务必须 `pnpm lint` + `pnpm typecheck` + `pnpm test` + `pnpm build` 全绿才 push（CI 曾因漏 lint 挂过）。
|
||
- 提交信息风格：`feat(terminal): ...` / `test(...)`，仓库惯例小写 scope。
|
||
|
||
---
|
||
|
||
### Task 1: Registry 等待登记 + `skipped` 结果 + `waiting` 快照
|
||
|
||
**Files:**
|
||
- Modify: `src/agent-pty.ts`
|
||
- Test: `tests/agent-pty.spec.ts`
|
||
|
||
**Interfaces:**
|
||
- Consumes: 现有 `AgentPtyRegistry.waitFor` / `notify` / `subscribe` / `snapshotOf`。
|
||
- Produces:
|
||
- `type AgentTerminalActiveWait = { needle: string; since: number; skipped: boolean }`
|
||
- `AgentTerminalHandle.waits: AgentTerminalActiveWait[]`（create 时初始化为 `[]`）
|
||
- `AgentTerminalSnapshot.waiting?: { needle: string; since: number }`（最新一条活动等待）
|
||
- `AgentTerminalWaitResult` 新增 `{ kind: 'skipped'; needle: string }` 变体
|
||
- `registry.skipWait(uuid: string): number`（标记全部活动等待，返回条数；未知 uuid 抛 not-found）
|
||
|
||
- [ ] **Step 1: 写失败测试（4 个新用例，加在 `describe('AgentPtyRegistry')` 内、现有 `waitFor` 用例之后）**
|
||
|
||
在 `tests/agent-pty.spec.ts` 的 import 块不需要新增（`AgentPtyRegistry` / `snapshotOf` 已导入）。追加用例：
|
||
|
||
```ts
|
||
it('waitFor returns skipped when the user skips from the sidebar', async () => {
|
||
const registry = new AgentPtyRegistry(testShell())
|
||
try {
|
||
const uuid = registry.create('s1', 'skip-test', 'echo skip-ready', process.cwd(), 80, 24)
|
||
await waitForTranscript(registry, uuid, 'skip-ready')
|
||
// waitFor registers its record synchronously (before the first poll
|
||
// await), so the skip can fire immediately after the call.
|
||
const waitPromise = registry.waitFor(uuid, 'NEVER_APPEARS_XYZ', 30_000)
|
||
expect(await registry.skipWait(uuid)).toBe(1)
|
||
const result = await waitPromise
|
||
expect(result.kind).toBe('skipped')
|
||
if (result.kind === 'skipped') expect(result.needle).toBe('NEVER_APPEARS_XYZ')
|
||
// Idempotent: nothing left to skip once the wait resolved.
|
||
expect(registry.skipWait(uuid)).toBe(0)
|
||
} finally {
|
||
registry.disposeAll()
|
||
}
|
||
})
|
||
|
||
it('snapshot exposes waiting while a wait is active and clears after it ends', async () => {
|
||
const registry = new AgentPtyRegistry(testShell())
|
||
try {
|
||
const uuid = registry.create('s1', 'wait-snap', 'echo snap-ready', process.cwd(), 80, 24)
|
||
await waitForTranscript(registry, uuid, 'snap-ready')
|
||
const waitPromise = registry.waitFor(uuid, 'LATER_MARK_9', 30_000)
|
||
// Registration happens synchronously before waitFor's first await.
|
||
expect(registry.list('s1')[0]?.waiting?.needle).toBe('LATER_MARK_9')
|
||
expect(typeof registry.list('s1')[0]?.waiting?.since).toBe('number')
|
||
expect(registry.skipWait(uuid)).toBe(1)
|
||
const result = await waitPromise
|
||
expect(result.kind).toBe('skipped')
|
||
expect(registry.list('s1')[0]?.waiting).toBeUndefined()
|
||
} finally {
|
||
registry.disposeAll()
|
||
}
|
||
})
|
||
|
||
it('fires change listeners when a wait starts and ends', async () => {
|
||
const registry = new AgentPtyRegistry(testShell())
|
||
try {
|
||
const uuid = registry.create('s1', 'watched-wait', 'echo notify-ready', process.cwd(), 80, 24)
|
||
await waitForTranscript(registry, uuid, 'notify-ready')
|
||
let changes = 0
|
||
const unsubscribe = registry.subscribe(() => { changes += 1 })
|
||
const waitPromise = registry.waitFor(uuid, 'NEVER_NOTIFY_1', 30_000)
|
||
const afterStart = changes
|
||
expect(afterStart).toBeGreaterThanOrEqual(1)
|
||
expect(await registry.skipWait(uuid)).toBe(1)
|
||
expect(await waitPromise).toEqual({ kind: 'skipped', needle: 'NEVER_NOTIFY_1' })
|
||
expect(changes).toBeGreaterThan(afterStart)
|
||
unsubscribe()
|
||
} finally {
|
||
registry.disposeAll()
|
||
}
|
||
})
|
||
|
||
it('skipWait rejects an unknown uuid with not-found', () => {
|
||
const registry = new AgentPtyRegistry(testShell())
|
||
try {
|
||
expect(() => registry.skipWait('missing-uuid')).toThrow(/not found/)
|
||
} finally {
|
||
registry.disposeAll()
|
||
}
|
||
})
|
||
```
|
||
|
||
- [ ] **Step 2: 跑测试确认失败**
|
||
|
||
Run: `pnpm exec vitest run tests/agent-pty.spec.ts`
|
||
Expected: FAIL — `waiting` 为 undefined、`skipWait` 不存在、skipped 分支不存在（TS 编译错误或断言失败）。
|
||
|
||
- [ ] **Step 3: 实现 `src/agent-pty.ts`**
|
||
|
||
(a) 在 `AgentTerminalReadResult` 之后、`AgentTerminalWaitResult` 之前新增：
|
||
|
||
```ts
|
||
/** One active wait_for registration on a handle (banner + skip bookkeeping). */
|
||
export interface AgentTerminalActiveWait {
|
||
/** The needle being awaited (shown on the sidebar wait banner). */
|
||
needle: string
|
||
/** Epoch ms when the wait registered (age display / debugging). */
|
||
since: number
|
||
/** Flipped by `skipWait()`; the waiting poll returns `skipped` within one tick. */
|
||
skipped: boolean
|
||
}
|
||
```
|
||
|
||
(b) `AgentTerminalWaitResult` union 末尾追加变体：
|
||
|
||
```ts
|
||
| {
|
||
/** The user skipped the wait from the sidebar banner. */
|
||
kind: 'skipped'
|
||
/** The needle that was awaited. */
|
||
needle: string
|
||
}
|
||
```
|
||
|
||
(c) `AgentTerminalSnapshot` 追加字段（`exitSignal` 之后）：
|
||
|
||
```ts
|
||
/**
|
||
* The model's active `terminal_wait_for` on this terminal (the sidebar
|
||
* renders the wait banner from it). Present only while a wait is
|
||
* registered; carries the LATEST wait when several overlap.
|
||
*/
|
||
waiting?: { needle: string; since: number }
|
||
```
|
||
|
||
(d) `AgentTerminalHandle` 追加字段（`exitSignal` 之后）：
|
||
|
||
```ts
|
||
/** Active wait_for registrations (skip bookkeeping; empty while idle). */
|
||
waits: AgentTerminalActiveWait[]
|
||
```
|
||
|
||
(e) `create()` 的 handle 字面量中 `exited: false,` 之后加 `waits: [],`。
|
||
|
||
(f) `snapshotOf` 在 `return out` 前追加：
|
||
|
||
```ts
|
||
const active = handle.waits.at(-1)
|
||
if (active !== undefined) out.waiting = { needle: active.needle, since: active.since }
|
||
```
|
||
|
||
(g) 新方法（放在 `waitFor` 之后）：
|
||
|
||
```ts
|
||
/**
|
||
* Mark every active wait on one terminal as skipped (the sidebar banner's
|
||
* skip button). Each waiting poll loop observes its record's flag within
|
||
* one 50ms tick and returns `{kind:'skipped'}`. Idempotent: 0 when nothing
|
||
* is waiting (a stale banner racing a wait that already resolved).
|
||
* @returns the number of waits that transitioned to skipped.
|
||
*/
|
||
skipWait(uuid: string): number {
|
||
const handle = this.expect(uuid)
|
||
let count = 0
|
||
for (const record of handle.waits) {
|
||
if (!record.skipped) {
|
||
record.skipped = true
|
||
count += 1
|
||
}
|
||
}
|
||
return count
|
||
}
|
||
```
|
||
|
||
(h) 重写 `waitFor` 中段（`const firstHit = ...` 快速路径之后到方法结尾），登记记录 + 轮询检查 + `finally` 清理：
|
||
|
||
```ts
|
||
const firstHit = locateNeedle(handle.transcript, needle, re)
|
||
if (firstHit !== undefined) {
|
||
return { kind: 'found', needle, line: firstHit.line, column: firstHit.column, match: firstHit.match, elapsedMs: Date.now() - start }
|
||
}
|
||
// Register the active wait so the sidebar can show the wait banner (the
|
||
// snapshot's `waiting` field rides the agent-terminals push). Registered
|
||
// only after the fast paths: a wait that resolves instantly never
|
||
// flashes the banner. The notify() makes every push subscriber (the
|
||
// sidebar view) converge on the new waiting state immediately.
|
||
const record: AgentTerminalActiveWait = { needle, since: start, skipped: false }
|
||
handle.waits.push(record)
|
||
this.notify()
|
||
try {
|
||
while (true) {
|
||
if (signal?.aborted) signal.throwIfAborted()
|
||
if (handle.exited) {
|
||
return { kind: 'exited', needle, exitCode: handle.exitCode ?? null, exitSignal: signalNameOf(handle.exitSignal) }
|
||
}
|
||
if (record.skipped) {
|
||
return { kind: 'skipped', needle }
|
||
}
|
||
const hit = locateNeedle(handle.transcript, needle, re)
|
||
if (hit !== undefined) {
|
||
return { kind: 'found', needle, line: hit.line, column: hit.column, match: hit.match, elapsedMs: Date.now() - start }
|
||
}
|
||
if (Date.now() >= deadline) {
|
||
return { kind: 'timeout', needle, timeoutMs: timeout, totalLines: handle.transcript.split('\n').length }
|
||
}
|
||
await new Promise(resolve => {
|
||
const t = setTimeout(resolve, 50)
|
||
// Allow the Node process to exit even if the timer is pending.
|
||
if (typeof t === 'object' && 'unref' in t) (t as { unref: () => void }).unref()
|
||
})
|
||
}
|
||
} finally {
|
||
const index = handle.waits.indexOf(record)
|
||
if (index !== -1) handle.waits.splice(index, 1)
|
||
this.notify()
|
||
}
|
||
```
|
||
|
||
(i) `waitFor` 的 JSDoc：`@returns one of `found` / `timeout` / `exited`.` 改为 `@returns one of `found` / `timeout` / `exited` / `skipped`.`；并在 `@param signal` 行后补一行 `* A wait can also be skipped by the user from the sidebar banner (`skipWait`), which resolves it with `{kind:'skipped'}`.`
|
||
|
||
- [ ] **Step 4: 跑测试确认通过**
|
||
|
||
Run: `pnpm exec vitest run tests/agent-pty.spec.ts`
|
||
Expected: PASS（全部用例，含既有 425 行文件内的用例）。
|
||
|
||
- [ ] **Step 5: Commit**
|
||
|
||
```bash
|
||
git add src/agent-pty.ts tests/agent-pty.spec.ts
|
||
git commit -m "feat(terminal): registry 支持等待登记、skipWait 与 skipped 结果"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 2: 工具层 `skipped` 分支 + 宿主 `agent-pty.skip-wait` 路由
|
||
|
||
**Files:**
|
||
- Modify: `src/tools.ts`（terminal_wait_for 定义，约 287-377 行）
|
||
- Modify: `src/index.ts`（buildApi 表，`'agent-pty.close'` 之后，约 545 行）
|
||
- Test: `tests/tools.spec.ts`
|
||
|
||
**Interfaces:**
|
||
- Consumes: Task 1 的 `AgentTerminalWaitResult` skipped 变体、`registry.skipWait(uuid): number`。
|
||
- Produces: `/sidebar/api/agent-pty.skip-wait` 路由（payload `{uuid}` → `{ok:true, skipped:number}`）；工具 output schema 第四分支；Task 4 的客户端 `api.agentSkipWait` 调它。
|
||
|
||
- [ ] **Step 1: 写失败测试**
|
||
|
||
`tests/tools.spec.ts`：(a) `FakeRegistry` 增加注入口 —— 在 `readonly terminals = ...` 行后加属性，并把 `waitFor` 改为：
|
||
|
||
```ts
|
||
/** When set, waitFor resolves with the skipped shape instead of the found default. */
|
||
nextWaitResult: { kind: 'skipped' } | undefined
|
||
|
||
waitFor(_uuid: string, needle: string): Promise<
|
||
{ kind: 'found'; needle: string; line: number; column: number; match: string; elapsedMs: number }
|
||
| { kind: 'skipped'; needle: string }
|
||
> {
|
||
// Mirrors the registry's empty-needle rejection (the tool layer no
|
||
// longer duplicates this check).
|
||
if (needle === '') return Promise.reject(new Error('needle must be a non-empty string'))
|
||
if (this.nextWaitResult !== undefined) return Promise.resolve({ kind: 'skipped', needle })
|
||
return Promise.resolve({ kind: 'found', needle, line: 0, column: 0, match: needle, elapsedMs: 1 })
|
||
}
|
||
```
|
||
|
||
(b) 在 `describe('agent terminal tools')` 内、现有 `terminal_wait_for returns the registry result...` 用例后追加：
|
||
|
||
```ts
|
||
it('terminal_wait_for returns skipped (schema-valid) when the registry reports a user skip', async () => {
|
||
const { captured, registry } = mount()
|
||
const tool = toolOf(captured, 'terminal_wait_for')
|
||
registry.nextWaitResult = { kind: 'skipped' }
|
||
const value = await tool.execute({ uuid: 'uuid-1', needle: 'BUILD_OK', timeout_ms: 1000 }, exec('s1'))
|
||
expect(value).toEqual({ kind: 'skipped', needle: 'BUILD_OK' })
|
||
expect(validateJsonSchemaValue(tool.output.schema, value, 'value')).toEqual([])
|
||
})
|
||
|
||
it('terminal_wait_for render describes the user skip and the needle', () => {
|
||
const { captured } = mount()
|
||
const tool = toolOf(captured, 'terminal_wait_for')
|
||
const blocks = tool.output.render({}, { kind: 'skipped', needle: 'BUILD_OK' }) as Array<{ type: string; text: string }>
|
||
expect(blocks[0]!.type).toBe('text')
|
||
expect(blocks[0]!.text).toContain('Skipped by user')
|
||
expect(blocks[0]!.text).toContain('BUILD_OK')
|
||
})
|
||
```
|
||
|
||
- [ ] **Step 2: 跑测试确认失败**
|
||
|
||
Run: `pnpm exec vitest run tests/tools.spec.ts`
|
||
Expected: FAIL（schema 拒绝 skipped / render 走到 exited 分支输出不符）。
|
||
|
||
- [ ] **Step 3: 实现**
|
||
|
||
(a) `src/tools.ts` terminal_wait_for：
|
||
|
||
描述末尾（`'The wait is cooperative: ...'` 句之后）追加一句：
|
||
|
||
```ts
|
||
+ 'The user can skip the wait from the sidebar ( a banner on the terminal\'s tab shows the needle and a skip button ) — the tool then returns `skipped`.',
|
||
```
|
||
|
||
output.schema 的 `oneOf` 数组末尾（exited 分支对象之后）追加：
|
||
|
||
```ts
|
||
{
|
||
type: 'object',
|
||
additionalProperties: false,
|
||
properties: {
|
||
kind: { type: 'string', required: true, const: 'skipped' },
|
||
needle: { type: 'string', required: true },
|
||
},
|
||
},
|
||
```
|
||
|
||
render 的 value 类型与分支 —— `const v = value as { kind: 'found' | 'timeout' | 'exited' | 'skipped'; ... }`（原行加 `'skipped'`），并在 timeout 分支后插入：
|
||
|
||
```ts
|
||
if (v.kind === 'skipped') {
|
||
return [{ type: 'text', text: `Skipped by user while waiting for "${v.needle}" — the wait ended early. Call terminal_read to inspect the transcript and decide how to proceed.` }]
|
||
}
|
||
```
|
||
|
||
(b) `src/index.ts` buildApi 表，`'agent-pty.close'` 条目（约 541-545 行）之后追加：
|
||
|
||
```ts
|
||
// The sidebar wait banner's skip button: abort every active
|
||
// terminal_wait_for on one agent terminal. Idempotent — 0 when nothing
|
||
// is waiting (a stale banner racing a wait that already resolved).
|
||
// Degraded mode (node-pty unavailable) has no registry and no waits: an
|
||
// honest ok.
|
||
'agent-pty.skip-wait': (payload) => {
|
||
const uuid = requireString(payload, 'uuid')
|
||
return { ok: true, skipped: agentPtyRegistry?.skipWait(uuid) ?? 0 }
|
||
},
|
||
```
|
||
|
||
- [ ] **Step 4: 跑测试确认通过**
|
||
|
||
Run: `pnpm exec vitest run tests/tools.spec.ts`
|
||
Expected: PASS。
|
||
|
||
- [ ] **Step 5: Commit**
|
||
|
||
```bash
|
||
git add src/tools.ts src/index.ts tests/tools.spec.ts
|
||
git commit -m "feat(terminal): terminal_wait_for 增 skipped 结果与 agent-pty.skip-wait 路由"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 3: 客户端状态 `agentWaits` 镜像 + 推送类型
|
||
|
||
**Files:**
|
||
- Modify: `src/client/state.ts`（SidebarState 接口 ~121 行、makeDefaultState ~221 行、sanitizeState ~1283 行、reconcileAgentTerminals ~1017 行）
|
||
- Modify: `src/client/sidebar/use-host-feeds.ts`（~66 行解析类型）
|
||
- Test: `tests/agent-terminal-reconcile.spec.ts`
|
||
|
||
**Interfaces:**
|
||
- Consumes: 宿主推送数组（Task 1 的 snapshot 含 `waiting`）。
|
||
- Produces:
|
||
- `SidebarState.agentWaits: Record<string, { needle: string; since: number }>`（uuid → 活动等待；瞬态，不持久化）
|
||
- `reconcileAgentTerminals(state, list)` 的 list 元素增 `waiting?: { needle: string; since: number } | null`，并把等待状态镜像进 `agentWaits`（仅等待变化也产出新状态）。
|
||
|
||
- [ ] **Step 1: 写失败测试**
|
||
|
||
`tests/agent-terminal-reconcile.spec.ts` 追加两个用例（沿用文件现有 import，无需新增）：
|
||
|
||
```ts
|
||
it('mirrors the pushed waiting state into agentWaits and clears it when it ends', () => {
|
||
let s = makeDefaultState()
|
||
s = reconcileAgentTerminals(s, [{ uuid: 'aaa-111', title: 'busy', waiting: { needle: 'READY_1', since: 42 } }])
|
||
expect(s.agentWaits['aaa-111']).toEqual({ needle: 'READY_1', since: 42 })
|
||
// The next push without waiting drops the entry (the push is authoritative).
|
||
s = reconcileAgentTerminals(s, [{ uuid: 'aaa-111', title: 'stable' }])
|
||
expect(s.agentWaits['aaa-111']).toBeUndefined()
|
||
})
|
||
|
||
it('produces a new state when ONLY the wait state changes (no tab add/remove)', () => {
|
||
let s = makeDefaultState()
|
||
s = reconcileAgentTerminals(s, [{ uuid: 'aaa-111', title: 'stable' }])
|
||
const before = s
|
||
const next = reconcileAgentTerminals(s, [{ uuid: 'aaa-111', title: 'stable', waiting: { needle: 'N', since: 1 } }])
|
||
expect(next).not.toBe(before)
|
||
expect(next.agentWaits['aaa-111']).toBeDefined()
|
||
// Idempotent: the same push again returns the same reference.
|
||
expect(reconcileAgentTerminals(next, [{ uuid: 'aaa-111', title: 'stable', waiting: { needle: 'N', since: 1 } }])).toBe(next)
|
||
})
|
||
```
|
||
|
||
- [ ] **Step 2: 跑测试确认失败**
|
||
|
||
Run: `pnpm exec vitest run tests/agent-terminal-reconcile.spec.ts`
|
||
Expected: FAIL（`agentWaits` 不存在 → TS 错误 / 断言失败）。
|
||
|
||
- [ ] **Step 3: 实现**
|
||
|
||
(a) `SidebarState` 接口 `floats: FloatWindow[]` 之后追加：
|
||
|
||
```ts
|
||
/**
|
||
* Live agent-terminal wait state (uuid → the wait the model currently
|
||
* blocks on in `terminal_wait_for`), mirrored from the host's
|
||
* agent-terminals push. Transient by design: sanitizeState never restores
|
||
* it, so a reload starts clean and the next push (sent immediately on WS
|
||
* attach) repopulates it.
|
||
*/
|
||
agentWaits: Record<string, { needle: string; since: number }>
|
||
```
|
||
|
||
(b) `makeDefaultState` 的返回字面量 `floats: [],` 之后加 `agentWaits: {},`。
|
||
|
||
(c) `sanitizeState` 的返回字面量 `floats,` 之后加（带注释）：
|
||
|
||
```ts
|
||
// The agent wait state is TRANSIENT (like revealed): never restored from
|
||
// storage — the host's first push after attach repopulates it.
|
||
agentWaits: {},
|
||
```
|
||
|
||
(d) `reconcileAgentTerminals`：参数类型改为
|
||
|
||
```ts
|
||
agentTerminals: ReadonlyArray<{ uuid: string; title: string; waiting?: { needle: string; since: number } | null }>,
|
||
```
|
||
|
||
在 `const toRemove = ...` 之后、`if (toAdd.length === 0 && toRemove.length === 0) return state` 处，替换为：
|
||
|
||
```ts
|
||
// Mirror the live wait state from the push (authoritative: a vanished
|
||
// waiting field simply drops the entry). A waits-only change must still
|
||
// produce a new state — the tab add/remove no-change check alone would
|
||
// swallow banner updates.
|
||
const serverWaits: Record<string, { needle: string; since: number }> = {}
|
||
for (const terminal of agentTerminals) {
|
||
if (terminal.waiting !== undefined && terminal.waiting !== null) {
|
||
serverWaits[terminal.uuid] = { needle: terminal.waiting.needle, since: terminal.waiting.since }
|
||
}
|
||
}
|
||
if (toAdd.length === 0 && toRemove.length === 0 && sameAgentWaits(state.agentWaits, serverWaits)) return state
|
||
```
|
||
|
||
文件末尾的 `return next` 改为 `return { ...next, agentWaits: serverWaits }`。
|
||
|
||
在 `reconcileAgentTerminals` 前方新增辅助函数：
|
||
|
||
```ts
|
||
/** Shallow equality of two agent-wait maps (same keys, same needle+since). */
|
||
function sameAgentWaits(
|
||
a: SidebarState['agentWaits'] | undefined,
|
||
b: Record<string, { needle: string; since: number }>,
|
||
): boolean {
|
||
if (a === undefined) return Object.keys(b).length === 0
|
||
const aKeys = Object.keys(a)
|
||
if (aKeys.length !== Object.keys(b).length) return false
|
||
for (const key of aKeys) {
|
||
const av = a[key]
|
||
const bv = b[key]
|
||
if (av === undefined || bv === undefined) return false
|
||
if (av.needle !== bv.needle || av.since !== bv.since) return false
|
||
}
|
||
return true
|
||
}
|
||
```
|
||
|
||
(e) `src/client/sidebar/use-host-feeds.ts` 66 行的解析类型改为：
|
||
|
||
```ts
|
||
const list = JSON.parse(event.data) as Array<{ uuid: string; title: string; command: string; exited: boolean; waiting?: { needle: string; since: number } | null }>
|
||
```
|
||
|
||
- [ ] **Step 4: 跑测试确认通过 + 全仓 typecheck（状态字段新增会暴露遗漏的构造点）**
|
||
|
||
Run: `pnpm exec vitest run tests/agent-terminal-reconcile.spec.ts && pnpm typecheck`
|
||
Expected: PASS。若 typecheck 报其他 `SidebarState` 字面量缺 `agentWaits`（tests 里的手搓状态），补 `agentWaits: {}` —— **只许改测试里测试自己构造的字面量，不许改上游断言逻辑**。
|
||
|
||
- [ ] **Step 5: Commit**
|
||
|
||
```bash
|
||
git add src/client/state.ts src/client/sidebar/use-host-feeds.ts tests/agent-terminal-reconcile.spec.ts
|
||
git commit -m "feat(sidebar): 镜像 agent 终端等待状态到 agentWaits（瞬态）"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 4: 等待 banner 组件 + TerminalView 接线 + api 方法 + i18n + CSS
|
||
|
||
**Files:**
|
||
- Create: `src/client/TerminalWaitBanner.tsx`
|
||
- Modify: `src/client/TerminalView.tsx`（render 区 ~387-408 行 + 组件顶部订阅）
|
||
- Modify: `src/client/api.ts`（`agentPtyClose` 之后 ~348 行）
|
||
- Modify: `src/client/locales.ts`（zh ~117 / en ~567，紧随 `terminalRetry`）
|
||
- Modify: `src/client/locales-ja.ts`（~105，紧随 `terminalRetry`）
|
||
- Modify: `src/client/sidebar.module.css`（`.terminalBanner` 块之后 ~2202 行）
|
||
- Test: `tests/terminal-wait-banner.spec.tsx`（新建）
|
||
|
||
**Interfaces:**
|
||
- Consumes: Task 2 的 `agent-pty.skip-wait` 路由；Task 3 的 `state.agentWaits`；`api` 对象、`t()`、`css` module。
|
||
- Produces: `TerminalWaitBanner({ needle: string; onSkip: () => void })` + `truncateNeedle(needle: string): string`（80 字符截断）；词典键 `terminalWaitBanner` / `terminalSkipWait`。
|
||
|
||
- [ ] **Step 1: 写失败测试（新文件 `tests/terminal-wait-banner.spec.tsx`）**
|
||
|
||
```tsx
|
||
/**
|
||
* TerminalWaitBanner unit tests: localized text with the needle, the skip
|
||
* button wiring, and the long-needle display cap (full text stays on the
|
||
* title attribute). The component imports no xterm — renderable in plain
|
||
* jsdom (the repo's jsdom pattern, see bottom-auto-terminal.spec.tsx head).
|
||
*/
|
||
// @vitest-environment jsdom
|
||
import { afterEach, describe, expect, it } from 'vitest'
|
||
import { createElement } from 'react'
|
||
import { createRoot, type Root } from 'react-dom/client'
|
||
import { act } from 'react-dom/test-utils'
|
||
import { setupReactAct } from './test-utils.ts'
|
||
setupReactAct()
|
||
|
||
import { TerminalWaitBanner } from '../src/client/TerminalWaitBanner.tsx'
|
||
|
||
describe('TerminalWaitBanner', () => {
|
||
const mounted: Array<{ root: Root; container: HTMLDivElement }> = []
|
||
function mount(needle: string, onSkip: () => void): HTMLDivElement {
|
||
const container = document.createElement('div')
|
||
document.body.append(container)
|
||
const root = createRoot(container)
|
||
act(() => { root.render(createElement(TerminalWaitBanner, { needle, onSkip })) })
|
||
mounted.push({ root, container })
|
||
return container
|
||
}
|
||
afterEach(() => {
|
||
for (const { root, container } of mounted.splice(0)) {
|
||
act(() => { root.unmount() })
|
||
container.remove()
|
||
}
|
||
})
|
||
|
||
it('shows the localized waiting text with the needle and a working skip button', () => {
|
||
let skipped = 0
|
||
const container = mount('BUILD_OK', () => { skipped += 1 })
|
||
// jsdom navigator.language is en-US → the en dictionary applies.
|
||
expect(container.textContent).toContain('Agent is waiting for')
|
||
expect(container.textContent).toContain('BUILD_OK')
|
||
expect(container.textContent).toContain('Skip wait')
|
||
const button = container.querySelector('button')
|
||
expect(button).not.toBeNull()
|
||
act(() => { button!.dispatchEvent(new MouseEvent('click', { bubbles: true })) })
|
||
expect(skipped).toBe(1)
|
||
})
|
||
|
||
it('truncates a long needle for display but keeps the full text on the title', () => {
|
||
const long = 'X'.repeat(200)
|
||
const container = mount(long, () => {})
|
||
const span = container.querySelector('span[title]')
|
||
expect(span).not.toBeNull()
|
||
expect(span!.getAttribute('title')).toBe(long)
|
||
expect((span!.textContent ?? '').length).toBeLessThanOrEqual(80)
|
||
})
|
||
})
|
||
```
|
||
|
||
- [ ] **Step 2: 跑测试确认失败**
|
||
|
||
Run: `pnpm exec vitest run tests/terminal-wait-banner.spec.tsx`
|
||
Expected: FAIL（模块不存在）。
|
||
|
||
- [ ] **Step 3: 实现**
|
||
|
||
(a) 新建 `src/client/TerminalWaitBanner.tsx`：
|
||
|
||
```tsx
|
||
/**
|
||
* The "Agent 正在等待 {needle}" wait banner: rendered at the top of an
|
||
* agent-owned terminal's view while the model blocks in terminal_wait_for.
|
||
* The skip button asks the host to abort every active wait on the terminal
|
||
* (`agent-pty.skip-wait`); the banner disappears when the host's next
|
||
* agent-terminals push drops the waiting field — no optimistic UI. Kept in
|
||
* its own module (no xterm imports) so jsdom tests can render it directly.
|
||
*/
|
||
import { t } from './locales.ts'
|
||
import css from './sidebar.module.css'
|
||
|
||
/** Cap the needle shown inline; the full text rides the title tooltip. */
|
||
const NEEDLE_DISPLAY_CAP = 80
|
||
|
||
/** Truncate one needle for inline display (title attr carries the full text). */
|
||
export function truncateNeedle(needle: string): string {
|
||
return needle.length > NEEDLE_DISPLAY_CAP ? `${needle.slice(0, NEEDLE_DISPLAY_CAP - 1)}…` : needle
|
||
}
|
||
|
||
export function TerminalWaitBanner(props: { needle: string; onSkip: () => void }) {
|
||
const { needle, onSkip } = props
|
||
return (
|
||
<div className={css.terminalWaitBanner}>
|
||
<span className={css.terminalWaitNeedle} title={needle}>
|
||
{t('terminalWaitBanner', { needle: truncateNeedle(needle) })}
|
||
</span>
|
||
<button type="button" className={css.terminalRetry} onClick={onSkip}>
|
||
{t('terminalSkipWait')}
|
||
</button>
|
||
</div>
|
||
)
|
||
}
|
||
```
|
||
|
||
(b) `src/client/api.ts`：`agentPtyClose` 条目之后追加：
|
||
|
||
```ts
|
||
/** Skip every active terminal_wait_for on one agent terminal (the wait
|
||
* banner's skip button). Idempotent: {skipped:0} when none is active. */
|
||
agentSkipWait: (uuid: string) =>
|
||
call<{ ok: true; skipped: number }>('agent-pty.skip-wait', { uuid }),
|
||
```
|
||
|
||
(c) `src/client/locales.ts`：zh 词典 `terminalRetry: '重试',` 行后加：
|
||
|
||
```ts
|
||
terminalWaitBanner: 'Agent 正在等待 {needle}',
|
||
terminalSkipWait: '跳过等待',
|
||
```
|
||
|
||
en 词典 `terminalRetry: 'Retry',` 行后加：
|
||
|
||
```ts
|
||
terminalWaitBanner: 'Agent is waiting for {needle}',
|
||
terminalSkipWait: 'Skip wait',
|
||
```
|
||
|
||
(d) `src/client/locales-ja.ts`：`terminalRetry: '再試行',` 行后加（仓库规则：新 zh 键必须同步 ja）：
|
||
|
||
```ts
|
||
terminalWaitBanner: 'エージェントが {needle} を待機中',
|
||
terminalSkipWait: '待機をスキップ',
|
||
```
|
||
|
||
(e) `src/client/sidebar.module.css`：`.terminalBannerUrl` 块之后加：
|
||
|
||
```css
|
||
/* The "Agent 正在等待 {needle}" wait banner: a warn-toned strip above the
|
||
terminal surface while the model blocks in terminal_wait_for; the needle
|
||
ellipsizes inline and the full text rides the title tooltip. */
|
||
.terminalWaitBanner {
|
||
flex: none;
|
||
display: flex;
|
||
align-items: center;
|
||
gap: 8px;
|
||
padding: 3px 10px;
|
||
font: var(--dsw-font-xxxs-11);
|
||
color: var(--dsw-alias-state-warn-label);
|
||
background: var(--dsw-alias-state-warn-tertiary);
|
||
}
|
||
|
||
.terminalWaitNeedle {
|
||
flex: 1;
|
||
min-width: 0;
|
||
overflow: hidden;
|
||
text-overflow: ellipsis;
|
||
white-space: nowrap;
|
||
font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
|
||
}
|
||
```
|
||
|
||
(f) `src/client/TerminalView.tsx`：
|
||
|
||
imports 区追加：
|
||
|
||
```ts
|
||
import { TerminalWaitBanner } from './TerminalWaitBanner.tsx'
|
||
```
|
||
|
||
组件体内（`const [lastUrl, setLastUrl] = ...` 之后）加等待订阅：
|
||
|
||
```ts
|
||
// Agent terminals only: the model's active terminal_wait_for (mirrored
|
||
// from the host's agent-terminals push into the store) drives the wait
|
||
// banner. Read + subscribe like the font prefs above; the banner vanishes
|
||
// when the host's push drops the waiting field (skip / exit / abort all
|
||
// converge through the same push). getSnapshot() is {sessionId, state?,
|
||
// prefs} — the state may be briefly undefined around session switches.
|
||
const agentUuid = isAgentTabId(tabId) ? agentUuidOf(tabId) : null
|
||
const [waiting, setWaiting] = useState<{ needle: string; since: number } | undefined>(undefined)
|
||
useEffect(() => {
|
||
if (agentUuid === null) return
|
||
const read = (): void => {
|
||
const next = store.getSnapshot().state?.agentWaits?.[agentUuid]
|
||
setWaiting(prev => {
|
||
const nextValue = next === undefined ? undefined : { needle: next.needle, since: next.since }
|
||
if (prev?.needle === nextValue?.needle && prev?.since === nextValue?.since) return prev
|
||
return nextValue
|
||
})
|
||
}
|
||
read()
|
||
return store.subscribe(read)
|
||
}, [agentUuid, store])
|
||
```
|
||
|
||
return JSX 中 `<div className={css.terminalWrap}>` 的第一个子元素位置（`depsFatal` 条目之前）加：
|
||
|
||
```tsx
|
||
{agentUuid !== null && waiting !== undefined && (
|
||
<TerminalWaitBanner
|
||
needle={waiting.needle}
|
||
onSkip={() => { void api.agentSkipWait(agentUuid).catch(() => { /* 跳过失败时 banner 留存，可重试 */ }) }}
|
||
/>
|
||
)}
|
||
```
|
||
|
||
- [ ] **Step 4: 跑测试确认通过**
|
||
|
||
Run: `pnpm exec vitest run tests/terminal-wait-banner.spec.tsx`
|
||
Expected: PASS。
|
||
|
||
- [ ] **Step 5: Commit**
|
||
|
||
```bash
|
||
git add src/client/TerminalWaitBanner.tsx src/client/TerminalView.tsx src/client/api.ts src/client/locales.ts src/client/locales-ja.ts src/client/sidebar.module.css tests/terminal-wait-banner.spec.tsx
|
||
git commit -m "feat(sidebar): agent 终端等待 banner（needle + 跳过等待按钮）"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 5: tab 标题 ⏳ 徽章（shell 层特例）+ jsdom 链路测试
|
||
|
||
**Files:**
|
||
- Modify: `src/client/Sidebar.tsx`（`tabBadgeOf` ~828-841 行）
|
||
- Test: `tests/agent-wait-badge.spec.tsx`（新文件，harness 照抄 `tests/bottom-auto-terminal.spec.tsx` 1-97 行的模式）
|
||
|
||
**Interfaces:**
|
||
- Consumes: Task 3 的 `state.agentWaits`；`isAgentTabId` / `agentUuidOf`（Sidebar.tsx 已 import，第 38-39 行）。
|
||
- Produces: agent tab 的 ⏳ 徽章 pill（复用 `css.tabBadge`）；推送 → 状态 → 徽章全链路。
|
||
|
||
- [ ] **Step 1: 写失败测试（新文件 `tests/agent-wait-badge.spec.tsx`）**
|
||
|
||
完整文件（FakeWebSocket 记录 url 与实例，驱动 `/sidebar/ws/agent-terminals` 推送；`registerStubTerminal` 防止懒加载 chunk 在 jsdom 里拉真实 bundle）：
|
||
|
||
```tsx
|
||
/**
|
||
* The agent-terminal wait badge chain, end to end in jsdom: the host's
|
||
* agent-terminals push (mirroring the real /sidebar/ws/agent-terminals
|
||
* frames) reconciles tabs AND the wait map; the shell's tabBadgeOf renders
|
||
* the hourglass pill on the agent tab while a wait is live and drops it
|
||
* when the push clears. Harness mirrors tests/bottom-auto-terminal.spec.tsx
|
||
* (real Sidebar shell + fake context + stubbed WebSocket).
|
||
*/
|
||
// @vitest-environment jsdom
|
||
import { afterEach, describe, expect, it, vi } from 'vitest'
|
||
import { createElement } from 'react'
|
||
import { createRoot, type Root } from 'react-dom/client'
|
||
import { act } from 'react-dom/test-utils'
|
||
import { setupReactAct } from './test-utils.ts'
|
||
setupReactAct()
|
||
|
||
import { Sidebar } from '../src/client/Sidebar.tsx'
|
||
import { createSidebarStore, openTabInActivePane } from '../src/client/state.ts'
|
||
import { createBetterSidebarService, type BetterSidebarService } from '../src/client/service.ts'
|
||
|
||
/** jsdom has no WebSocket; the agent-terminals push effect constructs one on mount. */
|
||
class FakeWebSocket {
|
||
static instances: FakeWebSocket[] = []
|
||
onmessage: ((event: { data: unknown }) => void) | null = null
|
||
onclose: (() => void) | null = null
|
||
onerror: (() => void) | null = null
|
||
close = (): void => {}
|
||
constructor(readonly url: string) {
|
||
FakeWebSocket.instances.push(this)
|
||
}
|
||
}
|
||
|
||
let sessionSeq = 0
|
||
|
||
function mountSidebar(): { container: HTMLDivElement; store: ReturnType<typeof createSidebarStore>; service: BetterSidebarService; unmount: () => void } {
|
||
vi.stubGlobal('WebSocket', FakeWebSocket)
|
||
FakeWebSocket.instances = []
|
||
const container = document.createElement('div')
|
||
document.body.append(container)
|
||
const store = createSidebarStore()
|
||
const service = createBetterSidebarService(store)
|
||
// Replace the terminal descriptor with a stub: the real one lazy-loads the
|
||
// xterm chunk, which jsdom cannot fetch — the badge under test renders in
|
||
// the TAB STRIP, independent of the view component.
|
||
service.registerTab({
|
||
id: 'terminal',
|
||
title: () => 'Terminal',
|
||
component: () => null,
|
||
})
|
||
const sessionId = `s1-${++sessionSeq}`
|
||
store.setSession(sessionId)
|
||
// Stub the terminal descriptor: the real one lazy-loads the xterm chunk,
|
||
// which jsdom cannot fetch (the bottom-auto-terminal harness does the same).
|
||
service.registerTab({
|
||
id: 'terminal',
|
||
title: () => 'Terminal',
|
||
component: () => null,
|
||
})
|
||
const localeSnapshot = { active: 'en' }
|
||
const sessionsSnapshot = {
|
||
current: sessionId,
|
||
byId: { [sessionId]: { cwd: '/tmp' } },
|
||
}
|
||
const ctx = {
|
||
locale: { subscribe: () => () => {}, getSnapshot: () => localeSnapshot },
|
||
sessions: { list: { subscribe: () => () => {}, getSnapshot: () => sessionsSnapshot } },
|
||
betterSidebar: service,
|
||
get: (name: string) => name === 'betterSidebar' ? service : undefined,
|
||
}
|
||
const root: Root = createRoot(container)
|
||
act(() => { root.render(createElement(Sidebar, { ctx: ctx as never, store })) })
|
||
return {
|
||
container,
|
||
store,
|
||
service,
|
||
unmount: () => {
|
||
act(() => { root.unmount() })
|
||
container.remove()
|
||
},
|
||
}
|
||
}
|
||
|
||
let sessionSeq = 0
|
||
|
||
afterEach(() => {
|
||
document.body.innerHTML = ''
|
||
localStorage.clear()
|
||
vi.unstubAllGlobals()
|
||
})
|
||
|
||
/** The agent-terminals push socket the shell opened for the current session. */
|
||
function feedsSocket(): FakeWebSocket {
|
||
const socket = FakeWebSocket.instances.find(candidate => candidate.url.includes('/sidebar/ws/agent-terminals'))
|
||
if (socket === undefined) throw new Error('agent-terminals socket not connected')
|
||
return socket
|
||
}
|
||
|
||
describe('agent terminal wait badge (push → state → tab pill)', () => {
|
||
it('shows ⏳ on the agent tab while a wait is active and drops it when it ends', () => {
|
||
const { container } = mountSidebar()
|
||
const terminal = { uuid: 'u1', title: 'dev server', command: '', exited: false }
|
||
// First push: the agent tab lands in the active pane.
|
||
act(() => { feedsSocket().onmessage?.({ data: JSON.stringify([terminal]) }) })
|
||
expect(container.textContent).toContain('dev server')
|
||
expect(container.textContent).not.toContain('⏳')
|
||
// Second push carries a live wait → the hourglass pill appears.
|
||
act(() => { feedsSocket().onmessage?.({ data: JSON.stringify([{ ...terminal, waiting: { needle: 'READY_1', since: 1 } }]) }) })
|
||
expect(container.textContent).toContain('⏳')
|
||
// The wait resolved (skip/exit/abort all converge to a waiting-less push).
|
||
act(() => { feedsSocket().onmessage?.({ data: JSON.stringify([terminal]) }) })
|
||
expect(container.textContent).not.toContain('⏳')
|
||
})
|
||
|
||
it('shows ⏳ only on agent tabs, never on UI-owned terminal tabs', () => {
|
||
const { container, store } = mountSidebar()
|
||
// A UI-owned terminal tab (id NOT agent:) lives in the strip too; the
|
||
// badge lookup keys on the agent uuid, so it never badges.
|
||
act(() => { store.reduce(s => openTabInActivePane(s, { id: 'terminal:manual-1', type: 'terminal', title: 'UI terminal' })) })
|
||
const terminal = { uuid: 'u1', title: 'dev server', command: '', exited: false }
|
||
act(() => { feedsSocket().onmessage?.({ data: JSON.stringify([{ ...terminal, waiting: { needle: 'READY_1', since: 1 } }]) }) })
|
||
// Exactly ONE hourglass: the agent tab. (Counted from textContent — CSS
|
||
// module class names are not stable under the test transform.)
|
||
expect((container.textContent.match(/⏳/g) ?? []).length).toBe(1)
|
||
// The wait resolved → the pill disappears entirely.
|
||
act(() => { feedsSocket().onmessage?.({ data: JSON.stringify([terminal]) }) })
|
||
expect(container.textContent).not.toContain('⏳')
|
||
})
|
||
})
|
||
```
|
||
|
||
> 实现注意：`sessionSeq` 声明放 `mountSidebar` 之前（与 bottom-auto-terminal.spec.tsx 相同的模块级写法）；`createSidebarStore` 返回类型直接用 `ReturnType<typeof createSidebarStore>`，勿手写接口。
|
||
|
||
- [ ] **Step 2: 跑测试确认失败**
|
||
|
||
Run: `pnpm exec vitest run tests/agent-wait-badge.spec.tsx`
|
||
Expected: FAIL（⏳ 从不出现）。
|
||
|
||
- [ ] **Step 3: 实现 Sidebar.tsx 的 `tabBadgeOf` 特例**
|
||
|
||
`src/client/Sidebar.tsx` 828 行 `const tabBadgeOf = (tab: SidebarTab): ReactNode => {` 函数体开头（descriptor 查找之前）插入：
|
||
|
||
```ts
|
||
// Agent-terminal wait indicator (sidebar-internal, deliberately NOT a
|
||
// TabDescriptor.badge — that API is type-keyed and shared with external
|
||
// plugins, and cannot address one tab): the agent-terminals push mirrors
|
||
// the model's live terminal_wait_for into state.agentWaits; an agent tab
|
||
// whose uuid is waiting shows the hourglass pill.
|
||
if (isAgentTabId(tab.id)) {
|
||
const wait = state.agentWaits?.[agentUuidOf(tab.id)]
|
||
if (wait !== undefined) return <span className={css.tabBadge}>{'⏳'}</span>
|
||
}
|
||
```
|
||
|
||
（`isAgentTabId` / `agentUuidOf` 已在 38-39 行 import；`css` / `state` 均在作用域内。）
|
||
|
||
- [ ] **Step 4: 跑测试确认通过**
|
||
|
||
Run: `pnpm exec vitest run tests/agent-wait-badge.spec.tsx`
|
||
Expected: PASS（2 个用例）。
|
||
|
||
- [ ] **Step 5: Commit**
|
||
|
||
```bash
|
||
git add src/client/Sidebar.tsx tests/agent-wait-badge.spec.tsx
|
||
git commit -m "feat(sidebar): agent 终端 tab 标题在等待时显示 ⏳ 徽章"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 6: 设计文档偏差记录 + 全量验证 + 推送 + PR
|
||
|
||
**Files:**
|
||
- Modify: `docs/plans/2026-09-09-terminal-wait-banner-design.md`（实施偏差记录节）
|
||
- 无代码改动。
|
||
|
||
- [ ] **Step 1: 更新设计文档**
|
||
|
||
在 `docs/plans/2026-09-09-terminal-wait-banner-design.md` 末尾追加：
|
||
|
||
```markdown
|
||
|
||
## 实施偏差记录
|
||
|
||
- **⏳ tab 徽章不走 `TabDescriptor.badge`**：实现时核实该 API 是 type-keyed
|
||
（`badge(ctx, scope, state)`，无 tab 参数，external 插件共享），无法定位单个
|
||
tab。改为 Sidebar 壳层 `tabBadgeOf` 的 sidebar-internal 特例（agent: tab 前缀
|
||
判断 + `state.agentWaits` 查表），`service.ts` 与 external-plugin-guide.md
|
||
零改动。
|
||
- **banner 抽为独立组件 `TerminalWaitBanner.tsx`**：设计原文写在
|
||
TerminalView.tsx 内；抽出后无 xterm 依赖，可直接被 jsdom 单测渲染
|
||
（TerminalView 仍负责订阅 store 并接线 onSkip → api.agentSkipWait）。
|
||
- **设计文档随 feat 分支进 PR**：main 受分支保护，纯文档直推被 hook 拒绝
|
||
（`4a6a77a` 随本分支合并）。
|
||
- **banner 配色**：仓库 CSS 无 state-info 令牌，沿用 `.terminalBanner` 的
|
||
warn 对（`--dsw-alias-state-warn-label/-tertiary`），符合皮肤契约。
|
||
```
|
||
|
||
- [ ] **Step 2: 全量验证**
|
||
|
||
Run（依次，全绿才继续）：
|
||
`pnpm lint` → `pnpm typecheck` → `pnpm test` → `pnpm build`
|
||
|
||
Expected:
|
||
- lint: 0 error（历史上 CI 因 no-useless-assignment 挂过——新代码避免「先声明后必然覆盖」的写法）；
|
||
- test: 除已知的 win32 非回归失败集（bottom-auto-terminal / free-window / sidebar-auto-activation / sidebar-crash 等既有失败，对照 main 基线）外全绿，新增 spec 全部 PASS；
|
||
- build: lib/ 产物含新 chunk `client.js` 变化（TerminalWaitBanner 打进 client bundle）。
|
||
|
||
- [ ] **Step 3: 提交并推送**
|
||
|
||
```bash
|
||
git add docs/plans/2026-09-09-terminal-wait-banner-design.md
|
||
git commit -m "docs(plans): 终端等待 banner 实施偏差记录"
|
||
git push -u origin feat/wait-banner
|
||
```
|
||
|
||
- [ ] **Step 4: 建 PR**
|
||
|
||
```bash
|
||
gh pr create --repo omdsh-dev/DSH-better-sidebar --base main --head feat/wait-banner \
|
||
--title "feat(terminal): 等待 banner + 跳过等待（terminal_wait_for skipped）" \
|
||
--body "设计：docs/plans/2026-09-09-terminal-wait-banner-design.md（随本 PR）。agent 阻塞在 terminal_wait_for 时：对应终端卡片顶部显示「Agent 正在等待 {needle}」banner，右侧跳过按钮走 agent-pty.skip-wait；tab 标题 ⏳ 徽章；工具新增 {kind:'skipped'} 返回。"
|
||
```
|
||
|
||
- [ ] **Step 5: 等待 CI（用 terminal_wait_for 盯 `(ci|ci-windows|plugin-mount).*\((pass|fail)\)` 之类的多结局 needle，勿 sleep）**
|
||
|
||
Expected: 三个 job 全 pass。
|