DeepSeek Balance for DeepSeek Harness

Show your DeepSeek account balance right above the account row in the DSH sidebar.

English · 中文

What it is

A client-side plugin for DeepSeek Harness (DSH). It renders one row in the
sidebar footer, directly above the account row (avatar + nickname), showing the
DeepSeek wallet balance for the signed-in account. Hovering or focusing the row
opens a details popover; clicking it forces a refresh.

The package is @local/dsh-balance, the row id is balance, and the plugin
appears in the plugin manager as DeepSeek Balance.

Features

• One-glance balance — a 24px wallet glyph plus the primary-currency total,
  rendered as a single row above the account row.
• Pixel-aligned with the account row — 44px row height, 14px tabular
  numerals, 6px padding, 8px gap. The row is widened 2px on each side so the
  icon and the avatar share a left edge, and the amount and the nickname share
  one too.
• Per-currency details on hover — total, top-up balance, bonus balance for
  every currency, the last update time (relative; absolute on hover), and the
  Usage / Top up links.
• Manual refresh — click the row, or press Enter / Space
  when it is focused, to bypass the focus throttle.
• Automatic refresh that survives a collapsed sidebar — every trigger is
  bound to the plugin lifecycle, not to the row component's mount.
• Threshold colors — the CNY total turns amber below the warn threshold and
  red below the danger threshold. USD never triggers a color; both light and
  dark themes are covered.
• Honest states — signed out, first load, and read failures are visually
  distinct; a failed read keeps the last good value and adds a gray ⚠.
• Configurable — polling switch, polling interval and both CNY thresholds
  are editable in the plugin settings page and apply without reloading.

Requirements

• DeepSeek Harness Desktop >= 0.2.1-rc.1 < 0.3.0
• Node.js ^22.19.0 || >=24 and pnpm — build-time only

Install

This is a local plugin: it is installed from a checkout, not from npm.

git clone https://github.com/ECHOUniverse/dsh-balance.git
cd dsh-balance
pnpm install
pnpm build

# Use the CLI that ships with DSH Desktop (do not use a global `dsh`)
DSH="/Applications/DeepSeek Harness.app/Contents/Resources/runtime/cli/bin/dsh"
"$DSH" plugin --profile desktop add link:"$PWD"

Then fully quit and restart DSH. The client bundle is loaded once when the
Web frontend starts, and external plugins have no hot-reload promise.

Use --profile for a profile other than desktop. Installation writes
the dependency and a link: symlink into
~/.dsh/profiles//package.json and its node_modules.

> lib/client.js is a build artifact and is not committed, which is why the
> pnpm build step is required before installing.

Uninstall

DSH="/Applications/DeepSeek Harness.app/Contents/Resources/runtime/cli/bin/dsh"
"$DSH" plugin --profile desktop remove @local/dsh-balance

Restart DSH afterwards for the row to disappear.

Configuration

Open Plugin manager → Plugins → DeepSeek Balance → Configuration. The fields
are volatile host configuration, so a save takes effect on the next refresh
without reloading the plugin.

The initial values also live in cordis.patch.yml.

Refresh behavior

Every trigger is owned by the plugin lifecycle (src/client.tsx,
ctx.effect(() => controller.attach())), not by the row component, so collapsing
the sidebar — which unmounts the row — does not stop automatic refresh. Rationale
in ADR 0001.

Triggers share in-flight merging: only one read runs at a time, and triggers
that arrive meanwhile collapse into at most one pending follow-up read. Each
client request times out after 8s. Failures are not retried — the only exception
is the startup refresh.

Cache. Key @local/dsh-balance/cache/v1 in localStorage, holding
{ wallets: { value, bonusWallets }, fetchedAt }. It never expires on its own:
on a cold start the cached value and its relative age render first, then the
background read replaces them.

Data sources and extension points

• Row position — slot sidebar.footer.action (kind list, scope root,
  owner props { wide }), inserted before settingsArea (the account menu).
• Balance — ctx.remote.account.getBalance({ version, locale, timezoneOffsetSeconds }),
  which returns null (signed out), { status: 'ready', value, bonusWallets },
  or { status: 'failed' }.
• Links — ctx.remote.account.getState().links.usageUrl and .topUpUrl.
• Strings — registered via ctx.locale.register('balance', { zh, en }); the
  plugin manager title and description come from locale/zh.json
  and locale/en.json.

