dsh-account-balance

DeepSeek Harness（DSH）侧栏底部的账户余额与花费卡片：常驻显示账户余额和今日花费， 点击展开五层级成本明细，带峰谷时段状态与一键充值入口。

本项目是 LL-cmyk-so/dsh-balance-widget 的修改版，自 0.1.0 起独立演进。上游完整文档保留在 docs/upstream/。

功能

• 账户余额：优先读 DSH 内置账号服务 deepseekAccount（与官方「设置 → 账号与余额」同源， 不需要 API Key）；未登录或旧版宿主时回退到官方 GET /user/balance + 已存的 DEEPSEEK_API_KEY
• 成本估算：最近一次提问 / 今日·本会话 / 今日·本工作区 / 今日·所有工作区
• 峰谷状态：按北京时间工作日 09:00–12:00、14:00–18:00 判峰，含中国法定节假日表
• 官方价格自动同步：启动时 + 每 12 小时抓取官方定价页，失败回退内置价表
• 模型工具：account_balance，可直接问模型「余额多少 / 今天花了多少」
• 卡片每 60 秒自动刷新；点开弹层立即强刷

安装

桌面端（DSH Desktop）：设置 → 插件 → 添加插件，填写包名或仓库地址，然后重启应用 + 硬刷新。

# 网页端
dsh plugin --profile web add @lithane/dsh-account-balance
# 或直接装仓库
dsh plugin --profile web add github:Lithane/dsh-account-balance
# 或本地开发目录（改动即生效，最适合开发）
dsh plugin --profile web add link:/绝对路径/dsh-account-balance

配置

写在 profile 的 cordis.patch.yml（桌面端是 ~/.dsh/profiles/desktop/）：

- id: account-balance
  name: '@lithane/dsh-account-balance'
  config:
    balanceBaseURL: https://api.deepseek.com   # 回退路径的余额接口
    balanceApiKeyEnv: DEEPSEEK_API_KEY         # 凭据服务里的 ref
    requestTimeoutMs: 5000
    modelId: deepseek-v4-flash                 # 计价模型
    lowThreshold: 5                            # 余额低于此值变黄
    criticalThreshold: 1                       # 余额低于此值变红

更多配置项与定价说明见 docs/upstream/README.md。

架构

没有构建步骤：lib/ 就是源码，改完直接生效（上游也是这个结构）。

lib/index.js          宿主半（Node）
  ├ 5 条 HTTP 路由      /api/account-balance/{balance,active-cost,today-cost,last-cost,cost}
  ├ 会话日志解析        遍历 ~/.dsh/sessions/ 算 token 与费用
  ├ 余额读取            账号服务 deepseekAccount → 回退凭据服务 + /user/balance
  └ 模型工具            account_balance
lib/client.js         浏览器半（React）
  ├ 注入槽位            ctx.slots.inject("sidebar.footer.action")
  ├ 自注入 CSS          <style data-plugin="account-balance" data-plugin-css="account-balance/styles.css">
  └ 卡片 + 弹层         弹层 portal 到 document.body，用 ResizeObserver 跟随侧栏宽度
cordis.patch.yml      把插件行插入 profile
package.json          的 dsh 字段：bundle.patch + client.platform = "web"

几个必须知道的机制

主题	要点
会话日志	~/.dsh/sessions/<工作区编码>/session-<id>/session.vN.jsonl.zstd。当前是 v4，append-only，每次 flush 追加一个独立 zstd 帧——必须按帧解压（Node 一次性解压只返回第一帧，会静默丢掉 99% 数据）。zlib.zstdDecompressSync 需要 Node ≥ 22.15
路径解析	sessionsRoot() 按 DSH_HOME → USERPROFILE → HOME 回退。Windows 不设 HOME，且 ?? 对空字符串不回退，所以别写 ${process.env.HOME ?? ""}
样式去重	CSS 按 data-plugin-css 的 tagId 去重。改 tagId 要同步改，否则与其它版本共存时你的样式会被判定"已注入"而静默跳过
样式类名	全部走 dshbw_ 前缀（沿用上游）。颜色/圆角优先用 --dsw-* 设计 token，自动跟随明暗主题
金额排版	moneyNodes() 用正则按第一个数字把金额拆成「符号 / 整数段 / 小数段」，分别套 .dshbw_sym/.dshbw_int/.dshbw_dec；line-height:1 保证不影响卡片高度
卡片标签	.dshbw_brand（全称）与 .dshbw_brandMini（侧栏收起成 36px 图标时显示），靠 [data-compact="true"] 切换
与其它卡片共存	sidebar.footer.action 是不换行的 flex 行，多张"占满一行"的卡片会被压成半行。注意卡片与那一行之间还有一层 DSH 槽位出口容器，它是 display: contents（不生成盒子），却正是 el.parentElement——往它上面写 flex-wrap 完全无效，必须从卡片向上爬到最近的 computed display: flex 祖先再写。本卡片根元素为 flex: 1 1 100%；换行在那一行元素上做引用计数（属性名 __dshBalanceCardWrap，是与 Liaobots 插件约定的跨插件契约）：首个声明者记录原值并打开换行，最后一个离开的还原。因此任意数量的卡片共用一行都不抢，卸载顺序也不会压扁仍在挂载的邻居。改这块务必同时守住"爬到 flex 祖先"和这个契约
客户端模块 id	lib/client.js 里 window.__ModuleLoader__.load({ id }) 的 id 必须等于 package.json 的包名（@lithane/dsh-account-balance）。DSH 的客户端模块表按包名索引：实测 harness 自带的 68 个客户端模块、以及能正常工作的 dsh-balance-widget、dsh-liaobots-balance，id 全部等于各自包名。写成别的值（如 0.1.1 的 account-balance）时 bundle 仍会被加载，但槽位永远不会挂载——卡片静默消失，没有任何报错，日志里也看不到

