# 读懂本书需要的全部概念

> 这一章是你进入后续所有内容的"通关证"。如果你在某个章节感到困惑，回到这里找定义。如果你想快速了解某个术语，这里是索引。

> **🌍 行业背景**：AI Agent 框架正在快速形成自己的术语体系。LangChain 有 Chain/Agent/Tool/Memory 四大抽象，AutoGPT 有 Task/Action/Plugin，CrewAI 有 Agent/Task/Crew。Claude Code 的概念体系（Tool/Agent/Session/Hook/MCP）与这些框架有交叉但不完全对应——例如 Claude Code 的 "Hook" 更接近 Webpack 的 plugin tapable 系统而非 LangChain 的 callback。本章帮你精确理解 Claude Code 的术语，避免从其他框架带来的错误对应。

---

## 阅读说明

Claude Code 是一个有 **1,884 个 TypeScript 文件** 的工程系统。它包含大量内部术语，很多术语和"Claude"（AI）这个词本身高度交织，容易混淆。

本章的目标不是让你记住所有概念，而是：
1. 让你建立一个**心智地图**，知道这个系统有哪些"房间"
2. 让你知道**哪个词指什么**，不被术语绊倒
3. 帮你理解各概念之间的**层级和从属关系**
4. 给你一套**比喻对照表**，用你已经懂的东西理解你还不懂的

> 📚 **给学生读者的桥接**：如果你学过操作系统、计算机网络或软件工程，本书的很多概念都有课程对应物。本章在每个核心概念旁标注了 📚 课程关联，帮你把工业界的实践和课堂的理论连起来。你会发现，Claude Code 的架构就是你学过的那些理论在真实产品中的工程化落地。

---

## 核心比喻：Claude Code 是一个操作系统

在深入术语之前，先建立一个总体的直觉框架。

你大概了解操作系统（Windows、macOS、Linux）是什么：它管理硬件资源（CPU、内存、磁盘），调度应用程序（进程），执行安全策略（用户权限），提供扩展机制（驱动程序、包管理）。

Claude Code 做着**几乎完全相同的事**——只不过它管理的不是硬件，而是 **AI 智能体**：

| 你熟悉的 OS 概念 | Claude Code 对应物 | 一句话解释 |
|---|---|---|
| 内核 (Kernel) | QueryEngine + queryLoop | 调度一切的核心循环 |
| 系统调用 (Syscall) | 工具调用 (Tool) | AI 访问外部世界的唯一方式 |
| 进程 (Process) | Agent | 一个独立运行的 AI 实例 |
| 进程调度器 (Scheduler) | Task 系统 | 管理多个并发 AI 实例 |
| 文件系统 (Filesystem) | JSONL 会话 + File History | 持久化存储 |
| 安全模型 (Security) | 权限系统 + 沙箱 | 多层访问控制 |
| 设备驱动 (Driver) | MCP 服务器 | 标准化的外部工具接口 |
| Shell | REPL 终端界面 | 用户和"内核"的交互层 |
| /etc/ 配置 | 设置系统（九层）| 系统配置管理 |
| 环境变量 | System Prompt | 进程启动时的上下文信息 |
| 内核模块 (Module) | Hooks | 在关键节点注入自定义逻辑 |
| 包管理器 (apt/npm) | 插件系统 + Skills | 第三方扩展机制 |
| 共享内存 (IPC) | Scratchpad | Agent 间通信 |
| 开机引导 (Boot) | main.tsx → init.ts | 系统启动序列 |

**在后续章节中，当你遇到一个不熟悉的 Claude Code 概念，试着在这张表里找到它对应的 OS 概念——你可能立刻就懂了。**

> 💡 **不熟悉操作系统也没关系！** 本书还会在每个概念首次出现时提供日常生活的通俗比喻。比如"内核"你可以想成"快递分拣中心"，"系统调用"可以想成"员工的技能证书"，"权限系统"可以想成"小区门禁"——这些日常比喻会帮助你建立直觉，即使你从未学过计算机科学。

---

## 第一层：最核心的五个概念

> 理解这五个概念，就理解了系统的骨架。

### 1. Tool（工具）

**最短定义**：AI 可以调用的一种能力。

每当 Claude 说"我要读这个文件"或"我要执行这个命令"，它实际上是在调用一个 Tool。系统内置 **40 个内置工具目录**，外加无限数量的 MCP 外部工具。

| 工具 | 作用 | OS 类比 |
|------|------|---------|
| `Read` | 读取文件 | `read()` 系统调用 |
| `Edit` | 编辑文件（差分替换） | `write()` 到特定偏移量 |
| `Write` | 创建/覆盖文件 | `creat()` + `write()` |
| `Bash` | 执行 Shell 命令 | `exec()` |
| `Agent` | 创建子 Agent | `fork()` |
| `WebFetch` | 抓取网页 | `connect()` + `recv()` |
| `Glob` | 按文件名搜索 | `glob()` |
| `Grep` | 按内容搜索 | `grep` 命令 |

