Chapter 13

Bridge / 远程控制

Bridge 模式让 Claude Code 可以作为远程会话的工作节点运行 — 支持多会话管理、JWT 认证、Worktree 隔离。由 BRIDGE_MODE feature flag 控制。

概览

源文件

2999

bridgeMain.ts 行

默认并发会话

Bridge 通过 CLI 快速路径进入（claude remote-control / claude rc / claude bridge），在完整 CLI 加载之前就被拦截处理。

核心架构

入口

bridgeMain.ts (2999 行)

多会话 Spawn 管理 + 状态更新循环

↓

协议

replBridge.ts

2406 行, REPL 协议

↓

无环境模式

remoteBridgeCore.ts

直接 OAuth→JWT

↓

API 层

bridgeApi.ts

HTTP + 重试 + 401

关键文件

文件	行数	��责
bridgeMain.ts	2999	多会话 Spawn 管理、状态更新循环、Worktree 支持
replBridge.ts	2406	REPL↔Bridge 协议、消息序列化、容量唤醒信号
remoteBridgeCore.ts	~500	无环境 Bridge — 直接 OAuth→worker_jwt 交换
bridgeApi.ts	~300	Environments API HTTP 客户端 + 重试
bridgeMessaging.ts	~200	消息入站、控制请求、结果序列化
initReplBridge.ts	~200	REPL Bridge 启动、状态读取、Gate 检查
types.ts	~150	SpawnMode, BridgeConfig, WorkData, SessionDoneStatus
jwtUtils.ts	~100	Token 刷新调度、主动续期
trustedDevice.ts	~80	可信设备 Token 管理

认证机制

Bridge 使用 JWT 进行会话认证，支持自动刷新：

OAuth 认证

用户通过 OAuth 登录获取 access token。

JWT 交换

remoteBridgeCore 通过 /v1/code/sessions/{id}/bridge 将 OAuth token 交换为 worker JWT。

自动刷新

jwtUtils 调度器在 JWT 过期前主动刷新（proactive renewal），支持 401/403 时重新获取。

可信设备

trustedDevice.ts 管理可信设备 token，用于提升认证级别。

多会话管理

Bridge 支持同时管理多个远程会话：

默认 32 并发 — 可配置的最大并发会话数
会话超时 — 默认 24 小时，watchdog 定时器监控
状态更新 — 1 秒间隔的状态更新循环，实时 UI 显示
容量唤醒 — 会话完成时发送 capacity wake 信号，立即调度新会话
退避重试 — Spawn 失败时指数退避

Spawn 模式

single-session

单会话模式，一次运行一个远程会话。最简单的模式。

worktree

每个会话在独立的 Git Worktree 中运行。支持并行修改不同分支。

same-dir

所有会话共享同一工作目录。适合只读或互不冲突的任务。

AppState 集成

Bridge 在 AppState 中维护 10+ 个状态字段：

// AppState 中的 Bridge 相关字段
{
  replBridgeEnabled: boolean,        // Bridge 是否启用
  replBridgeConnected: boolean,      // 连接状态
  replBridgeSessionActive: boolean,  // 会话是否活跃
  replBridgeConnectUrl: string,      // 连接 URL
  replBridgeSessionUrl: string,      // 会话 URL
  replBridgeError: string,           // 错误信息
  replBridgeReconnecting: boolean,   // 重连中
  // ... 更多字段
}

Daemon 模式 (Stub)

src/daemon/ — 长驻 supervisor 进程。目前仅 2 个 stub 文件 (Promise.resolve())。由 DAEMON flag 控制。

Background Sessions

BG_SESSIONS flag 启用后台会话管理命令：claude ps、claude logs、claude attach、claude kill。