开发

# 语法门（无构建步骤，改完直接查）
npm run verify          # = node --check lib/index.js && node --check lib/client.js

# 本地安装调试
dsh plugin --profile web add link:D:\path\to\dsh-account-balance

改动生效方式不同，别搞混：

• 客户端半（lib/client.js）：硬刷新页面通常即可
• 宿主半（lib/index.js）：必须重启 DSH（宿主代码只在启动时加载）

三个接口可直接自测（端口每次启动随机，用当前 GUI 的地址）：

(Invoke-WebRequest 'http://127.0.0.1:<port>/api/account-balance/balance'     -UseBasicParsing).Content
(Invoke-WebRequest 'http://127.0.0.1:<port>/api/account-balance/active-cost' -UseBasicParsing).Content
(Invoke-WebRequest 'http://127.0.0.1:<port>/api/account-balance/today-cost'  -UseBasicParsing).Content

active-cost 返回 no session files found = 会话路径解析有问题（见上表「路径解析」）。

调试经验

• 样式不生效时，先查 <style data-plugin-css="account-balance/styles.css"> 是否在 document.head 里
• 卡片整个消失但日志没有报错：多半是渲染时抛了异常——槽位对崩溃条目的处理是整条摘掉
• 改 .js 里的 CSS 字符串时注意：它是单行 JS 字符串，双引号要写成 \"

发布

# 1) 改 package.json 的 version，并往 CHANGELOG.md 加一节
# 2) 只做本地分发（不需要 npm 账号）
npm pack                                            # 产出 .tgz，别的机器 dsh plugin add <路径>
# 3) 发布到 npm（别的机器可按包名直接安装）
npm login
npm publish --access public                         # scoped 包必须带 --access public

• 同一版本号不能重复发布，每次改动都要 bump
• 发版后建议 git tag v<version> && git push --tags
• ⚠️ DSH 有 peer 兼容闸门：启动时比对 peerDependencies 里 @deepseek-ai/dsh 的范围 （预发布版本参与匹配）。不匹配且未豁免的 bundle 会被静默跳过（只记进 skippedBundles，不报错）。 改这个范围时要确认覆盖目标 DSH 版本，否则用户升级 DSH 后插件会凭空消失。 DSH 0.2.0 起还新增了这道闸门（上游 0.6.1 就是为此把范围从 <0.2.0 放宽到 <0.3.0）。

已知限制

• 位置固定在 sidebar.footer.action（侧栏底部、设置上方），改不了；想换位置只能改槽位注册
• macOS 桌面端收起侧边栏时整个左栏被隐藏，卡片会一起消失，而不是变成 36px 图标—— 这是 DSH 的布局行为（data-platform='darwin' 下不留图标轨），非本插件问题
• 成本数字为本地估算，不是官方账单；web_search 的辅助调用无 usage 字段，按标定常数估算（±30%）
• 会话解压依赖 Node 内置 zstd，需 Node ≥ 22.15
• 价格表与中国法定节假日表需跟随官方更新（节假日表每年 11 月左右发布次年安排）

上游与许可

上游 LL-cmyk-so/dsh-balance-widget（MIT）， 本仓库基于其 0.6.3。原始版权归原作者，LICENSE 保留上游版权行并追加本 fork 的版权行； 上游完整文档（含配置项、定价说明、历史版本）见 docs/upstream/。

两版可共存（HTTP 路由、模型工具名与全部 UI 标识均已改名），但会同时往同一个侧栏槽位注入两张外观相同的卡片，视觉上重复，不建议同时启用。

⚠️ 0.1.1 及更早版本不可与上游同时启用：那时的模型工具仍叫 deepseek_billing，与上游重名会让 DSH 在组装工具声明时抛 Duplicate tool declaration name。0.1.2 起改名为 account_balance 后此冲突消失。

License

MIT，继承上游。