# dsh-balance-stats

[English](README.md) | **简体中文**

`dsh-balance-stats` 是 DeepSeek Harness Web 的余额与用量统计插件。它在对话输入框下方的
底部栏中显示三个核心读数：

```text
余额 ¥40.22 ｜ 本次会话 ¥0.15 ｜ 累计消耗 42.5%
```

点击整行可打开详情卡，查看余额构成、Harness 本地用量估算、按模型花费、Token
用量及历史账单汇总。

## 一句话安装

确保 Node.js `>=22.19.0` 且 `pnpm --version` 可正常执行，然后运行：

```sh
npx @deepseek-ai/dsh plugin --profile web add https://github.com/pangzi499/dsh-balance-stats.git
```

安装后启动或重启 Harness Web，并对浏览器执行一次强制刷新：

```sh
npx @deepseek-ai/dsh web
```

> **更新**：`npx @deepseek-ai/dsh plugin --profile web update dsh-balance-stats`

## 界面预览

**统计栏** —— 输入框下方的余额、本次会话与累计消耗读数：

![余额、本次会话与累计消耗主栏](images/dsh-balance-stats-overview.png)

**详情卡** —— 点击统计栏打开：余额构成、历史账单、按模型花费、Token 用量与账单导入入口：

![余额与用量统计详情卡](images/dsh-balance-stats-details.png)

## 功能

- **余额**：读取 DeepSeek 官方余额接口，显示当前可用余额、充值余额和赠送余额。
- **本次会话**：通过 composer 作用域的 `balanceStatsSessionCost` projection 实时估算当前会话花费。
- **累计消耗**：导入账单后优先显示账务口径百分比；未导入时回退到 Harness 本地估算。
- **详情卡**：显示今天、最近 7/30 天花费、按模型分解、Token 用量和更新时间。
- **账单自动获取（可选）**：在详情卡里粘贴一次平台 `userToken`，服务端即按周期自动拉取账单并计算账务口径；token 可持久化到本机凭证文件（权限 0600），重启自动恢复，一键可清除。
- **JSON 账单导入（兜底）**：不提供 token 时，仍可直接粘贴 `get_all_invoice` 的 JSON 响应完成一次性导入；导入后自动强制刷新余额。
- **容错与缓存**：余额/账单请求失败时保留上次成功数据（stale-while-error）；服务端和客户端均按配置周期刷新。点击统计栏的刷新按钮可立即向 DeepSeek 重新拉取。

<details>
<summary><b>数据口径</b></summary>

### 余额

服务端请求：

```text
GET https://api.deepseek.com/user/balance
```

密钥默认复用 Harness credentials 中的 `DEEPSEEK_API_KEY`，不会发送给浏览器。

### Harness 本地估算

插件遍历 Harness 会话日志中的 usage 事件，按模型单价计算：

- 非缓存输入 Token
- 缓存命中/写入 Token
- 输出 Token
- 按日期和模型聚合的花费

这是本地估算，可能遗漏 Harness 之外、旧日志已删除或未写入标准 usage 事件的调用。

`prices` 用于普通模型，以及 `2026-08-17 00:00 +08:00` 前的 v4 用量。该时间点后，
v4 在北京时间 `09:00–12:00`、`14:00–18:00` 使用 `v4PeakPrices`，其余时段使用
`v4OffPeakPrices`。三组价格均可配置。

### 历史账单

DeepSeek 公开余额 API 不返回历史总充值。如需账务口径，有三种方式：

**方式一：账单自动获取（推荐）**

1. 点击 composer 底部统计栏打开详情卡，展开「账单自动获取」。
2. 按「如何获取 userToken」三步指引：登录平台 → 控制台执行
   `copy(localStorage.userToken)` → 回到卡片粘贴并点「保存」。
3. 保存时插件会先验证一次拉取，通过后将 token 写入本机凭证文件
   `~/.dsh/.credentials.yaml`（权限 0600），之后按
   `invoiceRefreshIntervalMs`（默认 6 小时）自动刷新，重启 dsh web 也自动恢复。
4. token 失效时状态点变黄提示「已过期」，重新粘贴即可；点击「清除」可彻底移除。

**方式二：手动粘贴 JSON（无需凭证）**

