Claude Code 源码解析：揭秘 Anthropic 的 AI Agent 工程实践

2026年3月31日Anthropic 的 npm 包因配置失误意外暴露了 Claude Code 的完整 TypeScript 源码，约 数万行代码 向所有人敞开大门。本文基于这份公开的源码快照进行深度解析，探讨其背后的设计哲学与工程实践。

src/query.ts 是整个系统的核心，约 数千行代码。其主循环采用 while 结构，每次迭代代表一个"轮次"。状态通过不可变的 State 对象传递：

let state: State = { ... }
while  {
  const { messages, turnCount, ... } = state
  // 处理逻辑
  state = { ...nextState } // 整体替换
}

这种设计的优点是状态管理清晰，所有状态变gengdou通过重新赋值整个 state 对象实现，保证了数据流的可追踪性。

LLM 的Zui大挑战之一是有限的上下文窗口。Claude Code 通过五层递进的机制来管理上下文：

1. Tool Result 大小限制
2. Snip 压缩
3. Microcompact
4. Context Collapse
5. Auto Compact

每层dou在 API 调用前依次执行，有效控制了上下文大小。以 Context Collapse 为例，它使用 Read-time projection 技术折叠历史消息，并将折叠记录存入 store 以保证状态持久。

"缓留"机制 是 Claude Code 错误处理的精髓：某些可恢复的错误消息在流式阶段被暂不传递给调用方，而是等待恢复逻辑判断。成功则悄无声息地重试，失败才暴露错误。这种设计避免了 SDK 消费者在kan到 error 字段时立即终止会话。

当 Claude 因输出 token 上限被截断时系统尝试三种恢复方式：

Token 升级Ru果未设置输出上限，则尝试用geng大的 token 上限重试；

截断续写Zui多尝试 N 次续写恢复；

"放弃，暴露错误"

"传统 Agent Loop 是串行的，而 StreamingToolExecutor 打破了这一局限。"

"它Neng在模型仍在流式输出时就开始执行Yi确认的工具调用，将'等待工具执行'的时间隐藏在'等待模型输出'的时间里。"

模型流式输出:     
                                   │                              │
StreamingToolExecutor:        addTool 立即开始执行         addTool 立即开始执行
                                   │                              │
流结束后:              getRemainingResults 收割所有完成的结果
          

当主模型降级到 fallback 模型时,Claude Code 会插入特殊的 Tombstone 消息:

for  {
    yield { type: 'tombstone', message: msg }
}

UI层接收到Tombstone后会移除对应的原始消息,保证视觉一致性。

从src/main.tsx的第一行就可见一斑:

import { profileCheckpoint } from './utils/startupProfiler.js'
profileCheckpoint // ← 第一行就开始计时
// 并行启动多个耗时操作
startMdmRawRead // 读取配置
startKeychainPrefetch // 预取密钥信息

运行时A/B测试 typescript const value = getFeatureValue_CACHED_MAY_BE_STALE 构建时消除 typescript if ) { // 此块在 feature 关闭的 build 中被完全删除 }

通读Claude Code源码后,我们不禁感叹Anthropic团队在AI工程领域的深厚造诣。从极致的性Neng优化到精妙的错误恢复机制,从并发工具执行到多层次上下文管理,每个细节dou体现了"以生产环境标准构建AI Agent"的设计哲学。

这份意外曝光的源码,不仅是技术爱好者的宝贵资料,geng是AI工程实践的优秀范本。它让我们kan到,一个真正面向生产的AI Agent系统,需要解决多少工程问题。

Ru果你对某个具体模块有geng深入的问题,欢迎在评论区讨论。让我们一起探索Claude Code背后的设计智慧。