# Claude Code 桥接系统详解

## 概述

桥接系统（Bridge）是 Claude Code CLI 与 IDE 扩展（VS Code, JetBrains）之间的双向通信层。它使 IDE 能够：
1. 在远程设备上启动 Claude Code 会话
2. 将用户输入转发到 Claude Code
3. 显示 Claude Code 的输出和工具执行结果
4. 处理权限请求和响应

---

## 核心架构

```
┌──────────────────────────────────────────────────────────────┐
│                     IDE Extension (VS Code / JetBrains)     │
│  - 用户界面                                                  │
│  - 输入处理                                                  │
│  - 输出展示                                                  │
└──────────────────────────────────────────────────────────────┘
                              │
                              │ WebSocket / HTTP
                              ▼
┌──────────────────────────────────────────────────────────────┐
│                     Bridge Layer                             │
│                                                              │
│  ┌────────────────────────────────────────────────────────┐  │
│  │                   bridgeMain.ts                        │  │
│  │  入口点，管理桥接生命周期                              │  │
│  └────────────────────────────────────────────────────────┘  │
│                                                              │
│  ┌────────────────────────────────────────────────────────┐  │
│  │                bridgeMessaging.ts                      │  │
│  │  消息处理、入口路由、流量控制                          │  │
│  └────────────────────────────────────────────────────────┘  │
│                                                              │
│  ┌────────────────────────────────────────────────────────┐  │
│  │                replBridge.ts                            │  │
│  │  REPL 会话桥接                                         │  │
│  └────────────────────────────────────────────────────────┘  │
│                                                              │
│  ┌────────────────────────────────────────────────────────┐  │
│  │                sessionRunner.ts                         │  │
│  │  会话执行管理                                          │  │
│  └────────────────────────────────────────────────────────┘  │
│                                                              │
│  ┌────────────────────────────────────────────────────────┐  │
│  │                jwtUtils.ts                              │  │
│  │  JWT 认证工具                                         │  │
│  └────────────────────────────────────────────────────────┘  │
│                                                              │
│  ┌────────────────────────────────────────────────────────┐  │
│  │           bridgePermissionCallbacks.ts                   │  │
│  │  权限回调处理                                          │  │
│  └────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌──────────────────────────────────────────────────────────────┐
│                   Claude Code CLI (子进程)                  │
│  - 命令处理                                                │
│  - 工具执行                                                │
│  - API 调用                                                │
└──────────────────────────────────────────────────────────────┘
```

---

## 1. bridgeMain.ts - 桥接主入口

**文件位置**: `src/bridge/bridgeMain.ts`

### 核心类型

```typescript
export type BridgeState = 'ready' | 'connected' | 'reconnecting' | 'failed'

export type ReplBridgeHandle = {
  bridgeSessionId: string
  environmentId: string
  sessionIngressUrl: string
  writeMessages(messages: Message[]): void
  writeSdkMessages(messages: SDKMessage[]): void
  sendControlRequest(request: SDKControlRequest): void
  sendControlResponse(response: SDKControlResponse): void
  sendControlCancelRequest(requestId: string): void
  sendResult(): void
  teardown(): Promise<void>
}
```

### 核心函数

```typescript
export async function initBridgeCore(
  params: BridgeCoreParams
): Promise<BridgeCoreHandle | null>
```

**BridgeCoreParams 输入参数**:

```typescript
type BridgeCoreParams = {
  dir: string                    // 工作目录
  machineName: string            // 机器名称
  branch: string                 // Git 分支
  gitRepoUrl: string | null      // Git 仓库 URL
  title: string                  // 会话标题
  baseUrl: string                // API 基础 URL
  sessionIngressUrl: string      // 会话入口 URL
  workerType: string            // 工作器类型
  getAccessToken: () => string | undefined
  createSession: (opts: {...}) => Promise<string | null>
  archiveSession: (sessionId: string) => Promise<void>
  toSDKMessages?: (messages: Message[]) => SDKMessage[]
  onAuth401?: (staleAccessToken: string) => Promise<boolean>
  getPollIntervalConfig?: () => PollIntervalConfig
  initialMessages?: Message[]
  previouslyFlushedUUIDs?: Set<string>
  onInboundMessage?: (msg: SDKMessage) => void
  onPermissionResponse?: (response: SDKControlResponse) => void
  onInterrupt?: () => void
  onSetModel?: (model: string | undefined) => void
  onSetMaxThinkingTokens?: (maxTokens: number | null) => void
  onSetPermissionMode?: (mode: PermissionMode) => {...}
  onStateChange?: (state: BridgeState, detail?: string) => void
  onUserMessage?: (text: string, sessionId: string) => boolean
  perpetual?: boolean
  initialSSESequenceNum?: number
}
```

