前言¶

在 DeepSeek Harness（DSH）裏做長會話時，上下文會逼近壓縮閾值。DSH 自帶的 dsh-compaction-basic 在 agent/pre-step 測壓，超過閾值後同步調用模型寫摘要並提交 checkpoint，這段時間界面往往表現爲「卡住」。輸入側前綴可以命中 KV 緩存，真正拖慢的是摘要的輸出。把生成挪到用戶不需要等待的時間窗，是這條路徑上唯一有效的優化方向。

下面介紹社區插件 dsh-background-compaction（維護者 OZONGO，分類：工作流）。它在上下文到達閾值之前用一次幾乎全緩存的模型調用，把截至上一輪的歷史在後臺總結成摘要；摘要就緒後的下一個回合邊界，用 0 次模型調用把摘要提交成 checkpoint，用戶可以繼續對話。

這是什麼¶

dsh-background-compaction 是 DSH 宿主平面上的壓縮引擎擴展：接管壓縮的觸發時機，不改變 checkpoint 渲染、日誌格式或計價規則。壓縮後模型看到的是 摘要 + 上一整輪原文。

• 倉庫：OZONGO/dsh-background-compaction
• 目錄頁：skillhub.cn 插件條目
• 當前 package 版本：0.1.0，許可證 MIT
• Node 要求：>=22.12.0

DSH 生態是「一切皆插件」；社區目錄站點與 DeepSeek / 幻方無官方從屬關係。

與原生壓縮的差異¶

原生路徑：沒到閾值什麼都不做；一到閾值就在 pre-step 同步 summarization。

本插件路徑示意：

回合 N-1（上下文到自動觸發比例，默認 85% × thresholdTokens）
  └─ 起游離任務，後臺總結 [首節點 .. 上一輪結束]（約 30~60s，用戶可繼續對話）

回合 N（摘要已就緒）
  └─ pre-step 提交 held 摘要（毫秒級，summarize 指紋命中 → 0 次模型調用）
     本輪請求 ≈ system + 摘要 + 上一輪原文 + 本輪消息

Web 版把壓縮放在 agent preset 裏；本插件掛在宿主平面，通過 agent/pre-step 工作，並繼承 compactRegion 自行提交。preset 裏的原生引擎仍作兜底（摘要沒趕上、上下文溢出、/compact 等）。子 agent（delegationDepth > 0）不做後臺預計算。

核心功能¶

自動壓縮¶

無需額外操作。當上下文達到 thresholdTokens × 自動觸發比例（默認 0.85）時後臺開始生成；摘要就緒後的下一回合自動換入。

注意：所有比例相對 DSH 的 thresholdTokens，不是 contextWindow × 0.8。以 200k 窗口爲例，README 給出 thresholdTokens = min(160000, 68928) = **68928**，85% 觸發點約 58.6k token，而非按窗口心算的 170k。

手動命令 /bcompact¶

命令在回合之外執行，不能同步壓縮（公開 compactRegion 要求 open turn）。

實現方式：起後臺任務 + 必要時 agent.followup(消息)。

設置頁與配置文件¶

設置 → 後臺壓縮 三項，改完立即生效，無需重啓：

持久化路徑：~/.dsh/background-compaction/config.json

{
  "$schema": 1,
  "autoTriggerRatio": 0.85,
  "summarizationModel": { "provider": "", "model": "" },
  "maxFailures": 2
}

優先級：設置文件 > YAML 配置 > 內置默認值；只有文件裏出現的鍵才覆蓋 YAML。

YAML（bundle / profile patch）還可配置 background 段，例如 startRatio、tailRatio、minShadowedRatio、holdTtlMs、maxFailures、failureCooldownMs 等，詳見倉庫 README 第 6 節。

安裝與啓用¶

插件以當前 DSH 進程權限運行；安裝前請自行審閱源碼與 MIT 許可證。安裝命令以倉庫 README 爲準，不要憑插件名拼接未文檔化的 CLI。

從 Git 安裝¶

cd ~/.dsh/profiles/desktop
pnpm add github:OZONGO/dsh-background-compaction

從本地目錄安裝（開發）¶

cd ~/.dsh/profiles/desktop
pnpm add file:E:/AI/workspace/dsh-plugin/dsh-background-compaction

（將 file: 路徑改爲你本機克隆或下載的目錄。）

註冊 bundle¶

在 profile 的 package.json 中把包名加入 dsh.profile.bundles，並在 dependencies 中聲明依賴，例如：

{
  "dsh": {
    "profile": {
      "bundles": ["...", "dsh-background-compaction"]
    }
  },
  "dependencies": {
    "dsh-background-compaction": "github:OZONGO/dsh-background-compaction"
  }
}

然後重啓 DSH（宿主默認不支持熱加載 bundle）。

確認加載¶

宿主日誌（Windows 示例：%APPDATA%/DSH Desktop/logs/host/dsh-YYYY-MM-DD.log）應出現類似：

[background-compaction-engine] background-compaction: engine ready (auto=true, startRatio=0.85, maxFailures=2, state=…)

設置面板左側應出現 後臺壓縮 一頁。

典型用法與驗收¶

README 給出三步驗收，無需刻意堆長對話：

1. 新會話做 2–3 輪對話（例如讀一個文件，幾百到幾千 token）——應正常。
2. 輸入 /bcompact 繼續——應立即得到回答；日誌出現 held ready。
3. 再發一條消息——該輪 pre-step 提交摘要；日誌出現 swap hit；生成 ~/.dsh/background-compaction/last-swap.json。

/bcompact 需要非空且平衡的可壓縮區間（絕對下限 512 token）；歷史太短會提示「歷史太短，壓縮沒有意義」。自動路徑還要求被壓縮區間至少爲 thresholdTokens 的 10%（200k 窗口約 6.9k token）。

last-swap.json 中的 messages 來自提交之後的 session.deriveMessages()，可用來覈對下一輪真正發出的 surface（摘要 + 保留尾巴）。

常用日誌關鍵字：engine ready、started、held ready、swap hit、discarded、summarize miss。

適用場景與注意¶

適合：桌面 DSH 長會話、希望壓縮發生在對話間隙而非 pre-step 阻塞的用戶；需要與官方 /compact、溢出恢復、tool result pruner 共存時（本插件只改觸發時機）。

注意：

• 摘要僅在前綴指紋、路由、surface 首節點等仍一致時換入；否則丟棄（見 README 失效矩陣）。任意 compaction/start（含 /compact）會中止在飛的後臺任務。
• auto: false（YAML）時後臺完全停止。
• 開發時在 Windows 上鍊本地包須用目錄聯接（junction），避免 Git Bash ln -s 退化成複製導致改代碼不生效（README 8.1 節）。
• 升級 @deepseek-ai/dsh-compaction-basic 後，維護者建議先跑插件內 npm test（116 個用例，含真實 Session 換入）。

結尾¶

dsh-background-compaction 把上下文摘要生成提前到閾值前的空閒窗口，在下一回合用 held 摘要完成 checkpoint，避免 pre-step 同步等待。若你在 DSH 裏常被壓縮卡頓打斷，可按上文安裝並在設置裏調整觸發比例與摘要模型。

• 目錄頁：https://www.skillhub.cn/plugins/OZONGO/dsh-background-compaction
• GitHub：https://github.com/OZONGO/dsh-background-compaction