FengHuoLinShan/dsh-plugin-llm-balance

🏷️ Part of the DSH official plugin ecosystem (git tag: dsh-official-plugin; GitHub topics: dsh-plugin · deepseek-harness).

English | 中文

A general-purpose DeepSeek Harness (DSH) plugin: a draggable, minimal rounded card pinned to the top-right of the Web GUI that shows the balance/quota of the three most recently used providers, including API balances and common coding plans.

• Recent providers (≤3): counts only successful model calls completed after the plugin is enabled and aggregates the three most recent distinct providers from persisted sessions.list projections. Membership updates in real time, while visible providers keep fixed slots: repeated use does not reorder rows, and a newcomer replaces only the evicted provider's slot. It does not scan old history, call session.models, or resume cold sessions.

• Balance-type (DeepSeek / Moonshot platform) color-coded by amount:

  Color	Balance	Meaning
  🟢 Green	>= 100	Healthy
  🟡 Yellow	20 ~ 99	Okay
  🔴 Red	1 ~ 19	Low
  ⚪ Gray	< 1	Depleted; or query failure / loading

• Quota-type (Kimi, Codex Connect, OpenCode Go, OpenRouter Key limits, MiniMax Token Plan, and Z.AI/BigModel Coding Plan) is color-coded by remaining ratio: green >= 50%, yellow 20–50%, red 5–20%, gray < 5%. Multi-window plans show 5h, daily, weekly, or monthly percentages and reset times; the status dot uses the lowest remaining window.

• DeepSeek peak/off-peak pill: DeepSeek balance rows carry a small 低谷/高峰 (off-peak/peak) badge — since 2026-08-17, peak hours are 09:00–12:00 and 14:00–18:00 Beijing time on weekdays, and every other time (including weekends) is half price. Pure wall-clock math with no extra requests; the tooltip shows the schedule plus a countdown to the next switch, and the pill refreshes with the existing balance polling and visibility-resume refresh. Rows without a configured key carry no pill.

• Auto-discovery: queryable providers come from the built-in usage table, llm-pi-ai.providers.*, and the plugin's compatibility config.

• Drag anywhere; the position is remembered in localStorage.

• Click to refresh immediately.

• Polling: every 60 s by default; paused while the tab is hidden, refreshed on return.

How it works

