Claude Code 源码深度分析

项目概览

Claude Code 是 Anthropic 推出的命令行 AI 编程助手，支持终端交互、代码编辑、Git 操作、多 Agent 协作等能力。本文档对其源码进行系统性分析，产出 20 份 HTML 分析文档，覆盖从启动链路到外部集成的全部核心模块。

1,884

TypeScript 文件

512K

行代码

20

分析文档

六层架构全景

Claude Code 采用清晰的分层架构。每一层内展示了该层的核心模块及其关键能力。

Layer 1 — 入口层

main.tsx

CLI 参数解析快速路径分发--version/--print--resume 恢复

setup.ts

项目初始化MCP 预加载Git 检测Hooks 快照

bootstrap/state.ts

AppState 全局状态Store<T> 响应式容器CWD 管理

replLauncher.tsx

REPL 启动动态 import按需加载 App/Screens

entrypoints/

SDK 入口CLI 入口多模式路由分发

▼

Layer 2 — 编排层

QueryEngine.ts (1296行)

submitMessage()权限决策包裹会话持久化先于API消息标准化/回放结构化输出预算检查错误恢复协调

query.ts (1730行)

while(true) 查询循环4级压缩管线流式并发工具执行模型降级链延迟错误恢复死亡螺旋防护不可变状态替换

coordinator/

MCP 客户端协调Scratchpad 管理用户上下文注入

interactiveHelpers

Trust 边界编排用户交互状态机权限确认流程

dialogLaunchers

对话框触发器权限确认 UIElicitation 回调

▼

Layer 3 — 工具/任务层

Tool.ts (793行)

buildTool() 工厂Fail-Closed 默认值inputSchema (Zod)权限检查并发安全只读/可撤销标记

tools/ (30+ 工具)

BashToolFileRead/Edit/WriteGrepToolGlobToolWebSearchToolNotebookEditSkillToolMCPTool

tasks/ (5 种任务)

LocalAgentTaskLocalShellTaskRemoteAgentTaskInProcessTeammateTaskDreamTask独立生命周期

AgentTool (1398行)

团队协作路由远程调度Fork 模式异步/同步分支

SendMessage

点对点通信广播关闭协商计划审批

▼

Layer 4 — 扩展层

services/mcp/ (26文件)

多传输支持7种连接配置5种连接状态认证缓存16ms 批量合并指数退避重连

plugins/

插件发现/加载/验证Chokidar 热重载版本化缓存隔离功能门控

skills/

Bundled → 目录 → 插件 → MCP条件激活动态发现

server/

MCP 服务端内嵌协议实现能力声明

commands/ (70+)

3种命令类型promptlocallocal-jsx参数解析

▼

Layer 5 — 服务层

context.ts

上下文构建系统提示组装Git 信息注入环境感知

services/compact

4级压缩管线Snip 裁剪Microcompact 缓存编辑Context Collapse 折叠Autocompact 全量摘要

services/api

Claude API 客户端流式响应重试策略Fallback 模型切换

services/oauth

OAuth PKCEXAA 企业认证Token 刷新安全存储

services/analytics

OTel 双通道Perfetto 追踪事件埋点性能分析

services/SessionMemory

会话记忆记忆提取跨会话知识保留

services/lsp

LSP 客户端管理诊断信息收集代码智能

cost-tracker.ts

Token 成本追踪多级阈值告警预算管理Usage 统计

▼

Layer 6 — 基础层

utils/git

分支/状态检测Diff 解析Commit 生成Worktree 管理

utils/permissions

6种权限模式13步决策链规则白名单AI 自动分类器

utils/sandbox

文件系统沙盒安全路径验证绕过免疫沙盒适配器层

utils/shell + bash

Shell 执行引擎进程管理信号处理超时控制

utils/memory

MEMORY.md 读写版本化存储嵌套记忆加载

hooks/ (50+ Hook)

React Hook 生态通知 Hook工具合并决策树权限 Hook

ink/ (终端渲染)

Yoga 布局引擎双缓冲差分渲染事件系统TermIO

native-ts/

color-diff 语法高亮file-index 模糊搜索yoga-layout 布局计算

核心数据流 — 一次查询的旅程

用户输入经过 7 个关键阶段，最终变为终端上的响应。

用户输入

PromptInput

➔

QueryEngine

构建上下文

➔

API 调用

流式响应

➔

工具调度
匹配 & 执行

➔

结果收集

循环或终止

➔

渲染输出

Ink 终端渲染

详细流程参见：查询的完整生命周期

安全体系纵览

Claude Code 采用三层深度防御策略保护用户安全：

Layer 1: 权限规则引擎

6 种权限模式 · 13 步决策链 · 规则白名单

▼

Layer 2: Hook 拦截层

PreToolUse · PostToolUse · 4 种执行策略

▼

Layer 3: 沙盒隔离

