dsh-compactor：DeepSeek Harness 的上下文壓縮插件

前言¶

DeepSeek Harness（dsh）採用「一切皆插件」的架構，旨在通過插件擴展系統能力。在長會話場景中，模型的輸入由全部歷史消息組成，其中工具結果（如搜索結果、文件內容、命令輸出）往往佔據上下文的大部分，且包含大量對後續推理無價值的細節。此外，重複的工具調用和冗長回覆會持續膨脹上下文，甚至誘發死循環。

dsh-compactor 是由 lionwill 維護的上下文壓縮插件。它在不破壞 dsh append-only 會話日誌的前提下，通過三層處理機制（實時層、批處理層、歸檔層）對上下文進行剪枝與摘要，並提供了死循環護欄與數據回滾功能。

核心能力¶

該插件主要解決長會話上下文膨脹問題，核心能力包括：

三層處理機制：
- 實時層：在工具結果（tool/result）進入事件流時，按固定策略剪枝（例如搜索只留標題/鏈接，文件只留預覽）。
- 批處理層：當會話 token 量超過閾值時，將可壓縮片段（工具結果、冗長回覆）替換爲摘要，壓縮邊界自動對齊，最近 N 輪消息不會被觸碰。
- 歸檔層：被替換的原文寫入 append-only 歸檔目錄，支持通過命令完整還原。
兩種摘要引擎：
- API 摘要：依賴 DEEPSEEK_API_KEY，調用 deepseek-chat 進行骨架化摘要；無 Key 時自動降級。
- 本地規則壓縮：基於正則與固定規則（如摺疊重複句、截斷長輸出），無需網絡請求，零額外依賴。
命令與工具：
- 語義理解壓縮 (/su-compact)：將意圖和策略餵給 LLM，保留關鍵結論。
- 本地規則壓縮 (/local-compact)：基於規則文件執行壓縮，需用戶確認。
- 數據回滾 (/restore)：將壓縮過的原文重新注入會話。
- 死循環護欄：監測工具調用，觸發閾值時注入防循環提示或記錄取消判定。

安裝與啓用¶

插件以 dsh 宿主權限運行，安裝前請確認來源可信。

推薦使用本地目錄安裝（file: 協議），無需處理 git 構建腳本：

# 1. 克隆倉庫
git clone https://github.com/lionwill/dsh-compactor.git
cd dsh-compactor

# 2. 構建產物（lib/ 目錄由 prepare 鉤子自動生成）
npm install && npm run build

# 3. 安裝插件
dsh plugin add "dsh-compactor@file:$PWD"

命令與用法¶

安裝完成後，dsh 會通過 bundle patch 顯式重新啓用內置的 /compact 命令。本插件新增以下命令：

本地規則壓縮：
首次調用僅輸出風險說明，需用戶確認後執行：

    /local-compact confirm

語義理解壓縮：
利用 LLM 理解上下文意圖並生成摘要：

    /su-compact

數據回滾：
恢復最近一次壓縮操作的數據：

    /restore

配置方式¶

插件通過 cordis.patch.yml（內置）或環境變量進行配置。主要配置項包括：

thresholdTokens：觸發壓縮的 token 閾值（默認 32768）。
targetTokens：壓縮後的目標 token 數（參考值）。
qualityThreshold：關鍵信息保留率告警閾值（默認 0.85）。
exemptTools：豁免工具列表（默認 write、edit、task）。
localRulesPath：自定義本地規則文件路徑。

示例配置片段：

- insert:
    - id: dsh-compactor
      name: dsh-compactor
      config:
        thresholdTokens: 32768
        targetTokens: 8192
        retainRecentRounds: 3
        qualityThreshold: 0.85
        exemptTools: [write, edit, task]
        enablePruning: true
        enableSummary: true

注意事項¶

信息丟失：壓縮是“保留骨架、丟棄細節”的過程。snippet、長輸出中段等細節可能丟失，若後續推理依賴這些細節，結果質量可能下降。
Token 估算偏差：插件使用啓發式方法估算 token，與真實計費 token 存在偏差。
權限風險：插件以宿主權限運行，僅建議從可信來源安裝並 pin 版本。
歸檔目錄：默認爲 $DSH_DATA_DIR/archive/ 或 ./.dsh-compactor-archive/，請確保目錄可寫且不要手工編輯。
命令衝突：本插件通過 patch 顯式重新啓用 dsh 內置的 /compact。如果同時安裝了其他註冊同名 /compact 的插件，可能會出現命令衝突導致失效。
熱重載：修改規則文件後無需重啓會話，每次執行 /local-compact 均會重新讀取。