源码分析 on 鬼哥的空间

解剖 Claude Code（三）：Prompt 缓存分割与四级上下文压缩

Sat, 04 Apr 2026 00:00:00 +0000

一个 AI Agent 的核心竞争力不在于它调用了多好的模型，而在于它的主循环有多健壮。Claude Code 的心脏是 query.ts 中一个 1,700 行的 while(true) 循环——本篇逐阶段拆解它。

本文为「解剖 Claude Code」系列第三篇。前篇：解剖 Claude Code（二）：ReAct 循环

问题

一个典型的 Claude Code 会话可能持续几十轮。每一轮都要把完整的系统提示、对话历史、工具定义发给 API。如果不做优化：

系统提示：~10K Token，每轮都重复发送
工具定义：50 个工具的 Schema，~15K Token
对话历史：逐轮增长，最终撑爆上下文窗口（200K Token）

不做缓存 = 每轮重复支付这些 Token 的输入费用。不做压缩 = 对话最终无法继续。

Claude Code 的解法是两套机制联合工作：

Prompt 缓存分割：把不变的部分标记为全局可缓存，只为变化的部分付费
四级上下文压缩：当对话增长时，逐级压缩保留核心信息

在整体架构中的位置

1
2
3


ReAct 循环的每一轮：
 Phase 1: 上下文准备 ← 四级压缩在这里运行
 Phase 2: 模型调用 ← 缓存分割在这里生效

Part 1：Prompt 缓存分割

核心思想：静态 vs 动态

Claude Code 将系统提示在物理上分为两部分，用一个边界标记隔开：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


┌─────────────────────────────────────────────────┐
│ STATIC（全局缓存，scope: 'global'） │
│ │
│ · 身份声明（"You are an interactive agent..."） │
│ · 系统指南（工具使用、权限、压缩规则） │
│ · 任务执行指南 │
│ · 操作安全指南（可逆性、爆炸半径） │
│ · 工具使用规范（Bash vs 专用工具） │
│ · 语气风格（无 emoji、简洁） │
│ · 输出效率指南 │
│ │
├──── SYSTEM_PROMPT_DYNAMIC_BOUNDARY ──────────────┤
│ │
│ DYNAMIC（不缓存，每轮重新计算） │
│ │
│ · 会话引导（Agent 类型相关指令） │
│ · 记忆内容（loadMemoryPrompt()） │
│ · 环境信息（模型 ID、平台、Shell、OS） │
│ · MCP 服务器指令（服务器随时连接/断开） │
│ · Scratchpad 目录 │
│ · 语言偏好 │
│ · 输出风格 │
│ │
└─────────────────────────────────────────────────┘

边界标记是一个常量字符串：

1

export const SYSTEM_PROMPT_DYNAMIC_BOUNDARY = '__SYSTEM_PROMPT_DYNAMIC_BOUNDARY__'

三种缓存范围

系统提示被分割成最多 4 个 TextBlockParam，每个有不同的 cache_control：

块	内容	cache_control.scope	含义
1	归属头（Attribution）	`null`	不缓存，每请求元数据
2	CLI 前缀	`null`	不缓存
3	静态内容（边界前）	`'global'`	跨组织缓存，所有用户共享
4	动态内容（边界后）	`null`	不缓存，用户/会话特定

为什么分 global 和 org？

global 缓存：所有 Anthropic 1P 用户共享。当你发送和另一个用户完全相同的静态系统提示时，直接命中缓存——零写入成本
org 缓存：组织内共享（Bedrock/Vertex 3P 用户的默认）
无 scope（ephemeral）：仅当前请求链，5 分钟 TTL

cache_control 的返回结构：

1
2
3
4
5


{
 type: 'ephemeral',
 ttl?: '1h', // 符合条件时升级到 1 小时
 scope?: 'global', // 1P 用户的静态内容
}

TTL 升级：从 5 分钟到 1 小时

默认 TTL 是 5 分钟（ephemeral）。对于付费订阅用户，可以升级到 1 小时：

升级条件（三项都要满足）：

内部用户或 Claude AI 订阅者（非超额使用）
查询来源在 GrowthBook 白名单内（repl_main_thread*, agent:* 等）
Bedrock 3P 用户需显式 opt-in

为什么 TTL 决策要"锁存"（latch）？ 如果用户在会话中途切换了订阅状态（如用量超额），TTL 可能从 1h 变回 5m，导致 ~20K Token 的缓存前缀失效。锁存确保 TTL 在整个会话中保持稳定。

Section 缓存机制

动态部分内部也有缓存优化。每个 prompt section 分为两类：

1
2
3
4
5
6
7
8
9


// 缓存 section：会话级别复用，/clear 或 /compact 时失效
systemPromptSection('env_info', async () => {
 return `Model: ${modelId}, Platform: ${platform}...`
})

// 非缓存 section（危险！每轮重算）
DANGEROUS_uncachedSystemPromptSection('mcp_instructions', async () => {
 return buildMcpInstructions(mcpClients)
}, 'MCP servers connect/disconnect mid-session')

为什么 MCP 指令不能缓存？ 因为 MCP 服务器可能在会话中途连接或断开。如果缓存了旧的服务器列表，模型会尝试调用不存在的工具。

DANGEROUS_ 前缀是刻意的命名——它强制开发者思考"为什么这个 section 不能缓存"，并通过第二个参数写下原因。

工具 Schema 的缓存稳定性

第 02 篇提到，工具注册表按名称排序以保护 Prompt Cache。这里看看具体怎么做的：

工具 Schema 通过 getToolSchemaCache() 会话级缓存
缓存 key 是 ${tool.name}:${jsonStringify(schema)}
每次请求只叠加 defer_loading、cache_control、eager_input_streaming 等运行时属性
如果工具列表稳定（名称和 Schema 不变），缓存前缀不受影响

缓存断裂检测：系统还有一个 promptCacheBreakDetection.ts 模块，监控 cache_read_input_tokens 的变化。如果缓存读取 Token 骤降 > 2,000 且 < 上次的 95%，说明缓存被打破了——系统会记录事件用于诊断。

Part 2：四级上下文压缩

当对话持续增长，四级压缩体系逐级介入：

触发阈值

1
2
3
4


上下文窗口 = 200,000 Token（默认）
摘要预留 = 20,000 Token（给压缩模型留空间）
有效窗口 = 200,000 - 20,000 = 180,000 Token
自动压缩阈值 = 180,000 - 13,000 = 167,000 Token

阈值	值	含义
`AUTOCOMPACT_BUFFER_TOKENS`	13,000	自动压缩的缓冲区
`WARNING_THRESHOLD_BUFFER_TOKENS`	20,000	UI 警告阈值
`ERROR_THRESHOLD_BUFFER_TOKENS`	20,000	UI 错误阈值
`MANUAL_COMPACT_BUFFER_TOKENS`	3,000	手动压缩的阻塞阈值
`MAX_CONSECUTIVE_AUTOCOMPACT_FAILURES`	3	熔断器上限

