Deep Dive ｜ bridge/bridgeMain.ts 2999 行双向消息总线拆解

重要性：⭐⭐⭐⭐（Claude Code ↔ IDE 实时双向同步的核心） 真实位置：src/bridge/bridgeMain.ts（2999 行） 配套：src/bridge/ 目录 25 个文件，bridgeMain.ts 是协调者 关联：phase-07-advanced.md § 7.3 Bridge、topics/async-generator-pattern.md

---

1. 整体架构

1.1 25 个 bridge/ 文件全景

src/bridge/
├── bridgeMain.ts           (2999 行)  ⭐ 协调者
├── bridgeApi.ts            API 定义
├── bridgeConfig.ts         配置
├── bridgeDebug.ts          调试
├── bridgeEnabled.ts        启用判断
├── bridgeMessaging.ts      消息序列化
├── bridgePermissionCallbacks.ts  权限回调
├── bridgePointer.ts        指针协议
├── bridgeStatusUtil.ts     状态工具
├── bridgeUI.ts             UI 集成
│
├── capacityWake.ts         容量唤醒（保活）
├── codeSessionApi.ts       Code session API
├── createSession.ts        创建 session
├── debugUtils.ts           调试工具
├── envLessBridgeConfig.ts  无 env 配置
├── flushGate.ts            ⭐ 背压控制
├── inboundAttachments.ts   入站附件
├── inboundMessages.ts      ⭐ 入站消息
├── initReplBridge.ts       初始化 REPL bridge
├── jwtUtils.ts             JWT 鉴权
│
├── pollConfig.ts           轮询配置
├── pollConfigDefaults.ts   轮询默认
├── remoteBridgeCore.ts     远程 bridge 核心
├── replBridge.ts           (2406 行) ⭐ REPL ↔ Bridge
├── replBridgeHandle.ts     handle 抽象
└── (其他)

bridgeMain.ts 是"协调者"，replBridge.ts 是"具体实现"，flushGate.ts 是"背压控制器"。

1.2 双向消息流

                  ┌────────────────────┐
                  │   bridgeMain.ts    │
                  │  (协调者 + 状态机)  │
                  └─────────┬──────────┘
                            │
        ┌───────────────────┼───────────────────┐
        ▼                   ▼                   ▼
┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│ replBridge.ts│    │ flushGate.ts │    │ pollConfig.ts│
│ (REPL ↔ Br) │    │ (背压)       │    │ (轮询)       │
└──────┬───────┘    └──────┬───────┘    └──────┬───────┘
       │                   │                   │
       └───────────────────┴───────────────────┘
                            │
                            ▼
                  ┌────────────────────┐
                  │   传输层            │
                  │ WebSocket / stdio   │
                  └─────────┬──────────┘
                            │
              ┌─────────────┴─────────────┐
              ▼                           ▼
        ┌──────────┐                 ┌──────────┐
        │  IDE     │                 │  Remote  │
        │ VSCode   │                 │  Server  │
        └──────────┘                 └──────────┘

关键设计： - bridgeMain.ts 不直接传输，只协调 + 状态机 - replBridge.ts 实现"REPL 端"细节 - flushGate.ts 控制"背压"（不淹没消费者） - pollConfig.ts 控制"轮询"（在 pull 模型下用）

---

2. bridgeMain.ts 结构总览（2999 行）

