一、前言
上一节课我们讲了上下文管理的基础策略（截断、优先级排序），但这些策略有一个明显的缺陷：简单截断会丢失有用信息，而完全保留又会导致Token超限。
Claude Code的核心亮点之一，就是“三层上下文压缩机制”——它不是简单的“删减”，而是“信息提纯”，在保证Agent能记住关键信息的前提下，将上下文压缩到合理长度，兼顾性能和效果。
本节课我们深入拆解这三层压缩的设计逻辑、实现细节，以及触发机制，这也是工业级Agent与普通Agent的核心区别之一。
二、三层压缩的核心设计思想
核心原则：从浅到深、从快到慢、从无损耗到有损耗，优先使用低成本、无损耗的压缩方式，只有在必要时才使用高成本、有损耗的压缩，最大限度保证信息完整性和性能。
三层压缩的触发顺序：微压缩 → 会话压缩 → 全量压缩，只有当前一层压缩无法将Token降到阈值以下时，才触发下一层。
触发阈值：Token占用达到93%（可配置），由TokenTracker监控触发。
三、第一层：微压缩（Micro Compact）—— 本地快速压缩（无API调用）
1. 核心特点
- 无API调用：纯本地字符串处理，速度最快（毫秒级）；
- 无信息损耗：只截断冗余的工具结果，不修改核心信息；
- 适用场景：上下文轻度膨胀，主要是工具结果过多导致Token超限。
2. 实现逻辑（Claude Code源码解析）
微压缩的核心类是com.claudecode.core.compact.MicroCompact，其逻辑是“按时间和数量截断工具结果”：
public class MicroCompact implements Compressor { // 保留最近的工具结果数量（默认6个） private static final int MAX_TOOL_RESULTS = 6; // 时间阈值（默认10分钟），超过该时间的工具结果只保留2个 private static final long TIME_THRESHOLD = 10 * 60 * 1000; // 10分钟 @Override public CompactionResult compact(ConversationMemory memory) { List<ToolResult> toolResults = memory.getToolResults(); int originalSize = toolResults.size(); // 1. 按时间筛选：超过10分钟的工具结果，只保留最近2个 List<ToolResult> recentResults = new ArrayList<>(); long currentTime = System.currentTimeMillis(); for (ToolResult result : toolResults) { if (currentTime - result.getTimestamp() <= TIME_THRESHOLD) { recentResults.add(result); } } // 超过10分钟的结果，保留最近2个 if (recentResults.size() < 2) { recentResults.addAll(toolResults.subList(Math.max(0, toolResults.size() - 2), toolResults.size())); } // 2. 按数量筛选：保留最近6个工具结果 if (recentResults.size() > MAX_TOOL_RESULTS) { recentResults = recentResults.subList(recentResults.size() - MAX_TOOL_RESULTS, recentResults.size()); } // 3. 更新记忆中的工具结果 memory.setToolResults(recentResults); // 计算压缩效果 int compressedSize = recentResults.size(); int reducedCount = originalSize - compressedSize; return new CompactionResult("微压缩完成", reducedCount, false); } }3. 关键设计点
- 时间感知：近期的工具结果更可能被后续推理使用，所以保留更多；远期结果只保留少量核心；
- 只压缩工具结果：不触碰系统提示词、用户目标、历史对话，保证核心信息不丢失；
- 无API调用：避免因压缩增加LLM成本和延迟。
四、第二层：会话压缩（Session Memory Compact）—— AI摘要压缩（1次API调用）
1. 核心特点
- 有API调用：调用LLM对历史对话和工具结果进行摘要，中等速度（秒级）；
- 低信息损耗：LLM会提炼核心信息，删除冗余描述，保留关键数据；
- 适用场景：微压缩后Token仍超限，上下文包含大量冗余的历史对话和工具结果。
2. 实现逻辑（Claude Code源码解析）
会话压缩的核心类是com.claudecode.core.compact.SessionMemoryCompact，其逻辑是“让LLM生成上下文摘要”：
public class SessionMemoryCompact implements Compressor { // 摘要后的Token范围（10K-40K） private static final int MIN_SUMMARY_TOKENS = 10000; private static final int MAX_SUMMARY_TOKENS = 40000; // LLM客户端（用于生成摘要） private final LlmClient llmClient; @Override public CompactionResult compact(ConversationMemory memory) { // 1. 提取需要压缩的内容（历史对话+工具结果） String contentToCompact = buildContentToCompact(memory); int originalTokens = tokenizer.countTokens(contentToCompact); // 2. 调用LLM生成摘要（提示词工程很关键） String prompt = buildSummaryPrompt(contentToCompact); String summary = llmClient.generateSummary(prompt); // 3. 校验摘要长度，确保在合理范围 int summaryTokens = tokenizer.countTokens(summary); if (summaryTokens < MIN_SUMMARY_TOKENS) { summary = addDetails(summary, memory); // 补充细节 } else if (summaryTokens > MAX_SUMMARY_TOKENS) { summary = truncateSummary(summary); // 进一步截断 } // 4. 更新记忆：用摘要替换原始历史对话和工具结果 memory.setHistory(List.of(summary)); memory.setToolResults(List.of()); // 工具结果已融入摘要 // 计算压缩效果 int reducedTokens = originalTokens - summaryTokens; return new CompactionResult("会话压缩完成", reducedTokens, true); } // 构建需要压缩的内容 private String buildContentToCompact(ConversationMemory memory) { StringBuilder content = new StringBuilder(); content.append("历史对话：").append(memory.getHistory()).append("\n"); content.append("工具结果：").append(memory.getToolResults()).append("\n"); return content.toString(); } // 构建摘要提示词（关键：告诉LLM如何提炼核心信息） private String buildSummaryPrompt(String content) { return "请你作为AI助手，对以下内容进行摘要，要求：" + "1. 保留用户的核心目标和所有关键工具结果数据；" + "2. 删除冗余的对话和重复的描述；" + "3. 保持逻辑连贯，让后续推理能基于摘要继续推进任务；" + "4. 摘要长度控制在10K-40K Token之间。" + "需要摘要的内容：" + content; } }3. 关键设计点
- 提示词工程：摘要的质量取决于提示词，必须明确告诉LLM“保留什么、删除什么”；
- 摘要范围控制：避免摘要过短（丢失信息）或过长（压缩无效）；
- 核心信息保留：系统提示词和用户目标不参与压缩，只压缩历史对话和工具结果。
五、第三层：全量压缩（Full Compact）—— 兜底压缩（多次API调用）
1. 核心特点
- 多次API调用：对整个上下文（除系统提示词）进行全量重写，速度最慢（数十秒）；
- 一定信息损耗：优先保留用户目标和核心工具结果，删除所有非必要信息；
- 适用场景：会话压缩后Token仍超限，属于极端情况（如长时间运行、大量工具调用）。
2. 实现逻辑（Claude Code源码解析）
全量压缩的核心类是com.claudecode.core.compact.FullCompact，其逻辑是“按API轮次分组，逐步丢弃非核心信息”：
public class FullCompact implements Compressor { // 熔断器：连续3次压缩失败，停止压缩（防止无限调用API） private static final int MAX_RETRY = 3; private final LlmClient llmClient; private int retryCount = 0; @Override public CompactionResult compact(ConversationMemory memory) { if (retryCount >= MAX_RETRY) { return new CompactionResult("全量压缩失败（熔断器触发）", 0, false); } try { // 1. 提取全量上下文（除系统提示词） String fullContext = buildFullContext(memory); int originalTokens = tokenizer.countTokens(fullContext); // 2. 按API轮次分组（每轮调用为一组） List<String> contextGroups = groupByApiRound(fullContext); // 3. 逐步丢弃早期非核心分组，生成全量摘要 List<String> keptGroups = new ArrayList<>(); int currentTokens = 0; // 从后往前保留分组（近期分组更重要） for (int i = contextGroups.size() - 1; i >= 0; i--) { String group = contextGroups.get(i); int groupTokens = tokenizer.countTokens(group); if (currentTokens + groupTokens <= MAX_SUMMARY_TOKENS) { keptGroups.add(0, group); // 插入到前面，保持顺序 currentTokens += groupTokens; } else { // 对当前分组进行摘要，再尝试加入 String groupSummary = llmClient.generateSummary("提炼以下内容的核心信息：" + group); if (currentTokens + tokenizer.countTokens(groupSummary) <= MAX_SUMMARY_TOKENS) { keptGroups.add(0, groupSummary); currentTokens += tokenizer.countTokens(groupSummary); } else { break; // 无法再加入，停止保留 } } } // 4. 生成最终全量摘要，更新记忆 String fullSummary = String.join("\n", keptGroups); memory.setHistory(List.of(fullSummary)); memory.setToolResults(List.of()); // 计算压缩效果 int reducedTokens = originalTokens - tokenizer.countTokens(fullSummary); retryCount = 0; // 重置重试次数 return new CompactionResult("全量压缩完成", reducedTokens, true); } catch (Exception e) { retryCount++; return new CompactionResult("全量压缩失败，重试次数：" + retryCount, 0, false); } } // 按API轮次分组（每一次LLM调用为一轮） private List<String> groupByApiRound(String fullContext) { // 解析上下文，按"API Round X"分组，逻辑略... return new ArrayList<>(); } }3. 关键设计点
- 熔断器保护：避免因LLM异常导致多次无效API调用，浪费成本；
- 分组保留：按API轮次分组，优先保留近期分组，符合Agent的推理逻辑；
- 兜底策略：只有在前面两层压缩无效时才触发，是最后的保障。
六、三层压缩的触发流程（总结）
TokenTracker监控Token数量 → 达到93%阈值 ↓ 调用AutoCompactManager.autoCompactIfNeeded() ↓ 1. 先调用MicroCompact（微压缩） ↓ 压缩后Token仍超限？ 2. 再调用SessionMemoryCompact（会话压缩） ↓ 压缩后Token仍超限？ 3. 最后调用FullCompact（全量压缩） ↓ 压缩后仍超限？ 触发异常，提示用户“上下文过长，无法继续执行”七、实操练习：实现简单的微压缩和会话压缩
结合本节课所学，实现微压缩（本地截断）和会话压缩（简化版，用固定摘要模拟LLM调用）。
public class SimpleCompactManager { // 微压缩：保留最近3个工具结果 public List<String> microCompact(List<String> toolResults) { if (toolResults.size() <= 3) { return toolResults; } // 保留最近3个 return toolResults.subList(toolResults.size() - 3, toolResults.size()); } // 会话压缩：简化版，模拟LLM摘要 public String sessionCompact(List<String> history, List<String> toolResults) { // 模拟LLM摘要，提炼核心信息 StringBuilder summary = new StringBuilder(); summary.append("用户目标：帮我写一个字符串反转工具类\n"); summary.append("工具执行记录：\n"); for (String result : toolResults) { if (result.contains("读取文件")) { summary.append("- 读取文件成功，确认项目为Spring Boot架构\n"); } else if (result.contains("编码规范")) { summary.append("- 检查编码规范，符合要求\n"); } } summary.append("历史对话：用户要求编写工具类，Agent已完成前期准备\n"); return summary.toString(); } // 测试 public static void main(String[] args) { SimpleCompactManager manager = new SimpleCompactManager(); // 测试微压缩 List<String> toolResults = new ArrayList<>(); toolResults.add("读取文件1成功"); toolResults.add("读取文件2成功"); toolResults.add("读取文件3成功"); toolResults.add("读取文件4成功"); List<String> compactedTools = manager.microCompact(toolResults); System.out.println("微压缩后工具结果：" + compactedTools); // 测试会话压缩 List<String> history = new ArrayList<>(); history.add("用户：帮我写一个字符串反转工具类"); history.add("Agent：好的，我需要先读取你的项目结构"); history.add("Agent：已读取文件，正在检查编码规范"); String summary = manager.sessionCompact(history, compactedTools); System.out.println("\n会话压缩后摘要：" + summary); } }八、本课重点总结
1. 三层压缩的核心是“从浅到深、兼顾性能和信息完整性”，避免简单截断导致的信息丢失；
2. 微压缩（本地、无损耗）→ 会话压缩（AI摘要、低损耗）→ 全量压缩（兜底、有损耗），逐步升级；
3. 关键设计点：时间感知、提示词工程
下节课预告
第05课：工具调用系统设计（Tool Calling）—— Agent的“手脚”，如何设计可扩展的工具系统，让Agent能执行文件操作、Shell命令、网络搜索等，对应tool包下的接口和实现类源码解析。
、熔断器保护，这也是Claude Code压缩机制的优势所在。
