@dsh-external/dsh-usage

Readme

# dsh-usage

![dsh-usage 面板截图](docs/usage-panel.png)

**DeepSeek 账户全量用量** —— 走 DeepSeek 平台官方用量接口，在 DSH Web GUI 直接查看余额与 Token 用量。

与其他 dsh 用量插件（从**本机会话日志**统计）不同，dsh-usage 读取的是 **DeepSeek 平台账户级数据**：能看到你账户的全部用量，包括 DSH 之外的调用（网页、手机 App、其他客户端）。所见即平台用量页（platform.deepseek.com/usage）的数据。

## 功能

| 功能 | 说明 |
|---|---|
| **余额** | 自动读取 DSH 凭证 `DEEPSEEK_API_KEY`，调用 `api.deepseek.com/user/balance`，显示总额/充值/赠送 |
| **Token 用量（账户全量）** | 调用平台官方 `api/v0/usage/by_api_key/{amount,cost}`，显示缓存命中/未命中/输出 Token、费用 |
| **时间范围** | 24 小时 / 7 天 / 30 天 / 90 天切换，堆叠柱状图 + 明细表 |
| **模型工具** | 注册 `deepseek_usage_query`，模型可直接查询余额与用量 |
| **令牌持久化** | 保存到 `~/.dsh/dsh-usage-token`，重启自动读取，无需每次重新获取 |

## 安装

```sh
# git 源一行安装（构建产物已入库，git 源不触发构建）
dsh plugin --profile web add "github:Huasecc/dsh-usage#main"
```

或手动：把仓库 clone 到任意目录，在 `profiles/web/package.json` 的
`dependencies` 加 `"dsh-usage": "link:<路径>/dsh-usage"`，`dsh.profile.bundles`
加 `"dsh-usage"`。装完**重启 web** 生效。

> 安全说明：插件读取的是**你自己这台机器的 DSH 凭证**与你自己粘贴的平台令牌，
> 显示的是你自己的 DeepSeek 账户数据；分发包内不含任何密钥。

## 与同类插件的差异

| | **dsh-usage（本插件）** | 日志聚合派（如 dsh-usage-stats） |
|---|---|---|
| 数据来源 | DeepSeek **平台官方接口** | 本机 DSH **会话日志** |
| 覆盖范围 | 账户**全量**（含网页/手机/其他客户端） | 仅本机 DSH 产生的用量 |
| 令牌 | 需一次性粘贴平台令牌（已持久化） | 无需令牌 |
| 安装 | `dsh plugin add` git 源 | npx 安装器 |

一句话：想要**账户真实花费**看 dsh-usage；只看**本机 DSH 消耗**选日志聚合派。两者可以共存。

## 原理

- `platform.deepseek.com` 有 WAF，请求需浏览器头（UA/Accept/Origin/Referer）
- 平台业务接口的 Bearer 令牌是**网页控制台会话令牌**（`localStorage` 的 `userToken`），
  不是 `sk-` API Key（后者返回 40003 invalid token）
- Host↔Client 通信走 `webServer` HTTP 路由 `/dsh-usage/api`（POST JSON，action 分发）

## 令牌获取（首次）

1. 浏览器登录 https://platform.deepseek.com/usage
2. F12 → 控制台执行：`JSON.parse(localStorage.getItem('userToken')).value`
3. 把输出粘贴到设置页「平台用量访问令牌」并保存

之后重启 DSH 自动读取；仅当令牌失效（平台登出/过期）时才需重新获取。

## 开发 / 打包

纯手写产物（`lib/index.mjs` + `lib/client.js`），无需构建步骤。

```bash
npm pack        # 生成 dsh-usage.tgz（若发布到 npm 需先改名去 scope）
```

## 许可

MIT