Comingbar|未来吧

Appearance

来源：Claude Code 技术文档 - v2.1.88 源码分析

Bridge 远程通信 ​

8.1 Bridge 架构概述 ​

Bridge 是 Claude Code 的远程通信系统，允许将会话在不同端点之间桥接。它实现了工作轮询、消息传输、心跳检测和会话生命周期管理。

┌──────────────────┐         ┌──────────────────┐
│   Local Client   │←──────→│   Remote Server   │
│   (CLI 实例)     │  HTTP   │   (Bridge API)    │
│                  │  轮询   │                   │
│  bridgeMain.ts   │         │  Work Queue       │
│  replBridge.ts   │         │  Session Store     │
│  bridgeMessaging │         │  Heartbeat Mon.    │
└──────────────────┘         └──────────────────┘

8.2 核心类型定义 ​

8.2.1 工作数据 ​

type WorkData = {
  workId: string              // 工作项 ID
  sessionId: string           // 会话 ID
  messages: Message[]         // 消息列表
  config: BridgeConfig        // 配置
  // ... 更多工作负载字段
}

type WorkResponse = {
  status: 'completed' | 'failed' | 'cancelled'
  result?: unknown
  error?: string
}

8.2.2 会话状态 ​

type SessionDoneStatus =
  | 'completed'     // 正常完成
  | 'failed'        // 执行失败
  | 'cancelled'     // 用户取消
  | 'timeout'       // 超时
  | 'killed'        // 被杀除

8.2.3 Bridge 配置 ​

type BridgeConfig = {
  apiEndpoint: string         // API 端点 URL
  authToken: string           // 认证令牌
  pollInterval: number        // 轮询间隔
  heartbeatInterval: number   // 心跳间隔
  maxRetries: number          // 最大重试次数
  // ... 更多配置
}

8.2.4 Bridge API 客户端 ​

type BridgeApiClient = {
  // 8 个核心方法
  getWork(): Promise<WorkData | null>
  submitResult(workId: string, response: WorkResponse): Promise<void>
  sendHeartbeat(sessionId: string): Promise<void>
  registerSession(config: SessionConfig): Promise<void>
  unregisterSession(sessionId: string): Promise<void>
  getSessionStatus(sessionId: string): Promise<SessionStatus>
  sendMessage(sessionId: string, message: Message): Promise<void>
  getMessages(sessionId: string, since?: string): Promise<Message[]>
}

8.3 Bridge 主循环 (bridgeMain.ts) ​

8.3.1 主循环流程 ​

bridgeMain()
  │
  ├─ 1. 初始化 Bridge 配置
  │     └─ 读取环境变量/配置文件
  │
  ├─ 2. 创建 BridgeApiClient
  │     └─ 配置认证、端点、超时
  │
  ├─ 3. 注册会话
  │     └─ registerSession(config)
  │
  ├─ 4. 启动心跳
  │     └─ setInterval(sendHeartbeat, interval)
  │
  └─ 5. 工作轮询循环
        │
        ├─ getWork() → WorkData | null
        │
        ├─ 有工作?
        │   ├─ YES → 创建/恢复会话
        │   │       ├─ 设置 AbortController
        │   │       ├─ 创建 QueryEngine
        │   │       ├─ 执行工作
        │   │       ├─ 提交结果
        │   │       └─ 重置轮询间隔
        │   │
        │   └─ NO → 退避等待
        │           ├─ 增加轮询间隔（指数退避）
        │           └─ 最大退避上限
        │
        └─ 循环继续...

8.3.2 退避策略 ​

初始间隔 → 较短 (如 1s)
  ↓ 无工作
增加间隔 → 逐步增加 (2s, 4s, 8s...)
  ↓ 达到上限
最大间隔 → 固定上限 (如 30s)
  ↓ 收到工作
重置间隔 → 回到初始值 (1s)

8.4 REPL Bridge (replBridge.ts) ​

8.4.1 ReplBridgeHandle ​

type ReplBridgeHandle = {
  // 消息写入
  writeMessages(messages: Message[]): Promise<void>
  // 写入 SDK 消息
  writeSdkMessages(messages: SDKMessage[]): Promise<void>
  // 发送控制信号
  sendControlStart(): Promise<void>
  sendControlStop(): Promise<void>
  sendControlError(error: Error): Promise<void>
  sendControlHeartbeat(): Promise<void>
}

8.4.2 消息桥接流程 ​

用户输入 (远程端)
  │
  ▼
Bridge API → getWork()
  │
  ▼
bridgeMain.ts → 创建会话
  │
  ▼
replBridge.ts → ReplBridgeHandle
  │
  ├─ writeMessages() → 发送到 QueryEngine
  ├─ writeSdkMessages() → SDK 层消息
  │
  ▼