1. 登录 `https://platform.deepseek.com/`。
2. 在浏览器开发者工具中获取
   `https://platform.deepseek.com/auth-api/v0/users/get_all_invoice` 的 JSON 响应。
3. 点击统计栏，在「高级导入」中粘贴完整 JSON 并点击“导入”。

**方式三：环境变量 / 配置**

将 token 写入 Harness credentials 的 `DEEPSEEK_PLATFORM_TOKEN`
（或 `cordis.patch.yml` 的 `platformToken`、同名环境变量），插件启动即自动开启。

插件仅统计 `payment_order_status === "SUCCESS"` 的充值订单，并单独累加有效赠送订单。

```text
账务总额 = 历史总充值 + 历史总赠送
账务总消费 = max(0, 账务总额 - 当前总余额)
累计消耗 = 账务总消费 / 账务总额 × 100%
```

未导入账单时：

```text
累计消耗 = Harness 本地估算总花费
             / (当前可用总余额 + Harness 本地估算总花费)
             × 100%
```

</details>

<details>
<summary><b>隐私与存储</b></summary>

- 默认（未提供 token 时）插件不会请求 `get_all_invoice`，也不会保存任何 DeepSeek Platform 凭证。
- 仅当你显式粘贴 `userToken` 并点击保存后，插件才会以该 token 请求账单接口，并把 token
  写入本机 Harness 凭证文件 `~/.dsh/.credentials.yaml`（权限 0600，由 Harness credentials
  provider 托管写入）。点击「清除」即从该文件移除。
- 不接受、不保存 DeepSeek Platform Cookie；token 只保存在你本机，不会发送到除
  `platform.deepseek.com` 之外的任何地址。
- 手动粘贴的原始 JSON 只在内存中解析；浏览器侧的 localStorage 兜底汇总仅包含历史充值、
  历史赠送、订单数、币种和导入时间。订单号、支付渠道和时间明细不会持久化。
- 在 DeepSeek 平台退出登录即可使已保存的 token 立即失效。

`get_all_invoice` 属于 DeepSeek Platform 的登录态私有接口，响应结构可能变化。请不要向他人分享
userToken、Cookie 或包含订单明细的原始 JSON。

</details>

## 运行要求

