poliucode/dsh-balance

dsh-balance

在 DeepSeek Harness 桌面端侧边栏常驻显示 DeepSeek 账号余额的插件（宿主统一取数 + 浏览器浮层）

待分类balancecordisdeepseek-harness

dsh-balance-hud

在 DeepSeek Harness 桌面端侧边栏底部常驻显示账号余额的插件：余额、今日消费、低余额告警、流速扫光。

包名是 `dsh-balance-hud`，不是 `dsh-balance`。 npm 上的 dsh-balance 是另一位作者的包（最新 0.2.7），它声明了 @deepseek-ai/dsh-credentials ^0.1.0-rc.6 等 peer 依赖，在新版 DSH 上会被兼容性预检判定为不兼容（就是那条「dsh-balance@0.2.7 与 DSH 0.2.1-rc.3 不兼容」的提示）。本包与它无关，请按下面的包名安装。

你看到的 · 它是什么 · 该怎么办 dsh-balance@0.2.7 不兼容 · 第三方的同名包 · 不要安装；改用 dsh-balance-hud dsh-balance-hud · 本插件 · 放心安装

两行：第一行余额，第二行今日消费；点击展开明细。侧边栏折叠时自动收成 36×36 图标，异常状态在数字旁点一个状态点。金额低于阈值（默认 ¥2）时整行转红、换成警示图标并显示「余额不足」：

明细浮层（正常态） · 明细浮层（取数失败，保留上次数字） ·

明细浮层（低余额，账号路由带「去充值」）

侧边栏折叠（图标形态）

1. 它显示什么、放在哪里

位置：侧边栏底部动作区（`sidebar.footer.action`），紧挨「设置」上方。

选择理由：

候选位置 · 结论 sidebar.footer.action ✅ · kind: 'list'（只追加、不抢占别人的坑位）、scope: 'root'（任何会话/任何页面状态都在），owner 还直接给出 wide，折叠时能自动切成图标 conversation.session.header.corner ❌ · single 且已被「右侧栏展开按钮」占用，占用等于替换别人的呈现 shell.leading ❌ · single，已被侧边栏标题控件占用 conversation.input.right ❌ · 与会话强绑定，切到设置页/空态就消失；余额是全局信息

显示内容：

常驻双行：第一行「余额 + 金额」，第二行「今日消费」（没有数据时不留占位噪音）
低余额（默认 < ¥2）：整行转红、图标换成警示三角并缓慢呼吸、金额加粗，浮层顶部出现横幅与「去充值」
余额流速：花得越快，行表面掠过一道蓝色光带（详见 2.1）
状态点（只在异常时出现）：黄 = 显示的是旧数据、红 = 读取失败、灰 = 未登录/未配置
明细浮层：大号余额、今日消费/充值、低余额横幅、各币种明细（金额、赠送/充值拆分）、数据来源徽标、更新时间、手动刷新
取数失败时：保留最后一次成功的数字并明确标注「显示的是上次成功读取的余额」，绝不把余额显示成 0

2. 「实时」是怎么做的

余额只在发生计费调用后才会变，所以刷新由三件事驱动，而不是一味缩短轮询：

装配即读一次 —— 打开界面就有数字；
每个回合结束（session/event 的 turn/end）后 1.2 秒防抖刷新一次 —— 让平台账本先落账，比「把定时器调到 10 秒」更准也更省接口；
后台定时器（默认 60 秒）+ 浏览器侧每 5 秒轮询宿主快照（本地内存，不打上游）、页面重新可见/获得焦点时补一次、用户点「刷新」时走 POST /refresh。

宿主是唯一的取数点：多个窗口/标签页共享同一份快照，不会各拿一个定时器去刷官方接口。

2.1 余额流速与扫光特效

花得越快，行表面掠过一道光带——「余额在流逝」这件事不用数字也能看见：

速率怎么算（宿主侧，src/host/flow.ts，纯函数、可单测）：

在最近 windowSeconds（默认 60s）的采样里取首尾余额，rate = 净减少 / 分钟；
余额上升视为充值/退款 → 窗口重开、速率归零（不会算出「负消耗」）；
采样跨度不足窗口一半（且至少 10s）时不报速率——宁可不演，也不给假数据；
两次读数间隔 > 30 分钟视为断档（睡眠/关机），不把停机时间算成消费；
速率做 EMA 平滑；整个窗口无消费时按 ×0.25 快速衰减，停手后特效不会拖太久；
档位切换有 holdMs（默认 8s）保持期，避免采样抖动导致闪烁。

