EdwinZDZ/dsh-api-balance-ring

API Balance Ring · API 余额圆环

一个住在 DeepSeek Harness 输入框里的实时 API 余额小仪表。 悬停圆环看实时余额，点击查看今日消费金额、请求次数与 Token 消耗 —— 按模型计价，数据直接来自你的真实会话日志。

🇬🇧 English README

Demo

✨ 亮点

- 🔴 余额一目了然 —— 发送按钮左侧的进度圆环，与内置的上下文占用圆环完全同款。弧长 = 余额 / ¥50（满圈 = 50 元），颜色随余额变化：绿 → 橙 → 红。
- 🖱 悬停即见 —— 光标碰到圆环立刻显示 API余额￥6.45。
- 📊 点击展开 —— 明细面板：今日消费金额、API 请求次数、消耗 Tokens，附带更新时间。每 60 秒自动刷新，点击时立即刷新。
- 🧮 按请求计价，而非按天 —— 每条请求按会话日志中记录的 deepseek-v4-flash 或 deepseek-v4-pro 官方费率单独计价，会话中途切换模型也准确无误。
- ⏱ 峰谷计价已内置 —— 官方峰谷定价（2026-08-16 起生效）按请求时刻自动切换费率。
- 🔒 只统计 deepseek-official —— 其他 provider（如阿里云 pi-ai 模型）的用量不会混入你的 DeepSeek 账单。
- 🎨 原生观感 —— 与产品内置圆环同槽位、同几何、同主题 token。零依赖、纯 JavaScript、无需构建。

🖼 截图

三个状态 —— 闲置、悬停、点击展开：

Idle · Hover · Panel

明细面板特写：

Panel

🧩 工作原理

┌───────────────────────────── 浏览器（Client 端）─────────────────────────────┐
│  conversation.input.right 槽位（输入框工具行，发送按钮左侧）                    │
│  ┌───────────────────────────────────────────────────────────────────────┐  │
│  │  BalanceRing 组件                                                      │  │
│  │   ┌─────────────────────────────────────┐    host.call('api-balance') │  │
│  │   │ 圆环 + 提示 + 面板 ◀────────────────┼──────────────────────┐      │  │
│  └───┴─────────────────────────────────────┘                      │      │  │
└────────────────────────────────────────────────────────────────────┼──────┘
│ JSON-RPC
┌─────────────────────────────── Host 进程 ──────────────────────────┼──────┐
│                                                                     ▼      │
│  harness.handle('api-balance')     → GET https://api.deepseek.com/user/balance│
│                                       （Authorization: Bearer $DEEPSEEK_API_KEY）│
│                                                                             │
│  harness.handle('api-usage-today') → 扫描全部会话日志（sessionQuery）          │
│                                        · 统计今日 assistant/message 次数      │
│                                        · 累加 input + output + cache tokens   │
│                                        · 按每条请求的模型（request/header 事件）│
│                                          与 UTC 时刻查询费率并计价             │
└─────────────────────────────────────────────────────────────────────────────┘

📦 安装

前置条件

- 本地运行的 DeepSeek Harness Web 界面。
- 已配置 DeepSeek API Key（DEEPSEEK_API_KEY 凭据，存于 ~/.dsh/.credentials.yaml 或环境变量）。

步骤

1. 在 Harness Web 界面打开 开发者 → 动态插件 → 新建。
2. 名称：API 余额圆环（随意）。
3. Host 代码：粘贴 plugin/host.js 的完整内容。
4. Client 代码：粘贴 plugin/client.js 的完整内容。
5. 创建插件并点击运行，在界面中批准激活请求。
6. 圆环即刻出现在输入框发送按钮左侧。

动态插件是进程级的，Harness 重启后需要重新创建。若希望常驻，可把两份文件并入你自己的 agent preset。

🎯 使用

| 操作 | 结果 |
| --- | --- |
| 悬停圆环 | 提示气泡显示实时余额，如 API余额￥6.45 |
| 点击圆环 | 面板：余额 + ¥50 进度条 + 今日消费/请求/Token |
| 点击其他区域 / Esc | 关闭面板 |
| 自动 | 每 60 秒刷新；点击圆环也会立即刷新 |