Troubleshooting

Known limitations

• sidebar.footer.action is a DSH-internal slot, not a documented public API.
  A DSH upgrade (especially 0.3) may change its name, props, or neighbors.
• External client bundles have no hot reload: rebuild and restart DSH to see
  changes.
• Local installation only — this package is not published to npm.
• Requires a signed-in DeepSeek account; when signed out, the row only says so.
• Threshold colors apply to the CNY total only. With multiple currencies the row
  shows CNY (or the first currency when there is no CNY).
• The host half declares @deepseek-ai/schemastery as a peer dependency and
  relies on the DSH runtime to resolve it.

Development

pnpm install
pnpm build      # src/client.tsx -> lib/client.js (lazy-CJS factory)
pnpm test       # vitest: formatting, totals, thresholds, cache, settings, relative time
pnpm typecheck  # tsc --noEmit
pnpm smoke      # loads lib/client.js in a Node VM and checks factory/slot/render
pnpm verify     # all of the above
pnpm watch      # esbuild watch; restarting DSH is still required

Build pipeline

src/client.tsx is bundled by esbuild to CommonJS (react, react/jsx-runtime,
react-dom, @deepseek-ai/cordis, zod and the rest of the web frontend's
staticModules stay external), then scripts/build-client.mjs wraps it in the
browser module-system factory:

window.__ModuleLoader__.load({
id: '@local/dsh-balance',
factory: (require) => {
var module = { exports: {} }
var exports = module.exports
/* esbuild CJS output */
return module.exports
},
})

Project layout

Contributing

Issues and pull requests are welcome. Please run pnpm verify before opening a
PR, and keep the row's alignment with the account row covered by the smoke test.

License

MIT © ECHOUniverse

Disclaimer

An unofficial community plugin, not affiliated with or endorsed by DeepSeek.
It reads balances through DSH's account remote API using the credentials the app
already holds; it does not store or transmit them anywhere else. Use at your own
risk.

中文

在 DSH 侧边栏账户行正上方显示 DeepSeek 账户余额。

这是什么

一个 DeepSeek Harness（DSH） 客户端插件。它在侧边栏底部、账户行（头像 +
昵称）正上方渲染一行，展示当前登录账户的 DeepSeek 钱包余额；悬停或键盘
聚焦时弹出明细，点击整行则强制刷新。

包名 @local/dsh-balance，行 id 为 balance，插件管理页显示名「DeepSeek 余额」。

功能特性

• 一眼可见余额 — 24px 钱包图标 + 主币种合计，占一行，位于账户行上方。
• 与账户行逐像素对齐 — 行高 44px、字号 14px（等宽数字）、内边距 6px、间距
  8px；左右各外扩 2px，使图标与头像左缘、金额与昵称左缘对齐。
• 悬停查看分币种明细 — 每个币种的总额、充值余额、赠金余额、上次更新时间
  （相对时间，悬停显示绝对时间），以及「用量」「充值」入口。
• 手动刷新 — 点击整行，或聚焦后按 Enter / Space，
  绕过 focus 节流立即读取。
• 收起侧边栏也不中断自动刷新 — 全部触发源挂在插件生命周期上，而不是行组件
  的挂载/卸载。
• 阈值配色 — CNY 合计低于警戒值显示橙色、低于危险值显示红色；USD 不参与
  判定；明暗主题均有适配。
• 状态诚实 — 未登录、首次加载、读取失败各有独立视觉状态；失败时保留上一次
  成功的数值并显示灰色 ⚠。
• 可配置 — 轮询开关、轮询间隔、两个 CNY 阈值均可在插件设置页修改，保存即时
  生效，无需重载插件。

环境要求

• DeepSeek Harness Desktop >= 0.2.1-rc.1 < 0.3.0
• Node.js ^22.19.0 || >=24 与 pnpm（仅构建时需要）

安装

这是本地安装插件：从代码检出安装，不发布到 npm。

git clone https://github.com/ECHOUniverse/dsh-balance.git
cd dsh-balance
pnpm install
pnpm build

# 使用 DSH Desktop 自带的 CLI（不要用全局 dsh）
DSH="/Applications/DeepSeek Harness.app/Contents/Resources/runtime/cli/bin/dsh"
"$DSH" plugin --profile desktop add link:"$PWD"

