Claude Code 源码架构深度解析报告

一、项目概述

Claude Code 是 Anthropic 推出的终端原生 AI 编程助手 CLI，支持通过自然语言与 AI 模型交互来完成代码编写、文件操作、命令执行等开发任务。本项目是从 @anthropic-ai/claude-code npm 包的 source map 中还原的完整 TypeScript 源码，可本地运行。

核心特性

🖥️ 终端 TUI：基于 React + Ink 的富交互终端界面（148+ 组件）
🤖 53+ 内置工具：Bash、文件读写、代码编辑、Web 搜索、MCP 工具等
🔌 MCP 协议：完整的 Model Context Protocol 客户端/服务器支持
🧠 多 Agent 编排：Coordinator 模式、子 Agent、后台任务
💬 87+ 斜杠命令：/buddy、/ultraplan、/compact、/cost 等
🎭 7 大隐藏功能：BUDDY 宠物、KAIROS 持久助手、ULTRAPLAN 云端规划等
🔒 三层门控：编译开关（50+）、用户类型（ant/external）、GrowthBook 远程开关

二、整体技术架构图

graph TB subgraph 入口层 A1[dev-entry.ts 开发启动器] A2[main.tsx 主入口 CLI] A3[QueryEngine.ts 无头/SDK 模式] A4[entrypoints/sdk SDK 入口] end subgraph CLI层["CLI 层 (Commander)"] B1[commands.ts 命令注册中心 87+ 命令] B2[commands/* 各命令实现] end subgraph 核心引擎层 C1[query.ts API 通信核心] C2[QueryEngine.ts 无头查询引擎] C3[Tool.ts / tools.ts 工具系统] C4[context.ts 系统上下文构建] end subgraph 工具层["工具层 (53+ Tools)"] D1[AgentTool 子 Agent 编排] D2[BashTool 命令执行] D3[FileEditTool 文件编辑] D4[FileReadTool 文件读取] D5[FileWriteTool 文件写入] D6[WebFetchTool 网页抓取] D7[WebSearchTool Web 搜索] D8[MCPTool MCP 工具桥接] D9[SkillTool 技能系统] D10[TodoWriteTool Todo 管理] D11[更多工具...] end subgraph MCP层["MCP 协议层"] E1[services/mcp/client.ts MCP 客户端] E2[services/mcp/config.ts MCP 配置管理] E3[services/mcp/types.ts MCP 类型定义] end subgraph UI层["TUI 层 (React + Ink)"] F1[ink/ Ink 渲染引擎] F2[components/ 148+ UI 组件] F3[REPL.tsx 主交互循环] end subgraph 状态管理层 G1[state/AppStateStore.ts 应用状态] G2[state/store.ts Store 管理] G3[bootstrap/state.ts 启动状态] end subgraph 高级功能层 H1[coordinator/ 多 Agent 编排] H2[assistant/ KAIROS 持久助手] H3[buddy/ 虚拟宠物系统] H4[bridge/ WebSocket 远程控制] H5[voice/ 语音交互] H6[proactive/ 主动模式] H7[vim/ Vim 模式] end subgraph 服务层 I1[services/api/ Anthropic API] I2[services/analytics/ 遥测分析] I3[services/compact/ 上下文压缩] I4[services/mcp/ MCP 服务] I5[services/autoDream/ 自动记忆整合] end A1 --> A2 A2 --> B1 A3 --> C2 B1 --> B2 B2 --> C1 C1 --> C3 C3 --> D1 C3 --> D2 C3 --> D3 D8 --> E1 E1 --> E2 A2 --> F3 F3 --> F1 F1 --> F2 C1 --> G1 F3 --> G1 H1 --> D1 H2 --> G1 H3 --> F2 H4 --> I1 C1 --> I1 I1 --> I2 I1 --> I3 style 入口层 fill:#e1f5fe style 核心引擎层 fill:#f3e5f5 style 工具层 fill:#e8f5e9 style MCP层 fill:#fff3e0 style UI层 fill:#fce4ec style 高级功能层 fill:#f3e5f5

三、系统启动流程图

flowchart TD START([用户执行 claude 命令]) --> CHECK_DEBUG{调试模式?} CHECK_DEBUG -->|是| EXIT_DEBUG[退出: 非内部用户禁止调试] CHECK_DEBUG -->|否| EAGER_LOAD[提前加载设置标志 eagerLoadSettings] EAGER_LOAD --> ENTRY_DETECT{判断入口类型} ENTRY_DETECT -->|cc:// URL| DIRECT_CONNECT[直连模式 DIRECT_CONNECT] ENTRY_DETECT -->|assistant| ASSISTANT_MODE[KAIROS 助手模式] ENTRY_DETECT -->|ssh| SSH_MODE[SSH 远程模式] ENTRY_DETECT -->|普通 CLI| CLI_MODE[标准 CLI 模式] CLI_MODE --> SET_INTERACTIVE[设置交互/非交互标志] SET_INTERACTIVE --> PRE_ACTION[Commander preAction 钩子] PRE_ACTION --> MDM_LOAD[加载 MDM 设置] MDM_LOAD --> KEYCHAIN[等待 Keychain 预取] KEYCHAIN --> INIT[init 初始化] INIT --> INIT_TELEMETRY[初始化遥测] INIT --> INIT_CONFIG[加载配置文件] INIT --> INIT_AUTH[认证初始化] INIT --> INIT_GROWTHBOOK[初始化 GrowthBook] INIT --> MIGRATIONS[运行数据库迁移 CURRENT_MIGRATION_VERSION=11] MIGRATIONS --> REMOTE_SETTINGS[加载远程管理设置] REMOTE_SETTINGS --> POLICY_LIMITS[加载策略限制] POLICY_LIMITS --> SETUP[setup 函数] SETUP --> APPLY_SETTINGS[应用设置到环境变量] APPLY_SETTINGS --> INIT_PERMISSIONS[初始化权限上下文] INIT_PERMISSIONS --> CHECK_MODE{运行模式?} CHECK_MODE -->|交互模式| REPL[启动 REPL renderAndRun] CHECK_MODE -->|打印模式 -p| PRINT[运行无头查询 runHeadless] CHECK_MODE -->|SDK 模式| SDK[SDK 查询引擎] REPL --> RENDER[React + Ink 渲染] RENDER --> INPUT_LOOP[用户输入循环] INPUT_LOOP --> CMD_CHECK{是斜杠命令?} CMD_CHECK -->|是| EXEC_CMD[执行命令处理器] CMD_CHECK -->|否| SEND_QUERY[发送到 Query 引擎] SEND_QUERY --> API_CALL[调用 Anthropic API] API_CALL --> STREAM[流式响应处理] STREAM --> TOOL_CALL{有工具调用?} TOOL_CALL -->|是| EXEC_TOOL[执行工具] TOOL_CALL -->|否| SHOW_OUTPUT[显示输出] EXEC_TOOL --> PERMISSION{权限检查} PERMISSION -->|允许| RUN_TOOL[运行工具] PERMISSION -->|询问| ASK_USER[询问用户] PERMISSION -->|拒绝| DENY[拒绝工具调用] RUN_TOOL --> TOOL_RESULT[工具结果] TOOL_RESULT --> STREAM SHOW_OUTPUT --> INPUT_LOOP ASK_USER -->|允许| RUN_TOOL ASK_USER -->|拒绝| DENY DENY --> INPUT_LOOP style START fill:#c8e6c9 style REPL fill:#bbdefb style API_CALL fill:#fff9c4 style EXEC_TOOL fill:#e1bee7

四、核心查询引擎时序图

sequenceDiagram participant U as 用户 participant REPL as REPL.tsx participant QE as QueryEngine participant Q as query.ts participant API as Anthropic API participant Tool as 工具系统 participant MCP as MCP Client participant Perm as 权限系统 U->>REPL: 输入消息 REPL->>QE: 调用 query(prompt, options) QE->>QE: 构建 ToolUseContext QE->>QE: 获取系统上下文 (context.ts) QE->>QE: 加载 CLAUDE.md 记忆文件 QE->>QE: 准备工具列表 (getTools) QE->>QE: 规范化消息 (normalizeMessagesForAPI) QE->>API: 发送 API 请求 (messages.stream) API-->>QE: 返回流式响应 loop 流式处理每个事件 QE->>QE: 处理 SSE 事件 alt 收到 text_delta (文本流) QE->>REPL: 更新文本显示 else 收到 tool_use (工具调用) QE->>QE: 解析工具参数 QE->>Perm: checkPermissions (权限检查) alt 权限允许 QE->>Tool: 执行工具 (call) Tool->>Tool: 显示权限对话框 (如需要) Tool->>MCP: (如为 MCP 工具) 调用 MCP 服务器 MCP-->>Tool: 返回 MCP 结果 Tool-->>QE: 返回 ToolResult QE->>API: 发送 tool_result 继续对话 else 权限拒绝 QE->>QE: 记录拒绝原因 QE->>API: 发送拒绝结果 end else 收到 thinking (思考过程) QE->>REPL: 更新思考显示 else 收到 error (错误) QE->>QE: 错误处理 + 重试 end end QE->>QE: 累积 usage 统计 QE->>REPL: 返回最终消息列表 REPL->>U: 显示 Assistant 回复 Note over QE,API: 自动压缩 (Auto-Compact) 当上下文接近限制时触发 QE->>QE: 检查 token 使用量 alt 超过阈值 QE->>API: 发送压缩请求 API-->>QE: 返回压缩后摘要 QE->>QE: 重建消息历史 end

五、工具系统架构

classDiagram class Tool { <<interface>> +name: string +aliases?: string[] +inputSchema: ZodType +isEnabled(): boolean +isReadOnly(input): boolean +isDestructive(input): boolean +isConcurrencySafe(input): boolean +call(input, context, canUseTool, parentMessage): Promise~ToolResult~ +description(input, options): Promise~string~ +checkPermissions(input, context): Promise~PermissionResult~ +renderToolUseMessage(input, options): ReactNode +renderToolResultMessage(output, progress, options): ReactNode +validateInput(input, context): Promise~ValidationResult~ } class BashTool { +name = "bash" +call(): 执行 Shell 命令 +checkPermissions(): 检查命令安全 } class FileEditTool { +name = "edit" +call(): 编辑文件 (旧版) } class AgentTool { +name = "agent" +call(): 启动子 Agent +built-in agents: 通用、后端、前端等 } class MCPTool { +isMcp = true +mcpInfo: serverName + toolName +call(): 代理到 MCP 服务器 } class SkillTool { +name = "skill" +call(): 执行技能脚本 } class WebFetchTool { +name = "web_fetch" +call(): 抓取网页内容 } Tool <|.. BashTool Tool <|.. FileEditTool Tool <|.. AgentTool Tool <|.. MCPTool Tool <|.. SkillTool Tool <|.. WebFetchTool class ToolUseContext { +options: ToolUseContextOptions +abortController: AbortController +readFileState: FileStateCache +getAppState(): AppState +setAppState(f): void +setToolJSX(): void +messages: Message[] } class ToolResult { +data: T +newMessages?: Message[] +contextModifier?: Function +mcpMeta?: Record } Tool ..> ToolUseContext : 使用 Tool ..> ToolResult : 返回

六、权限系统架构

flowchart TD START[工具调用请求] --> VALIDATE[validateInput] VALIDATE -->|失败| DENY[拒绝 + 错误信息] VALIDATE -->|通过| CHECK_PERM[checkPermissions] CHECK_PERM --> MODE{权限模式?} MODE -->|default| ASK[询问用户] MODE -->|plan| PLAN_CHECK{是否是计划模式?} MODE -->|acceptEdits| AUTO_ALLOW[自动允许编辑类] MODE -->|bypass| AUTO_ALLOW_ALL[自动允许全部] PLAN_CHECK -->|是| ASK PLAN_CHECK -->|否| PROCEED[继续] ASK --> USER_DECIDE{用户决定?} USER_DECIDE -->|允许| ALLOW[执行工具] USER_DECIDE -->|拒绝| DENY USER_DECIDE -->|始终允许| REMEMBER[记住规则] REMEMBER --> ALLOW AUTO_ALLOW --> CHECK_RULES{检查规则?} CHECK_RULES -->|有匹配| APPLY_RULE[应用规则] CHECK_RULES -->|无匹配| ALLOW APPLY_RULE --> ALLOW ALLOW --> EXEC[执行工具调用] EXEC --> RESULT[返回结果] DENY --> DENY_RESULT[返回拒绝] RESULT --> DONE([完成]) DENY_RESULT --> DONE subgraph 权限规则来源 R1[alwaysAllowRules 始终允许] R2[alwaysDenyRules 始终拒绝] R3[alwaysAskRules 始终询问] R4[additionalWorkingDirectories 额外工作目录] end style START fill:#e1f5fe style DENY fill:#ffcdd2 style ALLOW fill:#c8e6c9 style ASK fill:#fff9c4

七、MCP (Model Context Protocol) 集成架构

graph LR subgraph ClaudeCode["Claude Code CLI"] A[工具系统] B[MCPTool] C[工具发现] end subgraph MCPClient["MCP 客户端 (services/mcp)"] D[client.ts 客户端管理] E[config.ts 配置解析] F[types.ts 类型定义] G[utils.ts 工具过滤] end subgraph 传输层 H[StdioClientTransport 标准输入输出] I[StreamableHTTPClientTransport HTTP 传输] J[SSEClientTransport SSE 传输] end subgraph MCPServers["MCP 服务器"] K[文件系统服务器] L[数据库服务器] M[自定义服务器] N[官方注册表服务器] end A --> B B --> D D --> H D --> I D --> J H --> K I --> N J --> L D --> E E --> F C --> D D --> G G --> A style ClaudeCode fill:#e3f2fd style MCPClient fill:#f3e5f5 style 传输层 fill:#fff3e0

八、多 Agent 编排 (Coordinator) 架构

graph TB subgraph Coordinator模式 C[Coordinator Agent 纯指挥官] W1[Worker Agent 1 完整工具集] W2[Worker Agent 2 完整工具集] WN[Worker Agent N] end subgraph 任务管理 T[tasks/*.ts 任务状态管理] F[taskFile ~/.claude/tasks/] end subgraph 通信机制 SM[SendMessageTool Agent 间通信] TF[TaskFile 共享 任务列表] end C -->|派发任务| W1 C -->|派发任务| W2 C -->|派发任务| WN W1 -->|汇报进度| C W2 -->|汇报进度| C WN -->|汇报进度| C C --> SM W1 --> SM C --> T W1 --> T T --> F W1 -->|独立进程| W1_PROC[子进程] W2 -->|独立进程| W2_PROC[子进程] style C fill:#bbdefb style W1 fill:#c8e6c9 style W2 fill:#c8e6c9 style WN fill:#c8e6c9

九、状态管理体系结构

graph TD subgraph "状态存储" S1[AppStateStore.ts] S2[store.ts] -->|创建| S1 S3[bootstrap/state.ts] -->|初始化加载| S1 end subgraph "状态内容" A1[settings] & A2[verbose] & A3[mainLoopModel] & A4[mcp] & A5[messages] & A6[tasks] & A7[permissionContext] & A8[teammates] end S1 --- A1 & A2 & A3 & A4 & A5 & A6 & A7 & A8 subgraph "状态更新" U1[setAppState] --> S1 U2[setAppStateForTasks] --> S1 U3[React setState] -->|调用| U1 end subgraph "持久化" P1[(sessionStorage)] P2[(~/.claude/projects/cwd/)] P3[(.claude/settings.json)] end S1 -- 写入会话 --> P1 P1 -- 恢复会话 --> S1 S1 -- 写入项目文件 --> P2 P2 -- 加载项目状态 --> S1 A1 -- 读写 --> P3

十、项目目录结构详解

ClaudeCode-main/
├── src/
│   ├── main.tsx                    # 主入口 (Commander + React)
│   ├── dev-entry.ts               # 开发启动器
│   ├── QueryEngine.ts             # 无头查询引擎
│   ├── query.ts                   # 核心查询逻辑 (API 通信)
│   ├── Tool.ts                    # 工具类型定义
│   ├── tools.ts                   # 工具注册与组装
│   ├── commands.ts                # 命令注册中心
│   ├── context.ts                 # 系统上下文构建
│   ├── tasks.ts                   # 任务类型定义
│   │
│   ├── tools/                    # 53+ 工具实现
│   │   ├── AgentTool/            # 子 Agent 工具
│   │   ├── BashTool/             # Bash 命令执行
│   │   ├── FileEditTool/         # 文件编辑
│   │   ├── FileReadTool/         # 文件读取
│   │   ├── FileWriteTool/        # 文件写入
│   │   ├── GlobTool/             # 文件搜索
│   │   ├── GrepTool/             # 内容搜索
│   │   ├── WebFetchTool/         # 网页抓取
│   │   ├── WebSearchTool/        # Web 搜索
│   │   ├── MCPTool/              # MCP 工具桥接
│   │   ├── SkillTool/            # 技能系统
│   │   ├── TodoWriteTool/        # Todo 管理
│   │   ├── TaskCreateTool/       # 任务创建
│   │   ├── ScheduleCronTool/     # Cron 调度
│   │   └── ...
│   │
│   ├── commands/                 # 87+ 斜杠命令
│   │   ├── compact/              # 上下文压缩
│   │   ├── config/               # 配置管理
│   │   ├── resume/               # 恢复会话
│   │   ├── cost/                 # 成本统计
│   │   ├── mcp/                  # MCP 管理
│   │   ├── skills/               # 技能管理
│   │   └── ...
│   │
│   ├── services/                 # 后端服务
│   │   ├── api/                  # Anthropic API 通信
│   │   │   ├── claude.ts        # API 调用封装
│   │   │   ├── bootstrap.ts     # 启动数据获取
│   │   │   └── filesApi.ts      # 文件 API
│   │   ├── mcp/                 # MCP 协议服务
│   │   │   ├── client.ts        # MCP 客户端
│   │   │   ├── config.ts        # MCP 配置
│   │   │   └── types.ts         # MCP 类型
│   │   ├── analytics/            # 遥测分析
│   │   ├── compact/              # 上下文压缩
│   │   ├── autoDream/            # 自动记忆整合
│   │   └── lsp/                 # LSP 服务器
│   │
│   ├── components/               # 148+ React/Ink UI 组件
│   │   ├── PromptInput/          # 输入组件
│   │   ├── Settings/             # 设置界面
│   │   ├── HelpV2/               # 帮助系统
│   │   ├── StructuredDiff/       # 差异显示
│   │   ├── permissions/           # 权限对话框
│   │   ├── mcp/                  # MCP UI
│   │   └── ...
│   │
│   ├── ink/                      # Ink 渲染引擎 (自定义)
│   │   ├── ink.tsx               # 主渲染器
│   │   ├── components/           # Ink 基础组件
│   │   ├── hooks/                # Ink Hooks
│   │   ├── layout/               # 布局引擎 (Yoga)
│   │   └── termio/               # 终端 I/O
│   │
│   ├── state/                    # 状态管理
│   │   ├── AppStateStore.ts      # 应用状态
│   │   └── store.ts              # Store 创建
│   │
│   ├── coordinator/              # 多 Agent 编排
│   │   └── coordinatorMode.ts
│   │
│   ├── assistant/                # KAIROS 持久助手
│   │   ├── index.ts
│   │   ├── sessionDiscovery.ts
│   │   └── sessionHistory.ts
│   │
│   ├── buddy/                    # 虚拟宠物系统
│   │
│   ├── bridge/                   # WebSocket 远程控制
│   │
│   ├── voice/                    # 语音交互
│   │
│   ├── vim/                      # Vim 模式
│   │
│   ├── hooks/                    # 87+ 自定义 Hooks
│   │
│   ├── utils/                    # 工具函数
│   │   ├── permissions/          # 权限工具
│   │   ├── config.ts             # 配置读取
│   │   ├── auth.ts               # 认证工具
│   │   ├── model/                # 模型管理
│   │   ├── sandbox/              # 沙箱管理
│   │   └── ...
│   │
│   ├── entrypoints/              # 入口点
│   │   ├── sdk/                  # SDK 入口
│   │   └── init.ts               # 初始化
│   │
│   ├── skills/                   # 技能系统
│   │   └── bundled/              # 内置技能
│   │
│   ├── plugins/                   # 插件系统
│   │   └── bundled/              # 内置插件
│   │
│   ├── migrations/               # 数据库迁移
│   │
│   ├── types/                    # TypeScript 类型
│   │
│   └── constants/                # 常量定义
│
├── shims/                        # 原生模块兼容层
├── vendor/                       # 原生绑定源码
├── docs/                         # 文档 (7 大隐藏功能解析)
├── xiaohongshu/                 # 小红书相关
├── package.json                  # 项目配置
├── tsconfig.json                 # TypeScript 配置
└── README.md                     # 项目说明

十一、关键技术栈

技术	用途
TypeScript	主要开发语言
React 19	UI 组件系统
Ink 5	终端 UI 渲染引擎 (自定义分支)
Bun	运行时 + 打包器 (≥1.3.5)
Node.js	兼容运行时 (≥24)
@anthropic-ai/sdk	Anthropic API SDK
@modelcontextprotocol/sdk	MCP 协议 SDK
Commander.js	CLI 命令框架
Zod	运行时类型验证
Yoga Layout	终端布局引擎
GrowthBook	特性开关远程管理
ws	WebSocket 客户端/服务器

十二、核心数据流

flowchart LR A[用户输入] --> B[REPL 主循环] B --> C[消息队列] C --> D[QueryEngine] D --> E[API 请求构建] E --> F[Anthropic API] F --> G[流式响应解析] G --> H{事件类型?} H -->|text_delta| I[累积文本] H -->|tool_use| J[工具调用队列] H -->|thinking| K[思考过程] H -->|error| L[错误处理] J --> M[权限检查] M -->|通过| N[执行工具] M -->|拒绝| O[返回拒绝] N --> P[工具结果] P --> Q[继续 API 流] I --> R[显示输出] Q --> G R --> S[等待下一条输入] style A fill:#e1f5fe style F fill:#fff9c4 style N fill:#c8e6c9

十三、特性门控系统

graph TD subgraph 第一层["第一层: 编译时开关 (50+)"] F1[feature'BUDDY' 宠物系统] F2[feature'KAIROS' 持久助手] F3[feature'COORDINATOR_MODE' 多Agent编排] F4[feature'ULTRAPLAN' 云端规划] F5[feature'BRIDGE_MODE' 远程控制] F6[feature'VOICE_MODE' 语音模式] F7[更多...] end subgraph 第二层["第二层: 用户类型"] U1[USER_TYPE === 'ant' Anthropic 内部 全部功能] U2[USER_TYPE === 'external' 外部用户 裁剪版] end subgraph 第三层["第三层: GrowthBook 远程开关"] G1[tengu_kairos KAIROS开关] G2[tengu_ultraplan_model 模型选择] G3[tengu_session_memory 会话记忆] G4[更多...] end F1 --> U1 F2 --> U1 U1 --> G1 U2 -->|部分| G1 style 第一层 fill:#e3f2fd style 第二层 fill:#f3e5f5 style 第三层 fill:#fff3e0

十四、总结

Claude Code 是一个架构复杂、功能丰富的终端 AI 编程助手，其源码揭示了：

React + Ink 终端 UI 架构：148+ 组件构成的完整 TUI 系统
强大的工具系统：53+ 内置工具 + 无限 MCP 工具扩展
多 Agent 编排能力：Coordinator 模式支持复杂任务分解
三层门控系统：编译开关 + 用户类型 + 远程特性开关
完整的 MCP 协议支持：客户端/服务器、多种传输层
丰富的隐藏功能：BUDDY 宠物、KAIROS 持久助手等创新功能
企业级权限管理：细粒度权限控制 + 规则系统
会话管理与持久化：完整的会话生命周期管理