余额守卫 marksimZ/dsh-balance-guard

dsh-balance-guard

一个 DeepSeek Harness 插件，把 DeepSeek 账户余额固定在 GUI 右边缘，做成一条安静、按颜色分档的轨道，并在余额耗尽之前预估当前任务要花多少钱。

除此之外不碰任何东西：余额取自你已登录的 DSH 账号，从不读取 API Key，也没有任何消息内容离开 Host。

╭──────────────╮
│ ● ¥128.40 │ ← 20px chip, always visible
╰──────────────╯
┌────────────────────────────┐
│ 账户余额 ● 余额充足 │ │ ¥128.40 │ │ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░░░ │ ← 4px rail / meter │ 本轮已花 ¥0.42 还需 ¥0.90–2.30 │ │ 估算依据 ▾ │ │ 更新于 12 秒前 刷新 去充值 │ └────────────────────────────┘

| 余额（账户币种） | 档位 | 含义 |
| < 10 | 红 | 快要见底 |
| 10 – 30 | 橙 | 尽快充值 |
| 30 – 50 | 绿 | 正常 |
| > 50 | 蓝 | 充足（超出 50 的部分在面板里说明） |

每种颜色、圆角、阴影和字号都取自 shell 自带的 --dsw- 令牌；没有自定义色板，除 160–240ms 的过渡外没有动画。悬停显示面板的只读预览，点击固定面板，按 Esc 或点击外部关闭。

中文速览

- 界面最右缘一根 4px 极简轨道，按余额比例填充；旁边常驻一个 20px 小胶囊（语义色点 + 金额）。
- 颜色：<10 红、10–30 橙、30–50 绿、>50 蓝；>50 的超出部分在面板里以「超刻度 ¥x」说明，不再有波浪动画。
- 悬停 = 只读预览面板；点击 = 固定面板（Esc 或点击外部关闭）。面板里给出本轮已花 / 预计还需区间；预计不够跑完时胶囊上出现「!」徽标、面板里一行红字写缺口（不弹窗、不发声）。
- 余额来自已登录的 DSH 账号，不读 API Key；卡片可展开「估算依据」（步数、缓存命中、峰谷价）。
- 全部视觉走 DSH 主题令牌：11/12/13/16 字号阶、R8/R12/R16 圆角、系统面板阴影；无自定义色板。

预测什么

「当前任务」= 当前根会话正在运行的那一轮（turn/start → turn/end）。

- 已花 是服务商给出的真实数据：这一轮四个计费桶（uncachedInputTokens、cacheReadTokens、cacheWriteTokens、outputTokens）相对会话累计 tokenUsage 投影取增量，按当前模型和时段计价。
- 还需 按步预估：下一步的提示词大小取自服务商锚定的 contextPressure.projectedTokens，输出和提示词增长取自本轮的采样（缺失时回落到配置的默认值），缓存命中率按本轮到目前为止实测。
- 还剩多少步取本会话已完成轮次的平均每轮步数（没有历史时默认 8）。卡片给出最小值 / 期望值 / 最大值：最小值是再多一步，期望值是预计剩余步数，最大值是期望步数的两倍，同时缓存命中率差 10 个百分点、按峰值价格计算。
- 判定：required = expectedRemaining × 1.2 + reserve，再与余额减去余额读取之后发生的花费相比较（平台余额有几分钟延迟）。余额等于或低于这条线即为「不足」。

没有轮次在跑时，同一张卡片改用最近三轮估算下一个任务，而不是假装能预知未来。

环境要求

- 已登录 DeepSeek 账号的 DSH 客户端。守卫通过 ctx.deepseekAccount 读取余额；账号 token 不会传到渲染进程，也不读取任何 API key。
- Node 20+ 仅用于测试/安装脚本；插件本身没有构建步骤。

数字从哪来