第一级：Snip（轻量裁剪）

特性门控：HISTORY_SNIP

最轻量的压缩——直接移除旧消息。不做摘要，不做总结，就是删除。

保留最近的消息不动
释放的 Token 数（snipTokensFreed）传给后续阶段，影响 Autocompact 的触发判断
如果 Snip 已经释放了足够空间，Autocompact 就不需要触发

为什么最先运行？ 因为它最快（零 API 调用），且对缓存无影响。

第二级：Microcompact（缓存感知压缩）

核心创新：在不打破 Prompt Cache 的前提下压缩工具结果。

可压缩的工具：FileRead、FileWrite、FileEdit、Bash、Grep、Glob、WebSearch、WebFetch

两种模式：

时间触发压缩：如果距离上次 API 调用超过缓存 TTL，服务器缓存已过期。此时全量重写前缀不会有额外成本——因此可以直接清理旧工具结果。

缓存编辑压缩（Cache Editing，仅内部用户）：利用 API 的 cache_edits 功能，在不失效缓存的情况下删除工具结果：

1
2
3
4
5
6
7
8


// 不是替换缓存内容，而是发送编辑指令
{
 type: 'cache_edits',
 edits: [{
 type: 'delete',
 cache_reference: 'tool_use_abc123' // 要删除的工具结果 ID
 }]
}

这意味着：缓存前缀完全保持不变，只通过 cache_reference 标记哪些工具结果已经不需要了。API 服务器会在应用缓存时跳过被删除的部分。

为什么这很重要？ 传统做法是修改消息内容来"清空"工具结果——但这会改变消息的 hash，导致整个缓存失效。Cache Editing 绕过了这个问题。

第三级：Autocompact（AI 全量摘要）

当 Token 超过阈值（默认 ~167K），触发 AI 全量摘要。

触发条件：

1
2
3


tokenCount > getAutoCompactThreshold(model)
// 其中 threshold = effectiveWindow - AUTOCOMPACT_BUFFER_TOKENS
// = (contextWindow - 20K) - 13K

排除场景：

当前查询本身就是压缩查询（防止递归）
Session memory 查询
Context agent（marble_origami）查询

摘要模板（9 个分区）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


<analysis>
[模型的思考过程——最终会被剥离]
</analysis>

<summary>
1. Primary Request and Intent — 用户的所有显式请求
2. Key Technical Concepts — 讨论过的技术和框架
3. Files and Code Sections — 查看/修改的文件（含代码片段）
4. Errors and Fixes — 遇到的错误及修复方式
5. Problem Solving — 已解决和进行中的问题
6. All User Messages — 所有非工具结果的用户消息
7. Pending Tasks — 明确的待办任务
8. Current Work — 压缩前正在做什么
9. Optional Next Step — 下一步建议（仅当与最近请求一致时）
</summary>

强制文本输出：摘要 Prompt 开头有一段"反工具声明"：

1
2


CRITICAL: Respond with TEXT ONLY. Do NOT call any tools.
Tool calls will be REJECTED and will waste your only turn — you will fail the task.

末尾还有 REMINDER 重复一次——双重保险。因为压缩调用本身也消耗 Token 和时间，如果模型在这里"开小差"调工具，代价极高。

摘要后的智能恢复：

压缩完成后，系统不是简单地用摘要替换历史。它会恢复最重要的信息：

恢复项	上限
最近读取的文件	最多 5 个文件
文件恢复总预算	50,000 Token
单文件预算	5,000 Token
Skill 恢复预算	25,000 Token
单 Skill 预算	5,000 Token

熔断器：如果 Autocompact 连续失败 3 次（MAX_CONSECUTIVE_AUTOCOMPACT_FAILURES），停止尝试。防止"压缩失败 → 重试 → 又失败"的无限循环。

第四级：Reactive Compact（紧急 413 压缩）

当 API 返回 413 Prompt Too Long 错误后触发——这是最后手段。

与 Autocompact 的区别：

	Autocompact	Reactive Compact
触发时机	API 调用前（预防性）	API 返回 413 后（响应性）
触发条件	Token > 阈值	API 报错
可用次数	多次	每轮一次（`hasAttemptedReactiveCompact`）
图片处理	不处理	可剥离图片/PDF
Token 差距计算	不需要	从 413 错误信息解析

Token 差距计算：

1
2
3


getPromptTooLongTokenGap(errorMessage)
// 从 "prompt is too long: 137500 tokens > 135000 maximum"
// 提取出 gap = 137500 - 135000 = 2500

利用这个 gap，系统可以精确计算需要删除多少消息组，而不是盲目地一组一组删除。如果 gap 无法解析（Bedrock/Vertex 的错误格式不同），回退到"删除 20% 的消息组"策略。

图片/PDF 剥离：对于 Media Size Error，直接将图片块替换为 [image]、文档块替换为 [document] 文本标记。这不是压缩——是放弃媒体内容以换取请求可以通过。

Token 成本的数学

来算一笔账。以 Sonnet 4.6 为例：

Token 类型	价格（$/百万）	相对比
输入	$3.00	基准
输出	$15.00	5×
缓存写入	$3.75	1.25×
缓存读取	$0.30	0.1×
Web 搜索	$0.01/次	—

缓存回本点：写入成本 $3.75 / 读取成本 $0.30 ≈ 12.5 次读取回本。

对于一个持续 30 轮的会话，系统提示（~10K Token）的成本对比：

1
2
3
4


无缓存：30 轮 × 10K Token × $3/Mtok = $0.90
有缓存：1 次写入 $0.0375 + 29 次读取 × $0.003 = $0.12

节省：$0.90 - $0.12 = $0.78（节省 87%）

如果是全局缓存命中（scope: 'global'），连写入费用都省了——第一个用户写入后，所有用户都只付读取费用。

输出 Token 的优化：8K 默认 + 按需升级

第 02 篇提到的 Token 上限升级机制，也是一个成本优化：

1
2


默认 max_tokens = 8,000 (CAPPED_DEFAULT_MAX_TOKENS)
按需升级到 = 64,000 (ESCALATED_MAX_TOKENS)

为什么默认只给 8K？ 数据显示 p99 的输出 Token 才 4,911——绝大多数请求在 8K 以内就能完成。默认 64K 意味着 API 需要为每个请求预留 8 倍的计算资源，但 99% 的时候这些资源是浪费的。

8K 默认 + 按需升级 = 资源利用率大幅提升，< 1% 的请求需要重试。

6 级 Prompt 优先级

系统提示不是一个简单的字符串——它有 6 级优先级，决定最终发给 API 的内容：

1
2
3
4
5
6