QueryEngine 处理
  │
  ▼
结果消息 → writeMessages() → Bridge API → 远程端显示

8.5 Bridge 消息传输 (bridgeMessaging.ts) ​

8.5.1 消息去重 ​

使用 BoundedUUIDSet FIFO 环形缓冲区进行消息去重：

// 固定大小的 UUID 集合
// 使用 FIFO 策略淘汰旧的 UUID
class BoundedUUIDSet {
  private maxSize: number
  private set: Set<string>
  private queue: string[]
  
  add(uuid: string): boolean
  // 如果已存在返回 false (重复消息)
  // 如果超出 maxSize，淘汰最旧的 UUID
  
  has(uuid: string): boolean
  // 检查是否已处理
}

8.5.2 为什么需要去重 ​

Bridge 通信使用轮询模式，可能导致：

  1. 同一消息在多次轮询中返回
  2. 网络重试导致消息重复
  3. 多客户端同时读取导致竞争

BoundedUUIDSet 确保每条消息只处理一次。

8.6 Bridge 启用检测 (bridgeEnabled.ts) ​

8.6.1 GrowthBook 集成 ​

// Bridge 功能启用通过 GrowthBook Feature Gate 控制
function isBridgeEnabled(): boolean {
  // 1. 检查编译时 feature('BRIDGE')
  // 2. 检查 GrowthBook 运行时标志
  // 3. 检查环境变量覆盖
  return feature('BRIDGE') && growthbook.isOn('bridge_enabled')
}

8.6.2 Feature Gate 层次 ​

编译时 feature('BRIDGE')
  │
  ├─ false → Bridge 代码不编译到产物中
  │
  └─ true → 检查运行时标志
       │
       ├─ GrowthBook 'bridge_enabled'
       │   ├─ false → 功能禁用
       │   └─ true → 功能启用
       │
       └─ 环境变量覆盖 (开发/测试用)

8.7 会话管理 ​

8.7.1 会话创建 (createSession.ts) ​

// 创建新的 Bridge 会话
async function createSession(config: SessionConfig): Promise<SessionHandle> {
  // 1. 生成 SessionId
  // 2. 注册到 Bridge API
  // 3. 初始化 QueryEngine
  // 4. 返回 SessionHandle
}

8.7.2 会话运行器 (sessionRunner.ts) ​

// 管理会话生命周期
async function runSession(handle: SessionHandle): Promise<SessionDoneStatus> {
  // 1. 启动查询循环
  // 2. 处理消息流
  // 3. 检测中断/超时
  // 4. 清理资源
  // 5. 返回最终状态
}

8.8 辅助系统 ​

8.8.1 容量唤醒 (capacityWake.ts) ​

当 Bridge 检测到远程容量可用时，唤醒等待中的客户端：

客户端等待中 (退避轮询)
  │
  ▼
容量唤醒信号
  │
  ├─ 重置轮询间隔
  ├─ 立即尝试获取工作
  └─ 恢复活跃轮询

8.8.2 JWT 工具 (jwtUtils.ts) ​

// Bridge 认证使用 JWT
function createToken(payload: TokenPayload): string
function verifyToken(token: string): TokenPayload
function isTokenExpired(token: string): boolean

8.8.3 会话 ID 兼容 (sessionIdCompat.ts) ​

处理新旧会话 ID 格式之间的兼容性转换。

8.8.4 可信设备 (trustedDevice.ts) ​

// 设备信任管理
function isTrustedDevice(): boolean
function registerTrustedDevice(): Promise<void>
function revokeTrustedDevice(): Promise<void>

8.8.5 工作密钥 (workSecret.ts) ​

用于加密 Bridge 传输中的敏感数据。

8.9 Bridge 调试 (bridgeDebug.ts) ​

// 调试工具
function logBridgeEvent(event: string, data?: unknown): void
function getBridgeStats(): BridgeStats
function dumpBridgeState(): void

调试信息包括： ​

信息

描述

轮询统计

轮询次数、成功/失败率

消息统计

发送/接收消息数量

心跳状态

最后心跳时间、失败次数

会话状态

当前会话状态和持续时间

连接状态

网络连接质量指标

8.10 Bridge 与其他系统的交互 ​

Bridge 系统
  │
  ├─ → QueryEngine: 转发工作请求
  ├─ → AppState: 更新会话状态
  ├─ → ToolPermissionContext: 应用远程权限
  ├─ → CostTracker: 远程成本跟踪
  ├─ ← Commands: Bridge 安全命令过滤
  │     └─ 仅允许 BRIDGE_SAFE_COMMANDS
  └─ ← init(): Bridge 模式初始化

MIT

Copyright © 2025-present PanJiadong