源码泄露后,解析Claude Code架构

每一代开发者工具都源于一个关键的架构决策。Unix 押注小而可组合的程序，通过管道连接优于大型单体系统；Git 押注分布式版本控制会胜过集中式服务器；Docker 押注容器化会胜过虚拟机。这些决策对用户不可见，却决定了工具的最终命运。

如今，Claude Code 的架构赌注因源代码泄露而公之于众。这份从 npm 包的 sourcemap 文件中恢复的代码，包含 1332 个 TypeScript 文件，总计 512,664 行。

它揭示的核心理念是：AI 辅助编程的真正难题不在于代码生成的“质量”，而在于执行的“可靠性”。语言模型是引擎，而包裹其外的层层架构——包括 12 层Harness架构构建的“安全带”、40 多个工具、一个完整的 Bash AST 解析器和三个未发布的自研功能——其目标只有一个：让这个引擎变得安全、持久，并最终实现自主运行。

Claude Code 正在构建第一代能够在无人监督的情况下编写软件的雏形。其源代码清晰地揭示了这需要什么样的架构支撑。

一、12 层Harness架构

Claude Code 的核心是一个位于 query.ts 中的 while(true) 循环。一个生成器函数在每次 API 调用后让出控制权，检查响应，决定是继续还是停止，然后循环继续。除此之外的所有代码，都是“安全带”。这个架构并非单一创新，而是 12 种机制的有机组合，每一种机制都针对一个特定的故障模式。

演进逻辑：

• Layer 1-3：解决 API 调用的基本可靠性问题（流式传输、重试、错误处理）。
• Layer 4-6：解决“工具”问题（组装上下文、注册工具、安全解析命令）。
• Layer 7-9：解决“信任”问题（沙盒执行、权限分类、长对话压缩）。
• Layer 10-12：解决“自主”问题（跨会话记忆、主动行动、多智能体协作）。

大多数同类智能体只实现了前六层，它们可以调用工具、执行命令。而 Claude Code 的独特优势在于上方的六层——这些架构处理的是当会话持续数小时、用户不在线、多个智能体需要共享状态时的复杂场景。这完全是为了一类不同的产品而构建的基础设施。

二、工具系统：当 AST 解析遇上动态权限

Claude Code 内置了 40 多个工具，通过 buildTool() 工厂模式注册。每个工具的声明都包含名称、描述、输入模式、权限要求和执行函数。这种模式高度一致，添加一个新工具只需约 30 行代码。

Bash 工具是其中最引人注目的一个。它没有使用正则表达式来判断一个 Shell 命令是否安全，而是包含了一个完整的 Bash AST 解析器（2,679 行 TypeScript）。它先将 Shell 命令进行词法分析和语法分析，生成抽象语法树，然后遍历这棵树，提取每个可执行程序、标志、管道目标、重定向。这避免了正则表达式因引号、变量扩展、子 Shell 等复杂语法导致的判断失误。

权限系统与 AST 解析器深度集成。它使用一个 ML 分类器（通过一次额外的 Claude 查询）来将命令分为三个等级：允许、拒绝或询问用户。这不是静态白名单，模型会结合当前工作目录、用户最近的指令和工具声明的风险等级来评估每个命令。

知识注入策略也独树一帜。大多数智能体将知识塞入系统提示词。而 Claude Code 通过 tool_result 消息注入知识——将合成响应放入对话中，就像工具返回的一样。这让系统提示词保持精简，并将知识恰好放在模型最关注的近期上下文窗口中。

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

源代码中包含 108 个仅内部使用的模块（通过雇员检查或编译时特性标志控制）。其中三个功能揭示了 Anthropic 对编码智能体未来方向的思考。

1. KAIROS：永不停歇的智能体

KAIROS 是一个自主智能体守护进程。它不等待用户输入，而是基于心跳定时唤醒，检查事件（新 PR、CI 失败、代码审查评论、依赖更新）。当发现可操作的事件时，它会自主行动——打开 PR、推送修复、发表评论——并向用户发送推送通知。

架构： 心跳滴答→事件监控器(PR,CI,审查)→决策引擎→自主行动→推送通知

这标志着智能体从“响应命令的工具”向“监控项目的同事”转变。如果 KAIROS 发布，交互单元将从“对话”变为“订阅”。

2. Dream 系统：背景记忆整合

这是代码库中最具雄心的功能。Dream 系统实现了后台记忆整合——一个在用户空闲时运行的 AI 进程，用于重组和压缩智能体积累的知识。其触发机制是一个三阶段门控系统：

1. 距离上次整合时间足够长
2. 已达到最低会话数
3. 没有其他进程持有整合锁

一旦触发，将执行四阶段整合流程：

• 定向（orient）：分叉的子智能体读取当前内存状态和最近的会话历史。
• 收集（gather）：子智能体跨会话收集模式、重复主题和已解决的问题。
• 整合（consolidate）：将收集到的知识合成更新的内存条目，合并重复项并解决矛盾。
• 修剪（prune）：删除过时或低价值条目，确保内存不超限。

神经科学研究早已揭示出，人类记忆巩固发生在睡眠期间——大脑重放和重组白天的经历，这个就如同模拟人类记忆在睡眠中的巩固机制。Dream 系统相当于其工程实现，智能体在空闲时处理自己的经验，在下次会话开始时拥有比上次更清晰、更结构化的知识。这更接近学习而非存储。

3. BUDDY：电子宠物

源代码中最意想不到的发现是一个功能完整的虚拟宠物系统。BUDDY 是一个带有扭蛋机制（gacha mechanics）的“Tamagotchi”：18 个物种、5 个稀有度等级、1% 的闪光概率。宠物的进化取决于用户的编码活动，其心情、饥饿度和快乐值与用户使用 Claude Code 的频率挂钩。

