dsh-balance

[English](#english) | [中文](#中文)

<a id="english"></a>

English

A DeepSeek Harness Web plugin that displays your DeepSeek API balance in the sidebar footer.


> The plugin is currently 0.1.0 and requires DeepSeek Harness >=0.1.0-rc.7.

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.0-rc.7
• 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

1. The Host plugin registers GET /api/dsh-balance. 2. The route resolves DEEPSEEK_API_KEY through DSH credentials. 3. The Host requests https://api.deepseek.com/user/balance with a server-side Bearer token. 4. The client plugin renders the returned CNY/USD balances in the sidebar footer. 5. The client repeats the request every 60 seconds while the wide sidebar is visible.

API endpoint

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

---

<a id="中文"></a>

中文

一个用于 DeepSeek Harness Web 界面的插件，会将 DeepSeek API 余额显示在侧边栏底部。


> 当前版本为 0.1.0，要求 DeepSeek Harness >=0.1.0-rc.7。

功能

• 在侧边栏设置区域附近显示 CNY 和 USD 余额。
• 通过 DeepSeek 官方余额接口获取数据。
• API Key 只在服务端使用，浏览器只接收规范化后的余额数据。
• 每 60 秒自动刷新一次余额。
• 加载中、没有余额或请求失败时显示 --。
• 支持直接从 GitHub 仓库安装。

环境要求

• DeepSeek Harness >=0.1.0-rc.7
• 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 仓库。

工作原理

1. Host 插件注册 GET /api/dsh-balance 路由。 2. 路由通过 DSH credentials 服务解析 DEEPSEEK_API_KEY。 3. Host 使用服务端 Bearer Token 请求 https://api.deepseek.com/user/balance。 4. Client 插件将返回的 CNY/USD 余额渲染到侧边栏底部。 5. 侧边栏处于宽布局时，Client 每 60 秒重复请求一次。

API 接口

成功响应示例：

{
  "isAvailable": true,
  "balances": [
    { "currency": "CNY", "totalBalance": "10.00" },
    { "currency": "USD", "totalBalance": "1.00" }
  ]
}

凭据缺失时返回 503；DeepSeek API 无法访问或返回失败状态时返回 502；不支持的方法返回 405。

GitHub 分发

本插件仅通过 GitHub 分发，不发布到 npm。将仓库推送到 GitHub，并确保已提交 lib/ 构建产物以及 package.json 中列出的包文件。

许可证

MIT