前言¶

在 2026 年的智能體開發中，上下文窗口依然是硬約束。當對話變長或工具輸出（如代碼分析、日誌導出）超過 8192 字符時，token 消耗會迅速攀升。dsh-headroom 是一個專爲 DeepSeek Harness（DSH）設計的本地代理插件，它通過管理一個本地 Python 服務，在後臺自動壓縮歷史對話和大工具輸出，在不丟失語義的前提下減少 token 燃燒。插件本身非官方，由社區開發者 WanYanTianDe 維護，採用 MIT 許可證。

安裝與啓用¶

安裝插件最簡單的方式是通過 npm 安裝包。在 ~/.dsh/profiles/web 目錄下執行以下命令：

pnpm add @wanyantiande/dsh-headroom

安裝完成後，需要編輯 ~/.dsh/profiles/web/cordis.patch.yml 文件，將插件註冊進去：

- insert:
    - id: dsh-headroom
      name: '@wanyantiande/dsh-headroom'

保存並重啓 DSH Web 界面。首次運行時，插件會自動準備本地壓縮服務，首次下載模型文件大約需要數百 MB 的空間。如果需要從源碼安裝或進行本地開發，可以克隆倉庫後運行 node scripts/install.mjs。

核心功能¶

該插件主要包含以下五個組件：

1. 代理生命週期：插件啓動時探測 127.0.0.1:8787。若無服務，會嘗試通過 uv tool install headroom-ai[all] 自動安裝，然後啓動 headroom proxy 進程。代理健康後掛載 ctx.headroomClient。設置變更時，插件會串行重啓代理（複用舊代理，配置變更強制換代理）。卸載時會清理進程樹。
2. 歷史壓縮：當對話 token 壓力或溢出時，插件會選取歷史區間，通過本地代理的 /v1/compress 接口進行壓縮，並將結果寫入會話的 checkpoint 中。這繼承了 Harness 壓縮後端的事務和持久化機制。
3. 工具輸出壓縮：在模型請求的 step 邊界，插件會檢查工具輸出是否超過閾值（默認 8192 字符）。如果超過，會將其壓縮並影子替換爲壓縮文本，原文保留在會話日誌中。只有當壓縮收益超過 20%（默認值）或代理可用時纔會執行替換。
4. 取回工具：插件提供了 headroom_retrieve(hash) 工具。模型在需要細節時可以調用此工具，通過 POST /v1/retrieve 接口按 hash 取回被壓縮的原文（適用於歷史記錄和工具輸出）。
5. 配置命令：提供一個 /headroom 對話命令，用於查看和修改壓縮配置。

配置與使用¶

插件支持兩種配置方式：對話命令和配置文件。

1. 對話命令（推薦）¶

在任意會話中輸入以下命令即可查看或修改配置：

/headroom                          # 查看當前配置
/headroom set port 9000            # 修改端口號
/headroom set autoInstall true     # 修改布爾值
/headroom unset port               # 恢復默認

可配置的鍵包括 port、baseUrl、command、pythonPath、uvCommand、autoInstall、resultCompressionEnabled、resultCompressionThresholdChars。

2. 配置文件¶

也可以直接修改 ~/.dsh/settings.yaml 或插件的 config 部分。關鍵配置項如下：

headroom:
  port: 8787
  autoInstall: true
config:
  compressMode: 'ccr'         # 使用 CCR 模式以便取回原文
  prewarm: true               # 啓動時預熱模型
  headroom:
    savingsProfile: 'coding'  # 壓縮畫像
    kompressMustKeep: true    # 是否保留數字和路徑（設爲 false 可獲得更高 JSON 壓縮率）
  resultCompression:
    minSavingsRatio: 0.15     # 工具輸出壓縮的最小收益比例
    maxPerStep: 3             # 單次最多壓縮條數
  thresholdRatio: 0.8         # 歷史壓縮壓力閾值
  auto: true                  # 自動壓縮開關

3. 設置卡片限制¶

插件在 DSH 設置面板中提供了一個 “Headroom 壓縮” 卡片。由於 Harness 的 WEB_SETTINGS_NAMESPACES 白名單限制，外部插件默認無法通過設置卡片配置。如果卡片不可見，請直接使用 /headroom 命令或配置文件。

性能與限制¶

• 壓縮機制：壓縮遵循 Harness 的影子節點協議，消息可重建，會話日誌是唯一事實源。
• 安全性：如果壓縮後比原文大，事務會失敗並保留原文。插件保證下限收益爲 0%，不會比不裝更差。
• 衝突處理：當插件與 Harness 的 compaction-basic 同時啓用時，插件會自動接管 compaction-basic 的裝配條目，無需手動處理。
• 非捆綁代碼：插件本身不包含 headroom 的代碼，而是通過 uv 安裝其發行版並調用本地服務。

性能實測數據¶

根據 README 提供的實測數據，不同配置下的壓縮收益如下：

• lossless 路徑（默認配置）：中文散文約 52.6%，英文/混合約 24.3% ~ 33%。
• Kompress 有損路徑（0.3.0+，默認 profile）：中文散文約 33.5%。
• JSON 壓縮：
  • 默認 mustKeep：約 9%。
  • 激進模式（kompressMustKeep: false）：高達 96.6%（但會丟失精確數值，需配合 CCR 取回）。

常見問題¶

• 裝不上怎麼辦？ 先手動安裝服務：uv tool install "headroom-ai[all]"。
• 會丟失內容嗎？ 不會。所有原文都保存在本地，模型需要時通過 headroom_retrieve 取回。
• 區別於 dsh-compressor？ dsh-headroom 同時提供歷史壓縮和工具輸出壓縮，而 dsh-compressor 僅壓縮工具輸出。

總結¶

dsh-headroom 是一個解決長上下文 token 消耗問題的實用工具。它通過本地代理自動管理壓縮生命週期，利用 CCR 機制保證內容可逆。對於需要處理長對話或大量結構化數據輸出的智能體開發者，安裝該插件能有效降低成本並維持長程推理能力。