夜雨聆风前言
前几天面试，与面试官聊 AI 的情况，聊着聊着突然冷不丁地来了一句：
"那么既然你使用过ClaudeCode，前段时间ClaudeCode源码泄漏事件有了解吗？聊一点ClaudeCode源码"
今天这篇文章，我就结合泄漏出来的 Claude Code 源码，把它的核心架构掰开揉碎讲清楚。读完这篇文章，下次面试官再问你 Claude Code 的内部原理，你应该能从容地应对。
在这篇博客中，你可以了解到：
Claude Code 的 Query Loop 主循环 是怎么运转的 它内置的 工具注册与调度机制 面试官最可能追问的 五层上下文压缩系统 Claude Code 的 Multi-Agent 多智能体架构 一套精巧的 安全治理层 为什么说 Harness Engineering 才是 AI Agent 的真正壁垒
第一：Query Loop — Agent 的心跳循环
如果你只能记住一个东西，记住这个。
Claude Code 本身并不是什么神秘的推理引擎。它的底层其实就是经典的「模型推理 → 工具调用 → 工具结果 → 再次推理」循环。在泄漏的源码里，这个循环的核心就在一个文件里：query.ts。
（注：此文章中所有涉及 ClaudeCode 的代码均来自 GitHub 项目：claude-code-sourcemap ）
先看最核心的主循环入口：
// query.ts 第307行
// eslint-disable-next-line no-constant-condition
while (true) {
// 每轮迭代：拼接上下文 → 调用API → 判断是否需要工具 → 执行工具 → 继续
let { toolUseContext } = state
// ...
}
看到了吗？一个 while (true) 死循环驱动整个 Agent 不断推理。那它什么时候停呢？关键在这个变量：
// query.ts 第558行
let needsFollowUp = false
每一轮 API 调用后，Claude Code 会检查模型的响应里有没有 tool_use 块：
// query.ts 第832-834行
if (msgToolUseBlocks.length > 0) {
toolUseBlocks.push(...msgToolUseBlocks)
needsFollowUp = true// 有工具需要执行，继续循环
}
工具执行完、结果塞回上下文、再调用 API……如此往复，直到：
// query.ts 第1062行
if (!needsFollowUp) {
// 没有更多工具调用，任务结束，退出循环
return { reason: 'completed' }
}
面试加分项：工具执行不是简单一个接一个串行跑。Claude Code 专门设计了一个 toolOrchestration.ts 来做工具调度编排。它会区分 并发安全的工具 （比如读文件、grep 搜索）和 需要串行的工具 （比如写文件），前者并发执行提升效率，后者顺序执行保证正确性：
// toolOrchestration.ts 第30-79行
if (isConcurrencySafe) {
// 只读工具批量并发跑
forawait (const update of runToolsConcurrently(blocks, ...)) { ... }
} else {
// 写操作串行跑，避免竞态
forawait (const update of runToolsSerially(blocks, ...)) { ... }
}
面试可以这样说：Claude Code 的核心是一个
while(true)的 Query Loop，每次循环做四件事——拼接上下文、调 Claude API、判断有没有工具调用、执行工具并将结果塞回上下文。当一次 API 调用不再产生工具调用时，循环结束，任务完成。
第二：Tool Registry — 容纳多种工具的容器
如果 Query Loop 是心脏，那工具系统就是它的四肢。Claude Code 最大的特点其实是它的工具运行时。
从泄漏的源码里能清晰地看到，Claude Code 内部有一个完整的 Tool Registry ，可以看作是容纳多种工具的容器。它在 tools.ts 里一口注册了多个工具：
// tools.ts 第170-250行 getAllBaseTools() 函数
functiongetAllBaseTools(): Tool[] {
return [
AgentTool, // 子Agent
BashTool, // Shell命令执行
FileReadTool, // 文件读取
FileEditTool, // 文件编辑
FileWriteTool, // 文件写入
GrepTool, // 内容搜索
GlobTool, // 文件名匹配
WebSearchTool, // 网络搜索
WebFetchTool, // 网页抓取
SkillTool, // 技能系统
TaskCreateTool, // 任务创建
EnterPlanModeTool, // 计划模式
EnterWorktreeTool, // Git工作树隔离
ExitWorktreeTool,
...cronTools, // 定时任务
ListMcpResourcesTool, // MCP资源
// ... 省略其它工具
]
}
Claude Code 就是把这些工具全部注册到一个统一的 注册中心 里，然后根据不同的运行模式动态组装：
// tools.ts 第271-314行
exportconst getTools = (permissionContext: ToolPermissionContext): Tools => {
// Simple模式：只给Bash、Read、Edit三个核心工具
if (isEnvTruthy(process.env.CLAUDE_CODE_SIMPLE)) {
return [BashTool, FileReadTool, FileEditTool]
}
// 完整模式：组装全部40+工具
const tools = getAllBaseTools()
// 再根据权限规则过滤掉被禁用的工具
let allowedTools = filterToolsByDenyRules(tools, permissionContext)
// ...
}
面试加分项：工具过滤不是在调用时才判断，而是在注册阶段就做了：
// tools.ts 第262-269行
exportfunctionfilterToolsByDenyRules(tools, permissionContext) {
return tools.filter(tool => !getDenyRuleForTool(permissionContext, tool))
}
这意味着如果某个工具被管理员禁用了，模型甚至不知道这个工具的存在——从根本上避免了"模型想用但被拒绝"的无用交互。
所有工具都遵循统一的接口规范：
// Tool.ts 第15-20行
exporttype ToolInputJSONSchema = {
type: 'object'
properties?: { [x: string]: unknown }
}
面试可以这样说：CluaCode 内置了多个工具，通过 Tool Registry 统一注册，再通过 Tool Dispatcher 调度。而且在工具层做了权限过滤—，即被禁用的工具对模型完全不可见。
第三：Context Engineering — 五层压缩系统
这可能是面试官最想听到的部分。
Coding Agent 最大的问题不是写代码的能力，而是上下文太长 → 信息衰减 → Token 成本爆炸。Claude Code 为了解决这个问题，设计了一套 5 层的上下文压缩系统。你可以把它类比成 JVM 的 GC——Agent 需要不断地清理"上下文内存"。
在 query.ts 里，每一轮 API 调用前，五层压缩按顺序依次执行。我们来一层层看：
第1层：Snip Compact（裁剪冗余）
// query.ts 第400-410行
if (feature('HISTORY_SNIP')) {
const snipResult = snipModule!.snipCompactIfNeeded(messagesForQuery)
messagesForQuery = snipResult.messages
snipTokensFreed = snipResult.tokensFreed // 记录释放了多少token
}
把历史对话里跟当前任务无关的冗余内容裁剪掉。
第2层：Micro Compact（微压缩）
// query.ts 第412-426行
const microcompactResult = await deps.microcompact(
messagesForQuery, toolUseContext, querySource,
)
messagesForQuery = microcompactResult.messages
微压缩会针对特定的工具结果做压缩——比如之前读的文件内容、grep 的输出，只保留关键信息，扔掉原始冗余数据。哪些工具需要被压缩？源码里写得很清楚：
// microCompact.ts 第41-50行
const COMPACTABLE_TOOLS = new Set([
FILE_READ_TOOL_NAME, // 文件读取结果
...SHELL_TOOL_NAMES, // Shell命令输出
GREP_TOOL_NAME, // 搜索匹配行
GLOB_TOOL_NAME, // 文件匹配结果
WEB_SEARCH_TOOL_NAME, // 网页搜索结果
WEB_FETCH_TOOL_NAME, // 网页抓取内容
// ...
])
第3层：Context Collapse（上下文折叠）
// query.ts 第440-447行
if (feature('CONTEXT_COLLAPSE') && contextCollapse) {
const collapseResult = await contextCollapse.applyCollapsesIfNeeded(
messagesForQuery, toolUseContext, querySource,
)
messagesForQuery = collapseResult.messages
}
折叠是将历史对话中的整段内容做结构化归档——信息不丢，但以更紧凑的方式存储。
第4层：Auto Compact（自动压缩，重要）
// query.ts 第453-543行
const { compactionResult, consecutiveFailures } = await deps.autocompact(
messagesForQuery, toolUseContext, { ... }, querySource, tracking, snipTokensFreed,
)
当上下文超过阈值时，自动触发。它会另起一个 Agent 来生成整个对话的摘要，然后把原始对话替换成压缩版。threshold 怎么定的？
// autoCompact.ts 第28-30行
const MAX_OUTPUT_TOKENS_FOR_SUMMARY = 20_000 // 预留2万token给摘要输出
// autoCompact.ts 第62-64行
exportconst AUTOCOMPACT_BUFFER_TOKENS = 13_000 // 自动压缩缓冲区
exportconst WARNING_THRESHOLD_BUFFER_TOKENS = 20_000 // 警告阈值
有意思的是，自动压缩还有熔断机制：
// autoCompact.ts 第70行
const MAX_CONSECUTIVE_AUTOCOMPACT_FAILURES = 3
// 连续失败3次就停止重试，避免死循环浪费API调用
第5层：Reactive Compact（被动兜底）
// query.ts 第15-16行
const reactiveCompact = feature('REACTIVE_COMPACT')
? require('./services/compact/reactiveCompact.js')
: null
即便前面四层都没拦住，当 API 真的返回 prompt_too_long 时，Reactive Compact 还是会兜底处理——相当于做了一个 try-catch 层面的保护。
用一个表格来简单总结一下：
面试可以这样说：它内部设计了一套五层上下文压缩系统，像 GC 一样管理 token 上下文。具体包括 Snip、Micro Compact、Context Collapse、Auto Compact、Reactive Compact，层层递进。最核心的 Auto Compact 会在接近上下文窗口时自动触发，甚至还有熔断机制防止死循环。
第四：Multi-Agent — 主从协作的智能体军团
泄漏的源码里比较让人兴奋的一点是，Claude Code 已经不是单纯的单一 Agent 了。它已经演进到了 Coordinator + SubAgent 的模式。
这里的 Coordinator 指的就是 协调器 。在 Claude Code 的架构里，Coordinator 就是一个纯粹的 管理者 角色。它不亲自下场写代码，但负责所有关键的管理工作：
拆解任务 ：接到需求后，Coordinator 会判断任务的复杂程度，决定哪些部分可以交给专家去处理，并着手规划整体蓝图。
分配工作 ：规划好后，它会像项目经理给工程师分配任务一样，为每个特定任务创建一个或多个 SubAgent（子智能体）。
汇聚结果 ：所有 SubAgent 完成任务后，会把成果汇报给 Coordinator ，由它进行汇总、分析和整合，形成最终答案交还给你。
而 SubAgent 相当于 各个领域里专注于执行的专家 。它们有几个独特优势：
专职专能 ：每个SubAgent都被赋予了 特定的任务和有限的工具 。比如，"调研Agent"可能只有代码库的"只读"权限；而"实现Agent"则拥有修改和创建文件的权限。
独立工作，互不干扰 ：每个SubAgent拥有自己完全独立的 上下文窗口 。这意味着，负责调研的Agent不会因为看到的无关信息而干扰负责写代码的Agent的判断。
并行工作 ：因为是独立的，Coordinator可以 同时启动多个SubAgent 来处理互不依赖的子任务，大大缩短了整体完成时间。
用完即走 ：SubAgent完成任务、返回结果后，其生命周期就结束了，不会持续占用系统资源。
AgentTool 是整个 Multi-Agent 系统的核心。在 AgentTool.tsx 里可以看到，它能创建独立的子 Agent 来并行处理任务：
// AgentTool.tsx 导入的关键模块
import { spawnTeammate } from'../shared/spawnMultiAgent.js'
import { createAgentWorktree, removeAgentWorktree } from'../../utils/worktree.js'
import { runAsyncAgentLifecycle, completeAgentTask, failAgentTask } from'./agentToolUtils.js'
// AgentTool支持：
// - isolation: 'worktree' → Git工作树隔离
// - run_in_background: true → 后台异步执行
Agent 之间通过 SendMessageTool 通信，支持结构化消息：
// SendMessageTool.ts 第46-65行 — 支持的结构化消息类型
const StructuredMessage = z.discriminatedUnion('type', [
z.object({ type: z.literal('shutdown_request'), ... }), // 关闭请求
z.object({ type: z.literal('shutdown_response'), ... }), // 关闭响应
z.object({ type: z.literal('plan_approval_response'), ... }), // 计划审批
])
再往上看，Coordinator Mode 负责整体任务的拆解和分配：
// coordinatorMode.ts 第36-41行
exportfunctionisCoordinatorMode(): boolean{
if (feature('COORDINATOR_MODE')) {
return isEnvTruthy(process.env.CLAUDE_CODE_COORDINATOR_MODE)
}
returnfalse
}
// coordinatorMode.ts 第29-34行
const INTERNAL_WORKER_TOOLS = new Set([
TEAM_CREATE_TOOL_NAME, // 创建子团队
TEAM_DELETE_TOOL_NAME, // 删除子团队
SEND_MESSAGE_TOOL_NAME, // Agent间通信
SYNTHETIC_OUTPUT_TOOL_NAME, // 结构化输出
])
可以用一个流程图来概括以上内容：
面试可以这样说：Claude Code 有一个 Coordinator 负责拆解任务，通过 AgentTool 创建多个 SubAgent 并行执行。Agent 之间用 SendMessageTool 做通信，支持各种结构化消息。SubAgent 还能做文件系统隔离。
第五：安全治理 — 一个工具七个安全文件
Claude Code 能直接执行 Shell 命令。rm -rf、curl | bash……任何一个出了事都是严重事故。
所以它内部的安全层设计得非常重。我们只要看一个文件目录就够了：
tools/BashTool/
├── BashTool.tsx # 主文件
├── bashPermissions.ts # 权限检查入口
├── bashSecurity.ts # 安全检查
├── bashCommandHelpers.ts # 命令辅助
├── sedValidation.ts # sed命令验证
├── pathValidation.ts # 路径验证
├── modeValidation.ts # 模式验证
└── shouldUseSandbox.ts # 沙箱判断
一个 Bash 工具，配套了 7 个安全相关的文件。
权限检查的核心入口在 bashPermissions.ts，它依赖了一整套安全检查链：
// bashPermissions.ts 第1-100行 集成的安全检查模块
import {
classifyBashCommand, // 命令分类器：对命令做风险分级
isClassifierPermissionsEnabled,
} from'../../utils/permissions/bashClassifier.js'
import { parseForSecurityFromAst } from'../../utils/bash/ast.js'// AST解析
import { extractRules } from'../../utils/permissions/PermissionUpdate.js'
import { getRuleByContentsForTool } from'../../utils/permissions/permissions.js'// 规则匹配
import { SandboxManager } from'../../utils/sandbox/sandbox-adapter.js'// 沙箱
权限决策链路大致是这样的：
其中 Hook 就像在命令执行的“必经之路”上，安插了一个可以自定义的检查哨。回调 指的是：当命令走到这个检查哨时，会主动调用你提前写好的某个函数（比如一个自定义脚本、一个用户确认弹窗、或者一个日志记录器），等这个函数返回结果后，再决定继续还是终止。
面试可以这样说：Claude Code 的安全治理层非常重。以 BashTool 为例，一个执行工具配套了 7 个安全文件。命令执行前要走 6 步安全检查——AST 解析、命令分类、规则匹配、安全校验、沙箱判断、Hook 回调。
第六：真正的壁垒 — Harness Engineering
说到这，其实可以做一个总结了。
很多人觉得 AI Agent 的竞争核心是大模型本身——谁的模型强，谁的 Agent 就强。但你看完 Claude Code 的源码会发现：模型只是 CPU，而 Claude Code 的 Runtime 才是一个完整的操作系统。
Runtime 可以看作是 Agent 的整个运行环境和后勤系统 ，你可以这样理解：模型（比如 Claude、DeepSeek） 就像 大脑 ，负责思考、推理、生成想法；Runtime 则像是 躯体 + 神经系统 + 肌肉记忆 + 工作流程 的总和。它包括：
怎么记住之前说过的话（上下文管理、Memory 系统）
怎么用各种工具（工具调度，比如调用终端、读写文件、搜索代码）
怎么同时处理多个任务（多 Agent 协调）
怎么保证安全（权限系统，防止 AI 乱删文件）
怎么在任务中断后恢复（生命周期管理、Hook）
怎么安排工作的先后顺序（工作流编排）
没有 Runtime，模型就像一个很聪明但没有手脚、没有记忆、也不会用工具的人——只能空谈，不能实干。
回到源码目录结构，我们可以看到这个 Runtime 的全貌：
src/
├── query.ts # Query Loop 循环引擎
├── query/ # 查询相关子模块
├── QueryEngine.ts # 查询引擎
├── tools.ts # 工具注册中心
├── tools/ # 40+工具实现（每个都有独立目录）
├── services/compact/ # 5层上下文压缩
│ ├── snipCompact.ts
│ ├── microCompact.ts
│ ├── autoCompact.ts
│ ├── compact.ts
│ └── reactiveCompact.ts
├── coordinator/ # Multi-Agent协调
├── hooks/ # 80+个Hook（生命周期管理）
├── context.ts # 系统提示词动态构建
├── memory/ # Memory持久化系统
├── skills/ # 技能插件系统
├── server/ # HTTP/SSE服务端
├── plugins/ # 插件扩展体系
└── main.tsx # 运行时入口
你会发现，这里的核心壁垒不在于「调用哪个模型」。换成 DeepSeek、换成 Qwen、换成任何一个底层模型，上面这一整套编排层都可以独立工作。真正的竞争壁垒在：
上下文管理 — 五层压缩是怎么协同的 工具调度 — 40+ 工具如何高效、安全地调度 多 Agent 协作 — Coordinator 如何拆解和聚合 权限系统 — 多层安全防护如何嵌入每个执行路径 Memory 系统 — 跨 Session 的记忆如何持久化和检索 工作流编排 — 从简单的单次对话到复杂的 Multi-Agent 流水线
这就是Harness Engineering——Agent 编排工程。Claude Code 泄漏事件最有价值的地方，就是让行业第一次清楚地看到：AI Agent 的真正高度，不只是模型决定的，而是由 Agent Runtime 决定的。
面试可以这样说：我觉得 Claude Code 给行业最大的启示是——AI Agent 的核心壁垒已经不在模型层了，而是在编排层。模型像 CPU，而 Claude Code 更像一个操作系统。上下文管理、工具调度、多 Agent 协作、权限系统、Memory 系统、工作流编排这些才是真正决定 Agent 上限的工程能力。
结尾
如果这篇文章帮你搞清楚了一句话——「Claude Code 的源码里有什么」，那下次面试官再问起，你至少可以不再支支吾吾聊不起。
如果觉得这篇文章有用，不妨点赞、收藏、转发一波~ 你的支持是我继续深挖的动力！
