摘要
Claude Code 的上下文管理体系由四个相互衔接的子系统构成：按固定顺序组装的全局上下文、面向大体量工具结果的渐进式加载与磁盘分页、按成本与容量分级触发的三级压缩（snip、微压缩、全局压缩），以及基于只增不减磁盘日志的会话持久化与恢复。
本文整理自对其源码结构的技术分析，并以本地安装的 2.1.226 版发行产物做了字符串级验证：各机制的内部标识（microcompact、snipTokensFreed、autoCompactThreshold、九段式压缩提示词全部段落标题）均得到证实；具体数值参数未能在混淆产物中逐一定位，文中以「据源码分析」标注。
§ 1 · SCOPE & METHOD
范围与方法
分析对象为 Claude Code 的上下文管理子系统，不涉及权限模型与插件体系。Claude Code 以混淆后的 JavaScript 产物形式分发，其内部机制可经由还原分析与字符串检索加以考察。全文按两档标注证据强度：已证实——机制标识、遥测事件名或提示词文本可在 2.1.226 产物中直接命中；据源码分析——机制成立、但具体数值未能以字面量定位。
§ 2 · ASSEMBLY & LOOP
全局上下文的构成与请求循环
会话启动时，运行时将 CLAUDE.md、内置系统提示词与全部工具定义拼接为初始上下文。此后每轮响应包含三类内容块——思考过程、文本回复、工具调用 JSON——三者连同后续的工具执行结果全部写回窗口。工具结果与思考过程由此构成上下文增长的主要来源，后续全部管理机制都围绕这一增长压力展开。
§ 3 · LARGE RESULTS
大体量工具结果的处理
分页落盘（渐进式加载）。以联网搜索为例，单次返回可达数万字符。运行时不将其直接写入窗口，而是按最大页长分页、拼装为文本文件写入磁盘，仅将首页内容与文件路径插入上下文；模型如需查阅剩余内容，依据路径按需读取。产物中的 Output too large、saved to disk 与遥测事件 tool_result_persisted 证实了该落盘机制（已证实）。
小模型定向摘要。对网页抓取工具 WebFetch，运行时由小规模模型按主 agent 下发的任务提示词对长文本做定向摘要，仅摘要入窗。工具描述 Fetches content from a specified URL and processes it using an AI model 与多处 small, fast model 表述证实该路径（已证实）。
§ 4 · SUBAGENT ISOLATION
子 agent 的上下文隔离
需要并行探索时，主 agent 可派生若干子 agent。每个子 agent 的初始上下文由主 agent 撰写的任务描述与其自身系统提示词拼接而成；执行期间适用与主 agent 完全相同的上下文管理机制；任务完成后仅回传一段总结，全部执行轨迹随即丢弃。探索期的大量工具调用消耗因此被隔离在一次性的独立上下文中，代价是中间证据不可回溯，需由子 agent 在总结中自行保全关键信息。
§ 5 · THREE-TIER COMPACTION
三级压缩体系
当窗口接近容量上限时，运行时依次动用三种压缩机制，整体遵循「低损优先、有损殿后」的次序。snip 与微压缩均属对历史消息的改写；由于 Anthropic 提示缓存（prompt caching）按前缀匹配生效，改写历史会使缓存前缀失效、反而抬高成本，二者因此被安排在缓存失效之后触发——据源码分析，条件为距首次 API 调用超过约 60 分钟，与提示缓存的一小时扩展有效期相对应；遥测事件 tengu_time_based_microcompact 证实了时间维度触发路径（已证实）。全局压缩则由上下文长度触发。
全局压缩的触发与断路保护
据源码分析，运行时以字符数除以 4 估算 token 规模，对当前上下文总量与最近一次 API 调用新增量之和的估算值乘以三分之四的系数后，与约 167K token 的阈值比较，超出即启动压缩；该公式与阈值未能以字面量证实，但阈值变量 autoCompactThreshold 及配套字段确认存在（部分证实）。压缩失败累计超过 3 次后放弃本轮（据源码分析），构成断路保护；compact_failed 遥测与 isRecompactionInChain、willRetriggerNextTurn 等连锁压缩控制字段证实了失败记录与再压缩调度逻辑（已证实）。
willRetriggerNextTurn 字段表明压缩后仍超阈值时存在下一轮再触发的调度。§ 6 · PERSISTENCE & RESUME
会话持久化与恢复
全部上下文操作——内容新增、各级压缩、以及压缩前的原始上下文——均以只增不减（append-only）的形式持续写入磁盘日志。会话恢复因此成为一次纯粹的重放：进程退出或主机重启后，按序读取日志中的最新状态并附带对应的磁盘文件目录，即可还原至中断前的现场。磁盘容量远大于上下文窗口，渐进式加载与会话恢复共用同一存储事实——磁盘是上下文的外存层。
§ 7 · DESIGN NOTES
设计评述
综合来看，该体系呈现出三条清晰的工程原则。原分析对其给出了很高的工程评价，本文认同这一判断：上述机制单独看均非首创，但其组合覆盖了 agent 长程运行中上下文膨胀、成本控制与断点恢复的完整闭环，工程完成度较高，对同类系统具有直接的参考价值。
无损优先，有损殿后
分页落盘、定向摘要、snip 与微压缩要么可按路径找回原文，要么只裁剪低价值历史；唯一不可逆的全局压缩被置于触发序列末端，并配有断路保护。
成本感知的调度
对历史消息的改写与提示缓存的失效窗口对齐——避免为节省上下文而破坏缓存前缀，反使后续请求成本上升。
以磁盘为外存
分页、日志与恢复共用同一存储事实；上下文窗口被当作稀缺的一级资源来调度，热数据驻留窗口，冷数据留盘按需取回。
§ 8 · VERIFICATION
验证方法与局限
验证方式为对本地安装的 2.1.226 版发行产物（约 285 MB 打包 JavaScript）执行 strings 检索，以机制标识、遥测事件名与提示词文本的命中情况核对各项论断。
| 论断 | 验证状态 | 关键证据字符串 |
|---|---|---|
| snip 机制存在 | 已证实 | snipEnabled · snipTokensFreed |
| 微压缩保留最近工具结果 | 已证实 | compact_micro_keep_recent · keepRecent |
| 压缩存在时间触发路径 | 已证实 | tengu_time_based_microcompact |
| 九段式压缩提示词 | 已证实 | 九个段落标题全部命中 |
| 压缩后恢复最近文件 | 已证实 | post_compact_file_restore_success |
| 大体量结果落盘 | 已证实 | Output too large · tool_result_persisted |
| WebFetch 小模型摘要 | 已证实 | small, fast model |
| 压缩失败记录与再压缩调度 | 已证实 | compact_failed · isRecompactionInChain |
| 触发窗口 60 分钟 · 恢复 5 文件 · 熔断 3 次 | 据源码分析 | 数值未以字面量命中 |
| 阈值公式（字符 ÷4 · ×4/3 · 167K） | 部分证实 | 仅 autoCompactThreshold 变量命中 |
局限有三：字符串命中证实机制存在，但不覆盖其全部运行时行为，未做动态跟踪；混淆产物中的数值常量无法与特定机制可靠关联，所有数值均按源码分析结果转述并明确标注；版本迭代频繁，结论以 2.1.226 为基准。
SOURCES
信息来源
- 本地 Claude Code 2.1.226 发行产物字符串检索（2026-08-08 实测）
- Anthropic 官方文档：Prompt caching（提示缓存的前缀匹配语义与一小时扩展有效期）