前言¶
在使用 DeepSeek Harness (DSH) 处理第三方 API 请求时，若频繁查看余额或手动切换 Key，会打断工作流。这个插件直接在 DSH 的输入框底部集成状态显示，解决上述痛点。
插件介绍¶
插件名称：mengshang-spec/dsh-third-party-api-balance-wallet
这是一个由 Mengshang-spec 维护的联网工具类插件。它面向使用 Sub2API 构建的第三方 API 站点，在 DSH 界面中实时展示账户余额、Key 有效性及今日用量。插件版本为 0.3.1，采用 MIT 许可证。
核心功能¶
- 状态展示：在输入框底部显示账户余额。
- 有效性检测：显示 API Key 是否有效及当前账户模式。
- 详情悬停：鼠标悬停可查看今日请求数、Token 数、原价和折后实付金额。
- 自动刷新：启动后立即查询，之后每 30 分钟自动刷新一次。
- 配置灵活：支持 Sub2API 站点的自动发现和手动配置。
- 安全存储：API Key 仅保存在 DSH 宿主侧，浏览器端不保存完整 Key，只接收打码后的 Key。
- 地址限制：余额 URL 强制使用公网 HTTPS，拒绝本机地址和内网 IP。
安装与启用¶
在 DSH 终端中执行以下命令安装：
dsh plugin --profile web add github:Mengshang-spec/dsh-third-party-api-balance-wallet
安装或升级后，需要重启 DSH，让宿主和浏览器端插件重新加载配置。
典型用法¶
零配置自动发现¶
如果 DSH 已经配置了目标站点的模型 provider，插件可以自动找到余额地址和 Key。前提是：
~/.dsh/settings.yaml中的 provider 包含baseURL和apiKeyEnv。~/.dsh/.credentials.yaml的refs中有对应的apiKeyEnv。- API Key 以
sk-开头。
插件会按顺序选择满足以下条件的 provider：
* baseURL 是公网 HTTPS 地址。
* 不是 DeepSeek、OpenAI 等官方模型 API 地址。
* 有对应的 apiKeyEnv 和凭据。
自动发现后，插件会查询 {provider.baseURL}/v1/usage。
手动配置¶
自动发现失败时，点击余额面板右侧的设置按钮（齿轮图标）。
- API Key：填写目标站点的长期 API Key（例如
sk-xxxxxxxxxxxxxxxx），不要填写网页登录的 JWT 令牌。 - 余额接口地址：填写 Sub2API 站点的用量接口，通常为
/v1/usage。例如https://hgapi.dieqiyun.top/v1/usage。 - 保存：点击保存，Key 会存入
<DSH_PROFILE_DIR>/dsh-wallet-switcher/settings.json。
环境变量¶
也可以在启动 DSH 前设置环境变量来覆盖配置：
DSH_WALLET_USAGE_URL='https://你的站点/v1/usage'
DSH_WALLET_API_KEY='sk-xxxxxxxxxxxxxxxx'
DSH_WALLET_CURRENCY='USD'
配置优先级从高到低为：插件面板保存 > 环境变量 > 自动发现 > 旧 accessToken 配置 > 默认地址。
适用场景与注意¶
- 适用对象：主要适配 Sub2API 构建的站点。对于非 Sub2API 站点，接口路径或返回字段可能不同，需手动调整。
- 安全机制：浏览器端不再将 API Key 写入
localStorage。升级时会自动清理旧版本遗留凭据。错误响应也不会包含完整 Key。 - 地址限制：为了防止 SSRF 攻击，插件只允许公网 HTTPS 地址，拒绝
http://、localhost、127.0.0.1以及内网 IP。 - 排查建议：若查询失败，首先确认 Key 是否属于当前余额接口对应站点，确认地址格式是否为
/v1/usage，并检查是否因查询过于频繁触发限流（默认 30 分钟刷新一次）。
总结¶
该插件通过在 DSH 输入框底部集成余额查询功能，简化了第三方 API 的管理流程。它支持零配置自动发现和手动配置两种模式，同时注重安全性，确保 Key 仅在宿主侧存储。
