dsh-usage-stats

One-Line Description

Complements DeepSeek Harness web UI with multi-vendor account balances, subscription/Token Plan quota windows, and daily token usage and cache hit rates aggregated by provider/model—all consolidated in a floating panel at the bottom of the sidebar. Regular users in dsh web can immediately see how many tokens they've burned today and how long their account will last, without switching to each vendor's own console.

Core Features

• New "Usage/Balance" entry in sidebar bottom: Opens a floating panel showing only the currently selected provider, with a manual refresh button in the title bar (simultaneously refreshes tokens, provider list, and current account)
• Daily Token usage statistics: Today, this month, cumulative, cache hit rate, drill-down by date/provider/model; same model from different providers are grouped separately (e.g., deepseek-official · deepseek-chat vs ark · deepseek-chat)
• Code-like blue calendar heatmap: Cells mapped continuously using square root of monthly max (zero is neutral gray "empty"), clicking a date expands provider/model details with hit rate bars
• Multi-vendor balance unified cards: DeepSeek, OpenRouter, Moonshot, Z.ai, New API, Sub2API, Passion, general balance template, colored by remaining ratio "normal/warning/critical" (default 30%/10% thresholds)
• Subscription / Token Plan quota windows: OpenCode Go rolling usage, Z.ai Coding Plan (China region bigmodel-cn supported), Kimi For Coding, MiniMax Coding Plan (cn region supported), each showing remaining ratio and reset time
• Backend automatic monitoring: Server refreshes once on startup, then every 5 minutes refreshes all configured accounts and local token aggregation; browser only requests current provider, refresh frequency independent of panel open state

Technical Implementation

• Language: JavaScript (ESM; 5 .js files under lib/, client bundle single file 1464 lines hand-written, no build step)
• Key Dependencies: Pure Node.js built-ins—node:fs/promises (atomic cache writes), node:http/node:https/node:dns/node:net (upstream requests + DNS resolution + IP filtering), node:path/node:os (DSH_HOME resolution). Client uses host bundle's React 18 and @deepseek-ai/dsh-client-ui-primitives
• Architecture Pattern: dual-half host plugin. cordis.patch.yml inserts 1 line Loader in web profile (id: usage-stats, name: dsh-usage-stats); package.json#dsh.bundle.patch points to patch; server apply(ctx, rawConfig) registers 5 exact GET routes and starts 5-minute timer; client injects sidebar.footer.action slot via __ModuleLoader__, uses React.createPortal to mount floating layer to document.body avoiding sidebar theme variable leakage
• Entry Files: Server lib/index.js (apply / name = "usage-stats" / Config = { ~standard: ... }); client lib/client.js; account adapter lib/accounts.js; token aggregation lib/usage.js; balance schemes lib/balance.js; subscription windows lib/subscriptions.js

Use Cases

DSH users who want to centralize "how much money left / how much quota / how many tokens burned today" across multiple LLM vendors, especially developers using DeepSeek official + several Coding Plans + self-hosted New API/Sub2API proxies. This plugin doesn't display models or conversation history—it only adds an independent floating panel to the existing sidebar, zero workflow intrusion.

Prerequisites & Compatibility

Installation

dsh plugin --profile web add github:Ychris12138/dsh-usage-stats

Or via npx compatible install: npx --yes github:Ychris12138/dsh-usage-stats, supports --dry-run / --check / --no-enable. After install or update, must restart running dsh web and hard-refresh browser to load new client bundle.

Configuration Options

Plugin works out of the box—no config needed to see Token usage heatmap in sidebar; all fields below are optional, only needed when you want the panel to show a specific provider's balance/Token Plan. Write config under config.monitors of existing name: dsh-usage-stats entry in ~/.dsh/profiles/web/cordis.patch.yml (don't create a second plugin entry, otherwise will mount twice).

FAQ

Q: Don't see "Usage/Balance" entry in sidebar after install. What to do?

