dsh-usage-stats

Multi-provider account monitoring and token usage analytics for the DeepSeek Harness Web GUI.

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

The preview image uses sanitized demo data; the plugin never sends API keys, cookies, admin PATs, or raw upstream responses to the browser.

🐋 OrcaRouter sponsors this project and is available as an optional OpenAI-compatible provider. Learn more · Referral link.

At a Glance

Interface supports Chinese and English. Browser only requests the selected provider; auto-refresh is server-scheduled. Manual refresh updates usage, provider list, and forces refresh of the current account only—no batch forced requests to other providers.

Quick Start

Requires the DeepSeek Harness web profile (@deepseek-ai/dsh >= 0.1.0-rc.6).

Install the exact version from npm (stable) by default; this is the same package used by the DSH Desktop Market:

dsh plugin --profile web add "@ychris12138/dsh-usage-stats@0.3.3"

Use dsh plugin --profile web add "github:Ychris12138/dsh-usage-stats" only to test an unreleased source/RC. GitHub main may be ahead of npm stable; source installs must not be treated as acceptance of a marketplace install.

Then restart any running dsh web and hard-refresh in the browser. A "Usage/Balance" entry appears at the bottom of the sidebar.

Marketplace GUI Install (DSH Community Market, Path A standard source)

This repository integrates following the standard source (Path A) of the DSH Community Market catalog adapter guide, with no changes to the Market code required. Two catalog data files are built in:

• catalog/catalog-source.json — source manifest (catalog-source.schema.json v1.0.0)
• catalog/v1/plugins.json — standard provider page (catalog-provider-page.schema.json v1.0.0)

Prerequisite (important): Marketplace-hosted installs only accept exact stable versions from the npm registry; git entries are browse-only. The npm name dsh-usage-stats is already taken by another project, so the catalog entry identity uses @ychris12138/dsh-usage-stats. The current stable/catalog version is 0.3.3; each new version is published in the following order:

1. Run npm run release:sync -- <version> to sync package.json / package-lock.json / catalog/v1/plugins.json, then npm run check:release blocks any identity or version drift.
2. Publish the scoped public package: npm publish --access public.
3. Publish the contents of catalog/v1/plugins.json to https://ychris12138.github.io/dsh-usage-stats/v1/plugins (GitHub Pages; manifest and endpoint must share the same origin, HTTPS 443, no credentials).
4. In DSH Plugin Market → Source Management → Add Source, paste the manifest URL: https://ychris12138.github.io/dsh-usage-stats/catalog-source.json; once selected, proceed to the "recovery-safe install boundary" GUI install.

If the catalog points to a not-yet-published version first, the marketplace install will fail-closed — this is expected behavior. A release is only complete after npm, Pages catalog, and the actual Desktop Market install have all been verified.

Upgrade/uninstall:

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

Supported Account Types / Providers

The plugin auto-discovers official DeepSeek routes and provider profiles in llm-pi-ai. Only providers with a public account interface or an explicit monitor are queried for remote accounts; no extra credentials are needed for token usage statistics.

Providers without a public account interface still get their tokens counted; the card shows "Not supported" and never guesses a balance.

Credentials & Provider Configuration

Credentials are resolved by Harness from ~/.dsh/.credentials.yaml. The installer does not read, create, or modify that file. Do not commit real keys, cookies, or admin tokens to Git, public issues, or paste them into coding agents.

Account Refresh

Default refresh intervals: active 1 minute, detail 2 minutes, background 15 minutes. For strictly rate-limited New API or corporate relays, you can adjust the global policy or disable automatic account refresh entirely:

# ~/.dsh/profiles/web/cordis.patch.yml
- insert:
    - id: usage-stats
      name: "@ychris12138/dsh-usage-stats"
      config:
        refresh:
          enabled: false
          activeMs: 60000
          detailMs: 120000
          backgroundMs: 900000

