Add project documentation
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
arno
@@ -0,0 +1,187 @@
|
||||
# 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 开销。
|
||||
Reference in New Issue
Block a user