Zhanxueyou/deepseek-balance

DeepSeek API 余额查询工具

包含两个部分：

1. CLI 工具 check_balance.py：终端查询余额，低余额时 macOS 通知提醒。
2. DSH 侧边栏插件（仓库根即为插件包）：直接嵌入 DeepSeek Harness Web 侧边栏，可视化余额 / 今日用量 / 本月用量 / 缓存命中。

余额查询

一、CLI 工具

查询 DeepSeek 账户的 API 余额，当余额低于阈值时给出醒目提醒，方便你及时充值。

功能

- 展示每个币种的总余额 / 赠送余额 / 充值余额
- 余额低于阈值时红色警告，退出码为 2（便于 cron / 脚本联动告警）
- 多币种支持（CNY / USD 等，跟随账户实际币种）
- --json 输出，方便二次加工
- macOS 通知中心提醒（osascript 实现，无需额外依赖）

依赖

仅 Python 3 标准库，无需安装任何第三方包（macOS / Linux 自带 Python 3）。

配置 API Key（三选一，按优先级）

方式 1：环境变量
export DEEPSEEK_API_KEY=sk-xxxxxxxx

方式 2：本目录下创建 .env 文件
cp .env.example .env   # 然后填入你的 Key

方式 3：全局配置文件
mkdir -p ~/.config/deepseek
echo "sk-xxxxxxxx" > ~/.config/deepseek/api_key

API Key 在 platform.deepseek.com 创建。

使用

基本查询
python3 check_balance.py

自定义低余额阈值（默认 10.0）
python3 check_balance.py --threshold 5

低余额时发送 macOS 通知（会弹出系统通知中心提醒）
python3 check_balance.py --notify

仅低余额时通知（余额充足则静默，适合定时任务）
python3 check_balance.py --notify-only-low

JSON 输出
python3 check_balance.py --json

直接执行（已加执行权限）
./check_balance.py

macOS 通知

- --notify：无论余额如何都发送通知——低余额时红色警告标题「⚠ DeepSeek 余额不足，请及时充值」，余额充足时确认通知。
- --notify-only-low：只在余额低于阈值时通知，余额充足则静默。推荐用于每日定时检查，避免每天被打扰。
- 通知内容为各币种余额摘要，例如「CNY 余额 3.25」。
- 仅支持 macOS（通过 osascript 调用系统通知中心）；其他系统会自动跳过并提示。

退出码

| 退出码 | 含义                     |
| ------ | ------------------------ |
| 0      | 查询成功，余额充足       |
| 2      | 查询成功，余额低于阈值   |
| 1      | 配置 / 网络 / 接口错误   |

定时提醒示例（macOS）

编辑 ~/.zshrc，添加别名：

alias deepseek-balance="python3 /path/to/deepseek-balance/check_balance.py"

配合 cron 每天检查（Linux / macOS），低余额时弹出 macOS 通知提醒充值：

0 9 * * * /usr/bin/python3 /path/to/deepseek-balance/check_balance.py --notify-only-low >> /tmp/deepseek_balance.log 2>&1

低余额时脚本退出码为 2，可据此触发其他告警（邮件、短信等）。

二、DSH 侧边栏插件（仓库根 = 插件包）

把余额与用量仪表盘直接嵌入 DeepSeek Harness Web GUI 侧边栏（底部「DeepSeek 用量」按钮，点击弹出面板）。

展示内容

| 指标 | 来源 |
| ---- | ---- |
| 余额（总 / 充值 / 赠送，多币种） | DeepSeek 官方接口 /user/balance（key 读取 DSH credentials，不出进程） |
| 今日 / 本月 / 全部用量（输入/输出 Token、请求数） | 本机 ~/.dsh/sessions 会话日志聚合 |
| 缓存命中（Token 数 + 命中率 + 进度条） | 会话日志中每次调用的 cacheReadTokens |

- 余额低于阈值（10，可在 lib/client.js 的 LOW_BALANCE_THRESHOLD 调整）时标红并提示充值
- 打开面板时自动刷新，之后每 60 秒自动刷新，也可手动点刷新
- 宿主端数据带 TTL 缓存（余额 60s / 用量 30s）

架构

- 宿主端 lib/index.js：注册同源路由 /dsh-balance-api/stats（仅 loopback + 同源访问），
从 DSH credentials 服务解析 DEEPSEEK_API_KEY 查余额；用量直接扫描本地会话日志
（多帧 zstd 逐帧解码，与 DSH 持久化层算法一致）。
- 浏览器端 lib/client.js：注册进侧边栏 sidebar.footer.action 插槽，弹出面板渲染
数据。仅依赖 DSH 种子模块（react / primitives），无任何第三方依赖。

安装与启用

1. 把插件包符号链接到 DSH 的 node_modules（源码在本目录，改代码即时生效，无需重新安装）：

cd /path/to/deepseek-balance   # 进入项目源码目录（换成你的实际路径）
mkdir -p ~/.dsh/profiles/node_modules
ln -sfn "$(pwd)" \
~/.dsh/profiles/node_modules/dsh-balance-panel

$(pwd) 即当前目录；也可直接把 "$(pwd)" 换成源码目录的绝对路径。
2. 在 ~/.dsh/profiles/web/cordis.patch.yml 注册一行：
- insert:
- id: dsh-balance-panel
name: dsh-balance-panel

3. patch 变更会被 DSH 的配置监听器热加载（无需重启即可注册路由与客户端 bundle）；
宿主端代码的修改需要重启 dsh web 后生效。

验证

- curl http://127.0.0.1:3080/dsh-balance-api/stats — 数据接口
- curl http://127.0.0.1:3080/ | grep dsh-balance-panel — 浏览器启动清单
- 页面刷新后侧边栏底部出现「DeepSeek 用量」按钮

卸载

1. 删除 ~/.dsh/profiles/web/cordis.patch.yml 中对应的 insert 行
2. 删除 ~/.dsh/profiles/node_modules/dsh-balance-panel 链接
3. 重启 dsh web（或等待下次重启自动生效）