dsh-balance

DeepSeek Harness 插件：在聊天窗口右上角实时显示 DeepSeek 账户余额 与 token 用量，并支持在界面里直接配置凭据。

装一个插件，聊天时随时看到「账户还剩多少钱、本次 / 累计用了多少 token」。

功能

• 💎 余额徽章：聊天窗口右上角嵌入紧凑徽章（💎 ¥余额 · 本会话/本机累计），一眼看到余额与用量。
• 📊 详情下拉：点开徽章可看账户余额、可用状态、本次会话与全机 tokens、平台账户本月与历史累计用量。
• ⚙️ 界面内配置：下拉底部直接填 DeepSeek API Key / 平台 userToken，保存即生效，无需命令行。
• 🔄 自动刷新：本机数据 5s 刷新；平台数据 60s 节流；历史累计 12h 磁盘缓存。
• 🔒 凭据安全：密钥写入 DSH 凭据库（~/.dsh/.credentials.yaml，0600 权限），任何接口都不回读明文。

环境要求

• DeepSeek Harness，且有一个 web profile（标准 @deepseek-ai/dsh-web-app 组合即可，不依赖 dsh-worktable）。
• Node.js ≥ 20（与 DSH 运行时一致）。

安装

目标机已有一个 web profile 即可。三种装法任选。

方式 A：一条命令（推荐）

dsh plugin --profile web add https://github.com/liudiw/dsh-balance/releases/latest/download/dsh-balance.tgz

装完重启 dsh web 生效。

若重启后在界面里看不到徽章，先确认 profile 的 dsh.profile.bundles 已包含 dsh-balance（部分版本的 dsh plugin add 只装依赖、不自动登记 bundle）；没有就手动加一行再重启。

方式 B：手动改 profile（最稳）

编辑目标机的 web profile package.json：

// <dsh 安装>/profiles/web/package.json
{
  "name": "dsh-profile-web",
  "private": true,
  "dependencies": {
    // ...原有依赖...
    "dsh-balance": "https://github.com/liudiw/dsh-balance/releases/latest/download/dsh-balance.tgz"
  },
  "dsh": {
    "profile": {
      "bundles": [
        // ...原有 bundle...
        "dsh-balance"
      ],
      "patchReload": "live"
    }
  }
}

然后在目标机执行：

cd <dsh 安装>/profiles/web
pnpm install
# 重启 dsh web（示例：systemctl restart <你的 dsh-web 服务>，
# 或杀掉旧进程后 cd <harness> && nohup dsh web --no-open &）

⚠️ 若 pnpm install 报 ERR_PNPM_MISSING_TARBALL_INTEGRITY（URL 依赖命中 pnpm 缓存时 不写 integrity）：删除 pnpm-lock.yaml，把 dsh-balance.tgz 放到 profile 目录， 依赖改成 "dsh-balance": "file:./dsh-balance.tgz" 再 pnpm install。 （tar 包由 npm pack 产出。）

方式 C：本地 link 开发安装

dsh plugin --profile web add link:/path/to/dsh-balance   # 改代码后重启生效

装完徽章没出现，先对浏览器做一次硬刷新（Ctrl/Cmd+Shift+R）再判断。

首次配置（GUI 完成）

1. 点聊天窗口右上角 💎 徽章 → 下拉底部 ⚙️ 配置凭据。
2. DeepSeek API Key：一般已配置（DSH 跑 LLM 就要用），留空即可；若空则粘贴 sk-...。
3. 平台 userToken：登录 platform.deepseek.com → F12 Console 执行 copy(localStorage.getItem('userToken')) → 取返回 JSON 的 value 字段粘贴。
4. 点「保存配置」，约 10 秒内徽章即显示平台本月 / 累计用量。

密钥写入 DSH 凭据库（~/.dsh/.credentials.yaml，0600 权限），任何接口都不回读明文。

数据来源

数据	来源	说明
账户余额	api.deepseek.com/user/balance	官方公开接口，用 DEEPSEEK_API_KEY
本机 token 用量	DSH 会话日志（assistant/message 的 usage）	本机所有会话，启动时回放历史
平台本月用量	platform.deepseek.com/api/v0/usage/amount	平台私有接口，需 DEEPSEEK_USER_TOKEN
平台累计用量	逐月求和（2024-01 起）	12h 磁盘缓存

未配置 DEEPSEEK_USER_TOKEN 时，插件只显示余额与本机用量（下拉里有「去配置」入口）。

服务端接口

HTTP	路径	说明
GET	/api/balance	余额 + 本机 / 平台用量快照
GET	/api/balance/config	两个凭据的配置状态（configured / writable），不含值
POST	/api/balance/config	写入 {apiKey?, userToken?, unset?: [...]}；须带 x-dsh-balance-config: 1 头（跨源页面无法伪造，防 CSRF）

写接口把值交给 DSH credentials seam（set / unset 落到 ~/.dsh/.credentials.yaml 的 refs:），每轮请求重新解析——保存后无需重启即生效。API Key 若由只读来源（如环境变量）提供，writable: false，界面会提示且拒绝改写。

常见问题

• 徽章不出现：先硬刷新浏览器；仍不出现，确认插件已装、dsh web 已重启，且 profile 的 dsh.profile.bundles 含 dsh-balance。
• pnpm install 报 ERR_PNPM_MISSING_TARBALL_INTEGRITY：见「方式 B」下的说明，改用本地 file: 依赖。
• 整个 dsh web 起不来：多半是 profile 里 dsh-balance 的依赖无法解析（例如 link: 目标目录被移走 / 改名）。恢复目录或改用 tgz 安装。
• 改了 profile 却不生效：确认改的是运行中 DSH_HOME 下的 profile。默认是 ~/.dsh；有的机器设置了 DSH_HOME（如 ~/.config/dsh），要改那一个。
• 平台用量一直显示「—」：检查 userToken 是否已配置 / 过期，在徽章下拉里重填一次。

开发

# 本地开发安装（link 方式，改代码后重启生效）
dsh plugin --profile web add link:/path/to/dsh-balance
node --check lib/index.js && node --check lib/client.js

目录结构：

dsh-balance/
├── package.json       # dsh.bundle 声明 + 客户端注入
├── cordis.patch.yml   # 插件行
└── lib/
    ├── index.js       # 宿主端：余额 + 用量 + 平台接口 + /api/balance/config
    └── client.js      # 浏览器端：头部徽章 + 详情下拉 + 凭据配置面板

发布新版本：

npm pack                                   # 产出 dsh-balance-<version>.tgz
cp dsh-balance-<version>.tgz dsh-balance.tgz  # 上传用版本无关名（供 latest/download 使用）
gh release create v<version> dsh-balance.tgz --generate-notes

资产用版本无关名 dsh-balance.tgz 上传，这样各机器 .../releases/latest/download/dsh-balance.tgz 永远拿到最新版，安装配置无需改动。

License

MIT