Claude Code 源码深度解析:Anthropic 官方 AI 编程助手的架构设计与工程实践

导读

大家好，我是cici，12年北漂搜广推程序员，老家河南农村做题家，爱好读书写作，兼顾事业生活的八面手，致力于终身成长，过完幸福自洽的一生！关注我，一起成长！

作为一名程序员，今天带来一篇技术文章。本文能带来什么？

知道Claude Code的原理之后，能更好的使用它，比如上下文是如何管理的，就会明白多轮对话之后，效果衰减，不如新开一个对话。
找工作的时候是个加持项。

引言

2026年3月31日，Anthropic 官方 AI 编程助手 Claude Code 的完整源码意外泄露。由于 npm 发布时附带了包含完整源码的 source map 文件（cli.js.map，体积达57MB），开发者得以从 Anthropic 的 R2 存储桶下载到未混淆的 TypeScript 源码。还原后的代码库包含约1900个文件、超过70万行代码，为我们深入理解顶级 AI Agent 的架构设计提供了绝佳机会。

本文将从技术架构、核心子系统、设计模式等多个维度，对 Claude Code 进行全面剖析。

一、项目概览

1.1 Claude Code 是什么

Claude Code 是 Anthropic 推出的命令行 AI 编程助手，支持：

文件编辑与代码重构
Shell 命令执行
Git 工作流管理
代码审查与调试
多 Agent 协作
IDE 集成（VS Code、JetBrains）
Model Context Protocol (MCP) 协议支持

1.2 技术栈一览

类别	技术选型
运行时	Bun（非 Node.js）
语言	TypeScript（严格模式）
终端 UI	React + Ink（React for CLI）
CLI 解析	Commander.js
API 客户端	@anthropic-ai/sdk
Schema 验证	Zod v4
代码搜索	ripgrep
协议支持	MCP SDK、LSP
特性开关	GrowthBook
认证	OAuth 2.0、JWT、macOS Keychain
遥测	OpenTelemetry + gRPC

1.3 代码规模

文件数量：约 1,900 个
代码行数：512,000+ 行（核心源码）
主要目录结构：

src/├── main.tsx                 # 入口点（Commander.js CLI 解析器）├── QueryEngine.ts           # 核心 LLM API 引擎（~46K 行）├── Tool.ts                  # 工具类型定义（~29K 行）├── commands.ts              # 命令注册表（~25K 行）├── tools.ts                 # 工具注册表├── context.ts               # 系统/用户上下文收集├── cost-tracker.ts          # Token 成本追踪│├── tools/                   # Agent 工具实现（~40个）├── commands/                # 斜杠命令实现（~50个）├── components/              # Ink UI 组件（~140个）├── services/                # 外部服务集成├── hooks/                   # React Hooks├── types/                   # TypeScript 类型定义├── utils/                   # 工具函数├── screens/                 # 全屏 UI（Doctor、REPL、Resume）│├── bridge/                  # IDE 集成层├── coordinator/             # 多 Agent 协调器├── plugins/                 # 插件系统├── skills/                  # 技能系统├── server/                  # 服务器模式├── remote/                  # 远程会话├── memdir/                  # 持久化记忆目录├── tasks/                   # 任务管理├── state/                   # 状态管理├── voice/                   # 语音输入├── vim/                     # Vim 模式└── schemas/                 # 配置 Schema（Zod）

二、核心架构设计

2.1 整体架构

Claude Code 采用管道式架构，整个 UI 层基于 React + Ink 构建，使其成为完全响应式的 CLI 应用：

用户输入 → CLI 解析器 → 查询引擎 → LLM API → 工具执行循环 → 终端 UI

2.2 启动流程

入口点（src/main.tsx）：

使用 Commander.js 解析 CLI 参数和标志
启动并行预取副作用（MDM 设置、Keychain、API 预连接）
初始化 React/Ink 渲染器
交由 REPL 启动器（src/replLauncher.tsx）

初始化序列（src/entrypoints/）：

文件	职责
`cli.tsx`	CLI 会话编排——从启动到 REPL 的主路径
`init.ts`	配置、遥测、OAuth、MDM 策略初始化
`mcp.ts`	MCP 服务器模式入口
`sdk/`	Agent SDK——Claude Code 的编程式 API

启动时执行并行初始化：MDM 策略读取、Keychain 预取、特性标志检查，然后核心初始化。

2.3 查询引擎（QueryEngine.ts）

查询引擎是 Claude Code 的心脏，约46,000行代码，负责：

流式响应
：从 Anthropic API 接收流式数据
工具调用循环
：当 LLM 请求工具时，执行工具并将结果反馈
思考模式
：扩展思考与预算管理
重试逻辑
：针对瞬态故障的自动重试与退避
Token 计数
：跟踪输入/输出 token 和每轮成本
上下文管理
：管理对话历史和上下文窗口

