Claude Code 服务层、集成、桥接与安全分析

1. 服务层架构 (src/services/)

Claude Code 的服务层是一组松耦合的功能模块，通过 AppState 和依赖注入串联。

关键文件

• src/services/api/client.ts — Anthropic SDK 包装，支持多 provider（Direct/Bedrock/Vertex/Foundry）
• src/services/api/claude.ts — Claude API 调用核心逻辑
• src/services/api/withRetry.ts — 通用重试机制
• src/services/api/usage.ts — token 用量追踪
• src/services/tools/toolOrchestration.ts — 工具调度编排

2. MCP 集成详情

MCP（Model Context Protocol）是 Claude Code 连接外部工具服务的核心协议。

架构

src/services/mcp/
├── client.ts              # MCP 客户端实现（3348行），支持 SSE/Stdio/StreamableHTTP 传输
├── config.ts              # MCP 服务器配置管理（1578行），多作用域（项目/全局/托管）
├── MCPConnectionManager.tsx # React Context，管理 MCP 连接生命周期
├── types.ts               # 类型定义
├── auth.ts                # MCP 服务器认证
├── channelAllowlist.ts    # MCP 通道白名单
├── channelPermissions.ts  # MCP 通道权限
├── channelNotification.ts # MCP 通道通知
├── claudeai.ts            # Claude.ai MCP 配置获取
├── elicitationHandler.ts  # MCP 服务器主动请求用户输入
├── envExpansion.ts        # 环境变量展开
├── InProcessTransport.ts  # 进程内传输层
├── SdkControlTransport.ts # SDK 控制传输
├── officialRegistry.ts    # 官方 MCP 注册表
├── normalization.ts       # 配置规范化
├── oauthPort.ts           # MCP OAuth 端口
├── vscodeSdkMcp.ts        # VSCode SDK MCP 集成
├── xaa.ts                 # XAA 工具
└── xaaIdpLogin.ts         # XAA IdP 登录（token 缓存在 keychain）

传输层支持

client.ts 通过 @modelcontextprotocol/sdk 支持三种传输模式：

• Stdio — StdioClientTransport：本地进程通信
• SSE — SSEClientTransport：Server-Sent Events 流
• StreamableHTTP — StreamableHTTPClientTransport：HTTP 流式传输

配置层级

config.ts 管理多作用域 MCP 配置：

• 项目级 — .mcp.json（项目根目录）
• 全局级 — 全局配置目录
• 企业托管 — managed-mcp.json（受管路径）
• Claude.ai 云端 — 通过 claudeai.ts 从 claude.ai 获取配置
• 插件注入 — 通过 mcpPluginIntegration.ts 从插件系统注入

MCP 工具类型

• MCPTool — 标准 MCP 工具调用
• ListMcpResourcesTool — 列出 MCP 资源
• ReadMcpResourceTool — 读取 MCP 资源
• createMcpAuthTool — MCP 认证工具

关键文件

• src/services/mcp/client.ts:1-80 — 导入与类型基础
• src/services/mcp/config.ts:62-80 — 作用域配置管理
• src/services/mcp/MCPConnectionManager.tsx — React Context 连接管理

3. Bridge 系统（远程控制通信）

Bridge 是 Claude Code 的「远程控制」（Remote Control）系统，允许 claude.ai 网页端远程指挥 CLI 实例执行任务。

架构

src/bridge/
├── bridgeMain.ts          # 主循环（2999行）：轮询工作、启动会话、管理生命周期
├── bridgeApi.ts           # API 客户端（539行）：与 Anthropic bridge 服务通信
├── bridgeConfig.ts        # 桥接配置
├── bridgeMessaging.ts     # 消息传递
├── bridgePermissionCallbacks.ts # 权限回调（远程 ↔ 本地权限转发）
├── bridgePointer.ts       # 指针管理
├── bridgeStatusUtil.ts    # 状态工具
├── bridgeUI.ts            # UI 展示（日志器）
├── bridgeEnabled.ts       # 功能开关
├── bridgeDebug.ts         # 调试工具
├── capacityWake.ts        # 容量唤醒
├── codeSessionApi.ts      # 代码会话 API
├── createSession.ts       # 会话创建
├── jwtUtils.ts            # JWT token 刷新调度
├── pollConfig.ts          # 轮询间隔配置
├── replBridge.ts          # REPL 桥接
├── replBridgeHandle.ts    # REPL 桥接句柄
├── replBridgeTransport.ts # REPL 桥接传输
├── remoteBridgeCore.ts    # 远程桥接核心
├── sessionRunner.ts       # 会话运行器（spawn 子进程）
├── sessionIdCompat.ts     # 会话 ID 兼容
├── trustedDevice.ts       # 受信设备 token 管理
├── workSecret.ts          # 工作密钥编码/解码
├── types.ts               # 类型定义（262行）
└── inboundMessages.ts     # 入站消息处理

