ZHIZHU4410/deepseek-balance

DeepSeek 余额监控（dsh 内嵌版 · dsh-balance v2）

license
version
platform

一个运行在 DeepSeek Harness（dsh）内的余额监控插件：余额胶囊直接镶嵌在
dsh 侧边栏底部（sidebar.footer.action 原生槽位，随 dsh 布局一起出现/收起），
采用 TransparentUI 风格的玻璃质感（半透明 + 背景模糊 + 细描边），实时显示
DeepSeek 账户余额 / 额度使用比例。按北京时间峰/闲时段自动切换配色
（工作日峰时 09:00–12:00、14:00–18:00；2026-08-23 起周末全天按低谷价、
不再区分峰谷），余额不足红色闪烁，
30 秒自动刷新；点击胶囊原位浮出玻璃详情面板（详情 / 配置 / 凭据）。

- lib/index.mjs — Host 数据层（官方余额 API + 平台会话用量、凭据读取、配置管理、子进程 HTTP、connection RPC）
- client/client.js — Browser 侧 UI（sidebar.footer.action 内嵌胶囊 + portal 详情面板，TransparentUI 玻璃风格）
- cordis.patch.yml / package.json — 标准 dsh bundle 插件清单（随 dsh web 启动自动加载）
- README.md — 本文件（安装 / 部署 / 配置说明）

v2 变化（相对 v1）

| | v1（右下角悬浮） | v2（内嵌） |
| --- | --- | --- |
| 位置 | shell.overlay 悬浮层，右下角固定浮层 | sidebar.footer.action，dsh 侧边栏底部操作区（设置按钮上方） |
| 形态 | 242px 悬浮进度条 | 玻璃胶囊（状态点 + 余额 + 剩余比例）；侧边栏收起成窄栏时自动缩成状态圆点 |
| 交互 | 悬停展开 | 点击胶囊原位浮出详情面板（点击外部 / Esc / 滚动自动关闭） |
| 风格 | 深色实底卡片 | TransparentUI 风格玻璃：半透明面 + backdrop-filter 模糊 + 细描边 + 内高光，文本/描边跟随 dsh 主题 token（--dsw-），与透明主题插件（TransparentUI / aqua 等）自动融合 |
| 数据层 | 不变 | 不变（同 RPC 通道 /dsh-balance，配置/凭据完全兼容 v1） |

升级方式：直接替换插件目录后重启 dsh web 即可；v1 保存的配置
（deepseek-balance.json / 凭据库键）原样沿用。

一、数据来源与登录态

| 数据 | 来源 | 需要的凭据 |
| --- | --- | --- |
| 余额 | 官方公开 API：GET https://api.deepseek.com/user/balance（Authorization: Bearer ），响应含 balance_infos[].total_balance / granted_balance / topped_up_balance | DEEPSEEK_API_KEY（首选） |
| 余额（备选） | 平台会话私有 API：GET https://platform.deepseek.com/api/v0/users/get_user_summary（钱包 normal_wallets + bonus_wallets） | DEEPSEEK_PLATFORM_TOKEN（userToken） |
| 今日已用（官方） | GET https://platform.deepseek.com/api/v0/usage/cost?month=&year=（按天返回消耗） | DEEPSEEK_PLATFORM_TOKEN |
| 今日已用（兜底） | 本地余额差值估算（max(0, 当日开盘余额 − 当前余额)，状态存于 deepseek-balance-day.json） | 无 |

登录态处理：HTTP 401/403 或平台错误码 40002/40003 视为登录失效，胶囊显示
灰色「未登录/需重新登录」，绝不显示错误的进度。网络错误 / 解析失败同样显示灰色，
并在详情面板里给出具体原因。

凭据安全：不使用任何硬编码密码/Cookie。凭据统一放在 dsh 凭据库
（credentials 服务，默认文件 ~/.dsh/.credentials.yaml），也可以直接在启动 dsh
的环境里设置同名环境变量（环境变量优先于文件）。

若在凭据库（~/.dsh/.credentials.yaml）或环境变量中配置了 DEEPSEEK_API_KEY，
插件开箱即用即可通过官方余额 API 显示余额；平台 userToken 可选，
用于官方「今日已用」明细。

如何获取 userToken（可选步骤）