bridgeMain.ts (2999 行)
│
├── 行 1-58    ：imports
├── 行 59-105  ：配置 + 常量
│   ├── BackoffConfig          行 59
│   ├── DEFAULT_BACKOFF        行 72
│   ├── STATUS_UPDATE_INTERVAL_MS 行 82
│   ├── SPAWN_SESSIONS_DEFAULT 行 83
├── 行 107-127 ：辅助函数
│   ├── pollSleepDetectionThresholdMs  行 107
│   ├── spawnScriptArgs        行 119
│   ├── safeSpawn              行 127
│
├── 行 1582-1604：错误分类
│   ├── CONNECTION_ERROR_CODES
│   ├── isConnectionError
│   ├── isServerError
│
├── 行 1615-1677：工具函数
│   ├── addJitter              行 1615
│   ├── formatDelay            行 1619
│
├── 行 1678-1698：超时处理
│   ├── onSessionTimeout       行 1678
│
├── 行 1699-1736：参数解析
│   ├── ParsedArgs             行 1699
│   ├── SPAWN_FLAG_VALUES
│   ├── parseSpawnValue
│   ├── parseCapacityValue
│   ├── parseArgs              行 1737
│
├── 行 1953-... ：session 标题
│   ├── TITLE_MAX_LEN
│   ├── deriveSessionTitle
│
└── ... 还有更多

---

3. 关键概念详解

3.1 BackoffConfig + 退避算法

// 行 59-105
export type BackoffConfig = {
  initialMs: number     // 初始延迟
  maxMs: number         // 最大延迟
  factor: number        // 退避因子
  jitter: boolean       // 是否加随机抖动
}

const DEFAULT_BACKOFF: BackoffConfig = {
  initialMs: 1000,
  maxMs: 30000,
  factor: 2,
  jitter: true,
}

指数退避：

attempt 1: 1000ms
attempt 2: 2000ms
attempt 3: 4000ms
attempt 4: 8000ms
... 封顶 30000ms
+ 随机抖动（避免雪崩）

addJitter（行 1615）：

function addJitter(ms: number): number {
  // 1000ms → 800-1200ms 之间随机
  return ms * (0.8 + Math.random() * 0.4)
}

为什么要 jitter： - 多个客户端同时重试 → 雪崩 - 加随机 → 错开重试时间

3.2 错误分类（行 1582-1604）

const CONNECTION_ERROR_CODES = new Set([
  'ECONNREFUSED',
  'ECONNRESET',
  'ETIMEDOUT',
  'ENOTFOUND',
  'EHOSTUNREACH',
  'EPIPE',
])

export function isConnectionError(err: unknown): boolean {
  return err instanceof Error && CONNECTION_ERROR_CODES.has((err as any).code)
}

export function isServerError(err: unknown): boolean {
  return err instanceof Error && (err as any).status >= 500
}

4 类错误 + 不同处理： | 错误类型 | 处理 | |---|---| | 连接错误（ECONNREFUSED 等）| 重试 + 退避 | | 服务端错误（5xx）| 重试 + 退避 | | 客户端错误（4xx）| 不重试 + 报错 | | 超时（ETIMEDOUT）| 重试 + 退避 |

3.3 Status Update Interval（行 82）

const STATUS_UPDATE_INTERVAL_MS = 1_000

每秒推送一次状态 —— IDE 端显示"loading"动画用。

3.4 Spawn Sessions（行 83）

const SPAWN_SESSIONS_DEFAULT = 32

默认 32 个并发 session —— bridge 同时管理 32 个 session。

为什么 32： - IDE 用户的 session 数有限 - 32 是"既能并发，又不爆资源"的折中

3.5 safeSpawn（行 127-...）

function safeSpawn(
  command: string,
  args: string[],
  options: SpawnOptions,
): ChildProcess {
  // 1. 检查命令是否存在
  // 2. 安全环境变量（不传父进程所有 env）
  // 3. 限制资源（CPU / 内存 / fd）
  // 4. 设置 timeout
  // 5. spawn
}

安全 spawn 模式： - 不传 process.env（防止泄漏） - 限制资源（DoS 保护） - 不继承父进程的 cwd

3.6 Spawn Modes（行 1699-1736）

export type ParsedArgs = {
  spawn?: SpawnMode | string
  capacity?: number | string
  // ... 其他
}

const SPAWN_FLAG_VALUES = ['session', 'same-dir', 'worktree'] as const

