Claude Code 源码架构解析

1. 系统架构总览

技术栈、目录结构、核心数据流

Core 技术栈

Category	Technology
Runtime	Bun
Language	TypeScript (strict)
Terminal UI	React + Ink
CLI Parsing	Commander.js
Schema Validation	Zod v4
Code Search	ripgrep
Protocol	MCP SDK, LSP
API	Anthropic SDK
State Management	Zustand (custom impl)

Structure 目录结构 (~1,900 文件)

src/
├── main.tsx              # CLI 入口 (~4,700行)
├── query.ts              # 主查询循环 (~1,729行)
├── QueryEngine.ts        # LLM 查询引擎 (~46K 行)
├── cloud.ts              # API 客户端 (~3,600行)
├── tools.ts              # 38+ 工具定义
├── Tool.ts               # 工具类型定义
├── commands.ts           # 100+ 命令
├── context.ts            # 上下文收集
├── commands/             # 斜杠命令实现
├── tools/                # 工具实现
├── components/           # Ink UI 组件 (~140 个)
├── services/
│   ├── api/              # Anthropic API 客户端
│   ├── mcp/              # MCP 协议集成
│   ├── lsp/              # LSP 协议集成
│   ├── compact/          # 上下文压缩
│   └── SessionMemory/    # 会话记忆
├── coordinator/          # 多智能体协调器
├── plugins/              # 插件系统
├── skills/               # 技能系统
└── memdir/               # 持久记忆系统

Flow 核心数据流

用户输入 → main.tsx → REPL.tsx → QueryEngine.submitMessage() │ ├── fetchSystemPromptParts() ├── buildEffectiveSystemPrompt() │ query() → queryLoop() │ ┌───────────────────────────────────────────┐ │ 消息准备 → API调用 → 工具执行 │ │ │ │ │ │ 后处理 → needsFollowUp? │ └───────────────────────────────────────────┘ │ 结果返回 → UI 渲染 │ extractMemories() + sessionMemory()

Init 启动流程

并行预取: MDM配置、Keychain OAuth、API预连接
初始化: 配置验证、CA证书、优雅关闭、事件日志、LSP服务器、遥测
功能特性加载: 20+ feature flags (PROACTIVE、KAIROS、COORDINATOR_MODE等)

PROACTIVE

KAIROS

COORDINATOR_MODE

FORK_SUBAGENT

TOKEN_BUDGET

2. 核心循环 - ReAct 模式

五阶段执行流程、7层恢复机制、消息准备管道

Core 五阶段执行流程

┌──────────────────────────────────────────────────────────┐ │ 第一阶段：上下文准备 │ - 裁剪旧消息 - 微压缩缓存结果 - 触发全量摘要 └──────────────────────────────────────────────────────────┘ ↓ ┌──────────────────────────────────────────────────────────┐ │ 第二阶段：模型流式调用 │ - 打包对话历史 + 系统提示 + 工具列表 │ - 流式输出：边生成边回传 │ - 实时收集：文本回复 + 工具调用意图 └──────────────────────────────────────────────────────────┘ ↓ ┌──────────────────────────────────────────────────────────┐ │ 第三阶段：工具执行 │ - 流式执行器：模型输出时就开始并行执行 │ - 批量执行器：所有调用确定后统一执行 │ - 权限检查 + Hook 钩子拦截 └──────────────────────────────────────────────────────────┘ ↓ ┌──────────────────────────────────────────────────────────┐ │ 第四阶段：附件收集 │ - 任务通知 - 记忆内容 - 文件变更记录 └──────────────────────────────────────────────────────────┘ ↓ ┌──────────────────────────────────────────────────────────┐ │ 第五阶段：终止或继续 │ - 无工具调用 → 任务完成 │ - 有工具调用 → 反馈结果，继续循环 │ - 413 错误 → 响应式压缩 + 重试 │ - 输出截断 → 自动升级 Token 上限 (8K→64K) └──────────────────────────────────────────────────────────┘

Resilience 7 层恢复机制