三档只差三个参数（宽度 / 周期 / 强度），光带 = 品牌蓝（--dsw-alias-state-business-primary）+ 白色高光核心，纵向渐隐后像一道光扫过：

档位 · 速率下界（CNY） · 光带宽度 · 周期 L1 慢 · 0.02 /min · 28% · 4.6s L2 中 · 0.15 /min · 32% · 2.8s L3 快 · 0.60 /min · 36% · 1.8s

约束：

只在 status === 'ready' 时出现；stale / failed / loading 一律不演，避免暗示「这是实时数据」；
低余额时扫光自动换成告警红（--dsw-alias-state-error-primary），红色始终只属于「余额不足」；
侧边栏折叠时同一条光带跑在 36×36 图标上；
prefers-reduced-motion: reduce 下整条关闭（余额变化本身仍然可见）；
纯 CSS：一个伪元素 + transform 动画，零 JS 循环、零额外 DOM、不挡点击。

配置（可省）：

flow:
  enabled: true
  windowSeconds: 60
  holdMs: 8000
  thresholds:          # [L1, L2, L3] 的速率下界（元/分钟）
    CNY: [0.02, 0.15, 0.60]
    USD: [0.003, 0.02, 0.09]

速率数值本身不在界面上显示（产品决定），但保留在契约里便于调试与后续扩展。

3. 数据来源

模式 · 行为 auto（默认） · 先查已登录的 DeepSeek 账号（ctx.deepseekAccount.getBalance）；未登录/读取失败再退回 API Key 路由（GET {baseUrl}/user/balance，Bearer） account · 只查账号余额 api-key · 只查 API Key 余额

账号服务与凭据服务都是软取：没装账号插件、没配 Key 时插件照常装配，只是如实显示「未登录 / 未配置」并告诉用户去哪里处理。
凭据只经 DSH 的 credentials 服务解析（引用名默认 DEEPSEEK_API_KEY），不读配置文件、不进日志、不出进程。
响应解析采取「非法即失败」：字段缺失、金额不是数字、balance_infos 为空一律报错，不补 0（0 余额和读不到余额是两件事）。

今日消费的口径

DeepSeek 没有向本地暴露逐笔账单的接口（DSH 设置里的「用量」只是个跳转链接），所以今日消费用余额变动推算：

相邻两次读数余额减少 → 计入今日消费；
相邻两次读数余额增加 → 计入今日充值/退款（单独显示，不冲抵消费，所以「充 100 花 2」显示消费 2、充值 100）；
跨天（默认按北京时间，可配 dayTimeZone）→ 重置基准；
账本落在 $DSH_HOME/dsh-balance/ledger.json，重启后当天数据不丢；只在插件运行期间观测，关掉应用的时间段没有读数。

已知边界：充值恰好抵消消费发生在同一次读数间隔内时无法区分方向（余额本身不带方向信息）。这是该口径的固有上限，换来的是不依赖任何私有接口、也不需要硬编码价目表。

状态取值：

loading        首次读取中
ready          正常
stale          曾经成功、最近一次失败（保留旧数字 + 错误说明）
signed-out     账号未登录且没有其它凭据
no-credential  完全没有可用凭据
failed         读取失败且没有可回退的数据

4. 配置

在 profile 的 cordis.patch.yml 里按 id: dsh-balance-hud 覆盖即可（bundle 自带一层默认值）。全部可省略：

