Claude Code源码分析------Claude Code 核心架构与关键模块实现设计
- [Claude Code 核心架构与关键模块实现设计](#Claude Code 核心架构与关键模块实现设计)
-
- [1. 文档定位](#1. 文档定位)
- [2. 核心心智模型](#2. 核心心智模型)
- [3. 总体架构分层](#3. 总体架构分层)
- [4. 主运行链路](#4. 主运行链路)
- [5. 请求级时序图](#5. 请求级时序图)
- [6. 11 个关键模块设计](#6. 11 个关键模块设计)
-
- [6.1 System Prompt 分层设计](#6.1 System Prompt 分层设计)
- [6.2 Agent Loop 核心循环](#6.2 Agent Loop 核心循环)
- [6.3 工具系统架构](#6.3 工具系统架构)
- [6.4 权限模型](#6.4 权限模型)
- [6.5 上下文管理与压缩](#6.5 上下文管理与压缩)
- [6.6 Prompt Cache](#6.6 Prompt Cache)
- [6.7 多 Agent 协作](#6.7 多 Agent 协作)
- [6.8 MCP 集成](#6.8 MCP 集成)
- [6.9 启动性能优化](#6.9 启动性能优化)
- [6.10 Feature Flag 体系](#6.10 Feature Flag 体系)
- [6.11 安全机制](#6.11 安全机制)
- [7. 模块关系总图](#7. 模块关系总图)
- [8. 关键设计原则](#8. 关键设计原则)
- [9. 结论](#9. 结论)
Claude Code 核心架构与关键模块实现设计
1. 文档定位
本文更偏架构视角：用架构图、流程图、时序图展示claudecode各个模块如何协作。
一句话概括：
Claude Code 是一个围绕模型运行的本地 Agent Runtime，用 Prompt、工具、权限、上下文、缓存、MCP、多 Agent 和安全机制，把模型能力转化为可控的软件工程执行能力。
2. 核心心智模型
Claude Code 不是"模型直接操作电脑"，而是"三方协作"。
提出任务
组装 Prompt / Context / Tools
文本或 tool_use
权限检查后执行
文件 / Shell / Git / MCP / 网络结果
tool_result
流式渲染
用户
Claude Code 本地运行时
Claude 模型
本机环境
核心边界：
- 模型负责理解、规划和选择下一步。
- Claude Code 负责上下文装配、工具执行、权限判定和安全治理。
- 本机环境只通过受控工具暴露给模型。
3. 总体架构分层
横切治理层
扩展与集成层
基础能力层
终端 UI 层
React + Ink
输入 / 输出 / 流式渲染 / 权限弹窗
CLI 与启动层
src/main.tsx
参数解析 / 配置初始化 / 预取 / 权限模式归一化
会话编排层
src/QueryEngine.ts
消息历史 / token / 权限拒绝 / 本轮参数
执行循环层
src/query.ts
模型调用 / tool_use / tool_result / continue / compact
System Prompt
Tool System
Permission Model
Context Management
Compaction
Prompt Cache
MCP
Multi-Agent
LSP
OAuth
Plugins / Skills
Security
Feature Flags
Startup Optimization
这个架构的关键取舍是：query.ts 的主循环尽量保持直接，复杂性由外围模块承接。
4. 主运行链路
一次典型任务从用户输入到最终输出，可以拆成下面的主链路。
否
是
继续
compact
终止
MF-01 用户提交任务
MF-02 CLI 启动与运行时初始化
MF-03 组装 Prompt / Context / Tools
MF-04 发起模型请求
MF-05 模型输出类型
自然语言输出
tool_use
MF-06 权限系统判定
允许执行?
拒绝 / 询问用户 / 记录 denial
MF-07 工具执行
MF-08 tool_result 回填消息流
MF-09 继续 / compact / 终止
触发上下文压缩
MF-10 UI 渲染最终结果
5. 请求级时序图
下面用时序图展示 QueryEngine、queryLoop、模型、工具和权限系统之间的协作。
UI Tool Executor Permission Claude Model queryLoop Query Context QueryEngine User UI Tool Executor Permission Claude Model queryLoop Query Context QueryEngine User alt [allow] [ask / deny] alt [assistant 返回 tool_use] [无 tool_use] submitMessage(user input) fetchSystemPromptParts() systemPrompt + userContext + systemContext 准备模型 / tools / wrappedCanUseTool / 会话状态 start query(messages, context, tools) API request streaming assistant content 流式文本 / 工具状态 canUseTool(tool, input) allow / ask / deny execute tool ToolResult 转成 tool_result user-side message 下一轮 API request 记录 permission denial 展示确认或拒绝信息 最终回答
6. 11 个关键模块设计
6.1 System Prompt 分层设计
Claude Code 的 Prompt 是运行时装配结果，不是单个固定字符串。
并列上下文通道
override prompt
coordinator prompt
agent prompt
custom prompt
default system prompt
append prompt
effective system prompt
systemPrompt
userContext
CLAUDE.md / 项目规则 / 记忆
systemContext
OS / cwd / Git / 环境
本轮模型请求
Prompt 内部还会划出稳定区和动态区。
静态区
身份 / 工程原则 / 安全规则 / 输出风格
SYSTEM_PROMPT_DYNAMIC_BOUNDARY
动态区
会话指导 / 语言偏好 / MCP 指令 / Feature 片段
Prompt Cache 友好前缀
关键实现点：
systemPrompt、userContext、systemContext分通道进入请求。CLAUDE.md放入userContext，避免污染稳定 prompt 前缀。- MCP instructions 这类高波动信息尽量迁移到 delta 或 attachment 机制。
6.2 Agent Loop 核心循环
否
是
allow
ask / deny
compact
继续
终止
开始
整理 messages / context
调用模型
流式接收 assistant content
是否存在 tool_use?
自然语言最终输出
权限检查
权限结果
执行工具
ask / deny
生成 tool_result
继续 / compact / 终止
触发 compact
结束
关键实现点：
QueryEngine管会话状态，queryLoop()管请求内循环。tool_use识别不是只看stop_reason，而是扫描 assistant content block。tool_result会被显式重建成下一轮 user-side message。- 单 loop 默认偏顺序，需要并发时通过多 Agent 引入多个独立 loop。
6.3 工具系统架构
本轮真实工具池
模型 tool_use
Built-in Tools
MCP Tools
Feature Flag Tools
getTools()
内置工具过滤
assembleToolPool()
合并 built-in + MCP
toolUseContext.options.tools
工具查找
name / alias
参数 schema 校验
工具权限检查
tool.call()
ToolResult
协议层 tool_result
工具契约可以看成一个受控 API：
Tool 契约
name
description
inputSchema
permissionSemantics
call()
render()
resultFormatter()
关键实现点：
- 工具描述本身就是给模型看的细粒度 Prompt。
- 工具系统分为注册层、编排层、执行层。
BashTool是最复杂工具，因为它需要命令语义、路径、破坏性动作和沙箱分析。- 内置工具和 MCP 工具进入同一个执行池，但 MCP 保留协议特例。
6.4 权限模型
权限系统不是一个 if，而是一条判定流水线。
模型请求工具调用
当前 permission mode
工具权限语义
参数敏感度分析
路径安全检查
deny / ask / allow 规则
safety check
最终决策
自动允许
提示用户确认
直接拒绝
记录 permission denial
权限模式在启动阶段先被归一化。
CLI 参数
dangerouslySkipPermissions
settings 默认权限
feature / policy gate
归一化 permission mode
后续工具执行看到的 mode
关键实现点：
default、plan、acceptEdits、bypassPermissions、dontAsk、auto服务不同交互场景。- 路径安全是硬边界，不应被宽松 allow 规则轻易覆盖。
- 自动模式也不是全放开，会剥离危险规则并使用分类器判断风险。
6.5 上下文管理与压缩
上下文来源
Prompt 类
规则 / 身份 / 工具原则
环境类
OS / cwd / Git
项目类
CLAUDE.md / 目录规则 / 记忆
历史交互
messages / tool results / summary
fetchSystemPromptParts()
query 前消息整形
裁切 / normalize / tool-result pairing
token budget 计算
本轮模型请求
自动压缩流程：
否
是
模型上下文窗口
预留 summary 输出空间
effective context window
减去 proactive buffer
auto compact threshold
当前 token 使用量
是否超过阈值?
生成 compact summary
重建 postCompactMessages
当前 query 继续运行
关键实现点：
- 上下文管理不是"保存全部历史"，而是持续选择本轮最有价值的信息。
- compact 不是删除历史，而是用摘要保留任务连续性。
- 完整压缩处理历史太厚，micro compact 处理局部大工具结果。
- auto compact 成功后可以在当前 query 内继续运行。
6.6 Prompt Cache
Prompt Cache 会反向塑造数据放置方式。
请求前缀结构
是
否
systemPrompt
userContext
systemContext
messages 整形
tool schema
Prompt Cache Key
稳定?
cache hit
低成本 / 低延迟
cache miss
重算 / 高成本
MCP instructions / 动态 agent / 高频 flag / 项目规则变化
关键实现点：
- 缓存对象不是单独一段 System Prompt，而是请求前缀结构。
CLAUDE.md放在userContext，避免破坏稳定 prompt。- MCP instructions、动态 agent 列表、运行时 flag 都需要控制波动。
- 某些状态会在会话内锁定，牺牲实时性换稳定性。
6.7 多 Agent 协作
多 Agent 的核心价值是上下文隔离，而不是简单并发。
委派探索
摘要
委派规划
计划
委派验证
结论
主 Agent
保留高层目标和决策
Explore Agent
探索代码库
Plan Agent
制定方案
Verification Agent
验证结果
独立上下文
独立上下文
独立上下文
Agent 来源合并：
built-in
plugin
user settings
project settings
flag settings
policy settings
getActiveAgentsFromList()
active agents
关键实现点：
AgentTool为局部任务创建子 Agent。- Team 模式包含 team file、task list、leader、session 绑定和 cleanup。
- teammate 有独立
agentId、taskId、AbortController和上下文。 - 多 Agent 把复杂任务拆成多个 loop，而不是让单 loop 变成复杂并发引擎。
6.8 MCP 集成
MCP 将 Claude Code 从固定工具集合扩展成平台。
MCP Server
MCP 配置
parseMcpConfig()
schema 校验 / env 展开
filterMcpServersByPolicy()
allowlist / denylist
连接 MCP server
tools
resources
instructions
commands
skills
getMcpToolsCommandsAndResources()
MCPTool 外壳
统一工具池
模型可见能力
MCP 同时引入新的信任边界。
MCP 接入
Prompt Cache 风险
instructions 波动
安全风险
远程工具 / 本地命令 server
认证风险
OAuth / token / headers
输出风险
大结果 / 图片 / 资源
关键实现点：
- 支持
stdio、sse、http、ws、sdk等连接类型。 - MCP tools 和 built-in tools 共用主执行池。
- MCP instructions 是高波动内容，会影响 Prompt Cache。
- MCP 配置、认证、动态 headers、policy 都属于安全治理面。
6.9 启动性能优化
启动优化不是"少 import"这么简单，而是关键路径治理。
进程启动
顶层并行预取
MDM / keychain / 凭据 / 远程配置
核心模块加载
重模块懒加载
实验能力 / 少用命令 / 高级模式
preAction 收敛等待
进入交互或执行
关键实现点：
- 顶层尽早发起慢 I/O，让它们与后续 import 并行。
preAction作为收敛点等待预取结果。- 懒加载降低启动成本，也缓解循环依赖。
- Feature Flag 在构建期裁剪不用分支，减少包体和模块求值。
- startup profiler 让启动路径可观测。
6.10 Feature Flag 体系
Feature Flag 同时影响产品发布、构建裁剪和模型可见能力。
否
是
是
否
构建时 flag
feature('KAIROS')
运行时 flag
GrowthBook / cached gate
用户类型 / entrypoint / SDK 场景
代码是否存在?
构建中裁掉
当前会话是否可用?
影响工具池 / agent 列表 / prompt / import / 执行分支
当前用户不可见
关键实现点：
- 构建时 flag 让不用功能不进入当前构建。
- 运行时 flag 支持灰度、实验和会话级行为。
- flag 会改变模型看到的工具、agent 和 prompt，不只是改变 UI。
CACHED_MAY_BE_STALE体现会话内稳定优先于绝对实时。
6.11 安全机制
安全是横切能力，不是单独模块。
用户输入 / 文件 / 网页 / MCP 结果 / 工具输出
Prompt 安全约束
识别 prompt injection / 高风险动作谨慎
权限模式与规则
default / plan / auto / ask / deny / allow
参数级检查
路径 / Bash / PowerShell / 重定向 / 管道
运行时隔离与集成安全
沙箱 / MCP policy / auth / headers / init 时序
工具执行
本机或外部系统
Bash 和 MCP 是两个高风险面。
安全风险面
BashTool
命令语义
破坏性动作
路径提取
管道与重定向
PowerShell 特例
沙箱
MCP
外部工具
远程服务
本地命令型 server
OAuth / token
dynamic headers
instructions 注入
文件系统
路径逃逸
.git hooks
.env
系统目录
Prompt Injection
网页内容
工具结果
MCP resources
关键实现点：
- Prompt 层提供第一层风险感知，但不能作为唯一防线。
- 权限、路径、工具级检查和沙箱共同组成纵深防御。
- MCP、headers、init env 这类辅助路径也需要安全视角。
- 默认路径保持保守，高风险操作需要显式授权或切换模式。
7. 模块关系总图
用户任务
01 System Prompt
02 Agent Loop
03 Tool System
04 Permission Model
05 Context Management
06 Prompt Cache
07 Multi-Agent
08 MCP Integration
09 Startup Optimization
10 Feature Flags
11 Security
最终输出
8. 关键设计原则
核心 loop 简单
复杂性放外围
模型负责决策
工程层负责边界
高波动信息隔离
安全分层防御
压缩保持连续性
扩展伴随信任治理
总结成四组取舍：
| 设计取舍 | 具体表现 |
|---|---|
| 核心简单，外围厚 | queryLoop() 保持直接，Prompt、工具、权限、上下文、缓存、安全在外围协作 |
| 模型决策，系统控权 | 模型选择工具和步骤，工程层通过 schema、权限、路径和沙箱约束行为 |
| 稳定优先，波动隔离 | 高波动信息从稳定 prompt 前缀迁出，保护 Prompt Cache |
| 可扩展但不裸奔 | MCP、多 Agent、Feature Flag 扩展能力，同时引入 policy、认证和安全治理 |
9. 结论
Claude Code 的架构本质不是"模型 + 工具列表"，而是一个完整的本地 Agent Runtime。
强模型能力
Claude Code 本地编排与治理系统
可持续的软件工程执行能力
规则塑形
能力暴露
权限控制
上下文治理
成本优化
平台扩展
安全纵深
它最值得学习的地方是：不是把模型放大权限后直接执行，而是通过一套本地编排层，把模型的规划能力、工具的执行能力和工程系统的约束能力组合起来。