**关键理解**：
- 工具不是 Claude 自己执行的——Claude 发出"我要调用 X 工具"的**请求**，本地系统来**执行**，结果返回给 Claude
- Claude 运行在远端服务器上，根本**触不到你的电脑**——工具是它和你的文件系统之间唯一的桥梁
- 每个工具调用都经过**权限检查**——不是 Claude 想调就能调

> 💡 **通俗理解**：工具就像**员工的工作技能证书**——读文件证书、写代码证书、搜索证书。Claude 想做一件事，必须先出示对应证书（工具调用），然后经过考核（权限检查），通过了才能动手。

> **[图表预留 1.3-A]**：Tool 调用循环图 — AI 请求 → 权限检查 → 系统执行 → 结果返回 → AI 继续

---

### 2. Query Loop（主循环）

**最短定义**：从你按下 Enter 到 Claude 完成回答的整个处理过程。

这是系统的心脏，代码在 `query.ts` 里，是一个 `while(true)` 循环：

```
你的输入 → API 调用 → Claude 说话（可能包含工具调用）
  → 工具被执行 → 结果返回 → API 调用 → Claude 继续说话
  → ... → Claude 最终回答（不再调用工具） → 循环结束
```

**比喻**：心脏的收缩（调用 API）和舒张（处理工具结果）。每一次"心跳"是一轮 API 调用。当 Claude 不再调用工具时，心脏停止跳动，这轮对话结束。

> 💡 **通俗理解**：Query Loop 就像**快递分拣流水线**——收件 → 分拣 → 装车 → 送达 → 签收 → 等下一单。每轮循环就是处理一批快递，直到所有快递都送完（没有更多工具调用），流水线才停。

**关键理解**：
- 一次"回答"可能包含 5 次、10 次、20 次工具调用——用户看到的"最终回答"是**很多轮循环**之后的结果
- 循环是一个 **AsyncGenerator**——不是一次性返回结果，而是持续输出事件流，调用者可以实时处理
- 循环有**六种退出条件**：正常结束、达到最大轮次、用户中断、context 满了、API 错误、图片错误

---

### 3. Agent（智能体/代理）

**最短定义**：一个运行着自己的 Query Loop 的独立 AI 实例。

当 Claude 需要把一个子任务委托给另一个 AI 实例时，它调用 `Agent` 工具，创建一个子 Agent。子 Agent 有自己的 Query Loop，自己的工具调用历史，完成任务后把结果返回给父 Agent。

```
主 Agent（你的对话）
  ├── 子 Agent A（被委托：分析这个文件夹）
  │     └── 子子 Agent（被委托：分析这个文件）
  └── 子 Agent B（被委托：运行测试）
```

**比喻**：
- 主 Agent 是**经理**——接收你的请求，决定分配给谁
- 子 Agent 是**员工**——各自领一个任务，独立执行
- OS 类比：Agent = 进程，主 Agent 调用 `Agent` 工具 = `fork()` 创建子进程

**关键区别**：
- **主 Agent**：响应你输入的那个 Claude，在主界面运行
- **子 Agent**：被主 Agent 创建的，在后台运行，完成后消失
- **Coordinator**：特殊模式下的主 Agent——它不直接做任务，只负责分配和综合（像公司的 CEO）

> 💡 **通俗理解**：Agent 就像**派出去的外卖骑手**——主 Claude 是调度中心，每个 Agent 是一个骑手，各自独立送不同订单，完成后回报结果。Coordinator 模式就是调度中心自己不送餐，只负责分配订单和汇总反馈。

> 📚 **课程关联**：Agent 的多层嵌套结构（主 Agent → 子 Agent → 子子 Agent）就是操作系统课中**进程树**（process tree）的直接映射。`Agent` 工具 = `fork()` 系统调用，`Coordinator` 模式 = init 进程（PID 1，只管理子进程不做业务），`Swarm` 模式 = 分布式系统课中的 **Leader-Worker 架构**。

**七种 Agent/任务类型**：

| 类型 | 隔离级别 | 比喻 |
|------|---------|------|
| `local_agent` | 独立消息历史，共享进程 | 同一办公室的不同工位 |
| `in_process_teammate` | 共享进程和连接 | 同一张桌子上的不同人 |
| `remote_agent` | 完全独立的机器 | 在另一个城市的远程团队 |
| `local_bash` | 独立子进程 | 外包给 Shell 的单次任务 |
| `local_workflow` | 本地工作流 | 按步骤执行的自动化脚本 |
| `monitor_mcp` | MCP 监控 | 盯着外部服务的哨兵 |
| `dream` | 未确认 | — |

> **[图表预留 1.3-B]**：Agent 层级树状图 — 主 Agent → 子 Agent → 子子 Agent，标注隔离级别

