前言¶
做智能体开发时，DeepSeek 账户余额是个绕不开的问题：余额耗尽，调用直接失败。常见的做法是离开当前工作环境，去平台后台看一眼，或者自己手动调一次 API。dsh-balance 把这件事做成了 DSH 插件：注册一个可被代理调用的工具，同时在 Web UI 的会话输入区常驻显示余额，查询不再打断工作流。
下面介绍这个插件的定位、功能、安装配置和注意事项。
这是什么¶
dsh-balance 由 qiuyongjin 维护，当前版本 0.2.0，采用 MIT 许可证。它调用 DeepSeek 的 /user/balance API 查询账户余额，同时覆盖工具和界面两侧：headless 环境下作为工具供代理调用，Web 环境下在会话输入区常驻显示。
实现上是 TypeScript 双面开发（node half + client half），运行期零依赖——@deepseek-ai/* 依赖在构建时内联，唯一的 peerDependencies 是 react ^18.2.0。
核心功能¶
dsh_balance 工具¶
节点侧注册名为 dsh_balance 的工具，调用 DeepSeek GET /user/balance，返回账户可用状态与各币种余额明细——每个币种下分总余额、赠送余额、充值余额三项。headless 和 web 两种组合下都可用。
Web UI 余额入口¶
Web 环境下，插件填充官方 conversation.input.right slot：一个按钮常驻在会话输入区，直接显示当前总余额；点击展开明细卡片，内容包含可用状态、各币种明细和更新时间，支持手动刷新。
余额端点¶
节点侧经可选的 webServer 后端（通过 ctx.inject 等待就绪）暴露一个 JSON 端点，供浏览器拉取：
GET /plugins/dsh-balance/balance
浏览器只做同源 fetch，headless 组合下该端点不挂载。
凭据解析¶
API key 经 DSH 凭据服务解析，默认引用 DEEPSEEK_API_KEY，可以在 Web 的 Models 设置页直接写入；凭据服务缺席时回退到启动环境变量。每次调用实时解析，改 key 不需要重启，取值方式与官方 dsh-llm-deepseek 一致。
值得注意的设计：API key 只存在于节点侧，浏览器不接触凭据。
取消语义¶
工具执行时合并超时与调用方取消（AbortSignal.any），符合 dsh-tools 的协作取消契约。
安装与启用¶
先安装插件：
dsh plugin --profile web add ./dsh-balance
bundle 层栈变更需要重启才能生效：
dsh --profile web
启动日志出现下面这行即挂载成功：
[dsh-balance] plugin loaded（API key 引用：DEEPSEEK_API_KEY，基地址：https://api.deepseek.com）
重启后，会话输入区工具行右侧（发送按钮前）会出现 🔋 余额入口。
配置¶
默认配置开箱即用。如需覆盖，在 profile 的 cordis.patch.yml 按行 id 覆盖。注意 patch 会整替换 config，覆盖时需要重述全部键：
- id: dsh-balance
config:
apiKeyEnv: DEEPSEEK_API_KEY
baseURL: https://api.deepseek.com
timeoutMs: 10000
三个键的含义：
| 键 | 默认值 | 说明 |
|---|---|---|
apiKeyEnv |
DEEPSEEK_API_KEY |
读取 API key 的凭据引用（POSIX 环境变量名） |
baseURL |
https://api.deepseek.com |
DeepSeek API 基地址 |
timeoutMs |
10000 |
请求超时（毫秒） |
典型用法¶
安装并重启后，有两种用法：
- 看界面：余额按钮直接显示当前总余额，点击展开明细卡片，需要最新数据时手动刷新。
- 问代理：在会话中向代理提问「查询 DeepSeek 余额」，代理会调用
dsh_balance工具返回结果。
验证插件是否正常工作：
- 类型层面运行
pnpm run typecheck； - 在会话中提问「查询我的 DeepSeek 余额」，确认返回账户可用状态与余额明细。
开发与构建¶
如果需要二次开发，常用脚本如下：
pnpm install
pnpm run build # tsc 产出 lib/types + tsdown 产出 lib/index.js / lib/client.js
pnpm run typecheck # 严格类型检查，单一 tsconfig 覆盖 node + client 两侧
pnpm run watch # tsdown 增量重建 client half
lib/ 是构建产物，不要手改；改完源码后需要重新构建。
适用场景与注意¶
适合长期使用 DeepSeek、想随时掌握账户余额的开发者，尤其是已经在用 DSH 插件机制组织工作流的人。几点注意：
- 插件以当前 dsh 进程的权限运行，安装前建议自行检查源码与许可证（本项目为 MIT）。
- 改 API key 不用重启（凭据每次调用实时解析），但安装、卸载这类 bundle 层栈变更需要重启
dsh --profile web才生效。 - headless 组合下没有 webServer，余额端点和 Web UI 入口不可用，只能通过工具查询。
结尾¶
dsh-balance 解决的问题很小但很具体：让余额查询变成常驻信息，不再打断工作流。工具和界面两侧都能用，凭据留在节点侧，装一次即可。
- GitHub：https://github.com/qiuyongjin/dsh-balance
- 社区目录：https://www.skillhub.cn/plugins/qiuyongjin/dsh-balance
社区目录为独立站点，与 DeepSeek、幻方无官方从属关系。
