# 八个子系统的全景地图

> 这章的目标：在你进入任何一章的细节之前，先知道整个系统有哪些"房间"，每个房间里住着什么，它们之间的门开在哪里。

> **🌍 行业背景**：大型 AI Agent 系统的架构都在回答同一组问题：如何安全地执行工具？如何管理有限的上下文？如何扩展能力？**LangChain** 用 Chain → Agent → Tool 三层抽象，**AutoGPT** 用 Task → Action → Plugin，**CrewAI** 用 Agent → Task → Crew 分工协作。Claude Code 的八个子系统是它对这些问题的回答——比大多数框架更完整（包含了投机执行、后台记忆等独有子系统），也更重：仅 `src/` 目录下就有 1,884 个 TypeScript / TSX 文件（SoT 统计命令：`find src -type f \( -name "*.ts" -o -name "*.tsx" \) | wc -l`），规模远超一个典型的 LangChain Agent 示例项目（后者通常数百行配置即可起步，两者定位不同，此处仅示意工程量量级差距）。本章帮你建立对这八个"房间"的全局认知。

---

## 为什么需要一张全景地图

Claude Code 不是一个线性的程序——"输入 → 处理 → 输出"。它是一个**多中心、多循环、有后台任务的并发系统**。

如果你直接进入某个细节（比如"投机执行是怎么工作的"），很容易迷失在局部，不知道这个功能和其他部分是什么关系。

这张地图先帮你建立"系统感"。

[图表预留 1.4-A：系统全景架构图（八个子系统的位置和连接关系）]

---

## 八个子系统

### 子系统 1：主执行引擎（Core Engine）

**位置**：系统的心脏  
**文件**：`src/query.ts`（约 1,700 行）

**它做什么**：接收用户输入，驱动整个 AI 推理过程。它是一个 `while(true)` 循环：调用 API → 处理工具 → 再次调用 API → … → 最终回答。

**关键组件**：
- `queryLoop()`：主循环函数
- `StreamingToolExecutor`：在模型还在输出时就开始执行工具（并行优化）
- 六层上下文压缩机制：`toolResultBudget` → `snipCompact` → `microcompact` → `contextCollapse` → `autocompact` → `reactiveCompact`，当 token 接近上限时逐步升级压缩力度（详见 Part 4 Ch2「token 是一等公民」）

**和其他子系统的连接**：
- 调用"工具系统"来执行每个工具
- 调用"权限系统"来检查每次工具调用
- 完成后触发"后台任务系统"（SessionMemory、Prompt Suggestion）
- 受"上下文/Prompt 构建系统"提供输入

> 📚 **课程关联**：主执行引擎的 `while(true)` 循环在操作系统课中就是**事件循环**（event loop）——Node.js 的 `libuv` 事件循环、浏览器的消息循环、操作系统内核的调度循环都是同一个模式。差别在于 Claude Code 的循环体是"调用 AI → 执行工具"，而 OS 的循环体是"读取中断 → 执行系统调用"。

---

### 子系统 2：工具系统（Tool System）

**位置**：主执行引擎的执行层  
**文件**：`src/tools/`、`src/Tool.ts`

**它做什么**：管理所有可用工具，执行工具调用，返回结果。

**关键特性**：
- **并发控制**：只读工具（Read、Glob、Grep）可以并行执行；写操作（Edit、Bash）串行执行
- **流式执行**：`StreamingToolExecutor` 在模型输出工具调用时立即开始执行，不等模型停止说话
- **统一接口**：所有工具实现相同的 `Tool` 接口（约 20 个方法/属性）

**工具分类**：

| 类别 | 工具 |
|------|------|
| 文件操作 | Read, Edit, Write, Glob |
| 命令执行 | Bash |
| 搜索 | Grep |
| 网络 | WebFetch |
| AI 协作 | Agent（创建子 Agent） |
| MCP 工具 | `mcp__服务器__工具` 格式 |

> 💡 **通俗理解**：工具系统就像**瑞士军刀**——一把刀上集成了 40 个内置工具目录（剪刀、开瓶器、螺丝刀…），每次只用其中几个。更厉害的是，你还可以通过 MCP 给这把军刀**外接**无限多的配件。读文件、写代码、搜索、跑命令——Claude 能做的一切"动作"，都是通过翻开军刀的某个工具来完成的。

