# dsh-balance-plugin

> DeepSeek Harness 的余额与用量可视化插件：监控多账户余额、低余额告警、一键充值，复刻 Miyu 风格用量统计，并提供三方插件管理面板。

## Metadata

- Author: [@Francis-Xavier-code](https://github.com/Francis-Xavier-code)
- Repo: <https://github.com/Francis-Xavier-code/dsh-balance-plugin.git>
- GitHub: [Francis-Xavier-code/dsh-balance-plugin](https://github.com/Francis-Xavier-code/dsh-balance-plugin)
- Stars: 53
- Language: JavaScript
- License: [MIT](https://spdx.org/licenses/MIT.html)
- Topics: `dsh`, `dsh-plugin`, `dsh-plugins`, `dsharpplus`, `token`, `wallet`, `webui`
- Forks: 5
- Open Issues: 5
- Last push: 2026-08-15T03:07:54.000Z
- Added: 2026-08-19T00:00:00.000Z

## Install

```bash
dsh plugin --profile web add github:Francis-Xavier-code/dsh-balance-plugin
```

## Wiki

## 一句话定位
为 DeepSeek Harness 装上一组财务与统计仪表盘：监控 DeepSeek API 多账户余额、低余额告警、一键跳转官方充值，并复刻 Miyu WebUI 的用量统计视图，附带三方插件管理面板。

## 核心能力
- 监控 DeepSeek API 多账户余额（CNY / USD 双币池）并按币种独立阈值触发低余额告警（默认 ¥10 / $2，余额条变红、控制台打印警告）
- 一键直达 DeepSeek 官方充值页 `platform.deepseek.com/top_up` 与用量明细页 `platform.deepseek.com/usage`
- 提供 Miyu 风格的用量统计页：1天 / 7天 / 30天 / 至今切换、统计瓦片、GitHub 贡献图风格用量日历、三段堆叠趋势柱状图、模型消耗环形图与明细表、最近 50 条调用记录
- 实时性能指标条：轮次、步数、LLM 时长、工具调用时长、首 token 平均延迟、tok/s、缓存命中率
- 三方插件管理：列出 web profile 下非 `@deepseek-ai` 的所有插件（包名、Bundle rev、依赖、本地路径），macOS 上可一键「打开目录」定位源码
- 注册模型工具 `query_api_quota`，可让 LLM 直接查询 DeepSeek 余额并给出充值提醒

## 技术实现
- **语言**: JavaScript（Node.js + 浏览器端 ES Module / CommonJS bundle）
- **关键依赖**: `@deepseek-ai/dsh` 宿主（cordis 上下文注入 `timer / webServer / clientModules / credentials / sessionQuery / tools / shell / slots`）、浏览器侧 `react`（通过 `require('react')` 从宿主 bundle 复用）、`curl` 命令行（由宿主 `shell` 服务调用）、`window.__ModuleLoader__` 浏览器 bundle 加载器
- **架构模式**: 标准的 DSH 双面（host + client）插件；host 进程通过 `ctx.webServer.register` 注册私有 RPC 路由 `POST /bmon/api/<name>`，client 通过 `fetch` 调用；balance 轮询由 `ctx.interval` 触发；用量统计通过 `ctx.on('session/event')` 实时聚合 + `sessionQuery.readSession` 启动期扫描 90 天历史
- **入口文件**: `lib/index.js`（host）、`lib/client.js`（browser，经 `/plugins/dsh-balance-plugin/client.js` 加载），通过 `cordis.patch.yml` 把自己插入 web profile；仓库根 `host.js` / `client.js` 为动态版同源副本

## 适用场景
日常用 DeepSeek Harness 大量调用官方 API 的用户：想在主界面一眼看到余额还剩多少、避免被低余额卡住；想看自己过去一周 / 一个月的 token 消耗趋势、各模型占比、缓存命中率；想顺手看到当前装了哪些三方 web 插件并定位源码。普通轻度用户只关心余额条与告警，重度用户会用上用量统计与模型工具。

## 前置依赖与兼容性
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| DeepSeek Harness | 未声明 | 插件通过 cordis 注入 `timer / webServer / clientModules / credentials / sessionQuery / tools / shell / slots`，需宿主版本提供这些服务（lib/index.js:5） |
| Node.js | 未声明 | package.json 未声明 engines；宿主 Node 即可 |
| 平台 | 跨平台（macOS） | 余额查询、用量统计、浏览器面板均跨平台；「三方插件打开目录」用 macOS 的 `open -R` 命令，仅 macOS 可用（lib/index.js:535） |
| 原生模块 | 无 | 无 npm 原生依赖；balance 查询通过宿主 `shell` 调 curl，不引入额外原生模块 |

## 安装方式
```bash
dsh plugin --profile web add github:Francis-Xavier-code/dsh-balance-plugin
```

安装完成后重启 DSH，输入框工具行右侧出现三个图标按钮即生效。可选用 `DSH_PROFILE=<name>` 切换到其他 profile。

## 配置项
| 配置 | 类型 | 说明 | 默认值 |
|---|---|---|---|
| 账户列表 | 列表 | 「+ 添加账户」可加多个账户，每个账户有名称与 API Key；空 Key 提交表示保持不变，「清除」按钮可清空已配置的 Key | 空（首次启动时自动读取 DSH 凭据 `DEEPSEEK_API_KEY` 生成一个「自动读取·DSH 凭据」账户） |
| API Key 引用 | 字符串 | 直接填明文 Key，或填 `$env:环境变量名`（如 `$env:DEEPSEEK_API_KEY`），由插件调用前从环境变量展开 | 明文 |
| CNY 告警阈值 | 数字 | 对应币种总余额低于此值时触发低余额告警并标红 | 10 |
| USD 告警阈值 | 数字 | 同上 | 2 |
| 刷新间隔 | 选项 | 余额轮询间隔，从下拉中选择；提交后立即触发一次刷新 | 300000（5 分钟，可选 30 秒 / 1 分钟 / 15 分钟 / 30 分钟） |

## 常见问题

**Q：重启后插件还在吗？**

A：在。静态插件持久安装，重启后仍生效；通过面板手动配置的账户 Key 会重置，但自动读取的 `DEEPSEEK_API_KEY` 账户会在启动时自动恢复（lib/index.js:144）。

**Q：侧边栏底部看不到入口按钮？**

A：DSH 侧边栏底部槽位被官方 Cordis 面板插件独占整行。本插件入口固定在输入框工具行右侧（💰 钱包 / 📊 用量 / 🧩 三方插件）以及输入框下方的常驻余额条，不依赖侧边栏槽位（lib/client.js:799-816）。

**Q：API Key 会泄露吗？**

A：不会。Key 只保存在本机插件进程的内存对象里，界面只显示掩码（…后 4 位），源码与文档中不含任何凭据，curl 通过 Host shell 转发调用、不写入日志（lib/index.js:33-53）。

**Q：余额查询失败怎么办？**

A：看面板里账户行的错误提示：未配置 Key 会显示「未配置 API Key」；用 `$env:` 引用但变量缺失会显示「环境变量名 xxx 未设置」；Key 无效会透出 DeepSeek 返回的 401 / 错误信息（lib/index.js:43-91）。

**Q：用量统计为什么看不到 90 天前的历史？**

A：插件启动时扫描近 90 天的会话事件按 seq 去重聚合，但单次最多读取 60 个会话（lib/index.js:345）。如果会话数超出，会跳过更早的部分；「首 token 平均延迟」只统计插件运行后实时捕获的流式数据。

**Q：为什么不能用 `dsh plugin add dsh-balance-plugin`？**

A：npm 上存在他人同名包（`dsh-balance-plugin@0.1.0`），裸包名会装错版本。安装命令必须用 `github:` 源指向本仓库（README.md:163）。

**Q：怎么卸载？**

A：一键：`curl -fsSL https://raw.githubusercontent.com/Francis-Xavier-code/dsh-balance-plugin/main/uninstall.sh | bash`；手动：`dsh plugin --profile web rm dsh-balance-plugin` 并清理 `~/.dsh/cordis.patch.yml` 里本插件的 `- insert` 块，重启生效。

**Q：三方插件面板里「打开目录」在 Windows 上能用吗？**

A：不能。该功能通过 Host shell 执行 `open -R <路径>`（lib/index.js:535），这是 macOS Finder 专属命令；Windows / Linux 没有 `open`，点击会失败，列表展示本身仍正常用。

## 上手难度
入门 — 装好即默认带一个「自动读取·DSH 凭据」账户，余额条会立刻开始刷新，无需任何额外配置；想加账户或调阈值也是点开面板填两下即可。

## 已知问题与限制
- 三方插件「打开目录」用 macOS `open -R` 命令，Windows / Linux 下不可用（lib/index.js:535）。
- 启动期历史扫描最多读取 60 个会话（lib/index.js:345），90 天内会话数超过 60 的用户可能看到历史用量比预期少。
- 「首 token 平均延迟」仅统计插件运行后实时捕获的流式数据，安装前已发生的会话无法贡献（README.md:161）。
- 余额查询依赖 DeepSeek 官方接口 `api.deepseek.com/user/balance` 与本机 `curl` 命令；离线环境无余额查询能力。
- 浏览器端 client.js 自身 53 KB，注入的样式表约 100 行 CSS，会随插件一起进入页面 bundle（lib/client.js:37-137）。

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [dsh-balance-plugin](https://deepseek-plugin.org/plugins/Francis-Xavier-code/dsh-balance-plugin)
Wiki generated by AI (model: `MiniMax-M3`)