前言¶

在使用 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 版本。