前言¶
DeepSeek Harness (DSH) 的上下文壓縮層主要負責管理對話上下文。其中的 dsh-compaction-basic 負責對工具結果進行總結，這是一個調用昂貴模型的過程。如果上下文溢出但壓力尚未達到總結閾值，直接總結往往是不必要的開銷。dsh-compaction-micro 插件旨在填補這一空缺，它作爲一個獨立的“微清理層”，在官方總結層之前，將白名單內的可重運行工具結果替換爲佔位符，從而在不調用模型的情況下快速釋放 Token 空間。
它是什麼¶
這是一個爲 DeepSeek Harness 壓縮流程設計的微型清理層。它遵循觀察者模式：不修改模型請求，不發起模型調用，僅通過替換 tool/result 內容來觸發壓縮事件。每次重寫操作都會伴隨一個 compaction/prune 事件，確保持久化日誌仍作爲可重構的事實來源。
- 所有者：Perfirstvito
- 許可證：MIT
- 定位：在官方總結層之前介入的預壓縮層。
安裝與啓用¶
安裝該插件需要使用本地鏈接的方式。在插件目錄下執行以下命令：
dsh plugin --profile headless add link:<this-dir>
配置說明¶
該插件通過配置項控制清理行爲。以下是核心配置項：
| 字段 | 默認值 | 說明 |
|---|---|---|
clearableTools |
[] |
允許被清理的工具白名單。僅限只讀、可重運行工具（如 read, glob, grep）。留空則禁用該層。 |
retainRecent |
3 |
保留最新的 N 個可清理結果在上下文中可見。 |
microThresholdRatio |
0.85 |
清理觸發的閾值比例。當 Token 佔用超過 (contextWindow - reservedTokens) * 0.85 時觸發。 |
reservedTokens |
0 |
從有效上下文窗口中預先扣除的 Token 數量。 |
auto |
true |
是否自動安裝監聽器。設爲 false 時僅暴露 ctx.microCompaction.clearSession()。 |
使用示例¶
通常需要將此插件掛載在 dsh-compaction-basic 之前。在 DSH 的插件配置中，建議按以下順序排列：
- name: '@deepseek-ai/dsh-token-meter'
- name: '@deepseek-ai/dsh-compaction-tool-result-pruner'
- name: '@deepseek-ai/dsh-compaction-basic'
config:
thresholdRatio: 0.9
- name: 'dsh-compaction-micro'
config:
clearableTools: [read, glob, grep, web_search, web_fetch]
retainRecent: 3
microThresholdRatio: 0.85
reservedTokens: 0
工作原理¶
插件通過兩個前置監聽器工作：
-
agent/pre-step(prepend)：- 監聽並測量上下文壓力。
- 當
totalTokens達到閾值（即(contextWindow - reservedTokens) × microThresholdRatio）時，按從舊到新的順序清除白名單工具結果，但始終保留最近retainRecent個結果可見。 - 清理後，底層會重新測量，若壓力已緩解，則跳過昂貴的總結步驟。
-
agent/request-error(prepend)：- 當確認發生上下文溢出時，優先執行清理操作。
- 清理完成後，再將控制權委託給官方的後端修剪、總結及重試流程。
注意事項¶
- 掛載順序：雖然監聽器設置了
prepend: true，但爲了確保邏輯順序正確，建議將dsh-compaction-microbundle 掛載在dsh-compaction-basic之前。 - 工具安全：該插件僅對只讀、可重運行工具（如讀取文件、搜索內容）安全。寫操作、編輯、Shell 調用等工具必須從
clearableTools白名單中移除，否則可能導致不可逆的數據丟失。 - 權限運行：插件以當前 DSH 進程權限運行，使用前請檢查源碼與許可證。
開發¶
本地開發需要將 DSH 的工作空間包 junction 到 node_modules/@deepseek-ai 目錄下。
npm run typecheck # TypeScript 類型檢查
node --import tsx --test tests/micro.test.ts