优先级 0: Override（覆盖一切）
优先级 1: Coordinator 模式
优先级 2: Agent 系统提示
优先级 3: 自定义提示（--system-prompt）
优先级 4: 默认提示
优先级 5: Appendive（总是追加）

关键设计：Agent 在 Proactive 模式下是追加到默认提示（不是替换）。因为 Proactive 模式的默认提示已经很精简（自主 Agent 身份 + 记忆 + 环境），Agent 在此基础上添加领域指令，就像队友在共享基础上各自添加专长。

而在非 Proactive 模式下，Agent 是替换默认提示——因为默认提示太长，全部保留会浪费缓存前缀空间。

Appendive 级别的提示总是追加（除非 Override 激活）——用于注入临时上下文，如用户的 --append-system-prompt 参数。

可借鉴的模式

1. 静态/动态分割是缓存优化的第一步

任何 LLM 应用都可以做这个优化：把系统提示中不会变化的部分放前面，标记为可缓存。改动频繁的部分（用户上下文、环境信息）放后面，不缓存。

关键洞察：顺序很重要。Prompt Cache 是前缀匹配——只要前缀相同就命中。动态内容放后面意味着它的变化不影响前缀的缓存命中。

2. 分级压缩优于一刀切

不要在上下文快满时直接"砍掉一半历史"。分级压缩的好处是：

轻量操作（Snip）先跑，可能就够了
避免不必要的 API 调用（AI 摘要很贵）
每一级都保留尽可能多的信息

3. 缓存编辑是一个值得关注的 API 特性

Cache Editing（通过 cache_reference + cache_edits 修改缓存内容而不失效）是一个强大的优化手段。虽然目前只有 Anthropic API 支持，但它展示了一个方向：缓存不需要是全有全无的——可以细粒度地增删。

下一篇预告

缓存分割和压缩保证了"对话能继续"。但 Agent 的能力边界取决于工具——50 个工具如何做到自包含又统一？Tool<Input, Output, Progress> 类型契约是怎么设计的？buildTool() 的 fail-closed 默认值意味着什么？下一篇，我们拆解 Tool System。

篇	标题	状态
01	512K 行代码，一个终端里的 Agent Runtime	✅
02	ReAct 循环：`while(true)` 里的五个阶段与七层恢复	✅
03	Prompt 缓存分割与四级上下文压缩（本篇）	✅
04	50 个工具的统一契约：Tool System 设计	🔄 下一篇
05	五层记忆体系：从短期到持久化	⬚
06	纵深防御：23 项安全检查与"不信任任何输入"	⬚
07	投机执行与自研状态管理：隐藏延迟的两个利器	⬚
08	多 Agent 编排：三种执行模型与 Coordinator 模式	⬚
09	在终端里造一个浏览器：自定义 Ink 渲染引擎	⬚
10	Bridge 与协议层：让 VS Code、Web、Mobile 共享一个 Claude	⬚
11	Skill、Plugin、Hook：三层扩展的设计谱系	⬚
12	回顾：从 Claude Code 中提炼的 10 个 Agent 工程模式	⬚

解剖 Claude Code（二）：ReAct 循环 — while(true) 里的五个阶段与七层恢复

Fri, 03 Apr 2026 00:00:00 +0000

一个 AI Agent 的核心竞争力不在于它调用了多好的模型，而在于它的主循环有多健壮。Claude Code 的心脏是 query.ts 中一个 1,700 行的 while(true) 循环——本篇逐阶段拆解它。

问题

当你在 Claude Code 里输入"帮我重构这个函数"，系统不是简单地调一次 API 然后返回结果。它可能需要：

先搜索代码找到函数位置
读取相关文件理解上下文
生成修改方案
执行文件编辑
运行测试确认没有 break

每一步都是一次"模型思考 → 工具执行"的循环。如果中途上下文溢出了怎么办？输出被截断了怎么办？API 过载了怎么办？网络断了怎么办？

Claude Code 的回答是：一个能自我修复的 ReAct 循环。

在整体架构中的位置

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


用户输入 → QueryEngine.submitMessage()
 ↓
 ┌──────────────────┐
 │ query.ts │ ← 本篇聚焦
 │ while(true) { │
 │ ...1,700 行... │
 │ } │
 └──────────────────┘
 ↓
 Ink 渲染引擎 → 终端

QueryEngine 是入口，但真正的循环逻辑在 query.ts 的 queryLoop() 函数中。QueryEngine.submitMessage() 做的是消息规范化、系统提示组装，然后把控制权交给 query() 异步生成器。

循环状态：一个 Agent 需要记住什么

在进入循环之前，先看循环维护的状态。这个状态对象定义了一个 ReAct Agent 需要跨轮次追踪的所有信息：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


type State = {
 messages: Message[] // 对话历史（持续增长）
 toolUseContext: ToolUseContext // 工具执行上下文
 autoCompactTracking: AutoCompactTrackingState // 压缩状态追踪
 maxOutputTokensRecoveryCount: number // 输出截断恢复次数（上限 3）
 hasAttemptedReactiveCompact: boolean // 是否已尝试紧急压缩
 maxOutputTokensOverride: number | undefined // Token 上限覆盖（8K→64K）
 pendingToolUseSummary: Promise<...> // 上一轮的工具摘要（异步）
 stopHookActive: boolean // Stop Hook 是否激活
 turnCount: number // 当前轮次
 transition: Continue | undefined // 上一次继续的原因
}

两个关键设计：

恢复计数器在每轮重置：maxOutputTokensRecoveryCount 在正常轮次结束时归零——每轮都有 3 次恢复机会，而不是全局 3 次。这意味着一个跨 20 轮的长任务，每轮都能独立恢复。
Transition 追踪：transition.reason 记录上一次循环为什么继续，而不是结束。这不是给用户看的——是给调试和测试用的。可能的值包括 'next_turn'（正常）、'reactive_compact_retry'（紧急压缩后重试）、'max_output_tokens_escalate'（Token 升级）等。

五个阶段

阶段一：上下文准备 — 在调 API 之前先"瘦身"

每轮 API 调用之前，系统会运行一条压缩管线，确保消息历史不会超出上下文窗口：

1
2
3
4
5
6
7
8
9


Tool Result Budget (单消息上限)
 ↓
 Snip (历史裁剪)
 ↓
 Microcompact (工具结果压缩)
 ↓
 Context Collapse (选择性归档)
 ↓
 Autocompact (AI 全量摘要)

每级压缩逐层递进，前一级减少不够才进下一级：

Tool Result Budget：给单条工具结果设置上限。过长的搜索结果、文件内容会被截断。这一步在 Microcompact 之前运行，因为它的截断对缓存是不可见的。

Snip：轻量裁剪，直接移除旧消息。保留最近的上下文不动。释放的 Token 数 snipTokensFreed 会传给后续阶段，影响 Autocompact 的触发阈值。