核心流程

1. 注册 Worker — bridgeMain.ts 调用 registerWorker() 向 Anthropic 服务注册当前 CLI 为可用 worker
2. 轮询工作 — 通过 bridgeApi.ts 的 getNextWork() 持久轮询待执行任务
3. 会话启动 — sessionRunner.ts 的 createSessionSpawner() 创建隔离的子会话
4. 权限代理 — bridgePermissionCallbacks.ts 将远程权限请求转发到本地权限 UI
5. JWT 刷新 — jwtUtils.ts 的 createTokenRefreshScheduler() 管理 token 刷新
6. 受信设备 — trustedDevice.ts 管理 X-Trusted-Device-Token 头，用于 ELEVATED 安全层级

Spawn 模式

types.ts 定义三种会话目录策略：

• single-session — 单会话在 cwd，完成后桥接断开
• worktree — 持久服务器，每个会话获独立 git worktree
• same-dir — 持久服务器，所有会话共享 cwd

Worker 类型

type BridgeWorkerType = 'claude_code' | 'claude_code_assistant'

安全设计

• ID 验证 — validateBridgeId() 防止路径遍历攻击
• Fatal Error 区分 — BridgeFatalError 将不可重试错误（如 401）与可重试错误分开
• 受信设备 — 服务端要求 SecurityTier=ELEVATED 时验证设备 token
• 工作密钥 — workSecret.ts 编码会话 ingress token、API 地址等敏感数据

关键文件

• src/bridge/bridgeMain.ts:59-80 — 退避策略配置
• src/bridge/bridgeApi.ts:38-53 — ID 验证与安全
• src/bridge/types.ts:1-80 — 协议类型定义
• src/bridge/trustedDevice.ts:1-60 — 受信设备 token 管理

4. 远程/服务端模式 (src/remote/, src/server/)

远程会话管理 (src/remote/)

RemoteSessionManager 支持：

• SDK 消息接收/转发
• 权限请求的远程 ↔ 本地映射（创建合成 AssistantMessage 和 Tool stub）
• 查看者模式（viewerOnly）：纯观察不中断远程 Agent

直连管理 (src/server/)

DirectConnectSessionManager 通过 WebSocket 连接远程 Claude Code 实例，支持 authToken 认证。

5. 认证/安全机制

5.1 OAuth 2.0 + PKCE 流程

src/services/oauth/ 实现完整的 OAuth 2.0 授权码流程：

index.ts (OAuthService)
  ├── client.ts      — 构建 auth URL、token 交换、profile 获取
  ├── crypto.ts      — PKCE code verifier/challenge 生成
  ├── auth-code-listener.ts — 本地 HTTP 回调监听器
  └── getOauthProfile.ts — 获取用户 profile 信息

流程：

1. OAuthService.startOAuthFlow() 生成 PKCE verifier + state
2. 启动 AuthCodeListener（本地 HTTP 服务器监听 callback）
3. 同时生成自动流程 URL（localhost 回调）和手动流程 URL
4. 自动流程：openBrowser() 打开 → 重定向到 localhost → 捕获 auth code
5. 手动流程：用户复制粘贴 auth code
6. exchangeCodeForTokens() 用 auth code 换取 access/refresh token
7. fetchProfileInfo() 获取订阅类型和限速层级

支持的登录方式：

• Anthropic Console OAuth
• Claude.ai OAuth（Max 订阅）

5.2 安全存储 (src/utils/secureStorage/)

index.ts               — 平台分发：macOS → keychain，其他 → 明文
macOsKeychainStorage.ts — macOS Keychain 封装（通过 `security` CLI）
macOsKeychainHelpers.ts — Keychain 缓存状态管理
keychainPrefetch.ts     — 启动时预取 keychain（并行优化）
fallbackStorage.ts      — 回退存储（keychain 失败 → 明文）
plainTextStorage.ts     — 明文存储（非 macOS 平台）

存储策略：

• macOS: Keychain 优先（通过 security 命令行工具），失败时回退到明文文件
• 其他平台: 明文存储（.credentials.json，权限 0600）
• 预取优化: keychainPrefetch.ts 在 main.tsx 启动时并行预读 keychain

5.3 API 密钥管理 (src/utils/auth.ts)

多层 API 密钥获取策略：

1. ANTHROPIC_API_KEY 环境变量（最高优先级）
2. OAuth token（从 keychain/FD/环境变量）
3. API Key Helper 脚本输出
4. AWS Bedrock / GCP Vertex / Azure Foundry 凭证

OAuth token 刷新使用分布式锁防止并发刷新，并支持跨 tab 的 keychain 恢复（401 时检查 keychain 是否有其他 tab 刷新的 token）。

5.4 受信设备 (src/bridge/trustedDevice.ts)

Bridge 会话的额外安全层：

