前言¶

用 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              # 单次上游请求超时（毫秒）

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 页面同源可访问。

工作原理（简表）¶

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 目录页。