### 桥接生命周期

1. **注册桥接环境**
   ```typescript
   const reg = await api.registerBridgeEnvironment(bridgeConfig)
   environmentId = reg.environment_id
   environmentSecret = reg.environment_secret
   ```

2. **创建会话**
   ```typescript
   const createdSessionId = await createSession({...})
   currentSessionId = createdSessionId
   ```

3. **启动工作轮询循环**
   ```typescript
   void startWorkPollLoop(pollOpts)
   ```

4. **处理入口消息**
   ```typescript
   transport.onData(data => {
     handleIngressMessage(data, recentPostedUUIDs, recentInboundUUIDs, ...)
   })
   ```

5. **清理**
   ```typescript
   await doTeardownImpl()
   ```

---

## 2. bridgeMessaging.ts - 消息处理

**文件位置**: `src/bridge/bridgeMessaging.ts`

### 消息入口处理

```typescript
export function handleIngressMessage(
  data: string,
  recentPostedUUIDs: BoundedUUIDSet,
  recentInboundUUIDs: BoundedUUIDSet,
  onInboundMessage: ((msg: SDKMessage) => void | Promise<void>) | undefined,
  onPermissionResponse?: ((response: SDKControlResponse) => void) | undefined,
  onControlRequest?: ((request: SDKControlRequest) => void) | undefined,
): void
```

**消息类型判断**:

```typescript
export function isSDKMessage(value: unknown): value is SDKMessage
export function isSDKControlResponse(value: unknown): value is SDKControlResponse
export function isSDKControlRequest(value: unknown): value is SDKControlRequest
```

### 可桥接消息过滤

```typescript
export function isEligibleBridgeMessage(m: Message): boolean {
  // 排除虚拟消息
  if ((m.type === 'user' || m.type === 'assistant') && m.isVirtual) {
    return false
  }
  return (
    m.type === 'user' ||
    m.type === 'assistant' ||
    (m.type === 'system' && m.subtype === 'local_command')
  )
}
```

### 服务器控制请求处理

```typescript
export function handleServerControlRequest(
  request: SDKControlRequest,
  handlers: ServerControlRequestHandlers,
): void
```

**支持的请求类型**:
- `initialize` - 初始化
- `set_model` - 设置模型
- `set_max_thinking_tokens` - 设置最大思考 token
- `set_permission_mode` - 设置权限模式
- `interrupt` - 中断

### 标题文本提取

```typescript
export function extractTitleText(m: Message): string | undefined
// 从用户消息中提取标题
```

### BoundedUUIDSet - UUID 环形缓冲区

```typescript
export class BoundedUUIDSet {
  constructor(capacity: number)
  add(uuid: string): void
  has(uuid: string): boolean
  clear(): void
}
```

**用途**:
- 消息回音过滤
- 重复消息去重

---

## 3. replBridge.ts - REPL 会话桥接

**文件位置**: `src/bridge/replBridge.ts`

### 核心接口

```typescript
export type ReplBridgeTransport = {
  setOnConnect(callback: () => void): void
  setOnData(callback: (data: string) => void): void
  setOnClose(callback: (code: number | undefined) => void): void
  connect(): void
  write(message: object): Promise<void>
  writeBatch(messages: object[]): Promise<void>
  close(): void
  getStateLabel(): string
  getLastSequenceNum(): number
  isConnectedStatus(): boolean
}
```

### 传输类型

#### 1. HybridTransport (v1)
- WebSocket 读取
- HTTP POST 写入
- 目标: Session-Ingress

