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

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

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

🖼 界面预览（示例数据）

余额徽章与明细弹窗	用量统计（近 7 天每日图表 + 悬停提示框）

---

✨ 功能特性

模块	能力
余额徽章	会话头部右侧常驻：状态圆点 + 当前余额（如 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）。未配置时徽章显示「未配置」并提示。

一键安装

# 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 下均安全；浏览器端只收到解析后的数字。

---

🗑 卸载

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

---

License

MIT