• Host half (lib/index.js): registers the new DSH state/wire projection contract and the /api/llm-balance exact Fetch route (under dsh-client-connection's /api shared channel). Explicit apiKeyEnv references are authoritative; otherwise the plugin reads the llm-pi-ai/<provider> API-key record before falling back to the provider's default environment reference. OAuth grants are never interpreted. Same-source queries are deduplicated.

• Client half (lib/client.js): aggregates the three most recent providers from every session's projectionValues.llmBalanceRecentProviders and queries balances for only those providers through same-origin fetch('/api/llm-balance'). It refreshes immediately on mount, membership changes, and visibility restoration; recency-only order changes neither reorder rows nor trigger an extra request. While visible it polls every 60 seconds by default. Dragging, click-to-refresh, and card rendering are unchanged.

• Supported provider APIs:

  provider id	API	Basis
  deepseek / deepseek-official	GET https://api.deepseek.com/user/balance	Balance (CNY; official total_balance is a string, numbers also accepted)
  moonshotai / moonshotai-cn	GET https://api.moonshot.ai/v1/users/me/balance / https://api.moonshot.cn/...	International/CN balance (CNY)
  kimi-coding	GET https://api.kimi.com/coding/v1/usages	Subscription quota (top-level usage = weekly limit + per-window details (5h throttle etc.), membership level included)
  openai-codex	dsh-codex-connect (GET https://chatgpt.com/backend-api/wham/usage)	Codex Connect quota (primary rateLimits bucket (id codex, fallback first) windows = remaining percentage (limit=100; 18000s → 5h, 604800s → weekly, other durations get a stable label); optional individualLimit → monthly quota, credits → USD balance or a Credits segment (when credits.unlimited=true, rendered as finite 100/100 solely for the percentage UI — green 100% instead of gray ∞/∞; the account stays unlimited))
  opencode-go	GET https://opencode.ai/zen/go/v1/usage	OpenCode Go subscription quota (usage.rolling → 5h, usage.weekly → weekly: percent is the used percentage → amount=100-percent, limit=100, resetsAt → reset time; monthly ignored; an invalid single window is skipped, at least one valid window required. ⚠️ Endpoint is currently undocumented and may change)
  openrouter	GET https://openrouter.ai/api/v1/key	Current key's daily/weekly/monthly spending limit; an unlimited key reports no remaining-balance metric
  minimax / minimax-cn	GET https://www.minimax.io/v1/token_plan/remains / https://www.minimaxi.com/...	Token Plan text-model 5h/weekly remaining ratio
  zai / zai-coding-cn	GET https://api.z.ai/api/monitor/usage/quota/limit / https://open.bigmodel.cn/...	Coding Plan 5h/weekly remaining ratio; MCP/tool-only limits are ignored

  Other routes declared in llm-pi-ai without a built-in balance API are reported honestly as no_balance_api, never as a configuration error.

OpenAI Codex (Codex Connect, optional)

• Prerequisites: to display quota, install and enable dsh-codex-connect separately (dsh plugin --profile web add dsh-codex-connect@alpha, minimum compatible 0.1.0-alpha.4.5) and complete its ChatGPT OAuth sign-in. With only DSH-native Codex OAuth, the row reports that Codex Connect is still required for quota.
• No API key: Codex uses ChatGPT OAuth — no DEEPSEEK_API_KEY-style credential is needed; sign-in state and quota reads go entirely through codex-connect's OpenAICodexCredentialStore wrapper. The plugin dynamically imports codex-connect only when openai-codex is queried. Module missing/incompatible or not signed in → configured:false (safe ref, no credentials); signed in but quota lookup fails → status:error / error:unavailable; success → the secret-free OpenAICodexUsage is mapped onto the existing quota shape.
• Display: 5h/weekly limits render as remaining percentages (e.g. 5h 74% · 周 68%); accounts with a spend cap get an extra monthly (月) window; when codex-connect reports credits.unlimited=true, the account remains unlimited but the Credits segment renders as finite 100/100 solely for the existing percentage UI — green 100% instead of gray ∞/∞.
• Security: this plugin never reads or copies the OAuth document (.openai-codex-auth.json) directly; tokens never appear in responses, logs, or the page.

Install

Requires DSH 0.1.1-rc.2 through 0.1.2-alpha.4. The former uses loopback RPC authority; the latter uses the host's unified BrowserAuth RPC.

The plugin ships in the official bundle form (dsh.bundle.patch activation layer + dsh.client browser half, per the official packaging doc) — a single dsh plugin add both installs and activates it (auto-appended to the profile's bundles layer):

# A (recommended): from npm (after publish)
dsh plugin --profile web add dsh-plugin-llm-balance

# B: from GitHub (source checkout, no build needed)
dsh plugin --profile web add "github:FengHuoLinShan/dsh-plugin-llm-balance#main"

# C (local development): from a checkout
dsh plugin --profile web add /path/to/dsh-plugin-llm-balance

# D (any version): from a tarball
dsh plugin --profile web add ./dsh-plugin-llm-balance-0.3.0.tgz

Restart the dsh service (plugin-set changes need a restart; afterwards client-bundle edits hot-reload via HMR only while the DSH checkout's pnpm run dev:web watcher is running — otherwise reinstall/restart/refresh), then refresh the page.

Tune it in ~/.dsh/profiles/web/cordis.patch.yml by row id:

- update:
    - id: llm-balance
      config:
        refreshMs: 30000

Configuration

Field	Default	Description
refreshMs	60000	Client polling interval (ms)
timeoutMs	15000	Server-side query timeout (ms)
provider	deepseek	(Legacy) single-provider mode; multi-provider mode needs no config — auto-discovery
apiKeyEnv	DEEPSEEK_API_KEY	(Legacy) credential reference name for single-provider mode
baseURL	per-provider default	(Legacy) optional base URL override for single-provider mode

Multi-provider mode works out of the box: providers come from the built-in table plus llm-pi-ai settings. An explicit apiKeyEnv is resolved exclusively; otherwise the llm-pi-ai/<provider> API-key record is preferred before the provider's default environment reference. OAuth grants are not interpreted; Codex quota is managed by Codex Connect.

All fields are leniently validated: non-numeric / non-positive refreshMs / timeoutMs, non-string or empty provider / apiKeyEnv, non-string baseURL all fall back to defaults — the plugin never fails to start because of bad config (zero-dependency normalizeConfig, semantically equivalent to the official Config schema fallback).

Self-test

node test/balance.test.mjs   # host-half logic tests (stubbed ctx + stubbed fetch)

Uninstall

dsh plugin --profile web remove dsh-plugin-llm-balance   # removes dependency and bundle layer

Security notes

• API keys are resolved and used only server-side; they never appear in responses, logs, or the page.
• Balance endpoints are proxied by the server (same origin) — no CORS exposure, no key leakage.
• OpenAI Codex has no API key: quota reads go through dsh-codex-connect's OpenAICodexCredentialStore; a DSH-native llm-pi-ai grant is used only as a configured-state signal and its OAuth payload is never parsed, copied, or refreshed here.
• Balance/quota data comes from official APIs and may lag slightly; informational only.
• Trust boundary: balance queries use the /api/llm-balance exact Fetch route under dsh-client-connection's /api shared channel — Host/Origin fencing and the host's unified BrowserAuth complete before the plugin handler is invoked (identical to the official /api routes).
• Minimum DSH version: 0.2.0-alpha (connection.fetch.register is available from that version; also works on 0.1.5-rc.x — connection.rpc.handle is broken by construction for third-party plugins since 0.1.5-rc.2, so this plugin no longer uses it).

License

MIT