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）：
{
"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 许可发布；再次分发时请保留上游版权与许可文本
