ds-balance

Readme

# 💰 ds-balance — DeepSeek 官方余额徽章

**DeepSeek Harness (DSH) 插件**：会话头部常驻余额徽章 · 余额明细 · 用量统计 · 历史回填 · 站内充值浮窗（官方收银台）· 自动刷新与低余额预警

不使用小浮窗常驻卡片，余额以**会话顶部右侧徽章**形式嵌入界面（🟢 绿点 / 🟡 预警 / 🔴 异常），点击即可查看明细、用量与充值入口。

## 🖼 界面预览（示例数据）

| 余额徽章与明细弹窗 | 用量统计（近 7 天每日图表 + 悬停提示框） |
| --- | --- |
| ![余额明细弹窗](docs/screenshot-popover.png) | ![用量统计弹窗](docs/screenshot-usage.png) |

---

## ✨ 功能特性

| 模块 | 能力 |
| --- | --- |
| **余额徽章** | 会话头部右侧常驻：状态圆点 + 当前余额（如 `DeepSeek ¥88.69`）；绿=正常、黄=低于预警线（¥10 / $2）、红=余额不可用或查询失败；正常每 5 分钟自动刷新，低余额时加密到 1 分钟，失败 30 秒重试 |
| **余额明细** | 点击徽章弹出：总余额、充值/赠送拆分、可用状态、更新时间、今日/近 7 天用量概览 |
| **用量统计** | 监听 DSH 会话事件（`assistant/message` 携带官方 usage 数据），按**天 × 小时 × 模型**聚合：API 请求次数、输入（命中缓存/未命中缓存）、输出 Tokens、轮次/步骤/工具调用 |
| **用量详情弹窗** | 区间切换（今日 / 近 7 天 / 近 30 天）；**今日=24 小时堆叠柱状图**（HH:00 标签）；**近 7/30 天=每日堆叠柱状图**（官方平台样式：M/D 日期标签、柱顶总量标注）；悬停任意位置弹出官方同款提示框（完整日期/时段 + 总 Tokens + 三项精确拆分 + 请求数） |
| **消费估算** | 按 DeepSeek 官方价目（内置 v4-flash / v4-pro 双价表，含 **8/17 峰谷调价**：北京高峰 9-12/14-18 为高峰价、其余半价；之前为平价）由 Token 用量推算，界面标注「估算」 |
| **按模型拆分** | 每个模型一行：彩色圆点 + 名称 + 请求/Tokens/消费 + 消费占比条（V4 Flash / V4 Pro） |
| **每日明细表** | 日期、请求、输入·命中、输入·未命中、输出、消费，逐日列出 |
| **历史回填** | 启动时自动回填最近 15 个会话、30 天；弹窗右上角「**回填历史**」一键深度回填**最长 90 天、最多 60 个会话**，数据缺口自动提示 |
| **充值浮窗** | 「充值」打开站内浮窗：当前余额、金额预设（¥10/50/100/200/500）+ 自定义，确认后前往 **DeepSeek 官方收银台**（支付宝/微信）完成支付，到账后自动刷新 |

---

## 📥 安装（永久常驻）

### 前提

本机已配置 `DEEPSEEK_API_KEY` 凭证（DSH 凭证库，如 `~/.dsh/.credentials.yaml`）。未配置时徽章显示「未配置」并提示。

### 一键安装

```bash
# 1. 安装依赖（web profile）
dsh plugin --profile web add <本仓库路径或 github:Lateautumns/ds-balance>

# 2. 重启 DeepSeek Harness
```

重启后打开任意会话，顶部右侧即出现余额徽章。

> 说明：本包通过 `dsh.bundle.patch` 挂载 Host 半端（`cordis.patch.yml` 注入 `ds-balance` 行），
> 通过 `dsh.client` 加载 Client 半端（web 平台、立即生效）。重启后两者自动就位，无需手动改配置。

### 会话内动态试用（临时）

在任意会话中让 agent 加载仓库根 `host.js` + `client.js`（动态 Cordis 插件形态，
`cordis_define` / `cordis_run`），无需安装即可体验；**注意动态插件随 DSH 进程重启而失效**，
长期使用请用上面的静态安装。

---

## 🎮 使用说明

