Claude Code 核心架构深度解析

每一代开发者工具都由一个核心的架构决策所定义。Unix 赌的是由管道连接的小型可组合程序将超越单体系统；Git 赌的是分布式版本控制将超越中心化服务器；Docker 赌的是文件系统隔离将超越虚拟机。这些决策对用户来说往往是不可见的，但却决定了哪些工具能生存下来，哪些会沦为历史的注脚。

Claude Code 的架构决策现在已经清晰可见。通过从公开 npm 包的 sourcemap 文件中恢复的源代码，揭示了分布在 1,332 个文件中的 512,664 行 TypeScript 代码。它展示了一个关于软件开发未来的论点，这个论点是通过工程决策而非营销口号来表达的。

这个论点是：AI 辅助编程的难题不在于生成质量，而在于执行的可靠性。语言模型是引擎，而围绕它的所有东西——12 层治理架构（harness layers）、40 多个工具、一个完整的 Bash AST 解析器、三个尚未发布的自主功能——都是为了让这个引擎变得安全、持久并最终实现自主。Claude Code 正在构建第一代能够无人值守编写软件的系统，其架构揭示了实现这一目标所需的条件。

12 层治理架构 (12-Harness Architecture)

Claude Code 的核心是 query.ts 中的一个 while(true) 循环。生成器函数在每次 API 调用后交出控制权，检查响应，决定是继续还是停止，然后再次循环。除此之外，其余部分都是治理架构。该架构并非单一的创新，而是由 12 种机制组成的集合，每种机制处理不同的失败模式。

这个演进过程讲述了一个故事：

• 第 1-3 层解决了可靠调用 API 的基础问题：流式传输、重试、错误处理。
• 第 4-6 层解决了工具问题：组装正确的上下文、注册工具以及安全地解析命令。
• 第 7-9 层解决了信任问题：执行沙箱化、权限分类、以及当对话过长时压缩上下文。
• 第 10-12 层解决了自主性问题：跨会话记忆、主动采取行动、以及协调多个 Agent 完成单一任务。

大多数竞争对手的 Agent 止步于第 6 层。它们可以调用工具和执行命令，但 Claude Code 的独特之处在于堆栈的上半部分——处理当会话运行数小时、用户不在场、或多个 Agent 需要共享状态时发生的情况。这些是为完全不同类别的产品准备的基础设施。

工具系统 (Tool System)

Claude Code 附带了 40 多个工具，通过 buildTool() 工厂模式注册。每个工具声明都指定了名称、描述、输入 Schema、权限要求和执行函数。这种模式非常一致，添加一个新工具大约只需要 30 行代码。这是刻意为之的：系统被设计为可扩展的。

其中 Bash 工具最能说明问题。Claude Code 并没有使用正则表达式来判断 Shell 命令是否安全，而是包含了一个跨越 2,679 行 TypeScript 代码的完整 Bash AST 解析器。它将 Shell 命令词法分析并解析为抽象语法树，然后遍历该树以提取每个可执行文件、标志、管道目标和重定向。这就是“模式匹配”与“真正理解”之间的区别。

构建在此解析器之上的权限系统使用 ML 分类器（对 Claude 本身的侧向查询）将命令分为允许、拒绝或询问用户三个层级。这不是一个静态的白名单。模型会在上下文中评估每个命令，考虑当前工作目录、用户最近的指令以及工具声明的风险级别。

工具注册表还揭示了一种不同于行业常规的知识注入策略。大多数 Agent 将知识塞进系统提示词（System Prompt）中。而 Claude Code 通过 tool_result 消息注入知识——这些合成响应被放置在对话中，就好像工具返回了它们一样。这保持了系统提示词的精简，并将知识精确地放置在模型最关注的地方：最近的上下文窗口中，并格式化为工具输出。这是一个微小的架构选择，但对可靠性有着巨大的下游影响。

揭示未来的三个未发布功能

源代码包含 108 个内部模块，这些代码被员工检查或编译时功能开关（Feature Flags）所保护。其中三个功能揭示了 Anthropic 认为的编程 Agent 的发展方向。

KAIROS：全天候运行的 Agent

KAIROS 是一个自主 Agent 守护进程。它不等待用户输入消息，而是基于心跳机制运行，定期唤醒以检查事件：新的 Pull Request、CI 失败、代码审查评论、依赖更新。当它发现可操作的内容时，它会采取行动——开启 PR、推送修复、发布评论——并向用户的设备发送推送通知。

这种架构将编程 Agent 视为监控项目的“同事”，而非响应命令的“工具”。这种转变是从“助手”到“守护进程”的跨越。KAIROS 包含自己的调度系统、通知基础设施以及决定何时自主行动、何时需要人工批准的逻辑。

如果 KAIROS 发布，交互单位将从“对话”变为“订阅”。用户不再是打开 Claude Code 去干活，而是 Claude Code 已经在干活了，用户打开它只是为了审查已完成的工作。

Dream 系统：后台记忆整合

Dream 系统可能是代码库中最具野心的功能。它实现了后台记忆整合——一个在用户空闲时运行的 AI 过程，负责重新组织和压缩 Agent 积累的知识。

其触发机制使用三门控系统：自上次整合以来已过去足够时间、发生了最少次数的会话、且没有其他进程持有整合锁。这防止了系统运行过于频繁或与活动工作冲突。

一旦触发，Dream 周期执行四个阶段：

