Bridge 协议

Bridge 协议定义了 CLI 与 claude.ai 之间的通信格式。

重要说明: 以下描述已根据实际代码修正。Bridge 使用 SDK 消息类型（SDKMessage、SDKControlRequest、SDKControlResponse），而非自定义的 BridgeMessage 格式。

消息格式

// bridgeMessaging.ts — 类型守卫函数（非自定义消息类型）
// 实际使用 SDK 标准消息类型:
//   SDKMessage — SDK 消息
//   SDKControlRequest — SDK 控制请求
//   SDKControlResponse — SDK 控制响应
//
// 导出的类型守卫:
//   isSDKMessage()
//   isSDKControlResponse()
//   isSDKControlRequest()
//   isEligibleBridgeMessage()

握手流程

CLI                         claude.ai Web
 │                              │
 ├── Bridge 启用 ────────────→  │
 │                              │
 │  ←── Session 创建 ──────────┤
 │                              │
 ├── 连接确认 ───────────────→  │
 │   (workDir, capabilities)    │
 │                              │
 │  ←── 配置同步 ──────────────┤
 │   (permissions, tools)       │
 │                              │
 │      ═══ 双向通信 ═══       │

权限代理

// 实际类型为 BridgePermissionCallbacks，非 PermissionProxy
type BridgePermissionCallbacks = {
  sendRequest(): Promise<void>
  sendResponse(): Promise<void>
  cancelRequest(): Promise<void>
  onResponse(): Promise<BridgePermissionResponse>
}

interface BridgePermissionResponse {
  behavior: 'allow' | 'deny'
}

心跳机制

// 心跳通过 HTTP POST 实现（bridgeApi.heartbeatWork()）
// 而非 setInterval + WebSocket
// generalCapMs 在 bridgeMain.ts 中为 30_000

附件处理

// 实际类型为 Zod 推导类型，字段为:
interface InboundAttachment {
  file_uuid: string    // 文件 UUID
  file_name: string    // 文件名
}

实际函数名为 extractInboundAttachments(msg) 用于提取附件列表，resolveInboundAttachments() 用于解析附件内容。 其他导出: prependPathRefs()、resolveAndPrepend()。