Kilo Context Condensing 完整指南自动压缩、上下文剪枝与配置调优【免费下载链接】kilocodeKilo is the all-in-one agentic engineering platform. Build, ship, and iterate faster with the most popular open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kilocode导读Context Condensing上下文压缩是 Kilo 应对模型上下文窗口上限的核心机制当对话因代码片段、文件内容与来回讨论而迅速膨胀时它会智能地总结历史会话在保留继续工作所需关键信息的同时显著降低 token 消耗。本文以官方文档为主线结合仓库源码packages/core/src/session/compaction.ts、packages/opencode/src/session/compaction.ts等深入讲解压缩的触发条件、默认值、kilo.jsonc配置方式与最佳实践。读完你将掌握如何让长会话不因上下文耗尽而中断并能按需调优压缩时机、保留尾部的 token 预算与预留缓冲。问题背景上下文窗口限制每个 AI 模型都有一个最大上下文窗口context window即一次能处理的文本总量上限。随着对话中不断加入代码片段、文件内容与多轮往返讨论你会逐渐逼近这个上限并可能遇到以下现象模型需要处理的 token 增多响应速度变慢因 token 用量上升API 成本随之增加最终触及上下文上限会话无法继续。Kilo 的 Compaction压缩系统正是为此设计它自动接管上下文管理让长会话可持续进行。解决方案Auto-Compaction 锚定摘要当对话接近 token 上限时压缩机制会启动产出一份锚定摘要anchored summary覆盖以下关键信息会话的整体目标overall goal过程中你给出的约束与偏好constraints and preferences进度、关键决策与下一步计划progress, key decisions, and next steps继续工作所必需的关键上下文critical context相关文件与目录relevant files and directories。这份摘要会替换更早的对话历史而 Kilo 在空间允许时会原样保留最近几轮对话。若会话已经被压缩过Kilo 会在原有摘要基础上进行更新而非推倒重来保留仍然相关的细节剔除已过时的信息。源码层面摘要的生成遵循一份固定结构模板。在 compaction.ts 中SUMMARY_TEMPLATE要求模型严格输出## Objective、## Important Details、## Work StateCompleted / Active / Blocked、## Next Move、## Relevant Files五个章节并规定保留精确的文件路径、符号、命令、错误字符串、URL 与标识符而 buildPrompt 则根据是否存在前次摘要决定提示词是从对话历史创建新锚定摘要还是更新已有摘要、合并新事实并移除过期细节。压缩的触发机制自动触发Kilo 会在每次响应后检查 provider 上报的用量并在联系 provider 之前估算即将发送的文本、系统指令与工具定义。当以下两个条件之一先被满足时即触发压缩用量达到compaction.threshold_percent指定的百分比剩余窗口触及预留安全缓冲reserved safety buffer。缓冲的取值取决于模型如何声明其限制当模型**单独声明了输入上限input limit**时缓冲默认为 20,000 token或模型最大输出大小取较小者当模型只声明单一上下文窗口时Kilo 改为预留模型的完整输出上限——最高可达 32,000 token。compaction.threshold_percent为可选配置取值1100表示在模型输入或上下文窗口用量的该百分比处触发压缩。未声明上下文窗口的自定义模型不会被跟踪自动压缩对它们不生效详见自定义模型。在核心会话执行器中这一判断被实现为compactIfNeeded源码 compaction.ts 先汇总system、messages、tools三部分的估算 token并与context - max(output, buffer)比较超出才调用compactAfterOverflow执行真正的摘要生成若压缩失败如 provider 报错或产出为空会安全地返回false不破坏会话。runner/llm.ts 在每轮开始前调用该判断压缩完成后会基于压缩后的历史重建请求继续执行。此外threshold_percent在 CLI 侧对应更精细的**预检preflight**机制overflow.ts 会按floor(context * percent / 100)计算硬上限并额外用 1.3 倍的估算系数校正 token 计数偏差FACTOR同时对媒体附件与加密的推理状态做专门折算尽量避免估算不足导致的中途溢出。上下文剪枝Context Pruning在轮次之间Kilo 还会执行一次更轻量的prune剪枝过程遍历40,000-token 最近窗口之外的、已完成的工具输出将其替换为占位文本[Old tool result content cleared]。剪枝是增量执行的因此大型工具输出不会永久占用空间即使还没到需要完整压缩的程度。该占位符在 message-v2.ts 中定义。剪枝与完整压缩相互配合剪枝处理大而旧的工具结果压缩处理整体超限的会话历史。手动压缩你可以在任意时刻主动触发压缩VSCode 扩展斜杠命令在聊天框输入/compact也可输入smol或condense检索到任务头部按钮点击当前任务标题栏中的压缩图标设置在Settings → Context中切换自动压缩开关。CLI / TUI斜杠命令在 TUI 中输入/compact别名/summarize快捷键按leaderc触发压缩。默认值与配置压缩行为默认开启全部配置项及其默认值如下设置默认值作用compaction.autotrue到达可用窗口时自动压缩compaction.threshold_percent未设置token 用量达到模型窗口该百分比时压缩compaction.prunetrue清理 40K 最近窗口之外的工具输出compaction.tail_turns2尽可能原样保留最近的用户轮次及其响应compaction.preserve_recent_tokens可用上下文的 25%夹在 2,000 与 8,000 token 之间原样保留的最近尾部 token 预算compaction.reservedmin(20,000, model_max_output_tokens)为下一轮预留的 token 余量若先于阈值触及则作为安全触发条件压缩配置写在你的kilo.jsonc文件中{ compaction: { auto: true, // 启用或禁用自动压缩 threshold_percent: 80, // 可选在模型窗口的 80% 处触发 prune: true, // 启用对最近窗口之外旧工具输出的剪枝 tail_turns: 2, // 压缩期间原样保留的最近用户轮次数 preserve_recent_tokens: 8000, // 最近尾部保留的最大 token 预算 reserved: 20000, // 预留 token 缓冲越小越晚触发越大越早触发 }, }各选项的类型、默认值与详细说明选项类型默认值说明compaction.autobooleantrue到达可用窗口时启用或禁用自动压缩compaction.threshold_percentnumber未设置可选百分比取值 1100。当 token 用量达到模型输入或上下文窗口的该比例时执行自动压缩除非预留安全缓冲先行触发compaction.prunebooleantrue启用对 40K token 最近窗口之外旧工具输出的剪枝compaction.tail_turnsnumber2压缩期间原样保留的最近用户轮次数包括其后的 assistant 与工具响应compaction.preserve_recent_tokensnumber可用上下文的 25%夹在 2,000 与 8,000 token 之间压缩后原样保留的最近轮次最大 token 预算compaction.reservednumbermin(20000, model_max_output)为下一轮预留的 token 余量。仅对单独声明输入上限的模型生效单一上下文窗口模型改用完整输出上限作为预留上述字段在配置 schema 中均有对应定义v1/config/config.ts 定义了auto、threshold_percent、prune、tail_turns、preserve_recent_tokens、reserved六个字段及其描述v2 的 config/compaction.ts 则以auto、prune、keep.tokens、buffer的形式承载等效语义。也就是说preserve_recent_tokens与tail_turns在运行时会换算为尾部保留的 token 预算对应 v2 的keep.tokensreserved对应 v2 的buffer。从实现细节看compaction.ts 的settings函数会按文档顺序合并多个配置来源最终默认auto: true、buffer: 20_000、tokens: 8_000与文档表格完全一致CLI 侧的preserveRecentBudgetopencode 的 compaction.ts则实现了可用上下文的 25%夹在 2,0008,000 之间的默认计算逻辑。为压缩使用不同的模型摘要生成可以使用比主 agent 更便宜或上下文更大的模型。为压缩配置一个专用 agent{ agent: { compaction: { model: anthropic/claude-haiku-4-5, }, }, }若未配置压缩 agent则使用当前会话的模型。相应地压缩摘要的输出 token 上限被限制为SUMMARY_OUTPUT_TOKENS 4_096见 compaction.ts避免摘要本身占用过多窗口。环境变量覆盖变量作用KILO_DISABLE_AUTOCOMPACT1强制compaction.auto falseKILO_DISABLE_PRUNE1强制compaction.prune falseKILO_EXPERIMENTAL_OUTPUT_TOKEN_MAX覆盖默认 32,000 的输出 token 上限这些变量在 flag.ts 与 flag.ts 中定义前两者按值为true或1判定truthy后者要求正整数才生效number非法值会被忽略。最佳实践何时手动压缩长会话在复杂任务上持续工作了较长时间后重大切换之前即将转向项目另一个方面时接近上限时若希望自己掌控摘要产出的时机可在自动触发前手动运行/compact。调优压缩触发时机希望在模型窗口的可预期比例处触发压缩时使用compaction.threshold_percent例如长任务设置80以更早生成摘要预留安全缓冲仍然生效可能比百分比阈值更早触发压缩。对单独声明输入上限的模型reserved是一个权衡较小值如10000→ 压缩触发更晚原始窗口内能进行更多轮对话但若单次响应大于缓冲有中途上下文溢出的风险较大值如40000→ 压缩触发更早溢出错误更少但两次摘要之间的有效会话更短。默认值~20K是为容纳完整大小的 assistant 响应加上工具输出而调优的。该设置对单一上下文窗口的模型无效——这类模型始终预留完整输出上限。维持上下文质量在初始任务中描述具体清晰的任务描述有助于生成更好的摘要使用 AGENTS.md结合 AGENTS.md 提供无需压缩的持久化项目上下文检查摘要压缩完成后摘要会显示在你的聊天历史中可据此确认关键信息是否保留。相关功能AGENTS.md —— 跨会话的持久化上下文存储Codebase Indexing —— 高效的代码搜索与检索。【免费下载链接】kilocodeKilo is the all-in-one agentic engineering platform. Build, ship, and iterate faster with the most popular open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kilocode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考