function parseSpawnValue(raw: string | undefined): SpawnMode | string {
  // 解析 --spawn=session / --spawn=same-dir / --spawn=worktree
}

3 种 spawn 模式： - session —— 每个 session 一个进程 - same-dir —— 同 cwd 多个 session 共享 - worktree —— 每个 session 独立 git worktree

worktree 是隔离最强的 —— Claude Code 的修改不会污染主分支。

3.7 deriveSessionTitle（行 1956）

const TITLE_MAX_LEN = 80

function deriveSessionTitle(text: string): string {
  // 从第一条用户消息提取标题
  // 1. 取第一行
  // 2. 截到 80 字符
  // 3. 清理（去 markdown 标记）
  return firstLine.slice(0, TITLE_MAX_LEN)
}

Session 标题自动生成 —— IDE 显示 session 列表时用。

3.8 onSessionTimeout（行 1678）

function onSessionTimeout(session: Session): void {
  // 1. 关闭 stdin / stdout
  // 2. 等子进程自然退出（graceful）
  // 3. 超时 5s 后 SIGKILL
  // 4. 通知 IDE session 关闭
  // 5. 清理资源
}

优雅关闭流程： 1. 通知 IDE "session 关闭中" 2. 给 Claude Code 5s 清理 3. 5s 后强制 kill 4. 释放资源

3.9 消息处理（inboundMessages.ts / outboundMessages.ts）

// inboundMessages.ts 处理 IDE → CLI 的消息
export function handleInboundMessage(
  msg: BridgeMessage,
  context: BridgeContext,
): void {
  switch (msg.type) {
    case 'user_input':       // IDE 端用户输入
      context.engine.submitMessage(msg.text)
      break
    case 'file_selected':    // IDE 选中文件
      context.appState.setState({ selectedFile: msg.path })
      break
    case 'selection_changed': // IDE 选中内容变化
      context.appState.setState({ selection: msg.text })
      break
    case 'file_saved':       // IDE 保存文件
      context.invalidateFileCache(msg.path)
      break
    // ... 20+ 消息类型
  }
}

20+ 消息类型 —— bridge 协议覆盖 IDE 操作的方方面面。

3.10 背压控制（flushGate.ts）

// flushGate.ts
export class FlushGate {
  private queue: BridgeMessage[] = []
  private flushing = false
  private maxQueueSize = 100

  enqueue(msg: BridgeMessage): boolean {
    if (this.queue.length >= this.maxQueueSize) {
      // 队列满，丢弃（不阻塞 producer）
      return false
    }
    this.queue.push(msg)
    this.scheduleFlush()
    return true
  }

  private scheduleFlush(): void {
    if (this.flushing) return
    this.flushing = true
    setImmediate(() => this.flush())
  }

  private flush(): void {
    const batch = this.queue.splice(0, 50)  // 批处理
    this.transport.send(batch)
    this.flushing = false
    if (this.queue.length > 0) this.scheduleFlush()
  }
}

背压策略： - 批处理：50 条/批（不是 1 条/批） - 队列上限：100（满了丢弃） - 不阻塞 producer

意义： - IDE 端不会被 CLI 淹没 - CLI 端不会被 IDE 淹没 - 双方速度差异被缓冲

3.11 Polling 模式（pollConfig.ts）

// pull 模型（在某些场景）
export interface PollConfig {
  interval: number         // 轮询间隔
  maxRetries: number
  backoff: BackoffConfig
}

export const DEFAULT_POLL_CONFIG: PollConfig = {
  interval: 5000,
  maxRetries: 5,
  backoff: DEFAULT_BACKOFF,
}

什么时候用 polling： - WebSocket 不可用时（防火墙） - 远程 server 限制长连接 - 调试 / 测试场景

3.12 JWT 鉴权（jwtUtils.ts）

// JWT 用于远程 bridge 鉴权
export function generateBridgeToken(
  sessionId: string,
  secret: string,
  expiresIn: number,
): string {
  // 生成短期 JWT
  return jwt.sign({ sessionId }, secret, { expiresIn })
}

