VT Code 上下文压缩与 Compaction 内幕：长会话如何不爆 context 窗口
VT Code 上下文压缩与 Compaction 内幕：长会话如何不爆 context 窗口
VT Code 是一个开源的 Rust 终端编码 Agent，内置了完整的上下文压缩（Context Compaction）引擎。当你和它连续对话几十轮、跑几十次工具调用后，普通的聊天机器人往往会因为塞满 context 窗口而"失忆"或直接报错；VT Code 通过"本地清理 + 自动压缩 + 两阶段摘要"三层机制，把超长会话稳稳控制在模型容量之内。本文带你读懂它的上下文压缩内幕，以及你能调哪些配置。
一、先搞懂：长会话为什么会爆 context 窗口？
编码 Agent 的每一轮对话，发给模型的都不只是你说的话，而是完整的历史记录：系统提示词、工具定义（schema）、每一轮工具调用的输入与输出（比如一次 read_file 可能返回几千 token 的文件内容）。
这意味着：
- 历史是"只涨不缩"的：会话越长，每轮请求越贵，直到撞上模型的 context 上限；
- 工具输出是最大的"撑场子"主力：一次文件读取、一次日志打印，就可能占掉几千 token。
所以"压缩"不是锦上添花，而是长会话能持续干活的生存技能。VT Code 的答案是：平时先做廉价的本地清理，实在撑不住了才动用大模型做整体摘要。
二、第一层防线：本地清理旧工具结果（零成本）
VT Code 默认开启了一项名为 tool_result_clearing 的机制，它的特点是不需要再调用一次大模型，纯粹在本地投影层面把过期的工具结果替换成占位符：
- 触发阈值默认 40,000 token：历史投影超过阈值就清理；
- 保护最近 2 个工具调用批次（
keep_tool_uses = 2、keep_recent_tool_batches = 2），保证刚读过的代码、刚跑的命令还在模型眼前； - 只清旧的不清新的：小结果如果清理后省不了几个 token，会原样保留，避免"清完反而更长"的尴尬。
本地清理的触发点还会根据实际容量自适应：运行时按 窗口容量 − 输出预留 − 系统/工具 schema 开销 算出历史预算，再把触发线压到预算的 3/5 以内，防止"清理刚生效，窗口就满了"的临界情况。
💡 对用户的直观效果：你连读 10 个文件、再问 5 个问题，前 8 个文件的原始内容会被精简掉，但最近的 2 轮工具结果完整保留——上下文变瘦了，模型却"记得住"当下在干什么。
三、第二层防线：自动 Compaction（三种策略自动路由）
本地清理不够时，VT Code 会触发真正的压缩（Compaction），把旧历史整体改写成一条 Previous conversation summary: 摘要消息，再拼上保留的最近消息继续对话。压缩策略由引擎按 provider/模型自动路由，你不用手动选：
| 策略 | 适用场景 | 工作方式 |
|---|---|---|
NativeStandalone |
OpenAI Responses 系、Vercel Gateway、xAI Grok | 调用服务端 /responses/compact 端点，由服务商直接返回压缩结果 |
NativeInline |
Anthropic Claude Opus 4.x / Sonnet 4.6+ | 在正常请求里挂载 compact_20260112 编辑，按阈值触发、压缩后暂停 |
Local |
其他所有 provider（OpenRouter、Gemini、本地模型等） | 万能兜底：fork 一份历史交给模型做一次性摘要，重建为"摘要 + 近期消息" |
关键设计细节：
- 失败不伤身：原生压缩失败或被拒绝时自动回退到
Local摘要；任何压缩失败都会保留原历史，只给出有界的错误说明； - 摘要不是瞎摘：压缩提示词明确要求区分"已完成 / 进行中 / 失败 / 未运行"的检查，保留精确命令、exit code、未解决的审批与用户限制——摘要质量直接决定压缩后任务能否续跑；
- 防溢出保险：单条超 4,096 token 的工具输出在摘要前先被替换成预览；若摘要请求本身也超窗，会按预算减半自动重试（
max_overflow_retries默认 1 次）。
四、第三层加速：两阶段（Two-Pass）后台压缩
大历史的摘要很慢？VT Code 用了"提前开火"（prefire）思路：
- Pass 1（后台异步）：先摘要历史的前 95%（token 权重占比），产物缓存起来；
- Pass 2（压缩时同步）：把 Pass 1 的摘要 + 剩余 5% 尾部改写成最终摘要，瞬间完成。
配合缓存指纹校验（历史前缀变了就作废缓存、切换模型也作废），既省延迟又不牺牲一致性。
五、上手指南：你只需要知道这些
手动压缩：会话中直接输入 /compact，UI 会显示 Compacting context...，完成后回报 Context compacted · {耗时} ({压缩前} -> {压缩后} 条消息, {模式})。还能用 /compact edit-prompt 自定义压缩提示词。
常用配置项（在 ~/.config/... 的 vtcode 配置或项目 .vtcode/ 中）：
| 配置项 | 默认值 | 作用 |
|---|---|---|
agent.harness.auto_compaction_enabled |
true |
自动压缩总开关 |
tool_result_clearing.trigger_tokens |
40000 |
本地清理触发阈值 |
tool_result_clearing.keep_recent_tool_batches |
2 |
受保护的最近工具批次 |
context.max_context_tokens |
0 |
会话安全上限（0 = 跟随模型容量） |
context.trim_to_percent |
60 |
超限时修剪到的目标占比 |
context.preserve_recent_turns |
6 |
永远保留的最近轮数 |
六、想深入？这些路径值得看
- 压缩引擎核心实现：crates/codegen/vtcode-core/src/compaction/mod.rs
- 策略路由定义：crates/codegen/vtcode-core/src/compaction/strategy.rs
- 两阶段压缩：crates/codegen/vtcode-core/src/compaction/two_pass.rs
- 官方 Compaction 设计文档：docs/development/compaction.md
- 全部上下文配置字段参考：docs/config/CONFIG_FIELD_REFERENCE.md
- 默认配置样例：crates/codegen/vtcode-config/data/default_config.toml
一句话总结：VT Code 的长会话不靠"更大上下文"续命，而是靠一套分层防线——40k token 的本地清理做日常保洁，75% 阈值的自动 Compaction 做深度收纳，两阶段后台摘要做速度优化，失败则无损回退。理解了这套机制，你也能放心让 Agent 陪你跑完一整天。