00 — Claude Code 完整架构解析
本文档是什么。 这是 Claude Code 深度解析 系列的压轴篇章——一部将 17 篇架构分析浓缩为单一参考手册的微缩百科全书。在深入各章之前用它做地图，或在探索完各章后用它做复习。
本文档不是什么。 它不能替代各篇深度解析。下文每个小节都是一段"电梯演讲"——用 60 秒讲完一个在专篇中可能跨越 500-900 行的子系统。
第一部分 — 导航
§1 全局架构图
Claude Code 的强大不是来自某个杀手锏功能，而是六大支柱协同运作——每一个都在放大其他支柱的效果：
┌─────────────────────────┐
│ System Prompt │
│ (身份 + 规则 + │
│ 42+ 工具描述) │
└────────────┬────────────┘
│
┌──────────────────┼──────────────────┐
│ │ │
┌───────▼────────┐ ┌──────▼───────┐ ┌───────▼────────┐
│ 工具系统 │ │ 查询循环 │ │ 上下文 │
│ (42+ 工具， │ │ (12 步 │ │ 管理 │
│ 每个 30+方法) │ │ 状态机) │ │ (4 层压缩) │
└───────┬────────┘ └──────┬───────┘ └───────┬────────┘
│ │ │
└──────────────────┼──────────────────┘
│
┌──────────────────┼──────────────────┐
│ │ │
┌───────▼────────┐ ┌──────▼───────┐ ┌───────▼────────┐
│ 权限与安全 │ │ 多 Agent │ │ Skill & │
│ (7 层纵深防御) │ │ 集群 │ │ Plugin │
│ │ │ (3 后端， │ │ (6 源， │
│ │ │ 7 种任务) │ │ MCP 协议) │
└────────────────┘ └──────────────┘ └────────────────┘一句话数据流：
用户输入 → CLI (cli.tsx) → QueryEngine.query() → System Prompt 组装
→ 流式 API 调用 → 工具提取 → 权限检查 → 工具执行
→ 结果注入 → 继续/结束决策 → 下一次迭代或响应六大设计哲学：
| # | 哲学 | 一句话 |
|---|---|---|
| 1 | LLM = 大脑，Harness = 身体 | LLM 负责推理；Harness 负责感知、行动、记忆和约束 |
| 2 | 工具 = 能力边界 | Claude 只能做注册工具允许的事情 |
| 3 | 上下文是最稀缺的资源 | 200K token 听起来很多，一个中等项目就能填满 |
| 4 | 零信任安全 | 每一次工具调用都经过多层权限检查 |
| 5 | 循环直到完成 | 不是请求-响应，而是 调用 → 工具 → 结果 → 重复 |
| 6 | 可扩展性决定上限 | Skill、Plugin、MCP 让能力无限延伸 |
§2 篇章索引：每章一句话
| 篇 | 标题 | 电梯演讲 | 行数 |
|---|---|---|---|
| 01 | QueryEngine：大脑 | 将 LLM 变成 Agent 的 while(true) 循环——12 步流水线、AsyncGenerator 流式处理、错误恢复 | 711 |
| 02 | 工具系统：42 模块统一接口 | 每个工具 30+ 方法契约，Schema 驱动注册，三层过滤，流式并行执行 | 665 |
| 03 | 多 Agent 协调器 | tmux/iTerm2/进程内后端，AsyncLocalStorage 隔离，自动环境检测 | 342 |
| 04 | Plugin 系统：全生命周期 | Plugin = Skills + Hooks + MCP 服务器；6 种 Skill 来源，后台安装协调 | 548 |
| 05 | Hook 系统：20 种事件类型 | PreToolUse / PostToolUse / Notification 钩子，MCP 传输，否决与变异语义 | 299 |
| 06 | Bash 引擎：沙箱与管道 | 6 层纵深防御，tree-sitter AST 解析，macOS Seatbelt 沙箱 | 458 |
| 07 | 权限管道：从规则到内核 | 7 种规则来源，Bash AST 安全，投机性 YOLO 分类器，OAuth 2.0 PKCE | 619 |
| 08 | Agent 集群：团队协调 | 7 种 TaskState 变体，SendMessage 协议，DreamTask 记忆整理，UltraPlan | 503 |
| 09 | 会话持久化 | JSONL 追加存储，恢复/分叉/搜索，跨会话记忆 | 411 |
| 10 | 上下文组装 | System Prompt 分层，Token 预算分配，动态附件，斜杠命令 | 473 |
| 11 | 压缩系统 | 4 层压缩（微 → 截断 → 自动 → 紧急），电路断路器，Prompt Cache 共享 | 372 |
| 12 | 启动与引导 | Import-Gap 并行，快速路径分发，记忆化初始化，state.ts 叶模块模式 | 393 |
| 13 | 桥接系统 | CLI ↔ IDE WebSocket 桥接，3 种 Spawn 模式，Chrome 扩展集成 | 346 |
| 14 | UI 与状态管理 | Fork Ink + React 19，终端中的 W3C 事件模型，35 行 Store，Vim 状态机 | 980 |
| 15 | 服务层与 API | queryModel() 700 行核心，多提供商工厂，SSE 流管道，重试引擎 | 691 |
| 16 | 基础设施与配置 | Bootstrap 单例，5 层设置合并，安全存储，CLAUDE.md 记忆系统 | 876 |
合计：16 篇深度解析 + 本总纲，共 8,600+ 行架构分析。
§3 阅读顺序：六条认知路径
| 路径 | 名称 | 适合人群 | 篇章 |
|---|---|---|---|
| 🟢 A | 核心循环 | 初次阅读者 | 00 → 12 → 01 → 02 |
| 🔵 B | 安全与资源 | 安全工程师、成本优化者 | → 06 → 07 → 10 → 11 |
| 🟣 C | 协作与扩展 | 插件开发者、多 Agent 构建者 | → 03 → 08 → 04 → 05 |
| 🟠 D | 基础设施 | 后端工程师、平台团队 | → 15 → 16 → 09 |
| 🔴 E | 体验层 | UI 开发者、IDE 集成者 | → 13 → 14 |
| 🟡 F | 暗面 | 隐私研究者、运维工程师 | → 17 |
最小可行阅读：仅路径 A（4 篇，~2,100 行）即可获得 60% 的架构理解。加上路径 B 达到 85%。路径 F 是独立的压轴篇——在任意路径之后阅读，了解生产环境中的遥测管道、模型代号隐匿和远程运营控制系统。
第二部分 — 核心架构速览
§4 Harness：大脑周围的身体
LLM 是大脑，Harness 是其他一切——赋予大脑感知、行动、记忆和安全的运行时基础设施：
| 能力 | 实现 | 大脑看到的 |
|---|---|---|
| 感知文件 | FileReadTool, GlobTool, GrepTool | "我能看到代码库" |
| 修改代码 | FileEditTool, FileWriteTool | "我能修改东西" |
| 执行命令 | BashTool（沙箱化） | "我能运行和测试" |
| 搜索网络 | WebSearchTool, WebFetchTool | "我能查资料" |
| 与用户交互 | AskUserQuestionTool, 权限对话框 | "我能提问" |
| 分派工作 | AgentTool, TeamCreate, SendMessage | "我能委派任务" |
| 记忆 | CLAUDE.md, memdir, auto-memory | "我有长期记忆" |
| 扩展能力 | MCPTool, SkillTool, Plugin 系统 | "我能学新技能" |
System Prompt 的分层构建：
System Prompt 构建（按 Token 优先级排序）：
1. 核心身份与规则 ← 我是谁，能/不能做什么
2. 工具描述（42+） ← ~10K+ tokens 的能力定义
3. Git 状态与项目上下文 ← 当前分支、最近提交
4. CLAUDE.md 内容 ← 项目级指令
5. 用户/企业规则 ← 偏好、组织策略
6. 动态附件 ← 技能发现、记忆注入、MCP 资源→ 深度解析: EP12: 启动与引导 | EP16: 基础设施
§5 核心循环：12 步状态机
Claude Code 不是"发送提示，得到回答"，而是一个 while(true) 循环——将单次调用的 LLM 变成迭代式 Agent 的核心放大器：
| 步骤 | 名称 | 目的 |
|---|---|---|
| 1 | applyToolResultBudget | 裁剪超大工具结果 |
| 2 | snipCompact | 截断最旧对话轮次 |
| 3 | microcompact | 清理过期工具输出（时间衰减） |
| 4 | contextCollapse | 折叠冗余上下文 |
| 5 | autocompact | AI 生成对话摘要 |
| 6 | tokenWarningState | 预算检查与用户告警 |
| 7 | callModel | 流式 API 调用 |
| 8 | StreamingToolExecutor | 边流式输出边执行工具 |
| 9 | stopHooks | 评估停止条件 |
| 10 | tokenBudget check | 硬预算限制 |
| 11 | getAttachmentMessages | 注入记忆、技能发现 |
| 12 | state transition | 更新状态，继续循环 |
错误恢复策略矩阵： 429 → 指数退避；529 → 降级到 Sonnet；prompt-too-long → 紧急压缩；max_output_tokens → 自动提升 8K→64K。
→ 深度解析: EP01: QueryEngine
§6 工具系统：契约式能力边界
每个工具实现 30+ 方法的完整契约——身份、执行、安全、并发、UI 渲染。buildTool 工厂提供 fail-closed 默认值（isConcurrencySafe: false，isReadOnly: false）。三层工具过滤确保模型只看到当前上下文适用的工具，assembleToolPool() 的稳定排序保证 Prompt Cache 键稳定。
BashTool 是最复杂的工具（~156K 代码），采用 6 层纵深防御——从安全包装器剥离到 tree-sitter AST 解析再到 macOS Seatbelt OS 级沙箱。
→ 深度解析: EP02: 工具系统 | EP06: Bash 引擎
§7 上下文管理：最稀缺的资源
四层压缩保持系统活力： Layer 0（API 侧自动清除）→ Layer 1 微压缩（时间衰减清理旧结果）→ Layer 2 截断（丢弃最旧轮次）→ Layer 3 自动压缩（AI 生成摘要，带电路断路器）→ Layer 4 紧急压缩（仅在 API 返回 prompt-too-long 时触发）。
Token 估算三级精度： 粗略（bytes/4，零成本）→ 代理（Haiku usage.input_tokens，便宜）→ 精确（countTokens API，准确但慢）。
Prompt Cache 三层策略 + Beta header 锁存保持缓存键稳定，避免 12 倍成本惩罚。
→ 深度解析: EP10: 上下文组装 | EP11: 压缩系统
§8 权限与安全：地基而非天花板
安全采用纵深防御——每层假设上一层已被绕过：工具级验证 → 7 源权限规则合并 → Bash AST 安全分析（23 种注入检测 + fail-closed）→ 投机性 YOLO 分类器（2 秒超时）→ 用户确认对话框 → OS 级沙箱。
设计原则： 安全相关 fail-closed（未知 → 拒绝）；可用性相关 fail-open（策略服务宕机 → 允许所有，使用本地缓存）。
→ 深度解析: EP07: 权限管道 | EP06: Bash 引擎
§9 多 Agent：从独奏到交响乐
当任务超出单一上下文窗口时，系统分治而非压缩。三种执行后端自动检测（iTerm2 标签页 / tmux 面板 / 进程内 AsyncLocalStorage）。七种任务类型覆盖所有后台工作。团队协调使用 TaskList 共享状态 + SendMessage 异步通信 + 结构化消息类型。UltraPlan 模式启用分层规划。
→ 深度解析: EP03: 协调器 | EP08: Agent 集群
§10 Skill 与 Plugin：自我进化的架构
Skill 是可复用的 Prompt 工作流（YAML 前置元数据 + Markdown），6 种来源层级合并。Plugin 是组合单元（skills + hooks + mcpServers 捆绑）。MCP 是万能扩展管道（6 种传输类型，工具发现，OAuth 认证）。Hook 系统 提供 20 种事件类型的全生命周期拦截。
→ 深度解析: EP04: Plugin 系统 | EP05: Hook 系统
第三部分 — 工程卓越
§11 七个值得研究的工程实践
11.1 编译时死代码消除
feature('VOICE_MODE') 在编译时被替换为 true/false，false 分支被 Bun 打包器完全移除。三种条件加载层级共存：编译时 DCE → 运行时环境检查 → 运行时能力检测。
11.2 循环依赖消除：叶模块模式
bootstrap/state.ts（~55KB）被所有模块依赖，解决方案是让它成为依赖图的叶节点——禁止从 src/ 导入任何东西。这不是建议，而是由自定义 ESLint 规则（custom-rules/bootstrap-isolation）强制执行的架构约束。
11.3 35 行 Store 替代 Redux
35 行 createStore 函数提供 getState/setState/subscribe 接口，配合 React 19 的 useSyncExternalStore 完成状态管理。Object.is 引用相等跳过避免不必要的重渲染。依赖成本：0 字节。
11.4 Fork Ink：在终端中构建浏览器
原版 Ink 的 LegacyRoot → ConcurrentRoot（React 19），无事件系统 → W3C 捕获/冒泡模型，单缓冲 → 双缓冲 + ANSI diff。渲染管线：stdin → 按键解析 → DOM 事件分发 → React 更新 → Yoga 布局 → 屏幕缓冲 → ANSI diff → stdout（16ms 节流）。
11.5 Vim 模式：教科书级状态机
四态有限状态机：Normal → Insert / Operator Pending / Find Pending。每个状态有明确的进入/退出动作和有限的状态转换集——行为可预测、可测试、可扩展。
11.6 Import-Gap 并行化
在 import 语句之间启动异步操作，利用 ES 模块评估的"空闲窗口"（~135ms）作为免费并行时间。无需 Promise.all，只需把异步启动放在 import 之间。
11.7 Fail-Open 与 Fail-Closed 的工程抉择
Fail-Closed（安全优先）： Bash 解析错误 → 拒绝执行；权限超时 → 默认拒绝。Fail-Open（可用性优先）： 策略加载失败 → 允许所有；远程配置超时 → 用本地缓存；GrowthBook 不可用 → 用默认值。边界清晰：涉及用户数据/系统访问用 fail-closed，涉及配置/外部服务用 fail-open。
→ 深度解析: EP12: 启动 | EP14: UI 与状态 | EP16: 基础设施
第四部分 — 独特视角
§12 第一人称视角：我是如何运作的
12.1 我的思维循环
每次工具调用都是一次完整的 API 往返。你感受到的"思考 → 行动 → 观察"循环，在底层是：API 响应（tool_use）→ Harness 执行 → 结果注入 → 下一次 API 调用。修复一个 bug 可能需要 5 次 API 调用：读文件 → 搜索 → 确认 → 编辑 → 测试。
12.2 我的并行能力
我可以在一次 API 响应中调用多个工具，Harness 通过 StreamingToolExecutor 并行执行所有 isConcurrencySafe: true 的工具。读操作并行，写操作串行。
12.3 我的上下文感知
我通过六个通道感知世界：System Prompt（我的"DNA"）、CLAUDE.md（我的"项目记忆"）、对话历史（我的"短期记忆"）、工具结果（我的"感官"）、Memory/memdir（我的"长期记忆"）、动态附件（我的"外部知识"）。
12.4 我的局限性
有限的上下文窗口 → 4 层压缩自动管理；不能直接执行代码 → BashTool 代劳；可能输出不安全命令 → 6 层安全管道拦截；单次输出有限 → max_output_tokens 自动提升；可能产生幻觉 → 工具结果提供事实反馈；API 不稳定 → 重试+降级+错误恢复；单一上下文不够 → 多 Agent 分治。
12.5 我为什么能高效工作
42+ 种工具覆盖几乎所有场景；可以迭代试错；可以并行化；有跨会话记忆；被安全约束（用户放心给权限）；能自我修复（错误恢复机制）。
第五部分 — 可迁移的设计模式
§13 你可以带走的设计模式
以下模式从 17 篇架构分析中提炼而来。每条遵循场景 → 方案 → 效果闭环结构，可直接应用于任何 Agentic 系统、CLI 工具或复杂 TypeScript 应用。
| # | 模式 | 核心洞察 | 来源 |
|---|---|---|---|
| 1 | Import-Gap 并行预取 | 在 ES 模块评估间隙获得免费并发 | EP12 |
| 2 | AsyncGenerator 状态机 | yield = 天然背压 + 可取消 + 可组合 | EP01 |
| 3 | 多层压缩管道 | 逐级升级成本：便宜 → 昂贵，各层独立电路断路 | EP10, EP11 |
| 4 | 纵深防御安全 | 每层假设上一层已被绕过 | EP06, EP07 |
| 5 | Fail-Closed + Fail-Open | 安全默认拒绝；服务优雅降级 | EP07, EP16 |
| 6 | Schema 驱动注册 | 一份 Zod Schema → 验证 + API + 权限 + UI | EP02 |
| 7 | 投机执行 + 逐级升级 | 在确认需要之前就启动昂贵检查 | EP07 |
| 8 | 叶模块隔离 | 被依赖最多的模块不导入任何东西；ESLint 强制 | EP12, EP16 |
| 9 | 锁存模式 | 一旦激活永不关闭，防止缓存键不稳定 | EP15 |
| 10 | Agent 分治 | 用独立上下文窗口的子 Agent 突破容量限制 | EP03, EP08 |
| 11 | 35 行替代整个库 | 只写你需要的 API 表面 | EP14 |
| 12 | 错误恢复是一等公民 | 每种错误码 → 专指恢复策略 | EP01, EP15 |
| 13 | Stale-While-Error（独有发现） | 读取失败时返回上次已知好值 | EP16 |
| 14 | 闭包工厂替代 Class（独有发现） | 函数返回对象，非类实例；代际计数器防竟态 | EP15, EP16 |
详解：锁存模式（Pattern 9）
场景： API beta header 影响 Prompt Cache 键。问题： 中途切换 header 导致所有缓存失效（12 倍成本增加）。方案： 三态锁存——null（未知）→ true（锁定）→ 永远保持 true。效果： 整个会话缓存键稳定，一个决策，无翻转。
详解：闭包工厂（Pattern 14）
场景： LSP 服务器管理器需要私有状态 + 公共接口。问题： Class 带来继承诱惑和 this 绑定问题。方案： 工厂函数返回闭包对象，私有状态在闭包作用域中。代际计数器（++generationCounter）防止过期的异步操作覆盖新状态。效果： 比 class 更干净的 API，无 this 困惑。
结语
Claude Code 的强大不是来自某个天才般的设计决策，而是来自数百个正确工程选择的累积效应：
- 启动优化节省的每一毫秒
- 纵深防御拦截的每一个危险操作
- 多层压缩保住的每一个 token
- 缓存稳定性避免的每一次重复计算
- 错误恢复挽救的每一个即将中断的会话
- Agent 编排倍增的每一个上下文窗口
共同的主线：尊重每一个资源——时间、token、安全、用户信任。
╭─────────────────────────╮
│ │
│ 尊重每一个资源。 │
│ │
│ 从每一个故障中恢复。 │
│ │
│ 迭代直到完成。 │
│ │
╰─────────────────────────╯下一步： 选择一条阅读路径，深入各篇章。每篇 15-30 分钟，将改变你对 Agentic 系统设计的思考方式。
本文档是 Claude Code 深度解析 系列的一部分——17 篇架构分析，覆盖 8,600+ 行技术内容，中英双语提供。
下一篇: → 01 — 查询引擎