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

<profile> 一般是 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/<name>/package.json 备份为 package.json.bak-dsh-balance-hud；
在 dependencies 里加一条 "dsh-balance-hud": "link:<本仓库绝对路径>"（以后无论谁跑 pnpm install 都不会丢）；
在 dsh.profile.bundles 末尾追加 dsh-balance-hud；
在 profiles/<name>/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 两个开关分别打开低余额与账号路由的断言。

7. 架构

浏览器                                  宿主进程（DSH）
┌──────────────────────────┐            ┌─────────────────────────────────────┐
│ sidebar.footer.action     │  GET 5s    │ /dsh-balance/state  ──► 快照(内存)   │
│  .dshb-trigger / .dshb-pop│ ─────────► │ /dsh-balance/refresh ─► 强制刷新     │
│  React 组件（单文件脚本）  │            │                                     │
└──────────────────────────┘            │ refresh() 去重 ─► readBalance()      │
                                        │   ├─ deepseekAccount.getBalance()    │
                                        │   └─ credentials → GET user/balance  │
                                        │ 触发：启动 / 60s / turn/end / 手动    │
                                        └─────────────────────────────────────┘

宿主半侧（src/host/）：config（配置归一化）→ sources（来源编排）→ parse（响应校验）→ ledger（今日消费与低余额判定）→ store（快照与 stale 语义）→ index（Cordis 装配、路由、定时器、会话监听）。
浏览器半侧（src/client/）：index（__ModuleLoader__.load 外壳）→ app（插件三件套 + 插槽注册）→ widget（React 组件）→ styles（一次性注入的样式表）→ locales（中/英字典）。
共享（src/shared/）：types（唯一的线上契约）、format（金额/时间格式化，纯函数）。

