全景导图

%%{init: {'theme':'base', 'themeVariables': {'primaryColor':'#e3f2fd','primaryTextColor':'#1565c0','primaryBorderColor':'#1976d2','lineColor':'#42a5f5','secondaryColor':'#fff3e0','tertiaryColor':'#f3e5f5','fontSize':'14px'}}}%%
flowchart TD
    A[Entrypoints 入口层] --> B[Runtime 运行时层]
    B --> C[Engine 推理引擎层]
    C --> D[Tools & Caps 能力层]
    D --> E[Infrastructure 基础设施层]
    
    C --> C1[QueryEngine 单例]
    C --> C2[AsyncGenerator 循环]
    C --> C3[静态/动态提示词分界]
    C --> C4[四级上下文压缩]
    
    D --> D1[40+ 内置工具]
    D --> D2[多智能体编排]
    D --> D3[MCP 集成]
    D --> D4[记忆系统]
    
    E --> E1[Auth / Storage]
    E --> E2[Cache / Analytics]
    E --> E3[Bridge 传输抽象]

模式总览

本文覆盖的可迁移架构模式：

# 模式名称 一句话口诀 覆盖场景
1 Harness 护城河 模型提供智力，Harness 提供能力边界 AI 编程工具架构设计
2 生成器驱动 AsyncGenerator 替代状态机 Agent 控制流设计
3 上下文预算 静态/动态分界 + 四级压缩 LLM 上下文窗口管理
4 多智能体编排 文件系统 Team + 异步 Mailbox 多 Agent 协调通信
5 工具即能力 注册-校验-执行-聚合流水线 Agentic AI 安全模型
6 缓存继承 model: inherit 共享提示词缓存 子智能体性能优化

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

2026 年 3 月 31 日，Claude Code 的完整 TypeScript 源码通过 npm source map 意外暴露，共计 约 1,900 个文件、512,000 行代码。社区技术团队 redreamality 通读了全部目录，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 框架的最优控制流设计。

提示词工程架构：静态/动态分界与缓存优化

Claude Code 最具工程价值的设计之一，是将系统提示词拆分为静态部分和动态部分，并围绕 Anthropic API 的 prompt caching 机制构建了完整的缓存优化策略。

静态提示词：可缓存的跨用户共享内容

源码中的 getSystemPrompt() 函数（位于 src/constants/prompts.ts）返回的不是单一字符串，而是一个字符串数组，由多个 section 拼装而成。其中静态部分包括：

Section 函数 内容
getSimpleIntroSection() 身份定义：Claude Code 作为交互式代理的基本身份
getSimpleSystemSection() 系统规则：输出格式、工具调用被拒绝后的处理、prompt injection 防护
getActionsSection() 任务执行规范：不要过度设计、读文件后再改代码、避免安全漏洞
getUsingYourToolsSection() 工具使用规范
getSimpleToneAndStyleSection() 语气与风格
getOutputEfficiencySection() 输出效率控制

这些 section 使用 scope: 'global' 级别的缓存，跨所有用户共享。

动态提示词：会话特定的实时生成内容

在静态部分之后，源码通过一个关键标记 SYSTEM_PROMPT_DYNAMIC_BOUNDARY 明确划定静态/动态分界线。边界之后的内容在每次查询时实时生成：

1
2
3
4
5
6
7
8
9
const dynamicSections = [
  systemPromptSection('session_guidance', ...),
  systemPromptSection('memory', ...),
  systemPromptSection('env_info_simple', ...),
  systemPromptSection('language', ...),
  systemPromptSection('output_style', ...),
  DANGEROUS_uncachedSystemPromptSection('mcp_instructions', ...),
  systemPromptSection('scratchpad', ...),
]

注意 DANGEROUS_uncachedSystemPromptSection() 这个函数名——它直接在命名中警告开发者：这个 section 会破坏缓存。MCP 指令因为每个用户配置不同，无法被缓存，所以被显式标记为"危险"。

五级覆盖优先级

buildEffectiveSystemPrompt() 函数支持五级覆盖机制，优先级从高到低：

优先级 来源 场景
0 Override system prompt 调试/测试时的完全覆盖
1 Coordinator system prompt 多智能体协调器的专用提示词
2 Agent system prompt 特定智能体（如 explore、plan）的提示词
3 Custom system prompt 用户自定义提示词
4 Default system prompt 默认系统提示词

