dsh-token-diet: DeepSeek Harness 事前 token 節約工具集

前言¶

在 DeepSeek Harness (DSH) 的開發中，當輸入內容（如日誌、API 響應、數據報表）體積過大時，往往在模型處理指令之前就已經佔滿了上下文窗口。現有的 dsh-compaction-tool-result-pruner 屬於事後裁剪，而 dsh-token-diet 則是在內容進入上下文前進行結構保留摘要的純函數工具集。它通過零依賴的方式，在源頭減少 token 消耗。

核心功能¶

插件提供五個主要工具，根據輸入類型選擇使用：

diet_text：用於日誌、文檔、爬取正文。提取頭部 + 尾部 + 行數 + 高頻關鍵詞 + token 估算。
diet_json：用於 API 響應、配置文件。提取 key 骨架 + 類型/鍵數/數組長度 + 抽樣值。
diet_csv：用於數據文件、報表導出。統計列類型/distinct/min/max/avg + 抽樣行。
diet_estimate：用於任意文本。估算 token + 進上下文建議（決定讀全文、瘦身或跳過）。
diet_stats：累計節約統計。跨調用匯總 savedTotal。

節約反饋¶

每次調用瘦身工具（diet_text/json/csv）都會返回 saved 字段，提供真實節約數據：

{
  "kind": "csv",
  "rowCount": 8000,
  "colStats": [...],
  "saved": {
    "originalTokens": 38563,
    "outputTokens": 196,
    "savedTokens": 38367,
    "savedPercent": 99.5
  }
}

調用 diet_stats 可查看累計：

{
  "calls": 3,
  "originalTotal": 110272,
  "outputTotal": 1102,
  "savedTotal": 109170,
  "savedPercent": 99
}

壓縮配置¶

插件註冊 settings 命名空間 token-diet。支持三檔預設和手動壓縮比例。

三檔預設¶

在 Web UI 或 settings 文件中設置 preset：

light：保留更多細節，適合代碼評審。headChars: 2000, maxKeys: 25。
balanced（默認）：平衡骨架完整性與 token 減少。headChars: 800, maxKeys: 12。
aggressive：極致省 token，適合長會話。headChars: 300, maxKeys: 6。

手動壓縮比例¶

設置 compression: 0-99 直接指定壓縮強度：

0：不壓縮（mode: "raw"），用於對比基線。
99：極致壓縮。
系統在區間內線性插值覆蓋 headChars、maxKeys 等參數。

優先級鏈：工具顯式參數 > 工具 compression > settings compression > settings 逐項覆蓋 > 檔位默認值。

安全模型¶

純函數：不讀文件、不聯網、不執行 eval。
輸入上限：512KB，超限直接報錯，不截斷處理。
輸出格式：緊湊結構化 JSON 字符串。
Unicode 安全：按碼點截斷，不切開代理對，支持 emoji/生僻字。

安裝與啓用¶

在 cordis.yml 或 dsh.profile 中引入：

plugins:
  - id: tool-token-diet
    name: 'dsh-token-diet'

若需輕量級版本（單工具、無 settings 依賴），可使用 dsh-token-diet/lite：

plugins:
  - id: tool-token-diet-lite
    name: 'dsh-token-diet/lite'

技術要求¶

Node 版本：^22.19.0 || >=24.0.0。
依賴：@deepseek-ai/cordis、@deepseek-ai/dsh-tools。

總結¶

dsh-token-diet 通過結構保留摘要替代全量文本，實現了大文本/JSON/CSV 在進入上下文前的主動瘦身，配合真實的 token 節約反饋和可配置的壓縮策略，適合需要處理大量結構化數據或長日誌的 DSH 場景。