前言¶

在使用 DSH 进行开发或调试时，小上下文模型常因对话历史过长导致上下文溢出，进而丢失关键细节。dsh-handoff-compaction 是一个专为解决此问题设计的上下文压缩插件。它将旧对话转化为结构化的 # Context Handoff，保留近期消息的原始形式，并在模型需要时通过历史工具检索完整记录，从而让小上下文模型也能维持长会话的任务连续性。

功能介绍¶

该插件提供以下核心能力：

• 可视化上下文配置：支持在 Web 界面直接调整摘要限制和近期上下文预算，默认配置为 8192（摘要）+ 16000（近期）tokens。
• 缓存友好压缩：采用全表面压缩策略，在重放完整对话面时保留系统提示和工具定义，有助于本地 Provider 的缓存命中。
• 长期记忆无损保留：会话事件保持仅追加模式，被压缩隐藏的事实仍可通过官方 SQLite 历史工具进行搜索和读取。
• 任务连续性保障：通过 Context Handoff 结构化记录当前任务的目标、进度、决策、约束及下一步计划。
• 版本兼容：支持 DSH 0.1.x 和 0.2.x 版本，同一插件包适配所有兼容的 DSH 版本。

安装与启用¶

通过 npm 包名安装，该插件以 Bundle 的形式注入到指定的 DSH 配置文件中。

dsh plugin --profile web add dsh-handoff-compaction
dsh plugin --profile headless add dsh-handoff-compaction

安装完成后，需要重启配置文件以应用更改。

配置与使用¶

Web 界面配置：在 Web 客户端侧边栏进入 Plugins → dsh-handoff-compaction。在此页面可以调整 Handoff summary limit（默认 8192 tokens）和 Recent context budget（默认 16000 tokens）。点击 Save 保存配置，这些预算将持久化并应用于后续的压缩过程。

手动触发：在对话中输入 /compact 命令，可手动触发上下文压缩。

工作原理与注意事项¶

• 非原生扩窗：该插件不会物理增大模型的原生上下文窗口。
• 预算控制：配置的 maxTokens 和 retainTokens 控制的是摘要输出和近期消息保留量，而非请求的精确总大小。实际请求大小还包括系统提示、工具定义和消息对，因此配置时需预留足够空间。
• 全局替换：安装操作是配置文件范围的替换。该插件会通过 Bundle patch 禁用 compaction-basic 和 tool-result-pruner，并注入自身的压缩逻辑及 SQLite 后端。
• 数据可检索性：压缩仅隐藏旧对话内容，并不删除数据。Session events 保持追加写入，被压缩的事实在历史记录中依然可被搜索。

兼容性¶

根据已核实资料，该插件支持 DSH 0.1.x 和 0.2.x 系列。安装时无需选择特定版本，同一包名即可适配声明兼容范围内的所有 DSH 版本。