wonder/cs-note
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

vault backup: 2026-06-09 23:15:17

Browse Source
This commit is contained in:
wonder
2026-06-09 23:15:17 +08:00
parent 31fd89aafe
commit e92c0327d9
111 changed files with 7276 additions and 8846 deletions
Download Patch File Download Diff File Expand all files Collapse all files
claude-code-best/docs/features/background-agent-selector.md
+44 -33
View File
@@ -1,14 +1,20 @@
---
tags: [background-agent, selector, UI, 后台任务, fork]
create time: 2026-06-09 22:30
---
# Background Agent Selector — 底部统一后台 Agent 切换器
## 概述
Background Agent Selector 是渲染在 PromptInput 下方的常驻状态条，列出当前所有 backgrounded 的 local_agent 任务。用户可以用方向键在 main 和各 agent 之间切换焦点，按 Enter 把 REPL 主视图替换为所选 agent 的实时 transcript。
> [!info]
> Feature Flag: 无（直接启用）
> 实现状态：完整可用
> 依赖：`viewingAgentTaskId` / `enterTeammateView` / `exitTeammateView` 已有机制
## 一、功能概述
Background Agent Selector 是渲染在 PromptInput 下方的常驻状态条，列出当前所有 **backgrounded 的 local_agent 任务**（包括 `/fork` 派生的 fork agent 和 Task/AgentTool 调用 `run_in_background: true` 派生的子 agent）。用户可以用 ↑/↓ 方向键在 `main` 和各 agent 之间切换焦点，按 Enter 把 REPL 主视图替换为所选 agent 的实时 transcript，再按 Enter 选中 `main` 即可回到主对话。
整个机制完全复用官方已有的 teammate transcript 查看基础设施，不引入新的视图层 / 数据流，仅新增一条 footer pill 类型。
## 正文
### 核心特性
@@ -19,9 +25,9 @@ Background Agent Selector 是渲染在 PromptInput 下方的常驻状态条，
- **零界面侵入**：tasks 数为 0 时 selector 完全不渲染，不占屏幕高度
- **与旧 Dialog 共存**：Shift+↓ 打开的 `BackgroundTasksDialog` 原有行为保留，selector 只作为展示 + 快捷切换
## 二、用户交互
### 用户交互
### 触发方式
#### 触发方式
有任何 background agent 时，selector 自动出现在 `bypass permissions on` 行下方：
@@ -35,18 +41,18 @@ Background Agent Selector 是渲染在 PromptInput 下方的常驻状态条，
○ Explore Research src/utils 21s · ↓ 13.6k tokens
```
### 键盘路由
#### 键盘路由
| 位置 / 状态 | 按键 | 行为 |
|---|---|---|
| PromptInput 非空 | ↑↓ | 光标移动 / 翻历史（不变） |
| PromptInput 空 + 历史底部 | ↓ | 焦点下放到 selector，高亮到 `● main` |
| Selector 聚焦（`footerSelection === 'bg_agent'`） | ↓ | 高亮下移，-1 → 0 → ... → N-1 |
| Selector 聚焦 | ↑ | 高亮上移；在 `main` 再 ↑ → 焦点回 PromptInput |
| Selector 聚焦 | Enter | `-1` → `exitTeammateView`；`>=0` → `enterTeammateView(agentId)`。焦点保留在 pill |
| Selector 聚焦（`footerSelection === 'bg_agent'`） | ↓ | 高亮下移，-1 -> 0 -> ... -> N-1 |
| Selector 聚焦 | ↑ | 高亮上移；在 `main` 再 ↑ -> 焦点回 PromptInput |
| Selector 聚焦 | Enter | `-1` -> `exitTeammateView`；`>=0` -> `enterTeammateView(agentId)`。焦点保留在 pill |
| Selector 聚焦 | Esc | `footer:clearSelection`，焦点回 PromptInput |
### 视觉规则
#### 视觉规则
- `● main` / `● <agent>`：当前被**查看**（viewingAgentTaskId 指向）或被**光标聚焦**（pill focused 时以光标为准）的一行
- running 状态的 agent：圆点渲染为 `success` 色（绿色），与 `BackgroundTasksDialog` 状态语义对齐
@@ -56,15 +62,15 @@ Background Agent Selector 是渲染在 PromptInput 下方的常驻状态条，
- 已选中 terminal agent：`shift+↓ to manage · x to clear`
- 未选中任何 agent：`shift+↓ to manage background agents`
## 三、实现架构
### 实现架构
### 3.1 数据层：`useBackgroundAgentTasks`
#### 数据层：`useBackgroundAgentTasks`
文件：`src/hooks/useBackgroundAgentTasks.ts`
封装对 `useAppState(s => s.tasks)` 的过滤：
```ts
```typescript
export function useBackgroundAgentTasks(): LocalAgentTaskState[] {
const tasks = useAppState(s => s.tasks)
return useMemo(() => {
@@ -79,16 +85,16 @@ export function useBackgroundAgentTasks(): LocalAgentTaskState[] {
}
```
`/fork` 和 `AgentTool` 的 `run_in_background: true` 底层都走 `registerAsyncAgent → runAsyncAgentLifecycle`，最终写入同一个 `appState.tasks` Map；此 hook 是唯一数据源，Selector 和 PromptInput 的 `bgAgentList` 都消费它。
`/fork` 和 `AgentTool` 的 `run_in_background: true` 底层都走 `registerAsyncAgent -> runAsyncAgentLifecycle`，最终写入同一个 `appState.tasks` Map；此 hook 是唯一数据源，Selector 和 PromptInput 的 `bgAgentList` 都消费它。
### 3.2 状态层：新增两个字段
#### 状态层：新增两个字段
文件：`src/state/AppStateStore.ts`
```ts
```typescript
export type FooterItem =
| 'tasks' | 'tmux' | 'bagel' | 'teams' | 'bridge' | 'companion'
| 'bg_agent' // ← 新增
| 'bg_agent' // 新增
export type AppState = DeepImmutable<{
// ...
@@ -99,23 +105,23 @@ export type AppState = DeepImmutable<{
- `'bg_agent'` 作为 `FooterItem` 加入 footer pill 体系，享受既有的 `footer:up` / `footer:down` / `footer:openSelected` keybinding 路由
- `selectedBgAgentIndex` 记录 selector 的光标位置，与 `viewingAgentTaskId`（"正在看什么"）独立；它不可从 `viewingAgentTaskId` 派生——Enter 后光标留在 pill 继续导航，查看目标才变
### 3.3 键盘路由：PromptInput footer pill 分支
#### 键盘路由：PromptInput footer pill 分支
文件：`src/components/PromptInput/PromptInput.tsx`
1. **`bg_agent` 进入 footerItems[0]**：保证 prompt ↓ 溢出时（`handleHistoryDown` → `selectFooterItem(footerItems[0])`）直接进入 selector，而不是 `tasks` 等其他 pill
2. **`footer:up` 分支**：`bgAgentSelected` 时 `selectedBgAgentIndex > -1` 则递减；在 -1 → `selectFooterItem(null)` 退出 pill
1. **`bg_agent` 进入 footerItems[0]**：保证 prompt ↓ 溢出时（`handleHistoryDown` -> `selectFooterItem(footerItems[0])`）直接进入 selector，而不是 `tasks` 等其他 pill
2. **`footer:up` 分支**：`bgAgentSelected` 时 `selectedBgAgentIndex > -1` 则递减；在 -1 -> `selectFooterItem(null)` 退出 pill
3. **`footer:down` 分支**：`selectedBgAgentIndex < bgAgentList.length - 1` 则递增，到底 clamp
4. **`footer:openSelected` 分支**：index === -1 → `exitTeammateView`；否则 `enterTeammateView(bgAgentList[i].agentId)`。**不清理 pill 焦点**，光标留在 selector 上继续导航
4. **`footer:openSelected` 分支**：index === -1 -> `exitTeammateView`；否则 `enterTeammateView(bgAgentList[i].agentId)`。**不清理 pill 焦点**，光标留在 selector 上继续导航
5. **`selectFooterItem('bg_agent')`**：入 pill 时重置 `selectedBgAgentIndex = -1`（光标落到 `main`）
### 3.4 渲染层：`BackgroundAgentSelector`
#### 渲染层：`BackgroundAgentSelector`
文件：`src/components/tasks/BackgroundAgentSelector.tsx`
纯展示组件，不订阅键盘：
```tsx
```typescript
const tasks = useBackgroundAgentTasks()
const viewingId = useAppState(s => s.viewingAgentTaskId)
const footerSelection = useAppState(s => s.footerSelection)
@@ -129,13 +135,13 @@ const highlightedId = pillFocused
: (viewingId ?? null)
```
**高亮派生规则**：pill 聚焦 → 跟 `selectedBgAgentIndex`；未聚焦 → 镜像 `viewingAgentTaskId`。这样当用户通过 Shift+↓ Dialog 或 `enterTeammateView` 其它途径切换视图时，selector 也会正确反映。
**高亮派生规则**：pill 聚焦 -> 跟 `selectedBgAgentIndex`；未聚焦 -> 镜像 `viewingAgentTaskId`。这样当用户通过 Shift+↓ Dialog 或 `enterTeammateView` 其它途径切换视图时，selector 也会正确反映。
### 3.5 主视图切换：复用 `viewingAgentTaskId`
#### 主视图切换：复用 `viewingAgentTaskId`
REPL.tsx 主体仍复用原有查看逻辑：
```ts
```typescript
const viewedTask = viewingAgentTaskId ? tasks[viewingAgentTaskId] : undefined
const viewedAgentTask = ... (isLocalAgentTask(viewedTask) ? viewedTask : undefined)
const displayedMessages = viewedAgentTask ? displayedAgentMessages : messages
@@ -171,7 +177,7 @@ user([tool_result..., text("<fork-boilerplate>...Your directive: <prompt>")])
这个归一化只影响 UI 展示用的 `displayedAgentMessages`，不回写 `task.messages`，也不改变发送给模型的 fork transcript。
### 3.6 生命周期
#### 生命周期
完全复用官方既有机制：
@@ -181,7 +187,7 @@ user([tool_result..., text("<fork-boilerplate>...Your directive: <prompt>")])
- **evictAfter 过期**：`useBackgroundAgentTasks` 过滤时自然剔除，selector 行消失
- **手动清除**：`stopOrDismissAgent(taskId)` 设 `evictAfter = 0`，立即消失
## 四、设计决策
### 设计决策
1. **数据源单一**：`useBackgroundAgentTasks` 是唯一过滤点，PromptInput 也复用，避免过滤条件散落
2. **pill 聚焦保留**：Enter 切视图后不松焦，让 ↑↓ 连续导航，贴近官方体验
@@ -191,7 +197,7 @@ user([tool_result..., text("<fork-boilerplate>...Your directive: <prompt>")])
6. **与 `BackgroundTasksDialog` 共存**：Shift+↓ 行为完全不变，selector 是补充快捷入口；Dialog 仍管 shell / workflow / monitor_mcp 等 selector 不显示的 task 类型
7. **fork prompt 展示层兜底**：fork prompt 不依赖 boilerplate 自身渲染，统一在 `displayedAgentMessages` 中合成独立用户消息；普通 subagent 不走该分支，避免 prompt 重复
## 五、关键 API 复用
### 关键 API 复用
| 官方已有能力 | selector 如何使用 |
|---|---|
@@ -204,7 +210,7 @@ user([tool_result..., text("<fork-boilerplate>...Your directive: <prompt>")])
| `formatTokens` (`utils/format.ts`) | token 数 1k 缩写 |
| `footer:up` / `footer:down` / `footer:openSelected` keybinding | 键盘路由复用 Footer context |
## 六、文件索引
### 文件索引
| 文件 | 职责 |
|------|------|
@@ -218,8 +224,13 @@ user([tool_result..., text("<fork-boilerplate>...Your directive: <prompt>")])
| `src/components/messages/UserTextMessage.tsx` | 识别 `<fork-boilerplate>`，交给 fork 专用 renderer 处理 |
| `src/components/messages/UserForkBoilerplateMessage.tsx` | 将 fork boilerplate text 折叠为纯用户 prompt；作为 transcript 中原位渲染的兼容路径 |
## 七、已知限制
### 已知限制
- `Date.now()` 在 `useBackgroundAgentTasks` 的 useMemo 里冻结于 `[tasks]` 触发时：若长时间没有新 task 变更事件，某个 terminal agent 的 grace 期过期后不会立即从 selector 消失，要等下一次 tasks 变化才刷新。在典型使用（主对话一直在产生消息）下感知不到，暂不额外加 interval。
- Selector 当前不处理 Shell Task / Workflow / Monitor MCP 等类型——这些仍走 `BackgroundTasksDialog`（Shift+↓）管理。
- `AssistantToolUseMessage` 的 `defaultCollapsed` prop 目前无调用方传值，保留作为后续"agent 详情视图内工具块默认折叠"扩展点。
## 关联笔记
- [[claude-code-best/docs/features/fork-subagent]]
- [[claude-code-best/docs/features/coordinator-mode]]