第12章 IDE Bridge 通信架构

"Any sufficiently advanced CLI is indistinguishable from an IDE." -- 改自 Arthur C. Clarke

本章要点

1. 双模 Bridge 架构 -- Claude Code 通过两条路径实现 CLI 与 IDE 的桥接：独立进程 Bridge（bridgeMain.ts）用于 claude remote-control 命令行场景，REPL Bridge（replBridge.ts）用于 VS Code/JetBrains 等 IDE 内嵌场景
2. 环境-会话两层模型 -- Environment 注册建立宿主机与服务器的信任通道，Session 在通道内承载具体的对话生命周期，两层解耦使一个 Bridge 可服务多个并发会话
3. JWT 令牌生命周期管理 -- 从可信设备注册、OAuth 令牌交换到 session_ingress JWT 的主动续期，形成完整的认证链条，支持长达数小时的持续会话
4. 指数退避与容量感知 -- 轮询循环区分连接错误和通用错误两条退避轨道，结合系统休眠检测和容量唤醒信号，在可靠性与服务器友好之间取得平衡
5. 权限决策跨进程转发 -- 当子进程 CLI 需要工具执行权限时，control_request 经 Bridge 转发到 IDE/Web UI，决策结果以 control_response 回传，闭环完成跨进程权限对话

引言：从命令行到编辑器的桥梁

Claude Code 诞生于终端，但它的战场不仅限于终端。当一位开发者在 VS Code 中选中一段代码并请求 Claude 帮忙重构时，当另一位开发者在 JetBrains IDE 中让 Claude 分析整个项目结构时，他们所依赖的，是一套在 CLI 进程与 IDE 扩展之间搭建的精密通信管道 -- Bridge。

Bridge 的设计面临一个本质性矛盾：Claude Code 的核心能力（模型调用、工具执行、沙箱隔离、权限管理）全部实现在一个 Node.js/Bun 进程中，而 IDE 扩展运行在另一个完全不同的进程空间。如何让两端高效、安全、可靠地协作，是本章的核心命题。

更具挑战性的是，Bridge 不是简单的请求-响应管道。它需要处理长时间运行的会话（一个编码任务可能持续数小时）、支持多窗口并发（开发者可能在多个 IDE 标签页中同时使用 Claude）、在网络断开时优雅恢复、在 IDE 重启时无缝重连。这些需求交织在一起，催生了 Claude Code 中最复杂的子系统之一。

本章将从底层通信协议到上层会话管理，从认证安全到容错恢复，全面剖析 Bridge 的设计与实现。

12.1 为什么需要 Bridge

12.1.1 CLI 与 IDE 的鸿沟

Claude Code 作为一个 CLI 工具，天然运行在终端进程中。它拥有完整的工具系统、权限模型、流式对话引擎。但 IDE 扩展运行在另一个进程 -- VS Code 扩展运行在 Electron 的扩展宿主进程中，JetBrains 插件运行在 JVM 进程中。两者之间没有共享内存，不能直接调用函数。

最朴素的集成方式是让 IDE 扩展直接嵌入一个 Claude Code 运行时，但这不现实。Claude Code 的依赖链庞大（Bun 运行时、数百个 npm 模块、系统级沙箱组件），硬塞进 IDE 扩展会严重膨胀包体积，还会引发版本同步噩梦 -- 每次 Claude Code 更新，所有 IDE 扩展都要同步发布新版。

Bridge 模式的核心洞见是：让 Claude Code 继续运行在独立进程中，IDE 扩展只需要一个轻量的通信客户端。这样，Claude Code 的全部能力（包括沙箱、权限、MCP 协议等）对 IDE 透明可用，版本升级只需更新 CLI 本身。IDE 扩展的职责被简化为"消息的搬运工" -- 从用户界面收集输入，转交给 Bridge，然后把 Bridge 返回的结果渲染到编辑器中。

这种架构还带来了一个额外的好处：可测试性。Bridge 的所有行为都可以通过模拟的 API 客户端和 session spawner 进行单元测试，不依赖真实的 IDE 进程。类型定义中 BridgeApiClient、SessionSpawner、BridgeLogger 等接口的设计，正是为了这种可注入的测试模式。

12.1.2 两种集成场景

Claude Code 的 Bridge 架构服务于两种截然不同的场景：

独立进程 Bridge（Standalone Bridge）：开发者在终端运行 claude remote-control，启动一个持久运行的 Bridge 进程。这个进程向服务器注册为一个"环境"（Environment），然后持续轮询等待来自 claude.ai Web 界面或 IDE 扩展的任务。每个任务到达时，Bridge 会 spawn 一个子 Claude Code 进程来执行。这是 bridgeMain.ts 的职责。

REPL 内嵌 Bridge（REPL Bridge）：当开发者在 IDE 中使用 Claude Code 扩展时，扩展在后台启动一个 Claude Code REPL 进程。这个 REPL 进程内部初始化一个 Bridge 连接，将对话状态同步到 claude.ai Web 界面，同时接收来自 Web 端的输入和控制指令。这是 replBridge.ts 和 initReplBridge.ts 的职责。

两种模式共享大量基础设施 -- API 客户端、JWT 管理、消息协议、重试逻辑 -- 但在会话生命周期管理上有本质区别。独立 Bridge 是"一对多"的（一个 Bridge 进程服务多个会话），REPL Bridge 是"一对一"的（一个 REPL 进程对应一个 Bridge 会话）。

