dsh-balance
English | 中文
English
A DeepSeek Harness Web plugin that displays your DeepSeek API balance in the sidebar footer.
show balance
The plugin is currently 0.2.0 and requires DeepSeek Harness >=0.1.2-rc.1 <0.3.0-0.
Features
- Displays CNY and USD balances next to the sidebar settings area.
- Reads the balance through the official DeepSeek API endpoint.
- Keeps the API key on the server side; the browser only receives normalized balance data.
- Refreshes the balance automatically every 60 seconds.
- Shows
-- while loading, when no balance is available, or when the request fails.
- Supports installation directly from a GitHub repository.
Requirements
- DeepSeek Harness
>=0.1.2-rc.1 <0.3.0-0 (verified against 0.2.0-rc.2)
- The
web profile
- A configured
DEEPSEEK_API_KEY
Installation
Install directly from GitHub
dsh plugin --profile web add github:eka3os/dsh-balance
Restart the Web profile after installation:
dsh web
dsh plugin installs the package into the selected profile and automatically activates it as a profile bundle because this package declares dsh.bundle.patch.
Configuration
The plugin uses the DEEPSEEK_API_KEY credential reference. Configure the key through the DeepSeek Harness credentials/settings UI when available. You can also provide it through the launch environment for a single run:
DEEPSEEK_API_KEY=sk-your-key dsh web
For a managed local credential, add the key to $DSH_HOME/.credentials.yaml:
DEEPSEEK_API_KEY: sk-your-key
Do not commit API keys or credential files to Git.
How it works
- The Host plugin registers
GET /api/dsh-balance.
- The route resolves
DEEPSEEK_API_KEY through DSH credentials.
- The Host requests
https://api.deepseek.com/user/balance with a server-side Bearer token.
- The client plugin renders the returned CNY/USD balances in the sidebar footer.
- The client repeats the request every 60 seconds while the wide sidebar is visible.
Compatibility notes
Version 0.2.0 adapts the plugin to the DSH 0.2 client layout:
- The
slots service moved from the retired @deepseek-ai/dsh-client-runtime package (last release 0.1.1-rc.2) to @deepseek-ai/dsh-client-ui-renderer, so the peer declarations and dsh.client.inject list now name the renderer. DSH 0.2 refuses to load any bundle whose @deepseek-ai/dsh-* peers cannot be satisfied, which is what produced the skipping profile bundle … is incompatible with dsh 0.2.0-rc.2 error.
dsh.client.inject is the arrival-order contract: every listed package is loaded before this plugin's bundle, so slots is always available when apply() runs.- The sidebar footer markup, stylesheet hooks, and layout class names are unchanged between 0.1.7-rc.2 and 0.2.0-rc.2, so the rendered result is identical.
Run npm run check to verify both halves against the installed DSH contract (host route behavior plus client slot registration).
API endpoint
| Method | Path | Description |
|---|
GET, HEAD | /api/dsh-balance | Returns the current DeepSeek API balance. |
Successful responses contain the following shape:
{
"isAvailable": true,
"balances": [
{ "currency": "CNY", "totalBalance": "10.00" },
{ "currency": "USD", "totalBalance": "1.00" }
]
}
The route returns 503 when the credential is missing and 502 when the DeepSeek API cannot be reached or returns an unsuccessful response. Unsupported methods return 405.
GitHub distribution
This plugin is distributed through GitHub only and is not published to npm. Push the repository to GitHub and make sure the built lib/ files and the package files listed in package.json are committed.
License
MIT
中文
一个用于 DeepSeek Harness Web 界面的插件，会将 DeepSeek API 余额显示在侧边栏底部。
show balance
当前版本为 0.2.0，要求 DeepSeek Harness >=0.1.2-rc.1 <0.3.0-0。
功能
- 在侧边栏设置区域附近显示 CNY 和 USD 余额。
- 通过 DeepSeek 官方余额接口获取数据。
- API Key 只在服务端使用，浏览器只接收规范化后的余额数据。
- 每 60 秒自动刷新一次余额。
- 加载中、没有余额或请求失败时显示
--。
- 支持直接从 GitHub 仓库安装。
环境要求
- DeepSeek Harness
>=0.1.2-rc.1 <0.3.0-0（已在 0.2.0-rc.2 上验证）
web profile- 已配置的
DEEPSEEK_API_KEY
安装
直接从 GitHub 安装
dsh plugin --profile web add github:eka3os/dsh-balance
安装完成后重新启动 Web profile：
dsh web
dsh plugin 会将包安装到指定 profile，并根据本包声明的 dsh.bundle.patch 自动将其激活为 profile bundle。
配置
插件使用 DEEPSEEK_API_KEY 作为凭据引用。建议在 DeepSeek Harness 的凭据／设置界面中配置 API Key。也可以在启动时通过环境变量提供，仅对本次运行生效：
DEEPSEEK_API_KEY=sk-your-key dsh web
如果使用 DSH 的本地凭据文件，可以将密钥写入 $DSH_HOME/.credentials.yaml：
DEEPSEEK_API_KEY: sk-your-key
请勿将 API Key 或凭据文件提交到 Git 仓库。
工作原理
- Host 插件注册
GET /api/dsh-balance 路由。
- 路由通过 DSH credentials 服务解析
DEEPSEEK_API_KEY。
- Host 使用服务端 Bearer Token 请求
https://api.deepseek.com/user/balance。
- Client 插件将返回的 CNY/USD 余额渲染到侧边栏底部。
- 侧边栏处于宽布局时，Client 每 60 秒重复请求一次。
API 接口
| 方法 | 路径 | 说明 |
|---|
GET、HEAD | /api/dsh-balance | 返回当前 DeepSeek API 余额。 |
成功响应示例：
{
"isAvailable": true,
"balances": [
{ "currency": "CNY", "totalBalance": "10.00" },
{ "currency": "USD", "totalBalance": "1.00" }
]
}
凭据缺失时返回 503；DeepSeek API 无法访问或返回失败状态时返回 502；不支持的方法返回 405。
兼容性说明
0.2.0 版本适配了 DSH 0.2 的客户端结构：
slots 服务已从被移除的 @deepseek-ai/dsh-client-runtime 包（最后一个版本为 0.1.1-rc.2）迁移到 @deepseek-ai/dsh-client-ui-renderer，因此 peer 依赖声明与 dsh.client.inject 列表现在指向 renderer。DSH 0.2 会拒绝加载任何 @deepseek-ai/dsh-* peer 无法满足的 bundle，这正是 skipping profile bundle … is incompatible with dsh 0.2.0-rc.2 报错的原因。dsh.client.inject 是加载顺序契约：其中列出的每个包都会先于本插件 bundle 加载，因此 apply() 执行时 slots 必定可用。- 侧边栏底部结构、样式钩子与布局类名在 0.1.7-rc.2 与 0.2.0-rc.2 之间没有变化，因此渲染结果保持一致。
运行 npm run check 可针对当前安装的 DSH 契约校验两部分实现（Host 路由行为与客户端 slot 注册）。
GitHub 分发
本插件仅通过 GitHub 分发，不发布到 npm。将仓库推送到 GitHub，并确保已提交 lib/ 构建产物以及 package.json 中列出的包文件。
许可证
MIT
