前言¶

用 DeepSeek Harness（DSH）做智能体开发时，模型调用往往走 WorkBuddy 的 XD Pool 多账号池。积分按包发放、有过期时间，Token 用量又分散在多账号、多模型上。若只在上游网页里偶尔点开查看，很难在写提示、调工具的日常节奏里持续掌握「还剩多少、今天花了多少、哪包快过期」。

dsh-xdpool-billing 是面向 DSH 桌面 Web 界面的客户端插件：在对话输入区下方提供常驻胶囊面板，汇总余额、消耗与过期预警，并可选通过 Agent 工具读取同一份数据。它不替代上游账号管理，也不重复实现 XD Pool 协议，而是读取同机已安装的 dsh-xdpool 暴露的只读路由。

这是什么¶

• 名称：dsh-xdpool-billing（展示名 XD Pool Billing Meter）
• 维护者：Xun-Prog
• 分类：客户端（渲染在 conversation.composer.dock 槽位）
• 版本：1.0.0（见 package.json）
• 许可证：MIT

插件定位是 XD Pool（WorkBuddy）积分计费面板：显示各账号剩余积分与积分包明细；按余额快照差值统计今日/本月/累计已消耗；汇总 Token 用量；并对一次性积分包做分档过期预警。数据源唯一依赖社区插件 dsh-xdpool；未安装或未启用时，面板显示「数据源不可用」，而不是空白卡片。

数据从哪来¶

本插件不联网，也不读取 WorkBuddy 凭据。它只请求同一台 DSH Web 服务器上 dsh-xdpool 已注册的两个路由：

本地还维护账本与聚合状态：

• 账本文件：$DSH_HOME/storages/xdpool-billing/ledger.json（按天聚合 + 每账号基线）
• 面板/API 数据：GET /__xdpool-billing/state.json（加 ?refresh=1 可立即拉一次上游）

核心功能¶

胶囊面板¶

安装并刷新页面后，输入区下方会出现小胶囊；点击展开可查看余额、今日/本月/累计已用、累计占比进度条、过期预警、Token 用量，以及各账号余额与各自最近到期时间。样式使用宿主主题令牌（--dsw-alias-*），中英双语随宿主 locale。

「快过期」预警¶

积分包多有期限。面板从急到缓提供三层信息（只统计一次性包 monthly=false，月度包按周期刷新，不计入「快过期」以免误报）：

1. 最近一次到期：剩余天数、过期积分、账号与包名；折叠状态下 7 天内会在胶囊上显示红色角标（如 ⏳ 5.9d）。
2. 3 / 7 / 30 天分档：各档即将过期的积分累计量（档之间是包含关系，不可相加）。
3. 到期日历：按日列出将过期多少积分，便于优先消耗快过期部分。

分档窗口默认 3、7、30 天；可用环境变量 XDPOOL_BILLING_EXPIRY_WINDOWS=3,7,30,60 覆盖。README 说明上游 expiringSoon 仅 3 天窗口，本插件自行分档以避免大批积分显示为 0。

已使用多少：实测与推算¶

面板区分两种口径：

1. 实测消耗（measured）：约每 60 秒记一次余额快照，余额下降部分计为真实消耗；签到、领券、新开包导致的上升不计入；月度包重置也不扭曲该差额。
2. 按包推算（packages）：一次性包用 size - remain；月度包只表示本周期已用，单独展示、不并入一次性累计。

Agent 工具¶

注册工具名 xdpool_billing，数据与 state.json 一致，支持 refresh 参数，便于在对话里让智能体查询当前计费状态。

安装与启用¶

运行环境要求（package.json）：Node >=20，DSH >=0.1.5-rc.1 且 <0.3.0。

从插件市场安装（README 推荐）：

dsh plugin --profile desktop add dsh-xdpool-billing

从本地源码目录安装：

dsh plugin --profile desktop add ./dsh-xdpool-billing

（需先取得插件源码目录，例如自行下载 release 或已有副本；本文不按名称拼接未出现在资料中的 github: 安装串。）

安装完成后刷新 DSH Web 页面，胶囊应出现在输入区下方。请先确保已安装并启用 dsh-xdpool，否则面板会一直提示数据源不可用。

典型用法与排错¶

查看面板：在 DSH 对话页点击输入区下胶囊展开明细。

立即刷新上游数据：

curl "http://127.0.0.1:<你的端口>/__xdpool-billing/state.json?refresh=1"

面板显示「数据源不可用」（多为上游问题）：

1. 确认 dsh-xdpool 已安装且启用。
2. 访问 http://127.0.0.1:<端口>/plugins/dsh-xdpool/status?region=cn；404 通常表示上游未启用或路由变更。
3. 查看 state.json 中 ok 与 reason（如 xdpool-not-available(404)、xdpool-status-unavailable、N account(s) balance unavailable）。

余额显示「未知 (N)」：有 N 个账号余额未查到（刻意不把失败当 0，避免误读为巨额掉点）；常见原因是该账号登录过期。

国际版账号余额为空：上游国际版网关无积分系统，属上游事实而非本插件缺陷。

适用场景与注意¶

适合已在 DSH 桌面配置中使用 XD Pool 多账号、需要在本机界面内持续观察积分与 Token 用量的开发者。本插件以当前 DSH 进程权限运行，仅读写本机 $DSH_HOME 下的账本与本地路由；安装前宜查看 GitHub 仓库 源码与 MIT 许可证。DSH 生态强调「一切皆插件」；SkillHub 目录页 为社区收录站点，与 DeepSeek / 幻方无官方从属关系。

若 dsh-xdpool 调整只读路由，本插件需随上游变更——这是「不重复实现协议」带来的薄封装，也是维护上的耦合点。

结尾¶

dsh-xdpool-billing 把 XD Pool 的余额、消耗与过期信息收到 DSH 输入区旁，减少切页查账的成本；数据与隐私边界清晰：只读本机 dsh-xdpool 路由，账本落盘在本机。

• 目录页：https://www.skillhub.cn/plugins/Xun-Prog/dsh-xdpool-billing
• 源码与说明：https://github.com/Xun-Prog/dsh-xdpool-billing