Claude Code 源码拆解:从启动到多 Agent 扩展层
这篇文章只做一件事:把 Claude Code 拆成几个真正决定系统质量的核心模块,然后把几个最关键的问题讲透。
它到底怎么设计 为什么要这样设计 这样设计的价值是什么 我们做自己的 Agent 时,哪些最值得吸收
所以这里不做目录导览,也不搞“带你读源码”。源码只是证据,重点是把 Claude Code 背后的系统判断讲透。
先把靶子立起来。
这两年大家都在写 Agent,但其实所有人都知道一个尴尬事实:Demo 阶段看起来势如破竹,一旦加到三五个工具、几种运行模式、几类权限规则之后,系统就开始肉眼可见地变形。主循环越来越脏,工具一多就互相污染,后台任务和前台会话互相打架,扩展一接进来就满地特判。模型能力当然重要,但真正决定一个 Agent 能不能长期活下去的,往往不是模型,而是围着模型搭起来的运行时。
Claude Code 值得拆,不是因为它“功能很多”,而是因为它很像一套已经真正在承接复杂度的 Agent 系统。对我们内部做 Agent 平台、研发工具链、Vibe Coding 产品的人来说,它的价值不只是竞品分析,而是一个现成的参照物:哪些复杂度应该前置,哪些复杂度应该制度化,哪些复杂度必须通过架构收敛,而不能继续靠 prompt 和人肉兜着。
换句话说,这篇文章真正想回答的不是“Claude Code 有哪些功能”,而是“为什么有些 Agent 系统一复杂就散架,而它没有”。
一、入口与启动链路:别急着拉起全世界
很多系统的入口都是一个越来越胖的 main,恨不得一上来就把全世界都拉起来。Claude Code 在这里反而很克制,它先做了一次非常关键的判断:先分流,再装配,最后才进入会话。
核心矛盾
一个成熟 Agent 往往同时要支持本地交互、headless、SDK、remote、后台 session、会话恢复。如果启动层不先把模式、边界、权限和上下文装配清楚,后面每个宿主都会偷偷长出自己的运行语义,最终系统会裂成几套。
从源码看,启动大致分三段:
第一段是入口分流。系统不急着把整个运行时拉起来,而是先判断这次到底是什么启动:本地交互、无界面运行、远程接入、后台会话管理,还是一些极简 fast path。很多路径都用动态加载,这说明 Claude Code 从一开始就在控制启动成本,而不是先把全世界加载进来再说。
第二段是进程级初始化。这一层处理的是运行环境:配置、telemetry、远程设置、清理回调、一些全局设施。这里重要的不是具体初始化了什么,而是它刻意不碰当前会话语义。也就是说,它回答的是“进程能不能跑”,不是“这一轮 Agent 该怎么跑”。
第三段才是会话级准备。这里开始确定当前工作目录、会话身份、工具面、权限模式、扩展能力、系统约束、恢复方式等信息,最后再决定由交互式宿主承载,还是由无界面引擎承载。
这中间还有一个很容易被忽略、但对架构非常关键的细节:Claude Code 把“进程状态”和“交互状态”分开了。像 cwd、projectRoot、sessionId、telemetry、token/cost 计数这类更接近基础设施的东西,会沉在 bootstrap/state 一类全局状态里;而 tasks、MCP clients、plugin 状态、permission context、界面选择状态这类更接近控制面的东西,才进入 AppState。这个分层让它不会把 React state 误当成整套 runtime 的唯一真相,也不会把所有状态都做成不可控的全局变量。
Claude Code 的解法
它没有把启动做成“一个大 main 把所有东西拉起来”,而是显式拆成三段:入口分流、进程初始化、会话准备。这个顺序看起来普通,真正厉害的地方在于它把几个本来最容易搅在一起的问题拆开了:启动模式是什么、运行环境是否就绪、当前会话制度是什么、最后由谁承载会话。
这里最值得注意的是两个判断:
先装配共享 session/runtime 语义,再选择交互式或 headless 这种宿主 先区分进程状态和交互状态,再决定哪些进 AppState,哪些留在更底层状态里
为什么这样好
这样做的直接收益是,无界面运行、交互式运行、远程运行、后台运行可以共享同一套核心 runtime,而不是各自长一套逻辑。权限、工具、系统约束、扩展能力这些会影响执行边界的东西,也都能在第一轮请求前定型,后面的主循环不需要一边跑一边猜。
它还有一个更深的好处:系统复杂度被前置了。很多项目把模式判断、权限边界、宿主差异拖到运行中解决,最后主循环会越来越脏。Claude Code 则把这类复杂度尽量压到启动层,所以运行时主链路反而更纯。
代价也不是没有。这样做要求你在系统早期就想清楚“什么是宿主,什么是会话,什么是 runtime 公共语义”。如果团队还没有这些抽象意识,入口层会看起来有点重。但这类“重”是值得的,因为它换来的不是形式感,而是后续模式扩展时不分裂。
我们怎么学
最值得吸收的不是“复杂入口”,而是次序感。凡是会影响执行边界的东西,尽量都在第一轮请求前定型。
如果你们还在单一交互模式阶段,不必照抄 Claude Code 这么厚的入口层,但至少要先把三件事分开:启动模式、会话制度、宿主承载。如果你们已经同时有命令行、接口调用、后台任务、远程运行之类多种方式,这一层就不能再含糊了,否则很快就会长成几套彼此不兼容的 Agent。一个很实用的动作是,先把“启动时必须定型的边界”列成一张清单。
启动层做得好不好,平时不显山不露水;但系统一旦开始长模式、长宿主、长入口,它往往就是最先决定架构寿命的那一层。
二、REPL / UI Orchestration:UI 不是传话筒
很多团队把聊天 UI 理解成“显示消息的壳”,大模型吐什么,前端就渲染什么。Claude Code 明显不是。它的 REPL 本质上更像一个运行时控制台。
核心矛盾
一旦 Agent 不只是聊天,而开始执行工具、弹权限、跑后台任务、动态接入扩展,UI 面对的就不再是“如何显示回复”,而是“如何把一个复杂 runtime 变成用户可操作、可理解、可干预的系统”。如果这一层做不好,所有关键状态都会变成黑箱。
REPL 的启动层很薄,说明它不是启动中心,而是一个被装配好的宿主。真正值得注意的是,REPL 会把输入、消息流、权限确认、任务、MCP 连接、插件状态、远程状态、后台 session 等东西全部编排到同一个控制面里。
这意味着 Claude Code 的 UI 不是“模型回复展示器”,而是 runtime 的 orchestrator。一次用户输入进入 REPL 后,不是直接丢给模型,而是先经历几件事:
判断是不是本地命令、快捷指令或其他无需进入主循环的路径 组装当前这一轮执行所需的上下文 合并本地工具、外部工具、插件能力形成当前能力面 准备系统约束、用户环境和运行环境信息 最后才进入 query(...)
也就是说,REPL 先把“这一轮在什么制度下运行”准备好,再把控制权交给推理循环。
更具体地说,REPL 真正负责的是“当前能力面”的汇总。它要把本地 tools、MCP tools、plugin commands、动态 skills、任务状态、权限确认队列、MCP 连接状态、remote session 信息汇在一起,然后在用户提交输入的那个瞬间,生成一个完整的 turn-scoped 执行上下文。这也是为什么 REPL 会显得很大: 它并不是一个 view component,而是在做控制面拼装。
另外一层很重要的设计是,REPL 消费的不是纯文本,而是一串带语义的事件流。assistant message、tool progress、compact boundary、pending permission、task notification、API error,这些事件都会在这里重新归并成用户能理解的会话视图。换句话说,REPL 既是 query 的入口,也是整套运行时事件的落点。
Claude Code 的解法
Claude Code 没有把 REPL 做成薄薄的输入框加消息列表,而是让它负责两件大事:一是汇总当前能力面,二是归并当前事件流。能力面包括本地工具、外部工具、插件能力、任务状态、权限确认队列、远程会话信息;事件流包括助手消息、工具进度、待确认权限、任务通知、接口错误等。
所以 REPL 在 Claude Code 里既不是纯 view,也不是纯 controller,它更像 runtime 的操作台。用户每提交一次输入,REPL 都会先把当前 turn 的执行制度打包清楚,再交给 query loop;而 query loop 返回来的也不是原始文本,而是结构化运行时事件。
为什么这样好
这样设计的最大好处是“可控”。用户不是只看到一句模型回复,而是能看到系统正在执行什么、为什么停下来、当前有哪些能力、后台有哪些任务。对于需要权限确认、长时执行、工具调用的 Agent 来说,这种可控感往往比多一点模型智商更重要。
它还带来一个容易被忽略的收益:UI 不再只是消费文本,而是在消费统一事件协议。这样 query、permission、tool runtime、task system 都可以通过结构化事件和 REPL 协作,而不是各自偷偷改 UI 状态。
代价是 REPL 会变大,而且很难像普通前端那样被“优雅地拆成很多小组件”。但这不是坏事,因为它本来就不是简单页面,而是控制面。Claude Code 在这里的判断很清楚:运行时编排复杂度应该集中,不应该伪装成很多无边界的小组件。
我们怎么学
如果你的产品还停留在单轮问答,聊天 UI 足够。但只要系统已经进入工具执行、权限确认、后台协作阶段,UI 就必须承担显式控制面的职责。
最容易学错的地方,是把“控制面”理解成堆更多面板。真正该学的是显式化运行时关键状态:当前能力面、当前任务、当前权限状态、当前失败与恢复状态。不是界面越花越强,而是用户越能理解系统在做什么,越容易信任并驾驭它。一个很好的起点,就是先把后台任务和权限状态显式展示出来。
对复杂 Agent 来说,UI 做得好,用户看到的是系统在协作;UI 做得不好,用户看到的就只是一团偶尔会成功的黑箱。
三、Query Loop / QueryEngine:把单轮对话升级成状态机
如果说前两层是在搭台子,那么真正决定 Claude Code 像不像成熟 Agent runtime 的,就是 Query Loop。很多团队的 Agent 到了这里才开始真正分出高下。
核心矛盾
只要 Agent 开始连续运行,系统就会立刻碰到几个硬问题:长上下文会劣化,工具调用会打断推理,模型输出会截断,失败后要不要恢复,工具结果怎样回灌下一轮。这些问题如果还被当成“模型调用细节”,系统就会在复杂场景里迅速失稳。
先分清两个对象。
无界面会话引擎不是主循环本身,它更像会话外壳 真正的一次 agent turn 内核在 Query Loop 本体
无界面会话引擎做的事情很有代表性:先拉系统上下文,处理输入和命令,把用户消息先写进会话记录,暴露当前能力面,然后才把处理后的消息流交给主循环。这说明 Claude Code 不把 query 理解成“收到输入就打一次模型”,而是理解成“会话侧状态都准备好之后的最后一步”。
真正的核心在 Query Loop 本体。从状态组织方式就能看出来,这里维护的不是一次性请求参数,而是一组跨迭代状态:消息集、这一轮的执行上下文、上下文压缩状态、输出恢复计数、轮数预算、任务预算等。它明显不是 helper,而是状态机。
如果把源码里的状态骨架压到最小,会更容易看出它为什么已经是 runtime,而不是“模型调用封装”:
state = { messages, toolUseContext, maxOutputTokensOverride, autoCompactTracking, maxOutputTokensRecoveryCount, hasAttemptedReactiveCompact, turnCount, pendingToolUseSummary, transition,}这段骨架非常关键。一个普通 orchestrator 不会长期维护 autoCompactTracking、maxOutputTokensRecoveryCount、pendingToolUseSummary 这类对象;一旦这些状态都进入主循环,说明系统已经承认一件事:一次 agent turn 会被压缩、恢复、工具回灌、预算和中断反复改写。
从运行顺序看,Claude Code 对 query 的理解也非常“系统化”。它会先处理记忆预取、能力发现、上下文预算、各种压缩与折叠,再进入流式采样;一旦模型发出工具调用,runtime 就接管执行,把结果整理成结构化反馈、附加材料和后续提示,再重新送回下一轮推理。这说明在 Claude Code 里,模型不是一次性求值器,而是运行链路中的一个节点。
Claude Code 的解法
它把 query 拆成两层:会话外壳负责会话记录、输入处理、能力面暴露、无界面与接口场景;真正的 Query Loop 负责运行状态机,维护跨迭代状态,并在“推理 -> 工具 -> 回灌 -> 再推理”的闭环里反复推进。
这层最关键的设计,不是 while loop 本身,而是运行状态被显式保存了。Claude Code 很清楚,一次 agent turn 不是线性的 API 调用,而是一段会被工具、compact、fallback、token recovery、task budget 不断影响的运行。只有把这些状态升格成 runtime 对象,系统才不会变成一堆零散特判。
它大致在做下面这件事:
Claude Code 在这一层最强的地方,是它把“一次请求”理解成一段运行,而不是一问一答。于是很多本该是运行时问题的东西,都被提升成了 runtime 机制:
长上下文治理,不靠提示词硬扛,而是有 snip、microcompact、collapse、autocompact 失败恢复,不是报错就停,而是有 reactive compact、max output recovery、fallback model 工具结果,不是结束,而是下一轮输入 memory 和 skill discovery,不是同步堵塞,而是尽量藏到流式和工具执行的空隙里
再把主循环压成最小骨架,大致就是这样:
while (true) { prefetchMemoryAndSkills() messagesForQuery = applyBudget(messages) messagesForQuery = snipAndCompact(messagesForQuery) assistant = streamModel(messagesForQuery) if (!assistant.hasToolUse) return finishTurn(assistant) toolResult = runToolUse(assistant.toolUse, toolUseContext) state.messages = writeBack(messages, assistant, toolResult)}这和很多团队熟悉的“拿历史消息调一次模型,拿到结果就结束”完全不是一个层级。Claude Code 真正高明的点,不是 while loop 本身,而是它把 prefetch、budget、compact、tool result write-back 这些原来容易散落在边边角角的逻辑,全部拉回了主循环正中央。
如果把一次 query -> tool -> write-back 的真实控制权转移再压成一条缩略链,大概是这样:
messagesForQuery = getMessagesAfterCompactBoundary(messages)assistantMessages = streamModel(normalize(messagesForQuery))toolUseBlocks = collectToolUses(assistantMessages)toolUpdates = runTools(toolUseBlocks, assistantMessages, canUseTool, toolUseContext)toolResults = normalizeToolResults(toolUpdates)state.messages = [...messages, ...assistantMessages, ...toolResults]continue
这条链的价值非常大,因为它说明 Claude Code 不是“工具执行完了,往日志里打一行结果”这么简单。工具结果会被重新标准化成 user message,再回灌到主消息流里,下一轮模型看到的就是这段经过协议化处理后的历史。很多 Agent 系统会在这里偷懒,结果就是工具执行链和会话链是两张皮,后面越跑越乱。
为什么这种设计好?因为只要 Agent 进入多工具、多轮续跑、长上下文、失败恢复阶段,最脆弱的地方就不再是 prompt,而是运行链路本身。Claude Code 在这里做对的,不是某个具体 recovery 细节,而是认知升级了:上下文治理、失败恢复、工具回灌,都是 runtime 课题。
这里还有一个很有工程味的细节:Claude Code 会尽量把耗时工作藏在空隙里。memory prefetch 和 skill discovery 不是每轮都老老实实同步阻塞,而是尽量叠在流式输出和工具执行期间。这种设计看起来只是 latency 优化,实际上传达的是更成熟的运行时观念: Agent 的体验不只由模型速度决定,还由你能不能把未来大概率要用到的信息提前安排好。
为什么这样好
这样设计的好处,是它把最容易失控的复杂度都集中到了正确的位置上。上下文治理不再依赖提示词技巧,失败恢复不再散落在调用点,工具结果也不再只是 stdout,而是下一轮推理的结构化输入。系统因此能够持续运行,而不是每碰到一次工具调用或上下文膨胀就“断气”。
另一个很大的好处是,坏路径也被设计了。Claude Code 对 prompt-too-long、max_output_tokens、fallback model、继续续跑这些问题都给了 runtime 路径,而不是默认“失败就算了”。这对真实 Agent 系统特别重要,因为真实世界里坏路径往往比 happy path 更决定用户体验。
代价是 Query Loop 会很像一台小型运行机,而不是一个简单函数。它天然更难读、更难测,也更需要团队具备状态机心智。但这是成熟 Agent 不可回避的代价,因为连续运行本来就比单轮问答复杂得多。
我们怎么学
最值得学的不是每一个 compact/recovery 细节,而是判断升级:当系统开始“连续运行”时,query loop 就不该只是模型调用封装,而应该被单独当成一层系统设计。
如果你们还在单轮问答阶段,不必马上复制完整恢复体系;但一旦进入多工具、多轮续跑、长上下文阶段,就要尽快把上下文治理、失败恢复、工具回灌提升为 runtime 机制。别学错的地方,是把一堆恢复分支硬塞进业务代码;真正该复制的是“把失败路径也当主路径设计”的态度。团队动作上,可以先把“上下文治理”和“失败恢复”从 prompt 层挪到运行时层。
Query Loop 这一层真正值钱的,不是它写得有多复杂,而是它承认了一件很现实的事:连续运行从来不是一次模型调用能解决的问题。
四、Tool Runtime:把野生工具变成系统调用
很多 Agent 项目在工具层的默认心智是“给模型挂几个函数”。Claude Code 明显不是,它把工具层做成了一套受控执行协议。它不是在“接函数”,而是在设计“行动系统”。
核心矛盾
工具一旦开始碰文件、命令、网络和副作用,问题就不再是“模型会不会调用函数”,而是“这次行动是否合法、能否并发、如何上报进度、失败怎样表达、结果怎样重新喂给模型”。如果这些问题散落在每个工具里,系统很快就会失控。
从工具抽象和执行链的设计可以看出,Tool 在 Claude Code 里不是一个简单函数,而是一个带完整运行时语义的对象:有 schema、有输入校验、有权限关联、有并发安全声明、有中断语义、有结果回填规则。
真正的工具执行主链路,做的不是“找到函数然后调一下”,而是四段式执行:
解析真实 tool,做兜底 schema 校验和调用前准备 进入 permission 决策,再真正执行 把结果归一化成结构化反馈、进度和附加材料
这说明 Claude Code 对工具层的理解很成熟:工具不是模型的外挂函数,而是 runtime 的受治理执行单元。
这层还有一个容易被低估的点:Claude Code 把“未知工具”“参数不合法”“权限拒绝”“执行报错”都尽量归一化成协议内结果,而不是让整个回合直接炸掉。也就是说,它不是把工具调用看成业务函数成功或失败,而是看成 runtime 必须兜住的一类外部动作。只有这样,主循环才能在坏路径上继续工作,而不是每次失败都变成整轮崩溃。
Claude Code 的解法
Claude Code 的做法是把 Tool 定义成带完整运行时语义的对象,而不是简单函数签名。schema、输入校验、permission、并发安全、中断语义、结果回填规则,都进入 Tool 抽象本身;而统一执行链负责解析、校验、授权、执行、归一化。
这意味着工具层里的很多复杂度都被收敛了。开发者新增工具时,不需要重新思考权限弹窗怎么打、结果格式怎么写、是否能并发、进度怎么报,因为这…