上下文压缩引擎 WanYanTianDe/dsh-headroom

dsh-headroom

给 DeepSeek Harness 装的「省钱引擎」：对话太长时自动把旧内容压紧、大工具输出自动瘦身，少烧 token；需要细节时，模型还能自动找回原文。

非官方社区插件，与 Headroom Labs / DeepSeek 无隶属关系。

装它

方式一：npm 安装（推荐，已发布到 npm registry）

在 profile 目录(~/.dsh/profiles/web)执行,把包装进 profile:
pnpm add @wanyantiande/dsh-headroom

然后编辑 cordis.patch.yml,加:
- insert:
- id: dsh-headroom
name: '@wanyantiande/dsh-headroom'

重启 dsh web 即可用，打开 设置 → 插件 能看到 「Headroom 压缩」 卡片。

方式二：从源码装（开发/本地修改用）

1. 拿到代码
git clone https://github.com/WanYanTianDe/dsh-headroom.git
cd dsh-headroom

2. 一键安装(默认装进 web profile)
node scripts/install.mjs

脚本会自动把插件装进 profile 并配好，然后重启 dsh web 就能用。

手动装也可以，就两步：
dsh plugin --profile web add link:这个插件的路径
然后编辑 ~/.dsh/profiles/web/cordis.patch.yml,加:
- insert:
- id: dsh-headroom
name: '@wanyantiande/dsh-headroom'

用起来（什么都不用做）

- 插件会自动准备好本地压缩服务（第一次会自动下载，稍等一会儿）
- 对话变长后，旧内容会被自动压缩，省 token
- 大工具输出（默认超过 8192 字符）也会被自动压缩
- 压缩不等于删除——原文都存着，模型需要细节时会自己取回

功能

| 组件 | 说明 |
| 代理生命周期 | 启动时探测 127.0.0.1:8787；无服务则自动发现 headroom 命令，缺失时经 uv tool install headroom-ai[all] 引导安装；然后 spawn headroom proxy，等待健康后挂载 ctx.headroomClient。设置变更时串行重启（复用不杀旧代理；启动配置变更强制换代理）。插件卸载时清理进程树。 |
| 历史压缩 | 对话 token 压力/溢出时，把选中的历史区间发给本地代理 POST /v1/compress，压缩结果文本化为 checkpoint 写入会话。继承 harness 压缩后端全部机制（region 事务/压力触发/溢出恢复/持久化）。 |
| 工具输出压缩 | 每次模型请求前（step 边界），把超过阈值的大工具输出经代理压缩并影子替换为压缩文本；原文留在会话日志（可重建），模型可经 headroom_retrieve 取回完整内容。无收益（<20% token 节省）或代理不可用时保留原文。 |
| 取回工具 | headroom_retrieve(hash) → POST /v1/retrieve，模型按压缩文本/checkpoint 中的 ccr hash 取回被压缩的原文（历史与工具输出通用）。 |
| 配置命令 | /headroom 对话命令：查看/修改代理与压缩设置（写同一 settings 命名空间，不依赖设置面板）；设置卡片因 harness 白名单限制可能不可见（见「配置」章节）。 |

配置

方式一：对话命令 /headroom（所有环境可用）

在任意会话输入（agent 也会执行）：

/headroom # 查看当前生效配置 /headroom set port 9000 # 修改配置(数字/布尔/字符串按类型解析) /headroom unset port # 恢复组合层默认

可设置键：port、baseUrl、command、pythonPath、uvCommand、autoInstall、resultCompressionEnabled、resultCompressionThresholdChars。

方式二：设置卡片（需要 harness 白名单支持）

设置 → 插件 → 插件配置 里的「Headroom 压缩」卡片依赖 harness 的配置客户端暴露白名单（api-proxy.ts 的 WEB_SETTINGS_NAMESPACES，官方注释承认是待办）。外部插件默认不在白名单中，卡片会不可见——这是 harness 的限制，不是插件缺陷。两种解决：
- 在 harness 的 WEB_SETTINGS_NAMESPACES 加 'headroom'（一行）后重启；
- 或直接用 /headroom 命令（方式一，无此限制）。