All three intervals must be integers between 60000 and 86400000 ms. To stop, use refresh.enabled: false; do not fill in an oversized timeout. Once disabled, each identical provider config still allows the first query; afterwards, normal panel reads only return cached data and do not hit upstream on cache expiry. The account endpoint's refresh=1 (Retry) can still explicitly refresh, and provider/monitor config changes trigger one new query for the new config.

The legacy disableBackgroundRefresh: true config is still equivalent to refresh.enabled: false; when both are present, the explicit refresh.enabled wins. This switch only disables automatic upstream refresh for accounts; it does not disable local token usage aggregation.

Estimated Cost & Budgets

Budgets are an optional, non-sensitive setting, disabled by default. Amounts are only computed when provider, model, event time, and currency can all be reliably determined by the built-in pricing rules; unknown relays, subscription routes, cache writes without prices, or mixed currencies display — as a whole, never partial costs or FX conversion.

# ~/.dsh/profiles/web/cordis.patch.yml
- insert:
    - id: usage-stats
      name: "@ychris12138/dsh-usage-stats"
      config:
        budgets:
          currency: USD
          daily: 5
          monthly: 100

Budgets use local calendar day/month boundaries: below 80% is normal, at 80% is warning, at 100% is critical. daily / monthly must be positive numbers or null; the current version does not perform FX conversion, so when the budget currency is incompatible with the reliable price currency, the status stays unknown.

The panel's current provider is stored in the browser's namespaced localStorage and restored on page refresh or DSH restart. If that provider has been deleted, the plugin clears the stale value and falls back to the original DeepSeek/configured provider fallback. This choice is not written to DSH settings, the server-side cache, or the new API.

Balance-type Providers

DeepSeek, Moonshot, etc. reuse the corresponding provider profile's apiKeyEnv by default. For example:

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

OpenRouter is an explicit exception: the official account credits endpoint requires a Management Key and cannot reuse the regular inference OPENROUTER_API_KEY. The plugin reads a separate reference by default; if not configured, it displays "Not configured" and never probes with the inference key:

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

The plugin displays OpenRouter balance as total_credits - total_usage, showing cumulative used and total credits simultaneously. A regular key's /api/v1/key only describes that key's spending limit and is not treated as account balance. Custom references can be configured via adapter: openrouter-balance and credentialRef in monitors.openrouter.

OrcaRouter prefers its balance endpoint /v1/balance, aggregating paid, free, and promo credits into current available balance; when older deployments lack that endpoint, it falls back to the OpenAI-compatible billing summary endpoint from the official docs (subscription endpoint total quota + usage endpoint cumulative usage, converted from US cents). Any available path that returns unrecognized data shows a clear error state; unknown results are never treated as 0. Infinite-quota sentinel values display as ∞, and OrcaRouter routes still do not participate in this plugin's model price estimation.

Token Plan Providers

# ~/.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
OLLAMA_API_KEY: sk-ollama-your-key

OpenCode Go tries in order: Harness credentials, ~/.local/share/opencode/auth.json, and finally the explicit OPENCODE_GO_AUTH_COOKIE + OPENCODE_GO_WORKSPACE_ID compatibility fallback. The Bearer usage endpoint is not a public API and may change with upstream; the Cookie is equivalent to login credentials and should not appear in logs or issues.

Ollama Cloud reads OLLAMA_API_KEY, calls /api/usage to show two subscription windows (5-hour session + weekly), with no balance; usage is converted to a progress bar using the 0..1 ratio.

The Ollama adapter only applies to configured providers and never adds accounts automatically: it is selected when the provider id is ollama, or when its baseURL host is ollama.com (including subdomains); local Ollama (localhost:11434) is not treated as a cloud quota account. Special proxies/custom endpoints can be bound via an explicit monitor:

# ~/.dsh/profiles/web/cordis.patch.yml
- insert:
    - id: usage-stats
      name: dsh-usage-stats
      config:
        monitors:
          relay-ollama:            # 你配置的 provider id
            adapter: ollama
            usageBaseURL: https://ollama.example.com
            credentialRef: OLLAMA_API_KEY   # 非已配置 provider 时必填

