293 lines
8.7 KiB
Markdown
293 lines
8.7 KiB
Markdown
# 服务层与基础设施分析
|
||
|
||
## 服务层架构
|
||
|
||
```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` | 溢出测试工具 |
|