Microcompact：按 tool_use_id 压缩工具结果。关键技术：它操作的是缓存索引而非消息内容本身，对 API 的 Prompt Cache 不可见。这意味着压缩不会打破缓存。支持的工具包括 FileRead、Shell、Grep、Glob、WebSearch、WebFetch、FileEdit、FileWrite。

Context Collapse：选择性归档。不是摘要所有内容，而是保留细粒度上下文、只归档确定不再需要的部分。

Autocompact：AI 全量摘要。当 Token 数超过 上下文窗口 - 13,000 时触发。使用专门的 Prompt 让模型生成 9 个分区的结构化摘要（请求意图、技术概念、文件代码、错误修复、问题解决、用户消息、待办任务、当前工作、下一步建议）。

有一个熔断器：如果 Autocompact 连续失败 3 次（MAX_CONSECUTIVE_AUTOCOMPACT_FAILURES = 3），就停止尝试，避免无限循环。

阶段二：模型流式调用

准备好上下文后，调用 Anthropic API：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


for await (const message of deps.callModel({
 messages: prependUserContext(messagesForQuery, userContext),
 systemPrompt: fullSystemPrompt,
 tools: toolUseContext.options.tools,
 signal: toolUseContext.abortController.signal,
 options: {
 model: currentModel,
 fallbackModel,
 maxOutputTokensOverride, // 可能已从 8K 升至 64K
 fastMode: appState.fastMode,
 taskBudget: { total, remaining },
 queryTracking: { chainId, depth },
 // ...
 }
})) {
 // 流式处理每个消息块
}

流式处理的核心：模型的输出不是一次性返回的，而是逐块到达——文本块、工具调用块、思考块。系统在流式接收过程中做了三件关键的事：

1. 错误拦截与暂扣

并非所有错误都立即暴露给调用方。三类错误会被暂扣（withheld），等待后续恢复：

错误类型	暂扣条件	恢复手段
413 Prompt Too Long	Context Collapse 或 Reactive Compact 可用	压缩后重试
Max Output Tokens	总是暂扣	Token 升级或多轮恢复
Media Size Error	Reactive Compact 可用	剥离图片/PDF 后重试

暂扣的消息仍然会推入 assistantMessages，但不会 yield 给调用方。只有恢复失败后才会浮出。

2. 工具调用块收集

1
2
3
4


if (msgToolUseBlocks.length > 0) {
 toolUseBlocks.push(...msgToolUseBlocks)
 needsFollowUp = true // 标记：本轮需要继续循环
}

3. 流式工具执行（如果启用）

这是最精巧的部分——下一节详述。

阶段三：工具执行 — 流水线并行

Claude Code 有两种工具执行模式：

模式 A：流式执行器（StreamingToolExecutor）

当特性门控 tengu_streaming_tool_execution2 开启时，工具在模型还在输出时就开始执行。

工作原理：

模型流式输出 tool_use 块 → streamingToolExecutor.addTool(block) 立即入队
执行器检查并发安全性 → 满足条件立即开始执行
模型继续输出 → 新工具继续入队和执行
模型输出完毕 → getRemainingResults() 等待剩余工具完成

并发安全规则：

1
2
3
4
5
6
7


canExecuteTool(isConcurrencySafe: boolean): boolean {
 const executing = this.tools.filter(t => t.status === 'executing')
 return (
 executing.length === 0 ||
 (isConcurrencySafe && executing.every(t => t.isConcurrencySafe))
 )
}

翻译成人话：

如果没有工具在执行 → 直接执行
如果当前工具和所有正在执行的工具都是并发安全的 → 并行执行
否则 → 等待

哪些工具是并发安全的？ 读操作通常是安全的（FileRead、Grep、Glob）。写操作通常不安全（Bash、FileEdit）。但 Bash 工具有特殊逻辑：某些只读命令（git status、ls）也可以并发。

Bash 错误的传播：如果一个 Bash 工具报错，它会通过 siblingAbortController.abort('sibling_error') 取消所有兄弟工具。这是因为 Bash 错误通常意味着环境出了问题，继续执行其他工具没有意义。

工具状态机：

1

queued → executing → completed → yielded

模式 B：批量执行器（toolOrchestration.ts）

如果流式执行未启用，工具在模型输出完毕后批量执行：

1
2
3


partitionToolCalls(toolUseBlocks)
 → 并发安全工具分到同一批（并行，最多 10 个）
 → 非安全工具各自一批（串行）

两种模式的接口是统一的——都产出 { message, newContext } 的异步迭代器——循环体不需要知道用的是哪种模式。

阶段四：附件收集

工具执行完成后，系统收集一系列"附件"为下一轮做准备：

排队命令：用户在工具执行期间输入的命令
Skill 发现：后台预取的新 Skill
记忆预取：后台发现的相关长期记忆
工具摘要：用 Haiku 模型异步生成的工具使用摘要（fire-and-forget，不阻塞下一轮）

1
2
3
4
5


// 工具摘要是异步的——这一轮生成，下一轮才消费
nextPendingToolUseSummary = generateToolUseSummary({
 tools: toolInfoForSummary,
 signal: toolUseContext.abortController.signal,
}).catch(() => null) // 失败也不阻塞

阶段五：终止或继续？

这是每轮的最终决策点：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


模型调用了工具？
 ├─ 是 → needsFollowUp = true → 继续循环
 └─ 否 → 进入终止检查

终止检查链：
 1. API 错误？→ 执行失败 Hook，返回 'completed'
 2. Stop Hook 阻止？→ 返回 'stop_hook_prevented'
 3. Stop Hook 报错？→ 注入错误消息，继续循环（reason: 'stop_hook_blocking'）
 4. Token Budget 未用完？→ 注入 nudge 消息，继续循环
 5. 超过 maxTurns？→ 返回 'max_turns'
 6. 以上都不是 → 返回 'completed'

Stop Hook 是一个有趣的机制：用户可以在设置中定义 Shell 命令，在模型每次完成回复后执行。Hook 可以检查模型的输出，决定是否允许继续。如果 Hook 返回错误，错误会被注入到消息历史中，模型会在下一轮看到这些错误并尝试修正。

Token Budget 是另一个控制点：当启用时，系统会检查本轮已消耗的 Token 是否达到预算的 90%。如果没有，注入一条 nudge 消息（“已用 X%，继续工作，不要总结”）让模型继续工作。还有衰减检测：如果连续 3+ 轮且每轮新增 < 500 Token，判定为"衰减"并停止——模型可能在兜圈子。

七层恢复机制

恢复机制是这个循环最精妙的部分。不是简单的 try-catch 重试，而是分层的、有针对性的自我修复。

前三层：预防性（在 API 调用前）

层	名称	触发	做什么
L1	Autocompact	Token > 上下文窗口 - 13K	AI 生成 9 段结构化摘要
L2	Snip	历史消息过长	裁剪旧消息
L3	Microcompact	工具结果冗余	按 tool_use_id 压缩