---

### 4. Session（会话）

**最短定义**：一次完整的对话，从你打开 Claude Code 到关闭（或清空）。

Session 有唯一 ID（UUID），对话历史被保存在磁盘上（`~/.claude/projects/` 目录），以 **JSONL** 格式存储——每行一个 JSON 对象。

**Session 包含的内容**：
- 完整的消息历史（你说的 + Claude 说的 + 工具调用记录）
- 权限决策历史（本次会话里允许了哪些操作）
- 文件变更记录（`/rewind` 需要这个）

**比喻**：Session = 一本流水账本。每笔"交易"（消息/工具调用/结果）写一行，永远只往后写。本子存在磁盘上，关掉终端后还在。

**关键理解**：
- Session 是**持久化在磁盘上**的——这使得 `/resume`（恢复对话）、`/branch`（分支对话）、`/rewind`（回滚）成为可能
- JSONL 格式是**追加友好**的——崩溃时最多丢失最后一行，不会破坏整个文件
- 一个 Session 可能持续几分钟也可能持续几小时——长 Session 需要上下文压缩来管理 token 量

---

### 5. Context Window（上下文窗口）

**最短定义**：Claude 在单次 API 调用里能"看到"的最大信息量，以 token 为单位。

**Token** 是 AI 处理文本的基本单位，大约等于 3/4 个英文单词，或 1-2 个中文字符。每个 Claude 模型都有一个上下文窗口的最大值（如 200,000 tokens）。

> 💡 **直觉化换算**：1,000 token ≈ 750 个英文单词 ≈ 500-600 个中文字 ≈ 一页 A4 纸的内容。200,000 token 的上下文窗口 ≈ 一本 10-15 万字的中篇小说。以 Anthropic 官网公开的 Sonnet 量级定价估算（具体数字以 https://www.anthropic.com/pricing 为准，本段按 Sonnet 价格、下文"Token"表按 Opus 4.6 价格，注意区分）：每 1,000 个输入 token 约 $0.0003（缓存命中）到 $0.003（未缓存），每 1,000 个输出 token 约 $0.015。通俗地说：读一页 A4 花不到一分钱，但让 AI 写一页可能要几分钱——缓存命中比未缓存便宜约 10 倍。

**比喻**：Context Window = 计算机的 RAM。程序运行时的数据必须在 RAM 中——如果数据太多，就得把不常用的换出（swap）到磁盘。Claude Code 的上下文压缩机制就是这个"swap"。

**六套压缩机制**（从轻到重）：

| 层级 | 机制 | 比喻 |
|------|------|------|
| 1 | 工具结果大小裁剪 (toolResultBudget) | 把大件行李折叠 |
| 2 | 历史片段剪裁 (snipCompact) | 撕掉日记里无关的页面 |
| 3 | 微压缩 (microcompact) | 删掉文档里的废话 |
| 4 | 上下文折叠 (contextCollapse) | 把三个月的日记压缩成一段摘要 |
| 5 | 自动全文压缩 (autocompact) | 用真空袋把所有行李重新打包 |
| 6 | 响应式紧急压缩 (reactiveCompact) | 行李箱超重被拒——紧急重新打包 |

> 前五层在每次 AI 调用**之前**依次执行（99% 情况下前三层就够了）。第六层是**事后补救**——当 API 返回 413 错误（上下文超限）时才触发。如果连紧急压缩也无法解决，对话才真正终止。

**关键理解**：Context Window 是**稀缺资源**。系统的很多设计决策（6 层压缩、token 预算控制、工具描述字符限制、延迟加载工具）都是在管理这个有限资源。

> 📚 **课程关联**：Context Window 的管理本质上就是操作系统课中的**内存管理**——200K token 的上限 = 物理内存大小，六层压缩 = 多级页面置换算法，`autocompact` = 内存紧凑化（memory compaction），`reactiveCompact`（413 错误触发）= OOM Killer（内存耗尽时的紧急措施）。理解了 OS 的内存管理，Claude Code 的上下文管理就一点不神秘。

---

## 第二层：理解系统运行的关键概念

> 这些概念在各章节反复出现，理解它们能让你读得顺畅。

### Token（词元）

AI 文本处理的基本单位。本书中常见的四种说法和它们的"水价"：

> 💡 **通俗理解**：Token 就像**手机话费**——打电话 = 输出 token 计费（最贵），接电话 = 输入 token 计费，套餐内通话 = 缓存读取（便宜很多），超出套餐 = 全价计费（贵）。每次和 Claude 对话都在"打电话"，精打细算话费是整个系统的核心关注点。