1. 浏览器登录 https://platform.deepseek.com
2. 打开用量页 https://platform.deepseek.com/usage
3. F12 → Application → Local Storage → https://platform.deepseek.com
4. 复制键 userToken 的值
5. 粘贴到 详情面板 → 凭据 页 → 「保存 userToken」（会写入 ~/.dsh/.credentials.yaml）；
或手动执行 dsh 侧写入 / 编辑 ~/.dsh/.credentials.yaml 增加
DEEPSEEK_PLATFORM_TOKEN: ，重启 dsh 生效。

二、安装 / 部署（持久化 bundle 插件）

本插件是标准 dsh bundle 插件（与 dsh-pocket 同机制），装入 web profile 后
每次启动 dsh web 自动加载，余额胶囊自动出现在侧边栏底部，无需每次手动启用。

安装（本机已完成，供其他环境参考）

1. 将本目录（dsh-balance 包）复制到目标机器
2. 在 web profile 的 package.json 中注册本地依赖 + bundle：
dependencies:  "dsh-balance": "file:"
dsh.profile.bundles: 追加 "dsh-balance"
3. 在 profile 目录执行：pnpm install -w
4. 重启 dsh web

以本机为例：
- 包目录：C:\Users\10113\Desktop\deep\deepseek-balance
- profile：C:\Users\10113\.dsh\profiles\web\package.json
- dependencies 增加 "dsh-balance": "file:../../../Desktop/deep/deepseek-balance"
- dsh.profile.bundles 增加 "dsh-balance"
- 执行 pnpm install -w 后重启 dsh web

更新插件：编辑上面的包目录后重启 dsh web 即可生效。
本机 profile 的 node_modules\dsh-balance 已由旧拷贝改为 junction（目录联接，
指向本包目录，编辑即同步）；若之后执行过 pnpm install -w 且 pnpm 把它重建为
独立拷贝，需重新同步文件或重建 junction（见下方说明）。

临时运行（可选，调试用）

也可以按动态插件方式在会话内临时运行：让助手 cordis_define（code.host 用
lib/index.mjs 的 apply 逻辑、code.client 用 client/client.js 的组件逻辑）
再 cordis_run。动态版仅存在于当前进程，重启即消失——需要常驻请用上面的 bundle 安装。

运行前提：本机装有 Node.js ≥ 18（dsh 本身即运行于 Node，通常已满足）。
插件通过 subprocess 服务以 node -e 子进程执行鉴权 HTTP 请求，不占用主进程网络栈。

三、配置说明

配置优先级：环境变量 > dsh 凭据库（界面保存） > 配置文件（手动编辑） > 内置默认值。

- 界面保存（胶囊 → 详情面板 → 配置 → 保存配置）：优先写入配置文件
$DSH_HOME/storages/deepseek-balance.json；若 dsh 的 fs 策略为只读导致写文件失败，
自动改写到 dsh 凭据库（~/.dsh/.credentials.yaml 的 DEEPSEEK_BALANCE_CONFIG 键，
dsh 安全存储，不受 fs 策略限制），保存提示会注明实际落点。
- 手动编辑：直接在配置文件中改 JSON（读取不受只读策略影响）。
- 环境变量：启动 dsh 的 shell 中设置，优先级最高、跨重启持久。

配置文件路径（若可写则自动生成）：$DSH_HOME/storages/deepseek-balance.json
（默认 C:\Users\\.dsh\storages\deepseek-balance.json）。

{
"refreshIntervalSec": 30,     // 自动刷新间隔（秒），范围 5–3600
"lowRatioThreshold": 0.1,     // 余额不足：余额占参考总额度比例低于 10%
"lowAmountThreshold": 10,     // 余额不足：余额少于 10 元
"quotaTotal": 0,              // 参考总额度（元）：0 = 自动推算
"colors": {
"low":   "#e5484d",         // 余额不足（红，含闪烁）
"peak":  "#f5b301",         // 峰时（黄）
"valley":"#2ecc71",         // 空闲时段余额充足（绿）
"gray":  "#9aa0a6"          // 未登录 / 网络错误（灰）
}
}

常用修改示例

- 改刷新频率：把 refreshIntervalSec 改成 60（每分钟一次）；或设置环境变量
DEEPSEEK_BALANCE_REFRESH_SEC=60。
- 改余额阈值：如「余额低于 20 元或低于总额度 15% 即红色闪烁」→
lowAmountThreshold: 20、lowRatioThreshold: 0.15。
- 改颜色：编辑 colors 四项为任意 CSS 颜色值（胶囊圆点 / 详情面板进度条跟随）。
- 参考总额度（进度条 100% 基准）：
- quotaTotal > 0：进度 = max(0, quotaTotal − 余额) / quotaTotal（如充值总额）；
- quotaTotal = 0（自动）：有平台 token 时 总配额 = 今日已用 + 余额，
否则用「当日开盘余额」作为总配额估算。