这三层在 API 调用前运行，目的是把上下文控制在安全范围内，避免触发 413 错误。

第四层：Context Collapse（413 第一道防线）

当 API 返回 413 错误后，系统首先尝试 Context Collapse——选择性归档消息。

1
2
3
4
5
6
7


if (state.transition?.reason !== 'collapse_drain_retry') {
 // 只尝试一次，避免双重 drain
 const drained = contextCollapse.recoverFromOverflow(messagesForQuery)
 if (drained.committed > 0) {
 continue // reason: 'collapse_drain_retry'
 }
}

关键细节：通过 transition.reason 检查避免重复 drain——如果上一轮已经是 collapse_drain_retry，就不再尝试，直接进入下一层。

第五层：Reactive Compact（413 最后手段）

如果 Context Collapse 也不够，触发紧急全量压缩：

1
2
3
4
5
6


if (!hasAttemptedReactiveCompact) {
 const result = reactiveCompact.tryReactiveCompact({...})
 if (result) {
 continue // reason: 'reactive_compact_retry'
 }
}

Reactive Compact 会：

计算需要清理的 Token 差距（actualTokens - limitTokens）
对整个对话生成紧凑摘要
智能恢复：压缩后自动恢复最重要的信息（最近读取的文件、当前 PR 文件等，最多 5 个文件，预算 50K Token）
对于 Media Size Error，可以剥离图片/PDF 后重试

死亡螺旋防护：413 恢复路径显式跳过 Stop Hook——因为模型从未产生有效输出，Hook 没有东西可评估。如果在这里运行 Hook，会产生"错误 → Hook 阻塞 → 重试 → 错误"的死亡螺旋。

1
2
3
4


// 代码注释原文：
// Do NOT fall through to stop hooks: the model never produced a valid response,
// so hooks have nothing meaningful to evaluate. Running stop hooks on
// prompt-too-long creates a death spiral: error → hook blocking → retry → error → …

第六层：Token 上限升级（8K → 64K）

当模型输出被截断（max_output_tokens 错误），系统的第一反应不是重试，而是升级限制：

1
2
3
4
5


if (capEnabled && maxOutputTokensOverride === undefined) {
 // 从默认的 8K 升级到 64K——单次升级，同一请求内立即重试
 maxOutputTokensOverride = 64_000 // ESCALATED_MAX_TOKENS
 continue // reason: 'max_output_tokens_escalate'
}

为什么默认只给 8K？ 这是一个成本优化。大多数回复在 8K 以内就能完成。只在真正需要时才升级到 64K，避免不必要的 Token 消耗。

第七层：多轮恢复（最多 3 次）

如果 64K 也不够，系统会注入恢复指令让模型从断点继续：

1
2
3
4
5
6
7
8


if (maxOutputTokensRecoveryCount < 3) { // MAX_OUTPUT_TOKENS_RECOVERY_LIMIT
 const recoveryMessage = createUserMessage({
 content: 'Output token limit hit. Resume directly — no apology, no recap...',
 isMeta: true, // 对 UI 不可见
 })
 maxOutputTokensRecoveryCount++
 continue // reason: 'max_output_tokens_recovery'
}

注意恢复指令的措辞：“Resume directly — no apology, no recap”——告诉模型直接从断点继续，不要浪费 Token 道歉或重复已输出的内容。

3 次恢复后如果仍然被截断，才浮出错误给用户。

循环的 10 种终止方式

终止原因	含义
`completed`	正常完成：模型没有调用工具
`aborted_streaming`	用户中断（Ctrl+C），模型还在输出
`aborted_tools`	用户中断，工具还在执行
`hook_stopped`	Hook 发出了停止信号
`stop_hook_prevented`	Stop Hook 显式阻止继续
`prompt_too_long`	413 错误，所有恢复手段用尽
`image_error`	图片处理错误
`blocking_limit`	Token 超过手动压缩阈值
`model_error`	未处理的模型调用异常
`max_turns`	超过最大轮次限制

6 种继续循环的原因：

Transition Reason	含义
`next_turn`	正常：模型调用了工具，需要继续
`collapse_drain_retry`	Context Collapse 释放了空间，重试
`reactive_compact_retry`	紧急压缩成功，重试
`max_output_tokens_escalate`	Token 上限从 8K 升到 64K
`max_output_tokens_recovery`	注入恢复指令，继续输出
`stop_hook_blocking`	Hook 报错，注入错误让模型修正
`token_budget_continuation`	Token 预算未用完，注入 nudge

一个完整的循环实例

把所有部分串起来，看一个"重构函数"任务的完整循环轨迹：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34


Turn 1: 用户输入 "帮我重构 parseConfig 函数"
 Phase 1: 无需压缩（对话刚开始）
 Phase 2: 模型调用 GrepTool 搜索 "parseConfig"
 Phase 3: GrepTool 并发执行（read-only，并发安全）
 Phase 4: 收集搜索结果
 Phase 5: needsFollowUp=true → continue (reason: 'next_turn')

Turn 2:
 Phase 1: 无需压缩
 Phase 2: 模型调用 FileReadTool 读取文件 + GlobTool 查找相关文件
 Phase 3: 两个工具并行执行（都是只读）
 Phase 4: 收集文件内容
 Phase 5: needsFollowUp=true → continue

Turn 3:
 Phase 1: 无需压缩
 Phase 2: 模型调用 FileEditTool 修改代码
 Phase 3: FileEditTool 串行执行（写操作，非并发安全）
 Phase 4: 记录文件变更
 Phase 5: needsFollowUp=true → continue

Turn 4:
 Phase 1: 无需压缩
 Phase 2: 模型调用 BashTool 运行测试
 Phase 3: BashTool 串行执行
 Phase 4: 收集测试结果
 Phase 5: needsFollowUp=true → continue

Turn 5:
 Phase 1: 无需压缩
 Phase 2: 模型输出最终回复（无工具调用）
 Phase 3: 跳过
 Phase 4: 后台生成工具摘要、提取记忆
 Phase 5: needsFollowUp=false → Stop Hook 通过 → 返回 'completed'

5 轮循环，4 次工具调用，零错误——最简单的路径。

但如果 Turn 3 的编辑触发了上下文溢出：

1
2
3
4
5
6
7
8


Turn 3 (异常路径):
 Phase 2: API 返回 413 → 暂扣错误
 Recovery L4: Context Collapse → 释放了 20K Token → continue (reason: 'collapse_drain_retry')
 
Turn 3 (重试):
 Phase 1: 上下文已缩小
 Phase 2: API 调用成功，模型继续编辑
 → 恢复正常流程

用户完全无感——系统自动压缩、重试，编辑继续。

可借鉴的模式

从这个循环中可以提取三个通用模式：