[图表预留 1.4-B：工具并发执行时序图（StreamingToolExecutor 的工作方式）]

---

### 子系统 3：权限系统（Permission System）

**位置**：工具系统的守门人  
**文件**：`src/utils/permissions/`（约 1500 行）

**它做什么**：在每次工具调用前判断是否允许执行。十步状态机，六种权限模式。

**权限模式**（从最严格到最宽松）：

```
plan         → 只读，不允许任何写操作
default      → 遇到不确定时弹窗询问用户
acceptEdits  → 自动接受文件编辑，其他仍询问
dontAsk      → 不询问但遵守规则（子 Agent 内部使用）
auto         → AI 分类器替代用户确认
bypassPermissions → 绕过所有权限（除 bypass-immune 外）
```

**关键设计**：Bypass-Immune 层——在 `bypassPermissions` 模式之前执行，保护 `.git/`、`.claude/` 等路径，任何模式下都无法绕过。

> 📚 **课程关联**：Claude Code 的权限系统映射了操作系统安全课中的**多层访问控制**——十步检查链 = 安全检查管道（security pipeline），bypass-immune = 内核级保护（即使 root 也不能修改），权限弹窗 = `sudo` 提示，Auto 模式的 AI 分类器 = 基于策略的自动访问控制（PBAC）。

[图表预留 1.4-C：权限十步状态机流程图]

---

### 子系统 4：上下文构建系统（Context & Prompt Building）

**位置**：主执行引擎的"进料口"  
**文件**：`src/context.ts`、`src/utils/claudemd.ts`、`src/utils/settings/`

**它做什么**：为每次 API 调用组装完整的 System Prompt，包括：
- CLAUDE.md 内容（从多个目录加载、合并）
- 工具列表和描述
- 用户设置和规则
- 当前 git 状态
- 当前日期和工作目录

**CLAUDE.md 加载顺序**：

```
从当前目录向上遍历到 $HOME
  ↓ 找到的所有 .claude/ 目录中的 CLAUDE.md
收集 → 去重 → 按优先级排序
  ↓ 加入 context 时：越靠后优先级越高
  （利用 LLM 的"注意力偏后"特性）
```

**设置优先级**（从高到低）：
```
企业策略（policySettings）
  ↑
本地设置（localSettings）.claude/settings.local.json
  ↑
项目设置（projectSettings）.claude/settings.json
  ↑
用户设置（userSettings）~/.claude/settings.json
```

> 💡 **通俗理解**：上下文构建系统就像**厨师的备料台**——每次炒菜（调用 API）之前，要把所有食材（CLAUDE.md、工具描述、历史消息、git 状态）摆好。食材摆放顺序有讲究：最不常换的放最里面（系统指令），最常变的放最外面（用户最新消息），这样下次炒菜时里面的食材还能复用（Prompt Cache 命中）。

[图表预留 1.4-D：System Prompt 组装示意图（各来源的叠加关系）]

---

### 子系统 5：Agent 与任务系统（Agent & Task System）

**位置**：工具系统内部的特殊扩展  
**文件**：`src/tools/AgentTool/`、`src/tasks/`

**它做什么**：创建和管理子 Agent（独立的 AI 实例），以及各种后台任务。

**两种运行模式**：

| 模式 | 描述 |
|------|------|
| 本地子 Agent | 在同一进程内运行，共享文件系统 |
| Swarm/Teammate | 多个 Claude 实例协同工作（tmux/iTerm2/in-process 三种 backend） |

**Swarm 架构**：
```
Leader（主 Claude）
  ├── Teammate A（researcher@my-team）
  ├── Teammate B（tester@my-team）
  └── Teammate C（builder@my-team）
```

所有 Teammate 的权限决策都汇聚到 Leader（`leaderPermissionBridge`），Leader 界面是唯一的权限审批入口。

---

### 子系统 6：后台任务系统（Background Services）

**位置**：主执行引擎完成后触发  
**文件**：`src/services/SessionMemory/`、`src/services/PromptSuggestion/`

