aexachao/dsh-balance-tracker

dsh-balance-tracker 是一个 DeepSeek Harness（dsh）插件：在会话头部实时显示 DeepSeek 账户余额与今日花费，按金额设置提醒阈值，一键跳转充值。由 ai-suifeng/dsh-budget-meter fork 而来（MIT，见下方声明）。

特性

• 真实余额：host 端读取 ~/.dsh/.credentials.yaml 的 DEEPSEEK_API_KEY，调用 DeepSeek 官方余额接口；胶囊显示总余额，展开卡片查看赠送 / 充值分项
• 官方消费统计：配置 DEEPSEEK_PLATFORM_TOKEN 后，从平台用量接口拉取今日消费与累计消费（与官网用量页同源）；未配置时以余额差值估算（前缀 ≈）
• 用量追踪：按 DeepSeek 官方峰谷定价把会话 token 消耗折算成人民币，展示今日 tokens 分项与按模型花费
• 高峰 / 空闲标签：胶囊与卡片显示当前时段（默认北京 09:00–12:00、14:00–18:00 为高峰），带状态圆点；卡片设置区同步展示当前高峰时段（其余时间即为空闲）
• 按金额提醒：今日花费达到阈值（元）弹 toast；可开启「达到阈值自动停止当前回合」
• 充值快捷跳转：卡片「去充值」在系统浏览器打开 DeepSeek 充值页
• 设计一致：胶囊采用 Harness secondaryButton 设计规范，与 session log 按钮同排同款
• 中 / 英双语；74 个单元测试

工作原理

浏览器端胶囊 ──GET /budget/balance──▶ host 插件
                                        │
                                        ├─ DEEPSEEK_API_KEY ──▶ api.deepseek.com/user/balance（真实余额）
                                        │
                                        └─ DEEPSEEK_PLATFORM_TOKEN ──▶ platform.deepseek.com/api/v0/usage/cost
                                           （官方今日/累计消费，当月缓存；token 过期不阻塞余额展示）

• 余额：仅允许本机回环访问；API key 只在 host 进程内使用，绝不下发到浏览器
• 消费：官方源优先；无 platform token 时按「当天零点余额 − 当前余额」估算，持久化于 ~/.dsh/storages/
• 用量：client 订阅当前会话快照，按 sessionId:messageId|seq 去重计费并持久化到 localStorage——重开会话、重启应用不重复计费；统计固定按自然日

快速开始

1. 安装到 profile

在 ~/.dsh/profiles/web/package.json 中加入并安装（或使用 dsh plugin --profile web add <path>）：

{
  "dependencies": {
    "dsh-balance-tracker": "link:/绝对路径/dsh-balance-tracker"
    // ...其它依赖
  },
  "dsh": {
    "profile": {
      "bundles": [ /* ...其它 bundle */, "dsh-balance-tracker" ]
    }
  }
}

cd ~/.dsh/profiles/web && pnpm install

2. 配置凭证

在 ~/.dsh/.credentials.yaml 中：

DEEPSEEK_API_KEY: sk-xxx            # 必需：余额查询
DEEPSEEK_PLATFORM_TOKEN: xxx        # 可选：官方累计/今日消费

DEEPSEEK_PLATFORM_TOKEN（platform.deepseek.com 登录态的 userToken）两种获取方式：

自动探测（推荐）——登录 platform.deepseek.com 后，运行：

pnpm read-token     # 扫描本机 Chrome / Edge / Brave / Arc 等的 Local Storage，
                    # 提取 userToken 并写入凭证文件（不打印、不上传）

手动——浏览器开发者工具 → Application → Local Storage → 复制 userToken 值。

不配置时「今日已花费」为余额差值估算（≈），「累计（含往期）」隐藏。

3. 生效

重启 profile / 应用，浏览器 Cmd+Shift+R 强刷。顶部 session log 按钮左侧出现余额胶囊。

配置

默认值可通过 profile patch 的插件 config 覆盖；卡片设置区可再覆盖并持久化到 localStorage：

warnYuan: 20          # 今日花费提醒阈值（元），达到即弹 toast
stopOnOver: true      # 达到阈值时自动取消当前回合（每周期一次）
peakWindows: '09:00-12:00,14:00-18:00'   # 高峰窗口，北京时间，逗号分隔 HH:MM-HH:MM
pricingTimezone: Asia/Shanghai

开发

pnpm install
pnpm typecheck   # 双 program（host + client）
pnpm build       # tsc host → tsc client → tsdown
pnpm test        # 构建后跑 node --test（74 用例：端点契约 / platform 聚合 / pricing / usage / ledger / client bundle）

边界与限制

• 余额与消费统计为 DeepSeek 账户官方数据；「今日 tokens」「按模型」为本客户端打开过的会话消耗（框架无跨会话聚合面）
• 无 platform token 时「今日已花费」为余额差值估算，不反映官网账单精确值；token 过期需重新登录复制
• 历史回放节点不带模型身份时按 flash 价计（宁晚提醒不早报）；中断未 finalize 的请求不计费（保守少计）
• 余额接口偶发限流/超时由 10 秒超时 + 每 60 秒轮询自然恢复

开源与许可

本项目为 ai-suifeng/dsh-budget-meter 的自维护 fork，基于上游 MIT License 修改：

• 上游版权与许可声明见仓库 LICENSE（Copyright (c) 2026 ai-suifeng），fork 修改保留该声明
• fork 在保留原版「用量追踪」功能（高峰/空闲、tokens 统计、按金额阈值提醒、超额自动停止）的基础上，新增真实余额、官方消费统计与充值跳转
• 修改部分同样以 MIT 许可发布；再次分发时请保留上游版权与许可文本