ctx.deepseekAccount.getState() 和 getBalance() —— 与客户端账号菜单用的是同一个服务，所以进度条始终与客户端显示的一致。getState() 是异步的；曾经同步读取它，导致所有已登录账号都显示为未登录，这也是本文件在账号部分两次强调这一点的原因。

卡片会标明来源（余额来源：DSH 账号）。成功读取过一次之后，若后续读取失败，读数仍留在屏幕上，并清楚标注错误；显式退出登录会清空数字，进度条变灰。

安装

插件未发布到 npm，直接从代码检出加载。

git clone https://github.com/marksimZ/dsh-balance-guard.git dsh-balance-guard

然后二选一：单次运行时传入 overlay：

dsh web --patch /absolute/path/to/dsh-balance-guard/cordis.patch.yml

……或者追加到某个配置档自己的补丁层，使其永久生效，并支持热重载（无需重启，刷新页面即可）。安装脚本在 desktop 配置档存在时选它，否则选 web：

node scripts/install.mjs # writes $DSH_HOME/profiles/<profile>/cordis.patch.yml
node scripts/install.mjs --dry-run # show the exact result first
node scripts/install.mjs --profile web

cordis.patch.yml 自带一条与本机相关的绝对路径。 编辑那一行（或让 install.mjs 写入），指向你克隆本仓库的位置。

验证运行中的 GUI 确实加载了它：

node scripts/verify-deployed.mjs --url http://127.0.0.1:<GUI 端口>

配置

每个键都可选；默认值在 cordis.patch.yml 中。

| 键 | 默认值 | 含义 |
| safetyRatio | 0.2 | 在预计剩余花费上的乘数 |
| minReserveCny | 2 | 必须保留不动的金额（账号货币单位） |
| balanceTtlMs | 25000 | 一次余额读数缓存多久 |
| balancePollMs | 30000 | 后台余额刷新间隔 |
| balanceTimeoutMs | 30000 | 单次余额读取的超时时间 |
| runningPollHintMs | 1000 | 一轮对话运行期间，浏览器轮询的提示间隔 |
| idlePollMs | 15000 | 空闲时浏览器轮询的节奏 |
| cnyPerUsd | 7.2 | 美元报价价格表使用的美元兑人民币汇率 |
| assumedSteps | 8 | 会话没有历史记录时，假定的剩余步数 |
| assumedOutputTokens | 1200 | 没有样本时，每步的输出 token 数 |
| assumedGrowthTokens | 4000 | 没有样本时，每步的提示词增长量 |
| assumedCacheHit | 0.85 | 没有提示词样本时的缓存命中率 |
| holidays | [] | DeepSeek 全天按低谷计费的 UTC 日期 |
| balanceLagCompensation | true | 扣除在读数之后才入账的支出 |
| clientVersion | "" | 页面无法上报版本时使用的客户端版本 |

价格放在 src/policy.js 的 PRICE_TABLE 里（单位是每 100 万 token 的美元价，deepseek-flash 和 deepseek-v4-pro 各有高峰、低谷两行），抓取日期和来源 URL 写在文件头部。高峰时段是周一至周五 UTC 01:00–04:00 和 06:00–10:00，holidays 里列出的日期除外；其余时间都是低谷。改价格要动两个文件：policy.js，以及 scripts/policy-spec.mjs 里钉住的值。

架构

两半，一个插件。

Host half (src/index.ts)
ctx.deepseekAccount.getState() / getBalance(metadata) → the balance, token stays Host-side
ctx.on('session/event') → per-turn billed-token folding
ctx.sessionProjections.stateOf(...) → tokenUsage / contextPressure / modelSelection
src/policy.js → bands, prices, estimator, verdict (pure)
├─ GET /dsh-balance-guard/state → same-origin read-only JSON
└─ globalThis.__DSH_BALANCE_GUARD__ → index injection for first paint

Browser half (src/client.js)
window.__ModuleLoader__.load({ id, factory }) → the whole transport contract
require('react') → the shell's platform seed
ctx.slots.inject('shell.overlay') → the rail, chip and preview/pinned panel

