Context Compression

上下文压缩（P7 三级防线）

🧠 Agent 内核 · 🏠 首页 › Context-Compression

---

📑 本页目录

• 1. 三级流水线
• 2. 各层组件
• 3. 永不压缩的部分
• 4. 相关配置（两套口径必须对齐）
• 5. 事件与持久化
• 6. 排查技巧
• 7. 相关页面

长任务的死穴是上下文窗口。两条执行路径（Agent 引擎 · 任务编排器） 共享同一套 HybridCompressor，由 TokenEstimator 统一估算水位，逐级触发。

1. 三级流水线

flowchart TD
    IN["新工具输出 / 新一轮迭代"] --> W{"水位检查<br/>TokenEstimator > 上下文 × 80% ?"}
    W -- 否 --> KEEP["保持原样"]
    W -- 是 --> C1["Layer 1 · ToolOutputTruncator（零成本 · 永远在跑）<br/>JSON → 保头 + 尾 200 字符（闭合结构）<br/>列表多于 20 短行 → 保首 15 + 尾 10 行<br/>read_file 类 → 只保头<br/>默认 → 头 1200 + 尾 600 字符 + 省略标注"]
    C1 --> W2{"仍超阈值？"}
    W2 -- 否 --> DONE1["完成"]
    W2 -- 是 --> C2["Layer 2 · SlidingWindowCompressor（零成本）<br/>保系统提示 + 最近 N 轮<br/>中段折叠为单条规则摘要"]
    C2 --> W3{"仍超阈值？"}
    W3 -- 否 --> DONE2["完成"]
    W3 -- 是 --> C3["Layer 3 · LlmSummaryCompressor（一次额外 LLM 调用）<br/>中段结构化摘要（Task / Progress / State / Key Data ≤400 词）<br/>失败自动回退规则摘要"]

Loading

设计要点：成本递增、收益递减时停下。前两层零成本，第三层要花一次 LLM 调用， 因此只在真需要时用，且失败自动回退到规则摘要 —— 压缩本身绝不能成为新的失败源。

2. 各层组件

层	组件	成本	策略	位置
L1	ToolOutputTruncator	0	按内容形态（JSON / 长列表 / 文件内容 / 默认）智能截断	每次工具返回后即跑
L2	SlidingWindowCompressor	0	保留系统提示 + 最近 N 轮，中段折叠为规则摘要	迭代边界检查后
L3	LlmSummaryCompressor	1 次 LLM 调用	中段结构化摘要（≤400 词），失败回退规则摘要	L2 仍不够时
—	HybridCompressor	—	编排三者 + 发射 ContextCompressed 事件	两条执行路径共用
—	TokenEstimator	—	token 估算（不依赖 tokenizer 精确值）	水位唯一的裁决者

3. 永不压缩的部分

Important

以下四类内容永远不会被压缩： ① 系统提示；② 最新用户任务；③ 最近（preserveRecentTurns，默认 5）轮；④ 执行中的工具调用。

原因：压缩掉这些等于把"我在干什么、刚才发生了什么"抹掉，模型会立刻迷失或重复动作。

4. 相关配置（两套口径必须对齐）

来源	字段	默认	说明
AgentConfig	maxContextTokens	128000	上下文预算
AgentConfig	compressionThreshold	0.8	触发水位比例
AgentConfig	preserveRecentTurns	5	最近 N 轮免压缩
AgentConfig	maxToolOutputLength	2000	L1 单次输出截断上限
LlmConfig	contextWindow	128000	模型侧声明窗口
LlmConfig	reservedOutputTokens	4096	为输出预留预算

Warning

若"引擎预算"与"模型声明窗口"不一致，会出现两类错配： 引擎没压但模型报上下文超长；或模型还很宽裕但引擎白白压缩丢了信息。 改任何一侧都要同步另一侧。

5. 事件与持久化

AgentEvent.ContextCompressed(before, after, strategy, …)

• UI 把它渲染为系统消息（用户看得见"压缩发生了、压缩了什么"）；
• 压缩结果会同步回持久化记忆，重启后加载的仍是已压缩状态，避免"重启即爆窗"。

6. 排查技巧

现象	可能原因	怎么办
频繁出现"上下文已压缩"提示	单次工具输出过大（如全文文件、完整 HTML）	让模型用 json_path / regex_extract 等结构化工具只取所需片段；检查 L1 是否命中正确的形态分支
压缩后模型忘记早先约定	被折叠的段落含有关键约束	提高 preserveRecentTurns，或改用 Custom 模式把约束放进 system prompt（永不压缩区）
长任务越跑越慢	L3 每次调用 LLM 摘要成本高	优先用 Plan/Spec 模式切分任务；把中间结论写入文件而不是留在上下文里
疑似 token 估算不准	TokenEstimator 是估算而非精确 tokenizer	用较小的 compressionThreshold 留安全边界

7. 相关页面

• Agent 引擎 · 任务编排器
• LLM 适配层 —— 决定窗口上限的来源
• cs-mem 认知记忆 —— 长期记忆是压缩之外的信息保存手段

---

🏠 返回首页 · 📚 文档索引 · ❓ FAQ · 🔧 故障排查 · 🗺️ 路线图 · 🐛 提 Issue

_{Android Guru Agent · v1.4.4 · Kotlin 2.0.21 · Compose · PRoot · Room}