前言¶
用 DeepSeek Harness（dsh）跑編碼智能體時，會話很快會堆滿工具調用、文件內容和推理過程。上下文窗口一旦接近上限，默認後端 @deepseek-ai/dsh-compaction-basic 會再調一次模型，把舊歷史摘要成一段話。摘要要等推理、要花 token，文件路徑、命令和標識符還可能被改寫成「差不多」的說法。
dsh 把壓縮做成可替換的能力縫：服務定義在 @deepseek-ai/dsh-compaction（ctx.compaction），內置實現是 dsh-compaction-basic，人手動觸發走 dsh-command-compact（/compact）。官方文檔寫明每個上下文只加載一個實現，所以換引擎不需要改 Harness 源碼，換插件即可。
社區插件 dsh-compaction-instant 走另一條路：不調用模型，按 lllyasviel/VCC 的對話編譯思路，把舊歷史整理成一份只含原文的檢查點，被裁掉的內容用 seq 指針指回只增不改的會話日誌。本文按插件目錄頁、GitHub README / package.json，以及 DeepSeek Harness 官方壓縮文檔覈對後整理。
這是什麼¶
dsh-compaction-instant 是面向 DeepSeek Harness 的會話與消息插件，目錄頁標註由 KitDoesIt 維護，倉庫爲 KitDoesIt/dsh-compaction-instant，許可證 MIT。目錄頁一句話是：無 LLM 的無損壓縮引擎，壓縮上下文而不丟失信息。倉庫 README 寫得更精確：檢查點裏只有原文，省略處都帶出處標記，完整內容仍在持久日誌裏，因此定位是近無損，不是把整段歷史原樣塞進上下文。
它要替換的是內置摘要引擎 @deepseek-ai/dsh-compaction-basic。壓縮發生在毫秒級文本處理裏，不發摘要請求、不佔 KV 緩存。/compact 命令與後端無關，換引擎後仍然可用。
覈對時（2026-08-18）目錄頁與 GitHub 均爲 7 星；倉庫 package.json 版本爲 0.1.4，要求 Node.js >= 18。npm 上同名包 dsh-compaction-instant 當時最新公開版本是 0.1.3。目錄頁走 GitHub 源，README 裏的別名安裝走 npm 解析，兩邊版本可能不一致，安裝前按實際解析結果確認。
DeepSeek Harness 的核心理念是「一切皆插件」。本文引用的插件目錄 deepseek-harness-plugin.com 是獨立社區站點，與 DeepSeek / 幻方沒有官方從屬關係，不要把它當成官方應用商店。
核心功能¶
1、不調模型的確定性編譯¶
壓縮是對陰影區間做一次確定性掃描：無網絡、無模型、無摘要 prompt。同樣的輸入會得到同樣的檢查點。summarizationProvider / summarizationModel 爲兼容官方配置而保留，不起作用。
倉庫給的編譯示例（用戶請求、助手回覆加工具調用、再跟下一問）如下：
[user]
please fix the bug
[assistant]
on it
* read "a.js" (seq 2 -> result 3)
[user]
next question
規則可以收成幾條：
- 每個工具調用只佔一行。白名單工具（
toolArgTools，含read/write/edit/glob/grep/bash/shell/web_search/skill/subagent等）顯示關鍵參數，其餘只顯示名字，hideTools裏的工具整行不出現。 - 工具結果不佔條目，靠
-> result N指針，一次recall(type:"result")取回。 - 過長的用戶 / 助手文本按預算截斷，末尾寫
...(truncated from seq N)。 - 默認不保留 reasoning；
includeReasoning: true纔會寫進檢查點。 - 更早的檢查點被空間壓力裁掉時，會留下
[checkpoint N]（1 爲最早），不會無聲消失。
預算有兩道限制：token 數，以及 預算 × 4 的字符上限，避免 base64 或壓縮文件繞過截斷。超預算時先刪最舊的工具行，再刪其餘最舊條目，對話文本不會被工具調用擠掉；最新內容優先保留。
2、近無損：省略都帶 seq，日誌裏還能取回¶
「近無損」不是檢查點等於全文，而是：
- 檢查點裏只有原文，不做改寫、不編造。
- 每處省略都指向持久日誌裏的
seq。 - 舊檢查點原樣拷貝，不再二次摘要。
同一包還帶回讀層，模型和人都能用：
| 入口 | 模塊 | 作用 |
|---|---|---|
recall 工具 |
dsh-compaction-instant/tool |
按 seq / result / checkpoint 把原文寫回當前工具結果 |
search 工具 |
同上 | 在整份持久日誌裏做關鍵詞 / 正則搜索，含已被壓縮的內容 |
/recall 命令 |
dsh-compaction-instant/command |
把匹配事件和 seq 指針追加成一條用戶消息，下一輪模型能看見 |
recall 能取回文本、推理、完整工具參數和嵌套工具結果。默認 maxRecallTokens 爲 16000，超限會截斷並標註；搜索默認最多展示 50 條（maxSearchHits）。這兩個插件是獨立行，只讀日誌，可以掛在任意壓縮後端旁邊。每個檢查點開頭還有一段 RECALL 指南，告訴模型怎麼用 recall / search。
3、契約兼容，可頂替內置引擎¶
倉庫稱它是 compaction-basic 的契約級替換：同一個 ctx.compaction 縫、相同的注入列表（llm、tokenMeter、sessions）、相同的事件和報錯詞表，並走同一個 ctx.tokenMeter 計費。壓縮後若不能縮小表面上下文，檢查點會被拒絕。可選的 toolResultPruner 也兼容：pruner 整理保留尾部，本引擎處理被陰影覆蓋的舊區間。
部分默認值和 basic 不同，換引擎後行爲會變：
| 項 | instant 默認 | basic 文檔默認 |
|---|---|---|
thresholdRatio |
0.5（用到窗口一半就自動壓） |
0.8 |
retainRatio |
0.05 |
0.16 |
auto |
true |
true |
| 摘要模型 | 接受配置但不路由 | 一次 ctx.llm.stream() 摘要 |
手動 /compact 會按 manualRetainRatio（默認 0.05）留下最近原文，正在聊的內容不會整段被收走。
從 0.1.4 起，裝配了 settings 域的部署（標準 web / desktop profile）會在「設置 → 插件」出現 compaction-instant 卡片，可改 checkpointScale、checkpointCap、maxTokens、auto、debug、debugLogPath。改完寫入 settings.yaml，併疊在 cordis 配置之上。卡片在客戶端 bundle 裏，裝完後需要重啓一次 dsh web。npm 若仍停在 0.1.3，則沒有這一項。
4、倉庫 README 給出的壓縮率¶
下面數字來自倉庫 README，測的是本項目自己的開發會話，編譯時不丟條目，只做條目級截斷和工具調用單行化。百分比相對原文 token。這不是第三方評測，工具密集會話會明顯好看，純文本會差一截。
| 負載 | 原文 tokens | 編譯後 | 保留 |
|---|---|---|---|
| 工具密集會話全量（3181 節點） | 2,523,012 | 226,205 | 9.0% |
| 另一會話全量（864 節點） | 685,088 | 62,705 | 9.2% |
| 同一工具密集會話，最近 800 條 | 625,927 | 45,031 | 7.2% |
| 純文本（去掉全部工具行） | 160,963 | 109,945 | 68.3% |
壓縮主要來自：工具結果不佔條目、工具調用壓成一行（上限 128 tokens）、reasoning 默認整段省略。純文本大約只剩 1.5 倍壓縮，多半是去掉 JSON 包裝和截斷最長塊。README 也寫了權衡：敘述型長對話的信息密度可能不如 LLM 摘要，因爲長句是截斷而不是合併。
部署默認 checkpointCap 爲 65536。同一份 252 萬 token 的工具密集會話，在這個封頂下保留約 2.2%，會丟掉大量舊條目；要不丟條目，檢查點大約要到 22.6 萬 tokens。需要更完整的歷史時，應調高 checkpointCap / checkpointScale，或依賴 recall，不要默認「壓完還等於全文」。
安裝與啓用¶
目錄頁給出的安裝命令如下，在 DeepSeek Harness 終端執行：
dsh plugin add github:KitDoesIt/dsh-compaction-instant
可復現安裝請固定 commit 哈希：
dsh plugin add github:KitDoesIt/dsh-compaction-instant#<commit>
目錄頁同時寫明：插件以當前 dsh 進程的權限運行，安裝時可能執行代碼。裝前檢查源碼倉庫和許可證。
只執行上面這一條，未必能讓內置預設真正換引擎。倉庫 README 說明：dsh 目前沒有「選擇壓縮引擎」的開關，內置預設 standard / code / cordis 寫死了包名 @deepseek-ai/dsh-compaction-basic。要用起來，按 README 三選一，都通過插件管理器安裝（它會在 profile 目錄裏跑 pnpm）。示例里加了 --profile web，按自己的 profile 改。
方法 1：別名頂替內置引擎¶
內置預設會從 profile 的 node_modules 解析包名（優先級高於 Harness 自帶安裝）。把本包裝到內置名字下面，standard / code / cordis 會自動加載，不用改預設文件：
dsh plugin --profile web add "@deepseek-ai/dsh-compaction-basic@npm:dsh-compaction-instant"
刪掉這條別名依賴，就回到官方 basic。
別名安裝不會被識別成 dsh.bundle（Harness 仍按自己目錄裏的官方包名解析，那個包沒有 bundle 聲明）。recall 工具和 /recall 需要自己寫進 profile 的 cordis.patch.yml，新行放在 insert 列表裏，文件熱重載，不必重啓。行名必須用別名包名：
- id: compaction-basic
disabled: true
- insert:
- id: compaction-instant
name: '@deepseek-ai/dsh-compaction-basic'
- id: tool-recall
name: '@deepseek-ai/dsh-compaction-basic/tool'
- id: command-recall
name: '@deepseek-ai/dsh-compaction-basic/command'
引擎行可選，主要給沒有壓縮配置的預設（如 minimal）做宿主兜底。
方法 2：直接安裝，再複製一份預設¶
dsh plugin --profile web add dsh-compaction-instant
從 v0.1.1 起包內聲明瞭 dsh.bundle，直接安裝會自動成爲 profile 層：禁用內置摘要行，插入本引擎和 recall 工具（見包內 cordis.patch.yml）。宿主不用手寫 patch。
內置預設本身仍釘着 basic。用內置 cordis 預設（創作模式）開一個會話，讓模型執行：
複製
standard預設，把它的壓縮引擎行換成dsh-compaction-instant。
README 的流程是：agentPresets.copy 做本地副本，改壓縮行的 name，用 standingKeyFor 校驗掛載，需要的話再把 agent-presets 的 config.default 指到新預設。選擇器裏會多出一個預設，內置預設不動。
方法 3：直接安裝，再手工改預設副本¶
同樣先 dsh plugin --profile web add dsh-compaction-instant，然後複製內置預設，不要改 Harness 自帶的預設文件：
mkdir -p "$DSH_HOME/.agent-presets/<id>"
cp <內置預設路徑>/agent.cordis.yml "$DSH_HOME/.agent-presets/<id>/agent.cordis.yml"
在旁邊寫 preset.yml（name + description），再把副本里壓縮組的引擎行改成 dsh-compaction-instant，隔離域保持不變：
- id: compaction
name: cordis:group
group: true
isolate:
compaction: true
toolResultPruner: true
config:
- id: compaction-instant
name: dsh-compaction-instant
- id: command-compact
name: '@deepseek-ai/dsh-command-compact'
toolResultPruner 必須和引擎在同一 isolate。真正的檢驗是 standingKeyFor 掛載成功，或直接用該預設開會話；列表裏的 broken 只抓解析錯誤。
三種方法對照（摘自 README）：
| 方法 | 內置預設裏的引擎 | 改預設文件 | 選擇器多出預設 |
|---|---|---|---|
| 別名替換 | 自動（standard / code / cordis） | 否 | 否 |
| AI 複製副本 | 只有新預設 | 只改副本 | 是 |
| 手動預設 | 只有新預設 | 只改副本 | 是 |
每個上下文只能掛一個 ctx.compaction 實現；預設有獨立隔離域，宿主實例和預設實例不會撞車。
典型用法¶
裝好並讓當前預設真正加載本引擎之後，用法和 basic 同一套入口。
1、自動壓縮：默認 auto: true，在 agent/pre-step 看壓力，在 agent/request-error 做溢出恢復。thresholdRatio 默認 0.5，比 basic 的 0.8 更早觸發。
2、手動壓縮：會話裏執行 /compact。最近一段按 manualRetainRatio 原樣保留。
3、回讀：模型側用 recall / search；人側用 /recall <關鍵詞或正則>。
4、看檢查點：compaction/summary 事件帶着編譯後的條目本身，UI 可展開的檢查點行顯示的就是模型實際看到的內容。
常用配置（全部可選）。cordis 配置裏不要寫空數組想「關掉」白名單：schemastery 會給缺省數組鍵填 []，本引擎把空數組當成未設置並回退默認值。toolArgTools: [] 不會清空白名單。
thresholdRatio: 0.5
retainRatio: 0.05
auto: true
maxTokens: 8192
checkpointScale: 0.1
checkpointCap: 65536
textTokens: 512
userTextTokens: 1024
toolCallTokens: 128
includeReasoning: false
debug: true 會把每次編譯的診斷寫到 debugLogPath（默認 $DSH_HOME/compaction-debug.log）。
分詞是字符規則，不是模型 tokenizer：連續英文字母算 1、連續數字算 1、中文每個字 1（你好，世界！ 爲 6）。Harness 自帶的 tokenMeter 仍用 字符數 / 4 + 塊開銷 做縮小檢查和 /compact 用量報告，兩套算法並存。
適用場景與注意事項¶
比較適合：
- 工具密集的編碼會話，歷史裏大量
read/write/bash結果，摘要既貴又容易丟路徑。 - 希望壓縮確定、可復現，同一段歷史每次編譯結果一致。
- 需要在壓縮後按
seq把原文找回來，而不是依賴模型「回憶摘要裏寫過什麼」。
需要降低預期的情況：
- 以長敘述、討論爲主的歷史，檢查點是截斷不是合併，密度可能不如 LLM 摘要。
- 默認
checkpointCap: 65536在超長工具會話上會丟掉大量舊條目；完整內容在日誌裏，模型當下看不見，除非recall。 - DeepSeek Harness 仍處於 developer preview，官方倉庫寫明會有破壞性變更；本插件對 peer 依賴釘在
@deepseek-ai/dsh-*的^0.1.0-rc.6，升級 Harness 後要重新驗證能否掛載。
安裝與安全：
- 插件在當前 dsh 進程權限下運行，等於信任這份源碼。裝前讀倉庫和 MIT 許可證，重要環境建議固定 commit，並先在一次性 profile 裏試。
- 社區目錄不是官方審計。目錄頁和 GitHub 都要打開覈對，安裝命令以目錄頁原文爲準，啓用步驟以倉庫 README 爲準。
- 每個上下文只能有一個壓縮後端。別名安裝和直接安裝不要疊出兩個
ctx.compaction。
小結¶
dsh-compaction-instant 把 dsh 的上下文壓縮從「再調一次模型做摘要」，換成「確定性編譯原文 + seq 回讀」。工具密集會話上，倉庫自己的日誌顯示壓縮主要來自工具結果不佔位和調用單行化；敘述型對話則要接受截斷，並靠 recall / search 補回細節。
目錄頁：https://deepseek-harness-plugin.com/zh-CN/plugins/dsh-compaction-instant/
GitHub：https://github.com/KitDoesIt/dsh-compaction-instant
壓縮能力縫說明：https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/compaction
