前言¶
用 DeepSeek Harness（dsh）做开发，通常离不开 DeepSeek API。想知道账户余额还剩多少，一般得离开当前环境、去平台后台查一下。dsh-deepseek-balance 把这件事搬进了 dsh web 界面：余额直接显示在侧边栏底部，鼠标悬停看明细，点击即可强制刷新。下面介绍这个插件的用法和实现。
这是什么¶
dsh-deepseek-balance 是一个 DeepSeek Harness（dsh）插件，由 kyya 维护，当前版本 0.1.0，采用 MIT 许可证。它在 Web 侧边栏底部（设置按钮上方）实时展示 DeepSeek API 账户余额。DSH 的理念是「一切皆插件」，这是一个小而具体的例子。
核心功能¶
- 在 Web 侧边栏底部（设置按钮上方）实时展示 DeepSeek API 账户余额。
- 余额数据由 Node 侧定时拉取，浏览器侧每 30s 轮询；点击指示器可立即强制刷新。
- 状态点颜色指示：绿 = 可用；黄 = 账户不可用；红 = 拉取失败；蓝 = 加载中。
- 悬停显示完整明细：总额 / 赠送 / 充值 / 更新时间。
- API key 每次拉取时经
credentials服务解析，永远不会下发给浏览器。
安装与启用¶
先安装插件，支持从 git 或本地目录两种方式：
# 从 git 安装
dsh plugin --profile web add github:kyya/dsh-deepseek-balance
# 或本地目录方式
dsh plugin --profile web add /绝对路径/dsh-deepseek-balance
注意：dsh plugin 只会装依赖，插件集变更需要重启 dsh web 才生效：
dsh web
重启后打开 http://127.0.0.1:3080，侧边栏左下角即可看到余额指示器。
配置¶
默认读取凭据 DEEPSEEK_API_KEY，来源有三处：~/.dsh/.credentials.yaml、DEEPSEEK_API_KEY 环境变量、或「设置 → 模型」里保存的 key。
如需调整，在 ~/.dsh/profiles/web/cordis.patch.yml 里覆盖。注意这里是覆盖整行 config，需要写全所有字段：
- id: deepseek-balance
config:
refreshMs: 60000 # 后台刷新间隔（毫秒）
apiKeyEnv: DEEPSEEK_API_KEY # 凭据引用名
baseUrl: https://api.deepseek.com
endpoint: /user/balance
工作原理¶
插件分 host 和 browser 两个半边：
| 半边 | 文件 | 职责 |
|---|---|---|
| host（Node） | index.js |
定时 GET <baseUrl><endpoint>（Bearer 鉴权），缓存快照；用 webServer.register 暴露 /deepseek-balance |
| browser | client.js |
向 sidebar.footer.action 插槽注册 React 指示器；轮询 /deepseek-balance，点击带 ?refresh=1 强制刷新 |
余额接口返回形如：
{
"is_available": true,
"balance_infos": [
{
"currency": "CNY",
"total_balance": "123.45",
"granted_balance": "0.00",
"topped_up_balance": "123.45"
}
]
}
is_available 对应状态点的绿 / 黄，balance_infos 里的总额、赠送、充值字段对应悬停明细。
卸载¶
dsh plugin --profile web remove dsh-deepseek-balance
适用场景与注意¶
适合同时在用 dsh web 和 DeepSeek API、希望随时掌握账户余额的开发者。两点提醒：
1、插件以当前 dsh 进程的权限运行，安装前建议检查源码与许可证；
2、覆盖配置时必须写全 config 的所有字段，漏写会导致该字段丢失。
结尾¶
dsh-deepseek-balance 用很小的成本解决了一个高频问题：不离开 dsh web 就能看到 DeepSeek API 余额，且 key 不出 Node 侧。项目地址与社区目录：
- GitHub：https://github.com/kyya/dsh-deepseek-balance
- 目录页：https://www.skillhub.cn/plugins/kyya/dsh-deepseek-balance
目录为社区独立维护，与 DeepSeek / 幻方无官方从属关系。