A: After installing or updating plugin, must restart running dsh web and hard-refresh browser (Ctrl/Cmd+Shift+R). Plugin's server routes and client bundle are both mounted when dsh web starts; only refreshing browser won't reload. Installer writes one line - insert: id: usage-stats, name: dsh-usage-stats to cordis.patch.yml, repeated runs are idempotent, won't append duplicates.

Q: Works without configuring Keys? What can I see?

A: Token usage heatmap and cache hit rate work completely without any credentials, automatically aggregating all session event streams. Providers without public balance endpoints show "Not Supported" in account cards—plugin won't guess; providers missing Keys show "Unconfigured". OpenRouter is the exception: official account credits must use separate OPENROUTER_MANAGEMENT_KEY, plugin won't try inference OPENROUTER_API_KEY against /api/v1/key.

Q: Where is data stored? Does it upload?

A: Server aggregation cache only saves token counts folded by provider/model, session IDs, opaque revisions and fold cursors, written to $DSH_HOME/storages/usage-stats-cache.json using temp file + atomic rename. API Keys, OpenCode auth.json, Cookies, admin PATs and raw upstream responses never enter browser response, plugin cache or logs. The validate:live script compares plugin endpoint vs official token projection per session, returns non-zero exit code on mismatch—but script may output real balance, don't paste output to public issue.

Q: Can I connect my own private vendor?

A: Yes, using declarative adapter: set mode: balance or mode: subscription, request.path (HTTPS same-origin relative path), request.auth.type (bearer/raw/x-api-key), extract.* JSON Pointer fields. Only restricted GET + JSON Pointer execution, no JavaScript. Credentials can only be injected via reference; usageBaseURL doesn't allow embedded username/password; sensitive headers (Authorization/X-API-Key/API-Key/Cookie etc.) must be rejected by plugin if directly overridden in request.headers. Before sending credentials, plugin filters domain's IPv4/IPv6 resolution results to a single allowed connection address, prioritizing public IPs.

Q: OpenCode Go quota suddenly unavailable / interface returns 401. What to do?

A: OpenCode Go's Bearer usage endpoint (opencode.ai/zen/go/v1/usage) is not an official public API; upstream may change structure anytime; panel shows specific error when interface changes. Can explicitly set credentialRef: OPENCODE_GO_API_KEY under monitors.opencode-go, or fall back to OPENCODE_GO_AUTH_COOKIE + OPENCODE_GO_WORKSPACE_ID cookie-compatible solution (plugin prioritizes Harness credential, then reads ~/.local/share/opencode/auth.json, finally uses cookie). To disable, simply delete corresponding monitor from Cordis entry.

Q: Can reverse proxy expose these five endpoints to public network?

A: Not recommended. The five endpoints (/api/usage-stats/{usage,providers,balance,subscriptions,account}) only verify peer socket is loopback + Host header, no identity authentication; if behind reverse proxy, plugin sees proxy's own loopback address as peer, equivalent to bypassing security boundary. README and SECURITY.md both explicitly state "do not expose endpoints via reverse proxy to LAN or public networks; if proxying is necessary, must add reliable authentication and access control at proxy layer". Security issues please report privately per SECURITY.md.

Q: How to uninstall?

A: Just run dsh plugin --profile web remove dsh-usage-stats and restart dsh web. Cache file $DSH_HOME/storages/usage-stats-cache.json left on disk, manually delete if needed; cordis patch written by installer also cleaned up. Installer won't touch ~/.dsh/.credentials.yaml.

Getting Started

Beginner—one dsh plugin --profile web add + restart dsh web shows "Usage/Balance" entry in sidebar, token usage stats automatically available. Advanced part is reading README's monitors.<providerId> YAML config examples, configuring corresponding adapter and credential reference for OpenRouter, OpenCode Go, various Coding Plans and self-hosted proxies (New API / Sub2API / Passion / declarative).

Known Issues & Limitations

