在针对 ClaudeCode 泄露源码的技术洞察中其针对上下文超过限制、Token 超长的处理机制非常值得学习。相比于传统“保留最近的、压缩舍弃老的”简单粗暴的做法ClaudeCode 采用了一套极具工程韧性的多层级、渐进式上下文压缩机制。1. 项目技术栈概览技术类别具体实现编程语言TypeScript运行时Bun主要框架React (用于 UI), Ink (用于 CLI)AI SDKAnthropic AI SDK构建工具bun:bundle2. 核心压缩策略概述该项目没有依赖传统的 RAG检索增强生成方案而是完全基于 Runtime 的执行状态通过以下四层渐进式压缩机制来处理上下文过长问题策略名称触发时机处理方式微型压缩 (Micro-Compact)单个工具返回结果过大时动态裁剪旧工具的结果限制图片 Token最大 2000工具结果持久化单个工具结果50,000 50,00050,000字符时将大体积文本存储到本地磁盘上下文中仅保留预览与引用自动压缩 (Auto-Compact)总上下文超过阈值默认 187K tokens调用大模型生成包含 9 大核心要素的结构化摘要进行替代头部截断 (Truncate Head)压缩请求本身遭遇 PTL (Prompt Too Long) 错误计算 Token 缺口精确按 API 轮次丢弃最老的历史消息3. 关键配置参数配置项默认值源码文件位置默认上下文窗口200,000200,000200,000tokenssrc/utils/context.ts:91M 上下文支持1,000,0001,000,0001,000,000tokens模型名含[1m]后缀时启用压缩输出预留20,00020,00020,000tokenssrc/utils/context.ts:12自动压缩阈值缓冲13,00013,00013,000tokenssrc/services/compact/autoCompact.ts:62警告阈值缓冲20,00020,00020,000tokenssrc/services/compact/autoCompact.ts:63错误阈值缓冲20,00020,00020,000tokenssrc/services/compact/autoCompact.ts:64阻塞限制缓冲3,0003,0003,000tokenssrc/services/compact/autoCompact.ts:65工具结果默认限制50,00050,00050,000字符src/utils/toolResultStorage.ts:13工具结果最大限制100,000100,000100,000tokenssrc/utils/toolResultStorage.ts:22单消息工具限制总和200,000200,000200,000字符src/utils/toolResultStorage.ts:49压缩后恢复预算50,00050,00050,000tokenssrc/services/compact/compact.ts:123每文件恢复限制5,0005,0005,000tokenssrc/services/compact/compact.ts:124每技能 (Skill) 限制5,0005,0005,000tokenssrc/services/compact/compact.ts:129Git 状态截断阈值2,0002,0002,000字符src/context.ts:204. 核心实现详解4.1 上下文窗口管理文件src/utils/context.tsTypeScript// 默认上下文窗口大小exportconstMODEL_CONTEXT_WINDOW_DEFAULT200_000;// 压缩操作的最大输出 tokenexportconstCOMPACT_MAX_OUTPUT_TOKENS20_000;// 获取模型上下文窗口大小exportfunctiongetContextWindowForModel(model:string,betas?:string[],):number{// 支持 1M 上下文通过 [1m] 后缀或实验性标志if(has1mContext(model)){return1_000_000;}returnMODEL_CONTEXT_WINDOW_DEFAULT;}4.2 自动压缩 (Auto-Compact) 系统文件src/services/compact/autoCompact.ts4.2.1 有效窗口计算Runtime 在计算有效窗口时会主动扣除为摘要输出预留的 Token防止溢出。TypeScriptconstMAX_OUTPUT_TOKENS_FOR_SUMMARY20_000;exportfunctiongetEffectiveContextWindowSize(model:string):number{constreservedTokensForSummaryMath.min(getMaxOutputTokensForModel(model),MAX_OUTPUT_TOKENS_FOR_SUMMARY,);letcontextWindowgetContextWindowForModel(model,getSdkBetas());// 支持环境变量覆盖constautoCompactWindowprocess.env.CLAUDE_CODE_AUTO_COMPACT_WINDOW;if(autoCompactWindow){constparsedparseInt(autoCompactWindow,10);if(!isNaN(parsed)parsed0){contextWindowMath.min(contextWindow,parsed);}}returncontextWindow-reservedTokensForSummary;}4.2.2 渐进式阈值管理以 200K 默认窗口为例Runtime 将 Token 状态精细划分为四个梯度建立动态防御线阈值类型计算公式默认值 (200K 窗口)执行动作自动压缩阈值有效窗口−13,000\text{有效窗口} - 13,000有效窗口−13,000187,000tokens自动触发大模型异步生成上下文摘要。警告/错误阈值压缩阈值−20,000\text{压缩阈值} - 20,000压缩阈值−20,000180,000tokensCLI 界面向用户抛出 Token 告警。阻塞限制有效窗口−3,000\text{有效窗口} - 3,000有效窗口−3,000197,000tokens强行拦截当前请求强制进入同步压缩状态。4.3 完整对话压缩与兜底Full Conversation Compaction文件src/services/compact/compact.ts当上下文极其臃肿甚至压缩请求本身都触发了系统的 PTL (Prompt Too Long) 错误时Runtime 会启动退避截断逻辑计算精确的 Token 缺口并按 API 轮次ApiRound丢弃最老的数据。TypeScriptexportfunctiontruncateHeadForPTLRetry(messages:Message[],ptlResponse:AssistantMessage,):Message[]|null{constgroupsgroupMessagesByApiRound(input);consttokenGapgetPromptTooLongTokenGap(ptlResponse);letdropCount:number;if(tokenGap!undefined){// 按 token gap 精确计算并丢弃旧的消息轮次letacc0;dropCount0;for(constgofgroups){accroughTokenCountEstimationForMessages(g);dropCount;if(acctokenGap)break;}}else{// 弹性后备方案直接丢弃 20% 的老消息组dropCountMath.max(1,Math.floor(groups.length*0.2));}// 返回截断后的消息队列...}4.4 结构化压缩提示词 (Compaction Prompt)文件src/services/compact/prompt.ts为了防止大模型在压缩自身上下文时“再次调用工具”导致死循环Runtime 注入了极其严格的拒绝声明并强迫其输出结构化摘要。TypeScriptconstNO_TOOLS_PREAMBLECRITICAL: Respond with TEXT ONLY. Do NOT call any tools. - Do NOT use Read, Bash, Grep, Glob, Edit, Write, or ANY other tool. - You already have all the context you need in the conversation above. - Tool calls will be REJECTED and will waste your only turn - Your entire response must be plain text: an analysis block followed by a summary block.;constBASE_COMPACT_PROMPTYour task is to create a detailed summary of the conversation so far... Your summary should include the following sections: 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 # 建议的下一步行动;4.5 微型压缩 (Micro-Compact) 与持久化文件src/services/compact/microCompact.tssrc/utils/toolResultStorage.ts针对单次代码文件读取FileRead或 Bash 终端返回的巨量日志Runtime 不会任由其污染上下文可压缩工具白名单限制为FileRead,Bash,Grep,Glob,WebSearch等工具。多媒体限制单张图片最高被强行压缩至2,0002,0002,000tokens。磁盘持久化当单次工具返回数据超过50,00050,00050,000字符或100,000100,000100,000tokens 时Runtime 将完整文本写入本地磁盘而在 Message 流中将其替换为[Tool Result Persisted to Disk. Preview: ... SHA256: ...]5. 架构对比ClaudeCode 方案 vs 传统 RAG 方案特性维度ClaudeCode 渐进式压缩方案传统 RAG (检索增强) 方案实现复杂度中等(纯内存与本地文件 IO 状态控制)较高(需要构建分片、向量化与检索链路)外部服务依赖无(零外部依赖完全内嵌在 Runtime 中)有(需要向量数据库或独立 Embeddings 服务)工程语义保留极高(大模型生成的摘要保留了完整的逻辑前后因果)一般(知识被切碎容易丢失代码上下文的连续性)弱网/离线表现优秀(在本地运行时内闭环完成)较差(高频检索带来额外的网络和计算开销)最佳适用场景长对话代码重构、复杂 Debug 追踪、多文件联动编辑静态知识库检索、企业大规模文档问答6. 技术总结与洞察ClaudeCode 的上下文管理本质上体现了成熟Agent Runtime的系统级设计思维不信任模型的无限窗口即使底座模型支持超长上下文Runtime 依然在187K187\text{K}187K处设立防线因为长窗口会导致模型注意力和执行准确率骤降。隔离副作用与数据分离区分“对话线索Messages”与“工具产物Artifacts/Tool Results”。大体积的产物应该沉降到磁盘上下文中只保留语义符号。容错收敛通过精密的 Token 缺口计算Token Gap确保即使极端情况下发生 PTL 错误系统也能通过精确的裁剪实现自我恢复而非崩溃。