夜雨聆风
史上最强AI工具Claude Code 源码分析 – 项目概览与架构总览
Claude Code 源码分析 – 项目概览与架构总览
版本: 2.1.88 | 运行时: Bun | 语言: TypeScript | UI框架: React (Ink)
一、项目简介
Claude Code 是 Anthropic 推出的命令行 AI 编码助手。它是一个终端原生应用，通过 React (Ink) 框架在终端中渲染富文本 UI，使用 Anthropic API 进行对话推理，并通过一套完善的工具系统（Tool System）与本地文件系统、Shell、LSP、MCP 等进行交互。
二、技术栈
|
|
|
|
|---|---|---|
|
|
|
bun:bundle 特性开关 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
三、顶层目录结构
claude-code/├── src/ # 所有源代码│ ├── entrypoints/ # 入口点（CLI、MCP、SDK）│ ├── main.tsx # 主应用入口│ ├── query.ts # 核心查询循环│ ├── QueryEngine.tsx # 查询引擎（消息累积、API调用编排）│ ├── Tool.ts # Tool 基础类型定义│ ├── tools.ts # 工具注册表│ ├── tools/ # 40+ 工具实现（每个工具独立目录）│ ├── services/ # 核心服务层│ │ ├── api/ # API 通信（多后端支持）│ │ ├── compact/ # 上下文压缩（自动/微压缩/Snip）│ │ ├── mcp/ # MCP 协议客户端│ │ ├── analytics/ # 遥测分析（DataDog + GrowthBook）│ │ ├── lsp/ # 语言服务协议│ │ ├── oauth/ # OAuth 认证│ │ ├── tools/ # 工具执行引擎│ │ ├── plugins/ # 插件系统│ │ └── ... # 其他服务│ ├── state/ # 状态管理（createStore + React Context）│ ├── components/ # UI 组件│ ├── hooks/ # 90+ React Hooks│ ├── commands/ # 50+ 斜杠命令│ ├── utils/ # 200+ 工具函数│ │ ├── permissions/ # 权限系统（24个文件）│ │ ├── settings/ # 配置管理│ │ ├── hooks/ # 生命周期钩子│ │ ├── model/ # 模型抽象│ │ ├── telemetry/ # OpenTelemetry│ │ └── ...│ ├── ink/ # 定制 Ink 终端UI框架│ ├── screens/ # 页面（REPL、Doctor）│ ├── context/ # React Context│ ├── constants/ # 常量定义│ ├── types/ # 类型定义│ ├── schemas/ # Schema 定义│ ├── bridge/ # 远程桥接（CCR）│ ├── skills/ # 技能系统│ └── keybindings/ # 快捷键系统├── build.ts # 构建脚本（60+ 特性开关）├── package.json # 项目元数据├── tsconfig.json # TypeScript 配置└── bunfig.toml # Bun 配置四、系统架构总览图
4.1 整体架构层次
┌─────────────────────────────────────────────────────────────────┐│ 用户交互层 ││ ┌──────────┐ ┌──────────────┐ ┌──────────┐ ┌─────────────┐ ││ │ CLI 参数 │ │ REPL 交互界面 │ │ 斜杠命令 │ │ 快捷键系统 │ ││ └────┬─────┘ └──────┬───────┘ └────┬─────┘ └──────┬──────┘ ││ │ │ │ │ ││ ┌────┴───────────────┴───────────────┴───────────────┴──────┐ ││ │ React (Ink) 终端 UI 框架 │ ││ │ Components │ Hooks │ Context │ State Store │ ││ └────────────────────────┬──────────────────────────────────┘ │└───────────────────────────┼─────────────────────────────────────┘ │┌───────────────────────────┼─────────────────────────────────────┐│ 核心引擎层 ││ ┌────────────────────────┴──────────────────────────────────┐ ││ │ QueryEngine │ ││ │ ┌─────────────┐ ┌──────────────┐ ┌──────────────────┐ │ ││ │ │ 消息循环 │ │ API 流式调用 │ │ 上下文压缩 │ │ ││ │ │ (query loop)│ │ (streaming) │ │ (compact/collapse)│ │ ││ │ └─────────────┘ └──────────────┘ └──────────────────┘ │ ││ └───────────────────────────────────────────────────────────┘ ││ │ ││ ┌─────────────────────────┼─────────────────────────────────┐ ││ │ 工具执行引擎 │ ││ │ ┌───────────────┐ ┌────────────────┐ ┌──────────────┐ │ ││ │ │ 权限检查 │ │ 流式工具执行器 │ │ 工具编排 │ │ ││ │ │ (permissions) │ │ (streaming) │ │ (orchestr.) │ │ ││ │ └───────────────┘ └────────────────┘ └──────────────┘ │ ││ └───────────────────────────────────────────────────────────┘ │└───────────────────────────┼─────────────────────────────────────┘ │┌───────────────────────────┼─────────────────────────────────────┐│ 工具层 ││ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────────────┐││ │ Bash │ │ File │ │ File │ │ Grep │ │ Glob │ │ Agent │││ │ Tool │ │ Edit │ │ Read │ │ Tool │ │ Tool │ │ Tool │││ └──────┘ └──────┘ └──────┘ └──────┘ └──────┘ └──────────────┘││ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────────────┐││ │ Web │ │ MCP │ │ LSP │ │ Todo │ │ Task │ │ 30+ 更多 │││ │Fetch │ │ Tool │ │ Tool │ │Write │ │Tools │ │ │││ └──────┘ └──────┘ └──────┘ └──────┘ └──────┘ └──────────────┘│└───────────────────────────┼─────────────────────────────────────┘ │┌───────────────────────────┼─────────────────────────────────────┐│ 基础设施层 ││ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────────┐││ │ API 客户端 │ │ MCP 协议 │ │ 遥测与分析 │││ │ (多后端支持) │ │ (外部工具) │ │ (DataDog/GrowthBook/OTel)│││ └──────────────┘ └──────────────┘ └──────────────────────────┘││ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────────┐││ │ 配置系统 │ │ 钩子系统 │ │ 认证系统 │││ │ (分层配置) │ │ (生命周期) │ │ (OAuth/API Key/Bedrock) │││ └──────────────┘ └──────────────┘ └──────────────────────────┘│└─────────────────────────────────────────────────────────────────┘4.2 核心数据流
用户输入 │ ▼┌──────────┐ ┌──────────────┐ ┌───────────────┐│ TextInput │────▶│ QueryEngine │────▶│ 构建 API 请求 ││ 组件 │ │ 消息循环 │ │ (system prompt│└──────────┘ └──────┬───────┘ │ + messages) │ │ └───────┬───────┘ │ │ ▼ ▼ ┌──────────────┐ ┌───────────────┐ │ 处理流式响应 │◀────│ Anthropic API │ │ (逐块解析) │ │ (多后端) │ └──────┬───────┘ └───────────────┘ │ ┌────┴────┐ │ tool_use?│ └────┬────┘ Yes ──┤ ├── No │ │ ┌──────┘ └──────┐ ▼ ▼ ┌──────────────┐ ┌──────────────┐ │ 查找工具定义 │ │ 输出文本响应 │ │ (tools.ts) │ │ 到终端 UI │ └──────┬───────┘ └──────────────┘ │ ▼ ┌──────────────┐ │ 权限检查 │ │ (permissions) │ └──────┬───────┘ │ ▼ ┌──────────────┐ ┌───────────────┐ │ 工具执行 │────▶│ 产出结果消息 │ │ (tool.call())│ │ (tool_result) │ └──────────────┘ └───────┬───────┘ │ ▼ 返回 QueryEngine ──▶ 下一轮 API 调用4.3 状态管理架构
┌─────────────────────────────────────────────────────┐│ AppStateStore ││ (createStore<AppState> - 类 Zustand 极简实现) ││ ││ ┌─────────────────────────────────────────────────┐ ││ │ AppState 包含: │ ││ │ • messages: Message[] # 对话消息 │ ││ │ • toolPermissionContext # 工具权限上下文 │ ││ │ • mcp: MCP 状态 # MCP 连接状态 │ ││ │ • tasks: Task[] # 后台任务列表 │ ││ │ • fastMode: boolean # 快速模式 │ ││ │ • effortValue # 推理努力程度 │ ││ │ • todoItems # Todo 列表 │ ││ │ • ...更多状态 │ ││ └─────────────────────────────────────────────────┘ ││ ││ API: getState() / setState() / subscribe() │└──────────────┬──────────────────────────────────────┘ │ ┌──────────┴──────────┐ │ AppStateProvider │ │ (React Context) │ └──────────┬──────────┘ │ ┌──────────┴──────────────────────────────────┐ │ │ ▼ ▼┌──────────┐ ┌──────────────┐│ UI 组件 │ │ Hooks ││ (REPL等) │ │ (90+ hooks) │└──────────┘ └──────────────┘五、核心模块概要
5.1 入口与启动
|
|
|
|
|---|---|---|
|
|
src/entrypoints/cli.tsx |
|
|
|
src/main.tsx |
|
|
|
src/entrypoints/init.ts |
|
|
|
src/replLauncher.tsx |
|
|
|
src/screens/REPL.tsx |
|
5.2 核心引擎
|
|
|
|
|---|---|---|
|
|
src/query.ts |
|
|
|
src/QueryEngine.tsx |
|
|
|
src/Tool.ts |
|
|
|
src/tools.ts |
|
5.3 服务层
|
|
|
|
|---|---|---|
|
|
services/api/ |
|
|
|
services/compact/ |
|
|
|
services/mcp/ |
|
|
|
services/tools/ |
|
|
|
services/analytics/ |
|
|
|
services/lsp/ |
|
|
|
services/oauth/ |
|
|
|
services/plugins/ |
|
5.4 基础设施
|
|
|
|
|---|---|---|
|
|
utils/permissions/ |
|
|
|
utils/settings/ |
|
|
|
utils/hooks/ |
|
|
|
utils/telemetry/ |
|
|
|
utils/model/ |
|
六、关键设计决策
6.1 特性开关（Feature Flags）
使用 Bun 的编译时特性开关 feature('FLAG_NAME')，在构建时通过死代码消除（DCE）移除不需要的功能。build.ts 中定义了 60+ 个特性开关，实现：
-
• 内部 vs 外部构建: 内部版本（ant）包含额外的工具和服务 -
• 渐进式发布: 通过 GrowthBook 远程控制功能开关 -
• 平台差异化: 不同平台启用不同特性
6.2 工具系统设计
每个工具是一个独立目录，包含：
-
• XXXTool.ts— 工具实现（buildTool()工厂） -
• UI.tsx— 终端 UI 渲染 -
• prompt.ts— 系统提示词 -
• constants.ts— 常量
统一的 buildTool() 接口确保所有工具实现一致的权限检查、输入验证、执行和渲染逻辑。
6.3 上下文压缩策略
采用多层压缩策略管理上下文窗口：
-
1. Snip — 剪裁最早的历史消息 -
2. 微压缩（MicroCompact） — 压缩特定工具输出（不调用API） -
3. 上下文折叠（Context Collapse） — 将冗长输出折叠为摘要 -
4. 自动压缩（AutoCompact） — 使用 AI 生成摘要替代历史消息 -
5. 响应式压缩（ReactiveCompact） — 在 prompt-too-long 错误后触发
6.4 多后端 API 支持
API 层抽象了多个后端：
-
• 直连 — Anthropic API（OAuth/API Key） -
• AWS Bedrock — 通过 AWS SDK -
• Google Vertex AI — 通过 Google Auth -
• Azure Foundry — 通过 Azure 认证
6.5 安全架构
多层防御策略：
-
1. Zod schema 输入验证 -
2. 路径安全检查（UNC、设备文件、敏感目录） -
3. 可配置的 allow/deny/ask 规则 -
4. bypass 免疫的安全检查 -
5. Pre/Post 工具钩子 -
6. AI 安全分类器（Auto 模式） -
7. 危险命令模式检测
七、代码规模统计
|
|
|
|
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
八、文档导航
|
|
|
|
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|