上下文压缩：计量、摘要策略与历史替换
token-meter 从事件测量压力，compaction 定义压缩能力，compaction-basic 实现范围选择和模型摘要。自动策略与人工命令共享该能力，历史替换留在 Session，溢出恢复以替换代次推进为条件。
箭头表示标注的调用或依赖关系；点击组件定位正文。完整关系见下方文字说明。
文字关系说明与章节链接
command-compact →（调用压缩能力）→ compaction；compaction-basic →（实现服务）→ compaction；compaction-basic →（请求模型摘要）→ llm；token-meter →（读取记录计量）→ Session；compaction →（约束历史替换）→ Session；compaction-basic →（查询压力）→ token-meter。
command-compact · compaction · compaction-basic · Session · token-meter · llm
计量服务与压缩入口分别提供能力
dsh-token-meter 从持久记录测量请求与上下文压力，dsh-compaction-basic 据此触发自动压缩，也处理已确认的上下文溢出；command-compact 提供人工 /compact 入口。
dsh-compaction · 接口摘录，省略上下文 · compactIfNeeded · packages/compaction/compaction/README.md · compactNow · packages/compaction/compaction/README.md// 自动策略入口按当前请求路由与预算决定是否压缩；服务接口需装配后端实现。
compactIfNeeded
// 手动调用在 Agent 空闲时预留接纳权，即使低于自动压力阈值也尝试压缩安全旧片段。
compactNow// 用户无参数发起立即压缩；Agent 忙碌、压缩已运行或无可压缩历史时报告明确结果。
/compact固定版本 base 装配这一功能，但实际阈值随目标模型路由和配置计算。压缩是参与 Agent 执行的可选策略，不是所有 ctx.llm 调用内部都会自动发生的隐藏行为。
修剪器和摘要后端共同缩减旧材料
可选的 dsh-compaction-tool-result-pruner 在摘要前修剪过大的工具结果；compaction-basic 再选择可替换历史范围，调用统一 ctx.llm 生成摘要，并通过 compaction 能力应用替换。
// 显式区域调用方请求压缩选定范围，后端核验工具配对、锁与表面稳定性后才替换。
compactRegionSession 原始事件日志保持追加，不删除旧对话。compaction/start、compaction/summary、compaction/end 只记录压缩过程；摘要通过另一个携带 surfaceOp: { op: 'replace', startSeq, endSeq } 的 user/message 替换模型可见 surface 的选定范围。后续请求使用摘要与保留材料，不再重放被遮蔽的旧细节，也不包含摘要模型的整段私有对话。
模型路由决定触发预算与保留范围
固定版本默认触发阈值是 floor(min(W×0.8, W−O−B))，其中 W 是窗口、O 是输出预算、B 默认为 65536 token；近期保留量按 W−O 的百分之十六计算。模型首次使用时要求 W−O−B＞0，且解析后的保留预算严格小于触发阈值。
例如 W=65536、O=8192、B=65536 时，W−O−B=−8192，策略无效；必须调小余量以适配窗口。缺少容量、输出加余量耗尽窗口或保留预算过大时，手动压力路径抛出目标模型的配置错误；自动监听器对该精确目标告警一次，并在配置修正前跳过主动压缩，提供者确认的溢出恢复仍可执行。
这些是该版本策略而非当前部署读数。系统提示、工具定义和不可替换前缀不会因摘要变小，完整工具调用等不可分割单元也不能任意切开，因此总有压缩无法解决的过大请求。
历史替换推进后才能恢复请求
replacement generation 是会话可见 surface 应用替换时推进的代次，用来判断请求输入是否实际改变。AgentLoop 在溢出恢复中允许同一步重新请求，但必须看到该代次前进，避免同一超限请求无休止重发；仅追加压缩过程记录不算替换成功。替换影响的缓存从首个被替换位置开始失效，未受影响前缀与新摘要要正确拼合。
compaction-image-offload 还可在特定图像预算拒绝时把请求图像改为占位。压缩失败、请求仍过大或用户取消时，系统需要沿错误和取消路径结算，而不是承诺每次都能继续。
// 摘要失败恢复者先记录持久输入变化才能请求重试，否则通过 next() 委托后续处理。
'compaction/summary-error'辅助示例
压缩前，模型可见顺序为：系统提示 → 旧的“比较模块”请求 → 读取二十份文件的调用与完整结果 → 近期讨论 → 最新请求。压缩后变为：系统提示 → 摘要 user/message（任务目标、已确认事实、待办）→ 原样保留的近期讨论 → 最新请求。旧调用与完整结果仍在原始日志中，下一次模型请求只使用当前 surface，不再携带被替换的文件细节；选定范围仍须保持工具调用与结果配对。若真正超限的是工具 schema 或系统规则，反复摘要旧聊天也无法解决。
设计取舍
摘要让长任务能在有限窗口内推进，并把请求压力处理从主循环中独立出来；代价是额外模型费用、延迟和信息损失。保留任务目标与关键证据依赖摘要质量，原始记录可查询不代表摘要后的模型仍持有全部细节。
相关包与插件
- 确定性上下文用量估算
@deepseek-ai/dsh-token-meter - 会话压缩服务接口
@deepseek-ai/dsh-compaction - 摘要式自动上下文压缩
@deepseek-ai/dsh-compaction-basic - 大工具结果头尾裁剪
@deepseek-ai/dsh-compaction-tool-result-pruner - 历史图像卸载与重试
@deepseek-ai/dsh-compaction-image-offload - 手动上下文压缩命令
@deepseek-ai/dsh-command-compact
资料来源与核验范围
本章依据固定版本的官方文档整理，设计取舍根据所述机制分析；核验范围为文档，不包含运行实测。