前言¶
DSH 的會話跑久了，歷史前綴會撐大每次請求的 token 數。原生 Basic 壓縮負責給人留一口氣，但它不關心這次壓縮到底走了沒走緩存、也不關心這個模型的緩存價格。lloydzhou/dsh-smart-compaction 就是衝着這個縫來的：它把壓縮執行和「經濟策略」拆開，執行走緩存優先，策略層默認只做觀察、不替用戶做決定。
它屬於「模型推理」分類，維護者是 lloydzhou。下面介紹這個插件做了什麼、怎麼裝、怎麼確認它真的在跑。
這是什麼¶
一句話：一個可發佈的 npm 包、一個 DSH 插件入口，內部分離壓縮執行與自適應經濟策略，不需要額外裝第二個策略包，不修改 DSH 宿主。
它明確不做三件事：不保證緩存命中、不保證全局最低費用、不僞造模型的貨幣價格字段。
插件版本跟隨 DSH 的三段版本線（0.2.1），RC 序號獨立遞增。README 裏安裝示例寫的是 0.2.1-rc.1，倉庫 package.json 的 version 字段當前是 0.2.1-rc.3；宿主兼容範圍由 engines.dsh 單獨聲明，是 >=0.2.1-rc.3。README 與 package.json 的版本表述不完全一致，實際安裝時以你要裝的 RC 序號爲準，並按目標宿主的兼容範圍覈對。
核心功能¶
緩存優先壓縮¶
引擎以 cacheFirst（默認開）爲開關。開着時，摘要請求儘量沿用已有的緩存後綴；關閉時回落到原生 BasicCompactionEngine，同時自適應策略失效。
摘要參數連續性¶
同一個會話、同一個 provider/model 下，原生摘要請求如果沒有顯式提供 reasoningEffort，插件會從最後一次已路由的 request header 補齊。不同路由之間不繼承，已有參數不覆蓋。它只修參數連續性，不證明 effort 一定影響緩存。相關討論見 DSH #11816。
自適應經濟策略¶
adaptive.mode 取 off / observe（默認）/ active。策略按每次決策讀取，改完不用重啓。
RC.3 / RC.5 的公開模型元數據裏沒有貨幣價格字段，插件不會假裝能讀出來。默認缺價時使用 DeepSeek V4.1 Flash 官方峯時 USD 參考價格，並在策略日誌的 pricing 裏標明來源、日期和參考型號，這不是當前路由的真實賬單。referencePriceFallback: false 可以關掉這個兜底；缺價或幣種不兼容時返回 missing-prices，固定策略和硬壓力保護仍然有效。observe 始終不應用經濟建議。
結構化日誌¶
啓用 cacheFirst 時（不論 adaptive 是否關閉），後端在 info 級別輸出 cache-first-compaction/operation 和 cache-first-compaction/result，字段包括 sessionId、唯一 operationId、trigger、status、surfaceChanged，每次 summary attempt 還帶持久化的 compactionId。它不寫聊天上下文，不記錄 prompt、摘要文本、工具輸出或原始錯誤消息。
幾個容易誤讀的點：
summaryAttempts是真正進入 stock summarize hook 的次數，含重試、失敗、取消，不等於模型調用次數。llmStreamCalls/calls[]記錄的是實際觀測到的公開llm/stream調用，evidence字段區分來源。不能把 stream 調用直接當成已計費請求——公開 waterfall 在 adapter 查找、prepare 與真正 dispatch 之前就觸發，只有裁剪/無摘要時纔是modelCalls: 0、providerDispatch: none。usage.inputTokens是未緩存輸入，DSH 三類輸入計數互斥，完整計數時promptTokens = inputTokens + cacheReadTokens + cacheWriteTokens。缺失計數記爲null而不是 0，失敗且未報告 usage 的調用不會當作零消耗。knownUsageTotals只彙總已報告字段，不是完整總成本。
默認 adaptive.mode: observe 時，有請求 header 後會在自動壓力檢查中記錄 adaptive-compaction/decision 結構化 info 日誌。這些日誌在運行該會話的 DSH 進程日誌或日誌導出器裏找，不在聊天消息裏，具體路徑由宿主配置決定。
Chat UI 壓縮卡片¶
外部 client bundle 複用公開的 conversation.chat.node 的 compaction 與 manual-compaction 渲染插槽，保留摘要和原有估算數量。摺疊時是單行，在原文本後追加觀測到的摘要流調用數和緩存比例；展開後先看決策與實際執行詳情，再看原摘要。診斷採用實驗性的 ignorable plugin records，不進模型上下文，最多保留最近 64 次有意義的操作。README 裏寫明尚未在運行中的 GUI 驗證視覺效果，需要更新客戶端並刷新後確認。
安裝與啓用¶
發佈到 npm 之後的安裝命令（web 與 desktop 兩個 profile 裝同一個包）：
dsh plugin --profile web add dsh-smart-compaction@0.2.1-rc.1
dsh plugin --profile desktop add dsh-smart-compaction@0.2.1-rc.1
本地開發用 pnpm link，需要注意鏈接包不會按普通規則從目標 node_modules 解析 peers，這是鏈接模式的通用提醒，不等於 DSH 解析失敗。構建產物打成 tarball 後，由操作者明確執行：
npm ci
npm run build
npm run typecheck
npm test
npm pack
dsh plugin --profile web add ./dsh-smart-compaction-0.2.1-rc.1.tgz
環境要求：Node.js >=24.9.0，驗證過的宿主是 DSH 0.2.1-rc.3 與 0.2.1-rc.5，Cordis 4.0.5，Schemastery 3.18.5。README 同時註明「尚未發佈到 npm」，說明上述命令是發佈流程落地後的形態。
啓用與禁用¶
RC.3 / RC.5 會爲運行中的 Agent 保留舊引擎版本，公開接口不支持非空會話直接換引擎。切換後必須重啓 Web，再恢復原會話，不用新建、不改歷史。正在執行的壓縮也不要中途重啓。
- 啓用 bundle 或主開關：啓動適配器從當前 standard 配置派生插件引擎。
- 禁用主條目
smart-compaction-integration：保留 bundle 的啓動適配器，下次啓動註冊未經轉換的原生 standard，舊 smart-compaction 別名也指向原生配置。 - 禁用整個 bundle：整層 patch 撤銷，原宿主 standard 聲明恢復。
前端用公開優先級 -10 覆蓋原生優先級 0，保留原生註冊。smart-compaction-preset-adapter 只是 bundle 的啓動連接組件，不是第二個功能開關，不要單獨禁用它。
設置表單¶
插件詳情頁（插件 → 智能壓縮）有兩個即時寫入當前 profile 的設置，對應根條目 smart-compaction-integration 的 volatile 字段：cacheFirst（默認開）和 adaptiveMode（off / observe（默認）/ active）。表單要求 profile 中根條目 id 爲 smart-compaction-integration。
兩種開關組合的行爲：
| cacheFirst | adaptive.mode | 行爲 |
|---|---|---|
| true（默認） | observe（默認） | 緩存優先執行；只記錄經濟建議，不應用建議 |
| true | off | 固定配置的緩存優先執行，不安裝策略觀察器 |
| true | active | 緩存優先執行，啓用有界經濟策略 |
| false | off | 原生 BasicCompactionEngine，不安裝策略觀察器 |
| false | observe / active / 未填寫 | 拒絕配置，必須顯式設爲 off |
典型用法¶
安裝並重啓宿主後，既有 standard 會話會使用動態派生的壓縮配置，不需要另開會話。插件頁面顯示 agent-preset / Running 只說明 preset 聲明已經註冊，不證明當前會話真的用了這個引擎，要靠日誌確認。
確認一次實際運行：
- 打開宿主 info 級別日誌。
- 觸發一次自動壓力檢查或手動
/compact。 - 在宿主進程日誌裏找
cache-first-compaction/operation與cache-first-compaction/result。 - 實際摘要成功時，宿主日誌含
compaction (step pressure): shadowed ...或 overflow recovery；會話持久化日誌裏有compaction/start、compaction/summary、替換消息和compaction/end。僅工具裁剪用compaction/prune，不會憑空出現 summary 記錄。
注意 decisionApplied: true 只表示 active 策略返回了決策，不證明已經壓縮，更不代表省了錢。off 不生成策略日誌，也沒有 header 時不會產生策略檢查。後端策略日誌帶 sessionId / operationId，可以和執行日誌對上。
適用場景與注意事項¶
適合已經在用 standard preset、想搞清楚壓縮到底有沒有走緩存的 DSH 開發者。想先觀察再決定，用默認的 cacheFirst: true + adaptiveMode: observe；要用固定緩存優先策略，設 off；要把有界經濟建議真正接進決策，設 active。非 standard 的自定義 preset 仍需顯式接入，插件不會強行劫持其他壓縮實現。
幾點要注意：
- 插件以當前 DSH 進程權限運行，安裝前應檢查源碼與許可證（倉庫聲明 MIT）。
- 安裝時可能同時報出該 profile 已有插件的版本衝突。按警告裏的包名處理：舊 browser/computer-use、子代理或 usage-stats 的精確版本/範圍衝突不屬於本插件。優先升級或禁用不兼容插件，不建議直接授予版本豁免。
- 宿主運行庫被聲明爲 peerDependencies，鏈接安裝必須由宿主解析器共享這些庫，否則可能出現兩份 Session 導致公開插件記錄函數的類身份校驗失敗。診斷失敗會輸出一次無敏感內容的 warning。
client.inject聲明的是宿主提供的 UI/locale 服務依賴，只用於增強壓縮展示，不是另一套壓縮引擎。Desktop 實際界面啓停尚未單獨端到端驗收。- 不要用
npm install當作激活手段——它只裝文件，不激活 Cordis bundle。
結尾¶
這個插件的實際價值在於把「壓縮有沒有走緩存」和「緩存值多少錢」這兩件事拆開，並給觀察留出默認路徑，而不是一上來就把經濟決策塞進執行鏈路。想進一步覈對安裝與版本細節，見目錄頁和倉庫：
- 目錄頁：https://www.skillhub.cn/plugins/lloydzhou/dsh-smart-compaction
- GitHub：https://github.com/lloydzhou/dsh-smart-compaction
