# 附录 I：智能分层基础设施
> 基础设施决定上限——再聪明的 Agent，也跑在具体的进程、协议和文件系统之上。
---
## 附录 I-A：Bridge / IDE 远程控制
### 功能描述
Claude Code 可被 VS Code、JetBrains 等 IDE 插件以 WebSocket 协议**远程控制**：IDE 发送任务指令，Claude Code 在终端执行，结果流式回传给 IDE 展示。
这是 Claude Code VS Code 扩展、JetBrains 插件的底层通信机制。
### 架构概览
```
IDE 插件（VS Code / JetBrains）
│
│ HTTPS long-poll（工作任务获取）
│ + WebSocket / SSE（结果回传）
▼
Anthropic Bridge API（云端中继）
│
│ HTTP
▼
Claude Code CLI（本地进程）
├─ bridgeMain.ts ← 主循环：轮询任务、启动 Session
├─ sessionRunner.ts ← 每个任务对应一个 Session 进程
├─ replBridgeTransport.ts ← REPL ↔ Bridge 双向消息传输
├─ flushGate.ts ← 消息缓冲（防止乱序）
└─ bridgePermissionCallbacks.ts ← 权限请求代理给 IDE
```
### 核心文件
| 文件 | 作用 |
|------|------|
| `src/bridge/bridgeMain.ts` | 主循环：轮询 Bridge API 获取工作任务，管理 Session 生命周期 |
| `src/bridge/sessionRunner.ts` | 为每个任务创建独立 Claude Code 进程（`SessionSpawner`） |
| `src/bridge/replBridgeTransport.ts` | REPL 与 Bridge 之间的双向消息传输层 |
| `src/bridge/bridgeApi.ts` | Bridge API 客户端（HTTP），包括工作任务获取与状态上报 |
| `src/bridge/flushGate.ts` | 消息有序缓冲（确保 IDE 端按序收到消息） |
| `src/bridge/bridgePermissionCallbacks.ts` | 将权限请求（如写文件确认）代理给 IDE 展示 |
| `src/bridge/jwtUtils.ts` | JWT 令牌管理与自动刷新（`createTokenRefreshScheduler`） |
| `src/bridge/workSecret.ts` | Work Secret 解码（base64url JSON，含 API key + git 信息） |
| `src/bridge/trustedDevice.ts` | 可信设备令牌（避免每次 IDE 连接都弹认证） |
| `src/bridge/types.ts` | 协议类型定义（`WorkData`、`WorkSecret`、`SessionActivity` 等） |
### 关键协议细节
**工作任务获取**（Long-poll）：
```typescript
// bridgeMain.ts 简化逻辑
while (running) {
const work = await client.getWork(bridgeId) // 长轮询，最多等 30s
if (work.type === 'session') {
await sessionSpawner.spawn(work) // 启动子进程处理任务
} else if (work.type === 'healthcheck') {
await client.respondHealthcheck(work.id) // 心跳回复
}
}
```
**Work Secret 结构**（解码自 base64url JSON）：
```typescript
type WorkSecret = {
version: number
session_ingress_token: string // Session 入口认证令牌
api_base_url: string // 使用的 API 地址
sources: Array<{ // 代码来源（可含 git clone 指令）
type: string
git_info?: { repo: string; ref?: string; token?: string }
}>
environment_variables?: Record<string, string> // 注入的环境变量
mcp_config?: unknown // 远端 MCP 配置
}
```
**权限代理**：当 Claude Code 遇到需要用户确认的操作（如写文件、执行 bash），不在终端弹出确认框，而是通过 `bridgePermissionCallbacks.ts` 将请求发送给 IDE，由 IDE 展示确认对话框。
**退避重连**（`BackoffConfig`）：
```typescript
type BackoffConfig = {
connInitialMs: number // 初始重连等待（毫秒）
connCapMs: number // 重连等待上限
connGiveUpMs: number // 放弃时间（超过则报错）
generalInitialMs: number
generalCapMs: number
generalGiveUpMs: number
}
```
### 与 Worktree 的集成
Bridge 模式下，`bridgeMain.ts` 在启动任务前会调用 `createAgentWorktree()` 为每个任务创建独立的 git worktree（隔离分支），任务完成后 `removeAgentWorktree()` 清理。
---
## 附录 I-B：Computer Use（桌面自动化）
### 功能描述
允许 Claude 通过截图观察桌面状态、模拟鼠标/键盘事件控制 macOS 应用，实现完整的"看-思考-操作"桌面自动化循环。
### 架构概览
```
LLM 调用 computer_use 工具
│
├─ screenshot() → macOS screencapture → PNG → Base64 → LLM
│
├─ click(x, y) → Accessibility API 模拟鼠标点击
├─ type(text) → Accessibility API 模拟键盘输入
├─ scroll(x, y, d) → 模拟滚轮事件
└─ key(combo) → 模拟快捷键（如 Cmd+C）
```
### 核心文件
| 文件 | 作用 |
|------|------|
| `src/utils/computerUse/` | 完整 Computer Use 实现目录 |
| `src/utils/computerUse/mcpServer.ts` | 以 MCP Server 形式暴露 Computer Use 工具 |
| `src/utils/computerUse/screenshot.ts` | 截图实现（macOS `screencapture` 命令） |
| `src/utils/computerUse/input.ts` | 鼠标/键盘事件模拟（macOS Accessibility API） |
### 关键设计
**以 MCP Server 集成**：Computer Use 工具不是内置工具，而是以 MCP Server 形式运行（`computerUse/mcpServer.ts`），通过 stdio 协议与主 Agent 通信。这使得 Computer Use 权限管理与其他 MCP 工具一致。
**Computer Use Lock**：防止多个 Agent 并发控制桌面，避免鼠标/键盘事件交叉污染。
**权限要求**：需要 macOS 辅助功能权限（在系统偏好设置 → 隐私与安全性 → 辅助功能中授权）。
---
## 附录 I-C：Git Worktree 并行分支
### 功能描述
允许 Agent（或子 Agent）在不同的 git worktree 中**并行工作于不同分支**，互不干扰。每个 Worktree 是同一仓库的独立工作目录，共享 `.git` 对象存储但有各自的工作文件和当前分支。
### 核心文件
| 文件 | 作用 |
|------|------|
| `src/utils/worktree.ts` | Worktree 完整生命周期管理（创建/校验/删除） |
| `src/tools/EnterWorktreeTool/` | `EnterWorktreeTool`：LLM 可调用，进入新 worktree |
| `src/tools/ExitWorktreeTool/` | `ExitWorktreeTool`：LLM 可调用，退出并清理 worktree |
### Worktree 生命周期
```
createAgentWorktree(branchSlug)
│
├─ 1. 校验 slug（防路径穿越攻击）
│ └─ VALID_WORKTREE_SLUG_SEGMENT = /^[a-zA-Z0-9._-]+$/
│
├─ 2. git worktree add .claude/worktrees/<slug> <branch>
│
├─ 3. 复制 settings.json 到新 worktree（继承配置）
│
├─ 4. 执行 WorktreeCreate Hook（如有）
│ └─ executeWorktreeCreateHook()
│
└─ 返回新 worktree 路径（子 Agent 将在此路径下工作）
removeAgentWorktree(slug)
│
├─ 1. 执行 WorktreeRemove Hook（如有）
├─ 2. git worktree remove --force .claude/worktrees/<slug>
└─ 3. 删除本地配置文件
```
### 与多 Agent 的集成
`AgentTool`（第 13 章）在启动子 Agent 时，若 `worktree` 参数设为 `true`，会：
1. 调用 `createAgentWorktree()` 创建隔离 worktree
2. 在该 worktree 目录下启动子 Agent（`cwd` 切换）
3. 子 Agent 完成后，主 Agent 调用 `removeAgentWorktree()` 清理
这是第 13 章 `AgentTool` 中提到的"worktree 隔离"的具体实现。
### Hooks 系统
```typescript
// src/utils/hooks.ts
executeWorktreeCreateHook(worktreePath): Promise<void>
executeWorktreeRemoveHook(worktreePath): Promise<void>
// 触发条件：src/utils/worktree.ts 在创建/删除时调用
// 用途：用户可以自定义脚本（如自动 npm install、设置 env 等）
```
---
## 附录 I-D：Team / Swarm 模式（多 Agent 树）
### 功能描述
多个 Claude Code 实例组成**树形结构**协同工作：一个 Leader Agent 创建并管理一组 Teammate Agents，通过邮箱系统传递消息，各自负责不同子任务。
与第 13 章的 `AgentTool`（进程内子 Agent）不同，Swarm 模式的每个 Teammate 是**独立的 Claude Code 进程**，拥有独立的终端窗口（iTerm2 Pane / tmux 窗口）。
### 架构概览
```
Leader Agent
│
├─ TeamCreateTool → 创建 team.json，启动 Teammate 进程
├─ SendMessageTool → 写入 Teammate 邮箱（文件系统）
├─ TaskGetTool → 检查 Teammate 任务状态
└─ TeamDeleteTool → 关闭所有 Teammate，清理 team.json
Teammate Agent（独立进程 × N）
├─ 读取邮箱（轮询 ~/.claude/mailboxes/<agentId>/）
├─ 执行任务（使用自己的工具集）
├─ 完成后发送 idle 通知给 Leader
└─ 权限从 Leader 同步（leaderPermissionBridge.ts）
```
### 核心文件
| 文件 | 作用 |
|------|------|
| `src/utils/swarm/constants.ts` | 常量定义（`TEAM_LEAD_NAME`、`SWARM_SESSION_NAME`、环境变量名） |
| `src/utils/swarm/teammateInit.ts` | Teammate 启动时注册 Stop Hook（完成后通知 Leader） |
| `src/utils/swarm/teamHelpers.ts` | team.json 读写，成员状态管理（`setMemberActive` 等） |
| `src/utils/swarm/permissionSync.ts` | 权限从 Leader 同步给 Teammate |
| `src/utils/swarm/teammateLayoutManager.ts` | 多 Agent 的终端布局管理（Pane 分配） |
| `src/utils/swarm/backends/TmuxBackend.ts` | Tmux 后端：用 tmux 窗格展示各 Teammate 输出 |
| `src/utils/swarm/backends/ITermBackend.ts` | iTerm2 后端：用 iTerm2 分屏展示各 Teammate 输出 |
| `src/utils/teammateMailbox.ts` | 邮箱系统：基于文件系统的 Agent 间消息传递 |
### team.json 结构
```json
{
"teamName": "claude-swarm",
"leadAgentId": "uuid-of-leader",
"members": [
{
"agentId": "uuid-of-teammate-1",
"agentName": "backend",
"active": true,
"color": "blue"
},
{
"agentId": "uuid-of-teammate-2",
"agentName": "frontend",
"active": false,
"color": "green"
}
],
"teamAllowedPaths": ["/project/src"]
}
```
### 邮箱系统（消息传递）
```
Leader 发送消息：
writeToMailbox(teammateAgentId, message)
→ 写入 ~/.claude/mailboxes/<teammateAgentId>/inbox/<timestamp>.json
Teammate 接收消息：
readMailbox(agentId)
→ 读取所有未处理的 inbox 文件，按时间排序处理
Teammate 完成，发送 idle 通知给 Leader：
createIdleNotification() → writeToMailbox(leadAgentId, idleMsg)
```
### 终端布局后端（多屏显示）
Swarm 支持两种多窗格布局：
```
TmuxBackend（在 tmux 会话中运行）：
├─ 为每个 Teammate 创建 tmux 窗格（pane）
├─ Leader 与所有 Teammate 的输出分区展示
└─ 使用独立 socket（getSwarmSocketName()）隔离用户的 tmux 会话
ITermBackend（在 iTerm2 中运行）：
├─ 调用 iTerm2 AppleScript API 创建 Split Pane
└─ 每个 Teammate 占用一个 Pane
```
### Coordinator Mode（独立协调者）
与 Swarm 不同，Coordinator Mode 通过环境变量 `CLAUDE_CODE_COORDINATOR_MODE=1` 启用，由 `feature('COORDINATOR_MODE')` 门控：
```
Swarm 模式： Coordinator Mode：
Leader 可以直接执行工具 Leader 只使用管理工具
Teammate 也可执行工具 Leader 不直接操作文件/代码
所有具体操作交给 Teammate 执行
```
Coordinator Mode 适合任务边界清晰、需要严格"管理与执行分离"的场景。
### 使用前提
- **Tmux 后端**：需要安装 tmux（macOS: `brew install tmux`）
- **iTerm2 后端**：需要在 iTerm2 中运行，且开启 Python API（iTerm2 → Preferences → General → Magic → Enable Python API）
- **权限**：所有 Teammate 共享 Leader 的 allowed paths（通过 `teamAllowedPaths` 同步）
---
## 附录 I 源码快速导航
```
智能分层基础设施
├── Bridge / IDE 远控
│ └── src/bridge/ ← 40+ 文件，完整 Bridge 实现
│ ├── bridgeMain.ts ← 主循环（Long-poll + Session 管理）
│ ├── sessionRunner.ts ← Session 进程启动
│ ├── replBridgeTransport.ts ← REPL ↔ Bridge 双向传输
│ ├── bridgePermissionCallbacks.ts ← 权限代理
│ ├── flushGate.ts ← 消息有序缓冲
│ └── types.ts ← WorkData / WorkSecret / SessionActivity
│
├── Computer Use（桌面自动化）
│ └── src/utils/computerUse/ ← screenshot + input + MCP server
│
├── Git Worktree 并行分支
│ ├── src/utils/worktree.ts ← 创建/删除/校验
│ ├── src/tools/EnterWorktreeTool/ ← LLM 可调用工具
│ └── src/tools/ExitWorktreeTool/ ← LLM 可调用工具
│
└── Team / Swarm（多 Agent 树）
├── src/utils/swarm/ ← 22 个文件，完整 Swarm 实现
│ ├── constants.ts ← 常量（TEAM_LEAD_NAME、socket 名等）
│ ├── teammateInit.ts ← Teammate 初始化（注册 Stop Hook）
│ ├── teamHelpers.ts ← team.json 读写
│ ├── permissionSync.ts ← 权限 Leader → Teammate 同步
│ └── backends/ ← Tmux / iTerm2 / InProcess 后端
├── src/utils/teammateMailbox.ts ← 文件系统邮箱（Agent 间消息）
└── src/coordinator/ ← Coordinator Mode（严格管理/执行分离）
```
---
→ [附录 II：后台智能与持续学习](appendix-II-background-intelligence)