Add project documentation
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
arno
@@ -0,0 +1,292 @@
|
||||
# 服务层与基础设施分析
|
||||
|
||||
## 服务层架构
|
||||
|
||||
```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` | 溢出测试工具 |
|
||||
Reference in New Issue
Block a user