为何专业编码工具需要虚拟宠物？ 答案是用户留存。开发者工具的竞争维度之一与功能无关：日常养成。VS Code 获胜不是因为它是最优秀的编辑器，而是因为开发者每天早上不假思索地打开它。。BUDDY 是一个披着趣味外衣的参与度机制。扭蛋机制创造了可变比率强化——一种驱动手机游戏变现的心理学模式——被应用于编码工具。

需要说明的是，这些未发布功能的存在并不意味着它们会最终上线。大型代码库中常包含原型和实验项目。但它们揭示的架构模式（三阶段门控、四阶段整合）本身就具有启发性。

四、多智能体编排：从单线程到协同工作

Claude Code 的协调器模式实现了真正的单会话多智能体编排。一个协调器智能体可以生成工作智能体，分配任务，并整合它们的输出。它管理一个四阶段工作流：

Scratchpad 目录是关键技术。工作智能体将中间发现写入共享目录中的文件，其他智能体可以读取这些文件，协调器则可以读取所有文件。这解决了多智能体系统的核心问题：如何在不破坏彼此上下文窗口的情况下共享状态。答案是磁盘上的文件——最古老的协调机制，被应用于最前沿的领域。

系统支持两种工作智能体：

• 进程内智能体：共享父进程的 Node.js 进程，轻量、快速，适合只读任务。
• 基于进程的智能体：作为独立进程运行，完全隔离，拥有自己的上下文、工具和权限范围，更安全，适合修改性任务。

这种双智能体架构反映了务实的工程权衡。

五、每个编码智能体构建者应借鉴的六个架构模式

Claude Code 的源代码是一份蓝图。以下六个模式值得所有开发者关注：

1. 生成器查询循环：为中断式 AI 工作流提供“暂停-恢复”能力，是实现长时任务的基础。
2. 三层上下文压缩：解决长会话的“无声杀手”。 autoCompact（宏观总结） + snipCompact（微观摘要） + contextCollapse（合并工具调用），确保数小时会话性能不下降。
3. Bash AST 解析器：是实现安全自主操作的前提。它让模型能安全执行 Shell 命令，而不用担心危险命令。
4. tool_result 知识注入：保持系统提示词精炼，利用模型对工具输出的高关注度，将关键信息放在最佳位置。
5. 编译时功能标志：使用 Bun 的编译时特性，在构建时完全移除内部代码，而非运行时判断。这既保证了安全性，也解释了为什么 sourcemap 会泄露“预删除”代码。
6. 多智能体协调与 Scratchpad：通过文件系统共享状态，优雅地解决了多个 AI 上下文窗口间的通信问题，让并行工作成为可能。

六、竞争格局：可被观察，难以复制

源代码的泄露重绘了竞争地图。现在，每个竞争对手都能看到 Claude Code 的内部实现。

Cursor 在用户体验上最接近，其定制版 VS Code 的集成深度是 Claude Code 无法比拟的。但其架构更简单，缺乏多智能体协调和后台记忆能力。

GitHub Copilot 拥有最强的分发渠道，但其智能体模式仍停留在“带工具的自动补全”阶段，没有 AST 解析和自主功能。

Cline 和 Aider 代表了优秀的开源方案，但它们专注于当前范式下的工具，并未尝试多智能体编排或自主操作。

Claude Code 的护城河并非任何单一功能，而是这些功能之间的相互作用：

• Dream 系统通过后台整合知识，让 KAIROS 的自主行动更智能。
• Bash AST 解析器让权限系统成为可能，从而让自主操作变得安全。
• 三层压缩使长会话成为可能，这让多智能体协调变得实用。

移除任何一层，其他层的能力都会随之退化。这正是优秀架构的本质：整体比部分之和更难复制。

七、模型耦合问题：不可完全复制的智慧

源代码提出了一个无法完全回答的关键问题：有多少架构可以移植到其他模型？

• 模型无关层：生成器循环、Bash AST 解析器、文件系统操作等，与模型无关，可以轻松移植。
• 模型耦合层：
• 权限分类
  
  通过额外的 Claude 查询来判断工具调用是否安全，这高度依赖 Claude 的指令遵循能力和风险判断倾向。
• tool_result 知识注入
  
  效果取决于模型是否像 Claude 一样高度重视工具结果。
• 三层压缩
  
  提示词和压缩方式是为 Claude 的摘要能力量身定制的。

这意味着，竞争对手构建一个类似的 12 层架构时，低层级容易复制，但高层级需要大量的重新调优。权限分类器、Dream 系统的提示词、协调器的系统提示词（据报道有 4000 字）——这些是模型专属的“知识产权”。架构是开放的，但调优是核心壁垒。

八、总结：终局何在

源代码揭示的不仅是实现细节，更是对编码智能体发展方向的判断。

路线图已然清晰：能够跨会话整合知识的自主智能体、能够并行协作的协调者、能够在开发者离开时主动行动的守护进程。12 层Harness架构是一张路线图。KAIROS 是终点。Dream 系统是智能体建立项目级理解的途径。协调器则是它超越单线程，实现规模化协作的方式。

最终，每个编码智能体都将构建类似的东西。生成器循环是实现可中断 AI 工作流的正确抽象。三层压缩是运行数小时会话的必需品。AST 级安全分析是实现模型自主执行命令的必要条件。后台记忆整合是实现跨天、跨周持久化的智能体的必要条件。这些是所有该领域团队都终将面对的工程约束。

Claude Code 的优势在于，它比任何人都更早地看到了这一点，并已经开始围绕这些约束构建一个完整、协同的解决方案。

原文：https://x.com/yq_acc/status/2038994315180204104