Skip to content

dsh-balance-pill

Verified

dsh-balance-pill · v1.0.1 · MIT · Web UI

A composer-dock balance pill for DeepSeek Harness: wallet balance plus this session's spend, read from the signed-in DeepSeek account.

Install

dsh plugin add dsh-balance-pill

Confirm the layer applied with dsh --profile default --dump-config — see the install guide.

Source

Tags

Creators

Readme

余额条(Balance Pill)

CI npm License: MIT

English | 简体中文

在 DeepSeek Harness 输入框下方的 composer dock 里常驻一行小字:当前登录账户的钱包余额,以及本次会话开始以来钱包减少的金额。

余额条在输入框下方

非官方社区插件,与 DeepSeek 官方无隶属关系,也未获其背书。

预览

输入框下方余额条的文字示意。实际界面会跟随主题与语言。

  ┌─ 输入框 ────────────────────────────────────────────────────────
  │ 随便问点什么…
  │
  │ 缓存命中 0 · 轮次 3        (o) 余额 ¥6.19 · 本次 ¥0.42
  └─────────────────────────────────────────────────────────────────

  [就绪]      (o) 余额 ¥6.19 · 本次 ¥0.42
  [加载中]    (o) 余额 …
  [未登录]    (o) 余额 —
  [错误]      (o) 余额 — (http-503)

  ┌─ 悬停提示 ──────────────────────────────────────────────────────
  │ 充值 ¥6.19 · 赠送 ¥0.00 · 更新于 12:34:56
  │ 自 12:30:02 起累计
  │ 点击刷新
  └───────────────────────────────────────────────────────────────

余额条是一个可聚焦按钮:点击刷新,悬停查看明细和本次累计的起始时间。

显示内容

读数 含义
余额 充值余额 + 赠送余额,折算为同一币种。
本次 本次会话首次读数以来,观察到的钱包减少额累计。
  • 悬停可看到充值/赠送明细、最后更新时间,以及「本次」从何时开始累计。
  • 点击读数立即刷新。
  • 此外每 60 秒、窗口重新获得焦点、以及每轮回复结束后(约 2.5 秒稳定期)自动刷新;两次自动读取至少间隔 15 秒。连续失败时按 120s → 240s → 300s 退避(上限 300s)。
  • 页面重新加载时先显示上一次成功读数,避免输入框下方闪一下空值。

安装

环境要求:

  • DeepSeek Harness Desktop 或 Web,版本 0.2.1-rc.2 至 0.2.x。
  • 已登录 DeepSeek 账户(与账户菜单读取的是同一个钱包)。
  • Host 侧存在 deepseekAccount 服务。桌面版账户栈自带该服务;不包含它的 headless 组合会返回 account-unavailable。

任选一种来源。

从 npm 安装

dsh plugin --profile web add dsh-balance-pill

已发布为 dsh-balance-pill,npm 维护者账号为 jayve-dev。包名不带 scope,安装路径就是包名本身。

从 GitHub 安装

dsh plugin --profile web add github:Jayve/dsh-balance-pill

从本地 checkout 安装

git clone https://github.com/Jayve/dsh-balance-pill.git
dsh plugin --profile web add ./dsh-balance-pill

web 是 CLI Web 应用使用的 profile 名;桌面版通常叫 desktop,替换命令中的 profile 即可:

dsh plugin --profile desktop add dsh-balance-pill

安装后需要重启 Harness 进程(Host 代码改动不是刷新页面就能生效),然后重新加载 Web 页面。确认 bundle 层已经进入配置:

dsh --profile web --dump-config

应能看到 # == dsh-balance-pill 这一层,以及 balance-pill 行。如果插件已列出但界面没有余额条,见故障排查。

卸载

dsh plugin --profile web remove dsh-balance-pill

从本地版本迁移

如果还挂着 @local/dsh-balance-meter 之类的开发行,请先移除它,再安装本插件。否则输入框下方会出现两个余额条;新行 id 是 balance-pill,不会发生配置行冲突,但 dock 条目和轮询会重复。

工作原理

插件分为两半:

  1. Client:在 conversation.composer.dock 槽位注册一个条目,轮询本地 JSON 路由,并把本次会话的累计值保存在 localStorage。
  2. Host:在 Harness Web 服务器上提供 GET /dsh-balance-pill/state,向 Host 侧账户服务读取钱包,只返回聚合后的金额。

浏览器不直接调用账户 Remote,也接触不到令牌、账户 ID 或 Platform 请求头。这样拆分是因为当前桌面版里 Host 侧账户调用正常,但渲染进程调用 account Remote 可能失败;本地路由在 Web 与 Desktop 构建上都更稳定。

路由

GET /dsh-balance-pill/state?locale=<界面语言>&tz=<时区偏移秒数>

只接受环回对端、环回 Host authority 的 GET 请求,响应带 Cache-Control: no-store。

状态码 响应体 含义
200 {"ok":true,"status":"ready","currency":"CNY","recharged":6.19,"granted":0,"total":6.19} 成功读到钱包。
200 {"ok":true,"status":"signed-out"} 没有已保存的 DeepSeek 凭据。
200 {"ok":true,"status":"failed"} Platform 余额查询失败。
403 {"ok":false,"error":"loopback-only"} 非环回对端。
403 {"ok":false,"error":"host-not-allowed"} Host 不是 127.0.0.1、localhost 或 [::1]。
405 {"ok":false,"error":"method-not-allowed"} + Allow: GET 方法不对。
502 {"ok":false,"error":"…"} 账户服务的未预期异常(消息截断到 200 字符)。
503 {"ok":false,"error":"account-unavailable"} 当前组合没有账户服务。