- DeepSeek Harness：已在 `0.1.0-rc.6` ～ `0.1.1-rc.1` 上验证
- Node.js：`>=22.19.0`
- pnpm：需要在 `PATH` 中可用（Harness 使用 pnpm 管理 profile 插件；缺失时见[安装](#安装)）
- 已验证运行环境：OrbStack Ubuntu、Node.js `24.19.0`

> DeepSeek Harness 尚处于开发者预览阶段，插件所使用的槽位和客户端接口可能随上游版本变化。

这是 DeepSeek Harness 社区插件，不是 `@deepseek-ai` 官方插件。

## 安装

### GitHub（推荐）

安装 GitHub 默认分支的最新版本：

```sh
npx @deepseek-ai/dsh plugin --profile web add https://github.com/pangzi499/dsh-balance-stats.git
npx @deepseek-ai/dsh web
```

源码仓库：<https://github.com/pangzi499/dsh-balance-stats>

也可以从 GitHub Release 下载 `dsh-balance-stats-0.2.1.tgz`，再按下方 tarball 方式安装。

<details>
<summary><b>pnpm 前置准备</b></summary>

Harness 使用 pnpm 管理 profile 插件，安装前先检查：

```sh
pnpm --version
command -v pnpm
```

如果提示 `pnpm: command not found` 或没有输出，可通过 Corepack 安装：

```sh
corepack enable
corepack prepare pnpm@10 --activate
pnpm --version
```

如果当前 Node.js 环境没有 Corepack，可改用 npm：

```sh
npm install --global pnpm@10
pnpm --version
```

</details>

<details>
<summary><b>本地目录 / tarball</b></summary>

### 本地目录

```sh
npx @deepseek-ai/dsh plugin --profile web add /absolute/path/to/dsh-balance-stats
npx @deepseek-ai/dsh web
```

### tarball

打包：

```sh
cd /path/to/dsh-balance-stats
npm pack
```

安装：

```sh
npx @deepseek-ai/dsh plugin --profile web add /absolute/path/to/dsh-balance-stats-0.2.1.tgz
npx @deepseek-ai/dsh web
```

安装后对浏览器执行一次强制刷新（macOS：`Command + Shift + R`；Windows/Linux：`Ctrl + Shift + R`）。

</details>

## 更新

GitHub 一键安装的插件，更新命令见上方「[一句话安装](#一句话安装)」。

本地目录或 tarball 安装：使用新版本路径再执行一次 `add`，然后重启 `dsh web`。

<details>
<summary><b>配置</b></summary>

在 `$DSH_HOME/profiles/web/cordis.patch.yml` 中覆盖插件配置。配置层为整体替换，所以请重述需要保留的键：

```yaml
- id: dsh-balance-stats
  config:
    apiKey: ''
    apiKeyRef: DEEPSEEK_API_KEY
    baseUrl: https://api.deepseek.com
    refreshIntervalMs: 300000
    clientPollIntervalMs: 30000
    timeoutMs: 8000
    currency: CNY
    platformToken: ''
    platformTokenRef: DEEPSEEK_PLATFORM_TOKEN
    invoiceRefreshIntervalMs: 21600000
    platformBaseUrl: https://platform.deepseek.com
    prices:
      deepseek-chat: { cacheHit: 0.1, cacheMiss: 1, output: 2 }
      deepseek-reasoner: { cacheHit: 1, cacheMiss: 4, output: 16 }
      deepseek-v4-flash: { cacheHit: 0.02, cacheMiss: 0.1, output: 0.2 }
      deepseek-v4-pro: { cacheHit: 0.025, cacheMiss: 3, output: 6 }
    v4PeakPrices:
      deepseek-v4-flash: { cacheHit: 0.10, cacheMiss: 3.0, output: 9.0 }
      deepseek-v4-pro: { cacheHit: 0.30, cacheMiss: 9.0, output: 27.0 }
    v4OffPeakPrices:
      deepseek-v4-flash: { cacheHit: 0.05, cacheMiss: 1.5, output: 4.5 }
      deepseek-v4-pro: { cacheHit: 0.15, cacheMiss: 4.5, output: 13.5 }
    defaultPrices: { cacheHit: 0.1, cacheMiss: 1, output: 2 }
```

优先使用 `apiKeyRef` / `platformTokenRef` 引用 Harness credentials。不要在要分享的 `cordis.patch.yml` 中写入真实 API Key 或平台 token。

账单自动获取相关键：

- `platformToken`：直接写入的平台 token（明文，不推荐；推荐留空走 UI 保存或 credentials）
- `platformTokenRef`：凭证引用名（默认 `DEEPSEEK_PLATFORM_TOKEN`；UI 保存即写入该引用对应的凭证文档条目）
- `invoiceRefreshIntervalMs`：账单自动刷新间隔，默认 21600000（6 小时），最小 600000
- `platformBaseUrl`：DeepSeek 平台地址，一般无需修改

</details>

<details>
<summary><b>验证</b></summary>

启动 Web profile 后：

```sh
curl http://127.0.0.1:3080/balance-stats
curl http://127.0.0.1:3080/plugins/dsh-balance-stats/client.js
```

统计接口示例（金额仅为示例）：

```json
{
  "ok": true,
  "currency": "CNY",
  "balances": [
    { "currency": "CNY", "total": 40.22, "granted": 0, "toppedUp": 40.22 }
  ],
  "stats": {
    "state": "ok",
    "totalCost": 2.103612,
    "percent": 5,
    "today": 2.103612,
    "day7": 2.103612,
    "day30": 2.103612,
    "sessions": 10
  }
}
```

</details>

## 已知限制

- Harness 本地花费是估算值，不等于 DeepSeek 官方账单。
- 历史账单汇总依赖非公开 `get_all_invoice` 响应结构。
- 平台 `userToken` 在你退出平台登录后即失效，重新粘贴即可恢复自动获取。
- 手动 JSON 汇总按浏览器存储，不在不同浏览器或设备之间同步（自动获取的汇总保存在服务端）。
- 余额、账单和估算价格币种必须一致。
- 上游 DSH 客户端槽位或 projection API 变更后，插件可能需要同步适配。

## 卸载

```sh
npx @deepseek-ai/dsh plugin --profile web remove dsh-balance-stats
```

## License

MIT