claude-code/docs/features/bridge-mode.md

BRIDGE_MODE — 远程控制

Feature Flag: FEATURE_BRIDGE_MODE=1 实现状态：完整可用（v1 + v2 实现） 引用数：28

一、功能概述

BRIDGE_MODE 将本地 CLI 注册为"bridge 环境"，可从 claude.ai 或其他控制面远程驱动。本地终端变为一个"执行者"，接受远程指令并执行。

核心特性

• 环境注册：本地 CLI 向 Anthropic 服务器注册为可用的 bridge 环境
• 工作轮询：长轮询（long-poll）等待远程任务分配
• 会话管理：创建、恢复、归档远程会话
• 权限透传：远程权限请求发送到控制面，用户在 claude.ai 上批准/拒绝
• 心跳保活：定期发送 heartbeat 延长任务租约
• 可信设备：v2 支持可信设备令牌增强安全性

二、实现架构

2.1 版本演进

版本	实现	特点
v1（env-based）	src/bridge/replBridge.ts	基于环境变量的传统 bridge
v2（env-less）	src/bridge/remoteBridgeCore.ts	无需环境变量，更安全的 bridge

2.2 API 协议

文件：src/bridge/bridgeApi.ts

Bridge API Client 提供 9 个核心操作：

操作	HTTP	说明
registerBridgeEnvironment	POST /v1/environments/bridge	注册本地环境，获取 environment_id + environment_secret
pollForWork	GET /v1/environments/{id}/work/poll	长轮询等待任务（10s 超时）
acknowledgeWork	POST /v1/environments/{id}/work/{workId}/ack	确认接收任务
stopWork	POST /v1/environments/{id}/work/{workId}/stop	停止任务
heartbeatWork	POST /v1/environments/{id}/work/{workId}/heartbeat	续约任务租约
deregisterEnvironment	DELETE /v1/environments/bridge/{id}	注销环境
archiveSession	POST /v1/sessions/{id}/archive	归档会话（409 = 已归档，幂等）
sendPermissionResponseEvent	POST /v1/sessions/{id}/events	发送权限审批结果
reconnectSession	POST /v1/environments/{id}/bridge/reconnect	重连已存在的会话

2.3 认证流程

注册: OAuth Bearer Token → 获取 environment_secret
轮询: environment_secret 作为 Authorization
  ├── 401 → 尝试 OAuth token 刷新（onAuth401）
  └── 刷新成功 → 重试一次

OAuth 刷新：API client 内置 withOAuthRetry 机制。401 时调用 handleOAuth401Error（同 withRetry.ts 的 v1/messages 模式），刷新后重试一次。

2.4 安全设计

• 路径穿越防护：validateBridgeId() 使用 /^[a-zA-Z0-9_-]+$/ 白名单验证所有服务端 ID
• BridgeFatalError：不可重试的错误（401/403/404/410）直接抛出，阻止重试循环
• 可信设备令牌：v2 通过 X-Trusted-Device-Token header 增强安全层级
• 幂关注册：支持 reuseEnvironmentId 实现会话恢复，避免重复创建环境

2.5 数据流

claude.ai 用户选择远程环境
         │
         ▼
POST /v1/environments/bridge (注册)
         │
         ◀── environment_id + environment_secret
         │
         ▼
GET .../work/poll (长轮询)
         │
         ◀── WorkResponse { id, data: { type, sessionId } }
         │
         ▼
POST .../work/{id}/ack (确认)
         │
         ▼
sessionRunner 创建 REPL session
         │
         ├── 权限请求 → sendPermissionResponseEvent
         ├── 心跳 → heartbeatWork (续约)
         └── 任务完成 → 自动归档

2.6 模块结构

模块	文件	职责
API Client	bridgeApi.ts	HTTP 通信（注册/轮询/确认/心跳/注销）
Session Runner	sessionRunner.ts	创建/恢复 REPL 会话
Bridge Config	bridgeConfig.ts	配置管理（machine name、max sessions 等）
Transport	replBridgeTransport.ts	Bridge 传输层
Permission Callbacks	bridgePermissionCallbacks.ts	权限请求处理
Pointer	bridgePointer.ts	当前活跃 bridge 状态指针
Flush Gate	flushGate.ts	刷新控制
JWT Utils	jwtUtils.ts	JWT 令牌工具
Trusted Device	trustedDevice.ts	可信设备管理
Debug Utils	debugUtils.ts	调试日志
Types	types.ts	类型定义

三、关键设计决策

1. 长轮询而非 WebSocket：pollForWork 使用 HTTP GET + 10s 超时。简单可靠，无需维护 WebSocket 连接
2. OAuth 刷新内嵌：API client 自带 withOAuthRetry，无需外层重试逻辑
3. ETag 条件请求：注册时支持 reuseEnvironmentId 实现幂等会话恢复
4. v1/v2 共存：代码中同时存在两套实现，v2 是更安全的升级版
5. 权限双向流动：本地权限请求发送到 claude.ai，用户在 web 上审批

四、使用方式

# 启用 bridge mode
FEATURE_BRIDGE_MODE=1 bun run dev

# 从 claude.ai/code 远程连接
# 在 web 界面选择已注册的环境

# 配合 DAEMON 使用（后台守护）
FEATURE_BRIDGE_MODE=1 FEATURE_DAEMON=1 bun run dev

五、外部依赖

依赖	说明
Anthropic OAuth	claude.ai 订阅登录
GrowthBook	tengu_ccr_bridge 门控
Bridge API	/v1/environments/bridge 系列端点

六、文件索引

文件	行数	职责
src/bridge/bridgeApi.ts	541	API Client（核心）
src/bridge/sessionRunner.ts	—	会话运行器
src/bridge/bridgeConfig.ts	—	配置管理
src/bridge/replBridgeTransport.ts	—	传输层
src/bridge/bridgePermissionCallbacks.ts	—	权限回调
src/bridge/bridgePointer.ts	—	状态指针
src/bridge/flushGate.ts	—	刷新控制
src/bridge/jwtUtils.ts	—	JWT 工具
src/bridge/trustedDevice.ts	—	可信设备
src/bridge/remoteBridgeCore.ts	—	v2 核心实现
src/bridge/types.ts	—	类型定义
src/bridge/debugUtils.ts	—	调试工具
src/bridge/pollConfigDefaults.ts	—	轮询配置默认值
src/bridge/bridgeUI.ts	—	UI 组件
src/bridge/codeSessionApi.ts	—	代码会话 API
src/bridge/peerSessions.ts	—	对等会话管理
src/bridge/sessionIdCompat.ts	—	Session ID 兼容层
src/bridge/createSession.ts	—	会话创建
src/bridge/replBridgeHandle.ts	—	Bridge 句柄