**它做什么**：在 Claude 完成一轮回答后，在后台运行两个独立的 AI 任务：

**SessionMemory（会话记忆）**：
- 提取本次对话的关键信息
- 写入 `session-memory.md`（9 个固定节）
- 下次打开项目时 Claude 已知道上次做到哪里了

**Prompt Suggestion（提示词预测）**：
- 预测你下一条最可能输入的消息（2-12 个词）
- 驱动"投机执行"（Speculation）提前运行 AI

> 💡 **通俗理解**：后台任务系统就像**秘书的收尾工作**——会议（对话）结束后，秘书不下班：先写会议纪要（SessionMemory），再猜下次会议要讨论什么（Prompt Suggestion）。如果猜得准，下次老板一开口就能直接拿出准备好的材料（投机执行）。

[图表预留 1.4-E：后台任务触发时序图（与主循环的关系）]

---

### 子系统 7：投机执行系统（Speculation System）

**位置**：独立的并行执行轨道  
**文件**：`src/services/PromptSuggestion/speculation.ts`

**它做什么**：利用你阅读 Claude 回答、思考下一步输入的时间，提前运行 AI：

```
Claude 完成回答
  → 预测你最可能输入什么（Prompt Suggestion）
  → 以预测内容为输入，偷偷运行一遍 AI（Speculation）
  → 你按下 Enter
  → 如果你输入的确实是预测内容：结果已就绪，响应时间 ≈ 0
  → 如果不是：丢弃预测，正常处理
```

**关键机制**：Copy-on-Write 覆盖文件系统——投机执行期间的文件操作写入临时 overlay 目录，不影响真实文件；如果预测正确，overlay 合并到主目录；如果预测错误，overlay 被丢弃。

> 💡 **通俗理解**：投机执行就像**餐厅的预制菜升级版**——不仅提前备好半成品，还直接猜你今天要点什么菜，提前炒好端着等。猜对了 = 上菜秒速，零等待；猜错了 = 倒掉重做，损失一盘菜的成本。系统会在你阅读 Claude 回答的那几秒钟里偷偷"猜菜"。

（注：此功能目前仅 Anthropic 内部使用）

> 📚 **课程关联**：投机执行直接借用了计算机体系结构课中 CPU 的**分支预测 + 推测执行**（speculative execution）概念。CPU 在条件分支结果出来之前先猜测走哪条路并提前执行，猜对了 = 零延迟，猜错了 = 回滚（pipeline flush）。Claude Code 的 Copy-on-Write 覆盖文件系统就是"pipeline flush"的软件等价物——预测错误时丢弃所有临时文件改动。

---

### 子系统 8：扩展系统（Extension System）

**位置**：围绕所有其他子系统的外层  
**文件**：`src/utils/plugins/`、`src/utils/hooks/`、`src/services/mcp/`、`src/skills/`

**它做什么**：提供三种不同层次的扩展能力：

**MCP（Model Context Protocol）**：
- 连接外部工具服务器
- 让第三方服务注册新工具
- 6 种传输协议（`TransportSchema` 枚举：stdio / sse / sse-ide / http / ws / sdk）+ 2 种 `McpServerConfigSchema` 配置类型（ws-ide / claudeai-proxy），详见 Part 2 Ch9 §1.2

**Hooks（钩子）**：
- 在系统 27 个事件节点注入自定义逻辑（来源：`src/entrypoints/sdk/coreTypes.ts:25-53` 的 `HOOK_EVENTS` 常量数组，含 `PreToolUse` / `PostToolUse` / `SessionStart` / `SessionEnd` / `PreCompact` / `PostCompact` 等）
- 4 种执行类型（shell 命令/提示词/AI Agent/HTTP）
- 可以阻断操作、修改输入、监听事件

**Plugins（插件）**：
- 打包分发 Commands、Skills、Hooks、MCP 服务器
- 通过 Marketplace 安装
- 三重安全防护（名称白名单、仿冒检测、同形字防护）

[图表预留 1.4-F：扩展系统的三层结构图（MCP/Hooks/Plugins 的关系）]

---

## 与其他 AI 编程工具的子系统对比