Layer	Mechanism	Description
1	API 级指数退避重试	网络抖动、API 过载
2	529 过载处理	Anthropic 专用错误码
3	输出 Token 恢复	截断后自动扩容
4	响应式压缩	上下文溢出时紧急压缩
5	上下文排空	分批处理过长上下文
6	模型 Fallback	降级到其他模型
7	无人值守持久重试	最大退避 5 分钟，6 小时重置

最大退避 5 分钟，重置上线 6 小时 — 真正考虑长时间运行场景的设计

Pipeline 消息准备管道

原始消息 │ ↓ applyToolResultBudget() (结果大小限制) │ ↓ snipCompact() (片段压缩) │ ↓ microCompact() (微压缩) │ ↓ contextCollapse() (上下文折叠) │ ↓ autoCompact() (自动压缩) │ ↓ normalizeMessagesForAPI() (API格式标准化)

Flow 7 个 Continue 站点

Site	Description
`collapse_drain_retry`	上下文折叠排空后重试
`reactive_compact_retry`	反应式压缩后重试
`max_output_tokens_escalate`	输出token升级后重试
`max_output_tokens_recovery`	输出token恢复后重试
`stop_hook_blocking`	Stop Hook阻塞后重试
`token_budget_continuation`	Token Budget续费后继续
`(normal)`	正常工具执行后下一轮

3. 工具系统

38+ 工具、分类执行模型、投机执行

Core 内置工具列表 (~38个)

Read Type (Parallel)

Read文件读取

Glob模式匹配

Grep内容搜索

WebFetchURL抓取

WebSearch网页搜索

LSP语言服务器

Write Type (Serial)

Write文件写入

Edit文件编辑

BashShell命令

Special

Agent子智能体

TaskCreate任务创建

AskUserQuestion提问

EnterPlanMode规划模式

SendMessage智能体消息

Skill技能执行

ToolSearch工具搜索

Model 工具分类执行模型

读取型工具 (Read, Grep, Glob) → 并行执行, 最多 10 并发写入型工具 (Edit, Write, Bash) → 串行执行, 一次一个 // 状态流转 'queued' → 'executing' → 'completed' → 'yielded'

Advanced 投机执行机制 (Speculative Execution)

用户确认当前操作 ──────────────────→ 执行 ↑ │ 流水线化 │ 确认前就开始预执行 (Copy-on-Write Overlay 文件系统)

写操作先写入临时覆盖层
确认后复制回真实文件系统
拒绝后直接删除覆盖层
在确认当前建议时，下一条已经开始预执行

像 CPU 指令流水线一样，极大隐藏等待延迟

Design 工具 Prompt 设计模式

每个工具都有完整的描述 Prompt，包含:

描述: 工具用途
使用限制: 何时使用/何时避免使用
参数说明: 各参数含义
示例: 最佳实践

4. 上下文压缩与记忆

上下文压缩、五层记忆体系

Context 四级上下文压缩体系

Level	Name	Trigger	Strategy
1	Snip	每轮调用前	轻量裁剪旧消息头尾
2	Micro Compact	Token 占用高	缓存感知 / 基于时间 / API级压缩
3	Auto Compact	超过阈值	AI 全量摘要，浓缩成结构化摘要
4	Reactive Compact	413 错误	紧急压缩 + 重试

const AUTOCOMPACT_BUFFER_TOKENS = 13,000
const WARNING_THRESHOLD_BUFFER_TOKENS = 20,000
const MAX_CONSECUTIVE_AUTOCOMPACT_FAILURES = 3  // 熔断器

压缩后不是暴力丢弃，而是智能恢复优先级（最近读取文件 > plan 文件 > 已调用技能）

Memory 五层记忆体系

