系列开篇 | Claude Code 源码架构概览:51万行代码的模块地图

2024-07-06

系列开篇 | Claude Code 源码架构概览:51万行代码的模块地图

Hi,大家好,欢迎来到维元码簿。

这是一个关于 Claude Code 源码学习的系列。

Claude Code 是当前业界 Coding Agent 的 SOTA 实现。能接触到这样一个工业级系统的完整源码,是难得的学习机会。所以我决定用 Coding Agent 帮我读懂 Claude Code,同时把这个学习过程完整记录下来。

51 万行代码,体量庞大。一篇长文放不下,于是有了这个系列。

作为开篇,本文的任务是画地图——不急着深入细节,而是先搞明白:

Claude Code 是什么?有多少核心代码,多少支撑代码?可以拆成哪些模块?它们如何协作?学习路径是什么?从哪里开始读?

搞明白了这些,后面的学习就可以有条不紊地进行下去。

Claude Code 到底是什么?

Claude Code 到底是一个什么软件?

大多数人第一次听到 Claude Code,会说:“就是一个命令行里面能写代码的 ChatGPT 嘛。”

这个理解不算错,但远远不够。让我带你一层一层地剥开它的外壳。

第一层:CLI 命令行工具(表象)

在最外层,Claude Code 确实是一个 CLI 应用——你输入 claude,它启动交互式会话。

但如果你以为它只是"命令行里能写代码的 ChatGPT",那就错过了最重要的部分。

横向对比同类产品:Gemini CLI(Google)、Codex CLI(OpenAI)——看起来都是命令行工具。但这里的关键误区是:我们在比较"CLI",但 CLI 就是个入口交互形态,根本不是重点。

CLI 仅仅只是它交互的产品形态的壳,真正有价值的是里面的 Coding Agent。

光看数字:101 个子命令、389 个 React 组件——终端 UI 的复杂度堪比中型 Web 应用。

第二层:Agent 核心循环(能力)

剥开 CLI 外壳,里面是一个能自主决策的 Agent。

也许你知道 ReAct Agent 模式(Reasoning + Acting),Claude Code 的核心也是如此——感知 → 思考 → 行动 → 观察 → 再思考…

但和普通聊天机器人不同,Claude Code 不只是"告诉你怎么做",而是直接帮你做。它有30+ 个内置工具:读写文件、执行 Bash、搜索代码,还能通过 MCP 协议接入外部工具。

这个循环让它从"被动的聊天机器人"变成了"主动的任务执行者"。

第三层:Agent Harness 工程(复杂性)

这是 Claude Code 最有价值的部分。

部分代码行数占比Agent 核心逻辑~3,000< 1%工程支撑系统~511,000> 99%

Agent 的“大脑”只有不到 3000 行,但让它能稳定运行的“身体”占了 99%。

很多人认为 Claude Code 的能力全部来自于 Claude 模型。但当你深入理解 Harness 之后,你会发现:这是大模型能力的放大器——这部分工程工作至少贡献了一半的效果。

同样的模型,没有好的 Harness 只是玩具,有了完整的 Harness 才能变成生产级工具。想想这些实际问题:

对话太长怎么压缩?Agent 想执行 rm -rf / 谁来拦截?API 调用失败怎么重试?

Claude Code 给出了答案:上下文系统管理记忆,权限系统控制安全,错误处理保障稳定。

那么,这个占 99% 代码量的“支持系统”到底包含哪些核心模块?让我们拆开看看。

盲人摸象:业界 SOTA AI Coding 软件的模块拆解

如果要我们自己实现一个工业级的 AI Coding 软件,需要搞定哪些模块?

这个问题帮助我们建立全局视角。不是漫无目的地去读代码,而是先问:如果让我来写,我会怎么组织?

带着这个问题,我结合过去做服务端系统的经验,对 Claude Code 源码做了一次“盲人摸象”式的初步阅读。摸完之后,我把这个系统拆成了 9 个一级模块,每个模块标注了优先级。

需要说明的是,这个拆分是我个人的理解,不是官方定义。Claude Code 的源码没有显式的“模块边界”,目录结构也有交叉。我是按照“职责”和“依赖关系”来划分的——同一个目录下的文件可能属于不同模块,同一模块的代码也可能散落在多处。

但这个拆分对我很有帮助,它让 51 万行代码从“一团乱麻”变成了“几个相对独立的命题”。下面三个问题会逐一展开:

问题一:这 9 个模块分别是什么?如何协作?问题二:每个模块在代码里对应哪些目录?体量多大?问题三:应该按什么顺序学习?

问题一:这个系统有哪些模块?

99% 的代码在做“支撑”。但“支撑”不是一个模糊的大筐子,它有具体的结构,每个模块之间也有明确的协作关系。

模块优先级占比Agent 执行内核P01.6%上下文系统P0–P15.6%工具与扩展系统P0–P217.3%控制面与安全P1–P211.5%模型与云服务P1–P34.2%产品外壳与交互P235.9%多 Agent 协作P33.7%远程与非 CLI 形态P33.2%基础设施与底座P417.0%P0 = 内核运转 · P1 = 能力边界 · P2 = 产品化 · P3,P4 = 扩展底座

各模块的二级话题:

