前言¶

在 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 仓库。