Claude Code 源码深度解析之架构总览:它如何成为一套 agent runtime

Claude Code 是 Anthropic 官方推出的 agentic coding 工具，以 CLI 为核心形态，支持终端、桌面应用、Web（claude.ai/code）和 IDE 扩展（VS Code、JetBrains）等多种使用方式。它让 Claude 模型能够直接在你的开发环境中读写文件、执行命令、搜索代码，完成从理解到修改的完整编码工作流。

Claude Code 是目前最具代表性的 agentic coding 工具之一，其工程架构的完成度和复杂度使它非常适合作为源码研究对象。

本系列基于 Claude Code 源码，为源码架构的深度解析。源码为前段时间泄露版本临时加更：Claude Code 源码泄露（附源码 GitHub 地址）

也可在 GitHub 上搜索到，如：https://github.com/ChinaSiro/claude-code-sourcemap

基于源码，你会发现它是一个分层很清楚的 agent runtime：上层处理启动和会话装配，中间层负责 agent loop，下层承接工具、状态、MCP、权限和各种基础服务。真正值得研究学习的是，它怎么把模型放进一套可运行、可扩展、可控的工程系统——源码中将这个系统称为 harness。

但在铺开架构地图之前，有一个概念必须先说清楚：agent loop。因为整篇文章（以及后续整个系列）的讨论都建立在它之上。

先理解一个概念：什么是 agent loop

普通的大模型调用是单轮的：用户发一条消息，模型回一段文本，结束。整个交互是一问一答。

Agent loop 把这个过程变成了多轮的：模型在回答过程中，可以主动请求调用工具（比如读文件、跑命令、搜索代码），拿到工具结果后继续思考，再决定是否需要更多工具调用——直到它认为任务已经完成，才真正停下来。

用更技术的语言说：agent loop 就是一个 while 循环——每轮让模型生成输出，检查输出里有没有 tool_use 请求；如果有，就执行工具、把 tool_result 追加回消息链，然后进入下一轮；如果没有，就退出循环。

这个闭环看起来简单，但它带来的能力跃迁是巨大的：模型不再只能"想"，它可以"做"了。而 Claude Code 的大部分工程设计——harness、权限、预算、compact、工具编排——都是在回答同一个问题：怎么让这个闭环在真实环境里稳定、安全、高效地运行。

理解了这一点，后面再看每一层的设计意图都会清晰很多。

一图看懂：Claude Code 的 6 层结构

1. 进程入口层

代表文件：src/entrypoints/cli.tsx、src/entrypoints/init.ts、src/main.tsx

这一层不直接回答用户问题，它先回答另一个更底层的问题：程序应该以什么方式启动。CLI 参数怎么解释、配置和网络怎么初始化、代理和遥测怎么挂上、最后是进入 REPL（交互式终端，用户可以多轮对话）还是 headless（通过 -p 参数直接传入 prompt，执行完即退出，适合脚本和 CI 场景），都是在这里定下来的。所以它更像一个启动器，负责把程序送进正确的执行链路。

2. 会话编排层

代表文件：src/main.tsx、src/QueryEngine.ts、src/cli/print.ts

到了这一层，系统才开始真正面对“一次会话”。工具、命令、MCP 客户端、权限函数会在这里被装配起来，system prompt 和上下文也在这里成形，conversation/session 级状态同样由这里维护。它不直接跑 agent loop，但会把 loop 开始前需要的东西都备齐。

3. 核心 agent loop

代表文件：src/query.ts

query.ts 是 Claude Code 的心脏。更精确地说，它导出的 query() 函数是 agent loop 的公开入口，但只是一层薄包装——真正的 while (true) 循环体在其内部的 queryLoop() 函数中。每轮迭代里，消息链在这里推进，模型 API 在这里调用，流式输出在这里被消费，tool_use 在这里被识别并设置 needsFollowUp = true，工具结果也在这里回填成新的 tool_result；当 needsFollowUp 为 false 时，循环退出。Claude Code 之所以呈现出 agent 的执行形态，本质上就是因为这个多轮闭环在持续运转。

4. 能力扩展层

