本章总览
src/bridge/ 是 Claude Code「Remote Control / 远程桥接」实现层：把本地 REPL 或 claude remote-control 守护进程与 claude.ai 的 Session-Ingress、Environments API、CCR v2 worker 协议连接起来（33 个文件，约 12652 行）。务必区分：replBridge.ts（env-based 轮询核心）≠ remoteBridgeCore.ts（env-less OAuth→/bridge 直连）≠ bridgeMain.ts（多 session spawn 守护循环）。
总览图
学完本章你应该能
- 建立 repl-bridge → bridge-messaging → remote-bridge-core → bridge-permissions-ui 的阅读顺序
- 理解 v1 HybridTransport 与 v2 SSE+CCRClient 双传输路径
- 能在源码树中从本页跳转到子章节与高亮文件
- 区分 REPL 内嵌桥（useReplBridge）与 standalone remote-control 进程
建议学习步骤
- 浏览下方子章节导航表，选择入口主题
- 点击 SourceTree 中的 bridge/ 子目录跳转到对应讲解
- 建议顺序：repl-bridge → bridge-messaging → remote-bridge-core → bridge-permissions-ui
模块在架构中的位置
bridge 是 src/ 下的一级目录，共 33 个文件、12,652 行。一句话概括：Claude Desktop / 远程控制桥接：JWT 认证、会话同步、消息中继。
概览
| 指标 | 数值 |
|---|---|
| 行数 | 12,652 |
| 文件 | 33 |
子章节导航
| 子章节 | 主题 | 核心路径 |
|---|---|---|
| repl-bridge | REPL 桥初始化、传输、句柄 | initReplBridge.ts、replBridge.ts、replBridgeTransport.ts、replBridgeHandle.ts |
| bridge-messaging | 入站/出站消息、附件、FlushGate | bridgeMessaging.ts、inboundMessages.ts、inboundAttachments.ts、flushGate.ts |
| remote-bridge-core | env-less 核心、守护主循环、spawn | remoteBridgeCore.ts、bridgeMain.ts、sessionRunner.ts、createSession.ts |
| bridge-permissions-ui | 权限回调、TUI、API、可信设备 | bridgePermissionCallbacks.ts、bridgeUI.ts、bridgeApi.ts、trustedDevice.ts |
两条桥接架构路径
Claude Code bridge 在 GrowthBook 门控下分叉为 v1 env-based 与 v2 env-less：
| 路径 | 入口 | 会话创建 | 工作分派 | 传输 |
|---|---|---|---|---|
| v1 env-based | initReplBridge → initBridgeCore | createBridgeSession + Environments API | pollForWork / acknowledgeWork | HybridTransport（WS 读 + POST 写）或 CCR v2 |
| v2 env-less | initReplBridge → initEnvLessBridgeCore | POST /v1/code/sessions + POST .../bridge | 无 poll；JWT 刷新调度器 | createV2ReplTransport（SSE 读 + CCRClient 写） |
bundle 隔离是贯穿全模块的设计动机：initReplBridge.ts 与 replBridge.ts 拆分，避免 sessionStorage → commands.ts 拖入 Agent SDK；toSDKMessages、createSession、onAuth401 均以注入形式传入 BridgeCoreParams。
outboundOnly 模式（CCR mirror）只激活写出路径，入站 control_request 对可变操作返回明确错误，避免 claude.ai 显示「已成功」而本地无动作。
目录树展示 src/bridge/ 下全部 TypeScript 文件（bridgeApi、bridgeMain、replBridge、pollConfig 等）。commands/bridge/index.ts 提供 /remote-control 斜杠命令，属 commands 模块，本树不包含。
与其他模块的边界
| 协作方 | 关系 |
|---|---|
| hooks/useReplBridge.tsx | React 侧自动启动 bridge，setReplBridgeHandle 发布全局句柄 |
| cli/transports/HybridTransport | v1 Session-Ingress WS + POST |
| cli/transports/SSETransport、ccrClient | v2 读/写分离 |
| commands.ts | BRIDGE_SAFE_COMMANDS、isBridgeSafeCommand 限制远程可执行斜杠 |
| utils/sessionIngressAuth | 更新 ingress JWT |
| services/oauth、policyLimits | OAuth 刷新、allow_remote_control 策略 |
调试「bridge 连不上」：按 initReplBridge 步骤查 gate → OAuth → policy → 版本 floor；调试「手机发消息无反应」：查 handleIngressMessage 与 extractInboundMessageFields；调试「remote-control 子进程死掉」：查 bridgeMain poll 与 sessionRunner stderr。
本章小结与延伸
bridge 模块 = 本地 CLI 与 claude.ai 远程会话的双向管道。先懂 initReplBridge 门控与 initBridgeCore 生命周期，再读消息过滤、env-less 核心与权限/UI 面。 继续学习：