除了这两种模式之外，源码中还存在第三种变体：remoteBridgeCore.ts 实现的"无环境层 Bridge"。这是一种更新的 v2 直连模式，它完全绕过 Environments API 的工作派发层，直接通过 POST /v1/code/sessions/{id}/bridge 端点获取 worker JWT 和 epoch，建立 SSE+CCRClient 传输。这种模式消除了注册/轮询/确认/停止/心跳/注销的环境生命周期管理开销，使连接建立更加轻量。三种模式的存在反映了 Bridge 子系统正处于从轮询式架构向直连式架构的渐进迁移过程中。

12.1.3 VS Code 与 JetBrains 的统一抽象

无论是 VS Code 还是 JetBrains IDE，从 Bridge 的视角看都是"远端客户端"。Bridge 不直接与任何 IDE 通信 -- 它通过 claude.ai 的服务器作为中介：

IDE 扩展 <---> claude.ai 服务器 <---> Bridge 进程 <---> Claude Code CLI

这种间接通信的设计意味着 Bridge 不需要为每种 IDE 编写适配层。IDE 扩展只需实现 claude.ai 的 Web API 客户端，就能与 Bridge 交互。新增对 Neovim 或 Emacs 的支持，不需要修改 Bridge 的任何代码。

从特性门控的角度来看，Bridge 功能需要满足多项前置条件才能激活。bridgeEnabled.ts 中的 isBridgeEnabledBlocking 函数展示了这些条件的层叠结构：首先检查编译期特性标志（feature('BRIDGE_MODE')，通过 Bun bundler 的死代码消除确保外部构建不包含 Bridge 字符串字面量）；然后检查用户是否为 claude.ai 订阅者（排除 Bedrock/Vertex/API key 用户）；最后检查 GrowthBook 开关（tengu_ccr_bridge）是否对当前组织启用。任何一项不满足，Bridge 功能对用户完全不可见。这种多层门控保证了功能的灰度发布可以按组织维度精确控制。

12.2 Bridge 架构总览

下图展示了 Bridge 的两种运行模式及其与 IDE 和 Claude Code CLI 之间的通信路径：

12.2.1 目录结构与职责划分

src/bridge/ 目录包含 30 多个 TypeScript 文件，构成了 Bridge 子系统的完整实现。按职责可划分为以下几个层次：

src/bridge/
  |-- 核心流程
  |     |-- bridgeMain.ts        # 独立Bridge的主循环：注册→轮询→分发→清理
  |     |-- replBridge.ts        # REPL Bridge核心：注册→连接→消息转发→重连
  |     |-- initReplBridge.ts    # REPL Bridge初始化：鉴权门控、参数准备、动态导入
  |     |-- remoteBridgeCore.ts  # 无环境层Bridge核心（v2直连模式）
  |
  |-- 会话管理
  |     |-- sessionRunner.ts     # 子进程生命周期：spawn→监控→清理
  |     |-- createSession.ts     # 会话创建：POST /v1/sessions API
  |     |-- sessionIdCompat.ts   # 会话ID标签转换（cse_* <-> session_*）
  |
  |-- 通信传输
  |     |-- replBridgeTransport.ts  # 传输层抽象：v1(WebSocket) / v2(SSE+CCR)
  |     |-- bridgeMessaging.ts      # 消息路由：入站解析、类型守卫、去重
  |     |-- inboundMessages.ts      # 入站消息处理：附件解析
  |     |-- inboundAttachments.ts   # 附件下载与转换
  |     |-- flushGate.ts            # 初始消息刷新状态机
  |
  |-- API 客户端
  |     |-- bridgeApi.ts         # 环境API封装：注册/轮询/确认/停止/心跳
  |     |-- codeSessionApi.ts    # 会话API封装（v2直连模式）
  |     |-- workSecret.ts        # 工作密钥解码、SDK URL构建、Worker注册
  |
  |-- 认证安全
  |     |-- jwtUtils.ts          # JWT解码与令牌刷新调度器
  |     |-- trustedDevice.ts     # 可信设备注册与令牌管理
  |     |-- bridgeConfig.ts      # Bridge配置读取（OAuth令牌、API地址）
  |
  |-- 容错与配置
  |     |-- pollConfig.ts        # 轮询间隔配置（GrowthBook动态调参）
  |     |-- pollConfigDefaults.ts # 轮询间隔默认值
  |     |-- capacityWake.ts      # 容量唤醒信号（会话结束→立即轮询）
  |     |-- bridgeEnabled.ts     # 特性门控（订阅检查、GrowthBook开关）
  |
  |-- 类型定义
  |     |-- types.ts             # 核心类型：BridgeConfig, SessionHandle, WorkResponse...
  |     |-- bridgePermissionCallbacks.ts  # 权限回调类型定义
  |
  |-- 辅助工具
        |-- bridgeUI.ts          # 状态显示：Banner、会话进度、QR码
        |-- bridgeStatusUtil.ts  # 状态格式化工具
        |-- bridgePointer.ts     # 崩溃恢复指针（持久化环境/会话ID）
        |-- bridgeDebug.ts       # 调试故障注入（ant用户专用）
        |-- debugUtils.ts        # 调试日志工具
        |-- envLessBridgeConfig.ts  # 无环境层配置（v2模式）

12.2.2 bridgeMain.ts：独立 Bridge 的主循环

bridgeMain.ts 是独立 Bridge 模式的核心，其主函数 runBridgeLoop 实现了一个完整的服务器长轮询循环。这个文件超过 1600 行，是整个 Bridge 子系统中最大的单一文件。它的宏观结构如下：