1. 分层恢复，而非统一重试

不同类型的错误需要不同的恢复策略。413 和 max_output_tokens 是完全不同的问题——前者需要压缩输入，后者需要扩展输出。用一个通用的 retry(n) 处理所有错误是不够的。

2. 暂扣错误，给恢复留窗口

不是"收到错误 → 立即报告"，而是"收到错误 → 先暂扣 → 尝试恢复 → 恢复失败才报告"。这个模式适用于所有有恢复能力的系统。

3. 状态重置的粒度

maxOutputTokensRecoveryCount 每轮重置，hasAttemptedReactiveCompact 每轮重置（除非是 Stop Hook 阻塞的重试）。恢复预算是按轮次而非全局分配的——长任务不会因为早期的错误耗尽后期的恢复能力。

下一篇预告

ReAct 循环的阶段一（上下文准备）提到了四级压缩和 Prompt Cache 分割——这是控制 Token 成本的核心。下一篇，我们将深入拆解：静态/动态 Prompt 分割如何最大化缓存命中率，以及四级压缩体系如何在保留关键信息的同时将 Token 消耗降到最低。

系列导航

篇	标题	核心问题
01	512K 行代码，一个终端里的 Agent Runtime	全景认知
02	ReAct 循环：while(true) 里的五个阶段与七层恢复（本篇）	系统心脏怎么跳
03	Prompt 缓存分割与四级上下文压缩	长对话怎么省钱
04	50 个工具的统一契约：Tool System 设计	Agent 能力怎么扩展
05	五层记忆体系：从短期到持久化	Agent 怎么记住事情
06	纵深防御：23 项安全检查与"不信任任何输入"	怎么让 Agent 安全
07	投机执行与自研状态管理：隐藏延迟的两个利器	怎么让用户感觉快
08	多 Agent 编排：三种执行模型与 Coordinator 模式	多个 Agent 怎么协作
09	在终端里造一个浏览器：自定义 Ink 渲染引擎	终端 UI 怎么做到 60fps
10	Bridge 与协议层：让 VS Code、Web、Mobile 共享一个 Claude	CLI 怎么变成平台
11	Skill、Plugin、Hook：三层扩展的设计谱系	怎么不改源码就扩展
12	回顾：从 Claude Code 中提炼的 10 个 Agent 工程模式	带走什么

解剖 Claude Code（一）：512K 行代码，一个终端里的 Agent Runtime

Thu, 02 Apr 2026 00:00:00 +0000

2026 年 3 月 31 日，Anthropic 的 Claude Code CLI 完整源码因 npm 包中的 .map 文件泄露。512,000 行 TypeScript，1,900 个文件——这不是一个 CLI 工具，这是一个藏在终端里的 AI Agent 运行时。

为什么要读这份源码？

市面上的 AI 编程工具不少：Cursor、Windsurf、Aider、Copilot CLI……但 Claude Code 是第一个被完整泄露源码的生产级 Agent Runtime。它不是一个简单的"调 API → 输出结果"的 wrapper——它有自己的渲染引擎、权限系统、多 Agent 协调器、五层记忆体系、四级上下文压缩，甚至还有投机执行机制。

读懂它，不只是在看 Anthropic 的内部工程，而是在看一个完整的 Agent 架构范本。

本系列共 12 篇，本篇是全景导读。

技术栈：一个看似奇怪的组合

层级	选型	为什么？
运行时	Bun	启动速度是 CLI 体验的生命线。Bun 比 Node.js 快 3-5 倍。`bun:bundle` 的 `feature()` API 实现编译期死代码消除——未启用的功能从构建产物中彻底消失
语言	TypeScript (strict)	50 万行代码没有类型系统是不可想象的
终端 UI	React + 自定义 Ink	声明式 UI + Yoga flexbox 布局，在终端里实现接近 IDE 的交互体验
CLI 解析	Commander.js	成熟稳定，类型安全
Schema	Zod v4	一套 Schema 同时用于运行时验证和 API JSON Schema 生成
搜索	ripgrep	代码搜索的事实标准
协议	MCP + LSP	标准协议集成外部工具和语言服务
遥测	OpenTelemetry	标准化可观测性
特性门控	GrowthBook	灰度发布、A/B 测试

这套组合的底层逻辑是：启动要快（Bun）、交互要好（React+Ink）、扩展要广（MCP/LSP）、安全要硬（TypeScript strict + Zod）。

值得注意的是，Claude Code 完全不依赖传统的代码索引——没有 Embedding 向量检索，没有 AST 分析，没有代码图谱。它纯靠大模型的推理能力配合 Grep/Glob 全局搜索来理解代码库。这是一个大胆的哲学选择：赌模型能力的增长速度会超过代码库的增长速度。

核心数据流：一次对话背后发生了什么

当你在 Claude Code 中输入一条消息，数据会经过以下管线：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43


用户输入
 │
 ▼
┌─────────────────────────────────────────────────┐
│ QueryEngine.submitMessage() │
│ ┌─────────────────────────────────────────┐ │
│ │ query.ts: while(true) — ReAct 循环 │ │
│ │ │ │
│ │ Phase 1: 上下文准备 │ │
│ │ → Snip / Microcompact / Autocompact │ │
│ │ │ │
│ │ Phase 2: 模型流式调用 │ │
│ │ → Anthropic API (streaming) │ │
│ │ │ │
│ │ Phase 3: 工具执行 │ │
│ │ → StreamingToolExecutor (并行) │ │
│ │ → 权限检查 → 沙箱执行 │ │
│ │ │ │
│ │ Phase 4: 附件收集 │ │
│ │ → 任务通知 / 记忆 / 文件变更 │ │
│ │ │ │
│ │ Phase 5: 终止或继续？ │ │
│ │ → 有工具调用？继续循环 │ │
│ │ → 无工具调用？结束 │ │
│ │ → 出错？七层恢复 │ │
│ └─────────────────────────────────────────┘ │
│ │
│ 错误恢复层: │
│ L1 Autocompact (80% 预警) │
│ L2 Snip (历史裁剪) │
│ L3 Microcompact (工具结果压缩) │
│ L4 Context Collapse (选择性归档) │
│ L5 Reactive Compact (413 紧急压缩) │
│ L6 Token 升级 (8K→64K) │
│ L7 多轮恢复 (最多 3 次) │
└─────────────────────────────────────────────────┘
 │
 ▼
┌─────────────────────────────────────────────────┐
│ Ink 渲染引擎 │
│ React Reconciler → Yoga 布局 → Screen Buffer │
│ → 增量 Diff → ANSI 输出 → 终端 │
└─────────────────────────────────────────────────┘

这个流程最值得注意的是：