两个产物都不 import 任何 @deepseek-ai/* 运行时模块：宿主只用 ctx.get() 软取服务，浏览器只用 require('react') 等平台种子模块。因此产物自包含，可跨 DSH 版本安装，也不会给宿主引入重复的 cordis 实例。

GET /dsh-balance/state 的响应（也是唯一的线上契约）：

{
  "status": "ready",              // loading | ready | stale | signed-out | no-credential | failed
  "source": "account",            // account | api-key | none
  "wallets": [                    // 服务端原始金额字符串，格式化只在展示层做
    { "currency": "CNY", "total": "128.4500", "granted": "18.45", "toppedUp": "110.00" }
  ],
  "updatedAt": 1792923813096,      // 最近一次成功
  "checkedAt": 1792923815383,      // 最近一次尝试
  "error": "…",                    // 仅失败时存在
  "pollMs": 5000,
  "displayCurrency": "auto",
  "showInRail": true,
  "today": {                       // 今日账本（todaySpend=false 或还没读数时是 null）
    "date": "2026-10-25",          // 按 dayTimeZone（默认北京时间）
    "byCurrency": {
      "CNY": { "spent": "0.45", "toppedUp": "0", "startBalance": "3.73" }
    }
  },
  "flow": {                        // 余额流速（数据不足时为 null），驱动表面扫光
    "currency": "CNY",
    "ratePerMinute": "0.4200",     // 不展示，仅调试/扩展
    "level": 2,                    // 0 | 1 | 2 | 3
    "windowSeconds": 60,
    "samples": 9
  },
  "low": {                         // 低余额告警（未触发时为 null）
    "active": true,
    "currency": "CNY",
    "threshold": "2.00",
    "balance": "1.28"
  },
  "topUpUrl": "https://platform.deepseek.com/top_up"  // 仅账号路由提供的充值页
}

8. 兼容性与边界

兼容性：本包没有任何 peerDependencies，也不 import 任何 @deepseek-ai/* 运行时模块（宿主只用 ctx.get() 软取服务，浏览器只用 require('react') 等平台种子模块）。DSH 的兼容性预检只检查 @deepseek-ai/dsh* 的 peer 范围，没有 peer 就不会被判成不兼容。package.json 另外声明了已实测的 DSH 版本：

"dsh": {
  "compatibility": {
    "dshReleases": { "0.2.0-rc.2": "compatible", "0.2.1-rc.3": "compatible" }
  }
}

如果 DSH 提示 dsh-balance@0.2.7 … 不兼容：那是 npm 上的同名第三方包，不是本插件。本插件包名是 dsh-balance-hud，两者没有代码关系——卸载那个包、安装本包即可。

依赖的宿主能力：webServer（必需，装配前提）、credentials、deepseekAccount、session/event；浏览器侧 slots、locale、sidebar.footer.action 插槽与 window.__ModuleLoader__。
账号服务缺失（例如只用 API Key 的组合）不影响装配，会退到 API Key 路由。
sidebar.footer.action 在「Windows 标题栏 + 侧边栏折叠」时被平台整体隐藏（设置 一起隐藏），这是侧边栏自身的行为，不是本插件额外限制。
只读：不发起充值、不代登录。低余额横幅里的「去充值」是账号服务提供的外链（topUpUrl），没有该链接时不显示按钮。
失败详情文案为中文（面向当前使用场景）；界面骨架文案已做中/英双语。

9. 目录

src/host/        宿主半侧（config / sources / parse / ledger / flow / store / index / context）
src/client/      浏览器半侧（index / app / widget / styles / locales / context）
src/shared/      两侧共享的线上契约与格式化
test/            99 个纯函数单测（node --test，直接跑 .ts）
scripts/         install.mjs、verify-bundles.mjs、verify/（假接口 + e2e + 截图）
docs/            截图
.github/         CI（push / PR 跑 pnpm verify）
cordis.patch.yml bundle 配置层
LICENSE          MIT

License

MIT

dsh-balance-hud

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

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

侧边栏底部的余额行

低余额告警

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

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

侧边栏折叠（图标形态）

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

<profile> 一般是 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/<name>/package.json 备份为 package.json.bak-dsh-balance-hud；
在 dependencies 里加一条 "dsh-balance-hud": "link:<本仓库绝对路径>"（以后无论谁跑 pnpm install 都不会丢）；
在 dsh.profile.bundles 末尾追加 dsh-balance-hud；
在 profiles/<name>/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

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

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

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

7. 架构

浏览器                                  宿主进程（DSH）
┌──────────────────────────┐            ┌─────────────────────────────────────┐
│ sidebar.footer.action     │  GET 5s    │ /dsh-balance/state  ──► 快照(内存)   │
│  .dshb-trigger / .dshb-pop│ ─────────► │ /dsh-balance/refresh ─► 强制刷新     │
│  React 组件（单文件脚本）  │            │                                     │
└──────────────────────────┘            │ refresh() 去重 ─► readBalance()      │
                                        │   ├─ deepseekAccount.getBalance()    │
                                        │   └─ credentials → GET user/balance  │
                                        │ 触发：启动 / 60s / turn/end / 手动    │
                                        └─────────────────────────────────────┘

宿主半侧（src/host/）：config（配置归一化）→ sources（来源编排）→ parse（响应校验）→ ledger（今日消费与低余额判定）→ store（快照与 stale 语义）→ index（Cordis 装配、路由、定时器、会话监听）。
浏览器半侧（src/client/）：index（__ModuleLoader__.load 外壳）→ app（插件三件套 + 插槽注册）→ widget（React 组件）→ styles（一次性注入的样式表）→ locales（中/英字典）。
共享（src/shared/）：types（唯一的线上契约）、format（金额/时间格式化，纯函数）。

GET /dsh-balance/state 的响应（也是唯一的线上契约）：

{
  "status": "ready",              // loading | ready | stale | signed-out | no-credential | failed
  "source": "account",            // account | api-key | none
  "wallets": [                    // 服务端原始金额字符串，格式化只在展示层做
    { "currency": "CNY", "total": "128.4500", "granted": "18.45", "toppedUp": "110.00" }
  ],
  "updatedAt": 1792923813096,      // 最近一次成功
  "checkedAt": 1792923815383,      // 最近一次尝试
  "error": "…",                    // 仅失败时存在
  "pollMs": 5000,
  "displayCurrency": "auto",
  "showInRail": true,
  "today": {                       // 今日账本（todaySpend=false 或还没读数时是 null）
    "date": "2026-10-25",          // 按 dayTimeZone（默认北京时间）
    "byCurrency": {
      "CNY": { "spent": "0.45", "toppedUp": "0", "startBalance": "3.73" }
    }
  },
  "flow": {                        // 余额流速（数据不足时为 null），驱动表面扫光
    "currency": "CNY",
    "ratePerMinute": "0.4200",     // 不展示，仅调试/扩展
    "level": 2,                    // 0 | 1 | 2 | 3
    "windowSeconds": 60,
    "samples": 9
  },
  "low": {                         // 低余额告警（未触发时为 null）
    "active": true,
    "currency": "CNY",
    "threshold": "2.00",
    "balance": "1.28"
  },
  "topUpUrl": "https://platform.deepseek.com/top_up"  // 仅账号路由提供的充值页
}

8. 兼容性与边界

"dsh": {
  "compatibility": {
    "dshReleases": { "0.2.0-rc.2": "compatible", "0.2.1-rc.3": "compatible" }
  }
}

如果 DSH 提示 dsh-balance@0.2.7 … 不兼容：那是 npm 上的同名第三方包，不是本插件。本插件包名是 dsh-balance-hud，两者没有代码关系——卸载那个包、安装本包即可。

依赖的宿主能力：webServer（必需，装配前提）、credentials、deepseekAccount、session/event；浏览器侧 slots、locale、sidebar.footer.action 插槽与 window.__ModuleLoader__。
账号服务缺失（例如只用 API Key 的组合）不影响装配，会退到 API Key 路由。
sidebar.footer.action 在「Windows 标题栏 + 侧边栏折叠」时被平台整体隐藏（设置 一起隐藏），这是侧边栏自身的行为，不是本插件额外限制。
只读：不发起充值、不代登录。低余额横幅里的「去充值」是账号服务提供的外链（topUpUrl），没有该链接时不显示按钮。
失败详情文案为中文（面向当前使用场景）；界面骨架文案已做中/英双语。

9. 目录

src/host/        宿主半侧（config / sources / parse / ledger / flow / store / index / context）
src/client/      浏览器半侧（index / app / widget / styles / locales / context）
src/shared/      两侧共享的线上契约与格式化
test/            99 个纯函数单测（node --test，直接跑 .ts）
scripts/         install.mjs、verify-bundles.mjs、verify/（假接口 + e2e + 截图）
docs/            截图
.github/         CI（push / PR 跑 pnpm verify）
cordis.patch.yml bundle 配置层
LICENSE          MIT

License

MIT

poliucode/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. 验证

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

7. 架构

8. 兼容性与边界

9. 目录

License

Community comments

poliucode/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. 验证

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

7. 架构

8. 兼容性与边界

9. 目录

License

Community comments