装完必须完全退出并重启 DSH：客户端 bundle 只在 Web 前端启动时加载一次，
外部插件没有热更新承诺。

其他 profile 把 --profile desktop 换成对应名称。安装会写入
~/.dsh/profiles//package.json 的依赖与 link: 符号链接。

> lib/client.js 是构建产物、不提交到仓库，所以安装前必须执行 pnpm build。

卸载

DSH="/Applications/DeepSeek Harness.app/Contents/Resources/runtime/cli/bin/dsh"
"$DSH" plugin --profile desktop remove @local/dsh-balance

卸载后同样需要重启 DSH。

配置项

「插件管理 → 插件 → DeepSeek 余额 → 配置」。这些是 Host 端的 volatile 配置，
保存后在下一次刷新时生效，无需重载插件。

初值同时写在 cordis.patch.yml。

刷新策略

所有触发源都由插件生命周期持有（src/client.tsx 中的
ctx.effect(() => controller.attach())），不随行组件挂载/卸载变化；因此收起
侧边栏（行被卸载）后自动刷新仍继续。设计与取舍见
ADR 0001。

所有触发共享在途合并：同一时刻只有一次读取在进行，期间到达的触发合并为最多
一次待补读取。每次请求 8 秒超时；失败不自动重试，唯一例外是启动刷新。

缓存：localStorage 键 @local/dsh-balance/cache/v1，内容为
{ wallets: { value, bonusWallets }, fetchedAt }，不过期；冷启动先显示缓存值与
相对时间，再由后台读取覆盖。

数据来源与扩展点

• 行位置 — 插槽 sidebar.footer.action（kind list，scope root，owner
  props { wide }），插在 settingsArea（账户菜单）之前。
• 余额 — ctx.remote.account.getBalance({ version, locale, timezoneOffsetSeconds })，
  返回 null（未登录）、{ status: 'ready', value, bonusWallets } 或
  { status: 'failed' }。
• 链接 — ctx.remote.account.getState().links.usageUrl / .topUpUrl。
• 文案 — 通过 ctx.locale.register('balance', { zh, en }) 注册；插件页展示名
  与说明来自 locale/zh.json、locale/en.json。

常见问题

已知限制

• sidebar.footer.action 是 DSH 内部插槽，未在公开文档中承诺；DSH 升级（尤其
  0.3）可能改变其名称、props 或相邻布局。
• 外部插件的客户端代码没有热更新承诺：改完 pnpm build 后需重启 DSH。
• 仅支持本地安装，未发布到 npm。
• 仅对已登录的 DeepSeek 账户可用；未登录时行内只提示登录。
• 阈值配色只对 CNY 合计生效；多币种时余额行显示 CNY（无 CNY 时显示第一个币种）。
• Host 半依赖安装包提供的 @deepseek-ai/schemastery（peerDependency，由 DSH
  运行时解析，不随插件打包）。

开发

pnpm install
pnpm build      # src/client.tsx -> lib/client.js（lazy-CJS 工厂）
pnpm test       # vitest：金额格式化、合计、阈值、缓存、设置、相对时间
pnpm typecheck  # tsc --noEmit
pnpm smoke      # 在 Node VM 中加载 lib/client.js，验证工厂/插槽/渲染
pnpm verify     # 以上全部
pnpm watch      # esbuild watch，仍需重启 DSH 才能生效

构建链

src/client.tsx 由 esbuild 打成 CommonJS（react、react/jsx-runtime、
react-dom、@deepseek-ai/cordis、zod 等 Web 前端的 staticModules 全部
external，不重复打包），再由 scripts/build-client.mjs 包进浏览器模块系统的
工厂外壳：

window.__ModuleLoader__.load({
id: '@local/dsh-balance',
factory: (require) => {
var module = { exports: {} }
var exports = module.exports
/* esbuild CJS output */
return module.exports
},
})

目录

参与贡献

欢迎 issue 与 pull request。提交 PR 前请先跑 pnpm verify，并保持 smoke 测试
对「余额行与账户行对齐」的覆盖。

许可证

MIT © ECHOUniverse

声明

非官方社区插件，与 DeepSeek 无隶属或背书关系。它通过 DSH 已有的账户 remote API
读取余额，凭证由 DSH 持有，本插件不会另行存储或传输。使用风险自负。