@ruoyang/dsh-plugin-deepseek-balance

A floating badge in the DeepSeek Harness Web UI showing the remaining balance of the DEEPSEEK_API_KEY credential the harness itself uses for model calls.

中文说明见下方 中文。

What it does

Part	Behaviour
Status dot	green = balance available, amber = account cannot call the API, grey = querying, red = query failed
Badge text	total balance in the primary currency, e.g. ¥4.94
Hover panel	per-currency totals, granted vs topped-up split, whether the account is callable, and the query time
Interaction	click to refresh, drag to reposition, automatic refresh every 60 seconds
Language	every label comes from this plugin's own locale namespace, so the badge follows the UI language (English / Chinese)

The badge itself is a pill pinned to the lower-right corner; drag it anywhere and it stays there for the session.

Requirements

• A DeepSeek Harness installation with the Web surface (dsh web).
• DEEPSEEK_API_KEY configured — via the launching environment, a .env file, or Settings → Models. The plugin resolves it per query through the credentials seam, so a key you rotate takes effect on the next refresh with no restart.
• Node.js >= 18.17 on the host (the host half uses global fetch and AbortSignal.timeout).

The package deliberately declares no peerDependencies on @deepseek-ai/dsh-*, so it installs across harness versions instead of being pinned to one. It also has no runtime dependencies and no install scripts.

Install

Using the dsh CLI:

dsh plugin --profile web add @ruoyang/dsh-plugin-deepseek-balance

In the Web UI: Settings → Plugins, then install by the package name above.

Through an agent session, the equivalent is the plugin_manager tool with action: install_bundle and that package name as target.

If you install through a registry mirror

registry.npmmirror.com and other read-only mirrors lag behind npmjs.org, and a package they have not synced yet answers 404 — which looks exactly like "no such package". If your npm or pnpm is pointed at a mirror (common on machines set up for fast installs), either wait for the sync or send this scope to the official registry:

npm config set @ruoyang:registry https://registry.npmjs.org/

A scope key is a different setting from registry, so it also survives an inherited npm_config_registry environment variable, which outranks every .npmrc.

A new bundle activates immediately; if the badge does not appear, reload the page once so the browser picks up the new client module.

Uninstall

dsh plugin --profile web remove @ruoyang/dsh-plugin-deepseek-balance

How it works

One bundle, two halves, mounted by a single Loader row:

File	Role
cordis.patch.yml	inserts the row deepseek-balance
index.js	Host half: serves GET /deepseek-balance/api
client.js	Client half: a lazy module-system factory that registers into the shell.overlay slot

Your key never reaches the browser. The host half reads it through ctx.credentials and calls https://api.deepseek.com/user/balance itself; the browser half only fetches the same-origin JSON snapshot the host produces. Failures come back as { "ok": false, "code": …, "message": … } with the error's cause chain flattened into message, so a transport problem is diagnosable without logs.

The plugin declares no settings and no Config schema — there is nothing to configure.

Troubleshooting

curl http://127.0.0.1:3080/deepseek-balance/api            # the JSON snapshot the badge renders
curl "http://127.0.0.1:3080/deepseek-balance/api?force=1"  # bypass the host half's 20s cache

Response	Meaning
{"ok":true,…}	working
{"ok":false,"code":"NO_KEY"}	no DEEPSEEK_API_KEY is configured
{"ok":false,"code":"HTTP_401"}	the key is rejected by DeepSeek
{"ok":false,"code":"TRANSPORT"}	the host could not reach api.deepseek.com

A 404 on that path means the row did not mount — check that the bundle is enabled in Settings → Plugins.

Known limitations

• The badge position resets on page reload; it is not persisted.
• Only the two languages the harness ships (English, Chinese) have dictionaries; a third language falls back to the harness's own chain and then to the key, so add a dictionary before adding a language.

Language

Strings live in the plugin's own locale namespace and reach the component through the t seat the slot framework injects for a registration that names a locale namespace, so switching Settings → General → Language re-words the badge live. Host-side failures arrive as a machine-readable code that the badge translates; an unrecognised code falls back to the host's own message so a novel failure stays legible.

中文

在 DeepSeek Harness 的 Web 界面右下角悬浮显示当前 DEEPSEEK_API_KEY 的剩余余额。

它做什么：状态点（绿=有余额 / 黄=账号不可调用 / 灰=查询中 / 红=查询失败）、胶囊显示主币种 总余额、悬停展开各币种总余额与赠金/充值拆分、点击刷新、按住拖动、每 60 秒自动刷新。

要求：带 Web 界面的 Harness（dsh web）；已配置 DEEPSEEK_API_KEY（环境变量、.env 或 设置里的 Models 页均可，插件每次查询都重新解析，换密钥不用重启）；宿主机 Node ≥ 18.17。

安装：

dsh plugin --profile web add @ruoyang/dsh-plugin-deepseek-balance

或在 Web 界面 设置 → 插件 里按包名安装。装好后如果徽标没出现，刷新一次页面。

卸载：dsh plugin --profile web remove @ruoyang/dsh-plugin-deepseek-balance

密钥安全：密钥全程留在宿主机侧，由宿主半经 ctx.credentials 读出后直接请求 api.deepseek.com；浏览器半只读同源的 JSON 快照，密钥不会进入浏览器。

排查：

curl http://127.0.0.1:3080/deepseek-balance/api            # 徽标渲染用的 JSON
curl "http://127.0.0.1:3080/deepseek-balance/api?force=1"  # 绕过宿主半 20 秒缓存

返回 NO_KEY = 没配密钥，HTTP_401 = 密钥被拒，TRANSPORT = 宿主机连不上 api.deepseek.com；404 = 行没挂上，去 设置 → 插件 看是否启用。

已知限制：徽标位置在刷新页面后重置（不做持久化）；内置字典只有 harness 自带的两种语言 （中/英），加第三种语言前需要先补字典。

徽标文字走本插件自己的 locale 命名空间，设置 → 通用 → 语言 切换后会实时改文案。

Releasing (maintainer)

The default registry on a machine set up for fast Chinese installs is registry.npmmirror.com — a read-only mirror. It serves installs but accepts no publishes, so a bare npm publish fails with ENEEDAUTH against it. Pass the official registry explicitly:

cd dsh-plugins/deepseek-balance
npm login   --registry=https://registry.npmjs.org/
npm whoami  --registry=https://registry.npmjs.org/   # must print the owner of the @ruoyang scope
npm publish --registry=https://registry.npmjs.org/

Why the flag and not just .npmrc: npm resolves config as cli > env > project > user > global, and a shell that inherited npm_config_registry (npx exports it, so any shell started by an npx-launched dsh carries it) overrides every file. npm config ls shows it as registry = "…" ; overridden by env. The project .npmrc here is a convenience for clean shells; the flag is what always works.

A scoped package can only be published by the account that owns the scope, so npm whoami must match @ruoyang — either that is your npm username, or ruoyang is an org you belong to.

For a new release, bump version in package.json first: npm refuses to republish an existing version, and a re-npm pack at the same version silently overwrites the local tarball while the already-installed copy keeps the old bytes.

License

MIT