模型调用和工具执行是并行的 —— StreamingToolExecutor 在模型还在输出时就已经开始执行已完成解析的工具调用。这不是等模型说完再跑工具，而是流水线式并行。
七层恢复不是简单重试 —— 每一层处理不同类型的故障。413 上下文溢出会触发压缩后重试；输出被截断会自动将 Token 上限从 8K 升至 64K；API 过载会指数退避。系统在各种异常下自我修复，而不是直接崩溃。
上下文压缩是分级的 —— 不是简单地"砍掉旧消息"，而是四级递进：轻量裁剪 → 缓存感知压缩 → AI 全量摘要 → 紧急压缩。每一级都尽可能保留更多有用信息。

五个维度看系统成熟度

维度一：ReAct 循环 — 系统心脏

query.ts 中的 while(true) 循环是整个系统的心脏，实现了经典的 ReAct（推理-行动）模式。

五个阶段，每轮都走一遍：

阶段	做什么	关键技术
上下文准备	裁剪旧消息、压缩工具结果	Snip + Microcompact + Autocompact 三级组合
模型流式调用	发送对话历史 + 系统提示 + 工具列表	流式输出、Prompt Cache 分割
工具执行	并行执行工具调用	StreamingToolExecutor 流水线并行
附件收集	任务通知、记忆提取、文件变更	后台 Agent 异步提取记忆
终止决策	根据模型行为决定循环或结束	七层恢复、Stop Hook

最精巧的设计在于流式工具执行器：模型还在生成第二个工具调用时，第一个工具已经在并行执行了。如果第一个工具是并发安全的（isConcurrencySafe: true），它甚至可以和其他并发安全工具同时运行。

七层恢复机制则是韧性设计的典范：

层	触发条件	恢复策略
L1	对话达到上下文窗口 80%	预警式自动摘要
L2	历史消息过长	轻量裁剪（Snip）
L3	工具结果冗余	缓存感知压缩（Microcompact）
L4	API 返回 413	选择性消息归档（Context Collapse）
L5	L4 失败	紧急全量压缩（Reactive Compact）
L6	输出被截断	Token 上限 8K→64K 单次升级
L7	L6 仍被截断	注入恢复指令，最多重试 3 次

系列第 2 篇将深入拆解这个循环的每个阶段和恢复机制。

维度二：五层记忆体系 — 超越上下文窗口

大多数 Agent 工具的"记忆"就是对话历史。Claude Code 构建了五层记忆体系，覆盖从毫秒到永久的全时间尺度：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


┌─────────────────────────────────────────────────┐
│ 第 5 层：Checkpoint（会话持久化） │
│ 关闭终端，下次打开完整恢复 │
│ JSONL 转录文件 + 元数据快照 │
├─────────────────────────────────────────────────┤
│ 第 4 层：摘要记忆 │
│ AI 生成的结构化对话摘要（9 个分区） │
│ 区别于简单截断，保留语义 │
├─────────────────────────────────────────────────┤
│ 第 3 层：长期记忆 │
│ ~/.claude/projects/<path>/memory/ │
│ 4 种类型：用户偏好 / 纠正反馈 / 工作约束 / 外部引用 │
│ 检索时用 LLM 做相关性判断，提取 Top-5 │
├─────────────────────────────────────────────────┤
│ 第 2 层：工作记忆 │
│ 7 种任务状态 / 投机执行状态 / 权限追踪 │
├─────────────────────────────────────────────────┤
│ 第 1 层：短期记忆 │
│ 当前会话消息列表（内存中） │
└─────────────────────────────────────────────────┘

长期记忆的设计尤其精巧：它不是一个笨重的向量数据库，而是本地目录下的 markdown 文件，按主题组织。检索时不是做 embedding 相似度搜索，而是把所有记忆的文件名和描述发给模型，让模型选出最相关的 5 个再读取全文。

这种"用 LLM 做检索"的方式看似低效，但在记忆数量可控（几十到几百个文件）的场景下非常实用——它避免了 embedding 模型的维护成本，同时利用了大模型的语义理解能力。

系列第 5 篇将深入拆解五层记忆体系。

维度三：安全纵深 — 六层防御，不信任任何输入

一个能执行 Shell 命令的 AI Agent，安全不是可选项，是生存条件。Claude Code 构建了六层纵深防御：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


┌─────────────────────────────────────────────────┐
│ 第 6 层：内容检测 │
│ 秘密/PII 检测，遥测隐私保护 │
├─────────────────────────────────────────────────┤
│ 第 5 层：路径校验 │
│ 路径遍历防护、符号链接检查 │
├─────────────────────────────────────────────────┤
│ 第 4 层：命令级验证 │
│ 纯 TS Bash 解析器，23 项安全检查 │
│ 50ms 超时 + 50K 节点预算防 DoS │
├─────────────────────────────────────────────────┤
│ 第 3 层：规则匹配 │
│ 8 来源权限规则：policy > managed > project > user │
├─────────────────────────────────────────────────┤
│ 第 2 层：权限模式 │
│ default / plan / auto / bypass │
│ Auto 模式：二阶段分类器决策 │
├─────────────────────────────────────────────────┤
│ 第 1 层：沙箱 │
│ 文件系统/网络级隔离 │
└─────────────────────────────────────────────────┘

几个硬核细节：

纯 TypeScript 写的 Bash 解析器（130KB）：生成 tree-sitter-bash 兼容的 AST，在执行前静态分析命令安全性。设置了 50ms 超时和 50K 节点预算，防止恶意构造的命令消耗解析资源。
23 项 Bash 安全检查：覆盖命令替换、注入攻击、Unicode 同形攻击、IFS 注入、brace 展开、heredoc 注入等攻击面。
解释器黑名单：Python、Node 等只允许 --version 检查，禁止在自动模式下执行任意脚本。
ZSH 危险命令黑名单：16 个可绕过安全检查的 Zsh 内建命令（zmodload、emulate、sysopen、zpty 等）被显式禁止。

这套体系的设计哲学是每一层都不信任上一层——即使沙箱被绕过，权限系统仍然在拦截；即使权限被绕过，Bash 解析器仍然在检查命令安全性。

系列第 6 篇将深入拆解完整的安全体系。

维度四：多 Agent 编排

Claude Code 不是单 Agent 工具。它支持三种 Agent 执行模型和一个编排层：

三种执行模型：

模型	实现	隔离方式	适用场景
子 Agent	`AgentTool` 生成	Git Worktree	独立的文件修改任务
同进程队友	`InProcessTeammateTask`	`AsyncLocalStorage`	需要共享内存的协作
远程队友	`RemoteAgentTask`	独立进程/远程会话	PR 审查、后台任务

Coordinator 模式：

当启用后，系统切换为"指挥者-执行者"架构：

Coordinator 只负责任务分解和结果汇聚
Worker 拥有完整工具集，独立执行
内置角色：General Purpose（通用）、Explore（只读探索）、Plan（只读规划）、Verification（破坏性验证）
Worker 间通过 SendMessageTool 通信，通过 Scratchpad 目录共享持久知识
任务完成后以 <task-notification> XML 标签的 user-role 消息通知 Coordinator

