← 返回书架

Claude Code 源码深度解析

基于 Claude Code 原始 TypeScript 源码的架构深度解析 — 不再是反编译猜测，而是直面真实代码

Claude Code 是 Anthropic 推出的终端 AI 编程助手。它不只是一个“能写代码的 LLM“，而是一个完整的 Agentic 系统 — 拥有循环推理、工具调用、安全沙箱、多智能体协作等工业级能力。

本书基于 Claude Code 的原始 TypeScript 源码进行逐层拆解，揭示这个系统的真实架构。

与前作的区别

本书是 《Claude Code Deep Dive》的全面升级版。核心区别如下：

设计决策：Anthropic 已将 Claude Code 从 npm/Node.js 分发切换到 Bun 独立二进制分发。TypeScript 源码通过 bun build --compile 编译为独立可执行文件，运行时为 Bun（JavaScriptCore 引擎）。这意味着代码中随处可见的 import { feature } from 'bun:bundle' 是编译期条件编译的核心机制，在打包时会被静态求值，实现 dead code elimination。

本书结构

全书分为 6 篇 29 章 + 2 附录，从入门概览到核心架构、工具系统、安全机制、进阶子系统，最终到实战与展望：

第一篇 · 入门

第二篇 · 核心架构

第三篇 · 工具与能力

第四篇 · 安全与扩展

第五篇 · 进阶子系统

第六篇 · 实战与展望

附录

源码目录速览

本书分析的源码位于 src/ 目录下，以下是核心目录结构：

src/
├── main.tsx                  # CLI 主入口（Commander.js 参数解析 + 启动序列）
├── query.ts                  # Agentic Loop 核心（query() 循环）
├── QueryEngine.ts            # 查询引擎（SDK/headless 模式入口）
├── Tool.ts                   # Tool 接口定义与 ToolUseContext
├── tools.ts                  # 工具注册表（getAllBaseTools / getTools）
├── commands.ts               # Slash 命令注册表（90+ 命令）
├── Task.ts                   # 后台任务抽象
├── components/               # React/Ink UI 组件（App, REPL, MessageList...）
├── tools/                    # 40+ 工具实现
│   ├── BashTool/             #   Bash 执行 + 沙箱
│   ├── FileReadTool/         #   文件读取
│   ├── FileEditTool/         #   文件编辑
│   ├── FileWriteTool/        #   文件写入
│   ├── GlobTool/             #   文件搜索
│   ├── GrepTool/             #   内容搜索
│   ├── AgentTool/            #   子 Agent + 多智能体
│   ├── WebFetchTool/         #   URL 抓取
│   ├── WebSearchTool/        #   网络搜索
│   └── ...                   #   更多工具
├── services/                 # 服务层
│   ├── api/                  #   API 客户端（claude.ts, client.ts, withRetry.ts）
│   ├── mcp/                  #   MCP 协议（config, client, types）
│   ├── compact/              #   上下文压缩（auto, micro, snip）
│   ├── analytics/            #   遥测分析
│   └── ...
├── utils/                    # 工具函数
│   ├── permissions/          #   权限引擎
│   ├── sandbox/              #   沙箱适配器
│   ├── hooks/                #   Hooks 系统
│   ├── model/                #   模型选择与配置
│   └── ...
├── state/                    # 应用状态管理（AppState, store）
├── entrypoints/              # 入口点（cli, mcp, init）
├── bridge/                   # 远程桥接（Claude Desktop 集成）
├── commands/                 # Slash 命令实现（90+ 命令目录）
└── skills/                   # Skill 系统（YAML 定义的 AI 工作流）

阅读约定

本书基于原始 TypeScript 源码分析，使用真实的文件名、函数名、类名。标注格式如下：

query() in src/query.ts — Agentic Loop 核心函数

• 前者（query()）是源码中的真实函数名
• 后者（src/query.ts）是真实文件路径

代码引用示例：

// src/query.ts — Agentic Loop 核心循环
export async function* query(params: QueryParams): AsyncGenerator<...> {
  const terminal = yield* queryLoop(params, consumedCommandUuids)
  return terminal
}

每章末尾的速查表汇总了该章涉及的所有关键文件和函数。

feature() 编译开关约定

源码中大量使用 import { feature } from 'bun:bundle' 进行条件编译：

const reactiveCompact = feature('REACTIVE_COMPACT')
  ? require('./services/compact/reactiveCompact.js')
  : null

feature() 在编译时被静态求值为 true 或 false，用于：

• Dead code elimination：外部构建中排除内部功能
• Feature flags：控制实验性功能的开启/关闭
• 构建变体：区分 ant（内部）和 external（外部）构建

本书中提及 feature flag 时会标注 [feature: FLAG_NAME]。完整的 flag 索引见附录 B。

阅读建议

• 快速了解：先读第 3 章（架构总览），建立全局地图
• 深入核心：接着读第 4 章（Agentic Loop），理解 Agent 的心跳
• 按篇阅读：每篇相对独立，可根据兴趣选择
• 源码对照：每章都附有真实源码引用和速查表，建议边读边对照 src/ 目录

关于

• 作者：Liang Cui
• 分析对象：Claude Code 原始 TypeScript 源码
• 状态：持续更新中

声明

⚠️ 本书仅供学习和研究目的使用。

• 知识产权：Claude Code 是 Anthropic 公司的产品，其源代码及相关知识产权归 Anthropic 所有。本书引用的代码片段仅用于说明架构原理，版权归原权利人所有。
• 非官方：本书为独立的第三方研究作品，未经 Anthropic 公司授权、赞助或认可。
• 商标：Claude、Claude Code、Anthropic 均为 Anthropic 公司的商标或注册商标，本书中的使用仅为描述性引用，不暗示任何关联或背书。
• 合理使用：本书的分析属于为研究和教学目的对软件架构的学术性探讨，符合合理使用 (Fair Use) 原则。
• 范围限制：本书不提供完整源码，仅引用必要的代码片段用于技术分析和教学。
• 免责：本书内容仅供参考，不构成任何形式的技术建议或保证。
• 配合处理：如权利人对本书内容有异议，作者将积极配合处理。联系邮箱：[email protected]