# 这不是聊天机器人

当你在终端输入 `claude`，并不是打开了一个聊天窗口——你启动了一个有 1884 个 TypeScript 文件的工程系统。

> **🌍 你可能听过的同类产品**（以下竞品定位、能力、数字据各厂商公开资料与社区口径整理，截至 2026 年初，以官方公告为准）：2026 年的 AI 编程助手已完成从"单点补全"到"智能体集群编排"的范式跃迁。
>
> - **Cursor**：Background Agents 在云端 VM 中并行重构
> - **Windsurf**：Cascade Engine 实现亚秒级预测性编辑
> - **GitHub Copilot**：Agent Mode 已进入 GA（内置 Explore/Plan/Task 专职智能体）
> - **Codex（OpenAI）**：以 Rust 重写的终端工具，支持并行 Agent 工作流
> - **Kimi Code**：基于 K2.5 实现多并发子智能体的 Agent Swarm（厂商宣称百级并发）
> - **OpenCode**：以十万+ GitHub Star 量级成为开源 CLI 标杆（支持数十家模型提供商）
> - **GLM（Z.ai）**：以超大规模参数模型（具体以 Z.ai 官方公告为准）在国产算力集群上完成训练，提供 Z Code 私有化编程底座
> - **Aider**：引入 AST 级 Repo Map 和 Architect 模式
>
> Claude Code 和它们最大的不同：它是**纯终端原生**的 AI Agent，不依赖任何 IDE，且源码规模远超大多数同类工具——这意味着更复杂的工程系统，但也意味着更多可以分析和学习的设计决策。本书就是拆解这个系统的每一层。

> 📚 **课程关联**：如果你学过软件工程，Claude Code 的架构覆盖了教科书里几乎所有经典模式——事件循环（Event Loop）、责任链（Chain of Responsibility）、发布-订阅（Pub-Sub）、适配器（Adapter）、桥接（Bridge）、工厂（Factory）。读这本书相当于在一个真实产品中看到这些模式的工程化落地。后续每个模式首次出现时都会标注 📚 帮你对应到课程知识。

---

## 两种截然不同的心智模型

**模型 A（错误的）**：用户输入消息 → API 调用 → AI 输出 → 显示给用户

**模型 B（实际的）**：

```
用户输入
  → [权限系统] 检查是否允许这个操作
  → [上下文构建] 组装 git 状态 + CLAUDE.md + 会话历史
  → [queryLoop 主循环] 开始 AI 推理
      → AI 说：我要读这个文件
      → [StreamingToolExecutor] 在 AI 还在说话时就开始读文件
      → [工具并发] 三个文件同时读取（而不是串行）
      → AI 说：我要编辑这个文件
      → [权限弹窗] 请求用户批准
      → AI 继续...
      → [上下文压缩] token 快满时，用另一个 AI 来总结对话
  → [SessionMemory] 后台 AI 更新项目笔记
  → [Prompt Suggestion] 预测你下一条消息
  → [Speculation] 开始以预测消息执行 AI（你还没打字呢）
```

这不是一个 API 调用。这是一个**有自己生命周期的、多 AI 协作的、流水线执行的工程系统**。

---

## 系统的边界在哪里

大多数人对 Claude Code 的理解停在"一个带工具的 AI 助手"。但准确的描述是：

**一个 AI 主循环（`queryLoop`），加上围绕它工作的多个子系统。**

主循环是心脏：`while(true)` 的 AsyncGenerator（异步生成器——像水龙头一样持续输出事件流），接收用户输入，调用 API，处理工具，直到有最终回答。

> 💡 **通俗理解**：主循环就像**快递分拣流水线**——收件（用户输入）→ 分拣（判断需要调用什么工具）→ 装车（执行工具）→ 送达（返回结果）→ 签收（显示给用户）→ 等下一单（继续循环）。流水线不停转，直到所有快递都送完。

围绕主循环的子系统各自独立工作，通过共享状态（AppState）和 hooks 系统协调：

