套餐花销浮窗 Chi-hong22/dsh-plan-spend

@chi-hong22/dsh-plan-spend

DSH 用量弹窗插件：侧边栏导航「用量」行点开一个浮窗，显示已配置服务商的套餐花销。

展示内容

| 服务商 | 数据源 | 展示 |
| DeepSeek 官方 | DeepSeek 账号登录授权：Host 半包用 ctx.deepseekAccount.resolveToken 取授权，带 x-dsh-auth-token 请求 GET https://api.deepseek.com/user/balance（不需要 API key）；回落到同一接口 + DEEPSEEK_API_KEY | 充值余额（保留服务端精度）、兜底卡上的充值拆分、赠金（账户持有时显示）、余额是否充足、这个数字来自哪条路由，以及高峰/低谷时段与下次切换倒计时 |
| OpenCode Go | GET https://opencode.ai/zen/go/v1/usage | 5 小时 / 7 天 / 每月三个窗口的已用百分比、进度条、重置倒计时 |

赠金单独占一行：赠送额度是促销性质、会过期，不属于套餐额度，所以不计入充值余额；账户确实有赠金时，卡片在充值余额下面多一行「赠金」，为 0 时这一行不出现。
两条路由都映射 granted_balance，账号卡的头行数字仍只取 topped_up_balance。

已知限制：OpenCode Go 的用量接口只返回百分比与重置时间，不返回已用/上限金额。所以弹窗里 OpenCode 一栏只有百分比，没有「还剩多少美元」。确切金额只在 OpenCode 控制台可见。

峰谷时段（DeepSeek 官方）

DeepSeek 官方按高峰/低谷两档计价，低谷价是高峰价的一半，所以 DeepSeek 卡上多一行：当前处于高峰还是低谷，以及距离下一次切换还有多久。

官方没有可查询峰谷状态的接口，规则只写在定价页的脚注里，因此这一行是客户端按已公布规则推导的：

- 高峰：北京时间周一至周五 09:00–12:00、14:00–18:00（等价于 UTC 01:00–04:00、06:00–10:00）， 不含中国法定节假日。
- 其余全部为低谷：12:00–14:00、夜间、周末全天、法定节假日全天。

推导要点：

- 周末恒为低谷，所以「调休上班的周六/周日」不需要任何额外建模——周末规则已经把它判成低谷。
- 因此节假日的口径取国务院公布的整个放假安排（含调休拼进假期的那个工作日，如元旦的 1 月 2 日），而不是只取 11 天法定节假日；否则长假期中间会冒出「高峰」。
- 判定用 UTC 日期键查表：高峰窗口完全落在 UTC 00:00–16:00 之内，窗口之外必为低谷，所以按 UTC 日期查表与按北京日期查表等价。
- 区间是半开的：04:00:00 整已属低谷。

用词说明：官方中文文档称这一档为「空闲时段」（英文 off-peak）。界面与本文用「低谷」，以便与「高峰」对仗；与官方文档对照时按同一档理解。

节假日表需要维护

表在 client.body.js 的 UM_CHINA_PUBLIC_HOLIDAYS_UTC（2026 年 33 天，来源：国务院办公厅国办发明电〔2025〕7 号），覆盖年份列在 UM_HOLIDAY_YEARS。每年第四季度国务院公布次年安排后，需要追加次年的日期键与年份。

表不覆盖当前年份时，卡上会直接写明「节假日表未覆盖 YYYY 年……请补充数据」——那种情况下每个工作日的法定节假日都会被算成高峰，而静默给错数字比显式报缺更糟。覆盖到的年份不显示任何提示。

安装

dsh plugin --profile <profile> add github:Chi-hong22/dsh-plan-spend

desktop profile 由 Electron 应用独占管理，命令行 dsh plugin --profile desktop add 会报 profile "desktop" is managed exclusively by the Electron application；请改用 GUI 的插件页安装。

验证挂载：

dsh --profile <profile> --dump-config | grep dsh-plan-spend

配置

插件没有配置项。它按凭据是否配置来决定展示哪些服务商，凭据名写在 index.js 的 ADAPTERS 表里：

| 服务商 | 凭据 ref（POSIX 环境变量名） |
| DeepSeek 官方 | DEEPSEEK_API_KEY |
| OpenCode Go | OPENCODEGO_API_KEY |

凭据通过 ctx.credentials.resolve() 解析，来源优先级见 @deepseek-ai/dsh-credentials-local（启动环境 → 存储文件 → 项目 .env → harness home .env）。
未配置的服务商不会发起请求，会显示为「未配置凭据，已跳过」。

API key 那一行是兜底：DeepSeek 卡平时由 Host 半包向已登录的 DeepSeek 账号读取—— ctx.deepseekAccount.resolveToken 对配置的推理 origin（默认 https://api.deepseek.com）发放授权，再带 x-dsh-auth-token 请求同一个 /user/balance，因此不需要 API key，授权也不会下发浏览器。
账号答不上来时（未登录、该组合没挂账号服务、查询失败），API key 卡顶上并标明自己的路由；账号查询失败会在兜底卡上写明原因，因为「未登录」与「查询坏了」在数据里一样、在界面上不该一样。