圆环弧长 = 余额 ÷ ¥50（满圈 50 元）。颜色阈值：≥¥5 绿色、≥¥1 橙色、<¥1 红色。

🧮 数据与准确性

| 数据 | 来源 |
| --- | --- |
| 余额 | 官方 https://api.deepseek.com/user/balance 接口，用已存 DEEPSEEK_API_KEY 认证 |
| 请求次数 / Tokens | 你自己的会话日志 —— 每条 assistant/message 事件都带真实 API 用量（inputTokens、outputTokens、cacheReadTokens） |
| 消费金额 | 官方按模型费率 × 请求时刻（当前平价；2026-08-16 起峰谷），按固定美元兑人民币汇率折算 |

费率表（美元 / 每百万 tokens）

| 模型 | 缓存命中输入 | 未命中输入 | 输出 |
| --- | ---: | ---: | ---: |
| deepseek-v4-flash | $0.0028 | $0.14 | $0.28 |
| deepseek-v4-pro | $0.003625 | $0.435 | $0.87 |

2026-08-16 16:00 UTC 起启用峰谷计价（高峰为 UTC 01–04 与 06–10 时，低谷为高峰的一半），插件按每条请求的时刻自动选价。

统计口径

- ✅ 只统计 provider === 'deepseek-official' 的请求 —— 只有这些会扣你的 DeepSeek 余额。
- ✅ deepseek-v4-flash 与 deepseek-v4-pro 逐条计价，会话中途切换模型，两侧都按各自费率计算。
- ✅ 「今日」= 本地自然日（00:00 至今）。
- ⚠️ 若某条请求使用了费率表外的模型，金额前会显示 ~ 前缀 —— 宁可少算也不静默报错。
- ⚠️ 美元兑人民币汇率是固定常量（6.76）——官方以美元计价，人民币数字与平台自身换算可能有约 1% 偏差。

⚙️ 配置

所有可调项都在各文件顶部的 CONFIG 块里。

| 常量 | 文件 | 默认值 | 含义 |
| --- | --- | --- | --- |
| referenceBalance | client.js | 50 | 圆环/进度条满格的金额（¥） |
| refreshMs | client.js | 60000 | 后台刷新间隔（毫秒） |
| warnBelow / dangerBelow | client.js | 5 / 1 | 圆环颜色阈值（¥） |
| tooltipDelayMs | client.js | 200 | 悬停提示延迟（毫秒） |
| usdCnyRate | host.js | 6.76 | 美元兑人民币汇率 |
| PRICING | host.js | — | 按模型费率表（新模型在此添加） |
| PRICING_EFFECTIVE | host.js | 2026-08-16T16:00Z | 峰谷计价生效时刻 |

❓ 常见问题

为什么面板金额前有 ~？ 有请求使用了费率表外的模型（如刚发布的新版本）。请求次数与 Tokens 照常统计，金额标记为近似值。

为什么我的「今日」比平台后台少？ 插件读取的是 Harness 自己的 会话日志。其他工具或直接调 API 的用量不在日志里；另外日期边界口径的细微差异也可能差几次请求。

API Key 会泄露吗？ 不会。Key 运行时从 Harness 凭据库解析，只出现在余额请求的 Authorization 头里，本仓库不含任何密钥。

切换到 deepseek-v4-pro 后数据还准吗？ 准 —— 这正是按请求计价的原因。在设置里切换默认模型，消费金额立即按 Pro 费率重算。

🚧 已知限制

- 动态插件是进程级的，Harness 重启后需重新创建（见安装说明）。
- 汇率是常量而非实时报价。
- 用量来自会话日志 —— 反映 Harness 内的消耗，而非整个 API 账号。

🤝 贡献

欢迎 PR！我们期待的方向：

- 实时拉取美元兑人民币汇率（轻量报价接口）。
- 配置界面（满格金额、阈值），替代代码常量。
- 可安装的静态插件包，让圆环重启后依然存在、无需重新粘贴。

请保持插件两端零依赖，以便始终可粘贴使用。

📄 许可证

MIT © EdwinZDZ

视觉语言（圆环几何、面板表面、提示气泡）借鉴自 DeepSeek Harness 内置的上下文占用圆环，MIT 许可。