cs-note/claude-code-best/docs/features/bridge-mode.md

---
tags: [bridge, remote-control, claude-ai, oauth, 长轮询]
create time: 2026-06-09 22:30
---

# BRIDGE_MODE — 远程控制

## 概述

BRIDGE_MODE 将本地 CLI 注册为"bridge 环境"，可从 claude.ai 或其他控制面远程驱动。本地终端变为一个"执行者"，接受远程指令并执行。支持 v1（env-based）和 v2（env-less）两种实现。

> [!info]
> Feature Flag: `FEATURE_BRIDGE_MODE=1`
> 实现状态：完整可用（v1 + v2 实现）
> 引用数：28

## 正文

### 核心特性

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

### 实现架构

#### 版本演进

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

#### 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` | 重连已存在的会话 |

#### 认证流程

```mermaid
graph TD
    A["注册: OAuth Bearer Token"] --> B["获取 environment_secret"]
    B --> C["轮询: environment_secret 作为 Authorization"]
    C --> D{"401?"}
    D -->|"是"| E["尝试 OAuth token 刷新 onAuth401"]
    E --> F["刷新成功 → 重试一次"]
    D -->|"否"| G["正常处理"]
```

> [!tip]
> **OAuth 刷新**：API client 内置 `withOAuthRetry` 机制。401 时调用 `handleOAuth401Error`，刷新后重试一次。

#### 安全设计

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

#### 数据流

```mermaid
sequenceDiagram
    participant User as claude.ai 用户
    participant CLI as Claude Code CLI
    participant API as Bridge API
    User->>CLI: 选择远程环境
    CLI->>API: POST /v1/environments/bridge 注册
    API-->>CLI: environment_id + environment_secret
    loop 长轮询
        CLI->>API: GET .../work/poll (10s超时)
        API-->>CLI: WorkResponse { id, data: { type, sessionId } }
    end
    CLI->>API: POST .../work/{id}/ack 确认
    CLI->>CLI: sessionRunner 创建 REPL session
    Note over CLI,API: 权限请求 → sendPermissionResponseEvent
    Note over CLI,API: 心跳 → heartbeatWork 续约
    Note over CLI,API: 任务完成 → 自动归档
```

#### 模块结构

| 模块 | 文件 | 职责 |
|------|------|------|
| 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 上审批

### 使用方式

```bash
# 启用 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` | — | 调试工具 |

## 关联笔记

- [[remote-control-self-hosting]]
- [[daemon]]
- [[acp-link]]
- [[all-features-guide]]