dsh-deepseek-balance

A DeepSeek Harness plugin that shows your DeepSeek API balance in the web UI, pinned above the Settings button at the sidebar foot.

快速使用 Quick start

1. 安装插件到 web profile（见下方「Installation」）并重启 dsh web。
2. 打开 Settings → 余额 (Balance)，填入你的 DeepSeek API Key（或在环境变量 DEEPSEEK_API_KEY / Models 页面里配置，见「API key resolution」）。
3. 点 检查余额 (Check balance) —— 显示 Connection OK: <金额> <货币> 即成功。
4. 侧边栏底部（设置按钮上方）随即出现余额小部件：悬停查看货币 / 总余额 / 赠金 / 充值详情，点刷新按钮手动刷新，也可在设置页开启自动刷新间隔与主题色。

Features

• Balance widget above Settings — renders total_balance followed by the currency (e.g. 110.00 CNY) in the sidebar foot, directly above the Settings trigger.
• Hover details — hovering the widget opens an animated popover with the full balance information:
  • currency — 货币，人民币或美元 (CNY / USD)
  • total_balance — 总的可用余额，包括赠金和充值余额
  • granted_balance — 未过期的赠金余额
  • topped_up_balance — 充值余额
• Configurable color — a developer/user setting (Settings → 余额/Balance) changes the balance text and popover accent color; color changes animate smoothly.
• Manual refresh — a refresh button (with a spin animation) fetches the latest balance on demand; an optional auto-refresh interval can be enabled in settings (0 = manual only).
• Transition animations — popover fade/scale, value-change slide/fade, color transitions, refresh spin.
• API key stays server-side — the browser never sees the key. The host half proxies GET <baseURL>/user/balance and returns only public balance fields.

API key resolution

The host resolves the key in this order:

1. Plugin settings — dsh-deepseek-balance.apiKey (Settings → 余额 → API Key, write-only, stored in $DSH_HOME/settings.yaml).
2. Credentials service — the DEEPSEEK_API_KEY reference saved through the web Models page.
3. Environment — the DEEPSEEK_API_KEY environment variable (override the variable name with dsh-deepseek-balance.apiKeyEnv in settings.yaml).

Installation

The plugin ships as a normal out-of-tree dsh plugin package (host half + browser half). Install it into the web profile:

# from the profile directory
dsh plugin --profile web add dsh-deepseek-balance --link <path-to-this-package>

or, manually:

1. Add a loader entry to $DSH_HOME/profiles/web/cordis.patch.yml:

   - insert:
       - id: dsh-deepseek-balance
         name: 'dsh-deepseek-balance'
   

2. Make the package resolvable from the profile (pnpm file: dependency, or a junction into $DSH_HOME/profiles/node_modules).

3. Restart dsh web.

Note: the plugin's dsh.client declaration registers its browser half with the client-modules system, so the plugin-set change takes effect on server restart.

Configuration

All settings live under the dsh-deepseek-balance: section in $DSH_HOME/settings.yaml, or in the Settings → 余额 (Balance) page:

Field	Default	Meaning
apiKey	(empty)	Your DeepSeek API key (write-only; never read back to the browser).
apiKeyEnv	DEEPSEEK_API_KEY	Environment variable / credential reference holding the key.
baseURL	https://api.deepseek.com	API endpoint; GET <baseURL>/user/balance is used.
color	#4d6bfe	Balance text / popover accent color.
refreshIntervalMs	0	Auto-refresh interval in ms (0 = manual refresh only).

Security notes

• The API key never crosses the HTTP boundary: the browser calls the same-origin route /plugins/dsh-deepseek-balance/api/balance, and the host injects the Authorization header.
• The route is read-only (GET), returns no key material, and rejects non-loopback Host/cross-origin Origin headers.
• Settings describe redacts role('secret') fields, so the browser cannot read a stored key back.

其他设备能用吗？(Can it be used on other devices?)

结论：可以，但它是「本机专用」插件 —— 只能在运行 dsh 的那台电脑的浏览器里正常使用。 换到新设备需要做 4 件事，且有一个硬性限制（远程浏览器拿不到余额）。

换到新设备需要做的 4 件事

#	事项	说明
1	安装 DeepSeek Harness	新设备需要装好 dsh 并至少启动过一次 dsh web。
2	让 @deepseek-ai/* 依赖可解析	本包通过 node_modules/@deepseek-ai 解析 dsh 的包。本机是一个 junction（指向 D:\nodejs\node_global\node_modules\@deepseek-ai\dsh\node_modules\@deepseek-ai）—— 这是本机路径，换机后不存在。新设备上要么重建 junction 指向该机的 dsh 安装，要么把本包放进 dsh 工作区用 pnpm 正常安装。
3	注册到 web profile	在 $DSH_HOME/profiles/web/cordis.patch.yml 加入插件条目（见上方「Installation」），或 dsh plugin --profile web add dsh-deepseek-balance --link <此包路径>。
4	配置 API Key	设置页 / 环境变量 / Models 凭据，三选一（见「API key resolution」）。

⚠️ 设置白名单补丁（重要）：dsh 默认只允许 WEB_SETTINGS_NAMESPACES 白名单内的设置命名空间被写入。若新设备没有重新应用补丁（把 dsh-deepseek-balance 加入 @deepseek-ai/dsh-host-apiproxy/lib/index.js 中 WEB_SETTINGS_NAMESPACES 数组），设置页会渲染但所有控件无响应。本机已打补丁（与 dsh-notify 在同一白名单里，补丁代码见 dsh-notify 的 README）。未打补丁时仍可改用环境变量 / Models 凭据提供 API Key，插件其余功能不受影响。

限制：远程浏览器无法使用

• 余额 API 路由做了 loopback 防护（见 lib/index.js）：拒绝非 127.0.0.1 / localhost / [::1] 的 Host 头与跨域 Origin。
• 因此从另一台设备的浏览器访问同一 web UI 时，余额请求会返回 403，小部件只显示「请求被拒绝」。
• 设置页同样仅本机浏览器可写（远程浏览器会提示「远程浏览器无法持久化设置」）。

换机验证清单

• dsh web 启动后，侧边栏底部出现余额入口
• 设置 → 余额 → 填入 API Key → 「检查余额」返回 Connection OK 与金额
• 悬停小部件能看到货币 / 总余额 / 赠金 / 充值四项
• 点刷新按钮数字更新；开启自动刷新后数字定时变化
• （预期行为）用另一台设备的浏览器访问 → 余额显示「请求被拒绝 (403)」

Layout

dsh-deepseek-balance/
├── package.json      # dsh.client declaration + exports ("./client" bundle)
└── lib/
    ├── index.js      # host half: key resolution + balance proxy route + settings
    └── client.js     # browser half: sidebar widget + Balance settings page

The browser half registers into the sidebar.footer.action slot (the seat above the sidebar.settings trigger) and the settings.section slot (id: "balance").

Development

Headless smoke tests (no browser needed) verify the module structure and that both components render without errors:

node test/smoke-test.cjs   # client bundle structure (apply/inject exports)
node test/render-test.cjs  # server-renders the widget + settings page via react-dom

The host half resolves its @deepseek-ai/* imports through a scoped junction (node_modules/@deepseek-ai) pointing at the dsh installation; a normal pnpm install of this package replaces that with real dependency links.