claude-code/docs/services-and-infrastructure.md

服务层与基础设施分析

服务层架构

graph TB
    subgraph API 服务
        API_CLIENT[client.ts<br/>Anthropic API 客户端]
        API_CLAUDE[claude.ts<br/>Claude API 封装]
        API_BOOTSTRAP[bootstrap.ts<br/>引导逻辑]
        API_FILES[filesApi.ts<br/>文件 API]
        API_USAGE[usage.ts<br/>使用量查询]
        API_SESSION[sessionIngress.ts<br/>会话入口]
        API_ERRORS[errors.ts<br/>错误处理]
        API_RETRY[withRetry.ts<br/>重试逻辑]
        API_GROVE[grove.ts<br/>Grove 集成]
    end

    subgraph MCP 服务
        MCP_MGR[MCPConnectionManager.tsx<br/>MCP 连接管理器]
        MCP_AUTH[auth.ts<br/>MCP 认证]
        MCP_CONFIG[config.ts<br/>MCP 配置]
        MCP_TYPES[types.ts<br/>MCP 类型定义]
        MCP_REGISTRY[officialRegistry.ts<br/>官方注册表]
        MCP_VSCODE[vscodeSdkMcp.ts<br/>VSCode SDK MCP]
        MCP_SDK[SdkControlTransport.ts<br/>SDK 控制传输]
        MCP_NORMAL[normalization.ts<br/>MCP 规范化]
    end

    subgraph OAuth 认证
        OAUTH_FLOW[OAuth 2.0 流程]
        OAUTH_XAA[xaa.ts / xaaIdpLogin.ts<br/>XAA 认证]
        OAUTH_PORT[oauthPort.ts<br/>OAuth 端口]
    end

    subgraph 分析服务
        ANALYTICS_GROWTH[GrowthBook 特性开关]
        ANALYTICS_TELEMETRY[OpenTelemetry 遥测]
        ANALYTICS_TRACKING[diagnosticTracking.ts<br/>诊断追踪]
    end

    subgraph 其他服务
        COMPACT[compact/<br/>上下文压缩]
        POLICY[policyLimits/<br/>组织策略限制]
        REMOTE_SETTINGS[remoteManagedSettings/<br/>远程托管设置]
        EXTRACT_MEM[extractMemories/<br/>自动记忆提取]
        TOKEN_EST[tokenEstimation.ts<br/>Token 估算]
        TEAM_MEM[teamMemorySync/<br/>团队记忆同步]
        SESSION_MEM[SessionMemory/<br/>会话记忆]
        LSP[lsp/<br/>Language Server Protocol]
        PLUGINS[plugins/<br/>插件加载器]
        VOICE[voice.ts / voiceStreamSTT.ts<br/>语音输入/STT]
    end

Bridge 桥接系统

Bridge 是 IDE 扩展与 Claude Code CLI 之间的双向通信层，支持 VS Code 和 JetBrains。

sequenceDiagram
    participant IDE as IDE 扩展<br/>(VS Code / JetBrains)
    participant BridgeMain as bridgeMain.ts
    participant Messaging as bridgeMessaging.ts
    participant ReplBridge as replBridge.ts
    participant JWT as jwtUtils.ts
    participant Session as sessionRunner.ts
    participant CLI as Claude Code CLI

    IDE->>BridgeMain: 建立连接
    BridgeMain->>JWT: JWT 认证
    JWT-->>BridgeMain: 认证通过
    IDE->>Messaging: 发送消息
    Messaging->>ReplBridge: 转发到 REPL
    ReplBridge->>Session: 执行会话
    Session->>CLI: 调用工具/命令
    CLI-->>Session: 返回结果
    Session-->>ReplBridge: 处理结果
    ReplBridge-->>Messaging: 构建响应
    Messaging-->>IDE: 返回结果

Bridge 核心模块

文件	功能
bridgeMain.ts	Bridge 主循环
bridgeMessaging.ts	消息协议定义
bridgePermissionCallbacks.ts	权限回调处理
bridgeConfig.ts	Bridge 配置
bridgeApi.ts	Bridge API 接口
bridgeDebug.ts	Bridge 调试工具
bridgeEnabled.ts	Bridge 启用状态检测
bridgeUI.ts	Bridge UI 组件
replBridge.ts	REPL 会话桥接
replBridgeHandle.ts	REPL Bridge 句柄
replBridgeTransport.ts	REPL Bridge 传输层
initReplBridge.ts	REPL Bridge 初始化
jwtUtils.ts	JWT 认证工具
sessionRunner.ts	会话执行管理
createSession.ts	会话创建
codeSessionApi.ts	Code 会话 API
capacityWake.ts	容量唤醒
remoteBridgeCore.ts	远程 Bridge 核心
trustedDevice.ts	受信任设备
workSecret.ts	工作密钥

多代理协调器

flowchart TD
    A[coordinatorMode.ts] --> B{协调器模式?}
    B -->|是| C[分发任务给 Worker]
    B -->|否| D[普通模式]

    C --> E[Worker 1<br/>AgentTool]
    C --> F[Worker 2<br/>AgentTool]
    C --> G[Worker N<br/>AgentTool]

    E --> H[SendMessage<br/>消息传递]
    F --> H
    G --> H
    H --> I[Coordinator<br/>汇总结果]

    C --> J[TaskCreate<br/>任务创建]
    J --> K[TaskUpdate<br/>任务更新]
    K --> L[TaskList<br/>任务列表]

