前言¶
用 DSH（DeepSeek Harness）跑对话时，模型调用走的是你在 设置 → Models 里配置的 DeepSeek API Key。余额不足或 Key 失效，往往在请求失败之后才发现。去控制台或官网查余额，又要切出当前界面。
dsh-deepseek-balance 是社区维护者 CowB0ySpike 发布的 客户端 类 DSH 插件：在 Web GUI 输入框下方的 composer dock 里增加一条约 12px 的条目，与 activity、usage 同一行，实时展示当前 Key 对应账户余额；点右侧刷新可立即重查。API Key 只留在 Host 进程内，浏览器只收到余额与状态。
这是什么¶
- 仓库： CowB0ySpike/dsh-deepseek-balance
- 目录页： skillhub.cn 插件条目
- 许可：MIT（
package.json版本为 1.0.0） - 定位：DSH 插件，在 composer dock 显示 DeepSeek API Key 账户余额；读取 DSH 凭据服务里已配置的
DEEPSEEK_API_KEY，无需在插件内再填 Key。
界面示意（来自 README）：
余额 ¥123.45 ↻
核心功能¶
下面能力均来自项目 README，可按需选用。
凭据与隐私
- 开箱即用：使用 Models 页面写入的
DEEPSEEK_API_KEY。 - Host 调用
GET https://api.deepseek.com/user/balance；浏览器只请求同源只读路由GET /deepseek-balance，响应中仅有余额与状态，密钥不下发。
体验与性能
- 成功结果缓存 60 秒，失败结果缓存 5 秒；并发请求合并为一次上游调用。
- 刷新按钮带
?refresh=1可绕过缓存。 - 未配置 Key、Key 无效、网络超时、余额不足等有对应文案与颜色；界面语言跟随 DSH（中英双语）。
实现形态
- 纯 ESM，
client.js通过window.__ModuleLoader__注册，无打包、无额外依赖。 - Host 半部（
index.js）与 Client 半部（client.js）分工见下文「工作原理」。
安装与启用¶
插件以 本地链接包（link:）装进 DSH 的 profile，不依赖 npm 发布。README 未提供 dsh plugin add github:... 一类命令，请按下列步骤操作。
1、克隆仓库到任意目录（路径按你的环境替换）：
git clone https://github.com/CowB0ySpike/dsh-deepseek-balance.git
2、打开 DSH 的 profile 目录（环境变量 DSH_PROFILE_DIR，通常是 ~/.dsh/profiles/<name>），编辑其中的 package.json：在 dependencies 里加入 link: 指向克隆路径，并在 dsh.profile.bundles 中加入包名。
{
"dependencies": {
"dsh-deepseek-balance": "link:D:/path/to/dsh-deepseek-balance"
},
"dsh": {
"profile": {
"bundles": [
"@deepseek-ai/dsh-base",
"@deepseek-ai/dsh-web-app",
"dsh-deepseek-balance"
]
}
}
}
把 D:/path/to/dsh-deepseek-balance 换成实际路径（Windows 可用正斜杠或转义反斜杠）。
3、在 profile 目录执行一次安装，使 node_modules 中的链接生效：
pnpm install
4、重启 DSH。输入框下方出现「余额 …」即表示插件已加载；若显示「未配置 API Key」，到 设置 → Models 填入 DeepSeek API Key。
package.json 里的 dsh.bundle.patch 会指向 cordis.patch.yml，在 profile 中插入插件行（id 为 deepseek-balance）。只要把它加入 bundles，一般不必手写 patch。
配置（可选）¶
全部可调项有默认值，不配置也能用。需要时在 profile 的 cordis.patch.yml 里为 deepseek-balance 追加 config：
- id: deepseek-balance
name: dsh-deepseek-balance
config:
apiKeyEnv: DEEPSEEK_API_KEY # 凭据引用名
baseURL: https://api.deepseek.com
cacheTtlMs: 60000 # 成功结果缓存（毫秒）
timeoutMs: 10000 # 单次上游请求超时（毫秒）
| 选项 | 默认值 | 说明 |
|---|---|---|
apiKeyEnv |
DEEPSEEK_API_KEY |
交给 ctx.credentials 解析的引用名，不是 Key 本身 |
baseURL |
https://api.deepseek.com |
上游地址，可用于自建或代理网关 |
cacheTtlMs |
60000 |
成功结果的缓存时间 |
timeoutMs |
10000 |
上游请求超时 |
cordis.patch.yml 里若已有同 id 条目（仅声明 name），上述写法会覆盖其 config，不会重复插入。
典型用法¶
日常查看
启动 DSH 并配置好 API Key 后，在对话输入框下方 dock 查看余额；默认会走 60 秒内的缓存。
强制刷新
点击条目右侧刷新按钮，或让 Client 请求带 refresh=1 的同源路由：
GET /deepseek-balance?refresh=1
本地调试 Host 路由
在 DSH 本机回环 Web 服务上可直接访问（端口以你当前 DSH 为准）：
GET /deepseek-balance
成功时返回 JSON，例如：
{
"status": "ok",
"ref": "DEEPSEEK_API_KEY",
"isAvailable": true,
"balances": [
{ "currency": "CNY", "total": "123.45", "granted": "0.00", "toppedUp": "123.45" }
],
"fetchedAt": 1790000000000
}
未配置 Key 时 status 为 unconfigured；失败时 status 为 error，code 可能为 CREDENTIALS、UNAUTHORIZED、NETWORK、TIMEOUT、HTTP、RESPONSE、INTERNAL 等。非 GET 请求返回 405；路由不设置 CORS，仅 DSH 页面同源可访问。
工作原理（简表）¶
| 文件 | 作用 |
|---|---|
index.js |
Host：解析凭据 → 请求 /user/balance → 内存缓存 → 注册 GET /deepseek-balance |
client.js |
浏览器：在 conversation.composer.dock 注册组件，fetch 同源路由并渲染 |
cordis.patch.yml |
向 profile 插入插件 bundle patch |
locale/*.json |
设置页与市场中的中英文名称与简介 |
icon.svg |
插件图标 |
Host 通过 inject = ['credentials', 'webServer'] 取得凭据与 Web 载体；Client 通过 inject = ['slots', 'locale'] 注册槽位与词典。改完 index.js / client.js 后可在 DSH 中重载插件或重启 DSH 生效，无单独构建步骤。
适用场景与注意¶
适合谁
- 长期在 DSH Web GUI 里调试、对话，希望一眼确认当前 Key 余额是否充足。
- 已用 DSH profile +
link:方式管理本地插件的开发者。
安全与运行环境
- 插件以当前 DSH 进程权限运行；安装前请自行阅读源码与 MIT 许可证，确认行为符合你的环境策略。
- API Key 仅在 Host 内解析与使用；若将 DSH 暴露到公网，应在前面自行加认证。本项目与 DeepSeek 官方无关，仅为第三方 DSH 插件。
- 社区目录 skillhub.cn 为独立站点，与 DeepSeek、幻方无官方从属关系。
结尾¶
dsh-deepseek-balance 把 DeepSeek 账户余额收进 composer dock，凭据留在 Host、浏览器只看同源只读接口，适合作为 DSH 日常使用的轻量客户端插件。详情与更新见 GitHub 仓库 与 SkillHub 目录页。