此外，appendSystemPrompt 始终追加在末尾，不受优先级影响。

CLAUDE.md 的加载时机

CLAUDE.md 文件作为 userContext 注入，关键设计决策是：每次查询时重新读取，而非启动时一次性加载。这意味着用户在会话中修改 CLAUDE.md 后，下一次查询立即生效。当读取特定目录的文件时，还会自动加载该目录下的 CLAUDE.md——这就是 Claude Code 感觉"项目感知"的机制。

两层缓存架构

围绕静态/动态分界，Claude Code 构建了两层缓存：

缓存层级 范围 内容
Global Cache 跨用户共享 SYSTEM_PROMPT_DYNAMIC_BOUNDARY 之前的所有静态 section
Session Cache 会话级 动态 section + 对话历史

工程上的关键约束：提示词的排列顺序至关重要。Anthropic API 的 prompt caching 是前缀匹配的——任何在前缀中发生的细微改变，都会导致该位置之后的所有缓存失效。因此 Claude Code 严格遵循"静态内容在前，动态内容在后"的原则。

有用户实测到 13:1 的缓存命中率，这意味着每 13 个 token 的处理中只有 1 个需要重新计算。

子智能体的缓存继承

model: 'inherit' 的核心价值在于：Fork 出的子智能体继承父智能体的完整对话上下文，通过 byte-identical copies 实现提示词缓存共享。子任务必须使用和父对话相同的 prompt prefix，才能复用父对话的缓存。这使得生成 5 个并发子智能体的成本仅略高于 1 个。

[PATTERN] 上下文预算模式：LLM 应用的上下文窗口是稀缺资源，必须像管理内存一样管理它。静态/动态分界 + 两层缓存 + 四级压缩是 Claude Code 的核心工程策略。SYSTEM_PROMPT_DYNAMIC_BOUNDARY 这个标记本身就是一个值得借鉴的设计模式——用命名约定而非文档来传达架构约束。

上下文压缩：四级受控降级

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

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

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

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

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

智能体分类

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' 是缓存优化的关键。

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

源码中的工具列表读起来像一个小型 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 的能力上限。

记忆系统：跨会话持久化

源码暴露了跨会话记忆机制，实现了三级记忆：

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

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

源码中还发现了代号 KAIROS 的模块——这是一个未发布的全自主代理守护进程模式（always-on agent mode）。源码注释将其描述为 Start Claude in assistant mode (custom system prompt, brief responses, persistent)。与普通会话模式不同，KAIROS 具备主动心跳引擎、睡眠机制和追加式记忆系统，能够以 24/7 守护进程的方式运行，主动监控代码库变化并在需要时介入——类似《钢铁侠》中贾维斯的角色。这代表了 Claude Code 从"被动响应"向"主动协作"演进的实验性方向。

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

BUDDY：虚拟宠物系统

BUDDY 模块是 Claude Code v2.1.89 正式发布的终端虚拟宠物系统。用户在终端输入 /buddy 命令即可孵化一个 ASCII 像素宠物，系统基于用户 ID 的 hash 确定性分配 18 种物种（龙、海星、乌龟等），每种拥有稀有度分级（Common 到 Legendary）、属性系统（SNARK、WISDOM 等 stats）和装饰系统（帽子等）。宠物会根据任务执行进度表现出不同的情绪状态动画。

训练数据投毒防护

源码显示 Claude Code 在工具定义中注入了虚假的工具签名和参数描述——由 ANTI_DISTILLATION_CC 标志控制。当该标志激活时，虚假工具定义会被注入到系统提示词中。目的是污染从公开代码库中爬取用于训练的数据：如果竞争对手录制 Claude Code 的 API 流量来蒸馏训练自己的模型，这些虚假工具会 contaminant 其训练集。

实践启示

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

  • 静态/动态提示词分界：用 SYSTEM_PROMPT_DYNAMIC_BOUNDARY 式的标记明确划分可缓存和不可缓存的内容，最大化 prompt cache 命中率
  • 采用 AsyncGenerator 模式：替代状态机，获得原生流式、中断和预算控制
  • 五级覆盖优先级：让不同来源的上下文可组合、可覆盖，而非简单拼接
  • 四级压缩流水线：优雅降级而非粗暴截断
  • 文件系统的 Team 协调：轻量、持久、可调试的多智能体通信
  • model: 'inherit' 缓存优化：子智能体通过 byte-identical copies 共享父智能体提示词缓存

参考资料