#### 2. SSETransport (v2)
- Server-Sent Events 读取
- HTTP POST 写入
- 目标: CCR (/worker/*)

### 初始化流程

```typescript
export async function initReplBridge(
  params: InitBridgeOptions
): Promise<ReplBridgeHandle | null>
```

### 消息写入

```typescript
writeMessages(messages: Message[]) {
  // 过滤可桥接消息
  const filtered = messages.filter(m =>
    isEligibleBridgeMessage(m) &&
    !initialMessageUUIDs.has(m.uuid) &&
    !recentPostedUUIDs.has(m.uuid)
  )

  // 转换并发送
  const sdkMessages = toSDKMessages(filtered)
  void transport.writeBatch(events)
}
```

---

## 4. jwtUtils.ts - JWT 认证

**文件位置**: `src/bridge/jwtUtils.ts`

### JWT 解析

```typescript
export function decodeJwtPayload(token: string): unknown | null {
  // 剥离 sk-ant-si- 前缀
  const jwt = token.startsWith('sk-ant-si-')
    ? token.slice('sk-ant-si-'.length)
    : token

  // 解析 payload (不验证签名)
  const parts = jwt.split('.')
  if (parts.length !== 3 || !parts[1]) return null
  return jsonParse(Buffer.from(parts[1], 'base64url').toString('utf8'))
}
```

### Token 刷新调度器

```typescript
export function createTokenRefreshScheduler({
  getAccessToken,
  onRefresh,
  label,
  refreshBufferMs = 5 * 60 * 1000,  // 5 分钟
}): {
  schedule: (sessionId: string, token: string) => void
  scheduleFromExpiresIn: (sessionId: string, expiresInSeconds: number) => void
  cancel: (sessionId: string) => void
  cancelAll: () => void
}
```

**刷新策略**:
- 过期前 5 分钟刷新（默认）
- 指数退避重试
- 最多 3 次连续失败

---

## 5. sessionRunner.ts - 会话执行管理

**文件位置**: `src/bridge/sessionRunner.ts`

### 核心类型

```typescript
type SessionSpawnerDeps = {
  execPath: string
  scriptArgs: string[]
  env: NodeJS.ProcessEnv
  verbose: boolean
  sandbox: boolean
  debugFile?: string
  permissionMode?: string
  onDebug: (msg: string) => void
  onActivity?: (sessionId: string, activity: SessionActivity) => void
  onPermissionRequest?: (sessionId: string, request: PermissionRequest, accessToken: string) => void
}

export function createSessionSpawner(deps: SessionSpawnerDeps): SessionSpawner
```

### 会话句柄

```typescript
export type SessionHandle = {
  sessionId: string
  done: Promise<SessionDoneStatus>
  activities: SessionActivity[]
  accessToken: string
  lastStderr: string[]
  currentActivity: SessionActivity | null
  kill(): void
  forceKill(): void
  writeStdin(data: string): void
  updateAccessToken(token: string): void
}
```

### 活动提取

```typescript
function extractActivities(
  line: string,
  sessionId: string,
  onDebug: (msg: string) => void
): SessionActivity[]
```

**活动类型**:
```typescript
type SessionActivity =
  | { type: 'tool_start'; summary: string; timestamp: number }
  | { type: 'text'; summary: string; timestamp: number }
  | { type: 'result'; summary: string; timestamp: number }
  | { type: 'error'; summary: string; timestamp: number }
```

### 子进程管理

```typescript
const child: ChildProcess = spawn(deps.execPath, args, {
  cwd: dir,
  stdio: ['pipe', 'pipe', 'pipe'],
  env,
  windowsHide: true,
})
```

**环境变量设置**:
```typescript
const env: NodeJS.ProcessEnv = {
  ...deps.env,
  CLAUDE_CODE_OAUTH_TOKEN: undefined,
  CLAUDE_CODE_ENVIRONMENT_KIND: 'bridge',
  CLAUDE_CODE_SESSION_ACCESS_TOKEN: opts.accessToken,
  CLAUDE_CODE_USE_CCR_V2: opts.useCcrV2 ? '1' : undefined,
  CLAUDE_CODE_WORKER_EPOCH: String(opts.workerEpoch),
}
```

---

## 6. bridgePermissionCallbacks.ts - 权限回调

**文件位置**: `src/bridge/bridgePermissionCallbacks.ts`

### 权限响应类型

```typescript
type BridgePermissionResponse = {
  behavior: 'allow' | 'deny'
  updatedInput?: Record<string, unknown>
  updatedPermissions?: PermissionUpdate[]
  message?: string
}
```

### 回调接口

```typescript
type BridgePermissionCallbacks = {
  sendRequest(
    requestId: string,
    toolName: string,
    input: Record<string, unknown>,
    toolUseId: string,
    description: string,
    permissionSuggestions?: PermissionUpdate[],
    blockedPath?: string
  ): void

  sendResponse(requestId: string, response: BridgePermissionResponse): void

  cancelRequest(requestId: string): void

  onResponse(
    requestId: string,
    handler: (response: BridgePermissionResponse) => void
  ): () => void  // 返回取消订阅函数
}
```

---

## 7. replBridgeHandle.ts - REPL 桥接句柄

**文件位置**: `src/bridge/replBridgeHandle.ts`

### 句柄类型

```typescript
export type ReplBridgeHandle = {
  bridgeSessionId: string
  environmentId: string
  sessionIngressUrl: string
  writeMessages(messages: Message[]): void
  writeSdkMessages(messages: SDKMessage[]): void
  sendControlRequest(request: SDKControlRequest): void
  sendControlResponse(response: SDKControlResponse): void
  sendControlCancelRequest(requestId: string): void
  sendResult(): void
  teardown(): Promise<void>
}
```

---

## 8. replBridgeTransport.ts - 传输层实现

**文件位置**: `src/bridge/replBridgeTransport.ts`

### 工厂函数

```typescript
export function createV1ReplTransport(
  transport: HybridTransport
): ReplBridgeTransport

export function createV2ReplTransport(opts: {
  sessionUrl: string
  ingressToken: string
  sessionId: string
  initialSequenceNum: number
}): Promise<ReplBridgeTransport>
```

---

## 9. 入口消息处理流程

```
IDE Extension
     │
     │ 1. 用户输入
     ▼
┌─────────────────┐
│  WS 连接        │
└─────────────────┘
     │
     ▼
┌─────────────────────────────────────────┐
│ handleIngressMessage()                   │
│                                         │
│ 1. 解析 JSON                            │
│ 2. 检查 UUID (回音/重复过滤)            │
│ 3. 分发消息类型                         │
│    - user → onInboundMessage           │
│    - control_response → onPermission   │
│    - control_request → onControlRequest │
└─────────────────────────────────────────┘
     │
     ▼
┌─────────────────────────────────────────┐
│ Claude Code CLI (子进程)                │
│                                         │
│ - 执行工具                              │
│ - AI 推理                              │
│ - 返回结果                              │
└─────────────────────────────────────────┘
     │
     ▼
┌─────────────────────────────────────────┐
│ writeMessages() / writeSdkMessages()  │
│                                         │
│ 1. 过滤消息                            │
│ 2. 转换为 SDK 格式                     │
│ 3. 通过 transport.writeBatch() 发送    │
└─────────────────────────────────────────┘
     │
     ▼
IDE Extension (WebSocket 订阅)
     │
     ▼
显示输出
```

---

## 10. 权限请求流程

```
Claude Code CLI
     │
     ▼ (can_use_tool 请求)
┌─────────────────────────────────────────┐
│ BridgePermissionCallbacks               │
│                                         │
│ sendRequest(requestId, toolName, input) │
└─────────────────────────────────────────┘
     │
     │ WebSocket / HTTP
     ▼
┌─────────────────────────────────────────┐
│ IDE Extension                          │
│                                         │
│ 显示权限对话框                          │
│ 用户允许/拒绝                           │
└─────────────────────────────────────────┘
     │
     ▼
┌─────────────────────────────────────────┐
│ sendResponse(requestId, response)      │
│                                         │
│ response: {                            │
│   behavior: 'allow' | 'deny',         │
│   updatedInput?,                       │
│   updatedPermissions?                   │
│ }                                       │
└─────────────────────────────────────────┘
     │
     ▼
onResponse() 回调
     │
     ▼
CLI 继续执行或中止
```

---

## 11. 关键配置

### 轮询配置

```typescript
const DEFAULT_POLL_CONFIG = {
  poll_interval_ms_not_at_capacity: 5000,      // 5 秒
  poll_interval_ms_at_capacity: 120000,         // 2 分钟
  reclaim_older_than_ms: 5 * 60 * 1000,       // 5 分钟
  non_exclusive_heartbeat_interval_ms: 30000,  // 30 秒
  session_keepalive_interval_v2_ms: 120000,    // 2 分钟
}
```

### 重连策略

```typescript
const MAX_RECONNECT_ATTEMPTS = 5
const INITIAL_BACKOFF_MS = 1000
const MAX_BACKOFF_MS = 30000
```

### UUID 缓冲区容量

```typescript
const recentPostedUUIDs = new BoundedUUIDSet(2000)
const recentInboundUUIDs = new BoundedUUIDSet(2000)
```

---

## 相关源码文件

| 文件 | 功能 |
|------|------|
| `bridgeMain.ts` | 桥接主入口和生命周期管理 |
| `bridgeMessaging.ts` | 消息处理、路由、流量控制 |
| `replBridge.ts` | REPL 会话桥接 |
| `replBridgeTransport.ts` | 传输层实现 |
| `sessionRunner.ts` | 子进程会话管理 |
| `jwtUtils.ts` | JWT 解析和刷新调度 |
| `bridgePermissionCallbacks.ts` | 权限回调接口 |
| `replBridgeHandle.ts` | 句柄类型定义 |
| `bridgeApi.ts` | 桥接 API 客户端 |
| `pollConfig.ts` | 轮询配置 |
| `flushGate.ts` | 刷新门控 |
| `capacityWake.ts` | 容量唤醒机制 |