前言¶
DeepSeek Harness（DSH）採用插件化架構，旨在通過擴展組件解決長會話中的 Token 開銷問題。dsh-token-optimizer 作爲一個分層 Token 優化管道，不重複實現 DSH 核心已有的壓縮能力，而是基於真實 API 實現增量壓縮與調度，幫助在保持模型能力的前提下降低 Token 消耗。
插件定位¶
- 名稱：
dsh-token-optimizer - 維護者：Zoria-Lind
- 分類：模型推理
- 許可證：MIT
- 定位：基於 DSH 插件 API 的增量壓縮與調度插件。
核心功能¶
該插件通過多個模塊協作，覆蓋文本處理、工具輸出、文件管理和會話調度四個維度：
- 分層壓縮編排 (layeredCompact)：實現 L0 觀測、L1 無損裁剪、L2 有損壓縮的分級策略。
- 長文本轉圖摘要：針對長文本（≥1000 字符），支持渲染成圖並由 Vision 模型讀取摘要，動態調整分辨率。
- 工具輸出分流：根據輸出類型（錯誤結果、JSON/CSV、Shell 輸出）進行結構感知壓縮或採樣。
- 文件差異檢測：檢測重複讀文件操作，未變則摺疊，有變僅發送變更區段。
- 工具可見性管理：通過靜態裁剪與 MCP 懶加載，減少無用工具 Schema 進請求。
- 壓縮調度：在 Agent 空閒時，按自定義壓力比驅動核心壓縮，解決長會話窗口無法觸發壓縮的問題。
- 會話統計：提供會話結束後的 Token 節省統計、真實 Usage 聚合與緩存命中率。
安裝¶
在 DSH 項目目錄下執行以下命令安裝插件：
dsh plugin --profile web add ./dsh-token-optimizer
配置¶
插件掛載後，需在 Profile 的 cordis.patch.yml 中進行配置。由於 Web 部署默認禁用了核心壓縮後端，必須手動啓用：
- id: compaction-basic
disabled: false
- id: command-compact
disabled: false
插件主要配置節包括：
* text2img：控制長文本轉圖摘要的閾值、分辨率分檔與緩存策略。
* outputLadder：配置工具輸出的壓縮率、保留頭尾行數及 Shell 採樣間隔。
* fileDiff：設置文件差異檢測的最小大小與上下文行數。
* toolTrim：控制工具可見性管理與 MCP 懶加載開關（默認關閉）。
* compactionDriver：設置觸發壓縮的壓力比（默認 45%）與最小 Token 數。
權限與邊界¶
本插件屬於高權限插件，運行時需要訪問文件、網絡、命令與憑據。其具體行爲邊界如下：
- 文件邊界：僅寫入插件自有狀態目錄（
~/.dsh/token-optimizer/）與臨時產物，不修改 Profile 配置或 DSH 核心。 - 網絡邊界：僅向
https://api.deepseek.com/v1發送請求（用於摘要）。 - 命令邊界：Windows 上使用 PowerShell + .NET System.Drawing 進行文本渲染；非 Windows 自動降級爲僅落盤。
- 憑據邊界：僅用於
text2img的 Vision 調用，不落盤、不外傳。 - 失敗邊界：所有模塊採用 Fail-open 策略，任一步出錯僅降級跳過（保留原文），不影響核心流程。
- 運行時依賴：零 npm 依賴（除外部服務）。
兼容範圍¶
- DSH 版本：基於 DSH >= 0.1.1-rc.2。
- Node 版本：Node >= 18。
- 已知未驗證版本：0.1.2+ 與 0.1.3+ 尚未驗證兼容性。
結語¶
dsh-token-optimizer 通過分層壓縮、智能分流與懶加載機制，爲 DSH 提供了針對性的 Token 優化方案。其 fail-open 的設計保證了在不穩定環境下的可用性。完整源碼與文檔可參考 GitHub 倉庫。