Git Worktree 隔离是一个精巧的设计：每个子 Agent 在独立的 Git Worktree 中工作，可以自由修改文件而不影响主工作区。用户确认后才合并变更；拒绝则直接删除 worktree。

系列第 8 篇将深入拆解多 Agent 架构。

维度五：可观测性与隐私

遥测栈：OpenTelemetry（Trace + Metrics + Logs）→ OTLP/Prometheus/BigQuery

三级隐私类型系统——这是最值得学习的设计之一：

1
2
3
4
5
6
7
8


// 第 1 级：安全元数据（工具名、计数、状态码）
AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS

// 第 2 级：PII 标记数据（文件路径、仓库 URL）
// 用 _PROTO_* 前缀路由到特权列
AnalyticsMetadata_I_VERIFIED_THIS_IS_PII_TAGGED

// 第 3 级：通用元数据（已净化的值）

类型名本身就是安全检查：当你写 AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS 时，这个冗长的类型名逼迫你在写代码时思考：“我确认这个值不包含代码或文件路径吗？” 这是把安全审查嵌入类型系统的优雅做法。

MCP 工具名默认脱敏为 'mcp_tool'，只有官方注册的 MCP 服务器才保留原始名称。工具输入截断到 512 字符/4KB，防止业务代码意外被遥测上传。

六大惊艳的工程设计（速览）

#	设计	核心思路	详见
1	Prompt 缓存分割	系统提示拆为静态（全局缓存）+ 动态（不缓存），极大提高 API 缓存命中率	第 3 篇
2	四级上下文压缩	Snip → Microcompact → Autocompact → Reactive Compact，压缩后智能恢复关键信息	第 3 篇
3	投机执行	在用户确认前，在 Overlay 文件系统中预执行。确认写入，拒绝丢弃	第 7 篇
4	23 项 Bash 安全检查	覆盖注入、替换、同形攻击等。解释器黑名单防止自动执行脚本	第 6 篇
5	自研状态管理	Zustand 风格轻量 Store，精准订阅防止 React Ink 级联重渲染	第 7 篇
6	工具延迟加载	超过 20 个工具时，不直接写入 system prompt，让模型自己搜索发现	第 4 篇

模块地图

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52


src/
├── query.ts ★ ReAct 循环（系统心脏）
├── QueryEngine.ts ★ 对话引擎入口
├── Tool.ts ★ 工具类型契约
├── tools.ts ★ 工具注册表
├── commands.ts 命令注册表
├── main.tsx 入口（Commander.js + React/Ink）
├── context.ts 上下文收集
├── cost-tracker.ts 费用追踪
│
├── tools/ ~50 个工具实现
│ ├── BashTool/ Shell 执行（最复杂，含 23 项安全检查）
│ ├── AgentTool/ 子 Agent 生成
│ ├── FileEditTool/ 文件编辑
│ ├── GrepTool/ 代码搜索
│ ├── MCPTool/ MCP 协议桥接
│ ├── SkillTool/ Skill 执行
│ └── ToolSearchTool/ 工具延迟加载
│
├── services/ 服务层
│ ├── api/ Anthropic API 客户端（多提供商）
│ ├── compact/ 四级上下文压缩
│ ├── mcp/ MCP 集成（5 种传输）
│ ├── extractMemories/ 后台记忆提取
│ └── analytics/ 遥测与隐私（三级类型系统）
│
├── coordinator/ 多 Agent 协调器
├── tasks/ 7 种任务类型
├── memdir/ 长期记忆目录
├── state/ 自研状态管理
│
├── ink/ 自定义 Ink 渲染引擎
│ ├── reconciler.ts React Reconciler
│ ├── layout/ Yoga 布局引擎
│ ├── events/ W3C 事件模型
│ ├── screen.ts Screen Buffer（Intern 池化）
│ └── termio/ 终端 I/O 解析
│
├── bridge/ IDE 集成（VS Code / JetBrains）
├── skills/ Skill 系统（6 种来源）
├── plugins/ Plugin 系统
├── hooks/ Hook 系统（6 类 × 24 种事件）
├── vim/ Vim 模式（状态机实现）
├── voice/ 语音输入
├── utils/
│ ├── permissions/ 权限引擎（8 来源规则）
│ ├── sandbox/ 沙箱适配器
│ ├── bash/ 纯 TS Bash 解析器
│ └── telemetry/ OpenTelemetry 集成
│
└── constants/
 └── prompts.ts 系统提示（6 级优先级）

一个关键哲学选择

最后值得讨论一个贯穿整个架构的哲学选择：Claude Code 完全不做代码索引。

没有 Embedding 向量数据库，没有 AST 解析，没有代码图谱，没有符号表。当模型需要理解一个代码库时，它就用 GrepTool 和 GlobTool 全局搜索。

这意味着：

冷启动零成本——不需要先索引再使用
永远是最新的——每次搜索都读实际文件
简单到不可能出错——没有索引就没有索引过期

但也意味着：

大型代码库可能效率低——每次搜索都是全局扫描
依赖模型的推理能力——需要模型知道搜什么、怎么缩小范围
Token 消耗更高——搜索结果直接进入上下文

这个选择在当前模型变强的趋势下是说得通的。模型越强，越擅长用最少的搜索找到目标。但在百万行级代码库中，这个策略是否还能 hold 住，是一个开放问题。

系列导航

篇	标题	核心问题
01	512K 行代码，一个终端里的 Agent Runtime（本篇）	全景认知
02	ReAct 循环：`while(true)` 里的五个阶段与七层恢复	系统心脏怎么跳
03	Prompt 缓存分割与四级上下文压缩	长对话怎么省钱
04	50 个工具的统一契约：Tool System 设计	Agent 能力怎么扩展
05	五层记忆体系：从短期到持久化	Agent 怎么记住事情
06	纵深防御：23 项安全检查与"不信任任何输入"	怎么让 Agent 安全
07	投机执行与自研状态管理：隐藏延迟的两个利器	怎么让用户感觉快
08	多 Agent 编排：三种执行模型与 Coordinator 模式	多个 Agent 怎么协作
09	在终端里造一个浏览器：自定义 Ink 渲染引擎	终端 UI 怎么做到 60fps
10	Bridge 与协议层：让 VS Code、Web、Mobile 共享一个 Claude	CLI 怎么变成平台
11	Skill、Plugin、Hook：三层扩展的设计谱系	怎么不改源码就扩展
12	回顾：从 Claude Code 中提炼的 10 个 Agent 工程模式	带走什么

下一篇，我们将深入 query.ts 中的 while(true) 循环，看看这个 Agent Runtime 的心脏是如何一拍一拍跳动的。