Z.ai global region uses api.z.ai; the China region uses open.bigmodel.cn. MiniMax prefers the official www.minimax.io / www.minimaxi.com Token Plan endpoints, parsing the 5-hour and weekly window remaining ratios and reset times.

New API, Sub2API & Custom Monitors

Merge config under the existing name: "@ychris12138/dsh-usage-stats" Cordis entry; do not add a second plugin entry. Monitor keys must be provider ids that actually exist in Harness; unknown providers, adapters, or invalid mappings prevent plugin startup before route and timer registration. Exception: when a monitor explicitly provides both usageBaseURL and credentialRef, it is considered self-contained and is temporarily materialized as a provider before provider registration visibility (suitable for providers loaded later on the Harness settings page); in that case the provider does not need to already appear in the registry.

# ~/.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

Supported adapters: 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 and warning.criticalBelow are absolute balance thresholds. Balances and Token Plans with total quotas automatically produce normal / warning / critical remaining-ratio states (defaults 30% / 10%).

Usage

1. Click “Usage/Balance” in the sidebar.
2. Use “Current Provider” to switch account cards; only one provider is displayed at a time.
3. Use ‹ / › to switch months; click a heatmap date to view that day's provider/model breakdown.
4. Refreshing from the title bar updates Tokens, the provider list, and forces a refresh of the current account.

安全导出 / Secret-free export

The three download endpoints export only whitelisted aggregated fields and do not include credential ref/value, Authorization, Cookie, raw upstream responses, prompt/reply content, or file paths:

• /api/usage-stats/export/daily.csv: Four token categories and full cost estimates, per day × provider/model.
• /api/usage-stats/export/sessions.csv: Session title, provider/model set, Tokens, full cost estimate, and last activity time.
• /api/usage-stats/export.json: Full aggregated data with schemaVersion, public pricing provenance, budget, and account-safe status.

CSVs use UTF-8, RFC 4180 quoting, and spreadsheet formula protection; Unicode titles open directly. Costs are exported only when costComplete=true; unknown or mixed currencies remain blank or null—partial amounts are never emitted.

“Last 14 days” is calculated on the local calendar and shows only dates within the window that have usage; future timestamps are not counted. The same model served by different providers is tracked separately, e.g. deepseek-official · deepseek-chat vs 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 the exact npm stable used by Desktop Market: `dsh plugin --profile web add "@ychris12138/dsh-usage-stats@0.3.3"` (or update the existing scoped package).
3. Use `github:Ychris12138/dsh-usage-stats` only when I explicitly ask to test unreleased source/RC code.
4. If dsh plugin is unavailable, use the compatible source installer only with my approval: `npx --yes github:Ychris12138/dsh-usage-stats`.
5. Do not combine bundle installation with an existing manual dsh-usage-stats Cordis entry.
6. For npx, require a verified package and exactly one Cordis entry, then run again with --check.
7. Report the exact package identity/version, installation path, and resolved profile paths.
8. 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 Keys, OpenCode auth.json, Cookies, and admin PATs never appear in browser responses, plugin caches, or logs.
• Sub2API sub2api-auth reuses the provider's own inference API Key (the one configured on the model page); no additional panel credentials are introduced or persisted.
• Custom monitors require HTTPS, same-origin relative paths, manual redirect handling, and JSON responses by default, with a 1 MiB body limit.
• Before sending credentials, IPv4/IPv6 resolutions of the target domain are filtered and one allowed connection address is pinned, preferring public addresses; HTTPS domains resolving to 198.18.0.0/15 may be used as synthetic fake-IPs for proxies such as Clash/Mihomo. Literal 198.18/15 and other private/special addresses are still rejected by default, preventing DNS-rebinding bypass of private-network restrictions.
• usageBaseURL must not embed username/password; headers such as Authorization, X-API-Key, API-Key are injected via credential ref.
• The nine data endpoints accept GET only; the OrcaRouter integration route's GET returns a boolean status only, and its POST performs a local settings mutation only after an explicit user click, requiring a non-simple custom action header. All routes validate both the peer socket and the Host header, supporting IPv4, IPv4-mapped IPv6, and [::1]:port.
• The usage cache ~/.dsh/storages/usage-stats-cache.json stores only aggregated Tokens, session ids, opaque revisions, and fold cursors—never prompts, replies, or file paths.

