dsh-token-balance ⛽ 星际燃料舱

August 26, 2026 · View on GitHub

DSH（DeepSeek Harness）Web 插件：把 DeepSeek 官方 API 余额实时显示为会话头部的一个科幻「星际燃料舱」（HUD 风格）， 并给出按当前模型估算的剩余 token 数，内置一键充值入口。包含：实时余额 / 剩余 token 估算 / 自适应油箱 / 燃料液位仪表 / 一键充值 / 历史峰值。

星际燃料舱演示

AI 可读摘要（AI summary）

dsh-token-balance 是一个 DeepSeek Harness（DSH）web 插件，在对话会话头部渲染一个科幻风格的燃料舱徽标，实时显示 DeepSeek API 余额，并估算剩余可用 token。核心能力：

  • 实时余额：调用 DeepSeek 官方 /user/balance，显示人民币余额（总储量 / 充值 / 赠送）。
  • 剩余 token 估算：估算剩余=余额÷pricePerMToken×1e6估算剩余 = 余额 ÷ \text{pricePerMToken} \times 1\text{e6}。
  • 自适应油箱（满箱参考）：量程 = 历史见过的最高余额，非固定值。
  • 燃料液位仪表：四档颜色（充足/正常/偏低/告急）+ 扫描线动画 + 状态 LED。
  • 一键充值：直达 DeepSeek 官方充值页（可配置中转站地址）。
  • 实时同步：每 60 秒 + 窗口可见 + 手动刷新。

技术要点：宿主端（Node）通过 ctx.credentials 读取 DEEPSEEK_API_KEY 调用官方余额接口，只经回环 + 同源路由（/dsh-token-balance/api）暴露给前端；客户端为标准 DSH 插件 bundle（window.__ModuleLoader__.load），注入 conversation.session.header.utilities 槽位渲染组件。密钥绝不下发浏览器。

搜索关键词 / Keywords

DeepSeek DeepSeek API DeepSeek 余额 DeepSeek 充值 剩余 token token 余额 token 统计 API 余额 余额监控 配额 用量统计 fuel gauge interstellar fuel 星际燃料舱 燃料舱 余额插件 充值按钮 DSH 插件 DeepSeek Harness 插件 dsh plugin dshmarket web 插件 HUD sci-fi

中文搜索

DeepSeek 余额显示 / 剩余 token 显示 / DeepSeek 充值入口 / token 用量 / 余额监控插件 / DSH 插件市场 / 星际燃料舱 / 燃料徽标 / HUD 插件 / 科幻皮肤

English search

DeepSeek balance / remaining tokens / top up / recharge / DSH plugin / DeepSeek Harness web plugin / token usage / quota monitor / fuel gauge / sci-fi HUD / balance widget

特性

  • 星际燃料舱徽标：会话头部右侧，六边形燃料图标 + 余额 + 估算剩余 token + 呼吸状态 LED
  • 自适应满箱参考：油箱量程 = 历史见过的最高余额（自动记录），充值后量程自动变大，不再是固定值
  • 燃料液位仪表：扫描线 + 刻度 + 发光填充，绿（充足）/ 青（正常）/ 琥珀（偏低）/ 红（告急）四档
  • 详情面板：总储量 / 充值储备 / 赠送储备 / 估算剩余 token / 估算单价 / 满箱参考 / 历史峰值 / 同步时间
  • 一键充值：面板内「加注燃料 · 充值」按钮直达 DeepSeek 官方充值页（第三方中转可配置）
  • 实时同步：每 60 秒自动刷新 + 窗口可见时自动刷新 + 手动刷新
  • 安全：API Key 只在宿主端解析，绝不下发浏览器；余额接口仅限回环 + 同源访问

安装

⚠️ 尚未发布到 npm / 插件市场（仅在 GitHub 提供源码）。dsh plugin add dsh-token-balance 暂时不可用，请用下面的本地手动安装方式。等决定发布后此段会更新为 npm 方式。

方式：本地手动安装（当前唯一方式）

  1. 拿到代码：git clone https://github.com/Mrxiewei/dsh-token-balance（或直接拷贝整个目录）。

  2. 接入目标 profile（如 desktop）：编辑 ~/.dsh/profiles/<name>/package.json， 在 dependencies 加入，并在 dsh.profile.bundles 追加 dsh-token-balance：

    {
  "dependencies": {
    "dsh-token-balance": "file:<仓库的绝对路径>/dsh-token-balance"
  },
  "dsh": {
    "profile": {
      "bundles": ["@deepseek-ai/dsh-base", "dsh-token-balance"]
    }
  }
}

  3. 安装（务必用 pnpm add，而不是 pnpm install）——在 profile 目录：

    pnpm add "dsh-token-balance@file:<仓库的绝对路径>/dsh-token-balance"

    ⚠️ 关键坑：file: 依赖会被 pnpm 复制进 profile 虚拟仓库。改完 lib/ 后 只跑 pnpm install 会显示 "Already up to date" 而不同步新内容；必须用 pnpm add 强制重新解析。

  4. 重启 DSH Desktop 生效（重启会关闭应用进程，会话数据已持久化、自动恢复）。

  5. 验证：刷新后会话头部出现燃料舱徽标；或直接访问 http://127.0.0.1:<port>/dsh-token-balance/api/balance 看返回余额。

插件自带 dsh.bundle.patch（cordis.patch.yml），随 bundle 自动挂载，不要在 profile 的 cordis.patch.yml 里再手动 insert（重复挂载会报 duplicate prefix route）。

