侧边栏余额 WXJ-71/dsh-sidebar-balance

dsh-sidebar-balance

给 DeepSeek Harness 的侧边栏底部加一条余额：账号余额、计费时段提示、消耗数字弹出。
包名 @local/dsh-sidebar-balance，插件页显示为 侧边栏余额 / Sidebar Balance。

插件图标

- 余额常在眼前 — 侧栏「设置」上方一条 余额 ¥12.34，点开是账户面板：充值余额与赠金余额、刷新、用量/充值入口，以及浏览器内的 DeepSeek 账号登录。
- 计费时段一眼可辨 — 钱包图标里两颗点，红点闪 = 计费高峰，绿点闪 = 空闲优惠（UTC 01:00–04:00 与 06:00–10:00，周一至周五，中国法定节假日除外；节假日按空闲计）。
- 消耗数字弹出 — 余额真的减少时，这笔扣款会拆成一串 -¥0.0031 从钱包上方连续飘出，每 1–1.4 秒一个、每个停留 1.6 秒，加总正好等于这次真实扣款；不消费就不弹。

安装

在 Harness 网页的插件页 → 安装里粘贴这个地址：

https://github.com/WXJ-71/dsh-sidebar-balance

命令行等价写法：

dsh plugin --profile web add https://github.com/WXJ-71/dsh-sidebar-balance

装完在插件列表里启用 @local/dsh-sidebar-balance，刷新页面即可。完整步骤、依赖要求、卸载与排查见 INSTALL.md。

适用环境

| 项目 | 说明 |
| 适用系统 / 界面 | DeepSeek Harness 的 Web 界面（dsh web / dsh --profile web）：手机浏览器、安卓 DSH 应用内嵌页面、桌面浏览器都适用。清单里以 dsh.client.platform: "web" 声明，不依赖任何桌面端组件。 |
| Harness 版本 | ^0.1.7-rc.2 —— 0.1.7（含 -rc 预发布）起、0.2.0 之前。已写进 package.json 的 peerDependencies：版本不符时插件页直接拒绝安装并提示版本不兼容，不会出现「装上了却不工作」。核验方式见 INSTALL.md。 |
| 已验证版本 | 0.1.7-rc.2（开发与实测环境：安卓 DSH 应用 + 手机浏览器） |
| 依赖 | 无。只用 Harness 自带的 sidebar.footer.action 槽位与账户 Remote，不引入任何第三方包 |
| 账号 | 需要 DeepSeek 开放平台账号：余额由 Harness 的 Host 读取，登录在浏览器里完成（授权回调落在本机回环地址） |
| 网络 | 插件本身不直连平台；只有 Host 读余额、以及你点「登录」时才访问 platform.deepseek.com |

许可

MIT。

以下为技术说明（English）。

@local/dsh-sidebar-balance

插件页里的显示名：侧边栏余额 / Sidebar Balance（来自 locale/zh.json 和 locale/en.json；没有这两个文件时，卡片会退回显示原始包名）。

在 Harness 侧边栏底部、Settings 那一行上方显示 DeepSeek 账号余额，并在浏览器里把 Harness 登录到 DeepSeek Platform 账号。它读取内置的账户 Remote（account.getState、 account.getBalance、account.startSignIn、account.cancelSignIn），所以自己从不直接访问 Platform，也不需要任何配置。

为什么会有这个插件

自带的账户 UI（@deepseek-ai/dsh-client-ui-settings-account）只在 Desktop 渲染进程里注册 —— 它的 apply() 开头就是
if (!("dshDesktop" in globalThis)) return。因此在浏览器配置档里既没有账户页，也没法
登录，尽管 Host 那一半（dsh-deepseek-account-platform）支持 loginSource: 'web' 的 PKCE 流程，回调会落在回环 Web 服务器上。这个插件补上了缺失的入口。

渲染位置

在 sidebar.footer.action 槽位里占一项（id: account-balance）：

