# 五分钟看懂系统架构

这章给你一张地图。不求细节，只求方向感。

> 📚 **如果你学过操作系统**：Claude Code 的架构和操作系统有惊人的相似——它有自己的"引导序列"（启动流程）、"系统调用表"（40 个内置工具目录）、"进程调度器"（Agent 编排）、"权限系统"（十步检查链）、"设备驱动接口"（MCP 协议）。本章用 5 分钟给你一个全局视图，后面的 Part 2 会逐一深入每个子系统。

---

## 核心执行路径（从你按下 Enter 到 AI 回答）

```
① 用户输入一条消息
         ↓
② QueryEngine.submitMessage()
   收集系统上下文（git 状态、CLAUDE.md、日期）
         ↓
③ queryLoop()（query.ts）
   核心 while(true) 循环：
   
   ┌─────────────────────────────────────────┐
   │ a. 调用 Anthropic API（stream 模式）    │
   │ b. 流式读取响应                          │
   │    ├── text block → 显示给用户           │
   │    └── tool_use block                    │
   │        └──→ StreamingToolExecutor.addTool│
   │             （立即开始执行，不等模型停止）│
   │ c. 模型停止输出                          │
   │ d. 收集工具执行结果                      │
   │ e. 构建 tool_result 消息                 │
   │ f. 如需上下文压缩，先压缩                │
   │ g. 回到 a，继续下一轮                    │
   └─────────────────────────────────────────┘
         ↓
④ AI 产出最终回答（没有工具调用）
         ↓
⑤ 后台钩子运行：
   SessionMemory 提取、Prompt Suggestion 生成
         ↓
⑥ [可选] Speculation 开始以预测消息执行下一轮
```

---

## 7 个核心抽象

> 🌍 **竞品对比**：Claude Code 的七个抽象（Tool、ToolUseContext、AppState、QueryEngine、Task、Command、SystemPrompt）构成了一个完整的 Agent 运行时。**LangChain** 用更少的抽象（Tool + Agent + Memory）但灵活性更低；**Cursor** 的内部架构没有公开，但从行为看更接近 VS Code 扩展模型；**Aider** 的架构最简——核心只有 Coder + Repo + Model 三个类，没有 AppState 或 Task 的概念。Claude Code 选择了"抽象数量多但每个职责单一"的路线——这增加了学习成本，但让系统的每个部分都可以独立测试和替换。

> 💡 **通俗理解**：从你按下 Enter 到 AI 回答，就像**快递分拣流水线**——收件（用户输入）→ 分拣中心处理（queryLoop 循环：调用 API、执行工具、再调用 API）→ 最终送达（AI 给出回答）。流水线不停转，直到这批快递全部送完。

### Tool — 每个工具的通用接口

```typescript
interface Tool {
  name: string
  call(args, context, canUseTool): AsyncGenerator<ProgressMessage, ToolResult>
  checkPermissions(input, context): Promise<PermissionResult>
  isConcurrencySafe(input): boolean
  isReadOnly(input): boolean
  description(): Promise<string>
  // ... 还有多项方法/属性（完整定义见 src/Tool.ts，以官方仓库为准）
}
```

每个工具（Read、Edit、Bash、AgentTool 等）都实现这个接口。接口定义了工具与系统其他部分的所有交互点：权限、并发、描述、UI 渲染、延迟加载……

### ToolUseContext — 工具执行时的"世界"

```typescript
type ToolUseContext = {
  getAppState(): AppState       // 读取应用状态
  setAppState(updater)          // 修改应用状态
  messages: Message[]            // 当前会话历史
  abortController: AbortController // 可以被取消
  readFileState: FileStateCache  // 文件缓存
  options: QueryOptions          // 模型配置等
}
```

每次工具调用都携带这个上下文。子 Agent 有独立的 `ToolUseContext`，其中 `setAppState` 是 no-op（防止子 Agent 修改父进程状态）。

### AppState — 全局状态快照

系统运行时状态的单一来源，包括：
- 当前权限上下文（`toolPermissionContext`）
- MCP 连接列表（`mcp.clients`）
- 正在运行的任务（`tasks`）
- 投机执行状态（`speculation`）
- 用户设置（`settings`）

通过 React `createStore` 管理（一个仿 Redux 的极简 store），只在主线程的 React 组件树中维护。

### QueryEngine — 会话容器

每个对话 session 有一个 `QueryEngine` 实例，持有：
- 消息历史
- 系统提示词（包括工具列表、git 状态、CLAUDE.md）
- 模型配置
- 提交消息的入口（`submitMessage()`）

### Task — 子 Agent 的代理对象

当一个子 Agent 在运行时，主线程持有一个 `TaskState` 对象（存在 `AppState.tasks` 里），包含 Agent 的状态、输出流、取消控制器等。

### Command — 斜杠命令

用户输入 `/commit`、`/help` 等斜杠命令时触发。不同于工具（工具由 AI 调用），命令由**用户直接调用**，有独立的处理路径。系统内置命令众多（详见 `src/commands/` 目录，具体数量以官方仓库为准）。

