This article is derived from the plugin's already-indexed fields (wiki / faq / compatibility_json / readme), not freshly generated by AI. Source field is noted at the end of each section.

Quick start

dsh-usage-stats

— source: plugin_wiki.wiki_content

Install & verify

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

Run the command above in your DSH Web Profile. Then enable the plugin in the plugin list.

— source: plugins.install

Key points

• 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）
• • id: usage-stats
• 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.

— source: plugin_wiki.readme_en (fallback readme_raw)

FAQ

After installation, I don't see the "Usage/Balance" entry in the sidebar. What should I do?

You must restart dsh web after installation. The plugin's server-side routes and client bundle are mounted at startup; simply refreshing the browser won't reload the plugin. A hard refresh is required to load the new client modules. The installer writes - insert: id: usage-stats, name: dsh-usage-stats to cordis.patch.yml. Running it repeatedly won't append duplicates (README.md:31-36 / scripts/install.mjs:79-84).

Can I use it without configuring a Key? What can I see?

Token usage heatmaps and cache hit rates don't require any credentials and automatically aggregate across all sessions. Providers without a public balance endpoint show "Not Supported" on the account card, without guessing. Providers with missing keys show "Not Configured". OpenRouter is an exception: official account credits require a separate OPENROUTER_MANAGEMENT_KEY; the plugin won't try to use the regular inference key (README.md:74-90 / lib/balance.js:21-37).

Where is the data stored? Is it uploaded?

The server-side cache only stores aggregated token counts, session IDs, opaque revisions, and fold cursors, written to $DSH_HOME/storages/usage-stats-cache.json using temporary files + atomic renaming. API keys, cookies, management PATs, and upstream raw responses never enter browser responses, cache, or logs (README.md:265-270 / lib/index.js:229-242).

Can I integrate my own private provider?

Yes, using the declarative adapter: configure request.path (HTTPS same-origin relative path, body up to 1 MiB), request.auth.type (bearer/raw/x-api-key), and extract.* (JSON Pointer) under monitors.<providerId> in cordis.patch.yml. Only restricted GET + JSON is executed; no JavaScript. Credentials can only be injected via credential references, not by writing keys in URLs (README.md:179-199 / lib/accounts.js:189-234).

What should I do if OpenCode Go quota suddenly becomes unavailable?

OpenCode Go's Bearer usage endpoint is not an official public API; the upstream may change the structure at any time. When the interface changes, the panel will display specific error messages. You can explicitly set adapter: opencode-go and credentialRef: OPENCODE_GO_API_KEY under monitors.opencode-go, or fall back to the cookie scheme using OPENCODE_GO_AUTH_COOKIE + OPENCODE_GO_WORKSPACE_ID. When you want to stop using it, simply delete the corresponding monitor from the Cordis entry (README.md:127 / lib/subscriptions.js:8-22).

Can the reverse proxy be exposed to the public internet?

The five endpoints only verify loopback sockets and Host headers, without authentication; if placed behind a reverse proxy, the plugin will see the proxy's loopback address, which bypasses the security boundary. Both README and SECURITY.md clearly state "Do not expose endpoints via reverse proxy to LAN or public internet; if proxying is necessary, you must add reliable authentication and access control at the proxy layer" (README.md:272 / SECURITY.md:13-15).

How to uninstall?

Run dsh plugin --profile web remove dsh-usage-stats and restart dsh web; the cache file ~/.dsh/storages/usage-stats-cache.json remains on disk and can be manually deleted if needed (README.md:37-42).

Why is the balance abnormal / showing "Not Configured"?

Balance/Token plans use credentials from the corresponding provider profile: DeepSeek uses DEEPSEEK_API_KEY, OpenRouter uses OPENROUTER_MANAGEMENT_KEY, and Z.ai/Kimi/MiniMax each have independent keys. Check if these variables exist in ~/.dsh/.credentials.yaml, and note that the installer won't automatically create or modify this file (README.md:91-130 / lib/accounts.js:14).

— source: plugin_wiki.faq_json

Compatibility

• DSH: >=0.1.0-rc.6
• Node: 未声明
• Platforms: 跨平台

— source: plugin_wiki.compatibility_json

Pitfalls

Review the upstream repo before installing. This guide is auto-derived from indexed fields and may lag the latest release. If anything contradicts the official docs, treat the upstream source as authoritative.

— source: general rule