余额账本 Harua79/dsh-balance-ledger

dsh-balance-ledger

DSH 余额账本 — DeepSeek Harness 桌面端插件：余额常驻显示，并把每一笔消费记到真正花掉它的那个会话上。

它解决什么

DSH 里看余额要打开「设置 → 账户」，而且只能看到一个总数——不知道钱花在哪个会话上。

这个插件做两件事：

1. 余额常驻：输入框下方那排（运行统计 / 上下文条旁边）显示「余额 ¥xx.xx」，有赠金时附带显示。点一下打开「余额去向」小窗。
2. 按会话记账：小窗按主会话列出消费、占比、最近扣费时间；子代理 / 子会话的消费并入所属主会话，展开可看「本体 + 各子会话」的明细。支持按时间 / 消费、正序 / 倒序排序。

金额是怎么来的（重要）

DSH 本地没有「每个会话花了多少钱」的货币口径——dsh-token-meter 在文档里明确说明它的数字「不是计费记录」，真正的扣费只发生在 Platform 侧。

所以本插件不做 token × 单价估算，而是用唯一真实的金额信号：账号余额的实际下降。

- 每次读到余额比上一次低，就把这段下降记到当时正在运行的会话上；
- 没有会话在运行时发生的下降 → 记为「未归属」，不会硬塞给某个会话；
- 多个会话并发 → 均摊并打「均摊」标签；
- 应用关闭期间的消费 → 无法观察，也会落到「未归属」。

台账保存在浏览器 localStorage（键：dsh-balance-chip.ledger.v1），插件不上传任何数据，也不读取设置页的 DOM。

关于那个 dsh-balance-chip 键名：这是插件改名前的历史键，故意保留，否则升级后用户已记录的台账会丢失。

安装

要求：DSH 桌面版 0.2.x，并已登录 DeepSeek 账号（未登录时贴片自动隐藏）。

本地目录
dsh plugin --profile <your-profile> add "C:\path\to\dsh-balance-ledger"
或 git 地址
dsh plugin --profile <your-profile> add https://github.com/<owner>/dsh-balance-ledger

也可以在 DSH 的「设置 → 插件」里用管理页面安装。

安装后 profile 的 package.json 会多一条依赖，并在 dsh.profile.bundles 里追加 @local/dsh-balance-ledger。

结构

| 文件 | 作用 |
| client.js | 全部实现：余额贴片、弹窗、余额读取、消费归属、排序、样式（只用主题令牌） |
| index.js | Host 半侧占位，export function apply() {} |
| cordis.patch.yml | bundle 层，插入 balance-ledger 这一行 |
| package.json | dsh.bundle.patch + dsh.client（platform: web、immediately、依赖的客户端包） |
| locale/{zh,en}.json | Plugin Manager 卡片上的标题与描述 |
| test/smoke.mjs | 冒烟测试 |

为什么 Host 半侧是空的：DSH 的浏览器插件必须先有一个 Loader 条目，dsh-client-modules 才会为该包提供 ./client bundle；所以需要一个只导出 apply() 的 Host 半侧。

实现要点

- 数据来源：ctx.remote.account.watch() 订阅账号状态，getBalance() 读钱包；与「设置 → 账户」同一份数据。
- 实时性：api-session/status 转发事件标记每个 agent 回合的开始 / 结束；回合内每 2s 轮询，空闲降到 20s，页面隐藏时完全停止。
- 失败降级：读取失败保留上一次数字，不会闪成 0 或「不可用」。
- 子会话归并：按会话摘要的 parentId 向上走到顶层主会话，并在记账时把 owner 冻结进台账，避免会话列表变化后分组错乱。
- UI 位置：贴片占 conversation.composer.dock；弹窗占 shell.overlay，遮罩与卡片复用应用 Modal 的主题令牌（--dsw-alias-bg-mask-1、--dsw-mask-blur、--dsw-alias-bg-layer-2、--dsw-elevation-prominent），不引入 @deepseek-ai/dsh-client-ui-primitives。

开发与测试

node test/smoke.mjs # 或 npm test

测试用替身 React / Cordis 驱动真实的 client.js，41 项断言覆盖：

- 模块 id = 包名、bundle 只注册一次、注入的服务齐全
- 贴片保持原始 span 结构、默认不打开弹窗、点击可打开
- 子会话消费并入主会话（0.50 + 0.30 = 0.80）、折叠 / 展开、本体行
- 时间格式 MM/DD HH:mm、扣费列固定宽度
- 两种排序键 × 两个方向的首行顺序、活动按钮状态
- 归属规则：回合内下降归该会话、宽限期外的下降归「未归属」
- 台账持久化、子会话 root 冻结
- hook 顺序守卫：同一组件前后渲染的 hook 数变化即判失败（曾用它抓到把 useSyncExternalStore 写在提前 return 之后的崩溃）

已知限制

- 台账从安装之后开始记录，没有历史数据。
- 归属是「看到下降时谁在跑」的推断，不是 Platform 的账单；同一时刻的多笔扣费会被合并成一次下降。
- 如果某个子会话的父会话已从会话列表彻底消失，且它的台账是早期版本记录的（没有冻结 root），它会暂时单独占一行。
- 余额接口被限流时贴片沿用上一次数字；轮询间隔可在 client.js 顶部 POLL_RUNNING_MS / POLL_IDLE_MS 调整。
- CLIENT_VERSION 只作为 Platform 请求头里的客户端版本，不是 DSH 版本门禁。

兼容性

在 DSH 桌面版 0.2.0-rc.2 ~ 0.2.1-rc.2（Windows）上验证。用到的接口：conversation.composer.dock / shell.overlay 插槽、ctx.locale、ctx.remote.account.getBalance + account.watch、api-session/status 转发事件、ctx.sessions.list。

License

MIT

dsh-balance-ledger 是 DeepSeek Harness 客户端插件：账户余额常驻在输入框下方，一个小弹窗展示余额花到哪儿去了，按会话拆分。

宿主不记录按会话的价格（token 计量明确不是账单记录），所以插件不做估算。它把每次观察到的账户余额下降记到当时正在运行的会话头上，把子代理会话归并到对应的主会话，无法归属的部分放进「未归属」桶。

账本存在 localStorage 里，沿用旧键 dsh-balance-chip.ledger.v1（改名之前就在用，这样已有历史不会丢）。不上传任何数据。

通过 Plugin Manager 或 dsh plugin --profile <name> add <path-or-git-url> 安装到 DSH 配置档。