• OpenCode Go's Bearer usage endpoint (opencode.ai/zen/go/v1/usage) is non-official public API: when upstream changes structure, quota panel shows error; can use OPENCODE_GO_AUTH_COOKIE + OPENCODE_GO_WORKSPACE_ID cookie fallback, or directly delete monitor to disable
• DSH client sidebar layout is ROW arrangement: this plugin as second footer action triggers host layout to push subsequent items out of visible area—plugin works around by temporarily switching host container to column layout (see flexDirection toggle effect in client.js, issue #21 recorded)
• Some third-party Coding Plans have balance only: Kimi Code 5 hours/week window, Z.ai partial interfaces need adapter updates when upstream structure changes; Anthropic OAuth, OpenAI Codex, Gemini Code Assist, GitHub Copilot Personal have no API-keyable usage endpoint yet
• DSH restarts with compressed summary to restore active sessions: when plugin detects in-memory event cursor below fold cursor, it re-folds entire session statistics (issue #23 recorded), usage numbers briefly "rollback" then catch up after restart
• Account cards portal to document.body within panel container: avoids sidebar theme variable leaking into floating layer (issue #17 recorded), but therefore visually completely independent from sidebar
• Custom monitor defaults require HTTPS + same-origin relative path + manual redirect + JSON + 1 MiB limit: allowInsecure must be explicitly enabled to use HTTP; 198.18.0.0/15 range only accepted as Clash/Mihomo-style fake-IP synthesis address (HTTPS only), literal IPs and other private addresses rejected by default, prevents DNS rebinding bypass
• Must restart dsh web after install/update: server exact routes, 5-minute timer and client bundle all mount when dsh web starts, browser refresh alone won't reload
• dsh plugin and npx are two independent install paths: don't keep both manual cordis entry and bundle registration, otherwise will mount twice; installer checks YAML root node is not empty [] before writing, residual [] from historical versions auto-cleaned

为 DeepSeek Harness 网页端提供多供应商账户监测与 Token 用量分析。

Provider balances, subscription quotas, and token-usage analytics for the DeepSeek Harness Web GUI (dsh web).

展示图使用脱敏演示数据；插件不会把 API Key、Cookie、管理 PAT 或上游原始响应发送到浏览器。

一眼看懂 / At a glance

界面支持中文和英文。浏览器只请求当前选择的 provider；后台刷新与面板是否打开无关。手动刷新会更新用量、供应商列表，并强制刷新当前账户，不会批量强制请求其他供应商。

快速安装 / Quick start

需要 DeepSeek Harness web profile（@deepseek-ai/dsh >= 0.1.0-rc.6）。

dsh plugin --profile web add "github:Ychris12138/dsh-usage-stats"

然后重启已经运行的 dsh web，并在浏览器中硬刷新。侧边栏底部会出现“用量/余额”（Usage/Balance）入口。

插件市场 GUI 安装（DSH Community Market，Path A 标准来源）

本仓库按 DSH Community Market 目录 adapter 指南 的标准来源（Path A） 接入，无需修改 Market 代码。内置两份目录数据：

• catalog/catalog-source.json — 来源 manifest（catalog-source.schema.json v1.0.0）
• catalog/v1/plugins.json — 标准 provider page（catalog-provider-page.schema.json v1.0.0）

使用前提（重要）：市场托管安装只接受 npm registry 的精确稳定版本，git 条目仅可浏览。dsh-usage-stats 这个 npm 名已被其他项目占用，因此目录条目身份使用 @ychris12138/dsh-usage-stats（当前可用）。要启用 GUI「安装」按钮，需先发布：

1. 仓库包身份已统一为 @ychris12138/dsh-usage-stats；每次发版需同步 package.json / package-lock.json / catalog/v1/plugins.json 的版本。
2. 发布 scoped 公共包：npm publish --access public。
3. 把 catalog/v1/plugins.json 内容发布到 https://ychris12138.github.io/dsh-usage-stats/v1/plugins（GitHub Pages，manifest 与 endpoint 必须同源、HTTPS 443、无凭据）。
4. 在 DSH 插件市场 → 来源管理 → 添加来源，粘贴 manifest URL：https://ychris12138.github.io/dsh-usage-stats/catalog-source.json，选择后即可走「可恢复安装边界」GUI 安装。

若最终包名不同，请同步修改 catalog-source.json 的 providerId/transport.endpoint 与 catalog/v1/plugins.json 的身份字段。发布前目录条目可浏览但安装保持禁用（fail-closed，属预期）。

升级或卸载：

dsh plugin --profile web update "@ychris12138/dsh-usage-stats"
dsh plugin --profile web remove "@ychris12138/dsh-usage-stats"

npx --yes github:Ychris12138/dsh-usage-stats

# 预览，不修改文件
npx --yes github:Ychris12138/dsh-usage-stats --dry-run

# 检查现有安装
npx --yes github:Ychris12138/dsh-usage-stats --check

# 安装但不修改 Cordis patch
npx --yes github:Ychris12138/dsh-usage-stats --no-enable

支持的账户类型 / Providers

插件自动发现官方 DeepSeek 路由和 llm-pi-ai 中的 provider profile。只有存在公开账户接口或显式 monitor 的供应商才会查询远端账户；Token 用量统计不需要额外凭据。

没有公开账户接口的供应商仍会正常统计 Token；账户卡片会明确显示“不支持”，不会猜测余额。

凭据与供应商配置 / Configuration

凭据由 Harness 从 ~/.dsh/.credentials.yaml 解析。安装器不会读取、创建或修改该文件。不要把真实 Key、Cookie 或管理令牌提交到 Git、公开 issue，或粘贴给编码 Agent。

余额型供应商

DeepSeek、Moonshot 等默认复用对应 provider profile 的 apiKeyEnv。例如：

# ~/.dsh/.credentials.yaml
DEEPSEEK_API_KEY: sk-your-key-here

OpenRouter 是明确的例外：官方账户 credits 接口要求 Management Key，不能复用普通推理 OPENROUTER_API_KEY。插件默认读取独立引用；未配置时显示“未配置”，不会拿推理 Key 试探：

# ~/.dsh/.credentials.yaml
OPENROUTER_MANAGEMENT_KEY: sk-or-v1-your-management-key

插件按 total_credits - total_usage 显示 OpenRouter 余额，并同时展示累计已用和总 credits。普通 Key 的 /api/v1/key 只描述单个 Key 的 spending limit，不会被当作账户余额。自定义引用可在 monitors.openrouter 中设置 adapter: openrouter-balance 与 credentialRef。

Token Plan 供应商

# ~/.dsh/.credentials.yaml
OPENCODE_GO_API_KEY: sk-opencode-your-key
ZAI_API_KEY: your-zai-key
# 中国区 Z.ai 用户可选；默认 global
ZAI_API_REGION: bigmodel-cn
KIMI_API_KEY: your-kimi-key
MINIMAX_API_KEY: your-minimax-key
# 中国区 MiniMax 用户可选；默认 global
MINIMAX_API_REGION: cn

OpenCode Go 依次尝试 Harness credential、~/.local/share/opencode/auth.json，最后才使用显式 OPENCODE_GO_AUTH_COOKIE + OPENCODE_GO_WORKSPACE_ID 兼容回退。Bearer usage endpoint 目前不是公开 API，可能随上游变化；Cookie 等同登录凭据，不应进入日志或 issue。

Z.ai 全球区使用 api.z.ai，中国区使用 open.bigmodel.cn。MiniMax 优先使用官方 www.minimax.io / www.minimaxi.com Token Plan 地址，并解析 5 小时与周窗口的剩余比例和重置时间。

New API、Sub2API 与自定义 monitor

在现有 name: "@ychris12138/dsh-usage-stats" Cordis entry 下合并 config，不要追加第二个插件 entry。monitor 键必须是 Harness 中真实存在的 provider id；未知 provider、adapter 或非法映射会在路由和 timer 注册前阻止插件启动。例外：monitor 同时显式提供 usageBaseURL 与 credentialRef 时视为自包含，会在 provider 注册可见前临时物化为 provider（适用于 Harness 设置页里后加载的 provider），此时不要求该 provider 已出现在注册表中。

# ~/.dsh/profiles/web/cordis.patch.yml
- insert:
    - id: usage-stats
      name: "@ychris12138/dsh-usage-stats"
      config:
        monitors:
          relay-a:                 # Harness provider id
            adapter: new-api
            # 仅旧实例的 /api/user/self 回退需要：
            fallbackCredentialRef: RELAY_A_MANAGEMENT_PAT

        monitors:
          relay-a:
            adapter: general
            warning:
              warnBelow: 5
              criticalBelow: 1

        monitors:
          relay-a:
            adapter: sub2api
            warning:
              warnBelow: 5
              criticalBelow: 1

        monitors:
          relay-b:
            adapter: sub2api-auth

# 只要这些（不需要单独的 SUB2API_* 凭据）
# DSH 模型页里为 Sub2API 面板配置 provider，baseURL 指向面板，API Key 填可用的密钥

        monitors:
          private-model:
            adapter: declarative
            mode: balance
            request:
              path: /account/balance
              auth:
                type: bearer
                credentialRef: PRIVATE_MODEL_API_KEY
            extract:
              root: /data
              remaining: /available_balance
              used: /used_balance
              total: /total_balance
              currency: /currency

支持的 adapter：deepseek-balance、openrouter-balance、moonshot-balance、zai-balance、new-api、sub2api、sub2api-auth、general、opencode-go、zai-token-plan、kimi-token-plan、minimax-token-plan、declarative。

warning.warnBelow 与 warning.criticalBelow 是余额绝对值阈值。具有总额度的余额和 Token Plan 会自动产生 normal / warning / critical 剩余比例状态（默认 30% / 10%）。

使用 / Usage

1. 点击侧边栏“用量/余额”。
2. 用“当前供应商”切换账户卡片；一次只显示一个 provider。
3. 使用 ‹ / › 切换月份，点击热图日期查看当天的 provider/model 明细。
4. 标题栏刷新会更新 Token、provider 列表，并强制刷新当前账户。

“最近 14 天”按本地日历计算，只显示窗口内存在用量的日期；未来时间戳不会计入。同一模型来自不同 provider 时会分别统计，例如 deepseek-official · deepseek-chat 与 ark · deepseek-chat。

Agent 友好安装 / Agent-friendly installation

Install or update dsh-usage-stats from:
https://github.com/Ychris12138/dsh-usage-stats

Constraints:
- Resolve DSH_HOME from the environment; otherwise use ~/.dsh.
- Do not read, print, edit, or request .credentials.yaml, auth.json, cookies, or any API key.
- Do not expose the plugin through a reverse proxy.
- Do not restart or terminate an existing dsh process without asking me.

Procedure:
1. Confirm node, npx, and dsh are available.
2. Prefer `dsh plugin --profile web update "@ychris12138/dsh-usage-stats"` when already installed; otherwise use `dsh plugin --profile web add "github:Ychris12138/dsh-usage-stats"`.
3. If unavailable, use: npx --yes github:Ychris12138/dsh-usage-stats
4. Do not combine bundle installation with an existing manual dsh-usage-stats Cordis entry.
5. For npx, require a verified package and exactly one Cordis entry, then run again with --check.
6. Report the installation path and resolved profile paths.
7. If dsh web is running, report that a restart is needed and stop.

Optional account setup (never handle secret values yourself):
- OpenRouter account balance requires OPENROUTER_MANAGEMENT_KEY, not the inference key.
- OpenCode Go may reuse local auth.json or use OPENCODE_GO_API_KEY.
- Z.ai uses ZAI_API_KEY; China accounts may set ZAI_API_REGION=bigmodel-cn.
- Kimi and MiniMax use KIMI_API_KEY and MINIMAX_API_KEY.
- Never ask me to paste a key or browser cookie into chat.

Optional monitor setup:
- Read configured Harness provider ids and ask which id should receive a monitor.
- Add only non-secret config under the existing dsh-usage-stats Cordis entry.
- Store credential reference names, never credential values.
- Validate relative request.path and JSON Pointer fields beginning with /.
- Do not enable cross-origin, insecure HTTP, or private-network access unless I explicitly request it.

npx --yes github:Ychris12138/dsh-usage-stats --check

隐私与安全 / Privacy & security

• API Key、OpenCode auth.json、Cookie 与管理 PAT 不会进入浏览器响应、插件缓存或日志。
• Sub2API sub2api-auth 复用 provider 自己的推理 API Key（模型页已配置的那个），不会再引入或落盘额外的面板凭据。
• 自定义 monitor 默认要求 HTTPS、同源相对路径、手动 redirect 和 JSON 响应，body 上限为 1 MiB。
• 发凭据前会筛选域名的 IPv4/IPv6 解析结果并固定一个允许的连接地址，优先使用公网地址；HTTPS 域名解析到 198.18.0.0/15 时可作为 Clash/Mihomo 等代理的 synthetic fake-IP 使用。字面量 198.18/15、其他私网/特殊地址仍默认拒绝，防止 DNS rebinding 绕过私网限制。
• usageBaseURL 禁止内嵌 username/password；Authorization、X-API-Key、API-Key 等 header 必须由 credential ref 注入。
• 五个端点仅接受 GET，并同时校验 peer socket 与 Host；支持 IPv4、IPv4-mapped IPv6 和 [::1]:port。
• 用量缓存 ~/.dsh/storages/usage-stats-cache.json 只保存聚合 Token、会话 id、不透明 revision 与折叠游标，不保存提示词、回复或文件路径。

本机反向代理会让插件看到代理自身的回环地址。请勿把端点经反向代理暴露到局域网或公网；确需代理时必须在代理层增加可靠认证与访问控制。安全问题请按 SECURITY.md 私下报告。

正确性与数据口径 / Correctness

统计值来自 assistant/chunk 或 assistant/message 中 provider-reported usage，不是本地估算。相同 turn/step 的后续样本会替换旧样本，并按 provider/model 归集。

• 活跃会话只处理新追加事件。
• 持久化会话使用不透明 revision；未变化时不重复读取日志。
• seq 缺口、日志重写或 live/persisted 切换时完整重折叠该会话。
• 聚合采用 single-flight，并在同一临界区原子保存缓存。
• validate:live 会逐会话比较 raw artifact、session.history、插件端点与官方 token projection；缺文件或不一致会返回非零。

API

非 GET 返回 405，非回环请求返回 403；所有响应均为 JSON 并带 Cache-Control: no-cache。

开发与验证 / Development

npm install
npm run check
npm test
npm pack --dry-run

npm test 完全离线，覆盖 bundle、客户端渲染与请求竞态、服务端安全边界、余额/Token Plan adapter、缓存和安装器幂等性。真实数据验证需先运行 dsh web：

npm run validate:live
node scripts/check-balance.mjs

所有服务端脚本均遵循 DSH_HOME。check-balance.mjs 可能显示真实余额，不要把输出粘贴到公开 issue。

兼容性与致谢 / Compatibility & credits

当前版本为 0.2.0。插件依赖 Harness 客户端模块加载器、Cordis 服务与 session persistence；Harness 预发布接口变化时可能需要同步适配。

• Javis603/token-monitor：参考多 provider 配额归一化与 Z.ai 限额解析。
• xiaoqi20/dsh-opencode-go-usage：参考 DSH 凭据接入、OpenCode auth.json 回退与 Bearer usage endpoint。

本项目重新实现统一 account protocol、adapter 与单供应商 UI，不复制参考项目界面。

License

MIT