2026年5月3日

《Claude Code 源码解析系列》导读

这是一篇系列索引页，按工程架构、核心机制、工具系统、扩展能力与协作机制梳理 Claude Code 源码解析文章。

《Claude Code 源码解析系列》导读

这组文章想回答的不是“Claude Code 会不会写代码”，而是一个更工程化的问题：

一个编程 Agent，到底是怎么从模型接口，长成一套能读项目、调工具、控权限、管上下文、做协作的运行时系统的？

为了更容易阅读，我把整组文章按问题链重新整理成五个部分。你可以顺着读，也可以按兴趣跳读。

这组文章还有一个阅读约定：每篇都先讲“为什么要有这个机制”，再回到源码里看它落在哪些承重文件和关键对象上。这样读 Claude Code 会更稳：不要从目录树里随机找函数，而是先抓住 QueryEngine -> query.ts -> Tool -> Context/Prompt/Permission 这条运行链，再顺着链路看每个模块为什么出现。

一、先建立整体图景

《Claude Code 源码解析系列》第1章｜工程架构

这一篇先从高处看，建立 Claude Code 的总体结构：Model API、QueryEngine、Tools、Context / State、安全治理和 Agent 协作分别在系统里扮演什么角色。

源码阅读时先抓三个锚点：QueryEngine.ts 管一场会话，query.ts 推一轮轮 ReAct 循环，Tool.ts 定义模型行动进入真实工程环境前必须遵守的协议边界。

二、理解主循环与上下文

这几篇连在一起看，会比较完整地理解 Claude Code 每一轮“看到了什么、怎么决定下一步、历史如何保留、上下文太长时如何压缩”。

这一部分的源码主线是：QueryEngine.submitMessage() 启动一轮 turn，queryLoop() 根据 State 构造本轮请求，模型返回 tool_use 后执行工具，再把 tool_result 回填到 messages。Prompt 和 Context 不要分开读，它们都服务于“下一轮模型到底应该看见什么”。

三、理解工具系统

如果你最关心“Claude Code 为什么不只是调用模型，而是真的能干活”，这一部分最关键。

工具部分建议按协议读，而不是按工具名读：先看 Tool 类型声明，再看 tools.ts 如何生成本轮可见工具菜单，最后看 toolExecution.ts 如何完成 schema 校验、权限检查、hooks、执行和结果回填。

四、理解扩展能力

这部分讲的是 Claude Code 怎么把“更多外部能力”和“更成熟的任务经验”接入主运行时。

五、理解协作与规划

这一部分适合已经理解单 Agent 主循环后，再往上看任务拆分、子 Agent、审批边界和计划控制面。

阅读建议

如果你第一次看这组文章，推荐顺序是：01 -> 02 -> 03 -> 04.1 -> 05 -> 06 -> 07 -> 08.1 -> 09.1。
如果你更偏工程实现，优先看 02 / 03 / 04.1 / 05。
如果你更关心扩展生态，优先看 06 / 07 / 08.1。
如果你更关心方法论对比，再补 04.2 / 08.2 / 09.2 这几篇选修。

这组文章的统一命名

这次我把文件名统一成了更稳定的系列编号格式：

00 表示导读页
01-09 表示主章节
05.1 / 05.2 / 05.3 这类表示工具系统下的子章节
04.2 / 08.2 / 09.2 这类表示选修或横向扩展阅读

这样做的好处是，目录排序、文章 slug、上一篇下一篇和博客列表顺序会更一致，不容易因为文件名字面排序而跳来跳去。