Agent 执行内核:query.ts 主循环结构 · turn-by-turn 执行逻辑 · 停止条件判断 · QueryEngine.ts 消息管理与流式输出上下文系统:System Prompt 注入 · 会话记忆管理(memdir / MEMORY.md)· 上下文压缩(microcompact / contextCollapse / autocompact)工具与扩展系统:工具注册与发现(30+ 内置工具 + MCP 接入)· 并发调度(只读并行 / 写操作串行)· MCP 协议实现控制面与安全:权限模型(allow / deny / confirm 三级决策)· Feature Gate 灰度机制模型与云服务:Claude API 调用 · 流式响应处理 · 模型选择与降级策略产品外壳与交互:CLI 命令行(101 子命令)· React 终端 UI(389 组件)· 命令 / 钩子 / 主题系统多 Agent 协作:AgentTool 子任务分发 · swarm 编排远程与非 CLI 形态:Bridge 协议 · VSCode / IDE 集成 · 远程控制基础设施与底座:通用工具函数 · 类型定义 · 原生模块绑定

这 9 个模块在一次请求中是如何协作的?

执行链路拆解:

① 输入入口 → 产品外壳与交互

CLI 接收用户指令,解析参数,启动主循环

② 安全检查 → 控制面与安全

权限校验、Feature Gate 检查、危险操作拦截

③ 上下文拼装 → 上下文系统

System Prompt 注入 → 历史会话加载 → 微压缩合并冗余消息 → 上下文折叠(可选) → 自动压缩(超限时生成摘要)

④ 模型调用 → 模型与云服务

调用 Claude API,流式返回响应(文本或 tool_use)

⑤ 工具调度与执行 → 工具与扩展系统

匹配工具实现 → 内置 30+ 工具执行 → MCP 外部服务接入 → 结果写回消息数组 → 只读工具并行,写操作串行

⑥ 循环与停止 → Agent 执行内核

检查停止条件(轮次上限、Token 预算、用户退出)→ 不满足则回到 ③ 继续循环

问题二:每个模块在代码里在哪?体量多大?

知道有哪些模块还不够,我们还需要知道它们在源码里对应哪些文件,规模是多大,以及从哪几个文件下手。

模块对应目录文件数代码行核心入口文件Agent 执行内核src/ 根目录230.8万query.ts、QueryEngine.ts、Task.ts上下文系统constants/、services/compact/、memdir/962.9万constants/prompts.ts、services/compact/工具与扩展系统tools/、services/mcp/、skills/、plugins/2758.9万Tool.ts、tools.ts、services/mcp/控制面与安全bootstrap/、utils/permissions/1765.9万bootstrap/state.ts、utils/permissions/模型与云服务services/api/、utils/model/692.2万services/api/client.ts产品外壳与交互cli/、commands/、components/、hooks/、ink/87818.5万main.tsx、cli/多 Agent 协作tools/AgentTool/、utils/swarm/551.9万tools/AgentTool/远程与非 CLI 形态bridge/、remote/471.7万bridge/bridgeMain.ts基础设施与底座utils/、types/、native-ts/3048.7万utils/(通用工具)核心逻辑极度精简——query.ts 约 1700 行,QueryEngine.ts 约 1300 行,两个文件加起来不到 3000 行,比很多业务系统的单个 Service 还小。

问题三:应该按什么顺序学?

光知道有哪些模块、代码在哪还不够,我们需要一条有逻辑的学习路径。

5 步学习路线:

第 1 步:跑通主循环 · Agent 执行内核

query.ts 主循环结构、turn-by-turn 执行逻辑、停止条件判断QueryEngine.ts 消息管理、流式输出、上下文生命周期

第 2 步:读懂上下文 · 上下文系统

System Prompt 注入机制(工具描述、项目规则、权限状态)会话记忆管理(memdir 历史加载、MEMORY.md 机制)上下文压缩策略(microcompact、contextCollapse、autocompact)

第 3 步:理解工具链 · 工具与扩展系统

工具注册与发现(30+ 内置工具、MCP 外部工具接入)工具调度机制(并发分组、只读并行/写操作串行)MCP 协议实现(服务端配置、工具发现、结果回传)

第 4 步:搞清安全边界 · 控制面与安全

权限模型(allow/deny/confirm 三级决策)Feature Gate 机制(实验功能灰度、远程配置下发)

第 5 步:扩展视野 · 多 Agent / 远程形态

多 Agent 协作(AgentTool 子任务分发、swarm 编排)远程控制(Bridge 协议、VSCode/IDE 集成)

前三步是 P0 核心三件套,读懂这三个模块就理解了 Agent 的完整工作机制。

从这里开始,我们会按这个顺序逐个模块深入。

系列预告

本文是 Claude Code 源码学习的开篇,目的是画一张“地图”。三个核心结论:

Claude Code 的价值不在模型,在 Harness — 99% 代码在做工程支撑9 个模块,P0 核心三件套 — 执行内核 + 上下文 + 工具,读懂这三个就理解了 Agent学习路径清晰 — 从内核出发,逐层向外

如果这篇文章对你有帮助,欢迎点赞收藏支持一下。

如果你对 Claude Code 源码有自己独特的理解,或者发现文中有不准确的地方,欢迎留言交流——大家一起把这块拼图拼得更完整。