| 类型 | 含义 | 成本（Opus 4.6）| 比喻 |
|------|------|----------------|------|
| Input tokens | 发给 Claude 的文本 | $15/百万 | 自来水 |
| Output tokens | Claude 生成的文本 | $75/百万 | 纯净水（贵 5 倍）|
| Cache read tokens | 命中缓存的输入 | $1.5/百万 | 中水回用（便宜 10 倍）|
| Cache write tokens | 写入缓存的输入 | $18.75/百万 | 建水库（前期投入）|

**记住这个 10 倍差距**：缓存命中的 token 比普通 token 便宜 10 倍。系统中大量设计决策都在追求缓存命中率。

### Prompt Cache（提示词缓存）

Anthropic API 的特性：如果两次请求的**前缀完全相同**（逐 token 比较），重复部分不需要重新处理。

**比喻**：每天给同一个人写信。信的开头（"亲爱的张三"）每次都一样。如果邮局记住了这个开头，你只需要寄新写的部分。

> 💡 **通俗理解**：Prompt Cache 就像**餐厅的预制菜**——常点的菜提前备好半成品（缓存），只炒最后一步（只处理变化部分），大幅节省时间和成本。每次点同样的菜就不用从头做起。

系统的提示词组装顺序（最稳定的在前、最可能变化的在后）就是为了**最大化这个缓存命中**。

> 📚 **课程关联**：Prompt Cache 的工作原理就是计算机体系结构课中的**前缀匹配缓存**——类似 CPU 的 L1/L2 缓存通过地址前缀标签（tag）匹配，Prompt Cache 通过 token 序列前缀匹配。缓存命中（cache hit）= 10% 成本，缓存未命中（cache miss）= 100% 成本。系统的提示词组装策略（稳定内容在前、变化内容在后）就是为了最大化命中率——和 CPU 的**空间局部性**（spatial locality）优化原理一致。

### System Prompt（系统提示词）

发给 Claude 的"背景信息包"，包含：角色定义、工具列表、CLAUDE.md 内容、当前日期、git 状态、用户自定义规则。

> 💡 **通俗理解**：System Prompt 就像**新员工入职手册**——公司规章（系统指令）+ 岗位职责（工具描述）+ 个人备忘（CLAUDE.md）+ 老板的特别嘱咐（用户自定义追加）。每次 Claude "上班"都要翻一遍这本手册。

**关键理解**：System Prompt 是**每次 API 调用的固定成本**——不管你说什么，每次都要付这 15,000-34,000 token 的"税"。

### CLAUDE.md

用 Markdown 写的"指令文件"，告诉 Claude 关于你的项目的规则和约定。有六种来源：

| 类型 | 位置 | 提交 git？ | 优先级 |
|------|------|-----------|--------|
| Project | `.claude/CLAUDE.md` | ✅ | 中 |
| Local | `.claude/CLAUDE.local.md` | ❌ | 中 |
| User | `~/.claude/CLAUDE.md` | — | 低 |
| Managed | 企业策略路径 | — | 高 |
| Upstream | 父目录的 CLAUDE.md | ✅ | 中 |
| Workspace | 工作区根目录 | ✅ | 中 |

### Permission（权限）

控制 Claude 是否可以执行某个工具调用的机制。**十步检查链**产生三种结果：

| 结果 | 含义 | OS 类比 |
|------|------|---------|
| Allow | 允许，直接执行 | `rwx` 权限通过 |
| Ask | 需要用户确认 | `sudo` 提示输入密码 |
| Deny | 拒绝 | Permission denied |

**六种权限模式**：default（日常）、plan（只规划不执行）、auto-approve（自动批准）、bypassPermissions（绕过）、apiServerMode（API 模式）、headless（无头模式）。

### Hook（钩子）

在系统生命周期的特定时刻执行用户自定义命令的机制。系统有 **27 个**事件节点。

**比喻**：高速公路上的收费站。车（工具调用）经过时，收费站（Hook）可以检查、放行、或拦截。

> 💡 **通俗理解**：Hooks 就像**快递柜的短信通知**——快递到了自动通知你 = 事件钩子。你可以设置"到了通知我"或"直接放门口" = 自定义 Hook 行为。退出码 2 就像通知你"快递有问题，已拦截退回"。

关键：退出码 **2** = 阻塞（拦截操作），其他非零 = 只记录错误但不拦截。

### MCP（Model Context Protocol）

第三方工具扩展标准。外部服务器注册新工具，格式为 `mcp__服务器名__工具名`。

**比喻**：USB 协议。任何厂商只要按协议做设备，就能插到任何电脑上。MCP 服务器只要按协议实现，就能接入任何支持 MCP 的 AI 系统。

> 💡 **通俗理解**：MCP 就像**MacBook 的 USB 转接口**——MacBook 只有 Type-C 口，想接鼠标、键盘、投影仪都需要转接器。MCP 就是 Claude 的万能转接器，让它能连接任何外部工具和服务。

### Sandbox（沙箱）

OS 级别的进程隔离。限制 AI 调用的命令能访问的文件、网络和系统资源。