方式三：settings.yaml / cordis config

~/.dsh/settings.yaml 的 headroom 段 headroom: port: 8787 command: '' # 留空自动发现 autoInstall: true

插件 entry 的 config 下(设置面板未覆盖的高级项): config: compressMode: 'ccr' # 压缩请求模式:'ccr' 写入 CCR 取回 hash(默认,headroom_retrieve 可用);'default' 关闭 prewarm: true # 启动时预热 Kompress 模型(默认 true,避免首个请求被跳过) headroom: savingsProfile: 'coding' # 代理压缩画像:'agent-90' = 全部内容强制 Kompress 压缩(激进有损) kompressMustKeep: true # 保留数字/路径/标识符;false 时 JSON 收益可达 96%,但精确值会被丢弃(须配合 CCR) resultCompression: minSavingsRatio: 0.15 # 工具输出压缩的最小收益比例(默认 0.15) maxPerStep: 3 # 单次 step 最多压缩条数(默认 3) thresholdRatio: 0.8 # 历史压缩压力阈值(默认 0.8,继承 BasicCompactionConfig) retainRatio: 0.16 # 历史保留比例(默认 0.16) auto: true # 自动压缩开关(默认 true)

行为与限制

- 压缩发生在 step 边界;替换遵循 harness 影子节点协议,消息保持可重建(会话日志是唯一事实源)。
- checkpoint 必须比原文小,否则事务失败并保留原文(继承的安全语义)。
- 无 headroom 服务时插件保持加载、压缩自动禁用,DSH 其余功能不受影响。
- 后端为本地 Python 服务(uv 工具),首次自动安装约数百 MB;Kompress 模型(chopratejas/kompress-v2-base,261MB ONNX)首次压缩时自动下载,插件启动预热,之后压缩走 ML 有损路径(散文 33.5%,激进配置 JSON 96%)。
- 工具输出压缩默认阈值 8192 字符、最低收益 15%;低于阈值不压缩,收益不足不替换(负收益内容永远不会比不装更差)。
- CCR 原文取回可用(0.3.0 起):压缩请求默认 mode: 'ccr',有损替换写入 CCR store,headroom_retrieve 按 hash 恢复原文。
- kompressMustKeep: false 是有损激进模式(数字/ID/路径可能被丢弃),务必保持 CCR 模式以便取回。
- 与 harness 的 compaction-basic 冲突时自动接管(见 FAQ)。
- 完整实测数据见下方「性能实测」章节。

性能实测

环境:headroom 0.35.0(OSS,Kompress ONNX 模型已加载)+ DeepSeek Harness web 会话。合成测量对真实代理 POST /v1/compress;端到端为真实会话日志统计。

按内容类型的压缩收益(上限/下限)

lossless 路径(0.2.x,模型未启用时):

| 内容类型 | 压缩收益 | 角色 |
| 中文散文 | 52.6% | 上限(upper bound) |
| 英文/混合散文 | 24.3% ~ 33% | 上限 |
| 代码(AST 感知) | 27.5% | 高 |
| 复杂 JSON | 17.8% ~ 30.4% | 中 |
| 日志 / 简单文本 | ~0% | 下限(lower bound) |
| 重复 JSON | -15%(变差) | 下限:被 15% 门槛拦截,保留原文 |

Kompress(ML 有损)路径(0.3.0 起,模型自动下载+预热):

| 场景 | 压缩收益 | 说明 |
| 中文散文(默认 profile) | 33.5% | router:text (Kompress) |
| JSON(agent-90 + kompressMustKeep: false) | 96.6% | router:kompress:0.03;精确值被丢弃,须 CCR 取回 |
| JSON(agent-90,默认 must-keep) | ~9% | must-keep 规则保留数字/路径,紧凑 JSON 几乎全命中 |
| CCR 恢复 | 完整 | /v1/retrieve 按 hash 取回 56,803 字符原文(实测) |

