【Claude Code源码剖析】00-Claude Code 2.1.88 源码完全解析

📖 本文档系列基于从 cli.js.map 还原的约 70 万行 TypeScript 源码，由 AI 逐模块阅读后整理，力求第一性原理讲解，无编造。

一、项目是什么

Claude Code 是 Anthropic 公司开发的 终端 AI 编程助手（CLI Agent）。用户在终端输入自然语言，Claude Code 会：

理解你的代码库（读文件、搜代码、查 git）
调用 LLM（Claude API）进行推理
执行工具（编辑文件、运行命令、搜索网页等）
在终端中以 React Ink 渲染交互式 UI

本质上它是一个 “LLM + Tool Use” 的 Agentic Loop，外面包了一层漂亮的终端 UI。

二、技术栈总览

层级	技术	说明
运行时	Bun (打包) + Node.js ≥ 18 (运行)	用 Bun 的 `bun:bundle` 做条件编译/Dead Code Elimination
语言	TypeScript (严格模式)	全项目 TS，含 JSX/TSX
CLI 框架	Commander.js (`@commander-js/extra-typings`)	类型安全的参数解析
终端 UI	React Ink (React → 终端)	组件化终端渲染，支持 Flexbox 布局
LLM SDK	`@anthropic-ai/sdk`	官方 Anthropic SDK，Streaming API
MCP	`@modelcontextprotocol/sdk`	Model Context Protocol 客户端
状态管理	自研轻量 Store（类 Zustand）	`createStore<T>()` — 发布/订阅模式
工具链	Zod v4（校验）、lodash-es、chalk、strip-ansi 等

三、核心架构图（第一性原理）

用户输入 (stdin/CLI args)
       │
       ▼
┌─────────────────────────────────────────────────┐
│  main.tsx (入口)                                  │
│  ├─ Commander 解析 CLI 参数                      │
│  ├─ init() → 配置/认证/遥测 初始化               │
│  └─ launchRepl() → 渲染 React Ink 应用           │
└─────────────────┬───────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────────┐
│  REPL.tsx (主交互循环)                            │
│  ├─ PromptInput: 用户文本输入                     │
│  ├─ handlePromptSubmit() → 发起一次 "Turn"        │
│  │   ├─ processUserInput() → 解析斜杠命令/附件    │
│  │   └─ query() → **核心 Agentic Loop**          │
│  │        ├─ 构建 System Prompt                   │
│  │        ├─ 调用 Claude API (Streaming)          │
│  │        ├─ 解析 tool_use blocks                 │
│  │        ├─ runTools() → 并行/串行执行工具       │
│  │        ├─ 将 tool_result 送回 API              │
│  │        └─ 循环直到 stop_reason=end_turn        │
│  └─ Messages: 渲染对话历史                        │
└─────────────────┬───────────────────────────────┘
                  │
     ┌────────────┼────────────┐
     ▼            ▼            ▼
 ┌────────┐ ┌─────────┐ ┌──────────┐
 │ Tools  │ │Commands │ │ Services │
 │ 30+种  │ │ 60+种   │ │ MCP/API  │
 │ 内置   │ │ 斜杠    │ │ 分析/LSP │
 └────────┘ └─────────┘ └──────────┘

四、模块全景地图

整个 src/ 目录分为以下核心模块（按重要性排序）：

序号	模块	目录/文件	行数估算	文档章节
1	启动引导	`main.tsx`, `entrypoints/`, `bootstrap/`	~6,800	01-启动流程
2	Agentic 查询循环	`query.ts`, `QueryEngine.ts`	~3,000	02-查询引擎
3	工具系统	`Tool.ts`, `tools.ts`, `tools/`	~15,000+	03-工具系统
4	命令系统	`commands.ts`, `commands/`	~10,000+	04-命令系统
5	权限与安全	`utils/permissions/`	~5,000+	05-权限系统
6	终端 UI	`components/`, `screens/`, `ink/`	~30,000+	06-UI系统
7	状态管理	`state/`, `bootstrap/state.ts`, `hooks/`	~8,000+	07-状态管理
8	API 与 Streaming	`services/api/`	~5,000+	08-API通信
9	MCP 协议	`services/mcp/`	~5,000+	09-MCP
10	上下文压缩	`services/compact/`	~4,000+	10-上下文管理
11	任务系统	`Task.ts`, `tasks/`	~5,000+	11-任务系统
12	远程桥接	`bridge/`	~8,000+	12-Bridge
13	插件与技能	`plugins/`, `skills/`	~3,000+	13-插件技能
14	成本追踪	`cost-tracker.ts`, `utils/modelCost.ts`	~1,000+	14-成本追踪
15	辅助系统	`utils/` (200+ 文件)	~100,000+	15-工具函数库

五、学习路线与时间预估

🎯 推荐学习路径（由浅入深）