🤖 给 AI 助手的安装提示词（AI install prompt）

把下面整段复制给任意 AI 助手，它能独立帮你把这个插件装进 DSH profile：

请帮我在 DeepSeek Harness (DSH) 里安装本地插件 dsh-token-balance（星际燃料舱）。
目标 profile 通常是 desktop（路径 ~/.dsh/profiles/<name>/）。

⚠️ 别踩这些坑（执行前必读）：
- 不要用 `pnpm install` 安装 file: 依赖——它不会同步插件最新内容（报 "Already up to date"）。
  必须用 `pnpm add "dsh-token-balance@file:<插件目录绝对路径>"`。
- 不要在 profile 的 cordis.patch.yml 里手动 insert 本插件——插件自带 dsh.bundle.patch，会随
  bundle 自动挂载；重复 insert 会导致 "duplicate prefix route" 启动失败。
- 如果其它包是靠 cordis.patch.yml insert 挂载但没写进 package.json dependencies（例如
  @floatingsk/dsh-vision），pnpm 会当"游离包"剪掉，导致下次启动崩溃——**先把所有被引用的包
  写进 dependencies 再安装**。
- 改完插件 lib/ 目录后，必须重新 `pnpm add` 同步（pnpm 把 file: 依赖复制进虚拟仓库，不自动更新）。
- 装机后需要重启 DSH Desktop 才生效；重启会关闭应用进程（会话已持久化、会自动恢复）。
  如果你自己跑在 DSH 进程树里，重启会连带中断你的命令——**务必让用户手动重启**，不要自动杀进程。
- 需要 DEEPSEEK_API_KEY（插件经 ctx.credentials 解析）才能读到余额；未配置会显示"未接入"。

安装步骤：
1. 确保插件代码在本地：若不在，用 `git clone https://github.com/Mrxiewei/dsh-token-balance` 克隆。
2. 编辑目标 profile 的 package.json：
   - dependencies 加一行 `"dsh-token-balance": "file:<插件目录绝对路径>"`
   - 在 dsh.profile.bundles 数组末尾追加字符串 `"dsh-token-balance"`
3. 在 profile 目录执行 `pnpm add "dsh-token-balance@file:<插件目录绝对路径>"`。
4. 让用户手动重启 DSH Desktop。
5. 验证：
   - GET http://127.0.0.1:<port>/dsh-token-balance/api/balance 应返回 {"ok":true,...}
   - 会话头部右侧出现「星际燃料舱」徽标。

可选配置（cordis.patch.yml 的 config）：pricePerMToken / tankFloorYuan / baseURL / apiKeyEnv / rechargeUrl。

配置

在 profile 的 cordis.patch.yml 插入行中（或 bundle 的 insert 行）可配置：

- insert:
    - id: dsh-token-balance
      name: 'dsh-token-balance'
      config:
        # 余额接口基础地址（默认官方；DEEPSEEK_BASE_URL 环境变量优先）
        baseURL: https://api.deepseek.com
        # 读取哪个凭据引用（默认与 LLM 适配器一致）
        apiKeyEnv: DEEPSEEK_API_KEY
        # 估算剩余 token 用的混合单价（元 / 百万 token）
        pricePerMToken: 4
        # 自适应油箱下限兜底（元，默认 10）
        tankFloorYuan: 10
        # 充值页地址（默认由 baseURL 推导：api.deepseek.com → platform.deepseek.com/top_up）
        rechargeUrl: https://platform.deepseek.com/top_up

不配置则全部使用默认值。

⚠️ 注意事项（踩坑记录）

插件改完后必须重新同步到 pnpm 虚拟仓库

file: 依赖会被 pnpm 复制进 profile 的虚拟仓库（不是链接），改完 lib/ 后直接重启不会生效。 需要强制重新解析：

pnpm add "dsh-token-balance@file:<相对路径>"

只跑 pnpm install 会显示 "Already up to date" 而不同步内容。

重启会杀掉当前应用进程

插件接入 profile 后需要重启 DSH Desktop 才生效。重启会关闭当前正在运行的 DSH Desktop 进程（会话数据已持久化，重启后自动恢复），请在重启前保存好手头的工作。不要用脚本在后台 杀进程重启——DSH 的工具命令跑在应用进程树里，应用被杀时它们也会被一起终止，容易造成失联。

小心「游离包」被 pnpm 剪除

在 profile 里执行 pnpm install 时，pnpm 会把未在 package.json dependencies 中声明、 仅靠 cordis.patch.yml insert 挂载的插件当作游离包直接剪掉，导致下次启动时插件树加载失败、 应用崩溃。务必确认所有被引用的包都已写入 dependencies（包括 patchedDependencies 引用的包）， 再执行 pnpm install。

API Key 安全

  • 插件通过 ctx.credentials 解析 DEEPSEEK_API_KEY（或配置的引用），密钥只在宿主端使用
  • 余额接口只接受回环地址 + 同源请求（sec-fetch-site / Origin 校验）
  • 仓库中不包含任何凭据；若使用第三方中转站，注意中转站自己的安全要求

数字口径

  • 剩余 token 是估算值：官方只提供人民币余额，估算剩余 = 余额 ÷ pricePerMToken × 1e6
  • 余额单位是人民币（元），与模型真实价格存在偏差，可用 pricePerMToken 微调

开发

# 语法检查
node --check lib/index.js
node --check lib/client.js

# 余额接口冒烟测试（需要本机 DSH 凭据，仅开发者使用）
node scripts/smoke-balance.mjs

License

MIT

更新日志

CHANGELOG.md