源码概览：1,884 个文件的技术版图

2026 年 3 月 31 日，Claude Code 的完整 TypeScript 源码通过 npm source map 意外暴露，共计 1,884 个文件、512,000 行代码。社区技术团队 redreamality 通读了全部 150+ 个目录，ThreeFish-AI 完成了系统性逆向工程，多篇深度分析文章从不同维度拆解了这套架构。

源码揭示的核心事实：Claude Code 不是带工具访问的聊天机器人，而是一个完整的 AI 辅助软件开发操作系统——包含多智能体运行时、插件市场、跨会话记忆系统和安全模型。

[PATTERN] Harness 护城河模式：AI 编程工具的真正壁垒不在模型能力，而在 Harness（智能体编排层）。模型提供智力，Harness 提供能力边界、上下文管理和执行环境。

五层架构：从入口点到基础设施

源码显示 Claude Code 采用清晰的五层分层设计：

层级 职责 关键组件
Layer 1: Entrypoints 多端入口 CLI / Desktop / Web / SDK / IDE Extensions
Layer 2: Runtime 运行时核心 REPL loop / Query executor / Hook system / State manager
Layer 3: Engine 推理引擎 QueryEngine / Context coordinator / Model manager / Compact
Layer 4: Tools & Caps 能力层 100+ tools / Plugin / MCP / Skill / Agent / Command
Layer 5: Infrastructure 基础设施 Auth / Storage / Cache / Analytics / Bridge transport

这种架构的哲学是：Claude Code 是一个平台运行时，恰好附带了一个终端界面。同一个核心引擎驱动桌面应用、Web 客户端、IDE 扩展和程序化 SDK。Bridge 层抽象了传输协议，引擎永远不需要知道是哪个前端在驱动它。

架构上更接近 VS Code 的扩展宿主或 Emacs 的 Lisp 核心，而非典型的 AI 包装器。

核心引擎：QueryEngine 与 AsyncGenerator 循环

QueryEngine 单例

整个对话由一个 QueryEngine 单例驱动，它拥有一个 mutableMessages 数组——这是所有对话状态的唯一事实来源。

AsyncGenerator 核心循环

核心循环是一个异步生成器（async generator）：

1
2
3
4
5
6
7
8
9
10
用户消息
→ 构建系统提示词（分层上下文注入）
→ API 请求（流式）
→ yield tokens 到 UI
→ 如果收到 tool_use 块：
  → 检查权限（hook → policy → 用户审批）
  → 执行工具
  → 追加 tool_result
  → 继续循环（自然尾递归）
→ 如果 end_turn：退出

生成器模式带来的三个关键优势：

  • 原生流式：token 通过 yield 流动，而非回调
  • 工具调用递归：tool_use → tool_result → continue 只是另一次迭代
  • 干净的中断：AbortController 取消生成器，无需复杂的清理逻辑
  • 预算控制简单：在每次迭代边界检查 maxTurns 或 maxBudget

大多数 AI 工具框架使用状态机或事件循环。Claude Code 的生成器方法更简单、更可组合。

[PATTERN] 生成器驱动模式：用 async generator 替代状态机/事件循环，天然支持流式、中断、递归和预算控制。这是 Agent 框架的最优控制流设计。

上下文系统：六层注入与四级压缩

六层系统提示词组装

系统提示词不是静态字符串，而是在每次查询时从六层动态组装：

层级 来源 用途
1 defaultSystemPrompt 基础行为指令
2 memoryMechanics 记忆系统指令
3 appendPrompt 额外提示片段
4 userContext CLAUDE.md 文件（用户级 + 项目级）
5 systemContext Git 状态、环境变量、动态状态
6 workerToolsContext Coordinator 模式的工具描述

这种分层注入意味着不同上下文可以相互覆盖或扩展而不冲突。项目级的 CLAUDE.md 文件可以自定义行为而无需触碰核心提示词。这就是 Claude Code 感觉"项目感知"的机制——它在每次查询时字面意义上读取你仓库的指令。

四级上下文压缩

上下文窗口是有限的。Claude Code 通过四级压缩系统处理：

层级 机制 触发时机
1 autoCompact 上下文接近限制
2 apiMicrocompact API 原生的 context_management
3 reactiveCompact API 返回 context-too-large 错误后
4 snip 紧急：丢弃非关键内容

compact() 函数剥离图片、调用压缩 API 摘要对话，然后恢复文件引用和技能状态。压缩后，preservedSegment 边界允许选择性恢复。

这比"截断旧消息"复杂得多——这是一个受控降级流水线。

[PATTERN] 上下文预算模式：LLM 应用的上下文窗口是稀缺资源，必须像管理内存一样管理它。分层注入 + 四级压缩是唯一可持续的策略。

多智能体架构：三种隔离级别与七种任务类型

智能体分类

Claude Code 不仅生成子智能体，它有完整的智能体类型分类：