端到端实测(真实会话)

- 5 次影子替换落地(每次含 compaction/prune 定价事件 + tool/result 替换,会话日志可重建)。
- 实际压缩收益 24.3% / 30.4% / 33%(text/mixed 压缩器)。
- 0% 收益候选被正确跳过(不替换、不劣化)。
- headless 一次性模式:修复后 compaction/start/end 事件与代理压缩请求均出现(0.3.0)。

历史压缩(长会话)

- 早前实测:2410 → 1619 tokens(33% 收益),触发于上下文压力/溢出。

结论:节省区间

默认配置下,装比不装节省 0% ~ 53%(工具输出压缩 + 历史压缩叠加);开启 Kompress 激进模式(agent-90 + kompressMustKeep: false)后 JSON 类内容可达 96%,整体上限大幅上移:

| 负载画像 | lossless(默认) | Kompress 激进 |
| 散文密集(文档阅读/总结) | 25% ~ 53% | 30% ~ 60%+ |
| 开发混合(代码/JSON) | 18% ~ 33% | JSON 类 60% ~ 96% |
| 日志/重复数据(构建输出) | ~0%(无损失) | 视 must-keep 配置 |

插件保证下限恒为 0%——负收益内容被收益门槛拦截,低于阈值的内容不触发。

常见问题

Q: 装不上 / 服务起不来? 先手动把服务装好再重启试试:
uv tool install "headroom-ai[all]"
或者看设置卡片上的提示。

Q: 压缩会把内容弄丢吗?
不会。原文都存在本地,模型需要时会自动取回(工具 headroom_retrieve)。

Q: 想用自己电脑上的 Python 跑? 设置卡片填 Python 路径保存即可,马上换。

Q: 和 dsh-compressor 有什么区别?
它只压缩工具的输出,我们历史压缩和工具输出压缩都做(0.2.0 起内置工具输出压缩),取回统一走 headroom_retrieve。装了本插件就不需要 dsh-compressor 了;两者并存也无冲突。

Q: 装了它,原来的 compaction-basic 会怎样? 会自动被本插件接管:启动时若发现压缩服务已被 compaction-basic 占用,插件会禁用 compaction-basic 的装配条目(写入你的 cordis.patch.yml,preset 文件不会被改写)并注册 headroom 压缩引擎;卸载插件时自动恢复原状态。如果不想让 headroom 接管压缩,请勿同时启用两者。

给开发者

bash scripts/build.sh # 构建:类型检查 + 测试 + 打包(需要 DSH 源码,见下)bash
pnpm test # 测试(37 例,不需要 DSH 源码)
pnpm typecheck # 类型检查
pnpm build # 打包 → lib/index.js + lib/client.js

构建需要 DSH 源码：设环境变量 DSH_CHECKOUT 指向 DSH 源码目录，或建链接 ~/.dsh/source/current → DSH 源码目录。插件目录放在 ~/.dsh/plugins/ 下（开发依赖用相对路径引用 DSH 检出）。

收录信息

| 项 | 值 |
| npm 包名 | @wanyantiande/dsh-headroom（npm registry，public） |
| GitHub topic | dsh-plugin |
| 分类（taxonomy v2） | 🤖 Agent 能力 |
| 测试 | vitest 37 例（format/service/takeover/result-compressor/controller） |
| 许可 | MIT（插件）；依赖的 Headroom 为 Apache-2.0，DSH 为 MIT |

许可

- 插件本体：MIT（见 LICENSE）
- 依赖的 Headroom：Apache-2.0
- 依赖的 DeepSeek Harness：MIT

插件不捆绑 headroom 的代码，通过 uv 安装其发行版并调用本地服务。