第 1 周：宏观理解
  ├─ 读本总览文档
  ├─ 读 01-启动流程：理解从 CLI 到 REPL 的完整链路
  └─ 读 02-查询引擎：理解核心 Agentic Loop

第 2 周：核心系统
  ├─ 读 03-工具系统：理解 Tool 抽象和具体工具
  ├─ 读 08-API通信：理解如何与 Claude 交互
  └─ 读 05-权限系统：理解安全模型

第 3 周：用户界面
  ├─ 读 06-UI系统：理解 React Ink 终端渲染
  ├─ 读 07-状态管理：理解数据流
  └─ 读 04-命令系统：理解斜杠命令

第 4 周：高级系统
  ├─ 读 10-上下文管理：理解 Token 压缩算法
  ├─ 读 11-任务系统：理解多 Agent 架构
  └─ 读 09-MCP：理解协议扩展

第 5-6 周：专项深入
  ├─ 读 12-Bridge：理解远程模式
  ├─ 读 13-插件技能：理解扩展机制
  ├─ 读 14-成本追踪
  └─ 读 15-工具函数：按需查阅

⏰ 时间预估（对于有 2-3 年 TypeScript 经验的开发者）

阶段	目标	时间
能跑起来、能改配置	理解入口和配置	2-3 天
能读懂核心流程	理解 Agentic Loop	1-2 周
能修改/添加工具	理解工具系统	2-3 周
能独立改 UI/命令	理解 UI + 命令	3-4 周
基本掌握全部模块	通读所有模块	6-8 周
深度掌握（能重构核心）	理解每个算法和设计决策	3-6 月

⚠️ 70 万行不需要逐行读。大约 30% 是 UI 组件（可按需看），20% 是工具函数（当字典查），15% 是类型定义。核心逻辑链路约 5-8 万行，这是需要深读的。

六、关键设计理念

1. “一切皆工具” (Tool-First)

Claude Code 的核心范式是 LLM 通过 tool_use 与外界交互。读文件、写文件、运行命令、搜索代码——全都是 Tool。这是 Anthropic 的 Tool Use API 的最佳实践体现。

2. Agentic Loop (Agent 循环)

User Message → LLM → [tool_use] → Execute Tool → [tool_result] → LLM → ... → end_turn

这个循环是整个系统的心脏。LLM 决定调用什么工具，工具执行后结果回传给 LLM，直到 LLM 认为任务完成。

3. 流式优先 (Streaming-First)

所有 API 调用都是 Streaming 的。UI 实时显示 LLM 输出。工具执行也支持流式进度上报。

4. 权限分层 (Permission Layers)

安全是重中之重。每个工具执行前都经过多层权限检查：规则匹配 → 分类器判断 → 用户确认。

5. 条件编译 (Dead Code Elimination)

通过 Bun 的 feature() 函数实现条件编译，内部/外部构建包含不同功能模块。

七、文件数量统计

src/
├── 顶层文件:        ~20 个 (核心入口和类型)
├── tools/           ~40+ 个工具实现
├── commands/        ~60+ 个斜杠命令
├── components/      ~150+ 个 UI 组件
├── hooks/           ~90+ 个 React hooks
├── utils/           ~250+ 个工具函数
├── services/        ~60+ 个服务模块
├── bridge/          ~30 个桥接模块
├── state/           ~6 个状态模块
├── types/           ~10 个类型定义
└── 其他子目录       ~50+ 个辅助模块

总计约 700+ 个源文件，70 万行代码。

八、文档目录

九、配套学习资源（三层闭环）

本系列文档（第 01–29 篇）是层级 2：源码精读层，需配合另外两层食用：

层级 1  LLM 理论层          docs/LLM技术深度系列/
层级 2  CC 源码精读层       docs/01-29.md  ← 本系列
层级 3  技术栈实战层        docs/tech-stack/

层级 1 — LLM 技术深度系列（理解为什么）

不了解 LLM 原理就看源码，等于不懂 TCP 就看 Nginx 代码。建议先读 01 和 03。

文档	核心内容	建议时机
00-系列导航	全系列概览	开始前
01-Transformer架构	Attention/位置编码/KV Cache	第 1 周前
03-RLHF完整技术解析	为什么 Claude 听话	第 2 周
05-Reasoning模型训练	CoT/o1 类模型原理	第 3 周
07-长上下文技术	读完第 10 章后	第 4 周

层级 3 — 技术栈实战层（会写代码）

每个语言都有入门→进阶→高阶三级，按需取用。有语言基础可跳过 syntax/01。

语言	入口	适合场景
Python	tech-stack/python/syntax/	DeepSeek 岗位主力语言
TypeScript	tech-stack/typescript/syntax/	读懂 CC 源码类型
Node.js	tech-stack/nodejs/syntax/	理解运行时和 CLI
React	tech-stack/react/syntax/	读懂 CC 的 Ink UI
LLM 接入	tech-stack/llm/	SDK/MCP/Prompt 工程
算法	tech-stack/algorithms/	面试算法准备