**比喻**：气闸室。航天器内部（你的系统）是安全的，外太空（不受信任的代码）是危险的。沙箱是中间的气闸——允许有限的操作，但隔离危险。

| 平台 | 技术 |
|------|------|
| macOS | seatbelt profile |
| Linux | bubblewrap + seccomp |

### Settings（设置系统）

**九层配置**，从企业策略到用户偏好。高优先级覆盖低优先级。

**比喻**：俄罗斯套娃。最外层（企业策略）决定最大范围，每个内层只能在外层允许的范围内调整。

> 💡 **通俗理解**：配置系统就像**穿衣服的层次**——贴身内衣 = 默认配置 → 衬衫 = 项目配置 → 外套 = 用户配置 → 防弹衣 = 企业策略。外层覆盖内层，但防弹衣最高优先级，你没法把它脱掉。

---

## 第三层：内部代号和特殊名称

> 这些是代码里出现的内部名称，不是用户界面的词汇。理解它们有助于读懂技术细节章节。

| 代号 | 含义 | 出现在 |
|------|------|--------|
| `tengu` | Claude Code 的内部项目代号 | 函数名、分析事件、Feature flag |
| `queryLoop` | AI 主循环 | query.ts |
| `AppState` | 全局状态对象 | state/AppStateStore.ts |
| `ToolUseContext` | 工具执行时的上下文 | Tool.ts |
| `querySource` | "谁发起了这次 AI 调用" | 区分主 Agent/子 Agent/投机执行 |
| `forkedAgent` | 从父请求派生的 AI 实例 | 共享 Prompt Cache |
| `speculation` | 投机执行 | 在用户打字时提前运行 AI |
| `omitClaudeMd` | 跳过 CLAUDE.md 加载 | 只读子 Agent 的优化 |
| `CacheSafeParams` | 保证缓存命中的参数约束 | 编译时类型检查 |
| `bypass-immune` | 不可绕过的安全限制 | 权限系统 |
| `iron gate` | 自动模式的安全阀 | 连续拒绝 → 强制人工审批 |
| `ant` | Anthropic 员工版本 | 部分功能仅 ant 版可用 |
| `tungsten` | tmux 集成代号 | Swarm 模式后端 |
| `bagel` | Web 浏览器工具代号 | 内部工具 |
| `chicago` | Computer Use 代号 | MCP 服务器 |
| `amber_quartz` | Voice 模式代号 | Feature gate |
| `cobalt_harbor` | 自动连接代号 | MCP 自动发现 |
| `sage_compass` | Advisor 系统代号 | GrowthBook gate |
| `friend-2026-401` | Buddy 系统代号 | 2026 愚人节发布 |

---

## 第四层：系统的层级关系

> 理解"谁包含谁"、"谁调用谁"，是理解系统设计的基础。

### 从大到小

```
Claude Code 进程
  └── AppState（全局状态）
        ├── 主 Session
        │     ├── Query Loop（主循环）
        │     │     ├── API 调用 × N
        │     │     ├── 工具调用 × M
        │     │     └── 压缩检查
        │     ├── 子 Agent × P
        │     │     └── Query Loop（子循环）
        │     ├── 投机执行 Agent（后台）
        │     └── SessionMemory Agent（后台）
        ├── MCP 连接 × Q
        ├── Hook 注册表
        ├── 文件历史快照
        └── Buddy 小动物
```

### 从调用者到被调用者

```
用户输入
  → REPL 界面（React + Ink）
      → QueryEngine.submitMessage()
          → 组装系统提示词（fetchSystemPromptParts）
          → queryLoop()
              → callModel()（Anthropic API）
                  → 流式响应
              → StreamingToolExecutor（流式阶段并行）
                  → Tool.call() × N
                      → 可能创建子 Agent
                          → 递归的 queryLoop()
              → 收集 tool_result
              → 再次 callModel()
              → ... 直到最终回答
          → PostSamplingHooks
              → SessionMemory 提取
              → Prompt Suggestion 生成
          → fileHistoryMakeSnapshot()
      → [可选] 投机执行启动
```

> **[图表预留 1.3-C]**：完整系统调用栈图

### 数据流的三条高速公路

1. **主链路**：用户输入 → queryLoop → API → 工具执行 → 最终回答 → 渲染
2. **后台链路**：AI 回答后 → SessionMemory + PromptSuggestion + FileHistory + Speculation
3. **扩展链路**：MCP 服务器连接 → 工具注册 → 插件/Skill/Hook 加载

---

## 第五层：常见混淆辨析

> 这些概念容易被混淆，提前澄清省很多困惑。

### Agent vs Tool

| | Agent | Tool |
|--|-------|------|
| 是什么 | 一个完整的 AI 实例 | 一种能力 |
| 有 queryLoop 吗 | ✅ | ❌ |
| 有自己的消息历史吗 | ✅ | ❌ |
| OS 类比 | 进程 | 系统调用 |
| 关系 | `Agent` 是一种**特殊的 Tool** | Tool 是 Agent 调用的能力 |

