dsh-plugin-quota

Readme

# dsh-plugin-quota

DeepSeek 账户额度与 Token 用量，一键接入 DeepSeek Harness 的 Web 设置界面。

Real-time DeepSeek account balance and per-session token usage for the DeepSeek Harness web UI, as a standalone installable plugin.

![设置中的额度与用量分区](docs/screenshot.png)

## 功能 / Features

- **账户额度 / Account quota** —— 实时查询 DeepSeek 账户余额：
  - 按币种展示总额度 / 赠送额度 / 充值额度（数据直接来自 DeepSeek `/user/balance` 接口）
  - 可用性状态徽标（可用 / 不可用）
  - 加载、失败与重试状态齐全，失败时展示具体原因（未配置 Key、HTTP 错误、端点不支持等）
- **Token 用量 / Token usage** —— 当前会话的累计消耗：
  - 未缓存输入 / 输出 / 缓存读取 / 缓存写入 四个独立桶 + 合计
  - 悬停显示精确数值，行内使用紧凑的 k / M 格式
  - 数据来自 harness 的 `tokenUsage` 投影（与内置上下文计费器同一数据源），随会话实时更新

安装后在 设置 → **额度** 分区查看（Settings → **Quota**）。

## 安装 / Install

```sh
dsh plugin --profile web add dsh-plugin-quota
```

安装完成后**重启** `dsh web`（或重启桌面 App），在 设置 → 额度 中查看。

> 也可以直接从 GitHub 安装（等价，不经过 npm）：
>
> ```sh
> dsh plugin --profile web add github:ArvenWang/dsh-plugin-quota
> ```
>
> 开发期安装本地副本：`dsh plugin --profile web add /path/to/dsh-plugin-quota`

移除：

```sh
dsh plugin --profile web remove dsh-plugin-quota
```

## 工作原理 / How it works

- **宿主侧（node half）**：在 harness 的 web server 上注册一个只读路由 `GET /api/plugins/quota/balance`。连接事实来自官方 DeepSeek 适配器使用的同一处配置——`llm-deepseek` settings 命名空间（模型页写入的 `apiKeyEnv` / `baseURL`）与凭据服务（`credentials`），无凭据服务时回退到环境变量。凭据只在宿主进程内用于该次请求，不落盘、不经过浏览器。
- **浏览器侧（browser half）**：注册一个 `settings.section` 分区。额度卡片同源请求上面的路由；用量卡片经框架 `useSessions` 钩子读取当前会话的 `tokenUsage` 投影值。
- 插件通过 `dsh.bundle` 声明把自己作为一层组合补丁插入 profile；通过 `dsh.client` 声明进入 Web 浏览器 roster。零构建：`index.js` 与 `client.js` 均为可直接运行的纯 JS。

## 兼容性 / Compatibility

- DeepSeek Harness `>= 0.1.0-rc.5`（Web profile）。
- 需要可用的 DeepSeek API Key（`DEEPSEEK_API_KEY` 环境变量，或经 设置 → 模型 页配置）。未配置时分区会显示明确错误提示。
- 自定义 OpenAI 兼容端点若没有 `/user/balance` 路由，会显示 HTTP 错误信息。

## 安全 / Security

- 路由只读、仅同源可访问（同一 loopback 页面本身已可访问整个 `/api` 网关，因此不引入新的信任面）。
- 余额数据不会写入会话日志、设置或任何存储；API Key 不经浏览器，全部留在宿主进程内。

## 开发 / Development

本插件零构建、零运行时依赖（peer 依赖为 harness 官方包）：

```sh
npm test   # 语法检查
```

## 许可证 / License

MIT