Appearance
12 — Bridge / Remote
概述
Claude Code 不仅在终端中运行——它还可以与 IDE（VS Code、JetBrains）和 Web 界面（claude.ai）双向通信。这种通信通过 Bridge 系统实现。
Bridge 解决的核心问题是：如何让一个运行在终端中的 CLI 工具与 GUI 应用实时交互？
- IDE 扩展可以发送文件、选区、指令给 Claude Code
- Claude Code 可以在 IDE 中打开 Diff 视图、跳转到代码位置
- 权限确认可以在 IDE 侧边栏或 claude.ai 网页上完成
- 远程会话允许从任何设备控制 Claude Code
架构总览
Bridge 系统 (src/bridge/)
Bridge 是 双向通信通道，连接 CLI 和 IDE 扩展。
通信协议
Bridge 使用 JSON-RPC over 本地 Socket 通信。IDE 扩展和 CLI 各自有一端：
核心文件
| 文件 | 说明 | 与其他模块的关系 |
|---|---|---|
bridgeMain.ts | Bridge 主入口 | Feature Flag: BRIDGE_MODE |
bridgeApi.ts | Bridge HTTP/RPC API | 处理来自 IDE 的请求 |
bridgeMessaging.ts | 消息收发 | 双向消息队列 |
bridgePermissionCallbacks.ts | 权限回调 | 与权限系统的四方竞速集成 |
bridgeConfig.ts | 配置管理 | Socket 路径、端口等 |
replBridge.ts | REPL 集成 | 将 Bridge 消息转为 REPL 事件 |
initReplBridge.ts | 初始化 | 启动时建立连接 |
bridgeEnabled.ts | 启用判断 | 检查 IDE 是否在运行 |
bridgePointer.ts | 定位信息 | IDE 光标位置、选区 |
bridgeStatusUtil.ts | 状态工具 | 连接状态检查 |
sessionRunner.ts | 会话运行器 | 管理 Bridge 会话生命周期 |
inboundMessages.ts | 入站消息处理 | 解析 IDE 发来的消息 |
inboundAttachments.ts | 入站附件 | 处理 IDE 发来的文件/图片 |
pollConfig.ts | 配置轮询 | 定期同步 Bridge 配置 |
capacityWake.ts | 容量唤醒 | 从 idle 状态唤醒 |
jwtUtils.ts | JWT 工具 | 认证 token 管理 |
workSecret.ts | 工作密钥 | Bridge 通信加密 |
trustedDevice.ts | 可信设备 | 设备信任管理 |
flushGate.ts | 刷新门控 | 确保消息按序发送 |
Bridge 与权限系统
Bridge 是权限系统 四方竞速 的重要参与者。当工具需要权限确认时，Bridge 将请求同时发送给 IDE 侧边栏和终端弹窗。用户可以在任一端确认：
Remote 系统 (src/remote/)
Remote Session 允许通过 WebSocket 从远程控制 Claude Code。主要场景：
- claude.ai 网页端控制本地 CLI
- SSH 连接到远程服务器上的 Claude Code
Remote Session 架构
| 文件 | 说明 |
|---|---|
RemoteSessionManager.ts | 远程会话管理器 |
SessionsWebSocket.ts | WebSocket 连接管理 |
sdkMessageAdapter.ts | SDK 消息格式适配器（将内部消息转为 SDK 格式） |
remotePermissionBridge.ts | 远程权限桥（权限请求通过 WebSocket 转发） |
Server (src/server/)
Direct Connect Server 允许 IDE 扩展直接连接到 Claude Code（不经过 Anthropic 服务器）：
| 文件 | 说明 |
|---|---|
directConnectManager.ts | 直连管理器（本地 HTTP 服务器） |
createDirectConnectSession.ts | 创建直连会话 |
types.ts | 类型定义 |
Direct Connect 比 Bridge 更简单——它是一个本地 HTTP 服务器，IDE 扩展直接发送 HTTP 请求，无需 Socket 连接管理。
CLI IO (src/cli/)
CLI IO 模块处理 非交互模式 的输入输出。当 Claude Code 以 --print 模式运行时，不启动 REPL，而是通过这些模块处理 IO。
| 文件 | 说明 | 使用场景 |
|---|---|---|
print.ts | Print 模式输出 | claude --print "..." |
structuredIO.ts | 结构化 IO (JSON NDJSON) | SDK 集成、管道操作 |
remoteIO.ts | 远程 IO | Remote Session 的 IO 适配 |
exit.ts | 退出处理 | 清理资源后退出 |
update.ts | 自动更新检查 | 启动时检查新版本 |
Transports
Transport 层抽象了消息传输方式，支持多种协议：
| 文件 | 说明 |
|---|---|
transports/HybridTransport.ts | 混合传输（自动选择最佳协议） |
transports/SSETransport.ts | SSE (Server-Sent Events) 传输 |
transports/WebSocketTransport.ts | WebSocket 传输 |
transports/ccrClient.ts | CCR (claude.ai) 客户端 |
transports/SerialBatchEventUploader.ts | 批量事件上传 |
transports/WorkerStateUploader.ts | Worker 状态上传 |
Upstream Proxy (src/upstreamproxy/)
| 文件 | 说明 |
|---|---|
upstreamproxy.ts | 上游代理服务器 |
relay.ts | 请求转发 |
用于企业环境中需要通过代理服务器访问 Anthropic API 的场景。