2.4 状态管理

采用 React context + 自定义 store 模式：

组件	位置	用途
`AppState`	`src/state/AppStateStore.ts`	全局可变状态对象
Context Providers	`src/context/`	React context（通知、统计、FPS）
Selectors	`src/state/`	派生状态函数
Change Observers	`src/state/onChangeAppState.ts`	状态变化的副作用

AppState 对象传递给工具上下文，使工具能访问对话历史、设置和运行时状态。

三、工具系统（Tool System）

3.1 设计理念

每个工具都是自包含模块，定义了：

输入 Schema
：Zod 验证的参数
权限模型
：哪些操作需要用户批准
执行逻辑
：工具的实际实现
UI 组件
：调用和结果在终端中的渲染方式
并发安全
：是否可并行运行

3.2 工具定义模式

typescript
exportconstMyTool = buildTool({name: 'MyTool',aliases: ['my_tool'],description: '工具描述',inputSchema: z.object({param: z.string(),  }),asynccall(args, context, canUseTool, parentMessage, onProgress) {// 执行并返回 { data: result, newMessages?: [...] }  },asynccheckPermissions(input, context) { /* 权限检查 */ },isConcurrencySafe(input) { /* 可并行运行？ */ },isReadOnly(input) { /* 非破坏性？ */ },prompt(options) { /* 系统提示注入 */ },renderToolUseMessage(input, options) { /* 调用的 UI */ },renderToolResultMessage(content, progressMessages, options) { /* 结果的 UI */ },})

每个工具的目录结构：

src/tools/MyTool/├── MyTool.ts        # 主实现├── UI.tsx           # 终端渲染├── prompt.ts        # 系统提示贡献└── utils.ts         # 工具特定辅助函数

3.3 工具分类

文件系统工具

工具	描述	只读
FileReadTool	读取文件内容（文本、图片、PDF、笔记本）	✓
FileWriteTool	创建或覆盖文件	✗
FileEditTool	通过字符串替换进行部分文件修改	✗
GlobTool	查找匹配 glob 模式的文件	✓
GrepTool	使用 ripgrep 进行内容搜索	✓
NotebookEditTool	编辑 Jupyter notebook 单元格	✗
TodoWriteTool	写入结构化待办/任务文件	✗

Shell 与执行工具

工具	描述
BashTool	在 bash 中执行 shell 命令
PowerShellTool	执行 PowerShell 命令（Windows）
REPLTool	在 REPL 会话中运行代码（Python、Node 等）

Agent 与编排工具

工具	描述
AgentTool	为复杂任务生成子 Agent
SendMessageTool	Agent 间发送消息
TeamCreateTool / TeamDeleteTool	创建/删除并行 Agent 团队
EnterPlanModeTool / ExitPlanModeTool	切换规划模式
EnterWorktreeTool / ExitWorktreeTool	Git worktree 隔离
SleepTool	暂停执行（主动模式）
SyntheticOutputTool	生成结构化输出

任务管理工具

工具	描述
TaskCreateTool	创建后台任务
TaskUpdateTool	更新任务状态
TaskGetTool	获取任务详情
TaskListTool	列出所有任务
TaskOutputTool	获取已完成任务的输出
TaskStopTool	停止运行中的任务

Web 工具

工具	描述
WebFetchTool	从 URL 获取内容
WebSearchTool	搜索网络

MCP 工具

工具	描述
MCPTool	调用已连接 MCP 服务器上的工具
ListMcpResourcesTool	列出 MCP 服务器暴露的资源
ReadMcpResourceTool	读取特定 MCP 资源
McpAuthTool	处理 MCP 服务器认证
ToolSearchTool	发现 MCP 服务器的延迟/动态工具

集成工具

工具	描述
LSPTool	语言服务器协议操作（跳转定义、查找引用等）
SkillTool	执行已注册的技能

调度与触发工具

工具	描述
ScheduleCronTool	创建定时 cron 触发器
RemoteTriggerTool	触发远程触发器

四、命令系统（Command System）

4.1 命令类型

用户可通过 /command-name 在 REPL 中调用斜杠命令。三种类型：

类型	描述	示例
PromptCommand	向 LLM 发送格式化提示并注入工具	`/review` 、`/commit`
LocalCommand	进程内运行，返回纯文本	`/cost` 、`/version`
LocalJSXCommand	进程内运行，返回 React JSX	`/doctor` 、`/install`

4.2 主要命令

命令	描述
`/commit`	Git 提交
`/review`	代码审查
`/compact`	上下文压缩
`/mcp`	MCP 服务器管理
`/config`	设置
`/doctor`	环境诊断
`/login` / `/logout`	认证
`/memory`	持久化记忆
`/skills`	技能管理
`/tasks`	任务管理
`/vim`	Vim 模式切换
`/diff`	查看变更
`/cost`	检查使用成本
`/theme`	更改主题
`/context`	上下文可视化
`/share`	分享会话
`/pr_comments`	PR 评论
`/resume`	恢复会话
`/desktop`	桌面端移交
`/mobile`	移动端移交

五、核心子系统

5.1 Bridge（IDE 集成）

位置：src/bridge/

Bridge 是连接 Claude Code CLI 与 IDE 扩展（VS Code、JetBrains）的双向通信层。

架构：

┌──────────────────┐         ┌──────────────────────┐│   IDE Extension  │◄───────►│   Bridge Layer       ││  (VS Code, JB)   │  JWT    │  (src/bridge/)       ││                  │  Auth   │                      ││  - UI 渲染       │         │  - 会话管理          ││  - 文件监视      │         │  - 消息路由          ││  - Diff 显示     │         │  - 权限代理          │└──────────────────┘         └──────────┬───────────┘                                        │                                        ▼                              ┌──────────────────────┐                              │   Claude Code Core   │                              │  (QueryEngine, Tools)│                              └──────────────────────┘

关键文件：

文件	用途
`bridgeMain.ts`	主桥接循环
`bridgeMessaging.ts`	消息协议（序列化/反序列化）
`bridgePermissionCallbacks.ts`	将权限提示路由到 IDE
`jwtUtils.ts`	CLI 与 IDE 间的 JWT 认证
`sessionRunner.ts`	管理桥接会话执行

5.2 MCP（Model Context Protocol）

位置：src/services/mcp/

Claude Code 既可作为 MCP 客户端（消费 MCP 服务器的工具/资源），也可作为 MCP 服务器（通过 src/entrypoints/mcp.ts 暴露自己的工具）。

客户端功能：

工具发现：枚举已连接 MCP 服务器的工具
资源浏览：列出和读取 MCP 暴露的资源
动态工具加载：ToolSearchTool 在运行时发现工具
认证：McpAuthTool 处理 MCP 服务器认证流程

5.3 权限系统

位置：src/hooks/toolPermission/

每个工具调用在执行前都经过集中权限检查。

权限模式：

模式	行为
`default`	对每个潜在破坏性操作提示用户
`plan`	显示完整执行计划，一次性批量批准
`bypassPermissions`	自动批准所有操作（危险——仅用于可信环境）
`auto`	基于 ML 的分类器自动决定（实验性）

权限规则使用通配符模式：

Bash(git *)           # 允许所有 git 命令无需提示Bash(npm test)        # 特定允许 'npm test'FileEdit(/src/*)      # 允许编辑 src/ 下的任何内容FileRead(*)           # 允许读取任何文件

5.4 插件系统

位置：src/plugins/、src/services/plugins/

支持可安装插件扩展能力。

插件生命周期：

发现——扫描插件目录和市场
安装——下载并注册（/plugin 命令）
加载——启动时或按需初始化
执行——插件可贡献工具、命令和提示
自动更新——usePluginAutoupdateNotification 处理更新

5.5 技能系统（Skill System）

位置：src/skills/

技能是可复用的命名工作流，捆绑提示和工具配置用于特定任务。

内置技能（16个）：

技能	用途
`batch`	跨多文件的批量操作
`debug`	调试工作流
`loop`	迭代精化循环
`remember`	将信息持久化到记忆
`simplify`	简化复杂代码
`skillify`	从工作流创建新技能
`stuck`	卡住时获得帮助
`verify` / `verifyContent`	验证代码正确性

5.6 任务系统

位置：src/tasks/

管理后台和并行工作项。

任务类型：

类型	用途
LocalShellTask	后台 shell 命令执行
LocalAgentTask	本地运行的子 Agent
RemoteAgentTask	远程机器上运行的 Agent
InProcessTeammateTask	并行队友 Agent
DreamTask	后台"做梦"过程

5.7 记忆系统（Memory System）

位置：src/memdir/

基于 CLAUDE.md 文件的持久化记忆系统。

记忆层次：

范围	位置	用途
项目记忆	项目根目录的 `CLAUDE.md`	项目特定事实、约定
用户记忆	`~/.claude/CLAUDE.md`	用户偏好、跨项目
提取记忆	`src/services/extractMemories/`	从对话中自动提取
团队记忆同步	`src/services/teamMemorySync/`	共享团队知识

5.8 协调器（Coordinator）

位置：src/coordinator/

编排多个 Agent 并行处理任务的不同方面。

coordinatorMode.ts
管理协调器生命周期
TeamCreateTool
和 TeamDeleteTool 管理 Agent 团队
SendMessageTool
启用 Agent 间通信
AgentTool
生成子 Agent

5.9 语音系统

位置：src/voice/

免提交互的语音输入/输出支持。

组件：

语音服务（src/services/voice.ts）
STT 流式传输（src/services/voiceStreamSTT.ts）
关键词（src/services/voiceKeyterms.ts）
语音命令（src/commands/voice/）

六、设计模式与工程亮点

6.1 并行预取（Parallel Prefetch）

启动优化——MDM 设置、Keychain 读取和 API 预连接作为副作用在重模块评估前并行触发：

typescript
// main.tsxstartMdmRawRead()startKeychainPrefetch()

6.2 懒加载（Lazy Loading）

重度模块通过动态 import() 延迟加载：

OpenTelemetry（~400KB）
gRPC（~700KB）

6.3 特性标志与死代码消除

Bun 的 bun:bundle 特性标志在构建时启用死代码消除：

typescript
import { feature } from'bun:bundle'if (feature('PROACTIVE')) {// 主动 Agent 工具}

主要特性标志：

标志	功能
`PROACTIVE`	主动 Agent 模式（自主行动）
`KAIROS`	Kairos 子系统
`BRIDGE_MODE`	IDE 桥接集成
`DAEMON`	后台守护进程模式
`VOICE_MODE`	语音输入/输出
`AGENT_TRIGGERS`	触发 Agent 动作
`COORDINATOR_MODE`	多 Agent 协调器
`WORKFLOW_SCRIPTS`	工作流自动化脚本

6.4 Agent 群（Agent Swarms）

通过 AgentTool 生成子 Agent，coordinator/ 处理编排。TeamCreateTool 启用团队级并行工作。

6.5 React for CLI

整个 UI 层使用 React + Ink 构建，享受：

组件化开发
Hooks 模式
响应式更新
React Compiler 优化

6.6 Schema 驱动验证

所有输入验证使用 Zod v4，在系统边界进行强类型检查。

七、服务层

位置：src/services/

服务	用途
API	Anthropic SDK 客户端、文件上传、引导
MCP	MCP 客户端连接和工具发现
OAuth	OAuth 2.0 认证流程
LSP	语言服务器协议管理器
Analytics	GrowthBook 特性标志、遥测、事件
Plugins	插件加载器和市场
Compact	对话上下文压缩
Policy Limits	组织速率限制/配额
Remote Settings	企业托管设置同步
Token Estimation	Token 计数估算
Team Memory	团队知识同步

八、配置与迁移

配置位置：

全局：~/.claude/config.json、~/.claude/settings.json
项目：.claude/config.json、.claude/settings.json
系统：macOS Keychain + MDM、Windows Registry + MDM
托管：企业用户的远程同步

迁移（src/migrations/）：处理版本间配置格式变更——读取旧配置并转换为当前 schema。

九、关键文件解析

文件	行数	用途
`QueryEngine.ts`	~46K	核心 LLM API 引擎——流式传输、工具循环、思考模式、重试、Token 计数
`Tool.ts`	~29K	所有工具的基础类型/接口——输入 schema、权限、进度状态
`commands.ts`	~25K	命令注册与执行，带条件性环境导入
`main.tsx`	—	CLI 解析器 + React/Ink 渲染器；启动时并行化 MDM、Keychain、GrowthBook

十、总结与启示

10.1 架构亮点

终端原生 React 应用
：将现代前端框架思想引入 CLI，实现组件化、响应式的终端 UI
工具化架构
：每个能力都是自包含工具，具有清晰的接口、权限模型和 UI 渲染
多 Agent 协作
：内置协调器支持 Agent 群、团队并行工作
协议优先
：MCP 和 LSP 协议支持，实现生态互联
企业级安全
：完善的权限系统、MDM 集成、OAuth 认证

10.2 工程实践

性能优化
：并行预取、懒加载、死代码消除
类型安全
：TypeScript 严格模式 + Zod schema 验证
可扩展性
：插件系统、技能系统、MCP 协议
可观测性
：OpenTelemetry 遥测、成本追踪、诊断工具

10.3 对 AI Agent 开发的启示

工具抽象是核心
：将每个能力抽象为标准化工具，便于组合和扩展
权限模型不可少
：AI Agent 执行操作必须有清晰的权限边界
多 Agent 协作是趋势
：复杂任务需要多个专业 Agent 协同完成
记忆系统是关键
：持久化记忆让 Agent 具备长期上下文
协议标准化
：MCP 等协议让 Agent 能够接入外部工具生态

参考资料

Claude Code 源码快照：https://github.com/777genius/claude-code-source-code-full
架构文档：docs/architecture.md
工具参考：docs/tools.md
子系统指南：docs/subsystems.md
命令参考：docs/commands.md

声明：本文基于公开泄露的源码快照进行技术分析，仅用于学习和研究目的。Claude Code 的原始源码为 Anthropic 所有，本文不授予任何权利。