headroom-stats-plugin

在 DeepSeek Harness (DSH) Web UI 内实时展示 Headroom 压缩代理的压节省统计：设置页完整仪表盘 + 输入区常驻统计行。

English: README.md · LLM 索引: llms.txt · Agent 指南: AGENTS.md

关键词 / Keywords: dsh-plugin · deepseek-harness-plugin · headroom · token-savings · compression · 压缩 · 节省 · tokens · cost · 成本 · stats · 统计 · dashboard

---

📑 目录

• ✨ 特性
• 🏗️ 工作原理
• 🚀 快速开始
• ⚙️ 配置
• ❓ 常见问题
• ⚠️ 安全须知
• 📦 项目结构
• 🙏 致谢

---

✨ 特性

特性	说明
📊 设置页仪表盘	设置 → Headroom Stats：终身 KPI（节省 tokens、压缩 $、缓存 $、请求数）、当前会话卡片、缓存 vs 压缩占比条、Top-10 项目表格、加载/错误/过期状态
🪧 输入区常驻统计行	聊天输入框下方一行：Headroom: 11.4M tokens saved · $26.23 · 11.2% this session，随 5s 轮询实时更新
🧭 动态路径检测	无硬编码路径，可跨机器分享：按 HEADROOM_SAVINGS_PATH → HEADROOM_WORKSPACE_DIR → %USERPROFILE%\.headroom 顺序探测
⚡ 5s 实时刷新	单一共享轮询器，双席位共用一份快照，不重复读文件
🌗 主题自适应	全部颜色走 --dsw-alias-* 设计令牌，亮/暗色自动跟随
♨️ 重启常驻	真实 profile 打包插件：dsh plugin add 安装一次，每次 DSH 启动自动加载 —— 无需 cordis_define、无需每次重装

🏗️ 工作原理

Headroom 压缩代理 ──写入──> ~/.headroom/proxy_savings.json (持续增长)
                                   │
Host 半区（DSH 进程内）            ▼
  └─ 一次性 env 探测: cmd /c echo %HEADROOM_SAVINGS_PATH%&echo %HEADROOM_WORKSPACE_DIR%&echo %USERPROFILE%
       （DSH 宿主沙箱无直接 env 访问，经 subprocess 服务取；未展开的 %VAR% 视为空）
  └─ fs 服务 stat/readText → snake_case→camelCase 重塑
  └─ webServer 路由 GET /headroom-stats/api → JSON 快照
                                   │
Client 半区（浏览器）              ▼
  └─ 单一 5s 轮询 fetch(/headroom-stats/api) → 快照分发到两个席位
       ├─ settings.section (id headroom-stats)  → 完整仪表盘
       └─ conversation.composer.dock (id headroom-dock) → 常驻统计行

• 纯拉取模型：无推送、无事件、无文件监听；文件缺失/解析失败 → {ok:false,error}，UI 显示不可用态，轮询自动恢复。
• 只读：插件从不写入 headroom 目录，只读 proxy_savings.json。
• 持久化：随包声明 dsh.bundle（cordis.patch.yml）+ dsh.client（exports["./client"] 打包产物），作为真实 profile 插件安装，DSH client-modules 每次启动都会扫描加载。

🚀 快速开始

标准安装：dsh plugin add（重启常驻）

从本仓库（或发布到 npm 后）安装：

# 本地目录（在本仓库父目录执行）：
dsh plugin --profile web add ./headroom-stats-plugin

# 或直接从 GitHub（任意 DSH 机器）：
dsh plugin --profile web add git+https://github.com/Zenjibad/headroom-stats-plugin.git

dsh plugin add = 向 profile 做 pnpm add + dsh.profile.bundles 协调：识别到本包的 dsh.bundle 声明后，把 headroom-stats-plugin 追加进 bundle 栈。重启 DSH（或硬刷新页面）。启动时 client-modules 扫描器解析 exports["./client"]，设置页 + 统计行出现。无需 cordis_define，重启后依旧。

手动挂载（备选）

1. git clone https://github.com/Zenjibad/headroom-stats-plugin.git（任意位置）。
2. 在 ~/.dsh/profiles/web/package.json 的 dependencies 加 "headroom-stats-plugin": "link:<仓库路径>"，然后在 profile 目录 pnpm install。
3. 重启 DSH。

若之前有动态安装版本在运行，先 cordis_stop 停掉，避免两个设置页席位重复挂载。

使用前提

• 本机运行着 Headroom 压缩代理（写入 ~/.headroom/proxy_savings.json，或 HEADROOM_SAVINGS_PATH 指向的文件）。
• 文件不存在时：设置页显示「不可用 + 错误信息」，统计行隐藏 —— 不报错不崩溃。

⚙️ 配置

无配置文件、无持久化设置。路径由以下环境变量动态决定（探测一次并缓存）：

变量	作用
HEADROOM_SAVINGS_PATH	直接指定 proxy_savings.json 绝对路径（最高优先级）
HEADROOM_WORKSPACE_DIR	headroom 工作目录覆盖（拼接 /proxy_savings.json）
%USERPROFILE%	兜底：<USERPROFILE>\.headroom\proxy_savings.json

轮询间隔固定 5s（src/client/index.tsx 中的 POLL_MS）。

❓ 常见问题

Q: 设置页显示「Headroom stats unavailable」？ A: 找不到 proxy_savings.json。确认 headroom 代理在运行、文件存在；检查环境变量路径是否正确。

Q: 输入区统计行不显示？ A: 数据缺失时该行有意渲染为空（不产生噪音）。数据恢复后 ≤5s 自动出现。

Q: 数字为什么和我上次看的不一样？ A: proxy_savings.json 随代理压缩持续增长，统计是实时值；tests/fixtures/ 里的样例是时间点快照，会过时属正常。

Q: 装了新版本后出现两个仪表盘？ A: 停掉旧的动态版本（cordis_stop / cordis_undefine）——它注册的是同一批席位。

Q: 如何彻底移除？ A: dsh plugin --profile web rm headroom-stats-plugin（或删除 profile 依赖与 bundle 条目）后重启 DSH。

⚠️ 安全须知

• 插件只读 headroom 数据文件，不写任何内容，无网络请求（subprocess 仅用于读环境变量，一次）。
• 路径检测尊重 headroom 官方环境变量，不会猜测或扫描全盘。
• 展示的金额为 headroom 按模型单价估算的「成本避免」值，非真实账单。

📦 项目结构

headroom-stats-plugin/
├── src/
│   ├── index.ts            # host 半区：env 探测、fs 读取、重塑、/headroom-stats/api 路由
│   └── client/index.tsx    # client 包：5s 轮询、仪表盘、统计行
├── cordis.patch.yml        # dsh.bundle patch（启动时插入插件行）
├── tsdown.config.ts        # 打包 host（node ESM）+ client（CJS ModuleLoader）
├── package.json            # name、exports["./client"]、dsh.client + dsh.bundle
├── lib/                    # 构建产物（index.js、client.js）
├── tests/fixtures/         # proxy_savings.json 真实结构快照
├── AGENTS.md               # AI agent 仓库指南
├── llms.txt / llms-full.txt
├── README.md / README.zh.md
└── LICENSE

🙏 致谢

• Headroom — 压缩代理与 proxy_savings.json 数据源。
• DeepSeek Harness — DSH 插件/动态运行时、Slots、主题、webServer、client-modules。
• DSH-better-sidebar — 打包式 client 插件构建模式的参考。

📄 License

MIT