附录 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

核心文件

关键协议细节

工作任务获取（Long-poll）：

// 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）：

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）：

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）

核心文件

关键设计

以 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 对象存储但有各自的工作文件和当前分支。

核心文件

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 系统

// 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）

核心文件

team.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：后台智能与持续学习