┌─────────────────────────────────────────────────────────┐ │ 短期记忆：当前会话消息列表 (内存) │ ├─────────────────────────────────────────────────────────┤ │ 工作记忆：7种任务状态 + 投机执行状态 + 技能跟踪 │ ├─────────────────────────────────────────────────────────┤ │ 长期记忆：三层架构 │ │ ┌─────────────────────────────────────────────────┐ │ │ │ memory.md (索引文件) │ │ │ │ ├── user 类型 (用户角色偏好) │ │ │ │ ├── feedback 类型 (用户纠正反馈) │ │ │ │ ├── project 类型 (进行中工作约束) │ │ │ │ └── reference 类型 (外部系统引用) │ │ │ └─────────────────────────────────────────────────┘ │ ├─────────────────────────────────────────────────────────┤ │ 摘要记忆：四级压缩体系 │ ├─────────────────────────────────────────────────────────┤ │ Checkpoint：会话持久化和恢复 │ └─────────────────────────────────────────────────────────┘

Types 四种记忆类型

Type	Description	Content
user	用户角色、目标、偏好	角色、偏好、协作方式
feedback	用户反馈指导	规则偏好、避免重复的错误
project	项目状态、目标	谁在做什么、为什么、截止时间
reference	外部系统指针	URL、位置、如何找到信息

// 记忆文件结构
---
name: {{memory name}}
description: {{one-line description}}
type: {{user, feedback, project, reference}}
---

{{memory content}}

5. 多智能体系统

内置智能体类型、三种执行模型、Coordinator 模式

Core 内置智能体类型

general-purpose (通用)

Complete the task fully—don't gold-plate, but don't leave it half-done.

Tools全部可用

Modelinherit

Explore (代码探索)

=== CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS ===

Tools只读 (禁用 Agent, Edit, Write)

Model外部→Haiku, 内部→inherit

Plan (架构规划)

=== CRITICAL: READ-ONLY MODE ===

Tools只读

Output结尾包含 ### Critical Files

verification (验证)

Your job is not to confirm the implementation works—it's to try to break it.

Tools只读

Goal对抗性验证

Model 三种执行模型

Model	Description
Fork Agent	子 agent 继承父 agent 完整上下文，独立分支执行
In-process Teammate	同进程内异步执行，用 async local storage 隔离
Split-pane Teammate	在 tmux/iTerm2 里开分窗格

Advanced Coordinator 模式

Coordinator 角色: 指导 workers 进行 research/implement/verify

Agent tool: 生成异步 workers
SendMessage tool: 继续现有 workers
TaskStop tool: 取消 workers
Worker 结果: 以 <task-notification> XML 到达

工作流: Research → Synthesis → Implementation → Verification

Implementation Fork 子智能体实现

// Fork 继承父智能体完整上下文，共享 prompt cache
// 构建方式:
// 1. 复制父消息历史
// 2. 用字节相同的占位文本替换 tool_result (保持缓存键一致)

// 3. 添加 per-child 指令文本块

// 优势: 极低成本 (缓存命中率极高)
// 限制: 不能指定不同的模型

6. 安全纵深防御

权限决策管道、20项安全检查、Hook 系统

Core 权限决策管道

工具调用请求 ↓ Step 1: 规则检查 (hasPermissionsToUseToolInner) ↓ Step 2: 模式转换 (dontAsk/auto/plan) ↓ Step 3: 分类器 (如果需要) ├── 安全允许列表 → 跳过分类器 └── 两阶段 XML 分类器: ├── Stage 1 (fast): max_tokens=64, instant yes/no └── Stage 2 (thinking): max_tokens=4096, chain-of-thought ↓ Step 4: 交互处理 (如果 behavior === 'ask')

Bash Bash Tool 20 项安全检查

Category	Checks
命令完整性	不完整命令检测
注入攻击	JQ 函数注入
	IFS 注入
	Token 注入
	Unicode 伪装
危险字符	SH 元字符嵌入
	换行攻击
	命令替换模式
解释器黑名单	Python、Node、Ruby、Perl、PHP 默认禁止自动执行

Extensible Hook 系统 (24 种事件)

Event	Timing	Usage
PreToolUse	工具执行前	修改输入、阻止执行
PostToolUse	工具执行后	修改输出
PostToolUseFailure	工具错误后	错误处理
PreCompact	压缩前	准备压缩
PostCompact	压缩后	后处理
SessionStart/End	会话开始/结束	初始化/清理
Stop	模型停止时	停止钩子

