Cline Auto Compact 默认启用：长对话上下文压缩的触发原理与配置实践

本篇围绕 Cline 仓库中的一次变更说明（.changeset/proud-crabs-compact.md）展开：该变更为 IDE 扩展（npm 包名 claude-dev，见 apps/vscode/package.json）打了一个 patch 级别的版本升级——默认启用 Auto Compact，使长对话在接近模型上下文上限时自动压缩历史，而不是直接因超出 context limit 而失败。读完本文，你将掌握 Auto Compact 的工作流程、源码级的触发与预算计算机制、agentic/basic 两种压缩策略的差异，以及在 IDE 设置与 CLI 中调整、关闭该功能的具体方式。

这次变更做了什么

变更说明原文见 .changeset/proud-crabs-compact.md：

---
"claude-dev": patch
---

Enable Auto Compact by default so long chats automatically compress
conversation history instead of failing at the model context limit.
It can be disabled in Settings → Features → "Auto Compact".

三个要点：

1. 作用对象是 claude-dev 包，即 VS Code 扩展（在 apps/vscode/package.json 中 "name": "claude-dev"），且为 patch 级发布；
2. 行为变化是默认值：Auto Compact 从“需手动开启”变为“默认开启”，长对话将自动压缩历史，替代过去直接触顶报错的失败模式；
3. 保留了退出路径：可在 IDE 的 Settings → Features → "Auto Compact" 中关闭，对应实现位于 FeatureSettingsSection.tsx。

更完整的官方说明见 Auto Compact 功能文档。

Auto Compact 的工作流程

当对话接近模型的上下文窗口限制时，Cline 会：

1. 对迄今为止发生的每一件事创建一份综合摘要；
2. 保留所有技术细节、代码变更与决策；
3. 用摘要替换原有对话历史；
4. 从原地无缝继续。

触发时你会看到一次 summarization 工具调用，其费用展示方式与普通 API 调用一致。

为什么重要：在此机制出现之前，Cline 触达上下文上限时采用“截断旧消息”（rule-based truncation）的策略，会丢失重要上下文。切换为摘要压缩后：

• 所有技术决策与代码模式被保留；
• 文件变更与项目上下文保持完整；
• Cline 记住自己做过的所有事；
• 可以在更大的项目上长时间工作而不被打断。

官方文档同时给出使用建议：Auto Compact 在长任务中效果尤佳，配合结构化的任务列表（task list）有助于在多次摘要压缩之间保持进度。

源码级实现：何时触发、压缩到多少

Auto Compact 的默认开关最终落到 Cline Core SDK 的会话压缩配置上。核心实现在 sdk/packages/core/src/extensions/context/compaction.ts 的 createContextCompactionPrepareTurn 中，它构造了 agent runtime 在每次模型请求前调用的 prepareTurn 压缩回调：

• 总开关：config.compaction.enabled 不为 true 时直接返回 undefined，整条压缩管线不启用（见 compaction.ts#L273-L276）。也就是说，在设置里关闭 "Auto Compact" 后，压缩逻辑完全不参与每轮请求的准备阶段。
• 策略默认值：userCompaction?.strategy ?? "agentic"（见 compaction.ts#L285），未显式指定时走 LLM 摘要（agentic）策略。
• 触发条件：先估算本次请求的输入 token（系统提示 + 消息 + 工具定义，estimateRequestInputTokens），当 requestInputTokens >= maxInputTokens * COMPACTION_TRIGGER_RATIO 时判定需要压缩（见 compaction.ts#L313-L323）。模型的上限 token 数优先取 model.info.maxInputTokens / contextWindow（resolveEffectiveMaxInputTokens），取不到时使用 DEFAULT_MAX_INPUT_TOKENS 兜底。
• 压缩目标：resolveAutoRequestTargetTokens 决定压缩到多少 token——当对话已达到一定长度（user/assistant 轮次对 ≥ 5，且模型输出上限 maxTokens 小于 maxInputTokens）时，目标取 maxInputTokens * 0.5（LONG_CONVERSATION_TARGET_RATIO）；否则取触发线的一定比例 triggerTokens * DEFAULT_TARGET_RATIO（见 compaction.ts#L204-L217）。目标值随后扣除系统提示与工具定义的开销（translateRequestBudgetToMessages），转换为消息层预算。
• 模式区分：mode 支持 auto（自动）、manual（手动 /compact）、overflow_recovery（溢出恢复）。auto 模式下未达触发线则跳过；而 overflow_recovery 模式是当服务商已拒绝上一次请求（估算本身被证明不准）时的强制兜底——它使用确定性的 basic 策略，不依赖再一次成功的 LLM 调用（见 compaction.ts#L435-L498）。
• 可观测性：每次成功压缩与跳过都会写调试日志（token 前后值、利用率、消息数变化），并上报 task.compaction_executed / task.compaction_skipped 遥测事件（captureCompactionExecuted / captureCompactionSkipped），UI 上也会收到 auto-compacting / auto-compacted 状态通知（见 compaction.ts#L541-L589）。

