Kilo Context Condensing 完整指南：自动压缩、上下文剪枝与配置调优-平芜编程栈

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 State（Completed / 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为可选配置，取值1～100，表示在模型输入或上下文窗口用量的该百分比处触发压缩。

未声明上下文窗口的自定义模型不会被跟踪，自动压缩对它们不生效（详见自定义模型）。

在核心会话执行器中，这一判断被实现为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）；
快捷键：按<leader>c触发压缩。

默认值与配置

压缩行为默认开启，全部配置项及其默认值如下：

设置	默认值	作用
`compaction.auto`	`true`	到达可用窗口时自动压缩
`compaction.threshold_percent`	未设置	token 用量达到模型窗口该百分比时压缩
`compaction.prune`	`true`	清理 40K 最近窗口之外的工具输出
`compaction.tail_turns`	`2`	尽可能原样保留最近的用户轮次及其响应
`compaction.preserve_recent_tokens`	可用上下文的 25%，夹在 2,000 与 8,000 token 之间	原样保留的最近尾部 token 预算
`compaction.reserved`	`min(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.auto`	boolean	`true`	到达可用窗口时启用或禁用自动压缩
`compaction.threshold_percent`	number	未设置	可选百分比，取值 1～100。当 token 用量达到模型输入或上下文窗口的该比例时执行自动压缩，除非预留安全缓冲先行触发
`compaction.prune`	boolean	`true`	启用对 40K token 最近窗口之外旧工具输出的剪枝
`compaction.tail_turns`	number	`2`	压缩期间原样保留的最近用户轮次数，包括其后的 assistant 与工具响应
`compaction.preserve_recent_tokens`	number	可用上下文的 25%，夹在 2,000 与 8,000 token 之间	压缩后原样保留的最近轮次最大 token 预算
`compaction.reserved`	number	`min(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.tokens），reserved对应 v2 的buffer。

从实现细节看，compaction.ts 的settings函数会按文档顺序合并多个配置来源，最终默认auto: true、buffer: 20_000、tokens: 8_000（与文档表格完全一致）；CLI 侧的preserveRecentBudget（opencode 的 compaction.ts）则实现了"可用上下文的 25%，夹在 2,000～8,000 之间"的默认计算逻辑。

为压缩使用不同的模型

摘要生成可以使用比主 agent 更便宜或上下文更大的模型。为压缩配置一个专用 agent：

{ "agent": { "compaction": { "model": "anthropic/claude-haiku-4-5", }, }, }

若未配置压缩 agent，则使用当前会话的模型。相应地，压缩摘要的输出 token 上限被限制为SUMMARY_OUTPUT_TOKENS = 4_096（见 compaction.ts），避免摘要本身占用过多窗口。

环境变量覆盖

变量	作用
`KILO_DISABLE_AUTOCOMPACT=1`	强制`compaction.auto = false`
`KILO_DISABLE_PRUNE=1`	强制`compaction.prune = false`
`KILO_EXPERIMENTAL_OUTPUT_TOKEN_MAX`	覆盖默认 32,000 的输出 token 上限

这些变量在 flag.ts 与 flag.ts 中定义：前两者按"值为true或1"判定（truthy），后者要求正整数才生效（number），非法值会被忽略。