刻意不用账号服务自己的余额查询：它打的是 platform.deepseek.com，该站的 WAF 对非浏览器客户端返回 HTTP 429，于是只会报告失败而拿不到数字。

API key 读失败或未配置时，卡上还会显示生效凭据的来源层与是否可写（ctx.credentials.describe）——「存了 key 还是 401」几乎都是启动环境里的只读值压过了存储文件。

新增服务商 = 在 ADAPTERS 里加一行 + 写一个 reader 函数。

界面位置与尺寸

插件注册两条座位：

- sidebar.panellist（id dsh-plan-spend，order 20）：导航行。该座位是侧边栏自己的导航列表，行按钮、图标盒、标题、选中态、轨道态全由 shell 画；本入口只按 shell 下发的尺寸渲染仪表字形（侧边栏 16px、折叠轨道 18px，{ size, active }），不额外加任何像素。点击该行本来会让 shell 把 dsh-plan-spend 当成主面板去选中——而它并不存在，会抛错——所以字形在 document 的捕获阶段截住这次点击（早于 shell 挂在 React 根上的委托处理器，与根挂在哪个容器无关），改为开关面板。
- shell.overlay（id dsh-plan-spend）：面板。全局浮层位于每一列之外，面板因此能落在侧边栏 外侧，而不会被侧边栏的 overflow: hidden 裁掉。

面板定位：面板测量导航行所在的框架级列（结构性上溯到 frame 的直接子元素，不依赖哈希类名），左边缘锚在该列右缘 + 10px；顶边跟着对话正文而不是工作区：侧栏旁第一个 [data-conversation-content] 就是紧贴会话标题与「对话/轨迹」标签行下方的滚动区，面板锚在它顶端
+ 10px，因此不会压住标题和标签行。若当前没有会话正文，退回该列顶端。打开时、浮层尺寸变化时，以及该正文尺寸变化时都会重新测量：标签行出现使标题变高时，面板会跟着正文一起下移，而不是留在标题上。

关闭方式：再次点击该导航行、点面板里的 ×、按 Esc、或点击面板外任意位置，都会关闭。

缩放：手柄在面板右下角（离顶部锚点最远的那个角），向右拖增宽、向下拖增高；尺寸存 localStorage: dsh-plan-spend.size，并受面板最小尺寸与浮层边界双重约束。

键盘：打开后焦点进入面板，Esc 关闭并把焦点还给该导航行；Tab 可到达手柄，方向键按 16px 步进缩放，按住 Shift 步进放大四倍。

想恢复默认尺寸，清掉 dsh-plan-spend.size。改完源码运行 npm run build 重新生成 client.js； client.js 是构建产物，不要直接编辑。

浏览器侧要拿到新 client.js 需要刷新页面：DSH 的 bundle 替换不属于普通启停同步。

客户端半包必须导出 inject

client.body.js 返回的插件对象带 inject: ['slots', 'locale']，Cordis 才会等到这两个服务就绪后再
apply。若不声明，ctx.get('locale') 可能拿到 undefined，t 会静默退化成「原样返回键」，
界面上出现 button.label、panel.title、window.rolling 这类原始键——而数据与布局完全正常，只有文案坏掉，极易误判成其它问题。官方客户端半包（如 dsh-client-ui-sidebar、 dsh-client-ui-cordis）都导出了 inject，照做即可。

Host 半包同样用 ctx.get 取账号服务，而不写进 inject：没挂账号服务的组合仍要能挂上这个浮层，由 API key 卡顶上。

安全边界

- API 密钥只在 Host 半包内使用，不下发到浏览器；浏览器只读同源 JSON。
- GET /dsh-plan-spend/snapshot 走 harness web server 的命名路由，没有额外鉴权。当 web server 绑定 0.0.0.0 时，同一局域网内可读到余额与用量数字（不含密钥）。仅在本机使用时无影响。

结构

index.js Host 半包：凭据解析 + 两个上游接口 + 30s 缓存 + 路由 client.body.js Client 半包源码（裸函数体，无 import/JSX） client.js 构建产物（scripts/build-client.mjs 生成） cordis.patch.yml bundle patch：向 profile 插入一行 locale/ 插件管理器读取的显示名称与描述（en、zh） scripts/build-client.mjs scripts/render-client.mjs 构建与漂移测试共用的模板 scripts/probe-sources.ps1 一次性探针：不开插件直接验证两个上游接口 tests/client-ui.test.mjs 导航行/定位/缩放/峰谷 + 账号路由卡片测试（npm test） tests/host-snapshot.test.mjs Host 路由载荷测试（npm test） tests/build-drift.test.mjs client.js 必须与 client.body.js 一致（npm test） tests/plugin-meta.test.mjs 双语显示元数据（npm test） .github/workflows/test.yml CI：npm test + 重建漂移检查

License

MIT