类型 来源 示例
BuiltInAgent 硬编码 explore, plan, verify, general-purpose
CustomAgent 设置文件 用户或项目级 .claude/agents/*.md
PluginAgent 插件包 市场分发的智能体

七种任务类型

任务类型 隔离级别 用途
InProcessTeammate AsyncLocalStorage 同进程，共享终端
LocalAgentTask 异步后台 非阻塞子智能体
RemoteAgentTask 远程 CCR 云端执行
LocalShellTask 子进程 Shell 命令
DreamTask 后台 记忆整合
LocalWorkflowTask 后台 工作流脚本
MonitorMcpTask 后台 MCP 服务器监控

Team 协调模型

多个智能体通过基于文件的 Team 系统协调：

1
2
3
~/.claude/teams/{team-name}/config.json
├── members: [{ agentId: "researcher@my-team", status: "idle" }]
└── task list: ~/.claude/tasks/{team-name}/

通信通过 Mailboxes 异步进行——每个队友有独立的消息队列。协议支持结构化消息：shutdown_request、plan_approval_response、权限冒泡。

关键设计决策：

  • model: 'inherit' 确保子智能体共享父智能体的提示词缓存——字节级对齐缓存命中
  • TEAMMATE_MESSAGES_UI_CAP = 50 防止内存泄漏（他们在添加此限制前 292 个智能体达到了 36.8GB）
  • 只读智能体（Explore、Plan）上的 omitClaudeMd 每周在整个集群中节省约 5-15 GTok
  • AsyncLocalStorage 提供隐式上下文隔离，无需显式参数传递

[PATTERN] 多智能体编排模式：Agent 不是单打独斗，而是通过文件系统的 Team 配置 + 异步 Mailbox 消息队列协调。model: 'inherit' 是缓存优化的关键。

工具系统：30+ 内置工具与安全模型

源码中的工具列表读起来像一个小型 IDE：

  • 文件操作：BashTool, FileReadTool, FileEditTool, FileWriteTool, GlobTool, GrepTool
  • 网络能力：WebFetchTool, WebSearchTool
  • 笔记本支持：NotebookEditTool
  • 智能体调度：AgentTool, SendMessageTool, TaskCreate/Get/List/Update
  • 团队协作：TeamCreate/Delete
  • MCP 集成：通过标准协议接入外部服务

工具系统的设计原则：Agent 能做什么，完全由它拥有的工具集决定。系统中没有任何"后门"让模型绕过工具系统直接执行操作。

权限检查流水线

每个工具调用经过三层权限检查：

1
Hook → Policy → User Approval
  • Hook 层：项目级钩子脚本，可自定义验证逻辑
  • Policy 层：内置策略引擎，基于路径、命令模式、危险程度评估
  • User Approval：最终用户确认，fail-closed 默认值

[PATTERN] 工具即能力边界模式：Agentic AI 的能力不取决于模型智能，而取决于工具集的设计。注册-校验-执行-聚合的流水线决定了 Agent 的能力上限。

记忆系统：跨会话持久化

源码暴露了 KAIROS 模块，实现了三级记忆：

记忆类型 存储位置 用途
短期记忆 会话内 mutableMessages 当前对话上下文
中期记忆 ~/.claude/memory/ 用户偏好、常用命令模式
长期记忆 DreamTask 后台整合 跨项目经验积累

记忆系统让 Agent 在后续会话中自动加载历史偏好，表现出"越来越懂你"的行为。

隐藏功能：源码中的实验性模块

BUDDY：AI 宠物系统

BUDDY 模块在 Agent 执行长时间任务时，在终端中显示 ASCII 动画宠物，根据任务进度表现不同情绪状态。

训练数据投毒防护

源码显示 Claude Code 在工具定义中注入了虚假的工具签名和参数描述，目的是污染从公开代码库中爬取用于训练的数据。

社区深度分析文章汇总

以下是对 Claude Code 源码进行深度技术分析的代表性文章：

来源 标题 核心贡献
redreamality.com Claude Code Leak: A Deep Dive into Architecture 五层架构全景、QueryEngine 单例、AsyncGenerator 循环、四级压缩
Medium - han.heloir Nobody Analyzed Its Architecture Harness 护城河理论、60+ 工具中仅 40 个每次加载
知乎 - 深度解读 我用 Claude Code 深度解读 51 万行源码 Agent Loop ReAct 循环、System Prompt 流程化算法
51CTO 从 Harness 角度对 Claude Code 源码深度解读 单循环+Harness 架构、智能体编排框架
极客时间 Harness 架构深度解析 智能体编排框架、工具/上下文管理/执行环境
dev.to - ishaaan Every System Explained 完整系统逐一解读
ThreeFish-AI 逆向工程研究仓库 50,000+ 行混淆代码分析结果
腾讯云 Claude Code 源码分析笔记 v2.1.2 版本复杂架构设计

实践启示

对于构建 Agentic AI 系统的开发者：

  • 采用 AsyncGenerator 模式：替代状态机，获得原生流式、中断和预算控制
  • 分层上下文注入：让不同来源的上下文可组合、可覆盖
  • 四级压缩流水线：优雅降级而非粗暴截断
  • 文件系统的 Team 协调：轻量、持久、可调试的多智能体通信
  • model: 'inherit' 缓存优化：子智能体共享父智能体提示词缓存

参考资料