1. 定位 (Orient)：派生子 Agent 读取当前记忆状态和近期会话历史。
2. 收集 (Gather)：收集跨会话的模式、重复话题和已解决的问题。
3. 整合 (Consolidate)：将收集到的知识合成更新的记忆条目，合并重复项并解决矛盾。
4. 修剪 (Prune)：移除过时或低价值的条目，以保持在 Token 预算内。

这个名字并非偶然。神经科学研究早已证实，人类的记忆整合发生在睡眠期间。Dream 系统是一个工程化的模拟，Agent 在空闲时处理经验，使其在下一次会话中拥有比之前更清晰、更有条理的知识。这更接近于“学习”而非“缓存”。

BUDDY：电子宠物

源代码中最令人意外的发现是一个完整的虚拟宠物系统。BUDDY 是一个带有抽卡机制的确定性电子宠物。拥有 18 个物种、5 个稀有度等级和 1% 的闪光概率。宠物根据编程活动进化，它有情绪、饥饿状态和幸福感，这些都与用户使用 Claude Code 的频率Hook。

为什么专业的编程工具会包含电子宠物？答案是留存率。开发者工具的竞争维度之一是日常习惯的养成。VS Code 的胜出不仅是因为它是最好的编辑器，还因为开发者每天早上都会不假思索地打开它。BUDDY 是一种伪装成趣味性的参与机制，利用心理学模式来增强工具的粘性。

无论 BUDDY 是否发布，这都表明 Anthropic 的工程团队在非常严肃地思考注意力经济。开发者工具之战赢在让开发者在早上 9 点打开哪个工具，而基准测试（Benchmarks）在 9:05 就会被遗忘。

多智能体编排 (Multi-Agent Orchestration)

Claude Code 的协调模式实现了真正的多智能体编排。单个协调者 Agent 产生工作 Agent，分配任务并汇总输出。协调者不仅仅是分发工作，它还管理着一个四阶段的工作流。

scratchpad 目录是关键的基础设施。工作 Agent 将中间发现写入共享目录的文件中，其他工作 Agent 读取它们，协调者读取所有内容。这解决了多智能体系统的根本问题：Agent 如何在不破坏彼此上下文窗口的情况下共享状态。答案是磁盘上的文件——这是计算领域最古老的协调机制。

系统支持两种类型的工作 Agent：

• 进程内队友：共享父 Node.js 进程，轻量且快速，适用于代码搜索等只读任务。
• 基于进程的队友：作为独立进程运行，具有完全隔离性，拥有自己的上下文窗口、工具注册表和权限范围，适用于修改文件系统的任务。

值得借鉴的 6 个架构模式

Claude Code 的源代码是一份蓝图。并非每个想法都是原创的，但其组合方式极具参考价值。

其中模式 2（上下文管理）值得特别强调。它是长运行 Agent 会话的无声杀手。大多数 Agent 会随着对话增长而退化，模型会丢失早期指令或产生幻觉。Claude Code 的三层压缩是目前最先进的方法：

• autoCompact 处理宏观层面（总结对话的前半部分）。
• snipCompact 处理微观层面（将 3000 行的文件输出替换为 50 个 Token 的摘要）。
• contextCollapse 处理中观层面（将连续的工具调用合并为一个块）。

这种组合意味着会话可以运行数小时而不会出现性能退化。

竞争格局

源代码重新绘制了竞争版图。在此之前，编程 Agent 市场依赖于演示和基准测试。现在，每个竞争对手都能看到 Claude Code 的底层逻辑。

• Cursor：在用户体验上最接近，但架构上较简单。它利用 VS Code 的深度集成，这是 Claude Code 在终端中无法比拟的。但 Cursor 缺乏多智能体协调和后台整合机制。
• GitHub Copilot：拥有最广泛的分发渠道。但即使经过多次迭代，其 Agent 模式仍更接近于带有工具访问权限的自动补全引擎，缺乏 Bash AST 解析器或复杂的上下文压缩。
• Windsurf：在推理引擎上投入巨大，处理上下文表现出色。但其架构不透明，且目前没有表现出像 Claude Code 那样的治理深度。
• Cline 和 Aider：代表了开源力量。它们在各自范围内非常出色，但尚未尝试多智能体编排或自主运行。

Claude Code 的护城河不在于单一功能，而在于功能之间的相互作用。Dream 系统让 KAIROS 更聪明，Bash AST 解析器让权限系统成为可能，从而让自主运行变得安全。移除任何一层，其他层都会退化。这就是一个构思良好的架构的本质：整体比部分之和更难复制。

模型耦合问题

源代码提出了一个重要问题：这种架构有多少是可以迁移到其他模型的？

有些层是模型无关的，如查询循环、Bash AST 解析器和文件系统集成。但其他层与 Claude 的特定行为深度耦合。例如，权限侧向查询依赖于 Claude 的指令遵循校准和风险评估倾向。知识注入模式之所以有效，是因为 Claude 对工具结果的处理具有极高的保真度。在 GPT-4o 或 Gemini 上构建类似的 12 层架构，下 6 层很容易迁移，但上 6 层需要大量的重新调优。

终点

源代码揭示了编程 Agent 的发展轨迹：自主 Agent 能够跨会话整合知识、协调并行工作，并在开发者不在场时主动采取行动。

12 层治理架构是一份路线图，KAIROS 是目的地，Dream 系统是 Agent 建立项目级理解的方式，而协调者则是它扩展到单线程工作之外的手段。每个编程 Agent 最终都会构建类似的东西，因为这些是每个团队在这一领域最终都会遇到的工程约束。

• 原文链接： x.com/yq_acc/status/2038...
• 登链社区 AI 助手，为大家转译优秀英文文章，如有翻译不通的地方，还请包涵～