dsh-headroom DSH 插件

本插件自动为 DeepSeek Harness 配置 Headroom 压缩代理。它检测 Python、创建虚拟环境、安装 headroom-ai[proxy] 包，并管理代理进程。设置页提供一键切换启用或禁用压缩线路，以及实时显示节省的 token 和缓存命中率。

developer-tools

如何安装 dsh-headroom DSH 插件

dsh plugin add file:../dsh-headroom  # 或本地路径

复制不会执行命令。安装 dsh-headroom DSH 插件前请核对仓库和版本。

dsh-headroom DSH 插件数据来源

dsh-headroom DSH 插件快照日期：2026年8月16日

discovered

dsh-headroom DSH 插件能做什么

一键启用压缩线路：在设置页点击按钮，将 DSH 的 llm-deepseek.baseURL 指向本地 Headroom 代理。
自动环境管理：检测 Python → 创建 venv → 安装 headroom-ai[proxy]（轻量，无 torch）。
进程守护：自动启动 Headroom 代理，/livez 健康检查，崩溃提示。
兼容预设：固化 Windows 变通方案（HEADROOM_DETECT_BACKEND=python、HEADROOM_TOOL_SEARCH=off）和 DeepSeek 双协议路由。
一键切回直连：随时可切回 api.deepseek.com，无锁死风险。
实时统计：设置页显示花费/节省 token、缓存命中率（每 10 秒刷新）。

dsh-headroom DSH 插件适合哪些场景

减少工具 schema 描述中的冗余 token（每次请求节省 4-71 token）。
在大上下文 coding 会话中压缩跨轮重复内容，尤其在工具输出较大时。
利用 DeepSeek 前缀缓存（99.9% 命中率）不破坏缓存前缀，降低输入成本。
偶遇大工具输出触发去重时，可节省 8-20% token。

dsh-headroom DSH 插件适合谁

希望最小化每次请求 token 使用量和费用的 DeepSeek Harness 用户。
使用大上下文会话（如 1M token）且需要额外压缩的开发人员（DSH 自带压缩之外）。

dsh-headroom DSH 插件的限制

需要 Python 3.10+（Windows 限定 3.10-3.13）。
首次启用压缩线路后，首次对话可能需要等待约 1 分钟（Headroom tokenizer/模型冷启动）。
实际节省 token 效果因场景差异很大；在大上下文编码会话中，多数请求节省约 0.001%（工具 schema 已压缩、历史走缓存）。
不压缩会话历史（compaction-basic）或修剪工具结果（tool-result-pruner）——这些由 DSH 自身机制处理。
依赖外部 Headroom 项目（Apache 2.0）及其持续维护。

dsh-headroom DSH 插件的仓库 README 摘录

以下文字摘自 dsh-headroom DSH 插件的上游仓库 wjxn13/dsh-headroom 的 README，版权归原作者，仅作引用。

DeepSeek Harness 的 Headroom 上下文压缩代理集成插件：一键检测、安装、启动 [Headroom](https://github.com/headroomlabs-ai/headroom) 压缩代理，并自动接入 DeepSeek 线路（OpenAI 协议），在设置页提供状态面板与切换控件。 > **重要声明**：本插件是 [headroomlabs-ai/headroom](https://github.com/headroomlabs-ai/headroom) > （Apache License 2.0）的**集成与封装**，Headroom 压缩引擎本身由 Headroom 项目提供， > 版权归其作者所有。本插件不包含、也不修改 Headroom 的压缩算法，仅负责： > 环境检测、依赖安装、进程管理、DeepSeek 兼容预设与线路切换 UI。 > 详见 [NOTICE](./NOTICE) 与 [LICENSE](./LICENSE)。 ## 功能 - **一键启用压缩线路**：设置页点按钮，把 DSH 的 `llm-deepseek.baseURL` 指向本地 Headroom 代理 - **自动环境管理**：检测 Python → 自动建 venv → 安装 `headroom-ai[proxy]`（轻量，无 torch） - **进程守护**：自动启动 headroom proxy、`/livez` 健康检查、崩溃提示 - **兼容预设**：固化 Windows workaround（`HEADROOM_DETECT_BACKEND=python`、 `HEADROOM_TOOL_SEARCH=off`）与 DeepSeek 双协议路由 - **一键切回直连**：任何时刻可切回 `api.deepseek.com`，无锁死风险 - **实时统计**：设置页显示花费/节省 token、缓存命中率（每 10 秒刷新） ## 实测成果 > 以下数据来自本机真实使用（DeepSeek V4-Flash，DSH 大上下文会话），2026-08-15 统计： | 指标 | 实测值 | 说明 | |---|---|---| | 累计压缩节省 | **1,256,265 token** | Headroom 累计压缩掉的 token（跨 1,533 次请求） | | 累计输入 | 413M token | 压缩后实际发送量 | | 缓存命中率 | **99.9%** | 前缀缓存命中（DeepSeek 官方机制，Headroom 不破坏它） | | 单请求典型节省 | 4-71 token / 请求 | 工具 schema 压缩为主（大上下文会话） | ### 能省多少？（诚实预期） Headroom 官方宣称可省

阅读完整 README仓库许可: Apache-2.0

dsh-headroom DSH 插件常见问题

如何安装 dsh-headroom？

克隆仓库，然后在 DSH 配置文件目录下运行 `dsh plugin add file:../dsh-headroom`。接着在 `cordis.patch.yml` 中添加插件条目，重启 DSH。详细步骤见 README。

支持 Windows 吗？

支持。Headroom 0.35.0 起为 Windows 提供了预编译 wheel（Python 3.10-3.13），无需 Rust 或 MSVC 工具链。插件还内置了 Windows 环境检测的变通方案。

使用这个插件能节省多少 token？

节省量因场景而异。对于 JSON/结构化数据，可节省 60-95%。对于大上下文编码会话，多数请求节省很小（约 0.001%），因为工具 schema 已压缩、历史走缓存。但大工具输出可能触发偶尔的 8-20% 节省。真正的价值在于它不破坏 DeepSeek 的前缀缓存（99.9% 命中率），从而降低输入成本。

这个插件和 DSH 自带的压缩有什么区别？

DSH 内置压缩处理会话级别：摘要旧对话（compaction-basic）和超预算时修剪工具结果（tool-result-pruner）。本插件专注于请求级别压缩：减少工具 schema 冗余和跨轮去重。两者互补，不重叠。

如何卸载 dsh-headroom？

运行 `dsh plugin remove dsh-headroom` 并从 `cordis.patch.yml` 中移除条目。如需删除 Headroom 引擎，手动删除插件目录下的 venv 文件夹。卸载后不会影响 DSH 配置。