dsh-web-quota-meter

Readme

# DSH Web 额度表（dsh-web-quota-meter）

在 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（DSH）Web 页面右下角显示的额度小仪表：

- **余额**：官方公开接口 `GET https://api.deepseek.com/user/balance`
- **今日已消耗**：本地估算（当日基线余额 − 当前余额），每日重置时间可在 ⚙ 配置里自定义（默认 05:00），跨日自动归零
- **峰谷计价提示**：按北京时间显示当前是峰时（9:00–12:00、14:00–18:00）还是谷时，折叠栏有彩色小徽章，展开后有说明卡片

折叠后只保留一行数字：`¥ 123.45 · 今日 ¥ 2.30 [峰] [↻] [＋]`

> 基于 DSH `0.1.0-rc.6` 的组合加载器、`dsh.client` 包体约定与官方 `webServer` / `credentials` 服务编写；代码中不含任何密钥。

---

## 正式安装（推荐）：官方插件机制

本仓库本身就是一个 DSH 插件包（host 插件 + 官方 `dsh.client` 客户端包体 + **bundle 补丁**，与官方 `dsh-base` 同款形态）。正式安装后**可插可卸，每次启动 `dsh web` 自动加载**，且 API Key 存入官方凭证库、重启免重填。

### 安装（一条命令 + 重启）

```bash
# 发布到 npm 之后：
dsh plugin --profile web add dsh-web-quota-meter
# 或直接从 GitHub 仓库：
dsh plugin --profile web add github:wangfujian762/dsh-web-quota-meter
# 或本地路径（开发调试）：
dsh plugin --profile web add file:../dsh-web-quota-meter
```

然后**重启 `dsh web`**，卡片自动出现，以后每次启动都自动加载。

为什么一条命令就够：`dsh plugin add` 在 pnpm 安装成功后会**自动把声明了 `dsh.bundle` 的包写进你 profile 的 `dsh.profile.bundles` 列表**（写回 `~/.dsh/profiles/web/package.json`），组合树因此自动获得本插件行——不需要手动改任何配置文件。

> 如果你绕开 `dsh plugin`、直接 `pnpm add`，才需要手动把包名加进 `~/.dsh/profiles/web/package.json` 的 `dsh.profile.bundles`，或等效地在 `~/.dsh/profiles/web/cordis.patch.yml` 里写 `- insert: [{ id: quota-meter, name: dsh-web-quota-meter }]`。

### 卸载 / 停用

- **彻底卸载**（一条命令，组合行自动移除）：

  ```bash
  dsh plugin --profile web remove dsh-web-quota-meter
  ```

  凭证库里的 Key 也可以顺手删掉（或留着下次安装直接用）。
- **临时停用**（保留安装）：在 `~/.dsh/profiles/web/cordis.patch.yml` 里写：

  ```yaml
  - id: quota-meter
    disabled: true
  ```

---

## 路线 A：快速体验（动态插件，临时）

不想动 profile 配置时可用。动态插件**只存在于当前 DSH 进程**：同一进程内刷新 / 重开页面仍在，重启 DSH 后消失（API Key 也只存内存）。

1. 打开 DSH Web 会话，把下面这段话发给 agent（把 `<仓库地址>` 换成真实的）：

   ```text
   请按 <仓库地址> 的 README「路线 A」把这个插件安装为动态 Cordis 插件：
   读取仓库里的 plugin-host.js 和 plugin-client.js，去掉每份文件开头的
   `export default () => {` 和文件末尾的 `}`，把中间内容分别作为 code.host 和
   code.client 传给 cordis_define（新插件，idPrefix 用 dsqu），然后 cordis_run。
   ```

2. 在页面上批准运行；卡片出现后点 ⚙ 填 API Key 保存。

---

## 工作原理与隐私

- 余额来自官方公开接口，只带 `Authorization: Bearer <你的 API Key>` 请求 `api.deepseek.com`；API Key 除官方凭证库外不落任何地方、不会发往 DeepSeek 之外的任何地址；
- 「今日已消耗」不是官方接口数据：插件把每个「业务日」（重置时间可在配置里改，默认每日 05:00 换日）第一次成功取到的余额记为基线，之后用 `基线 − 当前余额` 估算消耗。期间若充值，数值会偏小，卡片会给出提示；
- 「峰时 / 谷时」按北京时间（UTC+8）计算：高峰 9:00–12:00、14:00–18:00，其余为谷时（对应 DeepSeek 2026-08-17 起生效的峰谷定价方案）；
- 插件重启后「今日已消耗」基线重计（卡片会提示）；重置时间设置目前仅存内存，重启后回到默认 05:00。

## 升级

```bash
dsh plugin --profile web update dsh-web-quota-meter
```

然后重启 `dsh web`。npm 发布版按版本范围升级；GitHub 直装版会重新拉取分支最新提交（个别 pnpm 版本行为有差异，不放心可带 tag 重新 add 一次）。DSH 没有后台自动升级机制（插件在你的机器上以你的权限运行代码，升级需由你触发）；装了 `dsh-market` 的话也可以在设置页里点「升级」。

## 仓库结构

| 文件 | 用途 |
| --- | --- |
| `lib/index.js` | Host 插件（正式包入口：curl 取数、webServer 同源路由、凭证库持久化） |
| `lib/client.js` | 客户端包体（`dsh.client` 预构建产物，卡片 UI） |
| `cordis.patch.yml` | bundle 补丁：向组合树插入本插件行（`dsh.bundle.patch` 声明） |
| `package.json` | 包清单，`exports["./client"]` + `dsh.client` 字段 + `dsh.bundle` 声明 |
| `plugin-host.js` / `plugin-client.js` | 路线 A 用的动态插件源码（与正式包同逻辑） |

## License

MIT