上下文压缩器 Asaka-RUM/dsh-headroom

dsh-headroom

为 DeepSeek Harness 提供 Headroom —— 内容感知的上下文压缩

Credits / 署名 — 本插件集成了 chopratejas 的 headroomlabs-ai/headroom（Apache-2.0，★67k+）—— 面向 AI 智能体的上下文压缩层。全部压缩智能（SmartCrusher、CodeCompressor、Kompress-v2、CacheAligner、CCR）都出自 Headroom 之手，在其本地代理中原样运行。本仓库只添加了 DeepSeek Harness 插件外壳（工具 + 自动压缩钩子）。许可证为 Apache-2.0，与上游一致。

署名声明 — 本插件集成了 chopratejas 的 headroomlabs-ai/headroom（Apache-2.0，★67k+）——AI 代理的上下文压缩层。全部压缩智能（SmartCrusher、CodeCompressor、Kompress-v2、CacheAligner、CCR）均为 Headroom 原作，在其本地代理中原样运行；本仓库只添加了 DeepSeek Harness 插件壳（工具 + 自动压缩钩子）。许可证与上游相同：Apache-2.0。

Headroom 会压缩智能体读到的一切内容 —— 工具输出、日志、JSON 转储、文件 —— 在它们送达 LLM 之前就压好。答案不变，token 只剩零头。本插件用 HTTP 把 DSH 接到本地 Headroom 代理上：插件进程里没有 Python，核心零补丁。

架构

DSH tools ──▶ tools/post-execute hook (opt-in) ──┐
▼
headroom_compress / headroom_retrieve / headroom_stats
│ HTTP
▼
Headroom proxy (localhost:8787) ← you run this
SmartCrusher(JSON) · CodeCompressor(AST) · Kompress-v2(prose)
CCR originals cache (reversible)

插件从不重新实现压缩器 —— 它只说代理的 REST API（POST /v1/compress、GET /health）。代理挂了，你拿到的是安装说明，不是悄悄塞进来的垃圾数据。

工具

| 工具 | 用途 |
| headroom_compress | 输入文本（可选 contentType 提示：json/code/log/prose/rag）→ 压缩后的文本 + token 节省统计 |
| headroom_retrieve | 按 block id 从 CCR 缓存取回原文 |
| headroom_stats | 代理健康状态 + 累计节省；也是最省事的「它活着吗？」检查 |

自动压缩钩子（可选开启）

打开 autoCompress: true 后，凡是大于 minChars 的工具结果，其展示内容都会被替换成压缩形式 —— 规范值对程序化调用方保持原样，同时告诉模型怎么取回原文。默认关闭。

前置条件

pip install "headroom-ai[all]" # or: uv tool install "headroom-ai[all]"
headroom proxy --port 8787 # leave running (any port; set baseUrl to match)

需要 Python 3.10+。代理挂掉时，插件会优雅降级。

安装（插件）

git clone https://github.com/Asaka-RUM/dsh-headroom E:\path\to\dsh-headroompowershell
New-Item -ItemType Junction -Path "$env:USERPROFILE\.dsh\profiles\web\node_modules\dsh-headroom" -Target "E:\path\to\dsh-headroom"

register in cordis.patch.yml insert list:

- id: headroom

name: 'dsh-headroom'

restart DSH

插件自身的 node_modules 必须能解析 @deepseek-ai/dsh-tools 和 cordis —— 把它 junction 到共享的 profile 存储： powershell New-Item -ItemType Junction -Path "E:\path\to\dsh-headroom\node_modules" -Target "$env:USERPROFILE\.dsh\profiles\node_modules"

配置（cordis 补丁） yaml
- id: headroom
name: 'dsh-headroom'
config:
baseUrl: 'http://127.0.0.1:8787'
timeoutMs: 20000
model: '' # optional model hint for /v1/compress
autoCompress: false # opt-in hook described above
minChars: 12000 # auto-compress threshold
excludeTools: [] # tool names never auto-compressed

Headroom 在代理读到内容之前——工具输出、日志、JSON 转储、文件——做内容感知压缩，答案不变，token 骤减。本插件让 DSH 通过 HTTP 对接本地 Headroom 代理：插件进程里不跑 Python，零核心补丁。

架构

DSH 工具 ──▶ tools/post-execute 钩子(可选开) ──┐ ▼ headroom_compress / headroom_retrieve / headroom_stats │ HTTP ▼ Headroom 代理 (localhost:8787) ← 由你启动
SmartCrusher(JSON) · CodeCompressor(AST) · Kompress-v2(文本)
CCR 原文缓存（可逆）

插件不重新实现任何压缩器——只讲代理的 REST API（POST /v1/compress、GET /health）。代理没起时给你安装指引，而不是静默输出垃圾。

工具

| 工具 | 用途 |
| headroom_compress | 文本进（可选 contentType 提示：json/code/log/prose/rag）→ 压缩文本 + 省 token 统计 |
| headroom_retrieve | 按 block id 从 CCR 缓存取回原文 |
| headroom_stats | 代理健康度 + 累计节省；也是最快的「起没起」检查 |

自动压缩钩子（默认关）

autoCompress: true 时，超过 minChars 的工具结果会把展示层 content 替换为压缩版——规范值原样保留给程序化消费者，模型会被告知如何取回原文。

前置条件 bash
pip install "headroom-ai[all]" # 或: uv tool install "headroom-ai[all]"
headroom proxy --port 8787 # 保持运行（端口任意；baseUrl 对应修改）

需要 Python 3.10+。代理不在时插件优雅降级。

安装（插件本体） powershell
git clone https://github.com/Asaka-RUM/dsh-headroom E:\path\to\dsh-headroom
New-Item -ItemType Junction -Path "$env:USERPROFILE\.dsh\profiles\web\node_modules\dsh-headroom" -Target "E:\path\to\dsh-headroom"

cordis.patch.yml insert 列表注册：

- id: headroom

name: 'dsh-headroom'

重启 DSH

插件自身 node_modules 需能解析 @deepseek-ai/dsh-tools 与 cordis——junction 到共享层： powershell New-Item -ItemType Junction -Path "E:\path\to\dsh-headroom\node_modules" -Target "$env:USERPROFILE\.dsh\profiles\node_modules"

配置（cordis patch） yaml
- id: headroom
name: 'dsh-headroom'
config:
baseUrl: 'http://127.0.0.1:8787'
timeoutMs: 20000
model: '' # /v1/compress 的可选模型提示 autoCompress: false # 上文所述的钩子开关 minChars: 12000 # 自动压缩阈值
excludeTools: [] # 永不自动压缩的工具名

License / 许可证 Apache-2.0 — 见 LICENSE。

集成了 chopratejas 的 headroomlabs-ai/headroom（Apache-2.0）。原始版权归各自作者所有；DeepSeek Harness 适配由 Asaka-RUM 完成。

集成了 chopratejas 的 headroomlabs-ai/headroom（Apache-2.0）。原始版权归各自作者所有；DeepSeek Harness 适配由 Asaka-RUM 完成。