# 服务层与基础设施分析

## 服务层架构

```mermaid
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。

```mermaid
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` | 工作密钥 |

## 多代理协调器

```mermaid
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/>任务列表]
```

## 插件系统

```mermaid
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 扩展]
```

## 技能系统

```mermaid
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) 服务支持多种传输协议：

```mermaid
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 认证流程

```mermaid
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 服务架构

```mermaid
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 计数。

```mermaid
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[增量渲染]
```

## 权限系统

```mermaid
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` | 溢出测试工具 |