### SystemPrompt — 发给 AI 的完整上下文包

不是一个字符串，而是一个结构化对象，包括：
- 工具描述列表
- 用户上下文（CLAUDE.md、当前日期）
- 系统上下文（git 状态）
- Coordinator 提示词（如果是协调者模式）

---

## 三个层次的权限控制

```
层次 1：规则（静态配置）
  always-allow / always-deny / always-ask
  来自 settings.json、CLAUDE.md 配置

层次 2：工具自检（动态）
  每个工具的 checkPermissions() 检查当前输入
  如：FileEditTool 检查路径是否在 .git/ 等敏感目录

层次 3：用户确认（交互）
  如果以上都没有明确答案，弹出确认对话框
  在 auto 模式下，由 AI 分类器替代用户确认
```

---

## 两种工具执行模式

**传统路径（`runTools`）**：
等 AI 完全停止输出 → 按并发安全性分批 → 执行（只读工具并行，写操作串行）

**流式路径（`StreamingToolExecutor`）**：
AI 每输出一个完整的 tool_use block → 立即开始执行
模型停止输出时，大多数工具已经完成

> 📚 **课程关联**：传统路径是经典的**批处理**（batch processing），流式路径是**流处理**（stream processing）——和大数据课程中 MapReduce（批处理） vs Apache Flink（流处理）的对比完全对应。流式路径的核心价值是**降低延迟**：不等所有数据到齐再处理，而是数据到一条就处理一条。

---

## 上下文压缩的六层防御

> 💡 **通俗理解**：六层压缩就像**会议记录员的分级处理策略**——先折叠超长附件 → 再删无用页面 → 再去重复内容 → 再做段落摘要 → 再做全文精华版 → 最后紧急压缩。从轻到重，绝大多数时候前三步就够了。

（详见 Q02 章节）

```
token 消耗：─────────────────────────────────────→
           toolResultBudget → snipCompact → microcompact
           → contextCollapse → autocompact → reactiveCompact
```

每一层在不同的 token 消耗阈值触发，逐步从"丢弃工具结果"到"完整对话摘要"。

---

## 你最需要知道的一个事实

**这个系统的每个设计决策，都在试图回答同一个问题：**

> 如何让 AI 在真实工程任务中可靠、高效、安全地工作？

所有的复杂性——多层权限、流式并行、上下文压缩、投机执行——都是对这个问题某个维度的回答。

当你看到代码里某个"为什么要这样"的地方，先问自己：它在解决哪个维度的问题？

---

## 关键源码入口

- `src/main.tsx`：启动入口——Pre-import 预加载 + 初始化序列 + React 渲染
- `src/query.ts`：查询循环核心——`query()` 函数（line 219）调用 `queryLoop()`（line 241）驱动 Agent Loop
- `src/tools.ts`：工具注册表——40 个内置工具目录的统一注册
- `src/utils/permissions/permissions.ts`：权限系统——10 步状态机的完整实现

## 行业共识框架：Model + Runtime + Harness

> 📚 **行业共识框架：Model + Runtime + Harness**
>
> LangChain 创始人 Harrison Chase 提出了一个被行业广泛接受的三层共识框架：
> - **Model 层**（大脑）— 底层大模型能力（Claude, GPT, Gemini...），负责"思考"
> - **Runtime 层**（神经系统）— 调用编排、工具路由、上下文管理，负责"传递信号"
> - **Harness 层**（身体 + 五官 + 四肢）— 面向用户的完整产品体验，负责"感知环境并执行动作"
>
> 💡 **通俗理解**：就像同样的引擎（Model）装在不同的车架（Harness）上，会变成跑车、卡车或救护车一样——Claude Code、Cursor、Windsurf 用的是同一个 Claude 大脑，但它们的"车架"设计完全不同，这才决定了各自的使用体验。本书拆解的，正是 Claude Code 这辆车的"车架"是怎么造出来的。

对照本章介绍的七个核心抽象，你会发现它们几乎全部落在 Harness 层：Tool 接口定义了用户可感知的工具能力边界，QueryEngine 编排了用户体验的核心循环，AppState 管理了产品级别的全局状态，权限系统塑造了用户的安全感知。Model 层（Claude 模型本身）和 Runtime 层（API 调用、流式传输）在本章只是"管道"——真正的工程复杂度和产品差异化，都在 Harness 层。

---

## 这张地图的局限

然而，五分钟的概览不可避免地有局限。这张地图省略了大量边界情况和权衡——比如流式工具执行在网络不稳定时的回退策略、上下文压缩可能丢失关键信息的风险、以及 Auto 模式下 AI 分类器可能做出错误权限判断的问题。如果你只读了这一章就觉得"我懂了"，那恰恰说明你还需要继续往下读。复杂性不在主流程里——它藏在异常路径、并发冲突和安全边界中。