企业用户可以在不修改源码的情况下深度定制行为

Architecture 三层防御架构

输入验证 → 8来源权限规则匹配 → 二阶段分类器 ↓ 文件系统边界锁定 → 路径遍历保护 → 危险文件保护列表 ↓ Shell 安全检查 → 解释器黑名单 → Docker 沙箱隔离

不信任任何东西，层层验证 — 这是被真实安全事件教训后才有的设计

7. Prompt 系统

组装结构、优先级体系、缓存优化

Core Prompt 组装结构

return [
  // 静态内容 (可跨用户/组织缓存)
  getSimpleIntroSection(),           // 身份与安全指令
  getSimpleSystemSection(),          // 系统规则
  getSimpleDoingTasksSection(),      // 任务执行指南
  getActionsSection(),               // 安全操作指南
  getUsingYourToolsSection(),        // 工具使用指南
  getSimpleToneAndStyleSection(),    // 语气风格
  getOutputEfficiencySection(),      // 输出效率

  SYSTEM_PROMPT_DYNAMIC_BOUNDARY,    // 缓存分界线

  // 动态内容 (每个会话/用户不同)
  getSessionSpecificGuidanceSection(),
  loadMemoryPrompt(),
  getAntModelOverrideSection(),
  computeSimpleEnvInfo(),
  getLanguageSection(),
  getOutputStyleSection(),
  getMcpInstructionsSection(),
  getScratchpadInstructions(),
  getFunctionResultClearingSection(),
  SUMMARIZE_TOOL_RESULTS_SECTION,
]

System Prompt 优先级 (6 级)

override > cornnet > agent > custom > 默认 > append

Priority	Type
1 (Highest)	Override system prompt
2	Coordinator system prompt
3	Agent system prompt
4	Custom system prompt (--system-prompt)
5	Default system prompt
6 (Lowest)	Append

Optimization 缓存优化策略

┌──────────────────────────────────────┬───────────────────────────────┐ │ 静态部分 (可缓存) │ 动态部分 (每次不同) │ ├──────────────────────────────────────┼───────────────────────────────┤ │ - 身份声明 │ - 记忆内容 │ │ - 工具使用指南 │ - MCP 指令 │ │ - 编码哲学 │ - 环境信息 │ ├──────────────────────────────────────┴───────────────────────────────┤ │ ↑ DYNAMIC_BOUNDARY 标记 │ └──────────────────────────────────────────────────────────────────────┘

Anthropic API 有提示缓存机制，缓存命中可大幅降低成本。精确切割静态/动态内容，最大化缓存命中率

8. 自修复机制

反馈循环、四层错误恢复、重试机制

Core 核心原理

Claude 生成 tool_use ↓ 工具执行 (成功或失败) ↓ tool_result 返回 (含 is_error 标志) ↓ Claude 在下一轮看到错误信息 ↓ 分析原因 → 尝试新策略 ↓ 再次调用工具 → 循环继续

Design 关键设计：is_error 标志

错误和成功使用完全相同的消息格式，唯一区别是 is_error: true

// 成功
{ type:'tool_result', tool_use_id:'call_abc', content:'...', is_error:false }

// 失败
{ type:'tool_result', tool_use_id:'call_abc', content:'Error: File not found', is_error:true }

Strategy 四层错误恢复策略

Layer	Error Type	Recovery Strategy
1	PTL (Prompt Too Long)	上下文折叠 → 反应式压缩 → 用户报告
2	输出 Token 超限	升级到 64K → 恢复消息 → 最多3次
3	模型过载 (529)	切换 fallbackModel → 重试
4	工具执行错误	错误反馈 → Claude 分析 → 调整策略

Implementation 重试机制 (withRetry)

// 错误处理
401/403 → 刷新凭证 → 重试
429     → 短延迟用fast mode, 长延迟切换速度
529     → 指数退避, 连续3次触发模型回退
PTL     → 计算可用token → 调整maxTokens → 重试
ECONNRESET → 禁用keep-alive → 重试

