dsh-compaction-cacheaware：DeepSeek Harness 中的 Reasonix 風格壓縮後端

在 DeepSeek Harness (DSH) 的插件生態中，處理長對話上下文時，壓縮策略決定了系統的穩定性和推理成本。DSH 自帶的 compaction-basic 是一個基礎實現。如果需要更接近 Reasonix 的緩存感知壓縮邏輯，可以使用 dsh-compaction-cacheaware。這是一個獨立、模塊化的 DSH 插件，實現了官方的 ctx.compaction 接口。

插件定位與特性¶

該插件旨在爲 DSH 提供一個 Reasonix 風格的後端。它不修改其他插件、預設或宿主文件，通過掛載來替換默認的壓縮行爲。

核心能力包括：
* Reasonix 風格設計：實現了緩存感知壓縮的核心邏輯。
* 模塊化實現：僅註冊 ctx.compaction 及其自動監聽器，不干涉其他組件。
* 官方接口對接：實現了 @deepseek-ai/dsh-compaction 的 ctx.compaction 接口。
* 自動同步：支持從 esengine/DeepSeek-Reasonix 自動同步設計更新。
* 單一觸發機制：僅使用 compact_ratio（默認 0.85）作爲自動觸發條件。
* 結構化檢查點：生成包含穩定前綴、摘要和近期尾部（recent tail）的結構化檢查點。
* Realm 自檢：具備 Realm 自檢機制，防止在同一個領域內發生競態條件。
* 非侵入性：安裝後不影響現有的插件、預設或宿主文件配置。

安裝¶

插件已發佈至 npm registry，推薦通過 pnpm 安裝。

    cd "$env:USERPROFILE\.dsh\profiles\web"

執行安裝命令：

    pnpm add dsh-compaction-cacheaware

也可以從 GitHub 直接安裝：

pnpm add dsh-compaction-cacheaware@github:Zhuchen00123/dsh-compaction-cacheaware

配置與啓用¶

安裝後，需要在預設的壓縮領域（compaction realm）中掛載該插件以替換默認的 compaction-basic。

注意：Profile 級別的 bundle 補丁無法覆蓋 Agent 預設內部的隔離壓縮領域，因此必須手動在每個預設中配置。

配置示例¶

在 Agent 預設的 YAML 配置中，將 compaction-basic 替換爲 dsh-compaction-cacheaware：

- id: compaction-cacheaware
  name: 'dsh-compaction-cacheaware'
  config:
    compactRatio: 0.85
    checkpointCeilingRatio: 0.5
    recentTailRatio: 0.1
    recentTailMinTokens: 8192
    recentTailMaxTokens: 16384
    summaryMaxTokens: 16384

同時，需要將 @deepseek-ai/dsh-command-compact 放在同一個 realm 中，以便 /compact 命令能夠使用該後端。

配置參數¶

Key	Default	Meaning
`compactRatio`	`0.85`	唯一的自動觸發閾值，決定上下文壓縮的觸發點。
`checkpointCeilingRatio`	`0.5`	正常自動檢查點接受的閾值上限。
`recentTailRatio`	`0.1`	近期原文尾部保留的比例。
`recentTailMinTokens`	`8192`	生產尾部的下限。
`recentTailMaxTokens`	`16384`	生產尾部的上限。
`summaryMaxTokens`	`16384`	摘要生成器的輸出上限。
`exceptionalMinSavingsRatio`	`0.25`	當固定前綴超過閾值時，所需的最低節省比例。
`minRecentKeep`	`2`	最近保留的最小消息數。
`minCompactMessages`	`2`	可壓縮的最小消息數。
`maxPinnedFirstUserTokens`	`1500`	首輪用戶對話被固定的 Token 上限。
`pinnedFirstUserWindowFrac`	`0.15`	首用戶固定窗口的分數上限。
`protocolReserveTokens`	`256`	協議保留 Token。
`summarizationProvider` / `summarizationModel`	`''`	可選的摘要路由，默認使用對話路由。
`auto`	`true`	註冊自動壓力/溢出監聽器。

注意事項¶

運行環境：要求 Node.js 版本 >= 22。
許可證：MIT。
非侵入性：插件不會修改 dsh-wsl-bash、dsh-team-dashboard 等其他插件或宿主文件。
隔離領域限制：Profile 級別的 bundle 補丁無法直接作用於 Agent 預設的隔離壓縮領域。如果預設中已經包含了 compaction-basic，必須單獨遷移該預設以使用此插件。

總結¶

dsh-compaction-cacheaware 爲 DSH 提供了一個從 Reasonix 遷移而來的、經過結構化設計的壓縮後端。它通過單一的觸發機制和結構化的檢查點設計，優化了長上下文的處理流程。開發者可以通過簡單的替換操作，在 Agent 預設中啓用這一能力。

更多細節與源碼，請參考 GitHub 倉庫。