两种压缩策略与降级链

从源码结构看，内建策略注册在 BUILTIN_COMPACTION_STRATEGIES（compaction.ts#L150-L175）：

• agentic（runAgenticCompaction）：调用 LLM 生成结构化摘要，支持通过 compaction.summarizer 自定义摘要器，并保留最近的 preserveRecentTokens（受目标预算约束）；
• basic（runBasicCompaction）：确定性的规则式压缩，不调用 LLM。

关键的健壮性设计是降级链：

• agentic 压缩若抛出异常（且非用户取消），记录警告后自动回退到 basic 压缩（见 compaction.ts#L502-L520）；
• 在 overflow recovery 模式下，即使配置了自定义 compact 回调，其结果也必须满足“非空、严格小于输入、不超过恢复目标 token”三重校验，否则仍回退 basic 压缩（见 compaction.ts#L464-L498）。

在 CLI 中查看与切换压缩模式

除了 IDE 的默认开关，CLI 侧暴露了更细粒度的压缩模式配置，实现见 apps/cli/src/utils/compaction-mode.ts：

Context compaction mode: agentic|basic|off (default: agentic)

模式	显示标签	映射到内部配置
agentic	LLM	{ enabled: true, strategy: "agentic" }
basic	Truncation	{ enabled: true, strategy: "basic" }
off	Off	{ enabled: false }

实现上（compaction-mode.ts#L33-L50）：

• buildCliCompactionConfig("off") 生成 { enabled: false }，与 SDK 侧 enabled !== true 即关闭的判定完全对应；
• 未显式指定模式时 getCliCompactionMode 返回默认值 agentic（DEFAULT_CLI_COMPACTION_MODE），即 CLI 同样默认启用 LLM 压缩；
• applyCliCompactionMode 负责把当前模式合并写回会话配置，off 时会剥离 strategy 字段只保留 enabled: false；
• getNextCliCompactionMode 支持在 agentic → basic → off 之间循环切换（如交互界面里的快捷键轮换）。

这与本次 changeset 的方向一致：IDE 端把 Auto Compact 默认打开，CLI 端则以 agentic 为默认策略，两者都保留了关闭通道。

成本考量

官方文档（auto-compact.mdx）说明：摘要过程复用对话已有的 prompt cache，因此成本与普通工具调用相当——大部分输入 token 已命中缓存，主要只为摘要生成（输出 token）付费，整体是划算的。

需要注意一个前提限制：对部分不支持该机制的模型，即使 Auto Compact 已启用，Cline 也会回退到标准的规则式上下文截断，这一点在 auto-compact.mdx 中有明确说明。

上下文恢复：压缩不等于丢失

Auto Compact 用摘要替换历史，但并不意味着上下文不可逆：

• 使用 checkpoints 可以把任务状态回滚到某次摘要发生之前；
• 编辑摘要工具调用之前的某条消息，效果类似——会话会恢复到那个时间点。

也就是说“你可以随时回滚，因此上下文并非真正丢失”。

小结

维度	说明	依据
变更内容	claude-dev（VS Code 扩展）patch：Auto Compact 默认开启	.changeset/proud-crabs-compact.md
关闭入口（IDE）	Settings → Features → "Auto Compact"	FeatureSettingsSection.tsx
关闭入口（CLI）	compaction mode 设为 off	compaction-mode.ts
触发机制	请求输入 token ≥ maxInputTokens × COMPACTION_TRIGGER_RATIO	compaction.ts
策略降级	agentic 失败 / 溢出恢复 → basic 确定性压缩	compaction.ts#L435-L520
回滚手段	checkpoints / 编辑历史消息	checkpoints.mdx

默认启用 Auto Compact 后，长对话的失败模式从“触顶即断”变为“自动摘要续作”，开发者通常无需额外配置即可受益；如果希望换用确定性压缩、或完全禁用该行为，可分别通过 IDE 功能设置或 CLI 的 off 模式关闭。