dsh-wallet-switcher
在 DSH 输入框底部显示第三方 API 账户余额和今日用量的插件。
插件面向使用 Sub2API 搭建的站点，默认查询：
GET https://hgapi.dieqiyun.top/v1/usage
Authorization: Bearer sk-...
它使用长期 sk- API Key，不使用网页登录会话，因此不会因为网页登录 JWT 的 24 小时有效期而每天要求重新粘贴令牌。
当前版本：0.3.1
功能
- 显示账户余额；
- 显示 Key 是否有效和账户模式；
- 鼠标悬停查看今日请求数、Token 数、原价和折后实付；
- 启动后立即查询，之后每 30 分钟自动刷新；
- 支持 Sub2API 站点的自动发现和手动配置；
- API Key 只保存在 DSH 宿主侧，浏览器不保存完整 Key；
- 余额 URL 强制使用公网 HTTPS，拒绝本机和内网地址。
安装
在 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- 开头。
插件会按 settings.yaml 中 provider 的顺序，选择第一个满足以下条件的 provider：
baseURL 是公网 HTTPS 地址；- 不是 DeepSeek、OpenAI 等官方模型 API 地址；
- 有对应的
apiKeyEnv 和凭据。
自动发现后，插件会查询：
{provider.baseURL}/v1/usage
因此，只要第三方站点是 Sub2API，并且已经作为 DSH provider 配置好，通常不需要在插件面板中填写任何内容。
手动配置
自动发现失败时，点击余额面板右侧的设置按钮（齿轮）。
API Key
填写目标站点的长期 API Key，例如：
sk-xxxxxxxxxxxxxxxx
不要填写浏览器开发者工具中看到的网页登录 JWT，也不要填写 Authorization: Bearer eyJ... 这一类网页登录令牌。
余额接口地址
Sub2API 站点通常填写：
https://你的站点/v1/usage
例如：
https://hgapi.dieqiyun.top/v1/usage
https://cfapi.dieqiyun.top/v1/usage
填入后点击“保存”。Key 会保存到 DSH profile 下的：
<DSH_PROFILE_DIR>/dsh-wallet-switcher/settings.json
如果没有设置 DSH_PROFILE_DIR，默认位置是：
~/.dsh/profiles/web/dsh-wallet-switcher/settings.json
货币单位
“货币单位”是可选项，可以填写 USD、CNY、$ 或 ¥。插件不会自行换算金额，单位应以服务商面板显示为准。
Sub2API 通用性
对于标准 Sub2API 站点，插件假定余额接口返回类似结构：
{
"balance": 61.41163914,
"isValid": true,
"mode": "unrestricted",
"daily_usage": [
{
"date": "2026-09-13",
"requests": 46,
"total_tokens": 6244709,
"cost": 8.7992584,
"actual_cost": 2.1998146
}
]
}
插件也兼容余额字段：
balance
remaining
quota.remaining
如果站点不是 Sub2API，接口路径或返回字段可能不同，不能保证直接兼容。
环境变量
也可以在启动 DSH 前设置：
$env:DSH_WALLET_USAGE_URL = 'https://hgapi.dieqiyun.top/v1/usage'
$env:DSH_WALLET_API_KEY = 'sk-xxxxxxxxxxxxxxxx'
$env:DSH_WALLET_CURRENCY = 'USD'
配置优先级从高到低：
插件面板保存的 settings.json
> DSH_WALLET_* 环境变量或插件配置
> DSH provider 自动发现
> 旧 accessToken 配置（仅当值本身是 sk- Key）
> 默认 https://hgapi.dieqiyun.top/v1/usage
查询失败排查
API Key 无效（401/403）
确认 Key 属于当前余额接口对应的站点。不同站点的 Key 不一定通用。不要把网页登录 JWT 当成 API Key。
余额接口不存在（404）
确认地址是否是：
https://站点/v1/usage
不要填写订阅列表接口、模型聊天接口或网页账户接口。
查询过于频繁（429）
等待一段时间后再刷新。插件默认每 30 分钟查询一次，不会高频重试。
地址被拒绝
插件只允许公网 HTTPS 地址，以下地址会被拒绝：
http:// 地址；localhost、127.0.0.1；10.0.0.0/8、172.16.0.0/12、192.168.0.0/16 等内网地址；- URL 中带用户名或密码的地址。
这是为了避免 DSH 宿主被当作 SSRF 请求跳板。
安全说明
- 浏览器端不再把 API Key 写入
localStorage；升级时会清理 0.2.x 遗留的旧凭据；
- 浏览器只收到余额、用量和打码后的 Key，不会收到完整 API Key；
- 错误响应不会包含完整 Key；
- 不要把 API Key 提交到 Git、截图或聊天记录；
- Key 泄露后，请在对应服务商面板中撤销或重新生成。
开发检查
npm test
npm run check
当前测试覆盖余额解析、URL 安全校验、DSH 配置自动发现、宿主路由、凭据持久化和浏览器端轮询逻辑。