- 已登录 — 钱包图标（见 WalletIcon：一个 1.25:1 的钱夹，带按扣，照着作者的两张参考图标画的）、余额/Balance，以及充值金额（¥12.34，余额不足一分钱但为正数时显示 <0.01）；点击打开面板，里面有充值钱包与赠金钱包、刷新操作，以及账号的 Usage / Top-up 链接。
- 已登出 —— 钱包图标显示 未登录/Not signed in；面板提供 登录/Sign in。
- 登录中 —— 尝试登录期间，状态以品牌色显示 等待登录完成…/Waiting for sign-in…，并提供 打开授权页 和 取消 操作。
- 读取失败 —— 状态变为错误色，面板显示 Remote 错误文本；轮询会持续重试。
- 折叠侧边栏 —— 36px 圆形纯图标按钮，和旁边的 Cordis 面板一样。
- 计费指示器 —— 钱包左侧空白面板里有两个圆点，红点在绿点上方。当前打开时段的圆点会闪烁，并带有自身颜色的光晕；另一个圆点保持 55% 不透明度，所以不盯着闪烁也能读出状态。标签的 tooltip 会标明时段（· 计费高峰时段 / · 空闲优惠时段）。

- 消费弹窗 —— 某次读取显示钱包金额减少时，减少的数额会以 -¥0.0031 这样的数字浮在钱包上方：每 1-1.4s 出现一个，每个在 1.6s 内上升并淡出，所以前一个还没消失，下一个就已经出现。一次读取损失了多少，它的弹窗加起来就是多少。

状态在挂载时刷新，每 60 秒刷新一次，标签页变为可见时也会刷新。登录尝试待处理期间，刷新频率为 2 秒，所以浏览器完成后，标签会自行切换到余额。

计费指示器

DeepSeek 按标准费率计费的时间是 UTC 的两个窗口，周一至周五；其余所有时间按折扣费率计费 —— 周末和中国法定节假日全程（定价）：

| 费率 | 时间（UTC） |
| 高峰（红点闪烁） | 01:00–04:00 和 06:00–10:00，周一至周五，中国法定节假日除外 |
| 空闲（绿点闪烁） | 其余所有时间、整个周末，以及所有中国法定节假日 |

client.js 里的 peakAt(date) 是当前时刻的纯函数，所以页面每次重新渲染，圆点都是对的；useOffPeak 只负责在边界处重新渲染：一个定时器会在下一个 00:00/01:00/04:00/06:00/10:00 UTC 边界重新触发，visibilitychange 监听器会重新读取时钟，因为手机在标签页进入后台时会冻结定时器。窗口按 UTC 计算，所以设备自身的时区不会改变哪个圆点闪烁。

节假日来自国务院的年度安排，按年份列在 CN_HOLIDAYS 里，格式为 MM-DD（2026 年是国办发明电〔2025〕7号）。这张表是唯一会过期的部分：缺失的年份会回退到工作日规则，也就是在节假日声称高峰，而不是承诺一个并不存在的折扣。每年 11 月发布后，从 <https://www.gov.cn/zhengce/zhengceku/> 添加下一年的日期。把周末调成工作日不影响：DeepSeek 对周末全程按空闲计费，不管是否 调休。

prefers-reduced-motion 会关闭闪烁；此时活动圆点保持加深的填充和光晕，与变暗的另一个圆点形成对比，所以时段仍然可读。

填充色是主题的状态 token 向黑色混合 20%，所以圆点读起来深色而非粉彩——浅色 #ec1313 → #bd0f0f 和 #22c55e → #1b9e4b，深色 #f25a5a → #c24848。每条规则先声明普通 token，所以不支持 color-mix 的浏览器仍能画出可用的颜色。光晕保留未加深的 token，正是这一点让点亮的圆点读起来像深色核心上的一道亮边。