代表文件：src/Tool.ts、src/tools.ts、src/commands.ts、src/skills/*

这一层决定 Claude Code 到底“会什么”。模型能看到哪些工具，用户能用哪些命令，高层工作流如何通过 skill 暴露出来，远程能力又怎样经由 MCP 接进来，都是这一层在定义。把它看成能力目录，比看成一个单纯的文件集合更贴切。

如果按当前源码再往前看一步，这一层已经不只是在管理 tool、command、skill 和 MCP。AgentTool 把子 agent、后台任务、worktree/remote 隔离执行也纳入了能力面；TaskCreateTool、TaskUpdateTool、WorkflowTool、LSPTool 这类更高语义的工具，也说明 Claude Code 的能力层正在从“动作集合”继续演化成“动态能力表面”。其中有些能力会直接暴露给模型，有些则会通过 ToolSearch 和 defer_loading 延后发现。

5. 状态与持久化层

代表文件：src/bootstrap/state.ts、src/utils/sessionStorage.ts

Claude Code 不是跑完就丢的一次性脚本，它得记住会话消息链、transcript、token 与 budget 状态、compact 边界，以及 resume 所需的信息。少了这一层，系统就只能做短平快的演示，没法支撑长任务和恢复执行。

6. 基础服务层

代表文件：src/services/api/*、src/services/mcp/*、src/services/tools/*

这一层负责和外部世界打交道。模型 API、MCP 连接、工具执行器，以及分析、实验、遥测这类横切能力，最后都落在这里。你可以把它理解成 Claude Code 的底座：上层所有设计，最终都要通过这里落到真实运行环境里。

这里也顺手补一个阅读上的边界：上面这张六层图主要是教学切面，方便你第一次建立地图；它不是源码目录的一一映射。当前源码里已经有不少横切机制会同时跨越多层，比如 cache-aware system prompt prefix、ToolSearch 带来的延迟工具暴露、以及 AgentTool 对子 runtime 的调度。把这些新机制先压回六层图里，不是为了忽略它们，而是为了先保住阅读顺序，让你第一次进入源码时不至于失焦。

贴近源码的主链路图

这张图里最值得先记住两件事：main.tsx 是总控；REPL 与 headless 虽然入口不同，但最后都会汇向同一个执行内核。

一定要分清的几个概念

`main.tsx`、`QueryEngine.ts`、`query.ts` 不是同一层

很多人一上来会把这几个文件都当成“主逻辑”。

更合适的理解是：main.tsx 管进程级调度，QueryEngine.ts 管会话级编排，query.ts 管 turn 级循环执行。它们都重要，但并不在同一层上。把这三者混成一个“主逻辑文件群”，后面读源码时会很容易失焦。

Tool、Command、Skill、MCP 各自负责什么

它们经常一起出现，所以也最容易被混为一谈。更实用的记法是：Tool 主要给模型调用，Command 主要给用户调用，Skill 是更高层的工作流封装，而 MCP 是外部能力接入协议，它带进来的不只是 tool，也可能是 command、prompt 甚至 skill。

为什么这种分层很重要

因为 Claude Code 做的是“围绕大模型的工程化执行环境”，而不只是把 prompt 写得更会编程。

只有先理解这种分层，你后面再看 agent loop、skill、tool、context engineering 时，才不会把所有东西都混成“提示词技巧”。

源码即视：一个关键类型的真实样貌

在正式进入后面的深入篇之前，先看一眼 query.ts 的主函数签名，感受下这套系统的“粒度”：

// src/query.tsexportasyncfunction* query(  params: QueryParams,): AsyncGenerator<  | StreamEvent  | RequestStartEvent  | Message  | TombstoneMessage  | ToolUseSummaryMessage,Terminal> {

这是一个 async generator，yield 出多种事件类型。后续篇章会详细解释这些事件如何驱动整个 agent loop。

源码锚点

建议你配合打开下面这些文件：

src/entrypoints/cli.tsx
src/main.tsx
src/QueryEngine.ts
src/query.ts
src/tools.ts
src/commands.ts
src/bootstrap/state.ts

结语

如果你只记住一句话，那就是：Claude Code 的核心不只是一段 prompt 或一组工具列表，它是一套分层清晰的 agent 工程系统。

下一篇我们就顺着这张地图往内层走，具体看一次用户请求是怎样进入 agent loop，并在 tool_use 和 tool_result 之间循环起来的。