余额用量悬浮面板Aisland-SJL/dsh-usage

🌊 dsh-usage

为 DeepSeek Harness 网页端（dsh web）提供常驻悬浮窗、完全可自定义的余额 / 用量面板、活跃热力图与双边通道用量对比的 bundle 插件。

README-English
License

✨ 功能速览

🌊 常驻悬浮窗

你关心的数字始终可见——余额常绿（欠费才变红），行间细线分隔，右上角 ⚙ 打开详情、↻ 一键刷新；sidebar 收起时自动折叠成一枚小巧的余额胶囊。

- 🟢 余额 — 健康时绿色，欠费时红色
- 📊 今日 / 本月 / 缓存命中 — 一眼尽收的用量数字
- ⚙ 齿轮开详情 · ↻ 一键刷新
- 🧲 与 pin 设置同步 — 每次调整立即生效

🎛️ 详情面板 — 七个 widget 全览

两列卡片布局；每个 widget 都有「详情 + 悬浮」两种表达，支持拖拽排序、折叠、隐藏、pin。

| Widget | 功能 |
| --- | --- |
| 💳 余额 | 左侧大数字 + 右侧「可用 / 充值 / 赠送」三行明细，供应商可切换 |
| 📊 今日用量 | 今日 token 总数 + 输入 / 输出 / 缓存读分桶 |
| 📈 本月用量 | 本月累计 token + 同样的分桶明细 |
| 🎯 缓存命中 | 今日与累计缓存命中率 |
| ↔️ 通道比例 | DSH 通道 vs Claude Code 通道的占比条 |
| 📜 用量记录 | 近 14 天按日列表，点击下钻到模型明细 |
| 🔥 活跃热力图 | 28 天 × 6 时段点块网格（横轴日期，纵轴 0–24 时） |

🎨 一切皆可自定义

主色调（预设色板 + 取色器）、背景色、面板不透明度随时可调；拖拽排序、pin、折叠、隐藏——每个数字都按你的方式呈现，正如 DeepSeek Harness 的「一切皆插件」。

一眼看懂

| | 能力 | 说明 |
| --- | --- | --- |
| 💳 | 常驻悬浮窗 | pinned 项始终可见；sidebar 收起时折叠为余额胶囊按钮 |
| 🎨 | 一切皆可自定义 | 每个 widget 可 pin / 折叠 / 隐藏 / 拖拽排序（虚线占位 + 平滑让位动画）；主色、背景、不透明度可调；设置持久化 localStorage |
| 📊 | 余额与用量面板 | 供应商切换、余额明细、今日/本月总量（k/M/B 紧凑单位）、缓存命中、用量记录与按模型下钻 |
| 🔥 | 活跃热力图 | GitHub 风格点块：28 天 × 6 时段（每格 4 小时）+ 顶部日期标签 |
| ↔️ | 通道比例 | DSH 通道 vs Claude Code 通道（解析 ~/.claude/projects JSONL 增量聚合） |
| 🔄 | 后台刷新 | 启动即刷新，之后每 5 分钟更新余额、DSH Token 与 Claude Code 聚合 |
| 🔒 | 本机安全边界 | 三个端点仅接受回环 GET；凭据只在服务端解析；上游强制 HTTPS、拒绝私网解析并固定 DNS 连接；Claude 日志只聚合数字，对话文本永不落盘 |

界面支持中文和英文。凭据由 Harness 从 ~/.dsh/.credentials.yaml 解析，插件不读取、不缓存、不回传任何密钥。

快速安装

需要 DeepSeek Harness web profile（@deepseek-ai/dsh >= 0.1.0-rc.6）。

dsh plugin --profile web add "github:Aisland-SJL/dsh-usage"

普通安装会按 manifest 自动安装运行时依赖 @deepseek-ai/dsh-client-ui-primitives@0.1.1-rc.2。如果开发时使用 link: 注册本地源码，需要在活动 profile 中安装同一精确版本，因为链接包不会自动补齐 profile 依赖树：

cd ~/.dsh/profiles/web
pnpm add @deepseek-ai/dsh-client-ui-primitives@0.1.1-rc.2 --save-exact

重启 dsh web 并在浏览器硬刷新，左下角出现常驻悬浮窗。更新 / 卸载：

dsh plugin --profile web update dsh-usage
dsh plugin --profile web remove dsh-usage

凭据配置

余额型供应商的凭据引用写在 ~/.dsh/.credentials.yaml：

DEEPSEEK_API_KEY: sk-your-key-here            # DeepSeek 官方路由
OPENROUTER_MANAGEMENT_KEY: sk-or-v1-...       # OpenRouter 账户（需要 Management Key，不是推理 Key）
ZAI_API_KEY: your-zai-key                     # Z.ai 开放平台

Moonshot / Kimi 等 llm-pi-ai 中的 provider profile 会自动发现并复用其 apiKeyEnv。没有公开余额接口的供应商显示「无公开余额接口」，不会猜测。

支持的供应商

| Provider | 上游接口 | 默认凭据引用 |
| --- | --- | --- |
| DeepSeek | GET {origin}/user/balance | DEEPSEEK_API_KEY |
| OpenRouter | GET {origin}/api/v1/credits | OPENROUTER_MANAGEMENT_KEY |
| Moonshot / Kimi | GET {origin}/v1/users/me/balance | pi-ai provider apiKeyEnv |
| Z.ai / 智谱 | GET {origin}/api/paas/v4/balance | ZAI_API_KEY |

API

| Method | Path | Response |
| --- | --- | --- |
| GET | /api/usage/providers | provider 列表、余额 scheme 与状态摘要 |
| GET | /api/usage/balance?provider= | 统一余额快照；refresh=1 强制刷新上游 |
| GET | /api/usage/usage | 按日期/provider/model 聚合的 Token、缓存命中率、24 小时桶（days[].hours）与 Claude Code 通道（claude） |

非 GET 返回 405，非回环请求返回 403；所有响应均为 JSON 并带 Cache-Control: no-cache。

开发与验证

npm install           # 仅 react/react-dom/jsdom 用于离线测试
npm run check         # 全量语法检查
npm test              # 83 个离线测试：余额 scheme、token 折叠、服务端边界、客户端、e2e 交互流、Claude 聚合、发布契约
npm run test:package # 运行时依赖与 client inject 契约

所有测试完全离线，不访问网络、不触碰真实 ~/.dsh（服务端测试重定向 DSH_HOME 到临时目录）。真实 Claude 数据预演：node scripts/validate-claude.mjs。

隐私与安全

- API Key 永不进入浏览器响应、插件缓存或日志；凭据由 Harness credentials seam 在请求时解析。
- 上游余额查询：强制 HTTPS、预解析 DNS 并拒绝回环/私网/链路本地/组播等非公网地址、连接固定到校验过的地址（防 DNS rebinding）、响应上限 1 MiB、超时 15 秒。
- 用量缓存 ~/.dsh/storages/ 只保存聚合 Token 与会话折叠游标，不保存提示词或回复内容。
- Claude Code 日志逐行解析即弃，只有聚合数字进入缓存。
- 请勿将本插件端点经反向代理暴露到局域网或公网。

致谢

- Ychris12138/dsh-usage-stats（MIT）：余额 scheme 与 Token 折叠语义、DSH bundle 插件结构与安全边界的参考实现。

License

MIT