dsh-hud

A game-style HP / MP / TIME HUD for DeepSeek Harness.

中文

Overview

dsh-hud is a standard Host + Client plugin bundle: no runtime patches, no node_modules surgery. It visualizes the current agent session's health at the bottom of the sidebar using a light, youthful gacha-HUD visual language.

Screenshot


> dsh-hud runs directly inside the DeepSeek Harness sidebar.


> HP for context, MP for resources, TIME for workspace cumulative time.


> OpenCode Go 5H / Weekly / Monthly quota details.


> HP / MP / TIME remain available in the 56px rail mini HUD.

The three meters

HP — remaining context capacity

How much context the current session has left.

• Source: the Harness contextPressure projection (projectedTokens / contextWindow).
• HP% = clamp(100 × (1 − projectedTokens / contextWindow)).
• Color steps with capacity: green → yellow-green → gold → orange → red.

MP — remaining resource of the current provider

MP reflects the available resource of the provider actually selected for the current session, not a fixed account balance.

• It is keyed on the provider route, never the model name — the same model name shows a different resource under a different provider.
• Unsupported providers show -- and NO QUOTA DATA, never the previous provider's balance.

TIME — workspace cumulative time

The cumulative agent wall-clock time of the current workspace, across sessions.

• Built from turn/start → turn/end intervals, merged as a union across all sessions (overlaps are never double-counted).
• An in-progress turn counts up to the current instant.

Provider-aware MP

DeepSeek Official

MP shows the account's total balance (e.g. ¥10.73); the bar is relative to mpMaxBalance (default 50 CNY — above that the bar stays full and the real amount is shown).

OpenCode Go

The official plan defines three simultaneously-active windows: Rolling 5 hours / Weekly / Monthly. The UI prefers percentages:

• Each window's remaining = clamp(100 − usagePercent).
• The main MP value is the bottleneck: min(rolling, weekly, monthly) — the resource most likely to run out first.
• The main bar uses the same bottleneck value.

Example:

◇ MP                         78%
[MP bar]

5H 92% · W 78% · M 86%

OPENCODE GO // 02

Layouts

Wide Sidebar

The full three-meter HUD: STATUS card head → HP → MP → TIME. Each meter opens a detail popover on click.

56px Rail

When the Harness itself collapses to the 56px rail, dsh-hud shows three mini vertical bars (HP / MP / TIME) plus a hover tooltip — no vertical space wasted.

HUD Collapse

The wide HUD can be manually collapsed into a single icon button (~34px), and expanded again by clicking it.

• The preference is stored in localStorage under key dsh-hud:collapsed.
• Expanded by default; survives refresh and restart; switching Session / Workspace does not change it.

Installation

BigFish users

Download dsh-hud-0.1.0.tgz from Releases, then:

dsh plugin --profile web add ./dsh-hud-0.1.0.tgz

dsh plugin reconciles dsh-hud into dsh.profile.bundles automatically. Fully quit and relaunch BigFish for the profile to boot with the plugin.

Native DeepSeek Harness users

dsh plugin add ./dsh-hud-0.1.0.tgz

Build from source

npm install
npm run build
npm pack          # produces dsh-hud-0.1.0.tgz

Configuration

Optional hud: section in $DSH_HOME/settings.yaml (schema-registered; safe defaults apply without it):

hud:
  mpMaxBalance: 50            # balance treated as a full MP bar (CNY)
  balanceRefreshMinutes: 5    # host-side resource refresh interval

Build

npm install
npm run build                  # tsc (strict) host + esbuild client bundle → lib/
npm run typecheck              # strict typecheck only
node scripts/verify-host.mjs   # host logic checks (real-history test optional, see below)

The build resolves @deepseek-ai/* type declarations from the installed BigFish distribution; override the location with DSH_TYPES_ROOT.

The real-history aggregation test in verify-host.mjs is optional: it only runs when DSH_HOME (default ~/.dsh) and DSH_HUD_VERIFY_WORKSPACE (the absolute workspace path to verify) are set. Without them it is skipped and the pure-logic checks still run.

Compatibility

• DeepSeek Harness / BigFish: @deepseek-ai/* 0.1.0-rc.6 (see package.json peerDependencies)
• Node.js: ≥ 20 (build verified on Node 22)
• Platform: Web profile (browser)

Security

Provider credentials are resolved only inside the Harness Host process via ctx.credentials.resolve():

• Credentials appear only as environment-variable names / credential references, e.g. DEEPSEEK_API_KEY, OPENCODE_GO_API_KEY; there is never a real key or token in the source.
• The resolved secret value never goes into:

- the Client bundle - RPC DTOs - localStorage - the README - logs

• The OpenCode Go credential reference comes from the apiKeyEnv configured under llm-pi-ai; dsh-hud reuses that provider's existing credential and never asks you to re-enter it.

Known Limitations

• v0.1.0 ships only two resource adapters: DeepSeek Official and OpenCode Go; selecting any other provider (GLM, OpenRouter, custom providers, …) shows -- for MP.
• The rail mode shows no numbers — only mini bars plus a tooltip.
• No EXP, levels, achievements, charts, or history.
• HUD collapse is purely manual; there is no auto-collapse based on workspace count or overflow.

License

[MIT](./LICENSE)