headroom-stats-plugin
DeepSeek Harness (DSH) Web UI 中 Headroom 压缩代理的实时令牌/成本节省仪表盘：设置页仪表盘，以及输入区下方的常驻统计行。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:Zenjibad/headroom-stats-plugin#fe4406d0bb36d0be19490e5ce1ea7bb7e19878cdHeadroom Stats Plugin 以 headroom-stats-plugin 发布，当前版本为 1.0.1。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
Show real-time token/cost savings from the Headroom compression proxy inside the DeepSeek Harness (DSH) Web UI: a full dashboard in Settings plus a persistent stats line under the composer. 在 DSH 内实时展示 Headroom 压节省统计：设置页仪表盘 + 输入区常驻统计行。
中文文档: README.zh.md · LLM index: llms.txt · Agent guide: AGENTS.md
Keywords: dsh-plugin · deepseek-harness-plugin · headroom · token-savings · compression · tokens · cost · stats · dashboard
| Feature | Description |
|---|---|
| 📊 Settings dashboard | Settings → Headroom Stats: lifetime KPIs (tokens saved, compression $, cache $, requests), current-session card, cache-vs-compression split bar, top-10 projects table, loading/error/stale states |
| 🪧 Composer stats line | One line under the chat input: Headroom: 11.4M tokens saved · $26.23 · 11.2% this session, refreshed every 5s |
| 🧭 Dynamic path detection | No hardcoded paths — shareable across machines: probes HEADROOM_SAVINGS_PATH → HEADROOM_WORKSPACE_DIR → %USERPROFILE%\.headroom |
| ⚡ 5s live refresh | One shared poller feeds both seats from a single snapshot — no duplicate file reads |
| 🌗 Theme-aware | All colors use --dsw-alias-* design tokens; follows light/dark automatically |
| ♨️ Survives restarts | Real profile-bundled plugin: install once with dsh plugin add, auto-loads on every DSH boot — no per-session define, no cordis_define |
Headroom proxy ──writes──> ~/.headroom/proxy_savings.json (grows continuously)
│
Host half (DSH process) ▼
└─ one-time env probe: cmd /c echo %HEADROOM_SAVINGS_PATH%&echo %HEADROOM_WORKSPACE_DIR%&echo %USERPROFILE%
(DSH host sandbox exposes no direct env access; fetched via subprocess)
└─ fs service stat/readText → snake_case→camelCase reshape
└─ webServer route GET /headroom-stats/api → JSON snapshot
│
Client bundle (browser) ▼
└─ single 5s poller → fetch(/headroom-stats/api) → snapshot fan-out to two seats
├─ settings.section (id headroom-stats) → full dashboard
└─ conversation.composer.dock (id headroom-dock) → stats line
{ok:false,error}, UI shows unavailable, polling self-recovers.dsh.bundle (cordis.patch.yml) + dsh.client (exports["./client"], bundled) so it installs as a real profile plugin that the DSH client-modules scanner loads on every boot.dsh plugin add (persists across restarts)Install the package from this GitHub repo (or from npm once published):
# local directory (from the parent of this repo):
dsh plugin --profile web add ./headroom-stats-plugin
# or directly from GitHub (any DSH machine):
dsh plugin --profile web add git+https://github.com/Zenjibad/headroom-stats-plugin.git
dsh plugin add is a pnpm add into the profile plus a dsh.profile.bundles reconcile: seeing this package's dsh.bundle declaration, it appends headroom-stats-plugin to the bundle stack. Restart DSH (or hard-refresh). On boot the client-modules scanner resolves exports["./client"] and the settings page + dock line appear. No per-session define, survives restarts.
git clone https://github.com/Zenjibad/headroom-stats-plugin.git (any location).~/.dsh/profiles/web/package.json dependencies: "headroom-stats-plugin": "link:<repo-path>", then pnpm install in the profile dir.If a previous dynamic install of this plugin is running, stop it first (
cordis_stop) to avoid double-mounting the two settings seats.
~/.headroom/proxy_savings.json, or the file HEADROOM_SAVINGS_PATH points at).No config file, no persisted settings. The path is resolved dynamically from these env vars (probed once, cached):
| Variable | Role |
|---|---|
HEADROOM_SAVINGS_PATH | absolute path to proxy_savings.json (highest priority) |
HEADROOM_WORKSPACE_DIR | headroom workspace override (appended /proxy_savings.json) |
%USERPROFILE% | fallback: %USERPROFILE%\.headroom\proxy_savings.json |
Poll interval: 5s constant (POLL_MS in src/client/index.tsx).
Q: Settings page shows "Headroom stats unavailable"?
A: proxy_savings.json not found. Confirm the headroom proxy is running and the file exists; check the env-var paths.
Q: The composer stats line is missing? A: Deliberate — the line renders nothing when data is absent (no noise). It reappears ≤5s after data returns.
Q: Why do numbers differ from what I saw before?
A: proxy_savings.json grows continuously as the proxy compresses; stats are live values. The fixture in tests/fixtures/ is a point-in-time snapshot — staleness is by design.
Q: My old dynamic plugin is still showing two dashboards after installing this?
A: Stop/remove the dynamic one (cordis_stop / cordis_undefine) — it re-defines the same seats.
Q: How do I remove it?
A: dsh plugin --profile web rm headroom-stats-plugin (or delete the profile dependency + bundle entry) and restart DSH.
subprocess call is one-time and only echoes env vars).headroom-stats-plugin/
├── src/
│ ├── index.ts # host half: env probe, fs read, reshape, /headroom-stats/api route
│ └── client/index.tsx # client bundle: 5s poller, dashboard, dock line
├── cordis.patch.yml # dsh.bundle patch (inserts the plugin row on boot)
├── tsdown.config.ts # bundles host (node ESM) + client (CJS ModuleLoader)
├── package.json # name, exports["./client"], dsh.client + dsh.bundle
├── lib/ # build output (index.js, client.js)
├── tests/fixtures/ # real-shape snapshot of proxy_savings.json
├── AGENTS.md # repository guide for AI agents
├── llms.txt / llms-full.txt
├── README.md / README.zh.md
└── LICENSE
proxy_savings.json data source.