配置项 · 默认 · 说明 source · auto · auto / account / api-key apiKeyRef · DEEPSEEK_API_KEY · API Key 路由使用的凭据引用名 baseUrl · https://api.deepseek.com · 官方接口根地址（可指向代理，允许带路径前缀） refreshIntervalSeconds · 60 · 宿主后台刷新间隔，夹紧到 15–3600 pollIntervalSeconds · 5 · 下发给浏览器的轮询间隔，夹紧到 5–600 requestTimeoutMs · 15000 · 单次 HTTP 超时，夹紧到 3000–60000 locale · zh-CN · 账号接口要求的调用方语言（只影响服务端文案） displayCurrency · auto · 常驻行显示哪个币种：auto / CNY / USD showInRail · true · 侧边栏折叠成图标栏时是否仍显示 todaySpend · true · 是否统计并展示今日消费 lowBalanceThresholds · { CNY: 2, USD: 0.3 } · 低余额告警阈值（币种 → 金额），0 表示该币种不告警；只写关心的币种 dayTimeZone · Asia/Shanghai · 计算「今天」用的时区（DeepSeek 按北京时间计费） flow · 见 2.1 · 流速扫光：enabled / windowSeconds / holdMs / thresholds debug · false · 输出刷新来源等调试日志（不含凭据）

示例：

- id: dsh-balance-hud
  name: 'dsh-balance-hud'
  config:
    source: api-key
    displayCurrency: USD
    refreshIntervalSeconds: 30

5. 安装

三种方式任选一种。装完需要重启 DeepSeek Harness（宿主半侧在启动时装配；只更新客户端的话页面会热更新）。

5.1 在 DSH Desktop 里搜索安装（最省事）

打开 DeepSeek Harness 桌面端 → 左侧「插件」；
点「安装插件」，在搜索/输入框里填包名 `dsh-balance-hud`；
选中后安装，按提示重启。

搜索走的是 npm registry。如果搜到 dsh-balance（不带 `-hud`），那不是本插件：它属于第三方作者，

声明了 @deepseek-ai/dsh-credentials ^0.1.0-rc.6 等 peer 依赖，在新版 DSH 上会被兼容性预检判定为不兼容

（即「dsh-balance@0.2.7 与 DSH 0.2.1-rc.3 不兼容」那条提示），不要安装。

可直接粘贴到「按名称安装」输入框的地址：

来源 · 地址 npm（推荐） · dsh-balance-hud GitHub 仓库 · github:poliucode/dsh-balance GitHub Release 附件 · Releases 里的 dsh-balance-hud-x.y.z.tgz

5.2 命令行安装

# npm（发布后可用）
dsh plugin --profile web add dsh-balance-hud

# GitHub 仓库：pnpm 会执行 prepare 构建，首次需按提示 allowBuilds 一次
dsh plugin --profile web add github:poliucode/dsh-balance

# Release 里的预构建 tarball：不需要批准任何构建脚本，推荐给他人用
dsh plugin --profile web add ./dsh-balance-hud-0.4.0.tgz

