前言¶

在 DSH（DeepSeek Harness）裏跑 Agent 時，bash、pwsh、web_fetch、run_code 等工具很容易吐出幾十萬字符的日誌或搜索結果。這些內容會佔滿上下文窗口，而真正需要推理的錯誤行、diff 改動反而沒地方展開。常見做法要麼整段丟棄（丟信息），要麼原樣留給模型（窗口爆炸）。bale 是維護者 AQYLPZ 發佈的 DSH 工作流類插件：在模型看到輸出之前，把大塊文本壓成帶類型的摘要，同時按內容哈希把原文存到本地；需要細節時通過 headroom_retrieve(hash) 取回完整字節。本文介紹其定位、架構、安裝與配置，事實均出自 GitHub README 與倉庫內 package.json。

這是什麼¶

bale 的 package.json 描述爲：在工具輸出進入模型上下文之前進行壓縮，並支持基於哈希的原文檢索。它掛在 DSH 的 tools/post-execute 鉤子上，針對白名單工具的大輸出調用本地 sidecar（http://127.0.0.1:8797/compress），用壓縮結果替換模型所見內容；壓縮失敗時採用 fail-open，原樣放行，不讓壓縮拖垮工具調用。

社區目錄頁：https://www.skillhub.cn/plugins/AQYLPZ/bale。SkillHub 爲社區插件目錄，與 DeepSeek / 幻方無官方從屬關係。README 記載當前包版本爲 0.1.5，許可證 MIT，GitHub 星標以目錄頁爲準（撰寫時爲 0）。

核心功能¶

壓縮策略與 kind¶

sidecar 會識別內容類型並選擇策略，返回字段包含 kind、hash、text、ratio。README 列出的類型與實測比例如下：

README 給出的樣例：24,611 字符構建日誌 → 7,531 字符（30.6%，ERROR/WARN 零丟失）；28,544 字符 grep → 1,750 字符（6.1%）；13,763 字符 git diff → 2,538 字符（18.4%，-/+ 改動行完整保留）。設計原則寫的是：寧可少壓，也不造假。

基於 Kompress ONNX 的 text（語義壓縮）在 README 中標記爲已停用（收益低、易超時）；sidecar 默認通過 HEADROOM_DISABLED_KINDS=text 短路。

雙進程架構¶

原文按字節寫入 store/<sha256[:16]>.bin。壓縮算法依賴 Python 庫 headroom-ai（倉庫內爲精簡重打包 wheel）。

默認介入的工具¶

配置默認白名單爲：ops_bash、bash、pwsh、web_fetch、run_code。另有 protectTools（如 read、edit、write 等）強制不壓縮。低於 minChars（默認 8192）或超過 maxChars（默認 32MB）時不壓縮。

安裝與啓用¶

安裝前請自行閱讀倉庫源碼與 MIT 許可證。bale 以當前 DSH 進程權限運行 sidecar 與寫本地 store，路徑與 Python 解釋器需按你的 profile 覈對。

前置要求¶

• DSH 桌面版或 CLI
• Node.js ≥ 20
• Python 3.10–3.14（README 實測 3.12.14 與 3.14.7）
• 預置 wheel 僅 Windows x64；macOS / Linux 需按 tools/repack/README.md 重打包

本項目未發佈到 npm（npm 上另有同名包）；README 要求用本地 npm pack 生成的 tgz 安裝。

步驟概覽¶

1. 獲取源碼並準備 Python 環境

README 的快速開始以克隆倉庫爲例（路徑 https://github.com/AQYLPZ/bale.git）。在倉庫根目錄創建 venv 並安裝依賴：

python -m venv venv

# Windows
venv/Scripts/python.exe -m pip install -r requirements.txt
# macOS / Linux
venv/bin/python -m pip install -r requirements.txt

也可使用 --find-links ./vendor/wheels 安裝 headroom-ai[code]==0.42.0.post1。README 明確：不要安裝 [ml] 額外組。插件裝入 profile 後，也可對 node_modules/bale/requirements.txt 執行同等安裝（0.1.4+ tgz 已含 vendor/wheels/）。

2. 打包插件

在倉庫根目錄執行：

npm pack

生成如 bale-0.1.5.tgz（README 示例）。將 tgz 放入 profile 的 vendor/，在 profile 的 package.json 中添加：

{
  "dependencies": {
    "bale": "file:./vendor/bale-0.1.5.tgz"
  },
  "dsh": {
    "profile": {
      "bundles": [ "bale" ]
    }
  }
}

然後執行 pnpm install。

3. 配置絕對路徑

在 profile 的 cordis.patch.yml 中增加（<PROFILE> 換爲實際絕對路徑）：

- id: bale
  name: bale
  config:
    enabled: true
    sidecarPython: '<PROFILE>/.headroom/venv/Scripts/pythonw.exe'
    sidecarScript: '<PROFILE>/node_modules/bale/sidecar/sidecar.py'
    storeDir: '<PROFILE>/.headroom/store'
    wsDir: '<PROFILE>/.headroom/headroom_ws'
    logFile: '<PROFILE>/.headroom/logs/headroom-auto.log'

README 強調：必須寫絕對路徑；默認從 lib/ 推導 venv 在真實目錄下可能算錯，sidecar 起不來時會靜默 fail-open，表面正常卻無壓縮。

4. 重啓 DSH 並探活

curl http://127.0.0.1:8797/health

期望形如 {"ok": true, "version": "0.1.5", ...}；compressors_loaded 初始爲空屬正常（懶加載）。

典型用法¶

自動壓縮¶

滿足白名單工具、長度閾值且 sidecar 可用時，大輸出會在進入模型前被替換爲「壓縮頭 + 摘要」，並附帶可用於檢索的 hash。無需額外調用即可節省上下文。

按哈希取回原文¶

當模型或工作流需要完整輸出時，使用插件註冊的 headroom_retrieve(hash)，按 README 說明從本地 store 逐字節取回與壓縮前一致的內容。

常用配置項（節選）¶

完整表見 README「配置參考」。

適用場景與注意¶

適合誰：長期在 DSH 裏用 Shell、抓取網頁、跑代碼塊，且經常遇到「日誌/tests/build 輸出撐爆上下文」的 Agent 開發者；希望保留 ERROR/WARN、diff 改動與可檢索原文，而不是粗暴截斷。

務必注意：

• sidecar 異常、超時或任一步失敗時 fail-open，輸出不壓縮；排障可看 README「排障」與健康檢查。
• Windows 以外需自行重打包 wheel；網絡需能拉取 PyPI 傳遞依賴。
• 卸載與 store 瘦身見 README「卸載」；0.1.5+ 對 store 口徑有修復說明。

結尾¶

bale 把「大工具輸出」從上下文中摘出來，換成結構化摘要 + 本地哈希存儲，在 DSH 工作流裏給模型留出 headroom，又不丟掉按 hash 還原原文的能力。進一步瞭解可看 SkillHub 目錄頁 與 GitHub 倉庫。