Claude Code 源码分析
Claude Code v2.1.88 反编译源码深度分析 · CodeGraph 知识图谱
系统架构
四层架构 · CLI → query 循环 → 工具/UI
查询引擎
Agent 心脏：tool_use 主循环与 SDK 模式
消息系统
五种 Message 类型与 API 管道
工具系统
51 内置工具 + MCP 扩展
权限与安全
canUseTool 链与用户信任模型
CodeGraph
4.4 万节点源码知识图谱
本章总览
欢迎来到 Claude Code 源码教学站。本站不是 API 文档式的信息罗列，而是带你从零理解一个生产级 AI Agent CLI 如何设计、如何运转。建议按侧边栏顺序阅读，每章都有「导读 → 原理 → 源码对照 → 小结」。
总览图
学完本章你应该能
- 建立 Claude Code 整体心智模型：入口、引擎、工具、UI 四层如何协作
- 知道 53 万行代码里，哪些模块最值得优先深入
- 能向他人解释「用户输入一句话后，系统内部发生了什么」
核心概念（先读懂这些）
Agent CLI 是什么
Claude Code 不是聊天网页，而是运行在终端里的编程 Agent：它读文件、跑命令、改代码，并在 Anthropic Messages API 的 tool_use 协议下循环工作。理解这一点，后面所有模块都围绕「对话 + 工具循环」展开。
为什么用 CodeGraph
纯人工读 50 万行不现实。本站结合静态分析与知识图谱，把调用关系、模块边界可视化，让你学会「先抓主干、再钻细节」的阅读方法。
建议学习步骤
- 先浏览本章统计数字，感受项目规模
- 记住「核心架构一图流」
- 从「系统架构」章节开始系统学习
常见误区
注意
不要试图一次读完所有工具页——先掌握 query 主循环
注意
反编译源码缺少部分内部模块，遇到 feature gate 阻断是正常的
项目概览
Claude Code 是 Anthropic 出品的 AI 编程 Agent CLI，本分析基于 @anthropic-ai/claude-code v2.1.88 反编译源码，结合 CodeGraph 知识图谱（44,402 节点 / 121,958 边）生成。
| 指标 | 数值 |
|---|---|
| 代码行数 | 536,325 |
| 内置工具 | 51 |
| 斜杠命令 | 87 |
| 服务子系统 | 22 |
| src 模块 | 38 |
| 图谱节点 | 44,402 |
核心架构一图流
推荐学习路线（活动图）
8 大核心模块
入口层 (entrypoints / main / cli)
CLI 启动、参数解析、OAuth 认证、GrowthBook 特性开关初始化，决定走 REPL 交互还是 Headless/SDK 模式。 4,167 行 · 14 文件
查询引擎 (query.ts / QueryEngine)
Claude Code 的心脏：驱动 tool_use 循环、流式 API 调用、上下文压缩、工具编排、权限检查。 12,155 行 · 22 文件
工具系统 (tools/ + Tool.ts)
53 个内置工具 + MCP 动态工具，统一 Tool 接口，支持并发安全标记、权限弹窗、Progress 流式回报。 51,099 行 · 199 文件
服务层 (services/)
22 个子系统：API 通信、MCP 客户端、上下文压缩、OAuth、插件、遥测、语音、记忆提取等。 53,949 行 · 148 文件
终端 UI (components/ + ink/)
React + Ink 渲染的 TUI：消息流、权限弹窗、Spinner、任务面板、MCP 配置界面。 101,975 行 · 506 文件
斜杠命令 (commands/)
87 个 /command：/model、/compact、/mcp、/memory、/doctor 等，用户可直接操控 Agent 行为。 26,692 行 · 213 文件
桥接层 (bridge/)
Claude Desktop / 远程控制桥接：JWT 认证、会话同步、消息中继。 12,652 行 · 33 文件
基础设施 (utils/)
最大模块：消息格式化、会话持久化、配置、权限、Hooks、Token 计数、Bash 解析等通用能力。 181,060 行 · 570 文件
技术难点预览
1. 流式 Tool Use 并发执行
Claude API 以 streaming 方式返回 content blocks，tool_use 块可能在 text 块之前/之间到达。Agent 需要在收包过程中就开始执行工具，而非等完整响应。
2. 上下文窗口管理与自动压缩
多轮对话 + 工具结果会快速填满 200K token 上下文。需在合适时机压缩历史，且压缩后不能丢失关键信息或破坏 API message 格式。
3. 编译期 Feature Gate (Bun DCE)
内部功能(KAIROS/DAEMON/COORDINATOR)不能泄露到公开发布包。需要编译期条件剔除，而非运行时 if。
4. 权限系统与用户信任
Agent 可执行 Shell/写文件/访问网络。需在安全与效率间平衡：每次弹窗确认 vs 自动批准 vs 完全绕过。
推荐学习路线（约 2 周）
第 1 步 · 建立全局观（1-2 天）
首页 → 源码统计 → 系统架构 → 核心流程。目标：能画出从输入到 tool call 的路径。
第 2 步 · 吃透引擎（3-4 天）
查询引擎 → 消息系统 → 状态管理 → API 通信层。目标：能解释一轮 turn 内 messages 如何变化。
第 3 步 · 能力与扩展（3-4 天）
工具系统 → 权限与安全 → MCP → Hooks。目标：知道扩展 Agent 的三条路径（Tool / MCP / Hook）。
第 4 步 · 按需深潜（持续）
模块详解、工具详解、CodeGraph 调用链。目标：对负责领域能定位到具体文件与函数。
本章小结与延伸
Claude Code = 终端 Agent + 流式 tool_use 循环 + 权限与压缩。下一章建议阅读「源码统计」了解模块体量，再进入「系统架构」。 继续学习：