188 lines
6.2 KiB
Markdown
188 lines
6.2 KiB
Markdown
# Claude Code 源码架构总览
|
||
|
||
> 基于 2026-03-31 公开暴露的源码快照分析
|
||
|
||
## 项目基本信息
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 语言 | TypeScript (strict) |
|
||
| 运行时 | Bun |
|
||
| 终端 UI | React + Ink |
|
||
| CLI 框架 | Commander.js |
|
||
| Schema 验证 | Zod v4 |
|
||
| 代码搜索 | ripgrep |
|
||
| 通信协议 | MCP SDK, LSP |
|
||
| API | Anthropic SDK |
|
||
| 遥测 | OpenTelemetry + gRPC |
|
||
| 特性开关 | GrowthBook / Bun feature flags |
|
||
| 认证 | OAuth 2.0, JWT, macOS Keychain |
|
||
| 规模 | ~1,900 文件, 512,000+ 行代码 |
|
||
|
||
## 整体架构
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph 用户层
|
||
CLI[CLI 入口<br/>main.tsx]
|
||
IDE[IDE 扩展<br/>VS Code / JetBrains]
|
||
Desktop[桌面应用]
|
||
Mobile[移动应用]
|
||
end
|
||
|
||
subgraph 命令层
|
||
CMD[命令注册器<br/>commands.ts]
|
||
CMD_IMPL[命令实现<br/>commands/ ~82个]
|
||
end
|
||
|
||
subgraph 工具层
|
||
TOOL_REG[工具注册器<br/>tools.ts]
|
||
TOOL_IMPL[工具实现<br/>tools/ ~40个]
|
||
TOOL_TYPE[工具类型定义<br/>Tool.ts]
|
||
end
|
||
|
||
subgraph 核心引擎
|
||
QE[查询引擎<br/>QueryEngine.ts]
|
||
QS[查询管道<br/>query.ts]
|
||
CTX[上下文管理<br/>context.ts]
|
||
end
|
||
|
||
subgraph 服务层
|
||
API_SVC[API 服务<br/>services/api/]
|
||
MCP_SVC[MCP 服务<br/>services/mcp/]
|
||
AUTH_SVC[OAuth 认证<br/>services/oauth/]
|
||
LSP_SVC[LSP 服务<br/>services/lsp/]
|
||
ANALYTICS[分析/特性开关<br/>services/analytics/]
|
||
end
|
||
|
||
subgraph 基础设施
|
||
BRIDGE[IDE 桥接<br/>bridge/]
|
||
COORD[多代理协调<br/>coordinator/]
|
||
PLUGINS[插件系统<br/>plugins/]
|
||
SKILLS[技能系统<br/>skills/]
|
||
PERM[权限系统<br/>hooks/toolPermission/]
|
||
end
|
||
|
||
subgraph UI 层
|
||
COMP[UI 组件<br/>components/ ~140个]
|
||
SCREENS[全屏界面<br/>screens/]
|
||
VIM[Vim 模式<br/>vim/]
|
||
KB[快捷键<br/>keybindings/]
|
||
end
|
||
|
||
CLI --> CMD --> CMD_IMPL
|
||
CLI --> TOOL_REG --> TOOL_IMPL
|
||
IDE --> BRIDGE --> QE
|
||
QE --> QS --> API_SVC
|
||
TOOL_IMPL --> PERM
|
||
QE --> CTX
|
||
CMD_IMPL --> TOOL_IMPL
|
||
TOOL_IMPL --> MCP_SVC
|
||
TOOL_IMPL --> LSP_SVC
|
||
QE --> ANALYTICS
|
||
BRIDGE --> AUTH_SVC
|
||
CLI --> COMP --> SCREENS
|
||
COMP --> VIM
|
||
COMP --> KB
|
||
COORD --> TOOL_IMPL
|
||
PLUGINS --> TOOL_REG
|
||
SKILLS --> CMD
|
||
```
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
src/
|
||
├── main.tsx # 入口：Commander.js CLI + React/Ink 渲染
|
||
├── commands.ts # 命令注册器
|
||
├── tools.ts # 工具注册器
|
||
├── Tool.ts # 工具类型定义
|
||
├── QueryEngine.ts # LLM 查询引擎
|
||
├── query.ts # 查询管道
|
||
├── context.ts # 系统/用户上下文收集
|
||
├── cost-tracker.ts # Token 成本追踪
|
||
│
|
||
├── commands/ # 命令实现 (~82 个命令, 189 个文件)
|
||
├── tools/ # 工具实现 (~40 个工具)
|
||
├── components/ # Ink UI 组件 (~140 个)
|
||
├── hooks/ # React hooks (~70 个)
|
||
├── services/ # 外部服务集成
|
||
├── screens/ # 全屏界面 (Doctor, REPL, Resume)
|
||
├── types/ # TypeScript 类型定义
|
||
├── utils/ # 工具函数
|
||
│
|
||
├── bridge/ # IDE 和远程控制桥接 (30+ 文件)
|
||
├── coordinator/ # 多代理协调器
|
||
├── plugins/ # 插件系统
|
||
├── skills/ # 技能系统
|
||
├── keybindings/ # 快捷键配置
|
||
├── vim/ # Vim 模式
|
||
├── voice/ # 语音输入
|
||
├── remote/ # 远程会话
|
||
├── server/ # 服务模式
|
||
├── memdir/ # 持久化内存目录
|
||
├── tasks/ # 任务管理
|
||
├── state/ # 状态管理 (AppState)
|
||
├── migrations/ # 配置迁移
|
||
├── schemas/ # 配置 Schema (Zod)
|
||
├── entrypoints/ # 初始化逻辑
|
||
├── ink/ # Ink 渲染器包装
|
||
├── buddy/ # 伙伴精灵
|
||
├── native-ts/ # 原生 TypeScript 工具
|
||
├── outputStyles/ # 输出样式
|
||
├── query/ # 查询管道子模块
|
||
├── assistant/ # 助手相关
|
||
├── bootstrap/ # 引导逻辑
|
||
├── cli/ # CLI 相关
|
||
├── constants/ # 常量定义
|
||
├── context/ # 上下文子模块
|
||
├── moreright/ # 扩展权限
|
||
└── upstreamproxy/ # 代理配置
|
||
```
|
||
|
||
## 启动流程
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant User as 用户
|
||
participant Main as main.tsx
|
||
participant Commander as Commander.js
|
||
participant MDM as MDM 设置
|
||
participant Keychain as macOS Keychain
|
||
participant GB as GrowthBook
|
||
participant Ink as Ink 渲染器
|
||
participant REPL as REPL 主循环
|
||
|
||
User->>Main: claude [command]
|
||
Main->>MDM: 并行预取 MDM 设置
|
||
Main->>Keychain: 并行预取 Keychain
|
||
Main->>GB: 并行初始化 GrowthBook
|
||
Main->>Commander: 解析 CLI 参数
|
||
Commander->>Main: 路由到对应命令
|
||
Main->>Ink: 初始化 React/Ink 渲染
|
||
Ink->>REPL: 启动 REPL 主循环
|
||
REPL->>REPL: 进入查询-响应循环
|
||
```
|
||
|
||
## 核心设计模式
|
||
|
||
### 1. 并行预取 (Parallel Prefetch)
|
||
启动时并行预取 MDM 设置、Keychain 读取和 API 预连接，优化启动时间。
|
||
|
||
### 2. 惰性加载 (Lazy Loading)
|
||
重型模块（OpenTelemetry、gRPC、分析等）通过动态 `import()` 延迟加载。
|
||
|
||
### 3. 特性开关 (Feature Flags)
|
||
通过 Bun 的 `bun:bundle` 实现编译时死代码消除：
|
||
```typescript
|
||
const SleepTool = feature('PROACTIVE') || feature('KAIROS')
|
||
? require('./tools/SleepTool/SleepTool.js').SleepTool
|
||
: null
|
||
```
|
||
|
||
### 4. 代理集群 (Agent Swarms)
|
||
通过 `AgentTool` 生成子代理，`coordinator/` 处理多代理编排，`TeamCreateTool` 支持团队级并行工作。
|
||
|
||
### 5. 工具搜索延迟发现
|
||
`ToolSearchTool` 允许在工具数量超过阈值时延迟加载工具定义，减少 prompt token 开销。
|