# 第一阶段 · 模块一 · 第八节：Bridge 桥接系统
什么是 Bridge 系统？Claude Code 如何实现远程控制和设备桥接？Bridge 的通信机制是什么？如何确保 Bridge 通信的安全性？
Claude Code 全局架构
┌─────────────────────────────────────────────────────────────────────┐
│ 桥接层（bridge/） │
│ │
│ Bridge 桥接系统 ← 本节 │
│ ├── 远程控制 │
│ ├── 设备桥接 │
│ └── 安全通信 │
└─────────────────────────────────────────────────────────────────────┘
源码位置：`src/bridge/`
Bridge 是 Claude Code 的桥接系统，用于实现远程控制、设备连接和跨进程通信。它允许 Claude Code 与外部设备、服务进行安全通信。
┌─────────────────────────────────────────────────────────────────────┐
│ Bridge 桥接系统 │
│ │
│ ┌──────────────┐ Bridge ┌──────────────┐ │
│ │ Claude │◄───────────────►│ Remote │ │
│ │ Code CLI │ │ Device │ │
│ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
源码位置：`src/bridge/`
// Bridge 模块文件
bridgeMain.ts // 主桥接逻辑
bridgeApi.ts // Bridge API
bridgeConfig.ts // 配置
bridgeMessaging.ts // 消息传递
bridgeUI.ts // UI 组件
initReplBridge.ts // 初始化
replBridge.ts // REPL 桥接
┌─────────────────────────────────────────────────────────────────────┐
│ Bridge vs MCP │
│ │
│ Bridge（桥接） │
│ - 用于 Claude Code 与外部设备的连接 │
│ - 远程控制、设备管理 │
│ - 跨进程/跨网络通信 │
│ │
│ MCP（Model Context Protocol） │
│ - 用于扩展 Claude 的工具能力 │
│ - 工具注册、调用 │
│ - 本地服务集成 │
└─────────────────────────────────────────────────────────────────────┘
问 1：Bridge 和普通 API 调用有什么区别？
// 普通 API 调用：
// - 同步请求-响应模式
// - 无状态
// - 需要处理超时、重试
// Bridge：
// - 持久化连接
// - 支持双向通信
// - 实时消息推送
// - 会话状态管理
源码位置：`src/bridge/bridgeConfig.ts`
// Bridge 配置
export interface BridgeConfig {
enabled: boolean // 是否启用
host: string // 主机地址
port: number // 端口
protocol: 'http' | 'https' | 'ws' | 'wss' // 传输协议
auth?: {
type: 'jwt' | 'apiKey' // 认证类型
token?: string // 认证令牌
}
}
源码位置：`src/bridge/envLessBridgeConfig.ts`
// 无环境变量的桥接配置
// 用于安全的环境（如沙箱）
export function getEnvLessBridgeConfig(): BridgeConfig {
return {
enabled: true,
host: 'localhost',
port: 8080,
protocol: 'ws'
}
}
配置加载流程：
1. 读取配置文件（bridge.json）
↓
2. 合并环境变量覆盖
↓
3. 验证配置合法性
↓
4. 初始化 Bridge 实例
问 1：为什么需要无环境变量配置？
// 原因：
// 1. 安全性
// - 避免敏感信息泄露
// - 沙箱环境中禁止环境变量
// 2. 简化部署
// - 容器化部署更简单
// - 配置集中管理
// 3. 测试友好
// - 测试环境隔离
// - 更容易模拟
源码位置：`src/bridge/bridgeMessaging.ts`
// Bridge 消息类型
type BridgeMessage =
| { type: 'exec'; command: string } // 执行命令
| { type: 'result'; data: unknown } // 返回结果
| { type: 'error'; error: string } // 错误信息
| { type: 'event'; event: string } // 事件通知
源码位置：`src/bridge/bridgeMessaging.ts`
// 消息队列
class MessageQueue {
private queue: BridgeMessage[] = []
enqueue(msg: BridgeMessage): void {
this.queue.push(msg)
}
dequeue(): BridgeMessage | undefined {
return this.queue.shift()
}
size(): number {
return this.queue.length
}
}
源码位置：`src/bridge/replBridgeTransport.ts`
传输层支持：
┌─────────────────────────────────────────────────────────────────────┐
│ 传输协议 │
│ │
│ WebSocket (ws/wss) │
│ - 实时双向通信 │
│ - 低延迟 │
│ │
│ HTTP 长轮询 │
│ - 兼容防火墙 │
│ - 实现简单 │
│ │
│ stdio (本地进程) │
│ - 父子进程通信 │
│ - 最高性能 │
└─────────────────────────────────────────────────────────────────────┘
问 1：消息队列有什么用？
// 消息队列的作用：
// 1. 削峰填谷
// - 避免消息丢失
// - 处理突发流量
// 2. 顺序保证
// - FIFO 顺序处理
// - 避免乱序
// 3. 可靠性
// - 支持消息持久化
// - 重试机制
源码位置：`src/bridge/remoteBridgeCore.ts`
// 远程桥接核心
export class RemoteBridgeCore {
// 建立远程连接
async connect(config: BridgeConfig): Promise<void> {
// 1. 验证配置
// 2. 建立连接
// 3. 交换密钥
// 4. 启动心跳
}
// 发送消息
async send(msg: BridgeMessage): Promise<void> {
// 1. 序列化消息
// 2. 加密传输
// 3. 发送
}
// 接收消息
onMessage(handler: (msg: BridgeMessage) => void): void {
// 注册消息处理器
}
// 断开连接
disconnect(): void {
// 1. 停止心跳
// 2. 关闭连接
// 3. 清理资源
}
}
源码位置：`src/bridge/sessionRunner.ts`
// 会话运行器
// 管理远程会话的生命周期
export class SessionRunner {
// 创建新会话
async createSession(config: SessionConfig): Promise<Session>
// 恢复会话
async resumeSession(sessionId: string): Promise<Session>
// 迁移会话
async migrateSession(sessionId: string, target: string): Promise<void>
// 销毁会话
async destroySession(sessionId: string): Promise<void>
}
连接建立流程：
┌─────────────────────────────────────────────────────────────────────┐
│ 1. 握手请求 │
│ Client → Server: { type: 'handshake', version: '1.0' } │
│ │
│ 2. 握手响应 │
│ Server → Client: { type: 'handshake', status: 'ok', token } │
│ │
│ 3. 认证 │
│ Client → Server: { type: 'auth', token: '...' } │
│ │
│ 4. 心跳 │
│ Client ↔ Server: { type: 'ping' } / { type: 'pong' } │
└─────────────────────────────────────────────────────────────────────┘
问 1：如何处理网络中断？
// 网络中断处理：
// 1. 心跳检测
// - 定期 ping/pong
// - 超时判定断开
// 2. 自动重连
// - 指数退避重连
// - 最大重试次数
// 3. 状态同步
// - 缓存未发送消息
// - 重连后继续发送
源码位置：`src/bridge/jwtUtils.ts`
// JWT 工具
export function signToken(payload: object): string {
// 1. 签名
// 2. 返回 token
}
export function verifyToken(token: string): object {
// 1. 验证签名
// 2. 解析 payload
}
export function isTokenExpired(token: string): boolean {
// 1. 解析 token
// 2. 检查 exp 字段
}
源码位置：`src/bridge/trustedDevice.ts`
// 信任设备管理
// 首次连接需要确认
// 后续连接自动信任
export class TrustedDeviceManager {
// 添加信任设备
addTrustedDevice(deviceId: string, publicKey: string): void
// 检查设备是否信任
isTrusted(deviceId: string): boolean
// 移除信任设备
removeTrustedDevice(deviceId: string): void
}
┌─────────────────────────────────────────────────────────────────────┐
│ Bridge 安全特性 │
│ │
│ 1. 传输加密 │
│ - TLS/SSL 加密 │
│ - WebSocket over WSS │
│ │
│ 2. 认证授权 │
│ - JWT token │
│ - API Key │
│ │
│ 3. 设备信任 │
│ - 首次确认机制 │
│ - 公钥存储 │
│ │
│ 4. 消息签名 │
│ - HMAC 签名 │
│ - 防篡改 │
└─────────────────────────────────────────────────────────────────────┘
问 1：为什么需要信任设备机制？
// 原因：
// 1. 避免重复认证
// - 首次认证后自动信任
// - 用户体验更好
// 2. 安全与便利平衡
// - 固定设备简化操作
// - 仍保留撤销能力
// 3. 审计追踪
// - 记录信任设备列表
// - 审计连接来源
// 场景：通过 Bridge 连接远程开发服务器
const bridge = new RemoteBridgeCore()
await bridge.connect({
host: 'dev-server.example.com',
port: 8080,
protocol: 'wss',
auth: { type: 'jwt', token: '...' }
})
// 执行远程命令
const result = await bridge.send({
type: 'exec',
command: 'ls -la'
})
// 场景：控制远程设备（如 Raspberry Pi）
const deviceBridge = await bridge.connect({
host: 'pi.local',
port: 8080,
protocol: 'ws'
})
// 发送控制指令
await deviceBridge.send({
type: 'exec',
command: 'gpio write 17 1'
})
答案：
// 区别：
// Bridge（桥接系统）
// - 用途：Claude Code 与外部设备的连接
// - 场景：远程控制、设备管理、跨网络通信
// - 特点：持久连接、双向通信、会话管理
// MCP（Model Context Protocol）
// - 用途：扩展 Claude 的工具能力
// - 场景：工具注册、调用、本地服务集成
// - 特点：工具抽象、协议标准化、本地集成
// 总结：Bridge 偏向「连接」，MCP 偏向「扩展」
答案：
// 支持的协议：
// 1. WebSocket (ws/wss)
// - 实时双向通信
// - 低延迟
// - 支持代理
// 2. HTTP/HTTPS
// - 长轮询实现
// - 更好的兼容性
// - 易于穿透防火墙
// 3. stdio
// - 父子进程通信
// - 最高性能
// - 适合本地集成
答案：
// 调试方法：
// 1. 启用调试日志
// BRIDGE_DEBUG=1 claaude
// 2. 使用调试工具
// src/bridge/bridgeDebug.ts
// 3. 检查连接状态
// bridge.status()
// 4. 查看消息历史
// bridge.getMessageHistory()
| 资源 | 说明 |
| `src/bridge/remoteBridgeCore.ts` | 远程桥接核心 |
| `src/bridge/bridgeMessaging.ts` | 消息传递机制 |
| `src/bridge/jwtUtils.ts` | JWT 认证工具 |
| `src/bridge/trustedDevice.ts` | 信任设备管理 |
下一节我们将进入 Voice Mode 语音模式：
- 语音输入与 STT
- 语音合成 TTS
- 实时语音对话
*- 第一轮：□ 事实准确性*
*- 第二轮：□ 深度与洞见*
*- 第三轮：□ 可读性与价值*