dsh-deepseek-balance

中文 · English

A dynamic Cordis plugin for DeepSeek Harness: a floating badge at the bottom-right of the Web UI showing your DeepSeek API account balance, refreshed periodically.

一个用于 DeepSeek Harness 的动态 Cordis 插件:在 Web 界面右下角悬浮展示你的 DeepSeek API 账户余额,并定时刷新。

---

中文

这是什么

在 DeepSeek Harness 的 Web 界面(浏览器页面)右下角显示一个余额徽章,查询的是 DeepSeek API Get User Balance 接口。它由 Host 与 Client 两个半边组成:

• Host 半边 负责真正请求 https://api.deepseek.com/user/balance。出于安全考虑,它通过本机子进程直接执行 curl(argv 数组形式,无 shell 注入;不可用时回退到 shell 服务),因此 API Key 始终留在 Host 进程内存中,不会发送给浏览器、不写入磁盘。
• Client 半边 在 shell.overlay 槽注册一个右下角悬浮卡片:未配置时提示输入 sk-… Key;配置后胶囊直接显示总余额,展开卡片可见赠送余额 / 充值余额 / 账户可用状态与更新时间,支持「立即刷新」与「清除 Key」,并每 60 秒自动刷新。

功能

• 右下角悬浮胶囊,不遮挡主界面,不替换任何自带 UI(与现有 toast 并存)
• 首次点击后输入 DeepSeek API Key 即自动查询
• 支持 CNY / USD(优先展示 CNY,其余币种分行展示)
• 绿色/黄色/红色圆点分别表示账户可用、余额不足或不可用、出错或未配置
• 每 60 秒自动刷新;也可手动「立即刷新」
• Key 仅存于本次运行的内存;「清除 Key」立即遗忘

安装(在 DeepSeek Harness 会话内)

这是一个动态 Cordis 插件,通过会话内工具装载,无需改任何部署配置、无需重启:

1. 在 DeepSeek Harness 的对话中,让助手执行动态插件装载流程(cordis_define):
   • code.host = src/host.js 中的函数体
   • code.client = src/client.js 中的函数体
   • 新的 Plugin 建议使用语义前缀 dsbal(Host 会自动分配最终 ID)
2. 对返回的 pluginId/packageId 执行 cordis_run 激活,并在 Web 界面批准 Client 授权。
3. 回到 Web 页面,右下角出现「DeepSeek · 未配置」胶囊 → 点击 → 粘贴你的 DeepSeek API Key(sk-…)→「保存并查询」。

也可以把 src/host.js / src/client.js 交给任何带动态 Cordis 插件能力的助手,要求它原样装载这两个函数体。

使用与安全

• API Key 只保留在本次运行的内存中;停止插件或重启进程后需要重新输入。
• Host 发出的 HTTP 请求使用 Authorization: Bearer <key>,密钥通过受控子进程(argv)传递,不经过 shell 字符串拼接。
• 不会把 Key 回传 UI;Client 只拿到 configured / balances / isAvailable / error / at 等展示字段。
• 如果你的环境没有可用出站通道(无 subprocess/shell 或子进程 TLS 被沙箱拦截),卡片会显示错误信息,不会静默失败。

手动验证

curl -sS -f https://api.deepseek.com/user/balance -H "Authorization: Bearer <YOUR_KEY>"

返回示例(展示字段:币种、总余额、赠送余额、充值余额):

{
  "is_available": true,
  "balance_infos": [
    {
      "currency": "CNY",
      "total_balance": "110.00",
      "granted_balance": "10.00",
      "topped_up_balance": "100.00"
    }
  ]
}

目录结构

dsh-deepseek-balance/
├── plugin.json          # 插件清单:名称、用途、入口、安装提示
├── src/
│   ├── host.js          # Host 半边函数体(直接粘贴到 code.host)
│   └── client.js        # Client 半边函数体(直接粘贴到 code.client)
├── docs/
│   └── ARCHITECTURE.md  # 实现说明与选型
├── package.json
├── LICENSE              # MIT
└── README.md

许可证

MIT © 2026 dsh-deepseek-balance contributors

---

English

What it is

A floating badge at the bottom-right of the DeepSeek Harness Web UI that shows your DeepSeek API account balance, powered by the official Get User Balance endpoint. The plugin has two halves:

• Host half performs the real request to https://api.deepseek.com/user/balance by spawning local curl through a subprocess (argv array — no shell injection; falls back to the shell service). The API key never leaves Host memory, is never sent to the browser and is never written to disk.
• Client half registers a bottom-right card in the shell.overlay slot: before configuration it asks for a sk-… key; afterwards the pill shows the total balance directly, and the expanded card shows granted / topped-up balances, availability and last-update time, with a manual refresh and a “clear key” action. It auto-refreshes every 60 seconds.

Features

• Bottom-right floating pill; does not shadow built-in UI (coexists with existing toasts)
• Enter your DeepSeek API key once to query immediately
• CNY / USD support (CNY preferred; other currencies listed separately)
• Dot color: green = account available, yellow = low/unavailable balance, red = error or not configured
• Auto-refresh every 60 s, plus a manual refresh button
• Key is kept in memory only; “Clear key” forgets it immediately

Install (inside a DeepSeek Harness session)

This is a dynamic Cordis plugin, loaded through the in-session tooling — no deployment config changes, no restart:

1. In a DeepSeek Harness conversation, ask the assistant to run the dynamic-plugin flow (cordis_define):
   • code.host = the function body in src/host.js
   • code.client = the function body in src/client.js
   • Use semantic prefix dsbal for a new Plugin (the Host allocates the final ID)
2. cordis_run the returned pluginId/packageId and approve the Client authorization in the Web UI.
3. Back in the page: click the “DeepSeek · 未配置” pill at the bottom-right → paste your DeepSeek API key (sk-…) → “Save & query”.

Alternatively hand src/host.js / src/client.js to any assistant with dynamic Cordis plugin capability and ask it to load those two function bodies verbatim.

Usage & security

• The key lives only in this run’s Host memory; after stopping the plugin or restarting the process you enter it again.
• Requests carry Authorization: Bearer <key>; the secret is passed via a controlled subprocess argv, never through shell string interpolation.
• The key is never sent back to the UI — the Client only receives display fields (configured / balances / isAvailable / error / at).
• If no outbound channel exists in your environment (no subprocess/shell, or child-process TLS blocked by a sandbox), the card shows the error instead of silently failing.

Manual check

curl -sS -f https://api.deepseek.com/user/balance -H "Authorization: Bearer <YOUR_KEY>"

Layout

dsh-deepseek-balance/
├── plugin.json          # manifest: name, purpose, entrypoints, install hint
├── src/
│   ├── host.js          # Host function body (paste into code.host)
│   └── client.js        # Client function body (paste into code.client)
├── docs/
│   └── ARCHITECTURE.md  # design notes and trade-offs
├── package.json
├── LICENSE              # MIT
└── README.md

License

MIT © 2026 dsh-deepseek-balance contributors