9. 扩展子系统

MCP、LSP、Skill 系统

Protocol MCP (Model Context Protocol)

// MCP 服务器作用域
local:      .mcp.json (项目目录)
user:       ~/.claude/.mcp.json
project:    .claude/.mcp.json
dynamic:    运行时添加
enterprise: 策略强制

// 连接流程
1. 服务器发现 → 连接尝试
2. 需要认证 → OAuth 流程
3. 工具/命令/资源获取
4. 权限提示通过 channel 发送
5. 重连: 指数退避, 最多5次

Protocol LSP (Language Server Protocol)

LSPServerManager: 按文件扩展名路由到 LSP 服务器
LSPServerInstance: 单个服务器生命周期
LSPClient: vscode-jsonrpc 协议通信

// 关键特性
MAX_DIAGNOSTICS_PER_FILE = 10
MAX_TOTAL_DIAGNOSTICS = 30
LRU 去重缓存 (MAX_DELIVERED_FILES = 500)

Skills Skill 系统

// 来源
1. 内置技能: src/skills/bundled/ (remember, verify, debug, stuck...)
2. 用户技能: ~/.claude/skills/*.md
3. 项目技能: .claude/skills/*.md
4. MCP 技能: 通过 MCP 服务器提供

// 格式
---
name: skill-name
description: ...
whenToUse: ...
allowedTools: [...]
model: inherit/haiku/sonnet/opus
hooks: { ... }
---
[技能提示词内容]

10. 斜杠命令

命令分类、100+ 内置命令

Types 命令分类

Type	Description
prompt	AI 驱动，展开为提示文本
local-jsx	Ink UI 组件
local	同步本地操作

Commands 主要命令列表

Git 与版本控制

/commit创建 git 提交

/review审查 PR

/diff查看未提交的更改

/branch创建对话分支

对话管理

/resume恢复之前的对话

/clear清除对话历史

/compact压缩对话

/rewind回退到之前的点

上下文与配置

/context可视化上下文使用情况

/memory编辑记忆文件

/config打开配置面板

/plan启用/查看规划模式

模型与推理

/model设置 AI 模型

/effort设置 effort level

/fast切换 fast mode

工具与扩展

/tasks管理后台任务

/skills列出可用技能

/agents管理智能体配置

/mcp管理 MCP 服务器

11. 核心设计原则

构建 Agent 的关键要点

Principles 构建 Agent 的关键要点

Aspect	Recommendation
工具设计	每个工具提供完整描述 Prompt，包含使用限制
错误处理	成功/失败使用相同格式，仅用 is_error 区分
反馈循环	工具结果必须反馈给模型让其调整策略
上下文管理	实现自动压缩防止上下文溢出
记忆系统	分离四种记忆类型，定期提取和更新
权限控制	实现多层权限检查和确认机制
自愈能力	诊断原因再行动，而非盲目重试
智能体分工	不同任务使用不同类型的专业智能体
验证机制	验证智能体应该试图破坏，而非确认工作
提示词组织	静态/动态分离，支持缓存优化

Summary 自修复机制总结 (10 点)

反馈循环 (最核心) - 工具执行结果都作为 tool_result 返回
精心设计的 System Prompt - "诊断原因再行动"而非"盲目重试"
四层错误恢复 - PTL恢复 → 输出超限恢复 → 模型过载回退 → 工具错误自然恢复
防错设计 - EditTool 的"必须先读取"、"唯一性检查"
错误记忆保持 - Compact 显式保留 "Errors and fixes" 段
对抗性验证 - Verification Agent 专门设计为"试图破坏实现"
多智能体分工 - Explore → Plan → Implementation → Verification
权限安全网 - 分类器 + 沙箱 + Hook 系统
上下文管理 - 自动压缩 + 微压缩 + 上下文折叠
Prompt Cache 优化 - 静态/动态分界线 + Fork 共享缓存

Claude Code Architecture