为什么要有 Host 半边？ 账户 token 永远不会到达渲染进程；每轮计费记录在 Host 的会话日志里；shell.overlay 入口拿不到 useProjection，所以页面自己读不了会话投影。

为什么用 HTTP 路由，而不是 @Remote？ Remote 方法由 Typert 构建流水线根据 Host 装饰器生成。Harness 构建之外的插件必须自己描述通信协议，所以它在 ctx.webServer 上发布一条具名路由——刻意不放在 /api 下，那里属于 Connection 插件，并且要做认证。跨线传输的只有聚合数据：没有 token，没有消息正文。随附的 Web 组合只绑定回环地址。

为什么所有阈值都放在 Host 上？ 这样产品规则只存在一处（policy.js），并且用普通 Node 测过一次，缓存的浏览器 bundle 永远不会和 Host 不一致。

测试

普通 Node，不用测试框架：

npm test # policy spec + client spec + bundle smoke + theme tokens + visual tokens
npm run test:host # mounts the Host half on a mock context and drives the real route
npm run verify # read-only probe of a running GUI

| 脚本 | 固定住什么 |
| scripts/policy-spec.mjs | 档位边界（9.99 红、10 橙、30 绿、50 绿、50.01 蓝）、峰谷日历、官方价目表、估算器算术（含 DESIGN.md 里的算例）、×1.2 + reserve 判定和钱包预测 |
| scripts/client-spec.mjs | 快照 → 面板模型：chip 文案、状态词、列、警告级别、标记规则、详情行、轮询节奏 |
| scripts/client-smoke.mjs | bundle 通过 __ModuleLoader__、require('react') 注册，装一张样式表，挂载到 shell.overlay |
| scripts/host-smoke.mjs | 登录 → 回合运行中 → 余额不足 → 回合结算 → 读取失败保留上一个数字 → 登出，全程走真实路由 |
| scripts/theme-tokens.mjs | 每个 var(--dsw-) 都由随包主题声明；chip 是横向的；色调、警告徽标和操作都还在 |
| scripts/visual-tokens.mjs | 没有裸色值，圆角只取 --dsw-radius-*，字号只取随包字号表，没有无限动画，overlay 始终在 shell toast 之下 |
| scripts/verify-deployed.mjs | 运行中的 GUI 同时提供 bundle 和状态路由 |

theme-tokens 存在，是因为自定义属性缺失会静默失败：声明被丢掉，硬编码的兜底值照常绘制，看起来像设计选择，而不是 bug。上一个余额插件就是这么翻车的。

限制

- 预测不是账单。 剩余步数、缓存命中率和工具输出大小都是估算；min/expected/max 区间才是诚实的误差范围。
- 平台余额有延迟，从几十秒到几分钟不等。守卫会减去读数之后落账的实测花费，但这份补偿本身也是实测值。
- 节假日是离线的。 没有 holidays 列表时，工作日的峰时窗口按峰时计价（保守高估）。
- 子代理不在预测里。 它们的花费是真实的，会体现在余额上；卡片只注明它们在运行。
- 一次只跟一个任务。 多个会话同时运行时，Host 跟踪最近活跃的运行中回合；卡片会写出会话标题。
- 价格可能变动。 价目表带抓取日期；改价只需改一个常量加一个测试。
- USD 账户以 USD 显示；价目表只对 CNY 账户用 cnyPerUsd 换算。
- 账户服务必须组合进来。 插件把 deepseekAccount 和 sessionProjections 声明为必需服务，所以缺少它们的配置档根本不会加载状态栏，而是比坏掉的好。两者都随 Desktop 客户端和 dsh web 一起提供。
- 应用内充值页不是我们的。 DSH 原生的 Platform 页面属于账号设置包，所以卡片上的「去充值」会在系统浏览器中打开 Platform 充值 URL。

许可证

MIT — 见 LICENSE。