Claude Code 源码架构深度解读

基于 1,884 个 TypeScript 文件、512,000+ 行代码的全量源码分析。 揭示 Anthropic 旗舰级 AI 编程工具背后的工程哲学:1.6% 的 AI 决策逻辑 + 98.4% 的确定性基础设施。

1,884
TypeScript 文件
512K+
代码行数
54+
内置工具
7 层
安全防护
5 层
上下文压缩

一、总体架构:五层子系统分解

Claude Code 的架构遵循"最小脚手架、最大操作线束"原则。模型负责推理,而线束(harness)负责执行。 整个系统被分解为 5 个架构层、7 个功能组件,其中核心的 Agent Loop 只是一个简单的 while-true 循环—— 真正的工程复杂性存在于围绕它的上下文管理、权限控制、安全防护和状态持久化等子系统中。

Surface 层
入口层
CLI 终端界面
SDK 接口
IDE 插件 (VS Code)
React + Ink 渲染
Core 层
核心引擎
Agent Loop (queryLoop)
Context Compaction
Streaming Executor
Sub-Agent Dispatch
Safety 层
安全 & 动作
Permission System (7模式)
Tool Pool (54+ 工具)
Hook Pipeline (27事件)
Shell Sandbox
State 层
状态 & 持久化
CLAUDE.md 记忆层级
JSONL Session 日志
history.jsonl 全局历史
POSIX flock() 协调
Backend 层
执行环境
Bash 执行引擎
文件系统操作
MCP Server 桥接
进程管理 (Bun)
核心设计洞察

Claude Code 的 Agent Loop 仅占总代码量的约 1.6%,其余 98.4% 都是确定性的基础设施代码。 这意味着整个系统的工程复杂度并不在"如何让模型做决策"上,而在于"如何安全、可靠、高效地执行模型的决策"。 Agent Loop 是一个 AsyncGenerator,遵循 ReAct 模式,但真正的精华在于围绕它构建的五层上下文压缩管线、七层安全防护机制和四级记忆层级体系。

TypeScript Bun Runtime React + Ink AsyncGenerator JSONL Persistence POSIX flock() MCP Protocol

二、Agent Loop:9 步 ReAct 循环

Agent Loop 的核心是 query.ts 中的 queryLoop() 异步生成器。它遵循经典的 ReAct(Reasoning + Acting)模式: 收集上下文 → 调用模型 → 分发工具 → 验证结果。每次迭代都是一个完整的 9 步管线。

Settings
解析
→
State
初始化
→
Context
组装
→
Pre-model
5阶段压缩
→
Model
API 调用
→
Tool
分发
→
Permission
门控
→
Execution
执行
→
Stop
条件检查

伪代码示意

