在本地使用 DeepSeek API 进行开发或测试时，确认剩余余额是常见需求。打开网页查询或使用命令行查询都不够直观。dsh-balance 插件通过在 DeepSeek Harness (DSH) 的侧边栏底部添加一个入口，将余额信息直接展示在界面中，紧邻“设置”按钮。
插件简介¶
dsh-balance 是一个由 etony668 维护的微型插件。它利用 DSH 的 sidebar.footer.action 注册位，将余额显示在侧边栏底部，与设置按钮并列。插件会自动读取本地存储的 API 密钥并查询官方接口，将结果缓存并在前端展示。
核心功能¶
- 位置与布局：注册
sidebar.footer.action，紧邻设置按钮。当侧边栏折叠为 56px 高度时，仅显示圆点图标，保持布局整洁。 - 实时数据：读取 DSH 本地凭证（
~/.dsh/.credentials.yaml）中的DEEPSEEK_API_KEY，向api.deepseek.com/user/balance发起请求。数据缓存 60 秒，减少不必要的网络请求。 - 余额预警：当可用余额低于阈值时（默认 ¥2），显示红色样式并带有警告标记。
- 交互详情：鼠标悬停可查看充值/赠送明细、货币单位及最后更新时间；点击图标可手动刷新数据。
- 主题适配：支持中英文切换，并根据 DSH 的主题配置（亮色/暗色）自动调整显示效果。
- 本地优先：API 密钥仅在本地读取，余额数据仅在前端和 DSH 后端之间传递，不会写入磁盘或上报到其他地方。
安装与启用¶
安装步骤¶
推荐使用 DSH 插件管理器安装。请勿手动编辑 profile 的 package.json 来添加依赖，这可能导致插件管理器拒绝更新。
方式一：通过命令行安装（推荐）
dsh plugin --profile web add @etony668/dsh-balance
方式二：从 GitHub 克隆安装
git clone https://github.com/etony668/dsh-balance.git
cd dsh-balance
./install.sh
启用与配置¶
安装后，刷新 DSH 页面（或重启 DSH），侧边栏底部会出现余额入口。确保已在 Settings → Models 中配置了 DEEPSEEK_API_KEY，否则显示为 “Balance unavailable — API key not found”。
注意事项¶
- 不要手动编辑依赖：如果之前已经通过手动编辑
package.json添加了此插件，请先删除手写的条目，然后通过上述命令重新安装。插件管理器会自动写入正确的依赖配置。 - 密钥安全：密钥由 DSH 从本地机器读取，余额仅在 DSH 后端与浏览器之间传递，不会记录在磁盘上。
总结¶
dsh-balance 是一个轻量级、本地优先的余额监控工具。通过在侧边栏直接查看余额，可以更高效地管理 API 使用情况。