一般是 web。桌面端 profile 是 desktop`，但它被 Electron 独占（CLI 会直接拒绝），请用 5.1 的界面安装，或用 5.3 的脚本。

5.3 本机开发：把仓库链接进 desktop profile

node scripts/install.mjs                      # 默认 profile = desktop，$DSH_HOME=~/.dsh
node scripts/install.mjs --profile <名字>      # 其它 profile
node scripts/install.mjs --dry-run            # 只看会改什么
node scripts/install.mjs --uninstall          # 移除

脚本只做最小改动，并且可回退：

首次安装时把 profiles//package.json 备份为 package.json.bak-dsh-balance-hud；
在 dependencies 里加一条 "dsh-balance-hud": "link:"（以后无论谁跑 pnpm install 都不会丢）；
在 dsh.profile.bundles 末尾追加 dsh-balance-hud；
在 profiles//node_modules/dsh-balance-hud 建一个指向本仓库的 junction。

为什么不用 dsh plugin --profile desktop add ...：desktop profile 被 Electron 独占，而且 dsh plugin

会驱动 pnpm 重新解析整个 profile 依赖，可能顺带升级你已装的其它插件。脚本只动本插件需要的三处。

5.4 打包与发布

pnpm release                                                    # 构建 + 产出 dsh-balance-hud-<version>.tgz
npm login   --registry https://registry.npmjs.org               # 首次发布前登录
npm publish --registry https://registry.npmjs.org               # 发布到官方 npm

本机默认 registry 是 registry.npmmirror.com（只读镜像，不能发布），所以显式加 --registry。

发布成功后包页是 https://www.npmjs.com/package/dsh-balance-hud ，

桌面端「插件 → 安装」里搜 dsh-balance-hud 就能直接装。

发布前建议先 npm publish --dry-run 核对内容（本包 files 只含 lib/、cordis.patch.yml、README.md、docs/）。

6. 验证

pnpm install
pnpm verify        # tsc --noEmit + 99 个单测 + 构建 + 产物契约检查

GitHub Actions 在每次 push / PR 上跑同一条命令（.github/workflows/verify.yml）。

scripts/verify-bundles.mjs（pnpm verify 的最后一步）只检查构建产物，因为 DSH 实际加载的就是产物：

package.json 的 dsh.bundle.patch / dsh.client / exports 是否齐全，指向的文件是否存在；
宿主产物是否只依赖 `node:` 内置模块、是否真的导出 apply/inject/name；
客户端产物是否没有顶层 import/export、是否用包名登记了 factory；
用假 ctx 跑一遍 apply()：宿主能否注册出 /dsh-balance 路由并回 JSON（200/404/405），客户端能否注册进 sidebar.footer.action。

真实进程端到端（本次已跑通）

scripts/verify/ 里留了可复用的道具，用临时 DSH_HOME + 假余额接口跑真实宿主，不接触真实凭据：

# 1) 假接口（按官方 GET /user/balance 的响应形状）
node scripts/verify/mock-balance.mjs 6398

# 2) 用临时 profile 启动一个隔离实例（profile 里把 baseUrl 指向假接口、apiKeyRef 指向假 Key）
DSH_HOME=<临时目录> DSH_BALANCE_TEST_KEY=sk-mock \
  dsh --profile verify --no-open --port 6399

# 3) 断言：boot graph 含本插件、客户端产物可取、/state 返回假接口里的数字、手动刷新真的打了上游
node scripts/verify/e2e.mjs "http://127.0.0.1:6399/?token=<启动 URL 里的令牌>" http://127.0.0.1:6398

# 4) 截图（走 CDP；`chrome --screenshot` 会被页面的长连接挂住）
node scripts/verify/screenshot.mjs "<authenticated url>" out.png 6000 1440 900

同一套检查也在真实 desktop 实例上跑过（重启后）：GET /dsh-balance/state 返回 {"status":"ready","source":"account",…} —— 走的是登录账号路由（deepseekAccount.getBalance），侧边栏底部的数字随本会话的计费消耗同步变化；POST /refresh 会推进 checkedAt。

本次验证结果：客户端条目被发现、/plugins/.../dsh-balance-hud/client.js 可取（页面共 10.8 MB combo）、 GET /dsh-balance/state 返回 ready 且金额与假接口一致、POST /refresh 让上游命中数 +1、未知子路径 404、断开上游后状态转为 stale 且旧数字保留。

同一套脚本还覆盖了这一版新增的行为：

假接口每次查询递减余额 → today.byCurrency.CNY.spent 随之增长（0.05 → 0.10 → …）；
重启实例后今日消费从 0.60 继续累计（账本落盘生效，不归零）；
阈值调到 ¥5 时 low.active=true 且界面整行转红、浮层出现「余额不足」横幅；
用假账号服务跑 source=account 分支：topUpUrl 进快照，横幅出现「去充值」按钮。

scripts/verify/e2e.mjs 用 --expect-low / --account 两个开关分别打开低余额与账号路由的断言。

站点导航

dsh-balance

dsh-balance-hud

1. 它显示什么、放在哪里

2. 「实时」是怎么做的

2.1 余额流速与扫光特效

3. 数据来源

今日消费的口径

4. 配置

5. 安装

5.1 在 DSH Desktop 里搜索安装（最省事）

5.2 命令行安装

5.3 本机开发：把仓库链接进 desktop profile

5.4 打包与发布

6. 验证

真实进程端到端（本次已跑通）

dsh-web

dsh-our-free-model

dsh-purge

dsh-balance

dsh-balance-hud

1. 它显示什么、放在哪里

2. 「实时」是怎么做的

2.1 余额流速与扫光特效

3. 数据来源

今日消费的口径

4. 配置

5. 安装

5.1 在 DSH Desktop 里搜索安装（最省事）

5.2 命令行安装

5.3 本机开发：把仓库链接进 desktop profile

5.4 打包与发布

6. 验证

真实进程端到端（本次已跑通）

同类插件

dsh-web

dsh-our-free-model

dsh-purge