> 🌍 Claude Code 并非唯一拥有这些子系统的工具，但在**完整度**上是独特的：

| 子系统 | Claude Code | Cursor | Aider | GitHub Copilot |
|--------|-------------|--------|-------|---------------|
| 主执行引擎 | ✅ while(true) Agent Loop | ✅ Agent Mode | ✅ main loop | ✅ Agent mode |
| 工具系统 | 40 个内置工具目录 + 无限 MCP | ~15 内置 | ~10 | ~10 |
| 权限系统 | 10 步检查链 + 6 种模式 | 简化确认弹窗 | 命令行 --yes 标志 | 沙箱限制 |
| 上下文构建 | 多源 CLAUDE.md + 5 层配置（policy 层内部再细分 4 子来源，详见 Part 2 Ch11 § 1 / Part 3 Ch9 § 1） | .cursorrules + AI rules | .aider.conf + repo map | 编辑器上下文 |
| Agent 嵌套 | 多层子 Agent + Swarm | 单层 multi-step | 无子 Agent | 单层 |
| 后台任务 | SessionMemory + PromptSuggestion | 无 | 无 | 无 |
| 投机执行 | ✅ Copy-on-Write | ❌ | ❌ | ❌ |
| 扩展系统 | MCP + Hooks + Plugins + Skills | Extensions API | 无 | Extensions API |

---

## 八个子系统的关系矩阵

[图表预留 1.4-G：子系统依赖关系矩阵（哪些子系统调用哪些子系统）]

简化版文字描述：

```
主执行引擎  →  工具系统
主执行引擎  →  权限系统
主执行引擎  →  上下文构建系统（接收输入）
主执行引擎  →  后台任务系统（完成后触发）
后台任务系统 → 投机执行系统
工具系统    →  Agent 与任务系统
扩展系统    →  所有其他系统（通过 Hooks 注入、通过 MCP 添加工具）
```

---

## 用这张地图阅读后续章节

每个章节都聚焦于某个子系统内部。当你读到某章时，先问自己：

1. **这个子系统在地图的哪个位置？**
2. **它的上游（输入来自哪里）和下游（输出到哪里）是什么？**
3. **它的存在解决了什么问题？**

这三个问题比理解实现细节更重要。理解了"为什么存在"，实现细节才有意义。

---

## 关键源码入口

八个子系统对应的核心源码入口：

- **子系统 1 · 主执行引擎**：`src/query.ts`（`query()` line 219 / `queryLoop()` line 241，~1,700 行 while(true) Agent Loop）。注：程序启动入口是 `src/main.tsx`（4,684 行，负责 CLI 参数 / REPL 外壳 / 全局初始化），**不等于**主执行引擎本身。
- **子系统 2 · 工具系统**：`src/tools/`（40 个内置工具目录）+ `src/Tool.ts`（工具基类接口）+ `src/tools.ts`（装配链入口）
- **子系统 3 · 权限系统**：`src/utils/permissions/`（权限检查、auto 模式 YOLO 分类器、拒绝追踪）
- **子系统 4 · 上下文构建系统**：`src/utils/claudemd.ts`（CLAUDE.md 加载）+ `src/services/api/claude.ts`（API 调用与 prompt cache）+ `src/utils/context.ts`
- **子系统 5 · Agent 与任务系统**：`src/utils/forkedAgent.ts`、`src/Task.ts`（7 种 TaskType）、`src/utils/coordinatorMode.ts`（Coordinator 提示词）
- **子系统 6 · 后台任务系统**：`src/services/SessionMemory/`（会话记忆）+ `src/services/extractMemories/`（记忆抽取）+ `src/services/autoDream/` + `src/tasks/DreamTask/`（梦境整理）
- **子系统 7 · 投机执行系统**：`src/services/PromptSuggestion/`（下一条用户消息预测）+ query.ts 中的 Speculation 触发逻辑
- **子系统 8 · 扩展系统**：`src/services/mcp/`（MCP 协议）+ `src/utils/hooks.ts` 与 `src/utils/hooks/`（27 个 hook 事件）+ `src/utils/plugins/`（插件系统）+ `src/skills/`（Skill 加载）