前言¶
DeepSeek Harness (DSH) 采用插件化架构，旨在扩展 Web UI 的功能。Headroom 是一个压缩代理，用于减少 Token 消耗。本插件为 DSH Web UI 提供了一个实时的令牌和成本节省仪表盘。它将 Headroom 的统计信息集成到设置页面和聊天输入区，帮助开发者直观地监控压缩效果和成本。
功能概览¶
该插件主要包含以下能力：
- 设置仪表盘：位于 Settings → Headroom Stats。提供生命周期 KPI（节省的令牌、压缩/缓存的成本、请求数），当前会话卡片，缓存与压缩的成本分割条，以及 Top 10 项目表格。同时处理加载、错误和陈旧状态。
- Composer 统计行：在聊天输入框下方显示一行数据，格式为
Headroom: tokens saved · $ · %，刷新间隔为 5 秒。 - 动态路径检测：不使用硬编码路径，支持跨机器使用。探测顺序为
HEADROOM_SAVINGS_PATH→HEADROOM_WORKSPACE_DIR→%USERPROFILE%\.headroom。 - 5 秒实时刷新：使用单一共享轮询器从单个快照为设置页和统计行提供数据，避免重复读取文件。
- 主题感知：使用
--dsw-alias-*设计令牌，自动适配 DSH 的浅色/深色主题。 - 存活重启：作为真实配置文件捆绑插件，通过
dsh.bundle配置，随 DSH 启动自动加载，无需每次会话重新定义。
安装与启用¶
安装命令如下。该命令会将插件添加到指定 Web 配置文件中，并随配置文件持久化。
dsh plugin --profile web add git+https://github.com/Zenjibad/headroom-stats-plugin.git
安装后需要重启 DSH（或进行硬刷新）以加载插件。访问路径为 Settings → Headroom Stats。统计行会自动出现在聊天输入框下方。
工作原理与配置¶
- 数据源：插件仅读取 Headroom 代理生成的文件
~/.headroom/proxy_savings.，不进行任何写入操作。 - 路径解析：插件启动时根据环境变量探测 Headroom 数据文件位置。如果未配置环境变量，则默认查找用户目录下的
.headroom文件夹。 - 刷新机制：使用固定的 5 秒轮询间隔（
POLL_MS）从服务器拉取快照数据。 - 无配置文件：插件不包含配置文件，也不持久化用户设置。所有逻辑基于当前环境变量和文件状态运行。
注意事项¶
- 依赖运行环境：必须确保机器上运行着 Headroom 代理，且代理正在写入
proxy_savings.文件。 - 文件缺失处理：如果找不到
proxy_savings.文件，设置页面会显示“unavailable + error”提示，统计行则会隐藏。 - 仅读权限：出于安全考虑，插件仅具备读取 Headroom 数据文件的权限，不会修改磁盘文件或进行网络请求。
- 移除方法：若需卸载，可执行
dsh plugin --profile web rm headroom-stats-plugin并重启 DSH。
结语¶
该插件通过将 Headroom 的统计信息可视化，填补了 DSH 在压缩代理监控方面的空白。它不仅提供了详细的设置页仪表盘，还通过常驻统计行提供了即时的会话反馈，适合需要在开发过程中频繁关注 Token 和成本节省的开发者。