export function verifyBridgeToken(token: string, secret: string): {
  sessionId: string
} | null {
  // 验证 JWT
  return jwt.verify(token, secret) as { sessionId: string }
}

JWT 用于： - 远程 IDE ↔ CLI 鉴权 - 防中间人 - 短期 token（默认 1h 过期）

3.13 Capacity Wake（capacityWake.ts）

// 保持长连接的活跃
export function wakeBridge(connection: BridgeConnection): void {
  // 1. 发送 ping
  // 2. 等待 pong（超时 5s）
  // 3. 失败则标记为 dead
  connection.send({ type: 'ping' })
}

为什么需要： - 防火墙 / NAT 经常 idle 30s 后断连 - 主动 ping 保持连接活跃 - 30s 一次 ping（典型值）

---

4. bridgeMain.ts 推测的核心逻辑

// 推测的整体流程
export class BridgeMain {
  private config: BridgeConfig
  private connections: Map<string, BridgeConnection>
  private flushGate: FlushGate
  private statusInterval: NodeJS.Timeout

  async start() {
    // 1. 初始化 transport
    // 2. 启动 status updater
    // 3. 启动 inbound handler
    // 4. 启动 outbound queue
  }

  // 主循环
  private async loop() {
    while (!this.shutdown) {
      try {
        // 1. 读 inbound
        for await (const msg of this.inbound()) {
          await this.handleInbound(msg)
        }
      } catch (err) {
        // 错误分类 + 重试 / 降级
      }
    }
  }

  // 出站
  send(msg: BridgeMessage): void {
    this.flushGate.enqueue(msg)
  }

  // 状态更新
  private updateStatus() {
    const status = {
      sessions: this.connections.size,
      uptime: Date.now() - this.startedAt,
      memoryUsage: process.memoryUsage(),
    }
    this.broadcast({ type: 'status', data: status })
  }
}

---

5. 与 REPL 的协作

// replBridge.ts 推测
export class REPLBridge {
  private engine: QueryEngine
  private bridge: BridgeMain
  private fileCache: FileStateCache

  // REPL 端：本地状态变化时推送 IDE
  notifyMessageAdded(message: Message) {
    this.bridge.send({
      type: 'message_added',
      data: message,
    })
  }

  notifyFileChanged(path: string) {
    this.bridge.send({
      type: 'file_changed',
      data: { path },
    })
  }

  // IDE 端：接收消息时更新 REPL
  onInbound(msg: BridgeMessage) {
    switch (msg.type) {
      case 'user_input':
        this.engine.submitMessage(msg.data.text)
        break
      // ...
    }
  }
}

双向同步： - REPL → IDE：消息、文件 diff、cost 更新 - IDE → REPL：用户输入、文件选中、文件保存

---

6. replBridge.ts 2406 行（另一个大文件）

replBridge.ts (2406 行)
│
├── class REPLBridge
│   ├── 构造（与 BridgeMain 关联）
│   ├── 双向消息路由
│   ├── 文件状态同步
│   ├── IDE 通知（VSCode 特有）
│   ├── 会话状态同步
│   ├── 重连逻辑
│   ├── 错误恢复
│   └── 生命周期管理

replBridge 是 bridgeMain 的"REPL 端具体实现"。

---

7. Bridge 协议设计

7.1 消息格式

type BridgeMessage =
  | { type: 'message_added', data: Message }
  | { type: 'tool_use_start', data: { id: string, name: string } }
  | { type: 'tool_use_result', data: { id: string, result: unknown } }
  | { type: 'cost_update', data: { cost: number, tokens: number } }
  | { type: 'status', data: BridgeStatus }
  | { type: 'user_input', data: { text: string } }
  | { type: 'file_selected', data: { path: string } }
  | { type: 'file_saved', data: { path: string } }
  | { type: 'selection_changed', data: { text: string } }
  | { type: 'request_permission', data: { tool: string, input: unknown } }
  | { type: 'response_permission', data: { decision: 'allow' | 'deny' } }
  | { type: 'ping' }
  | { type: 'pong' }
  // ... 30+ 类型