• 通过 POST /auth/trusted_devices 注册设备
• Token 持久化存储在 keychain，90 天滚动过期
• 由 GrowthBook feature gate tengu_sessions_elevated_auth_enforcement 控制
• 每次 bridge API 调用附带 X-Trusted-Device-Token 头

6. 权限执行 (src/hooks/toolPermission/)

权限上下文

PermissionContext.ts 是权限决策的核心协调器：

createPermissionContext(tool, input, toolUseContext, assistantMessage, toolUseID, ...)

权限决策来源：

权限处理流程

1. 分类器检查 — tryClassifier() 对 Bash 命令进行自动安全分类（feature flag: BASH_CLASSIFIER）
2. Hook 执行 — runHooks() 调用 executePermissionRequestHooks() 执行用户自定义 hook
3. 用户确认 — 通过 PermissionQueueOps 推入 React 权限队列，等待用户交互
4. 决策持久化 — persistPermissions() 将永久授权写入配置

权限处理器

handlers/ 目录包含三种处理模式：

• coordinatorHandler.ts — 协调器模式（主进程权限处理）
• interactiveHandler.ts — 交互模式（终端 UI 权限确认）
• swarmWorkerHandler.ts — Swarm Worker 模式（子 Agent 权限处理）

权限更新

使用 PermissionUpdate schema 支持细粒度权限更新：

• 可以指定更新目标（项目级/全局级配置）
• 支持 supportsPersistence() 判断是否持久化
• applyPermissionUpdates() 应用到 ToolPermissionContext

关键文件

• src/hooks/toolPermission/PermissionContext.ts:96-348 — 权限上下文工厂函数
• src/hooks/toolPermission/permissionLogging.ts — 权限决策日志
• src/hooks/toolPermission/handlers/coordinatorHandler.ts — 协调器处理器

7. 遥测/分析系统

架构

src/services/analytics/
├── index.ts                    # 公共 API（logEvent），队列化事件，零依赖避免循环
├── sink.ts                     # 事件扇出：Datadog + 1P Event Logging
├── sinkKillswitch.ts           # Sink 杀死开关
├── datadog.ts                  # Datadog RUM 事件追踪
├── firstPartyEventLogger.ts    # 内部 1P 事件记录器
├── firstPartyEventLoggingExporter.ts # 1P 事件导出器
├── growthbook.ts               # GrowthBook/Statsig feature gate
├── config.ts                   # 分析配置
└── metadata.ts                 # 事件元数据处理

设计原则

1. 零依赖入口 — index.ts 无任何导入（避免循环依赖），事件入队直到 attachAnalyticsSink() 被调用
2. PII 安全类型 — 使用 phantom type 标记：
   • AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS — 一般元数据
   • AnalyticsMetadata_I_VERIFIED_THIS_IS_PII_TAGGED — PII 标记字段（仅 1P 系统可见）
3. Proto 字段隔离 — _PROTO_* 前缀的 key 只路由到内部系统，stripProtoFields() 在 Datadog 分发前过滤
4. 采样控制 — shouldSampleEvent() 支持事件级别采样
5. Feature Gate — Datadog 追踪由 tengu_log_datadog_events gate 控制

事件命名

事件使用 tengu_ 前缀，例如：

• tengu_oauth_auth_code_received — OAuth 授权码接收
• tengu_oauth_401_recovered_from_keychain — Keychain 恢复 token
• tengu_tool_use_cancelled — 工具使用取消
• tengu_api_key_saved_to_keychain — API key 保存到 keychain

8. LSP 服务

架构

src/services/lsp/
├── manager.ts              # 单例管理器，启动/关闭/状态查询
├── LSPServerManager.ts     # LSP 服务器管理器工厂
├── LSPServerInstance.ts    # 单个 LSP 服务器实例
├── LSPClient.ts            # LSP 客户端
├── LSPDiagnosticRegistry.ts # 诊断注册表
├── config.ts               # LSP 配置
└── passiveFeedback.ts      # 被动反馈通知处理

manager.ts 提供全局单例 lspManagerInstance，在 Claude Code 启动时异步初始化，使用 generation counter 防止过期 promise 更新状态。

9. 插件系统

架构

src/services/plugins/
├── PluginInstallationManager.ts  # 后台安装管理（自动安装/更新市场和插件）
├── pluginOperations.ts           # 插件操作（配置/删除/清理）
└── pluginCliCommands.ts          # CLI 插件命令

配合 src/utils/plugins/：

• marketplaceManager.ts — 市场管理（git clone、私有仓库认证）
• pluginLoader.ts — 插件加载器
• reconciler.ts — 市场差异比较与协调
• mcpPluginIntegration.ts — 插件 MCP 服务器注入
• lspPluginIntegration.ts — 插件 LSP 集成

插件配置存储

• 普通配置 → settings.json
• 敏感配置（sensitive: true）→ secureStorage（macOS Keychain 或 .credentials.json）

10. 关键文件索引