完整路由与账本约定见 docs/architecture.md。

消费口径

插件计量的是钱包,不是 token,也不是价格表,因此适用于任意模型与计费规则。

  • 两次读数之间的余额下降计入「本次」。
  • 充值或赠送只移动基线,不会产生负数消费。
  • 基线与累计值按会话保存在 dsh.balance-pill/v1/<sessionId>。刷新页面不会清零;新会话从零开始。
  • 切换界面语言或时区不会重置账本。
  • 在同一会话中切换账户会沿用上一个账户的基线。需要干净读数时,请退出登录并新建会话,或删除该会话的 localStorage 键。
  • 同一账户并行多个会话时,每个会话都会把其他会话的消费算进自己的「本次」。钱包本身无法区分是哪个会话花的钱。
  • Platform 账单可能延迟结算,读数会相应滞后。
  • 小于 0.01 的金额显示 4 位小数,避免一次很小的请求看起来像免费。
  • 账户同时持有 CNY 与 USD 钱包时只显示一个余额条,优先 CNY。

隐私与安全

  • 路由挂在 Harness Web 服务器上,拒绝非环回对端。
  • Host 头必须是环回 authority(127.0.0.1、localhost 或 [::1])。解析到环回地址的公网域名会被拒绝,从而堵住 DNS rebinding 读取这条路由的路径。
  • 与其它本地插件路由一样,这条路由没有额外认证:同一台机器上的任意进程都能读到余额数字。响应里只有币种金额,没有账户 ID、资料、令牌或流水。
  • Client 只在 Harness 源下的 localStorage 保存最后一次汇总和按会话的账本,不含凭据。
  • 插件不上报遥测。唯一的网络请求是 Host 账户服务发往已配置 DeepSeek Platform 域名的请求,与账户菜单相同。
  • 浏览器 bundle 不加载远程内容,也不使用 eval。

配置

随包提供的 patch 以默认值启用插件,多数用户不需要配置。

clientVersion 是发给 Platform 账户接口的 UI 标识。默认情况下插件上报当前 Web Host 的 release 版本;取不到时回退到本版本测试过的版本。只有组合中隐藏了 clientModules 服务,或需要复现特定 Platform 客户端标识时才需要固定它:

- id: balance-pill
  name: dsh-balance-pill
  config:
    clientVersion: 0.2.1-rc.2

刷新间隔和路由路径是固定值:前者是流量整形常量,后者是安全与兼容性常量,不作为部署配置项。

故障排查

现象 检查
完全没有余额条 bundle 未激活。运行 dsh --profile web --dump-config 确认 dsh-balance-pill 层存在,再重启 Harness 进程并刷新页面。
显示 余额 — 账户未登录,或凭据存储为空。从账户菜单登录。
悬停提示 余额读取失败 看括号里的短错误码。http-503 表示组合里没有 deepseekAccount 服务;http-502 表示 Platform 查询抛错。
数字不变 账单可能延迟。点击余额条强制读取(仍受 in-flight 保护)。
「本次」偏高 同一账户的其它会话正在消费,或同一会话切换过账户。钱包无法归因到具体会话。
403 loopback-only 页面是通过局域网地址打开的。改用 http://127.0.0.1:<端口>/。
403 host-not-allowed 页面是通过解析到本机的非环回域名打开的。改用 127.0.0.1、localhost 或 [::1]。

兼容性

组件 支持范围
DeepSeek Harness >=0.2.1-rc.2 <0.3.0(写入 engines.dsh)
界面 Desktop Web GUI;CLI web profile
账户服务 deepseekAccount(DeepSeek 账户登录)
Node(仅开发) ^22.19.0 或 >=24.0.0

manifest 声明了 engines.dsh,不兼容的 Harness 版本会拒绝加载 bundle,而不是半加载后崩溃。删掉该字段不是受支持的绕过方式;请附上 Harness 版本开 issue。

开发

包没有运行时依赖,也没有构建步骤。

npm test          # node --test:Host 路由、账本、格式化、loader 约定
npm run pack:check

目录:

index.js              Host 路由与钱包汇总
client.js             Client bundle(dock 条目、轮询、账本)
test/host.test.mjs    路由与汇总测试
test/client.test.mjs  账本、存储与格式化测试
docs/                 预览图与架构说明

要在真实 Harness 里调试,在仓库根目录把 checkout 装进你用于 Web GUI 的 profile(不想影响日常配置时请使用一次性 profile):

dsh plugin --profile web add .
dsh web --profile web

Host 改动需要重启进程;Client bundle 改动刷新页面即可。

Client 模块上的 _internals 是测试桥,不是公开 API。它让账本逻辑可以在不启动浏览器或 React 渲染器的情况下被测试。

发布

  1. 更新 CHANGELOG.md 与 package.json 里的版本号。
  2. npm test && npm run pack:check。
  3. 提交、打 vX.Y.Z tag 并发布:
    • 用 jayve-dev npm 账号执行 npm publish --access public
    • 或推送 tag,让 .github/workflows/release.yml 使用仓库的 NPM_TOKEN secret 发布(token 需属于同一账号)。

许可证

MIT © 2026 Jayve