pythonshiyi/dsh-plugin-balance

dsh-plugin-balance

DeepSeek Harness 网页端余额显示插件 —— 在会话头部右侧实时显示账户余额，每 60 秒自动刷新，点击立即刷新。

License
GitHub release
dsh-plugin

功能特性

- 会话头部右侧显示余额徽标（可键盘聚焦的按钮）：

[余额 ¥42.87]

- 每 60 秒自动刷新（intervalSeconds 可调），点击立即刷新
- 悬停明细：总余额、充值余额、赠送余额、账户可用状态、自动刷新间隔、最近更新时间，以及最近的刷新错误
- stale-while-revalidate：刷新失败时保留上次成功值（变淡显示，悬停见原因），不会闪红；只有从未成功过才显示红色 余额--
- 错误细节：curl 带 -f，HTTP 401/402/429/5xx 会以非零退出码暴露，悬停直接看到具体原因（凭证缺失、key 失效、余额不足、限流、网络失败等）
- 多语言：优先跟随 Harness 界面语言（zh/en），无 locale 服务时回退中文
- 千分位：金额按 toLocaleString 格式化（如 1,234.50）

工作原理

| 环节 | 说明 |
| --- | --- |
| 接口 | Host 半段在 Harness 网页服务器上提供 GET /dsh-balance（同源，无 CORS 问题） |
| 凭证 | 优先 credentials 服务，其次 DEEPSEEK_API_KEY 环境变量（preferEnv: true 可交换顺序） |
| 供应商配置 | 优先级：行配置 > llm-deepseek 设置命名空间 > 默认（DEEPSEEK_API_KEY、https://api.deepseek.com） |
| 请求 | subprocess + curl（-sS -f，HTTP ≥400 非零退出）→ GET {baseURL}{balancePath}，携带 Authorization: Bearer （argv 直传，15 秒超时） |
| 缓存 | 成功缓存 ttlMs（默认 55s，≥ 客户端轮询间隔使缓存真正生效）；失败缓存 failTtlMs（默认 10s，恢复更快）；并发请求单飞去重 |
| 槽位 | conversation.session.header.utilities（id: balance，order: 5） |

兼容性：面向提供 GET /user/balance 接口的 DeepSeek 兼容供应商（官方 DeepSeek API 形态）。自定义网关若未暴露该端点，会在悬停提示中显示失败原因（含 HTTP 状态）。

安全说明：默认 Authorization 头经短暂存活的 curl 进程参数传递（≤15 秒、本机进程），适合单用户机器；更严格的环境可设置 headerViaFile: true 将请求头写入临时文件（curl ≥ 7.55），请求结束即删除。

行级配置

cordis.patch.yml 中该行可携带 config（均可省略，使用默认值）：

- insert:
- id: plugin-balance
name: 'dsh-plugin-balance'
config:
ttlMs: 55000          # Host 成功缓存 TTL（毫秒，默认 55000）
failTtlMs: 10000      # Host 失败缓存 TTL（毫秒，默认 10000）
timeoutMs: 15000      # curl 超时（毫秒，默认 15000）
baseURL: https://api.deepseek.com   # 覆盖供应商地址
apiKeyEnv: DEEPSEEK_API_KEY          # 覆盖 key 环境变量名
balancePath: /user/balance           # 覆盖余额路径（须以 / 开头）
headerViaFile: false                 # true 时经临时文件传 Authorization（curl ≥ 7.55）
preferEnv: false                     # true 时优先使用环境变量中的 key
intervalSeconds: 60                  # 客户端轮询间隔（秒，≥5，须小于 ttlMs 才有缓存意义）

环境要求

- DeepSeek Harness web 版（dsh --profile web）
- 系统 PATH 中存在 curl（Windows 10+ 与多数 Unix 系统自带）
- 已配置 API Key：模型 页面（credentials 服务）或 DEEPSEEK_API_KEY 环境变量

安装

方式一：npm（发布后可用）

cd ~/.dsh/profiles
npm install dsh-plugin-balance

方式二：本地目录或 Git 仓库

cd ~/.dsh/profiles
npm install /path/to/dsh-plugin-balance
或：npm install https://github.com/pythonshiyi/dsh-plugin-balance

然后注册到你的 profile 补丁，例如 ~/.dsh/profiles/web/cordis.patch.yml：

- insert:
- id: plugin-balance
name: 'dsh-plugin-balance'
重启应用（dsh --profile web）并刷新页面即可生效。

卸载

从 cordis.patch.yml 删除该行，或直接禁用：

- id: plugin-balance
name: 'dsh-plugin-balance'
disabled: true

重启并刷新。

常见问题

显示 余额--？ 这是从未成功获取过余额时的初始错误态（之前成功过则保留旧值并变淡）。悬停查看具体原因：未找到凭证（请在 模型 页面配置 API Key 或设置 DEEPSEEK_API_KEY 环境变量）、HTTP 401（key 失效）/ 402（余额不足）/ 429（限流）/ 5xx、curl 退出码（网络/证书问题）、响应解析失败（网关未暴露余额端点）。

余额多久更新一次？ 浏览器每 intervalSeconds（默认 60 秒）拉取一次；Host 成功缓存 ttlMs（默认 55s，≥ 轮询间隔，缓存真实生效）、失败缓存 failTtlMs（默认 10s），并发请求单飞去重，避免重复请求供应商接口。

为什么悬停里会显示“刷新失败”但数字还在？ 这是 stale-while-revalidate：刷新出错时保留上次成功值（变淡），并在悬停中同时给出错误原因和上次更新时间，点击可立即重试。

兼容范围

开发和验证版本：

- DeepSeek Harness 0.1.0-rc.6（web profile）
- curl ≥ 7.55（Windows 10+ 自带；headerViaFile: true 需要该版本以支持 -H @file）

支持与品牌

公众号：十一AIGC —— AI 工具评测与教程，第一时间获取本插件更新与更多 DeepSeek Harness 玩法。

如果本项目对你有帮助，欢迎 ⭐ Star，并关注公众号「十一AIGC」。

License

MIT