### Hook vs Tool

| | Hook | Tool |
|--|------|------|
| 谁触发 | 系统自动触发 | AI 主动调用 |
| 目的 | 在关键节点注入逻辑 | 执行操作 |
| OS 类比 | 内核模块 | 系统调用 |
| 能阻止操作吗 | ✅（退出码 2）| ❌ |

### Session vs Context Window

| | Session | Context Window |
|--|---------|---------------|
| 存在哪 | 磁盘（JSONL 文件）| 内存（API 请求体）|
| 大小限制 | 无（磁盘空间）| ~200K token |
| 生命周期 | 持久的 | 每次 API 调用重建 |
| 关系 | Session 可能远大于 Context Window | — |
| OS 类比 | 硬盘上的文件 | RAM 中的数据 |

### Skill vs Command

| | Skill | Command |
|--|-------|---------|
| 谁触发 | AI 自主决定 **或** 用户 `/<name>` | 只能用户 `/xxx` |
| 关键字段 | `whenToUse` 描述 | 无 |
| OS 类比 | Shell 脚本（可被 cron 自动执行）| 手动执行的命令 |

### Plugin vs MCP

| | Plugin | MCP |
|--|--------|-----|
| 是什么 | 功能包（可含多种组件）| 外部工具协议 |
| 能包含什么 | 工具 + Skills + Hooks + MCP 配置 + 命令 | 只提供工具 |
| 关系 | Plugin 可以包含 MCP 配置 | MCP 是 Plugin 的一种组件 |
| OS 类比 | apt 包（可含多个程序）| USB 设备驱动 |

### Prompt Cache vs Context Compression

| | Prompt Cache | Context Compression |
|--|-------------|-------------------|
| 做什么 | 复用之前请求的前缀 | 缩减消息历史的大小 |
| 效果 | 降低成本和延迟 | 延长对话寿命 |
| 代价 | 需要保持前缀稳定 | 丢失部分信息 |
| 关系 | 压缩会**破坏**缓存（因为改写了消息） | — |
| 设计冲突 | 这两者是**互相矛盾**的——系统在两者间寻找平衡 | — |

> 🌍 **竞品的不同选择**：不同 AI 编程工具对这些概念做了不同的取舍。**Aider** 用 "repo map"（仓库地图）代替大量的上下文压缩——预先只加载相关函数签名，而非全部加载后压缩。**Cursor** 的 Agent 没有多层子 Agent 嵌套，而是单层的 "multi-step"（多步执行）。**GitHub Copilot** 的工具集远小于 Claude Code（约 10 个 vs 40 个内置工具目录），侧重代码补全而非全能 Agent。这些不同选择反映了"简单但受限" vs "复杂但灵活"的经典工程权衡。

### QueryEngine vs query()

| | QueryEngine | query() |
|--|-------------|---------|
| 是什么 | 会话级门面（facade，软件设计模式术语，指"对外统一入口"） | turn 级状态机（state machine，像红绿灯一样在几种固定状态之间按规则切换） |
| 职责 | 整理一次提交（收集消息、检查会话上下文、调用 `ask()`） | 运行单轮循环（调模型→解析→执行工具→判断是否继续） |
| 生命周期 | 跟随会话 | 跟随单次 query 调用 |
| OS 类比 | 前台接待员（收件、登记、分流） | 后厨主厨（接单→烹饪→出菜→看是否还有下一道） |
| 常见误解 | ❌ "QueryEngine 是执行引擎" | ❌ "query() 管整个会话" |
| 源码 | `QueryEngine.ts` | `query.ts`（核心循环在 `queryLoop()`） |

> 💡 **通俗理解**：QueryEngine 是快递公司的"客服前台"，负责接单、核实地址、安排派送。query() 是那个真正骑着电动车跑腿送货的快递员——每跑一趟（一次 turn）包括取件、送达、客户签收、看还有没有下一单。

### Tool vs Task

| | Tool | Task |
|--|------|------|
| 是什么 | 一种能力（做什么） | 一个托管容器（怎么管理生命周期） |
| 关注点 | 执行逻辑、权限检查、结果格式化 | 状态保存、前后台切换、停止/恢复 |
| 生命周期 | 一次调用 | 可能跨越多次 turn |
| 关系 | Tool 是"做事的手"，Task 是"管手的经理" | Task 通过 `query()` 间接使用 Tool |
| OS 类比 | 系统调用（read/write） | 进程控制块（PCB） |

### subagent vs teammate