async function* queryLoop(config, initialContext) { const state = initMutableState(config); let context = assembleContext(initialContext, state); while (true) { // 5 阶段上下文压缩 context = budgetReduce(context); context = snip(context); context = microCompact(context); context = contextCollapse(context); context = autoCompact(context); // 调用 Claude API const response = await callModel(context, tools); yield response; // 工具分发与权限门控 if (response.toolUse) { const permitted = await checkPermission(response.toolUse, state); if (permitted) { const result = await executeTool(response.toolUse); state.appendTranscript(result); } } // 停止条件检查 if (shouldStop(response, state)) break; } }

停止条件

无工具调用

模型回复中不包含任何 tool_use,说明任务完成或模型选择直接回答。

最大轮次到达

达到配置的最大交互轮数限制,防止无限循环。

上下文溢出

上下文窗口无法进一步压缩,系统安全退出。

Hook 干预

某个 Hook 事件处理器主动中断了循环。

显式中止

用户通过 Ctrl+C 或程序信号主动中止。

流式执行优化

Claude Code 使用 StreamingToolExecutor 进行工具执行:只读工具(如文件读取、搜索)可以并发执行以降低延迟, 而修改状态的工具(如文件写入、Bash 命令)则串行执行以保证一致性。当流式执行器不可用时,自动降级为同步的 runTools 回退路径。

三、工具系统:54+ 工具的动态装配

Claude Code 的工具系统是其执行能力的核心。系统维护一个最多 54 个内置工具的工具池,通过 assembleToolPool() 动态装配。工具分为并发安全型和独占型,分别对应不同的执行策略。

📁 文件操作

Read, Write, Edit, Glob, Grep 等。提供文件读写、搜索、模式匹配能力。Edit 工具支持精确字符串替换。

⚡ Bash 执行

真正的编排骨干。用于运行测试、构建项目、Git 操作、进程管理。支持超时和后台执行。

🌐 网络工具

WebFetch 和 WebSearch,用于获取网页内容、API 调用和网络搜索。

🤖 子代理 (Task)

生成独立的子代理处理复杂子任务。拥有隔离的上下文窗口,仅向父代理返回摘要。

🔌 MCP 工具

通过 Model Context Protocol 连接外部服务(Slack、GitHub 等),动态扩展工具池。

🎨 辅助工具

图片生成、TodoWrite 任务追踪、AskUserQuestion 用户交互等辅助功能。

工具装配流程

枚举
全部可用工具
→
过滤
权限预筛选
→
去重
名称冲突检测
→
合并
+MCP 工具
→
就绪
Tool Pool

工具分类为 concurrent-safe(并发安全)和 exclusive(独占)两类。并发安全型工具如文件读取、搜索等可以并行执行, 独占型工具如文件写入、Bash 命令等必须串行执行。这种分类机制在保证正确性的前提下最大化了执行效率。

四、权限系统:7 种模式的渐进信任谱

权限系统是 Claude Code 安全架构的核心支柱。它实现了"deny-first with human escalation"(拒绝优先、人工升级)的安全策略, 提供 7 种权限模式形成一个信任谱——从最保守的 plan 模式到完全放开的 bypassPermissions 模式。

模式 信任级别 行为描述
plan
最保守。模型只能制定计划,不能执行任何实际操作。
default
默认模式。读操作自动放行,写操作和 Bash 命令需要用户确认。
acceptEdits
自动接受文件编辑,但 Bash 命令仍需确认。
auto
ML 分类器自动评估操作安全性。学习用户信任模式,减少审批疲劳。
dontAsk
不弹出确认对话框,但仍有规则层面的限制。
bypassPermissions
完全放开。跳过所有权限检查,仅限受信环境使用。
bubble (内部)
子代理内部模式。权限请求冒泡到父代理的终端进行裁决。
Deny-First 规则求值

权限规则的求值顺序是"deny 优先":任何一条 deny 规则命中即拒绝操作,即使有其他 allow 规则匹配。 无法识别的操作一律升级为人工确认。这种设计确保了安全下限——宁可多问一次用户,也不放过一次潜在的危险操作。 此外,会话恢复时权限不会被恢复(no permission restoration on resume),每次恢复都重新建立信任。

五、记忆与上下文管理

上下文窗口是整个系统的绑定资源约束。Claude Code 为此构建了一套精密的四级记忆层级体系和五层压缩管线, 确保在有限的 token 预算内最大化信息密度。

CLAUDE.md 四级记忆层级

🏛️
Managed(托管层)
~/.claude/CLAUDE.md — Anthropic 托管的全局配置
👤
User(用户层)
~/.claude/CLAUDE.md — 用户个人偏好与全局指令
📂
Project(项目层)
./CLAUDE.md — 项目级约定、代码规范、架构说明
🔒
Local(本地层)
./CLAUDE.local.md — 本地开发环境特定配置(不入库)

记忆检索不使用向量数据库或 embedding,而是基于 LLM 扫描文件头部的透明机制。 这种"文件即记忆"的设计让记忆对用户完全可见可编辑——用户直接编辑 CLAUDE.md 文件就能修改 AI 的行为。

五层上下文压缩管线

在每次调用模型 API 之前,系统都会依次执行 5 个压缩阶段,确保上下文不超出 token 限制:

Budget Reduction
预算裁剪
按 token 预算截断低优先级内容
→
Snip
片段裁剪
移除冗余的工具输出
→
Micro Compact
微压缩
精简对话历史细节
→
Context Collapse
上下文折叠
合并相似的工具调用
→
Auto Compact
自动压缩
LLM 摘要式压缩全文
Context Scarcity 设计哲学

Claude Code 从设计第一天起就假设 token 是稀缺资源。上下文组装使用 memoization 避免重复计算, 使用 lazy loading 确保未使用的指令不消耗 token。整个压缩管线的设计目标不是"塞入更多信息", 而是"在有限空间内保留最高价值的信息"。

六、安全防护:7 层纵深防御

Claude Code 采用经典的"纵深防御"(Defense in Depth)策略,部署 7 个独立的安全层。 任何一层都可以独立阻止一个操作——即使其他层全部失效,单层也能兜底。

1
工具预过滤(Tool Pre-filtering) — blanket-denied 的工具在装配阶段就从工具池中移除,模型甚至看不到它们的存在。
2
Deny-First 规则求值 — 权限规则按 deny 优先策略求值,deny 规则覆盖同范围的 allow 规则。
3
权限模式约束 — 7 种权限模式形成信任谱,用户可按需选择保守到激进的信任级别。
4
Auto 模式 ML 分类器 — 在 auto 模式下,ML 分类器独立评估每个操作的安全性,学习用户的信任模式。
5
Shell 沙箱隔离 — Bash 命令在受限的 shell 环境中执行,限制文件系统和网络访问范围。
6
会话恢复无权限继承 — 恢复会话时不继承之前的权限授予,信任必须在新会话中重新建立。
7
Hook 拦截 — 通过 PreToolUse / PostToolUse 等 Hook 事件,外部系统可以在工具执行前后注入安全检查逻辑。
可逆性加权评估

安全评估不仅看操作类型,还看操作的可逆性。读取文件是高度可逆的(无副作用), 写入文件是中等可逆的(可通过 Git 回滚),而删除文件或执行不可逆 Bash 命令则需要更高的信任级别。 这种基于可逆性的风险评估贯穿整个权限系统的设计。

七、Hook 系统与四种扩展机制

Claude Code 提供了四种渐进式的扩展机制,按上下文开销从低到高排列: Hooks → Skills → Plugins → MCP Servers。每种机制在不同的抽象层级上扩展系统能力。

Hook 管线:27 种事件类型

Hook 是最轻量的扩展机制,通过事件监听器在 Agent Loop 的生命周期关键节点注入自定义逻辑。 每个 Hook 可以修改工具输入/输出、注入额外上下文、甚至阻止操作执行。

PreToolUse
工具执行前触发。可以 deny、ask 或修改输入参数。
PostToolUse
工具执行后触发。可以注入上下文或修改输出结果。
PermissionDenied
权限被拒绝时触发。可以启用外部重试或引导逻辑。
PreModelCall
模型调用前触发。可以修改上下文或注入系统提示。
PostModelCall
模型响应后触发。可以过滤或修改模型输出。
SessionStart
会话开始时触发。初始化外部资源或加载配置。
SessionEnd
会话结束时触发。清理资源或上报统计。
+ 20 种其他事件
覆盖子代理生命周期、压缩事件、错误处理等。

四种扩展机制对比

Hooks

上下文开销最低。通过 JSON 配置事件监听器,不消耗 token。适合安全策略注入和 CI/CD 集成。

Skills

中等开销。以 Markdown 文件形式提供领域知识和最佳实践,按需加载到上下文。

Plugins

较高开销。可注册新工具和指令,但会占用上下文窗口空间。

MCP Servers

最高开销也最强大。通过 Model Context Protocol 连接外部服务,提供实时数据和操作能力。

八、子代理系统:隔离式任务委托

Claude Code 采用"主代理 + 子代理"(lead-agent-plus-subagents)模式。 主代理负责协调和决策,子代理负责执行具体的子任务。每个子代理运行在隔离的上下文窗口中, 仅向父代理返回结果摘要——这种设计防止了子代理的对话历史膨胀父代理的上下文。

主代理 (Parent Agent)
协调决策 · 完整上下文 · 用户交互 · 权限裁决
↙ ↓ ↘
子代理 A
隔离上下文
受限工具集
bubble 权限模式
→ 返回摘要
子代理 B
隔离上下文
受限工具集
bubble 权限模式
→ 返回摘要
子代理 C
隔离上下文
受限工具集
bubble 权限模式
→ 返回摘要
上下文隔离

每个子代理拥有独立的上下文窗口。Sidechain 日志独立存储子代理的对话历史,防止父上下文膨胀。

权限冒泡

子代理使用内部的 bubble 权限模式——遇到需要权限的操作时,请求冒泡到父代理的终端进行裁决。

受限工具集

子代理只能访问主代理分配的工具子集,不能直接访问所有系统资源或用户交互工具。

九、状态管理:Append-Only 持久化

Claude Code 的状态管理采用"append-only"(仅追加)设计,所有会话操作都以 JSONL 格式追加写入日志文件。 这种设计让系统具备了强大的恢复能力——可以从日志重建任意时间点的状态,支持恢复(resume)、 分叉(fork)和回退(rewind)操作。

会话日志 (Session Transcript)

每次工具调用、模型响应、权限决策都以 JSON 行追加到会话日志。支持断点续传和状态恢复。

全局历史 (history.jsonl)

跨会话的全局历史记录,用于长期趋势分析和上下文关联。

进程协调 (POSIX flock)

使用文件锁机制协调多个 Claude Code 实例的并发访问,防止状态文件冲突。

状态重建

从 append-only 日志重建完整状态,支持 resume(恢复)、fork(分叉)和 rewind(回退)。

十、核心设计模式总结

纵深防御 (Defense in Depth)

多个独立的安全层共享失败模式。即使 6 层防护全部失效,第 7 层仍能兜底。 安全不是单点机制,而是多层冗余的系统工程。

渐进信任 (Graduated Trust)

用户通过 7 种权限模式沿信任谱逐步升级。从 plan(只读)到 bypass(全权), 信任是挣来的,不是默认授予的。ML 分类器在 auto 模式下学习用户的信任模式。

上下文稀缺 (Context Scarcity)

从第一天起就假设 token 是稀缺资源。五层压缩管线、memoization、lazy loading—— 一切设计都围绕"在有限空间内最大化信息价值"。

可逆性优先 (Reversibility)

风险评估按操作的可逆性加权。读操作(无副作用)自动放行, 写操作(可 Git 回滚)中等审查,删除操作(不可逆)严格管控。

仅追加状态 (Append-Only State)

所有状态变更记录为 JSONL 日志,支持完整的时间旅行式恢复。 不依赖数据库,不使用复杂的状态机——文件系统就是最好的数据库。

人机决策权分离 (Human Decision Authority)

模型推理、线束执行、人类裁决。三者职责清晰,不可越权。 模型不能绕过权限系统直接执行操作,用户始终保有最终否决权。

十一、彩蛋:未发布的隐藏特性

源码泄露还揭示了一些通过 feature flags 隐藏但尚未发布的计划特性:

afk-mode

AFK 模式——允许 Claude Code 在用户不在时自主运行,适合长时间后台任务。

advisor-tool

顾问工具——可能是一种"只建议不执行"的辅助决策模式。

Browser Automation

浏览器自动化——让 Claude Code 具备操控浏览器的能力。

KAIROS Daemon

名为 KAIROS 的后台守护进程——用于后台索引和持续监控,类似 Chyros 记忆守护进程的进化版。

总结

Claude Code 的架构展现了一个成熟的 AI 编程工具应该如何构建:不是简单地包装一个 LLM API, 而是围绕"安全执行、可靠运行、人机协作"三大目标,构建了一套完整的工程体系。 它的核心哲学可以归结为一句话——模型负责思考,基础设施负责执行,人类保有最终决策权。

从五层子系统分解到七层安全防护,从四级记忆层级到五层上下文压缩,从七种权限模式到 27 种 Hook 事件—— 每一个子系统都体现了"最小化 AI 决策范围、最大化确定性工程保障"的设计理念。 这或许是当前市面上最成熟的 agentic coding 工具架构之一。