说明：未配置 DEEPSEEK_PLATFORM_TOKEN 时，「今日已用」走余额差值估算
（当日开盘余额 − 当前余额）；开盘基线持久化在 dsh 凭据库
（DEEPSEEK_BALANCE_DAYSTATE，跨刷新/跨重启有效，不受 fs 只读策略影响）。
当日首次抓取基线即当前余额（今日已用 0），之后随消耗显示真实差值。
「已用额度」统一为 总配额 − 余额；无法推算时显示 —（不再错误显示 0）。
配置平台 token（官方用量）或设置 quotaTotal（充值总额度）可得到更精确口径。

环境变量一览（在启动 dsh 的 shell 中设置）

| 变量 | 说明 | 默认 |
| --- | --- | --- |
| DEEPSEEK_API_KEY | DeepSeek API Key（官方余额 API） | —（也可放凭据库） |
| DEEPSEEK_PLATFORM_TOKEN | platform.deepseek.com 的 userToken | — |
| DEEPSEEK_BALANCE_REFRESH_SEC | 刷新间隔（秒） | 30 |
| DEEPSEEK_BALANCE_LOW_RATIO | 余额低比例阈值（0–1） | 0.1 |
| DEEPSEEK_BALANCE_LOW_AMOUNT | 余额低金额阈值（元） | 10 |
| DEEPSEEK_BALANCE_QUOTA_TOTAL | 参考总额度（元，0=自动） | 0 |

四、颜色与峰谷规则

- 峰时（工作日 09:00–12:00、14:00–18:00 北京时间）：黄色 #f5b301
- 空闲时段且余额充足：绿色 #2ecc71
- 余额不足（余额  峰时黄 > 空闲绿*（未登录/异常为独立灰色态，不参与配色竞争）

峰谷口径（2026-08-23 北京时间 00:00 起生效的新规）：
- 工作日（周一至周五）：高峰时段为北京时间 09:00–12:00、14:00–18:00，
其余为空闲时段（原规则，不变）；
- 周末（周六、周日）：全天不再区分峰谷，统一按低谷时段价格计费，
插件判定为永不峰时（始终绿色空闲态）；
- 2026-08-23 凌晨之前仍按原「每日峰谷分段」规则判定（周末同样有峰时）；
- 统一按北京时间（Asia/Shanghai）判定星期与小时，与机器时区无关；
不区分节假日与调休（公告口径只有「周末」，插件按自然周六/周日处理）。

五、交互

- 胶囊（侧边栏底部）：状态圆点（当前配色发光）+ 余额数值 + 「剩余 N%」；
余额不足时整体红色闪烁；侧边栏收起为窄栏时自动缩成一颗状态圆点。
悬停显示完整提示（余额 / 剩余比例 / 错误原因）。
- 点击胶囊：在原位上方浮出玻璃详情面板（详情 / 配置 / 凭据 三个页签）：
- 详情：余额大数字 + 峰/闲/低徽章 + 已用迷你进度条 + 总配额 / 已用额度 / 今日已用 /
剩余比例 / 已用比例 / 峰时段 / 数据来源 / 最后更新时间（+ 赠送额度），
以及总配额快捷设置；
- 配置：刷新间隔、总配额（0 = 自动推算）、余额阈值、四态配色取色器，保存后立即生效；
- 凭据：管理 API Key 与平台 userToken（写入 dsh 凭据库）。
- 面板底部：刷新（立即抓取）+ 打开用量页（platform.deepseek.com/usage）。
- 关闭面板：点击面板外部 / 按 Esc / 滚动页面或侧边栏 / 缩放窗口。
- 自动刷新：默认每 30 秒一次（仅页面打开时轮询，定时器随组件卸载自动清理，低 CPU 占用）。

六、性能与异常

- 抓取由独立 node -e 子进程完成，单次 15 秒超时，失败不阻塞主进程；
- 结果带 30 秒缓存 + 在途请求合并，避免并发重复抓取；
- 所有外部调用均有 try/catch，异常统一落为灰色 + 原因提示；
- 子进程退出即回收，不残留句柄；
- UI 为 dsh 原生槽位组件：随 dsh 布局缩放/收起，不遮挡任何主界面内容。