| | subagent | teammate |
|--|----------|----------|
| 创建方式 | AgentTool.call() → fork/local | Swarm Leader 分配 |
| 通信 | 通过 generator 链返回结果（generator = 生成器，结果像流水线一节一节传过来，而不是等全部完成才一起返回） | 通过 Mailbox 文件系统异步通信（Mailbox = 邮箱，一个真实的文件目录，teammate 之间靠读写这个目录里的文件来互相传消息） |
| 协作协议 | 简单（调用-返回） | 复杂（idle = 还没开工 / plan approval = 等审批 / shutdown = 干完关机，三种协调信号） |
| 隔离 | 共享内核或 git worktree（git worktree = git 的多目录 checkout 功能） | 独立终端进程（tmux / iTerm2 / in-process 都是终端复用工具，让多个 AI 实例各自占一个窗格） |
| OS 类比 | 子进程 | 分布式计算节点 |

### bridge vs remote vs teleport

| | bridge | remote | teleport |
|--|--------|--------|----------|
| 职责 | 本地暴露：让 Web/手机 attach 到本地会话 | 远端执行：把工作送到云端 CCR 运行 | 恢复协议：crash 后接回会话 |
| 方向 | 外→内（远端观察本地） | 内→外（本地推给远端） | 时间维度（断点续传） |
| 关键文件 | `replBridge.ts` | `RemoteAgentTask.tsx` | `bridgePointer.ts` |
| OS 类比 | SSH 服务端 | 远程 Job 提交（slurm） | 断电后的 session 恢复（tmux attach） |

> 💡 **通俗理解**：bridge 是你家装的远程摄像头（外面看家里），remote 是你派保姆去别人家干活（自己看进度），teleport 是停电来了保存游戏存档、来电后从存档继续。

### tool pool vs 工具注册表

| | tool pool | 工具注册表 |
|--|-----------|-----------|
| 是什么 | 当前回合模型可见的工具子集 | 系统所有已注册工具的完整列表 |
| 大小 | 动态变化（取决于权限模式、feature gate、MCP 状态） | 相对固定（40 个内置工具目录 + MCP 动态） |
| 构建 | `assembleToolPool()` 每次 query 调用时重新装配 | `getAllBaseTools()` 启动时注册 |
| OS 类比 | 当前进程可用的系统调用表 | 内核的完整系统调用表 |

### feature() vs GrowthBook

| | feature() | GrowthBook |
|--|-----------|------------|
| 类型 | 编译期门控 | 运行时实验 |
| 何时判断 | 构建时由 Bun bundler 裁剪 | 运行时从远端拉配置 |
| 可回退 | ❌ 需要重新构建 | ✅ 秒级远端翻转 |
| 用途 | 裁掉未发布功能的死代码 | A/B 测试、灰度发布、紧急 killswitch |
| 源码 | `feature('BUDDY')` 等字面量 | `GrowthBook.isOn()` / `GrowthBook.getPayload()` |

### viewerOnly vs "只读"

| | viewerOnly | "只读" |
|--|------------|--------|
| 关掉了什么 | 控制端语义（interrupt、watchdog、title ownership） | 全部写操作 |
| 保留了什么 | 消息收发、权限处理、tool_result 渲染、点赞/反馈 | 只有读取 |
| 本质 | **角色重定义**——从"操控者"变成"观察+轻交互者" | 简单的权限禁用 |
| 依赖 | `useAssistantHistory()` + `useRemoteSession()` 双数据源 | 单一数据源 |

---

## 第六层：数量级感知

> 对系统规模有正确的数量级感知，比记住精确数字更有价值。

| 维度 | 数值 | 感知 |
|------|------|------|
| TypeScript 文件数 | ~1,884 | 大型项目（VS Code ~3,000） |
| 内置工具目录数 | 40 | `src/tools/` 下 40 个工具子目录（排除 shared/ 与 testing/ 辅助目录）|
| 斜杠命令数 | 101 | 非常多——大部分用户只用 5-10 个 |
| Hook 事件数 | 27 | 远超文档提到的 5-6 个 |
| 配置来源层数 | 9 | 企业级复杂度 |
| 压缩机制层数 | 6 | 从轻到重的梯度设计 |
| Agent 类型数 | 7 | 从轻量到完全隔离的谱系 |
| 系统提示词大小 | 15K-34K token | 每次 API 调用的"固定税" |
| Context Window | ~200K token | 有限的"RAM" |
| MAX_SNAPSHOTS | 100 | 100 个文件历史存档点 |
| Prompt Cache 节省 | 10x | 缓存命中 = 十分之一的价格 |
| 模块加载时间 | ~135ms | Pre-import 并行利用这段时间 |

---

## 快速检索索引