| 子系统 | 职责 | 竞品对比 |
|--------|------|---------|
| 权限系统 | 决定每个操作是否被允许 | Aider 只有 `--yes` 开关；Cursor 用简化弹窗 |
| 上下文构建 | 组装发给 AI 的完整提示词 | Aider 用 repo map 预过滤；Cursor 用 .cursorrules |
| 工具执行 | 并行、流式执行 AI 调用的工具 | 大多数竞品是串行执行 |
| 上下文压缩 | 在 token 快满时无感压缩对话 | Aider 选择预过滤而非事后压缩 |
| Agent 系统 | 创建并管理子 Agent 实例 | 见 Part 4 "多 Agent 编排" |
| MCP 层 | 接入外部工具服务器 | Cursor/Windsurf 也支持 MCP，调度细节不同 |
| SessionMemory | 后台提取和维护会话笔记 | 多数竞品无此机制 |
| Speculation | 预测下一个用户输入并提前执行 | 公开资料中未见其他 CLI 工具做预测执行 |

> 💡 **通俗理解**：上下文压缩就像**会议记录员**——全程录音太长了 → 做一份精华摘要 → 把原始录音归档。下次开会带摘要就行，不用重听三小时的录音。

---

## 这个系统有多大

- **1,884 个源文件**（1,332 `.ts` + 552 `.tsx`，以 Claude Code 2.1.88 源码 `find src -name '*.ts' -o -name '*.tsx' | wc -l` 核实）
- 主入口文件 `main.tsx`：785KB / 4,684 行（单文件）
- AI 主循环 `query.ts`：**1,729 行**（`wc -l` 核实）
- 权限系统 `permissions.ts`：**1,486 行**（`wc -l` 核实）
- CLAUDE.md 加载 `claudemd.ts`：**1,479 行**（`wc -l` 核实）
- 工具接口 `Tool.ts`：约 25+ 方法/属性（以 `src/Tool.ts` 中 `export type Tool<Input, Output, P> = {...}` 的字段枚举为准）

它使用了 React（用于终端 UI 渲染）、Zod（类型验证）、Anthropic SDK（AI 调用）、OpenTelemetry（可观测性）、GrowthBook（特性门控），以及数十个其他依赖。

> 💡 **通俗理解**：GrowthBook 的"特性门控"就像**餐厅的隐藏菜单**——菜做好了，但只有 VIP 或内部员工才能点。普通客人看不到菜单上有这道菜，但只要服务员（feature gate）允许，随时可以端上来。

---

## 为什么这些设计值得深入了解

Claude Code 是一个在约束条件极为苛刻的场景下构建的系统：

- **不能失去上下文**：对话历史有 token 上限，需要自动压缩
- **不能中断工作流**：工具执行必须高效，用户等待时间必须最短
- **不能意外破坏文件**：权限系统必须有多道防线
- **不能浪费 token**：缓存策略必须精心设计
- **不能信任所有输入**：工具结果可能包含注入攻击

每一个设计决策背后都有这些约束的影子。理解这些约束，你就理解了代码里那些"为什么要这么复杂"的问题。

---

## 本书的导读

**Part 2（代码架构完全解构）** 是地基。系统性地拆解整个代码库，从启动序列到终端 UI，按架构层次逐层解剖每一个子系统。

**Part 3（好奇心驱动的深度问答）** 是主体。每章选择一个"反直觉"或"令人困惑"的设计，从"你可能以为……"开始，揭示实际的实现和背后的权衡。

**Part 4（子系统完全解析）** 是参考资料。如果你想深入了解某个子系统的完整细节，从这里找。

**Part 5（工程哲学）** 是提炼。Claude Code 展示了哪些可以借鉴的工程思想？

**Part 6（批判与超越）** 是反思。哪些设计是有代价的权衡？哪些地方可以做得更好？

---

*建议阅读方式*：先读 Part 3 的任意一章，建立初步印象，然后按照关联章节的指引跳转。每章都可以独立阅读。

---

## 关键源码入口

- `src/main.tsx` — 整个系统的入口文件（4,684 行），启动序列、REPL 循环、全局状态初始化都在这里
- `src/query.ts` — Agent 循环的核心：`while(true)` 查询循环，驱动"调用 API → 执行工具 → 再次调用"的心跳
- `src/services/api/claude.ts` — 封装 Anthropic API 调用，流式响应处理、token 计数、缓存控制
- `src/Tool.ts` — 工具基础接口定义，所有 40 个内置工具目录都实现这个接口