1. **查看余额**：会话顶部右侧徽章直接显示余额，圆点颜色表示健康状态
2. **余额明细**：点击徽章 → 总余额 / 充值 / 赠送 / 可用状态 / 今日与近 7 天用量概览
3. **用量详情**：点「用量详情」→ 切换区间：
   - **今日**：24 小时堆叠柱状图（输出/输入未命中/输入命中），悬停显示 `HH:00 ~ HH:59` 精确拆分
   - **近 7 天 / 近 30 天**：每日堆叠柱状图，M/D 日期标签，悬停显示 `2026-08-10` 完整日期拆分
   - 底部：本期合计拆分行、按模型拆分（消费占比）、每日明细表
4. **补齐历史**：若显示「当前仅 X/Y 天有数据」，点右上角「**回填历史**」补全最长 90 天
5. **充值**：点「充值」→ 选金额（预设或自定义）→ 「前往官方收银台支付」→ 支付宝/微信完成付款 → 返回后余额自动刷新

---

## 🏗 架构

```
host.js / client.js        动态版（会话内 cordis_define 用；RPC: harness.handle + host.call）
lib/index.js               静态版 Host（安装后用；RPC: webServer 路由 POST /ds-balance/api/*）
lib/client.js              静态版 Client（ModuleLoader bundle；fetch 调路由）
cordis.patch.yml           bundle layer：把 host 行注入组合
```

**RPC 通道**（动态版 / 静态版一一对应）：

| 方法 | 说明 |
| --- | --- |
| `ds-balance:get` / `api/get` | 查询官方余额（`https://api.deepseek.com/user/balance`） |
| `ds-balance:usage` / `api/usage` | 用量聚合（区间参数 1d/7d/30d/all；返回每日/每时/每模型聚合） |
| `ds-balance:backfill` / `api/backfill` | 深度回填历史（参数 days≤90、sessions≤60） |

**数据流**：Host 监听 `session/event`（`assistant/message` 携带 usage）→ 按北京时区聚合
`perDay` / `perHour` / `perModel`（保留 90 天）→ 查询时按区间切片返回 → Client 绘图。

**浮层层级**：徽章在「会话头部右侧」槽位；全部浮层（余额弹窗/充值/用量详情）在
`shell.overlay` 槽位（产品全屏浮层层，z:20，高于聊天区内任何元素 z≤10），
避免聊天内容「复制」工具条等元素压在弹窗之上；两个槽位通过轻量 store 同步状态。

---

## ⚙️ 配置与口径

- **凭证**：`DEEPSEEK_API_KEY`（DSH 凭证库），密钥只在 Host 进程内用于 curl，**永不进入浏览器**
- **预警阈值**：¥10 / $2（代码常量 `LOW_CNY` / `LOW_USD`，可自行修改）
- **刷新频率**：正常 5 分钟 / 低余额 1 分钟 / 失败 30 秒重试（代码常量）
- **价格表**：内置 8/17 前平价与 8/17 后峰谷价两档（`PRICE_TABLES`），按事件时间自动选择；
  消费为**估算**，实际以官方账单为准
- **回填上限**：90 天（与 DSH 会话日志保留期一致；更早的旧日志通常已被压缩清理，无法恢复）

---

## ❓ 常见问题

**Q：为什么近 30 天只有几天有数据？**
插件只统计激活后的事件 + 启动时轻量回填（15 会话/30 天）。点用量详情右上角「**回填历史**」
可深度补全最长 90 天。若某天日志中确无事件，该天为 0。

**Q：弹窗会被聊天区的「复制」条遮挡？**
已修复：浮层全部迁移到 `shell.overlay` 槽位（z:20），聊天区元素（z≤10）无法再压住弹窗。

**Q：查询命令为什么以 danger-full-access 运行？**
Windows ACL 沙箱 runner 在部分机器不可用（temp 在工作区内），且 `web.fetch` 不支持自定义
Header（无法携带 Bearer 认证），因此查询走 `shell` + `curl`，显式以
`sandboxPolicy.resolve({ mode: 'danger-full-access' })` 运行；命令为固定 curl（硬编码官方
URL + 单引号包裹的密钥），无注入面。

**Q：密钥安全吗？**
密钥从 DSH 凭证库读取，只在 Host 进程内使用；DeepSeek 的 `sk-` 密钥只含十六进制字符，
单引号内联进 curl 参数在 pwsh 与 bash 下均安全；浏览器端只收到解析后的数字。

---

## 🗑 卸载

```bash
dsh plugin --profile web rm ds-balance
# 并从 cordis.patch.yml 移除 ds-balance 行（若安装脚本未自动清理）
```

---

## License

MIT