| 如果你想了解... | 去看... |
|----------------|---------|
| 系统整体架构 | Part 1 第二章 |
| 代码库的完整地图 | **Part 2 第一章** |
| 启动序列 | **Part 2 第二章** |
| 提示词如何组装 | **Part 2 第三章** |
| 主循环如何工作 | **Part 2 第四章** |
| 工具系统全貌 | **Part 2 第五章** |
| Agent 编排 | **Part 2 第六章** |
| 安全与权限 | **Part 2 第七章**，Part 3 Q05，Part 4 第一章 |
| 状态与持久化 | **Part 2 第八章** |
| MCP/Hooks/插件/Skills | **Part 2 第九章** |
| Token 经济学 | **Part 2 第十章** |
| 配置系统 | **Part 2 第十一章**，Part 3 Q08 |
| 终端 UI | **Part 2 第十二章** |
| import 前的性能把戏 | Part 3 Q01 |
| 上下文压缩 | Part 3 Q02 |
| 流式工具执行 | Part 3 Q04 |
| 投机执行 | Part 3 Q06 |
| CLAUDE.md 加载 | Part 3 Q07 |
| SessionMemory | Part 3 Q09 |
| 对话分支和回滚 | Part 3 Q11 |
| 多 Claude 协作 | Part 3 Q14 |
| 小动物伴侣 | Part 3 Q15 |
| 语音模式 | Part 3 Q17 |
| 跨对话记忆 | Part 3 Q18 |
| 思考深度控制 | Part 3 Q19 |
| Dream Mode（睡眠记忆） | Part 2 第十三章第 6 节 |
| Auto-Memory（自动记忆） | Part 2 第十三章第 7 节 |
| GrowthBook（远程配置） | Part 2 第十三章第 12 节 |
| 错误重试与降级 | Part 2 第十三章第 2 节 |
| Token 设计哲学 | Part 5 第二章 |
| 系统的代价 | Part 6 第一章 |

---

## 关键源码入口

以下是本书最常引用的源码文件，提前认识它们会帮助你更快定位讨论的上下文：

- `src/main.tsx`（4,684 行）：整个系统的启动入口和 React 根组件
- `src/Tool.ts`：所有工具的基类接口定义——理解工具系统的起点
- `src/query.ts`：`query()` 函数（line 219）调用 `queryLoop()`（line 241）——查询循环的核心驱动
- `src/utils/permissions/permissions.ts`（约 1,500 行）：10 步权限状态机
- `src/utils/settings/settings.ts`：配置系统的合并逻辑

## 关键调用链速查

> **这是给工程师读者准备的快速索引**——如果你是文科生读者，这一节可以**跳过**，不影响理解后续章节。如果你是工程师或正在翻阅源码，这张表能帮你快速定位每个函数在系统中的位置和顺序。
>
> 调用链的意思：**一个功能从入口到结果经历的一连串函数调用**，就像多米诺骨牌——你敲第一张（用户按回车），后面的牌依次倒下（启动链 → 执行链 → 回传结果）。

以下是 Claude Code 中最重要的几条调用链。当你在后续章节中看到某个函数名时，这张表能帮你快速定位它在系统中的位置。

**启动链**（你敲下 `claude` 之后发生了什么）：
```
cli.tsx → main.tsx → setup() → getCommands() → launchRepl() → REPL.tsx → query()
```

**执行链**（AI 说"我要读个文件"之后发生了什么）：
```
tool_use 块 → runTools()/StreamingToolExecutor → runToolUse()
→ checkPermissionsAndCallTool() → tool.call() → toolResultStorage → 回写到消息历史
```

**Agent 链**（AI 决定"这个任务太复杂，我要派个子 Agent"）：
```
AgentTool.call() → team/fork/remote/local 分流
→ runAgent()/runForkedAgent() → query()（子 Agent 复用同一个核心循环）
```

**跨环境链**（你在手机上查看 Mac mini 上的工作进度）：
```
bridge: useReplBridge.tsx → replBridge.ts → Work Poll / SSE → bridge UI
remote: teleportToRemote() → RemoteAgentTask → CCR session → 轮询 → 本地 task 更新
```

**上下文压缩链**（对话太长时系统如何续命）：
```
applyToolResultBudget → snipCompact → microcompact
→ applyCollapsesIfNeeded → autocompact → reactiveCompact（触发时）
```

> 💡 **通俗理解**：这五条链路就像人体的五大系统——启动链是"清晨醒来"（从睁眼到起身），执行链是"干活"（从接到任务到完成），Agent 链是"派人帮忙"（从发现忙不过来到找同事），跨环境链是"出差时查家里情况"（从打开手机到看到进度），压缩链是"整理书桌"（从堆满到清出空间继续工作）。

---

## 关于术语的局限

需要注意的是，这些概念之间的边界并不总是清晰的。然而，在实际源码中，Agent 一词的含义取决于上下文——有时指子进程（Task），有时指 Coordinator 的工作节点。同样，"权限"在不同层级的含义不同——工具级权限和企业策略级权限是完全不同的机制。如果在后续章节中某个术语让你困惑，可能是因为它在那个上下文中有特殊含义——回到这里确认它的基础定义，然后注意该章节如何扩展或限定这个定义。