bridge mode

Bridge 模式允许 IDE 或 Web 客户端远程控制 Claude Code。

设计理念

问题

终端 UI 有局限：

• 无法显示富媒体

• 交互能力有限

• 难以集成到 IDE

解决方案

通过 Bridge 连接到图形界面：

VS Code / Web UI
  ↕ (WebSocket/SSE)
Claude Code (Bridge)
  ↕ (Anthropic API)
Claude AI

架构

组件

┌─────────────────┐
│   IDE Client    │
│  (VS Code Ext)  │
└────────┬────────┘
         │ WebSocket
┌────────▼────────┐
│  Bridge Server  │
│  (Claude Code)  │
└────────┬────────┘
         │ API
┌────────▼────────┐
│  Anthropic API  │
└─────────────────┘

通信协议

type BridgeMessage =
  | { type: 'query'; messages: Message[]; tools: Tool[] }
  | { type: 'query_event'; event: QueryEvent }
  | { type: 'state_update'; state: Partial<AppState> }
  | { type: 'tool_approval'; approved: boolean };

核心实现

Bridge Server

class BridgeServer {
  private wss: WebSocketServer;
  private clients = new Set<WebSocket>();
  
  constructor(port: number) {
    this.wss = new WebSocketServer({ port });
    
    this.wss.on('connection', ws => {
      this.handleConnection(ws);
    });
  }
  
  private handleConnection(ws: WebSocket): void {
    this.clients.add(ws);
    
    ws.on('message', data => {
      this.handleMessage(ws, JSON.parse(data));
    });
    
    ws.on('close', () => {
      this.clients.delete(ws);
    });
  }
  
  private async handleMessage(
    ws: WebSocket,
    message: BridgeMessage
  ): Promise<void> {
    if (message.type === 'query') {
      // 执行查询，流式返回结果
      for await (const event of query(message.messages, message.tools)) {
        ws.send(JSON.stringify({
          type: 'query_event',
          event: event,
        }));
      }
    }
  }
}

Bridge Client

class BridgeClient {
  private ws: WebSocket;
  
  constructor(url: string) {
    this.ws = new WebSocket(url);
  }
  
  async query(
    messages: Message[],
    tools: Tool[]
  ): AsyncGenerator<QueryEvent> {
    // 发送查询请求
    this.ws.send(JSON.stringify({
      type: 'query',
      messages: messages,
      tools: tools,
    }));
    
    // 接收流式响应
    for await (const data of this.receive()) {
      const message = JSON.parse(data);
      
      if (message.type === 'query_event') {
        yield message.event;
      }
    }
  }
  
  private async *receive(): AsyncGenerator<string> {
    const queue = [];
    
    this.ws.on('message', data => {
      queue.push(data.toString());
    });
    
    while (true) {
      if (queue.length > 0) {
        yield queue.shift();
      } else {
        await sleep(10);
      }
    }
  }
}

认证

JWT Token

function generateToken(deviceId: string): string {
  return jwt.sign(
    {
      deviceId: deviceId,
      timestamp: Date.now(),
    },
    SECRET_KEY,
    { expiresIn: '7d' }
  );
}

function verifyToken(token: string): boolean {
  try {
    jwt.verify(token, SECRET_KEY);
    return true;
  } catch {
    return false;
  }
}

设备信任

const trustedDevices = new Set<string>();

function trustDevice(deviceId: string): void {
  trustedDevices.add(deviceId);
  saveTrustedDevices();
}

function isTrusted(deviceId: string): boolean {
  return trustedDevices.has(deviceId);
}

状态同步

推送状态更新

function syncState(state: AppState): void {
  // 广播给所有连接的客户端
  for (const client of clients) {
    client.send(JSON.stringify({
      type: 'state_update',
      state: state,
    }));
  }
}

接收状态更新

// 客户端接收状态更新
ws.on('message', data => {
  const message = JSON.parse(data);
  
  if (message.type === 'state_update') {
    updateLocalState(message.state);
  }
});

下一步

• 了解 Remote Control 的详细实现

• 探索 Assistant 模式 的会话管理

• 查看 Coordinator 模式 的任务编排