Claude Code 源码深度解析

深入一个 AI 编程助手的内核实现。

你每天在终端里敲 claude，回车之后到出现提示符之间发生了什么？它凭什么敢替你改文件、跑命令，又凭什么在某些命令前停下来问你？当它同时调用三个工具时，谁来保证它们不互相踩踏？

这些问题的答案都写在源码里。本专栏以 Claude Code 完整源码（2026.3.31 泄露版本）为解剖对象——51 万行代码、40+ 工具、80+ 命令——逐层拆开它的每一个子系统。

flowchart TB
  CLI[CLI 启动<br/>三阶段 · 并行预加载 · 快速路径] --> Q
  subgraph Q [Query 引擎 · 两层架构]
    direction LR
    HI[query.ts<br/>高层编排] --> LO[QueryEngine.ts<br/>循环状态机]
  end
  Q --> TS[工具系统<br/>自描述 · Zod 校验 · 注册表]
  TS --> PERM{权限<br/>静态规则 + 动态分类器}
  PERM -->|放行| EXEC[并发编排<br/>并发安全标记]
  PERM -->|需确认| ASK[用户确认 / 拒绝追踪]
  EXEC --> UI[终端 UI · React 渲染]
  TS -.-> MCP[MCP 集成<br/>外部工具接入]
  TS -.-> BR[IDE Bridge<br/>JWT · 会话 · 权限转发]
  Q -.-> SUB[多 Agent<br/>上下文隔离]

无论你是否使用 Claude Code，这些设计模式都是你构建自己的 Agent 系统时会遇到的同一批问题——区别只在于，这里有一份跑在几百万开发者机器上的答案可以对照。

读完你能做到什么

说清一次 Agent 循环的完整生命周期。 从 query.ts 的高层编排到 QueryEngine.ts 的状态机，包括停止条件的完整图谱与 AsyncGenerator 为什么是这里的正确抽象（第4章 Query 引擎、第5章流式响应）。
设计一套自描述、可校验、能并发的工具系统。 Tool 类型定义、Zod 运行时校验、工具注册表、渲染体系，以及那个决定谁能和谁一起跑的「并发安全标记」（第6章工具类型系统、第7章工具编排、第8章核心工具）。
实现一个既安全又不烦人的权限模型。 四档权限模式、useCanUseTool 这个钩子怎么把静态规则匹配与动态分类器串起来、拒绝行为如何被追踪与分析、多 Agent 场景下权限怎么继承（第9章权限模型、第10章沙箱）。
把启动时间当成一个工程指标来优化。 启动的三个阶段、并行预加载、特性标志驱动的死代码消除、--bare 极简路径——「从第一个字节到交互式提示符」这段路上每一毫秒花在哪（第3章 CLI 启动）。
把 Agent 接进 IDE 和外部工具生态。 MCP 服务器的生命周期、工具发现与调用、通道通知；以及 IDE Bridge 的 JWT 认证、会话管理与权限对话转发（第11章 MCP 集成、第12章 IDE Bridge、第13章 LSP）。
用 React 写终端界面。 为什么是 React、它在终端里怎么协调流式输出与用户输入（第17章终端 UI）。

这个专栏的讲法

读的是源码，不是文档。 每一章都落到具体的文件、类与函数上——useCanUseTool 怎么写的、Tool 注册表长什么样、状态机有哪几个停止条件。不是"Claude Code 支持权限管理"这种介绍性描述。

每章末尾有「设计决策分析」。 这是这个专栏与「源码导读」的分界线：不只说它怎么做的，还说它为什么不那样做——两层 Query 架构为什么要拆、权限为什么要静态规则加动态分类器两条腿走路、并发标记为什么放在工具自己身上。这些取舍才是能迁移到你自己系统里的东西。

从启动到收尾，覆盖一个完整的 Agent。 18 章按运行顺序排列：启动 → 循环 → 工具 → 权限 → 扩展（MCP / IDE / 多 Agent） → 上下文管理 → UI → 设计模式总结（第18章）。读完你手里是一张完整的架构图，不是一堆知识点。

适合谁读

有 TypeScript 经验的前端/全栈工程师。 源码是 TS 写的，读起来没有语言门槛。
正在造 Agent 或 Agent 平台的开发者。 这里的工具系统、权限模型、并发编排就是你要做的那几件事。
想知道 AI 编程助手到底怎么工作的技术人。 包括不打算自己造一个、但希望用得更明白的人。

不适合：找 Claude Code 使用教程的读者（这里不讲怎么用），以及没有工程背景、只想了解 AI 概念的读者。

源码版本

本专栏基于 Claude Code 2026.3.31 源码快照——对应 npm 包 @anthropic-ai/claude-code@2.1.89（2026-03-31 发布）短暂随包分发的 source map 所还原出的 TypeScript 源码树。

需要先说清楚：这份源码今天已经拿不到了，否则你会白白花时间去找。

github.com/anthropics/claude-code 里没有产品源码。那个仓库是 issue 跟踪、文档、示例与插件仓库，不包含 src/，更没有 main.tsx，clone 它对照本专栏一行都对不上。
npm 包里也已经没有 source map 了。把 2.1.89 的 tarball 解开可以自己验证：整包 19 个文件，主体是一个 13MB、16824 行的压缩 cli.js，没有任何 .map 文件，末尾也没有 sourceMappingURL 注释。

所以本专栏引用的文件路径和行号，对照的是那一份已不可再获取的快照。这意味着你没法像读其他源码专栏那样 checkout 一棵树来逐行核对——正文因此尽量以模块职责、函数名和调用关系为锚点来讲，而不是把结论压在某个行号上。把它当作一份对已发生实现的记录来读，而不是一份可复现的实验。

版权声明

欢迎分享本专栏的链接。引用少量内容用于评论、教学或研究时，请署名 杨艺韬 并附上原文链接。

Claude Code 源码深度解析

读完你能做到什么

这个专栏的讲法

适合谁读

源码版本

目录

第一部分：开篇

第二部分：启动与核心循环

第三部分：工具系统

第四部分：权限与安全

第五部分：协议与集成

第六部分：Agent 进阶

第七部分：终端 UI 与工程实践

版权声明