前言¶

在 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 机制保证内容可逆。对于需要处理长对话或大量结构化数据输出的智能体开发者，安装该插件能有效降低成本并维持长程推理能力。