第17章 紧凑化:突破上下文限制的对话摘要机制
第17章:紧凑化
紧凑化通过用摘要替换较早的对话来为长会话腾出空间,使会话能够突破模型上下文限制继续运行。
当会话接近模型上下文上限时,OpenCode 会总结当前的完整对话。同时,它会在摘要旁保留最近的对话(默认约 15,000 个 token),以确保精确的最新细节依然可用。
- 之前:[ 系统提示 ] [ 较早对话 ... ] [ 最近 15k ] [ 待处理工作 ] - 请求时:[ 系统提示 ] [ 较早对话 ... ] [ 最近 15k ] [ 摘要指令 ] - 之后:[ 系统提示 ] [ 较早+最近对话的摘要 ] [ 最近 15k ] [ 待处理工作 ]
发送完整对话有助于在提供商支持时,让摘要请求复用正常请求的提示词缓存。后续的紧凑化操作将基于该检查点之后的对话来更新现有摘要。
默认启用自动紧凑化: ```opencode.jsonc { "$schema": "https://opencode.ai/config.json", "compaction": { "auto": true, "keep": { "tokens": 15000 }, }, } ``` 紧凑化是有损的。如果需要精确的最近细节,请增加 keep.tokens;或者在自动紧凑化发生前手动请求紧凑化。
随时请求紧凑化,即使历史很短也可以: Terminal `opencode api post /api/session/ses_example/compact --data '{}'`
该 api 命令会检测并认证后台服务。响应仅确认请求已被接受,不会等待摘要生成完毕。监听 session.compaction.* 事件以了解何时完成。完整操作详情参见 API 参考。
| 规则 | 行为 | 时机 | | :--- | :--- | :--- | | 运行于 | 下一个安全点,仍在等待的提示之前 | | | 重复 | 一个紧凑化待处理时发出的请求会合并到其中 | | | 自动化 | 当 compaction.auto 为 false 时也可工作 | |
传入 id 可使精确重试具备幂等性。如果将相同 ID 复用于不同的请求,将返回冲突。 Terminal `opencode api post /api/session/ses_example/compact --data '{"id":"msg_compact_once"}'`
将紧凑化添加至任何 OpenCode 配置文件: ```opencode.jsonc { "$schema": "https://opencode.ai/config.json", "compaction": { "auto": false, "keep": { "tokens": 24000 }, "buffer": "20%", }, } ```
| 字段 | 默认值 | 行为 | | :--- | :--- | :--- | | auto | true | 在接近上下文限制时自动紧凑化;若提供商因请求过长拒绝,可恢复一次。手动紧凑化始终有效。 | | keep.tokens | 15000 | 摘要旁保留的近似最近对话量。数值越大,保留的细节越多,留给新工作的空间越少。 | | buffer | "15%", 最少 16k | 保持空闲的模型上下文窗口比例。当对话达到剩余部分时,自动紧凑化启动。数值越大,紧凑化越早发生。 |
keep.tokens 接受非负整数。
buffer 是各模型窗口的百分比,因此一个设置适配所有模型:
| 模型窗口 | "buffer": "20%" 紧凑化点 | | :--- | :--- | | 128k | ~102k | | 1M | 800k |
这是保持的空闲空间,而非紧凑化启动点:"20%" 意味着在充满 80% 时进行紧凑化。 接受 "1%" 到 "99%",包括 "12.5%" 这样的小数。 像 20000 这样的 token 计数也有效。相同的计数在较小的窗口中占比很大,在较大的窗口中占比很小。 如果 token 计数大于或等于模型窗口,则被忽略并应用默认值。
默认情况下,OpenCode 使用会话模型自行撰写摘要。设置 agents.compaction.model 可使用其他模型生成摘要: ```opencode.jsonc { "$schema": "https://opencode.ai/config.json", "agents": { "compaction": { "model": "anthropic/claude-sonnet-5-5" }, }, } ``` 如果该模型无法解析,OpenCode 将回退到会话模型。
自动紧凑化通常在撰写摘要时暂停会话。启用后台紧凑化后,OpenCode 会提前撰写摘要,并在需要紧凑化时换入: ```opencode.jsonc { "$schema": "https://opencode.ai/config.json", "experimental": { "background_compaction": true, }, } ``` - 在阈值前 60k tokens:当前对话摘要在后台开始生成 - 会话继续运行;摘要被保留,未被应用 - 阈值:保留的摘要被换入;其后的一切内容原样保留
在小上下文窗口中,摘要生成最迟始于上次紧凑化后的第一个响应与阈值之间的一半位置。
| 规则 | 行为 | 成本 | | :--- | :--- | :--- | | 缓存 | 摘要请求复用提示词缓存。如果会话在阈值前结束导致摘要从未使用,仍消耗 token。 | | | 等待 | 如果需要紧凑化时摘要仍在撰写,会话会等待其完成。 | | | 回退 | 如果自保留摘要以来的对话增长超过阈值的 40%,或模型、指令或对话起点发生变化,则正常紧凑化。 | | | 跳过 | 原生紧凑化不适用、刚切换模型后、或提供商因过长拒绝请求时不使用。在断开超过提示词缓存生命周期后,从下一个响应重新开始。 | | | 存储 | 保留的摘要存在于内存中,重启后丢失。 | |
某些提供商可以代你在其端压缩对话。通过 settings.compaction 按提供商或模型启用: ```opencode.jsonc { "$schema": "https://opencode.ai/config.json", "providers": { "openai": { "settings": { "compaction": { "type": "native" } }, "models": { "gpt-6.1-sol": { "settings": { "compaction": { "type": "summary" } } }, }, }, }, } ``` 模型设置覆盖提供商设置。native 使用提供商的紧凑化;summary 使用 OpenCode 自己的。
使用原生紧凑化时,OpenCode 将对话发送至提供商的紧凑化端点。提供商返回一个不透明的加密项来代替较早的对话。你的最近消息和附件(上限为 keep.tokens)与其一起保留: - 之前:[ 较早对话 ... ] [ 最近用户消息 ] - 之后:[ 加密检查点 + 最近用户消息 ]
| 主题 | 行为 | 支持情况 | | :--- | :--- | :--- | | 支持 | OpenAI Responses 模型。支持情况因部署和模型而异。 | | | 阈值 | 与摘要紧凑化相同的 auto 和 buffer 设置。手动请求也可用。 | | | 可移植性 | 加密检查点仅对同一提供商和模型有效。如果切换模型,会话将从原始对话继续。 | | | 过长 | 如果提供商因过长拒绝紧凑化,OpenCode 会用较小的请求重试,不会切换为摘要。 | |
摘要结构化设计,以便其他智能体可以从中接手工作: ```markdown ## 目标 完成身份验证迁移。
## 下一步行动 - 更新回调处理器。 - 验证登录流程。 ``` 它涵盖目标和需求、决策、已完成和进行中的工作、障碍和下一步行动,以及相关文件。在摘要旁保留的最近对话中,长工具输出会被缩短,附件数据会被简短描述替换。 紧凑化后,指令文件的当前版本成为会话的基准;见“指令”章节。
| 限制 | 结果 | | :--- | :--- | | 模型 | 摘要紧凑化遵循 agents.compaction.model;否则使用会话模型。原生紧凑化始终使用会话模型。 | | 历史 | 紧凑化需要替换的较早对话。如果请求主要由固定的指令和工具架构组成,无法腾出空间。 | | 大小 | 如果要紧凑化的对话本身过长,OpenCode 发送缩短的文本版本,可能会遗漏最旧的交流。 | | 恢复 | 因过长被拒绝的请求会紧凑化并重试一次。第二次拒绝返回错误。 | | 存储 | 即使不再发送给模型,较早的消息仍会保留存储。 |
例如,紧凑化在此处无用: 128k 上下文 = 120k 固定指令和工具 + 8k 对话
V1 使用尾部轮次和修剪行为。V2 使用摘要和 compaction.keep.tokens: ```jsonc { "compaction": { "keep": { "tokens": 15000 } } } ``` 本页的设置和行为适用于 V2。