文件系统沙盒 · 安全路径验证 · 绕过免疫

详细分析参见：权限与安全系统

模块导航

按功能域分类的分析文档索引。每份文档包含：架构设计（层级图）、数据流（流程图）、关键接口（真实代码）、设计模式、开发者指南、架构师指南、代码索引。

核心流程

文档	覆盖范围	关键文件
00 - 启动链路	从 main.tsx 到 REPL 启动的 7 阶段初始化流程	`main.tsx` `setup.ts` `bootstrap/`
01 - Query 循环	QueryEngine 核心循环：输入处理 → API 调用 → 工具调度 → 结果收集	`QueryEngine.ts` `query/`
查询生命周期	端到端 12 阶段流程：用户输入 → 响应渲染	跨模块集成分析

核心机制

文档	覆盖范围	关键文件
02 - 工具调度	30+ 工具的注册、匹配、执行机制，4 级组装管道	`Tool.ts` `tools/`
03 - 权限系统	三层安全：权限规则 + Hook 拦截 + 沙盒隔离，13 步决策链	`utils/permissions/` `hooks/toolPermission/`
04 - Agent 架构	5 种任务类型、多 Agent 协作、消息传递机制	`tasks/` `AgentTool` `SendMessageTool`
11 - Hook 机制	50+ Hook 的注册、触发、工具合并决策树	`hooks/` `hooks/notifs/`

扩展体系

文档	覆盖范围	关键文件
05 - MCP 体系	Model Context Protocol 完整实现，7 种传输变体，5 种连接状态	`services/mcp/` `server/`
07 - 插件系统	插件生命周期、技能发现、热重载机制	`plugins/` `skills/`
08 - 命令系统	70+ 斜杠命令的注册、分发、3 种命令类型	`commands.ts` `commands/`

数据与服务

文档	覆盖范围	关键文件
06 - 上下文管理	上下文窗口管理、压缩策略、会话记忆、记忆提取	`context.ts` `services/compact/`
10 - 服务层	15 个服务模块：API、OAuth、LSP、分析、设置同步等	`services/` 各子模块
15 - 成本与限流	Token 成本追踪、策略限制、多级阈值、预算管理	`cost-tracker.ts` `services/policyLimits/`

界面与配置

文档	覆盖范围	关键文件
09 - UI 交互层	Ink (React for CLI) 终端渲染、组件架构、双缓冲差分渲染	`ink/` `components/` `screens/`
13 - 配置与迁移	五层配置层级、迁移系统、输出样式、快捷键绑定	`utils/settings/` `migrations/`

外围能力

文档	覆盖范围	关键文件
12 - 外部集成	Vim 模式、语音输入、GitHub、Git、遥测、Computer Use	`vim/` `voice/` `utils/github/`
14 - Native 能力	Yoga 布局引擎、文件索引、语法高亮、上游代理	`native-ts/` `upstreamproxy/`

全局视图

文档	覆盖范围
模块依赖全景图	全部模块的依赖关系，6 层架构的跨层依赖分析
工具执行流程	工具调用端到端流程：API 响应 → 匹配 → 权限 → Hook → 执行 → 结果
Agent 协作流程	多 Agent 协作：3 种后端、Agent 生命周期、文件邮箱消息传递

核心设计原则

通过源码分析提炼出的 Claude Code 架构设计原则：

分层隔离

六层架构，层间通过接口通信。入口层不直接操作工具层，编排层不关心 UI 渲染细节。

可维护性

深度防御

权限规则、Hook 拦截、沙盒隔离三层安全机制，任何单层绕过不会导致系统失守。

安全性

插件化扩展

MCP 协议、插件系统、技能系统三层扩展机制，核心功能与扩展严格分离。

扩展性

流式优先

API 调用、工具执行、UI 渲染全链路流式处理，用户无感知延迟。

性能

上下文感知压缩

多级压缩策略（微压缩、自动压缩、会话记忆），在有限窗口内保留最大信息密度。

智能

Agent 原生

5 种任务类型 + 消息传递机制，原生支持多 Agent 协作，而非后加的补丁。

架构

如何使用本文档

如果你是开发者：重点关注每个模块的「开发者实践指南」章节，了解如何扩展和修改。从启动链路和工具调度开始阅读。

如果你是架构师：重点关注「架构师决策指南」和「设计模式与亮点」章节，理解设计权衡。先看本页的六层架构图，再看模块依赖图。

如果你想了解完整流程：从三个流程图文档开始：查询生命周期 → 工具执行流程 → Agent 协作流程。

技术栈

核心

TypeScript React (Ink) Zod AsyncGenerator

终端

Yoga Layout ANSI 控制序列双缓冲差分渲染

协议

MCP (Model Context Protocol) HTTP SSE stdio OAuth PKCE

工具链

ESBuild NPM Tree-sitter Chokidar