插件系统

flowchart LR
    A[builtinPlugins.ts<br/>内置插件] --> C[插件加载器]
    B[bundled/<br/>捆绑插件] --> C
    D[用户插件目录<br/>.claude/plugins/] --> C
    C --> E[插件注册]
    E --> F[工具扩展]
    E --> G[命令扩展]
    E --> H[Hook 扩展]

技能系统

flowchart LR
    A[bundled/<br/>捆绑技能] --> C[技能加载器]
    B[bundledSkills.ts<br/>技能注册] --> C
    D[loadSkillsDir.ts<br/>用户技能目录] --> C
    E[mcpSkillBuilders.ts<br/>MCP 技能构建] --> C
    C --> F[SkillTool<br/>技能执行]

内置技能清单

技能	功能
update-config	配置 settings.json 和 hooks
simplify	代码简化和质量审查
loop	定时循环执行命令
claude-api	Claude API / Anthropic SDK 开发
commit	Git 提交
remember	记忆管理

MCP 服务详细架构

MCP (Model Context Protocol) 服务支持多种传输协议：

flowchart TD
    A[MCPConnectionManager] --> B{传输协议}
    B -->|stdio| C[子进程通信]
    B -->|SSE| D[Server-Sent Events]
    B -->|HTTP| E[HTTP 传输]
    B -->|SDK| F[SdkControlTransport<br/>IDE SDK 控制]

    A --> G[officialRegistry.ts<br/>官方 MCP 服务器注册表]
    A --> H[vscodeSdkMcp.ts<br/>VS Code SDK 集成]
    A --> I[normalization.ts<br/>工具名规范化]

    A --> J[auth.ts<br/>认证]
    J --> K[OAuth 认证]
    J --> L[API Key 认证]
    J --> M[XAA 认证<br/>xaa.ts / xaaIdpLogin.ts]

OAuth 认证流程

sequenceDiagram
    participant CLI as Claude Code
    participant Browser as 浏览器
    participant OAuth as OAuth 服务
    participant Listener as 本地监听

    CLI->>OAuth: 生成 PKCE 挑战
    CLI->>Browser: 打开授权页面
    Browser->>OAuth: 用户授权
    OAuth-->>Browser: 授权码
    Browser->>Listener: 回调携带授权码
    Listener->>CLI: 传递授权码
    CLI->>OAuth: 用授权码 + PKCE 换取令牌
    OAuth-->>CLI: Access Token + Refresh Token
    CLI->>CLI: 存储令牌（Keychain/文件）

LSP 服务架构

flowchart TD
    A[lsp/manager.ts<br/>LSP 管理器<br/>单例模式] --> B[LSPServerManager<br/>服务器管理]
    B --> C[LSPServerInstance<br/>单个服务器实例]
    B --> D[config.ts<br/>服务器配置]

    C --> E[TypeScript Server]
    C --> F[Python Server]
    C --> G[Go Server]
    C --> H[其他语言服务器]

    A --> I[功能]
    I --> J[代码诊断<br/>被动反馈]
    I --> K[跳转定义<br/>hover 信息]
    I --> L[代码补全]
    I --> M[多项目并行连接]

查询引擎 (QueryEngine.ts)

QueryEngine 是核心的 LLM API 调用引擎（约 46K 行），处理流式响应、工具调用循环、思考模式和 Token 计数。

flowchart TD
    A[QueryEngine.ts<br/>~46K 行] --> B[query.ts<br/>查询管道<br/>~68K 行]
    A --> C[流式响应处理]
    A --> D[工具调用循环]
    A --> E[思考模式管理]
    A --> F[重试逻辑]
    A --> G[Token 计数]

    B --> H[query/ 子模块]
    H --> I[查询管道子步骤]

    D --> J{工具调用?}
    J -->|是| K[执行工具]
    K --> L[收集结果]
    L --> M[继续对话循环]
    J -->|否| N[生成最终响应]

    C --> O[SSE 流解析]
    C --> P[增量渲染]

权限系统

flowchart TD
    A[hooks/toolPermission/<br/>权限系统] --> B[PermissionMode]
    B --> C[default<br/>默认模式]
    B --> D[plan<br/>计划模式]
    B --> E[bypassPermissions<br/>绕过权限]
    B --> F[auto<br/>自动模式]
    B --> G[dontAsk<br/>不询问模式]

    A --> H[工具调用拦截]
    H --> I{权限检查}
    I -->|允许规则| J[执行]
    I -->|拒绝规则| K[拒绝]
    I -->|无规则| L[询问用户]

特性开关体系

通过 Bun 的 bun:bundle 实现编译时死代码消除：

特性开关	控制功能
PROACTIVE	主动模式（SleepTool）
KAIROS	KAIROS 功能集
BRIDGE_MODE	IDE Bridge 模式
DAEMON	守护进程模式
VOICE_MODE	语音模式
AGENT_TRIGGERS	定时触发器（Cron）
AGENT_TRIGGERS_REMOTE	远程触发器
MONITOR_TOOL	监控工具
COORDINATOR_MODE	多代理协调模式
CONTEXT_COLLAPSE	上下文折叠
TERMINAL_PANEL	终端面板
WEB_BROWSER_TOOL	Web 浏览器工具
WORKFLOW_SCRIPTS	工作流脚本
HISTORY_SNIP	历史记录剪辑
UDS_INBOX	UDS 收件箱
OVERFLOW_TEST_TOOL	溢出测试工具