# dsh-balance（DeepSeek 余额查询）

[English](README.md) | 中文

![awesome · DSH plugin](https://awesome-dsh-plugin.com/badge.svg)

[deepseek-harness](https://github.com/deepseek-ai/deepseek-harness)（`dsh`）的组合插件（Host + Web Client 双半）：
查询 DeepSeek 开放平台账户余额，并估算当前会话的消耗金额。通过 `dsh plugin add` 安装。

![1786767848384](image/README.zh/1786767848384.png)

![1786767084496](image/README.zh/1786767084496.png)

![1786898960860](image/README.zh/1786898960860.png)

## 功能

- **余额查询**：调用官方 `GET https://api.deepseek.com/user/balance`，复用 harness 自身的
  `DEEPSEEK_API_KEY` 凭据（与 Models 页同一把）。密钥只经有界 node 子进程的 stdin 传递，
  不进入命令行、日志或任何输出。
- **当前会话消耗估算**：从会话日志折叠 provider 上报的 token 用量（未命中输入 / 缓存命中 / 输出），
  按官方价目表逐步骤计价（按北京时间峰谷价，高峰 9-12 / 14-18，其余为「空闲」）。
  **仅为估算，以官方账单为准。**
- **顶栏徽章**（会话头部）：`余额 ¥x | 会话 ≈¥y`，点击刷新；悬停 500ms 显示明细气泡
  （按钮正下方、水平居中、视口边缘自动夹紧）。
- **设置页**（设置 → DeepSeek 余额）：余额明细、自动刷新开关、自动刷新间隔下拉
  （15 秒 … 5 分钟或自定义）、界面语言下拉（跟随主界面 / 中文 / English）、可编辑价目表
  （空闲 / 高峰 × 模型）。改动持久化于设置文档，重启不丢。
- **模型工具**：`deepseek_balance`——余额 + 调用方会话的预估消耗。
- **暂停自动查询**：连续 2 个刷新周期无新对话（user/assistant 消息）后暂停自动查询
  （转为 5 分钟低频探测）；出现新对话后自动恢复活跃刷新。自动刷新也可手动开关
  （设置页开关或 `/dsh-balance auto-refresh <on|off>`），关闭后不再发起查询。
- **完全自包含**：部署无需修改宿主仓库任何代码（通信走内置 `commands` Remote 命名空间）。

## 安装

标准方式（bundle 安装，推荐）：

```sh
dsh plugin --profile web add @lemcae/dsh-balance
```

安装器把包加入 web profile 的依赖与 bundle 列表；重启 `dsh web` 后，loader 自动应用包内
`cordis.patch.yml` 完成插件挂载。验证：

- 打开任意会话 → 顶栏出现 `余额 ¥x | 会话 ≈¥y` 徽章，悬停显示明细；
- 设置 → DeepSeek 余额 → 完整卡片（余额、间隔、界面语言、价目表）；
- 让模型调用 `deepseek_balance` 工具。

手动安装（同一机制，不经过插件安装器）：编辑 `$DSH_HOME/profiles/web/package.json`，
在 `dependencies` 加 `"@lemcae/dsh-balance": "<最新版本>"`（以 npm 为准），在 `dsh.profile.bundles`
数组加 `"@lemcae/dsh-balance"`，然后在该目录执行 `pnpm install` 并重启。

Peer 依赖为官方 `@deepseek-ai/*` 包（`^0.1.0-rc.5` 线，兼容 rc.5 与 rc.6；`@deepseek-ai/cordis` ^4.0.1）
与 `react`，由宿主提供。

## 使用

- **徽章**：显示 `余额 ¥x | 会话 ≈¥y`；点击刷新；悬停查看明细（构成、模型、更新于、刷新节奏/空闲提示）。
- **设置页**：余额行、「自动刷新开关」、「自动刷新间隔」（15 秒 … 5 分钟或自定义）、「界面语言」（跟随主界面 / 中文 / English）、价目表编辑（「保存」持久化）、切换时刻提示。
- **命令**（命令面板也可用）：`/dsh-balance [refresh | interval <毫秒> | prices <JSON> | language <auto|zh-CN|en> | auto-refresh <on|off>]`。
- **工具**：`deepseek_balance`（无参数）。

## 配置

settings 命名空间 `dsh-balance`：

| 字段                  | 默认      | 含义                                                                                                                  |
| --------------------- | --------- | --------------------------------------------------------------------------------------------------------------------- |
| `autoRefresh`       | `true`  | 是否启用自动刷新（`/dsh-balance auto-refresh on\|off`）                                                              |
| `refreshIntervalMs` | `30000` | 活跃时自动刷新间隔（5000–600000 毫秒）                                                                               |
| `language`          | `auto`  | 插件界面语言：`auto`（跟随主界面）、`zh-CN` 或 `en`                                                             |
| `prices`            | 见源码    | `{ models: { deepseek-v4-flash, deepseek-v4-pro, default } }`，每模型 `{ offPeak, peak }`，单位：元 / 百万 tokens |

计价按北京时间峰谷价：高峰 9-12、14-18 用 `peak`，其余用 `offPeak`。

## 已知限制和延后工作

- **估算与账单的差异**：消耗基于本机会话日志计算，可能与官方账单不一致（平台侧缓存策略、
  未记录请求、模型改名、价格变动等）。可在设置页更新价目表。
- **未知模型**按 `default`（v4-flash）计价。
- **子代理**（subagent）有独立 sessionId，不纳入本会话估算。
- **压缩（compaction）**：会话压缩会重写事件 seq，增量折叠可能停留在压缩前的合计（估算场景可接受）。
- **日志噪声**：每次自动刷新都会执行一次斜杠命令，向会话日志追加 `command/run` 与 `command/done`
  两条事件；暂停自动查询可大幅减少。
- **暂停恢复延迟**：暂停期间客户端每 `PAUSED_REFRESH_MS`（5 分钟）探测一次；新对话出现后
  会在下一次探测时恢复活跃刷新，恢复最长延迟该间隔。
- 余额缓存 10 秒；同一周期内工具与界面共享一次 API 调用。

## 模型体验

### 请求上下文与条件

#### 模型读取

工具 `deepseek_balance` 的 schema（零参数）与描述：声明使用 harness 凭据查询官方余额端点，
并返回当前会话的消耗估算。

#### Token 开销

无固定 token 开销；结果为数据相关载荷（余额、消耗、价目表、空闲状态）。

#### KV 缓存影响

前缀稳定：工具名、描述与 schema 恒定，结果随调用变化，不影响前缀复用。