30+ 消息类型 —— bridge 协议覆盖 IDE 操作的方方面面。

7.2 序列化

// bridgeMessaging.ts
export function serializeMessage(msg: BridgeMessage): string {
  return JSON.stringify(msg)
}

export function deserializeMessage(raw: string): BridgeMessage | null {
  try {
    return JSON.parse(raw)
  } catch {
    return null
  }
}

JSON 序列化 —— WebSocket / stdio 都用 JSON。

---

8. 关键洞察

8.1 "Bridge = 双向消息总线"的设计哲学

不是 RPC（不是"调用-返回"），是 Pub/Sub： - 任何一方都可以发任何消息 - 接收方按 type 决定怎么响应 - 无状态总线（不是 sessionful）

这和 GraphQL Subscriptions、WebSocket 推送、消息队列是同种思想。

8.2 背压控制是"生产级"标志

flushGate.ts 的存在说明 Claude Code 是真生产级： - 批处理（不是每条都发） - 队列上限（满了丢弃） - 不阻塞 producer - 这是消息总线的基本功

8.3 3 种 spawn 模式的 trade-off

模式	隔离	资源开销	适用
session	强	高	多任务并行
same-dir	弱	低	调试 / 快速
worktree	极强	高	安全敏感

用户可选是灵活性。

8.4 JWT 短期 token 的安全实践

• 短期（1h 过期）
• 签名（防中间人）
• 含 sessionId（可追溯）

比长期 API key 安全。

8.5 Capacity Wake 的"被动保活"

wakeBridge() 不是"持续 ping"，是"按需 ping"： - 空闲时偶尔 ping - 有消息时不用 ping - 节省带宽

这是个细节，但生产级系统的标志。

---

9. 实战：写一个简单 Bridge

// 简化版 bridge（~50 行）
type BridgeMessage = { type: string; data?: unknown }

class SimpleBridge {
  private connections: WebSocket[] = []
  private queue: BridgeMessage[] = []

  addConnection(ws: WebSocket) {
    this.connections.push(ws)
    // 推送积压消息
    for (const msg of this.queue) {
      ws.send(JSON.stringify(msg))
    }
  }

  send(msg: BridgeMessage) {
    this.queue.push(msg)
    // 限制队列大小
    if (this.queue.length > 1000) this.queue.shift()
    // 推送给所有连接
    for (const conn of this.connections) {
      if (conn.readyState === WebSocket.OPEN) {
        conn.send(JSON.stringify(msg))
      }
    }
  }

  onMessage(msg: BridgeMessage) {
    // 处理 inbound
  }
}

对比 Claude Code： - 简化版没有 flushGate（背压控制） - 简化版没有 capacity wake（保活） - 简化版没有 JWT（鉴权） - Claude Code 多了 20+ 边界处理

---

10. 阅读清单

1. ✅ 完整通读 src/bridge/bridgeMain.ts（2999 行）
2. ✅ 读 src/bridge/flushGate.ts（背压）
3. ✅ 读 src/bridge/inboundMessages.ts（入站）
4. ✅ 读 src/bridge/jwtUtils.ts（鉴权）
5. 📌 读 src/bridge/replBridge.ts（REPL 端 2406 行）
6. 📌 读 phase-07-advanced.md § 7.3

11. 练习任务

1. 数 bridgeMain.ts 里的 30+ BridgeMessage 类型 —— 列举完整
2. 设计你自己的 FlushGate —— 写一个简化版批处理队列
3. 思考：bridge 用 push (server push) 还是 pull (client poll)？为什么？什么时候切换？
4. 思考：JWT vs API Key 哪个更适合 bridge 鉴权？Claude Code 选 JWT 的理由？