前言¶
DeepSeek Harness (DSH) 的自動壓縮機制在觸發“壓力”路徑時存在一個具體問題：沒有嘗試上限，導致一個徒勞的“快速填充”循環，即一個過大的文件讀取或工具輸出會在每一步都消耗一次總結調用。dsh-zcode-breaker 旨在通過在總結浪費之前停止這個循環來解決這個問題。
核心功能¶
該插件擴展了 BasicCompactionEngine 並包裝了 compactIfNeeded 方法。它提供以下能力：
- 會話級狀態：狀態是按會話管理的，防止會話之間互相污染。
- 日誌驅動檢測：從持久會話日誌（攜帶至少一個工具調用的助手消息）讀取工具輪次，而不是在內部使用計數器。這是壓縮縫用於平衡計算的單位。
- 快速填充檢測：如果在少於
toolTurnThreshold個工具輪次後請求壓縮，則視爲快速填充。 - 提前拒絕：當達到
maxConsecutiveRapidRefills時，嘗試在總結調用運行前被拒絕。這種拒絕是鎖定的；一旦觸發，會話將保持拒絕狀態直到被重置。 - 錯誤處理：拋出
CompactionRapidRefillError，並附帶可操作的建議。 - 可見性：由於 DSH 的主機捕獲來自
compactIfNeeded的錯誤並繼續執行輪次，插件在鎖定期間注入一個提示部分，以確保停止可見。 - 管理命令：提供
/compaction-breaker命令來報告狀態和重置斷路器。
安裝與配置¶
安裝該插件需要滿足以下依賴條件：
- DSH 版本 >= 0.1.5-rc.2 和 >= 0.1.6-alpha.1
- @deepseek-ai/cordis ^4.0.2
- @deepseek-ai/dsh-compaction-basic
- @deepseek-ai/schemastery ^3.18.2
安裝命令如下：
dsh plugin --profile web add dsh-zcode-breaker
典型用法¶
安裝後，可以使用以下命令檢查插件狀態：
/compaction-breaker status
/compaction-breaker reset
插件包含測試套件用於驗證狀態機邏輯和包裝器行爲：
node --test test/tracker.test.js
node --test test/engine.test.js
node tools/boot-check.mjs --port 32100
實現細節¶
該插件從 ZCode 實現中獲取快速填充狀態機邏輯，但進行了改進：
- 日誌讀取：不像 ZCode 那樣在循環中維護計數器，此插件從 DSH 的持久會話日誌讀取工具輪次，以匹配壓縮縫使用的測量單位。
- 鎖定時機：拒絕邏輯在總結調用運行之前發生（鎖定），而不是之後。
- 可配置性：閾值（
toolTurnThreshold、maxConsecutiveRapidRefills）作爲行配置提供，而不是編譯時常量。 - 不實現 microcompact：該插件明確不實現 ZCode 的
microcompact.ts邏輯，因爲它不重新實現該邏輯。
注意事項¶
- Node 版本：雖然 package.json 聲明
>=20，但使用 npm install 在 Node 20 上會帶來 10 個包且沒有 dsh 二進制文件，而在 Node 24 上則是 488 個包。徽章顯示測量值爲 Node >=22.19。
總結¶
dsh-zcode-breaker 通過防止壓縮-填充-壓縮循環浪費總結資源，直接解決了 DSH 自動壓縮中的一個具體問題。它通過在調用運行之前拒絕快速填充，並從持久日誌中讀取工具輪次來提供準確的狀態跟蹤。