A local reverse proxy causes the plugin to see the proxy's own loopback address. Do not expose the endpoints to your LAN or the public internet via a reverse proxy; if you must use a proxy, add reliable authentication and access control at the proxy layer. Report security issues privately via SECURITY.md.

正确性与数据口径 / Correctness

Token counts come from provider-reported usage in assistant/chunk or assistant/message events and are not local estimates. Later samples for the same turn/step replace earlier ones, and values are aggregated by provider/model.

Costs are explicitly labeled as derived estimates: each usage sample uses its own event time, the original provider/model, and four token buckets to match against lib/pricing.js; when a sample is replaced, the old cost is subtracted first and the new cost is added. "Current price × historical cumulative tokens" is never used. The derived cost for each session continues to flow into usage.sessions, the session CSV, JSON export, and overall billing aggregation; the plugin does not inject any session UI into the DSH composer.

• Active sessions only process newly appended events.
• Persisted sessions use an opaque revision (Harness's list(); the older listSnapshots() remains compatible); when unchanged, logs are not re-read.
• Persisted logs are read through Harness's open(id, "read") read handle (the older readFrom() remains compatible); the handle is closed immediately after each read.
• Sessions that have left the live store (e.g. finished sub-agent runs) have their persisted logs back-filled by id at the next aggregation, and their tokens are counted toward daily/model totals without waiting for a background full scan.
• Gaps in the seq sequence, log rewrites, or live/persisted switches trigger a full re-folding of that session.
• Aggregation uses single-flight, and the cache is saved atomically within the same critical section.
• validate:live compares per session the raw artifact, session.history, the plugin endpoint, and the official token projection; missing files or inconsistencies return non-zero.

API

Except for the OrcaRouter POST above, non-GET methods return 405; non-loopback requests return 403. API JSON responses use Cache-Control: no-cache; download responses use Cache-Control: no-store and a fixed filename.

开发与验证 / Development

npm install
npm run check
npm test
npm pack --json

npm test runs fully offline and covers the bundle, client-side rendering and request races, server-side security boundaries, balance/Token Plan adapters, caching, and installer idempotency. Real-data validation requires running dsh web first:

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

All server-side scripts respect DSH_HOME. check-balance.mjs may display real balances; do not paste its output into public issues.

兼容性与致谢 / Compatibility & credits

The current npm stable is 0.3.3; the full release gate for v0.3.3 is in docs/release-checklist.md, and the change summary is in docs/release-notes-v0.3.3.md. The plugin depends on the Harness client module loader, the Cordis service, and session persistence; when Harness pre-release interfaces change, corresponding adaptations may be needed.

Reading persisted and active sessions branches on capability detection, not on version numbers, so the supported range >= 0.1.0-rc.6 remains unchanged: 0.1.3-alpha.1–0.1.5-rc.2 use list() snapshots + open(id, "read") read handles, while 0.1.0-rc.7–0.1.2-rc.1 use listSnapshots() + readFrom(); active sessions support both seq/snapshotEvents() and the legacy events array. session/disposed exists across this range (when it is missing, finished sessions are back-filled by the background full scan instead). The cache format is still version: 5; old caches are reused directly and re-folded in place.

display.currentSessionPill continues to be accepted as a v0.3.0 legacy boolean configuration key to avoid startup failures caused by old configs; the current client no longer registers any composer UI, so this key no longer has a visible effect. The session-context server API temporarily retains its original response semantics for v0.3.0 API compatibility and future integrations.

• Javis603/token-monitor: Reference for multi-provider quota normalization and Z.ai limit parsing.
• xiaoqi20/dsh-opencode-go-usage: Reference for DSH credential integration, OpenCode auth.json fallback, and Bearer usage endpoint.

This project reimplements a unified account protocol, adapters, and a single-vendor UI; it does not copy the reference projects' interfaces.

License

MIT