闪烁本身也在它们旁边调好了：1.4s，曲线在 65% 的周期里停在满不透明度，然后快速下探到 .12，活动圆点带 saturate(1.35)，外加一圈自身颜色的 drop-shadow 光晕（--dsh-sidebar-balance_glow）。平均下来，亮度约为对称淡入淡出的 1.8 倍；周期、下探深度、光晕半径和 80% 混合比例就是旋钮，需要更响、更静或更深时调它们。

花费弹窗

弹窗搭的是 chip 已经在做的读取——不额外产生 Platform 流量。每次就绪的读取都会把每个钱包行（toppedUp 加上任何正的 bonusWallets）按钱包货币的百万分之一单位加总，再与上一次读取比较。第一次就绪的读取只设基线，充值会静默抬高它，读取失败则不动它，所以弹窗只会打印真实的花费。

检测到的下降会入队，每 1-1.4s 一个弹窗，逐步释放其中一份：

- 份额在下降入队时就算好（ceil(queue / SPEND_PIECES)），不是每个弹窗现算，所以一次下降大约要 50 个弹窗才排空——读取间隔除以节奏，于是一次 60s 读取的花费能撑约 60s 的弹窗，而不是一下子喷完、剩下的一分钟空着。按弹窗现算会变成几何衰减。
- 节奏（1-1.4s）故意短于 1.6s 的生命周期，所以同一时刻有一两个数字在空中，整列读起来像连续的水流。
- 队列的最后一个弹窗拿走余数，于是一次读取的弹窗加起来正好等于那次读取的下降，算术也始终不离开整数百万分之一。
- 低于 SPEND_MIN_MICROS（0.0001）的份额留在队列里，而不是打印一行零。

文本是一个减号、钱包自己的货币符号（symbolOf），以及份额所需的最少小数位（最少两位，最多四位）——没有别的字。它按 chip 的实时包围盒定位，放在固定、pointer-events: none 的图层里，z-index: 35，锚定在 chip 中心上方 SPEND_LIFT（34px）处——所以 36px 的轨道 chip，其 18px 字形位置更高，仍与 42px 宽的 chip 保持同样的间距。第一帧让数字停在钱包字形上边缘上方约半个行盒处，上升过程的第一帧和最后一帧都不碰到按钮。它待在账户面板（40）之下，又不碰侧边栏的布局。样式是峰值圆点的深红（--dsw-alias-state-error-primary 向黑色混合 20%，普通 token 先声明作为回退），12px、字重 500、表格数字，外加一层侧边栏自身填充色的柔和阴影，让数字保持无论浮在什么内容上，都要保持清晰可读。

prefers-reduced-motion 会去掉浮动效果；数字随即在原地停留 1.6s。SPEND_PIECES、SPEND_GAP_MS、SPEND_LIFE_MS、SPEND_MIN_MICROS 和 SPEND_LIFT 是调节旋钮——更慢的滴落、更长的停留、更高的队列下限，或者与 chip 之间更大的间距。

登录流程

1. 面板上的 登录/Sign in 操作会调用
account.startSignIn(client, window.location.origin, 'web')。
2. Host 执行 PKCE 尝试，在其 Web 服务器上注册浏览器回调路由 /oauth/callback，并返回带 authorizeUrl 的尝试；插件在新标签页中打开它。
3. 平台批准后，标签页重定向到 http://127.0.0.1:<port>/oauth/callback?code=…&state=…，Host 完成交换并存储为 deepseek-account-platform/default 授权。
4. 下一次 2 秒轮询会看到 credential-stored，读取钱包，chip 显示金额。

window.open 与点击在同一轮执行，因此不会被当作弹窗；如果浏览器仍然拦截，面板会提示，并改为提供 打开授权页 按钮。取消时调用 account.cancelSignIn(attempt.id)；如果面板在尝试中途关闭，尝试会在 Host 上继续存活，下一次轮询会再次采用它的 id。

文件

