learn-claude-code S06ContextCompact 上下文压缩：用 TaoToken 统一 Key 给 agentLoop 腾出空间

1. 当 agentLoop 把上下文撑爆时我在本地踩过的坑如果你正在本地跑 learn-claude-code 这类 Claude Code 风格的编程智能体大概率遇到过这个场景agentLoop 循环跑了几十轮工具调用结果一条条堆在 messages 数组里突然某次请求直接报上下文超限或者模型开始失忆前面读过的文件内容全被挤掉了。这不是你的代码写错了而是上下文窗口本身就有硬上限——learn-claude-code 的 S06ContextCompact 这一节讲的就是怎么在上下文逼近上限时主动腾出空间。ContextCompact 的核心思路是三层压缩microCompact 在每次 LLM 调用前把旧的 tool_result 替换成占位符autoCompact 在 token 超过阈值时保存会话记录并让模型总结后重建上下文manual compact 则允许用户或模型主动触发压缩。这套机制让无限会话在工程上变得可行。本文面向本地跑 Claude Code 类工具的开发者重点不是复述源码而是把 settings.json 里接入 TaoToken 统一 Key/API 通道的配置骨架给出来再演示一次 compact 触发前后的上下文长度对比让你能把压缩流程真正跑通、可复现。适合谁看已经在本地跑通 agentLoop、手里有 learn-claude-code 或类似 Java/Python 实现、想搞清楚压缩触发条件和验证方法的开发者。如果你还没跑通基础循环建议先看 S05SkillLoading 那篇把技能加载跑顺再回来。2. TaoToken 前置统一 Key 与 API 通道准备在讲压缩配置之前得先把模型调用通道理顺。learn-claude-code 的 agentLoop 每次压缩都要调一次 LLM 做总结如果 Key 管理混乱压缩流程会频繁因为鉴权或通道问题中断。TaoToken 在这里的作用是提供一个统一的 API 通道把模型调用收敛到一个 base_url 和一把 Key 上settings.json 里配置一次agentLoop 里所有 LLM 调用包括 autoCompact 的总结调用都走同一条路。你需要先拿到 Key。访问 https://taotoken.net/api-keys 创建一把 API Key注意保存时只显示一次。然后确认你的接入文档版本参考 https://taotoken.net/doc 里的 base_url 和模型名写法。TaoToken 的 API 端点是 https://taotoken.net/api这个地址不加任何查询参数直接作为 OpenAI 兼容的 base_url 使用。这里有个容易踩的坑learn-claude-code 的 Commons.getClient() 通常封装了一个 OpenAI 兼容客户端base_url 要填到 /api 这一层而不是填到 /v1。如果你填成 https://taotoken.net/api/v1部分 SDK 会拼成 /api/v1/chat/completions 导致 404。实测下来填 https://taotoken.net/api 让 SDK 自己拼路径最稳。注意Key 不要硬编码进源码提交到仓库。settings.json 或环境变量是更合适的存放位置后面配置骨架里会给出两种方式。3. 可复制配置settings.json 接入 TaoToken 统一 Key下面这份 settings.json 骨架可以直接抄字段名按你本地 learn-claude-code 的读取逻辑调整。核心是把 base_url、api_key、model 三个值统一到 TaoToken 通道agentLoop 里所有 LLM 调用包括 autoCompact 的总结请求都从这里读。{ llm: { provider: openai-compatible, base_url: https://taotoken.net/api, api_key: ${TAOTOKEN_API_KEY}, model: claude-sonnet-4-20250514, max_completion_tokens: 2000, timeout_seconds: 60 }, context_compact: { threshold_tokens: 3000, keep_recent_tool_results: 3, transcript_dir: ./transcripts, summary_model: claude-sonnet-4-20250514, summary_max_tokens: 2000 }, agent_loop: { cwd: ./workspace, max_iterations: 200 } }几个关键点说明。base_url 填 https://taotoken.net/api不要带 /v1。api_key 用 ${TAOTOKEN_API_KEY} 占位运行时从环境变量注入这样源码里不出现明文。context_compact 这一段对应 S06 的三层压缩参数threshold_tokens 就是源码里的 THRESHOLD示例给 3000你可以按模型窗口调大keep_recent_tool_results 对应 KEEP_RECENT保留最近 3 条 tool_result 不压缩transcript_dir 是 autoCompact 保存 transcript_*.jsonl 的目录。环境变量注入方式Linux/macOS 下export TAOTOKEN_API_KEY你的KeyWindows PowerShell$env:TAOTOKEN_API_KEY你的Key然后在 Java 侧读取配置时把 ${TAOTOKEN_API_KEY} 替换成 System.getenv(TAOTOKEN_API_KEY)。如果你用的是 Spring Boot 或类似框架Value(${TAOTOKEN_API_KEY}) 也能直接注入。配置好之后agentLoop 里的 LLM 调用应该统一走这个配置。以 S06 源码里的 autoCompact 为例它构造 ChatCompletionCreateParams 时用的 model 和 client都应该从这份配置读而不是散落在各处硬编码。这样压缩总结调用和正常对话调用走同一条 TaoToken 通道Key 轮换时只改一处。4. 验证请求compact 触发前后的上下文长度对比配置写完不算跑通得验证压缩真的生效。S06 源码里 Tokens.countDialogTokens(messages) 是判断是否触发 autoCompact 的依据我们就用它来做前后对比。先写一个最小验证脚本模拟 agentLoop 里消息堆积的过程。下面这段 Java 代码可以直接放进你的测试类import java.util.ArrayList; import java.util.List; public class CompactVerify { public static void main(String[] args) { ListChatCompletionMessageParam messages new ArrayList(); // 模拟 10 轮工具调用每轮塞入一个较大的 tool_result for (int i 0; i 10; i) { messages.add(ChatCompletionMessageParam.ofUser( ChatCompletionUserMessageParam.builder() .content(读取第 i 个文件).build())); messages.add(ChatCompletionMessageParam.ofAssistant( ChatCompletionAssistantMessageParam.builder() .content(我来读取).build())); // 模拟 2000 字符的 tool_result StringBuilder sb new StringBuilder(); for (int j 0; j 2000; j) sb.append(x); messages.add(ChatCompletionMessageParam.ofTool( ChatCompletionToolMessageParam.builder() .toolCallId(call_ i) .content(sb.toString()).build())); } int before Tokens.countDialogTokens(messages); System.out.println([压缩前] token 估算: before); // Layer 1: microCompact Compacts.microCompact(messages); int afterMicro Tokens.countDialogTokens(messages); System.out.println([microCompact 后] token 估算: afterMicro); // Layer 2: autoCompact超过阈值时 if (afterMicro 3000) { System.out.println([已触发自动压缩]); Compacts.autoCompact(messages); } int afterAuto Tokens.countDialogTokens(messages); System.out.println([autoCompact 后] token 估算: afterAuto); System.out.println([压缩后消息条数] messages.size()); } }跑之前确认 Tokens.countDialogTokens 和 Compacts.microCompact/autoCompact 的签名和你本地源码一致。S06 源码里 estimateTokens 对中文按每字符 1 token、英文按每 4 字符 1 token 估算所以 10 轮 × 2000 字符的英文 tool_result 大约产生 10 × 500 5000 token加上对话文本压缩前应该在 5000 以上。预期输出大致是这样[压缩前] token 估算: 5230 [microCompact 后] token 估算: 2180 [已触发自动压缩] [会话记录已保存: ./transcripts/transcript_1730000000.jsonl] [autoCompact 后] token 估算: 320 [压缩后消息条数] 2microCompact 把前 7 条旧 tool_result 替换成 [上一步: 已使用 readFile] 这类占位符token 从 5230 降到 2180。autoCompact 触发后会话记录落盘到 transcript_*.jsonlmessages 被清空重建为 2 条一条 user 消息带总结和 transcript 路径一条 assistant 确认消息token 降到 320 左右。这里有个验证细节autoCompact 里的总结调用会走 TaoToken 通道如果 Key 或 base_url 配错这一步会抛异常压缩流程中断。所以跑验证脚本时先确认总结调用能返回内容再看 token 对比。如果总结调用失败检查 base_url 是不是填成了 https://taotoken.net/api/v1以及环境变量 TAOTOKEN_API_KEY 是否在当前 shell 生效。想单独验证模型通道是否通可以用模型对话页面发一条测试消息确认 Key 有效后再跑压缩脚本能省不少排查时间。5. 本篇常见错排查压缩流程跑不通多数问题集中在几个地方。下面按现象列排查路径。现象一autoCompact 触发后 messages 没变少。检查 messages.clear() 之后是否真的只 add 了 2 条。S06 源码里重建上下文是 clear 后加 user assistant 两条如果你本地实现里 clear 之后又保留了旧消息引用token 不会降。另外确认 Tokens.countDialogTokens 统计的是重建后的 messages而不是压缩前的快照。现象二microCompact 没替换旧 tool_result。检查 toolMessages.size() KEEP_RECENT 这个判断。如果 tool 消息不足 3 条microCompact 直接 return什么都不做。验证脚本里至少要有 4 条以上 tool 消息才能看到替换效果。另外确认 tool_call_id 到 tool_name 的映射建对了占位符里的工具名是从 assistant 消息的 tool_calls 里取的映射建错会显示成 null。现象三总结调用报 401 或 404。401 是 Key 问题确认 TAOTOKEN_API_KEY 环境变量在当前进程可见不是只在另一个终端 export 了。404 是 base_url 路径问题填 https://taotoken.net/api不要带 /v1也不要带尾部斜杠。如果 SDK 报 model not found检查 model 字段是不是 TaoToken 支持的模型名参考接入文档里的模型列表。现象四transcript 文件没生成。autoCompact 里 Files.createDirectories(transcriptDirPath) 之后才写文件如果 transcript_dir 配置的路径没有写权限会静默失败或抛异常。检查 ./transcripts 目录是否可写以及 timestamp 是否用了秒级导致同一秒内多次压缩覆盖同名文件。S06 源码用 System.currentTimeMillis() / 1000高频压缩时建议加毫秒或随机后缀。现象五压缩后模型失忆继续执行时找不到之前的状态。这是总结质量的问题不是压缩机制的问题。autoCompact 的总结 prompt 要求包含已完成事项、当前状态、关键决策三部分如果总结太简略重建上下文后模型确实会丢细节。可以调大 summary_max_tokens或者在总结 prompt 里明确要求保留文件路径和函数名。transcript_*.jsonl 是完整历史必要时可以让模型按需回读。提示排查时先把 threshold_tokens 调小比如 500让 autoCompact 快速触发缩短验证周期。跑通后再调回正常值。6. 把压缩流程接进你的 agentLoop到这里配置骨架、验证脚本、排查路径都齐了。最后一步是把三层压缩真正接进 agentLoop 的循环体。S06 源码里的顺序是每次循环开头先 microCompact然后判断 token 是否超阈值决定是否 autoCompact正常 LLM 调用和工具执行之后检查是否有 manual compact 标记。接入时注意两个顺序问题。microCompact 必须在 token 统计之前执行否则你统计的是压缩前的值autoCompact 可能被误触发。manual compact 的标记要在工具执行阶段设置但不能立即执行压缩要等当前轮的工具结果都处理完否则会丢掉刚拿到的结果。S06 源码里用 continue 跳过 compact 工具的实际执行只设标记就是这个道理。如果你打算长期跑编码类 Agent压缩会频繁触发建议把 Coding Plan 纳入考虑统一管理调用配额和通道避免压缩总结调用和正常对话调用抢额度。接入文档里有完整的参数说明配置字段和本文的 settings.json 骨架能对上。压缩机制跑通之后你的 agentLoop 就能在上下文窗口内持续工作不会因为消息堆积而中断。transcript_*.jsonl 保留了完整历史需要回溯时随时能查。这套流程我在本地反复跑过最深的体会是阈值别设太激进留出总结调用的 token 余量否则压缩本身也会撞上限。