- package.json —— 打包清单：dsh.bundle.patch、显示用 icon、元数据读取器解析的 locale/.json 和 package.json 导出，以及 Client 声明（platform: web、immediately 和加载顺序 inject）。
- cordis.patch.yml —— 为本包插入唯一的 Host 行。
- locale/en.json、locale/zh.json —— 插件卡片和组件行上显示的 meta.title / meta.description。
- icon.png —— 插件卡片图稿：241×256 RGBA PNG（90.9 KiB），从 1155×1229 的源图裁切而来，源图本身已带透明背景。只有插件列表、打包列表和清单行会读取它；侧边栏 chip 在 client.js 中保留内联钱包字形。
- index.js —— Host 部分；它不渲染任何内容，也不拥有任何服务。
- client.js —— 浏览器部分：sidebar.footer.action 注册、chip 和账户面板、消费弹窗、登录流程、内联样式、内联 WalletIcon / RefreshIcon 字形、peakAt / useOffPeak 计费窗口辅助函数，以及 sidebar.balance 字典（en/zh）。

维护

client.js 中的 clientMetadata() 会向 Platform 发送 x-client-version。它固定了本包编写时所针对的 Harness 版本（0.1.7-rc.2）；升级 Harness 后请一并更新。

package.json 声明了 peerDependencies: { "@deepseek-ai/dsh": "^0.1.7-rc.2" }，管理器的兼容性预检会读取它：超出该范围时，插件会在安装阶段被拒绝，而不是之后静默失败。对应的 peerDependenciesMeta 条目将其标记为可选，这样包管理器就不会尝试为它拉取整套 dsh 运行时。当 slot 和 account 的 Remote 接口在新版本线上确认后，再放宽范围。

用 link: 方式安装到配置档，这个目录会保持实时生效：只要 web 开发监听器在跑，编辑 client.js 就会被 Client HMR 捕获；否则刷新页面即可。改动 cordis.patch.yml 里的行需要重新安装 bundle（或重启 Harness）才生效。安装本身见 INSTALL.md。

卡片图标是例外，下面这段说明并不涵盖它：readPluginMeta 只解析一次 ./package.json，之后每次调用都用 readFileSync 重新读这个文件，把图标字节内联成 data: URL。所以替换 icon.png——或者把 icon 指向 manifest 目录里已有的另一个文件——会在下一次拉取插件列表时生效，页面在挂载时就会拉取。首次添加 icon 字段、新增 exports 条目，或首次添加 locale/.json 就不一样了：Node 会在进程整个生命周期内缓存包解析出的 exports 映射，所以运行中的 Harness 一直读旧映射——因此也一直显示包名和默认插图的兜底——直到重启 dsh web。想不等重启就验证新文本或新图标地址，可以在新进程里调用 readPluginMeta：

node --input-type=module -e "import { readPluginMeta } from '@deepseek-ai/dsh-app-boot'; \
console.log(JSON.stringify(readPluginMeta('@local/dsh-sidebar-balance', 'file://' + process.env.DSH_PROFILE_DIR + '/'), null, 2))"

icon.png 是从一张 1155×1229 的 RGBA 源图裁出来的，背景透明：用 Lanczos 缩放进 256px 的框，得到 241×256，约 89 KiB。manifest 上限是 256 KiB，所以 512px 的渲染会被拒，384px 的也只是勉强放得下。这个包里没有别的东西依赖那张源图。

诊断登录失败

面板会原样打印 Remote 错误。有用的映射：

- account start failed / protocol —— startSignIn 拒绝了回调 origin。Host 只接受 http://localhost|127.0.0.1|[::1]:<port>，且不带路径，授权 URL 必须是 <platformOrigin>/dsh/authorize。
- expired —— 这次尝试超过了 attemptTimeoutMs（默认 10 分钟），或者 Browser 在同意之前就被关掉了。
- network —— Host 连不上 https://platform.deepseek.com。
- storage —— 存在已存储的授权，但解析不了；用 signOut（或删掉 $DSH_HOME/.credentials.yaml 里的 deepseek-account-platform/default 记录）清掉它。