# dsh-token-rush

> 一个挂在 DeepSeek Harness（DSH）Web GUI 会话页左上角的 token 告急小窗。
> 实时告诉你：这一局烧了多少 token、大概多少钱、账户还剩多少。高峰时段，它会自动变成橙红色——因为那是官方 2 倍价的时间。

[中文](README.md) | [English](README.en.md)

---

## 为什么需要它

作为一个贫穷的 API 使用者，你是否也有像我一样的 token 焦虑？

每次让 AI 干活，都忍不住切到后台看一眼这轮烧了多少 token；等账单出来才发现，明明聊得很爽，钱包却已经瘦了两斤。更惨的是：白天 9 点到 12 点、下午 14 点到 18 点（北京时间），DeepSeek 的高峰时段单价是平时的 **2 倍**——你以为是闲聊，实际上是双倍扣费。

**dsh-token-rush** 把答案钉在会话页左上角：一个永远跟着你走的小窗口，实时显示当前会话累计消耗的 token、按官方单价估算的金额、以及账户余额；每到高峰时段，窗口整体变橙红色，等于在你耳边喊了一句：

> "现在用 AI，是两倍价格，悠着点。"

![会话仪表窗口实物图（空闲时段 · 随主题色）](docs/window.png)

*上图：会话进行中的实际效果 —— 左上角悬浮窗，实时显示总 Token（进/出）、估算消耗与账户余额；当前为空闲时段，窗口颜色跟随 DSH 主题；高峰时段整体变橙红色。*

## 功能

| 能力 | 说明 |
| --- | --- |
| 🎯 左上角悬浮窗 | 帧级 overlay 层的小窗口（约 216px 宽），不遮挡主要信息；默认位置 (12, 56) |
| 📊 实时统计 | 当前会话累计总 token（输入/输出/缓存分桶），来自 DSH `tokenUsage` 投影（订阅推送，非轮询） |
| 💰 消耗金额 | token × DeepSeek 官方单价表（按模型、按高峰/非高峰价）估算，界面标注 ≈；单价表与官方「模型 & 价格」页一致 |
| 🧾 账户余额 | host 侧代理 DeepSeek `GET /user/balance`，60s 缓存；复用「设置 → 模型」里的 API Key，Key 不出服务端；桌面端（`dsh-app://app`）与浏览器端均可读到 |
| 🚦 高峰变色 | 每次启动 DSH 服务时自动检查当前时间；高峰时段（默认北京时间周一至周五 09:00–12:00、14:00–18:00，**法定节假日除外**）窗口整体变橙红色，否则跟随当前 DSH 主题（亮/暗自动匹配） |
| 👻 透明度渐变 | 未开启对话时 0% 透明度且不拦截鼠标；开始对话后 0.8s 平滑渐变为半透明 |
| 🖱️ 随意拖动 | 按住窗口任意处拖动，位置自动记忆（localStorage）；双击复位默认位置 |

## 安装

### 从本目录安装（开发 / 本地使用）

```powershell
dsh plugin --profile web add link:E:\万物暂存\AI缓存工作区\dsh-token-rush
```

重启 `dsh web` 进程（仅刷新页面不生效），左侧上方即出现悬浮窗。验证挂载：

```powershell
dsh --profile web --dump-config | Select-String token-rush   # 应看到 - id: token-rush
```

### 卸载

```powershell
dsh plugin --profile web remove dsh-token-rush
```

重启 `dsh web` 后窗口消失。

## 配置（环境变量，读取于 `dsh web` 启动环境）

| 变量 | 说明 | 默认 |
| --- | --- | --- |
| `DSH_HUD_PEAK_WINDOWS` | 高峰时间段，如 `"9-12,14-18"`、`"8-10 20-23"`（半开区间 [start, end)） | `9-12,14-18` |
| `DSH_HUD_PEAK_TZ` | 高峰判断时区（IANA 名称） | `Asia/Shanghai` |
| `DSH_HUD_PEAK_HOLIDAYS` | 法定节假日（全天按空闲时段计价），如 `"2027-01-01,2027-02-05..2027-02-11"`；`none` 关闭节假日规则；留空或无法解析则用内置 2026 年清单 | 内置 2026 年清单 |
| `DEEPSEEK_BASE_URL` | DeepSeek API 地址覆盖（同官方 llm-deepseek 约定） | `https://api.deepseek.com` |

余额查询复用「设置 → 模型」中 DeepSeek 提供商的 `apiKeyEnv`（默认 `DEEPSEEK_API_KEY`）/`baseURL` 配置；未配置 Key 时余额行显示「未配置 Key」，查询失败时显示失败原因（如「余额不可用（403）」），悬停可见详情。

## 计价口径（api-docs.deepseek.com「模型 & 价格」，2026-10 核对）

单位：元 / 百万 tokens；空闲时段单价 = 高峰时段的一半。

| 模型 | 输入（缓存命中）空闲 | 输入（缓存命中）高峰 | 输入（缓存未命中）空闲 | 输入（缓存未命中）高峰 | 输出空闲 | 输出高峰 |
| --- | --- | --- | --- | --- | --- | --- |
| `deepseek-flash`（含 `deepseek-v4-flash`、`deepseek-v4-flash-vision-exp`） | 0.02 | 0.04 | 1 | 2 | 4 | 8 |
| `deepseek-v4-pro` | 0.15 | 0.3 | 4.5 | 9 | 13.5 | 27 |

缓存写入（`cacheWriteTokens`）按缓存未命中价计费：DeepSeek 只区分命中 / 未命中两档。

## 数据口径

| 项目 | 来源 | 说明 |
| --- | --- | --- |
| 总 Token | DSH 会话 `tokenUsage` 投影（`uncachedInputTokens` / `cacheReadTokens` / `cacheWriteTokens` / `outputTokens`） | host 按会话日志维护的 provider 上报总值，实时推送 |
| 消耗金额（估算 ≈） | Token × 官方单价表 | 价格按模型匹配（`deepseek-flash` / `deepseek-v4-pro` / …，未知模型回退 Flash 价），模型取最近一次**实际发起请求**的模型（`modelSelection.lastUsed`，未跑过请求时取待用选择），高峰价 = 空闲价 ×2；单价表快照在浏览器半区 `lib/client.js`（算账的一方为准，host 只补充它还不认识的模型） |
| 账户余额 | DeepSeek `/user/balance` | host 缓存 60s，浏览器每分钟拉取一次 |
| 高峰判定 | host 提供窗口 / 时区 / 节假日配置，浏览器按同一规则判定 | 每次 DSH 启动另记一条 host 判定日志；默认北京时间工作日窗口，周末与法定节假日全天空闲；浏览器半区随 client-hmr 热更新，因此判定不受 host 半区版本影响 |
| 只读路由访问控制 | Host / Origin 校验 | 同源网页请求与桌面端（`dsh-app://app` 转发，会剥掉 Origin / Sec-Fetch-Site）均可读取；跨站请求、非本机 loopback Host（DNS rebinding）一律 403 |

## 已知限制

- 消耗金额为**估算值**：token 总量来自 provider 上报；价格取最近一次实际请求所用的模型，且整段会话按**当前**时段单价折算 —— 若一次会话跨越 09:00 / 12:00 / 14:00 / 18:00 的时段边界，跨界的部分仍按当前时段计价。实际扣费以 DeepSeek 账单为准。
- 内置法定节假日清单仅覆盖 **2026 年**（依据国办发明电〔2025〕7 号）；其他年份请用 `DSH_HUD_PEAK_HOLIDAYS` 指定，否则节假日的工作日会被算成高峰。
- 余额查询仅覆盖 DeepSeek 官方 API（含自定义 `baseURL` 端点）；使用其他 LLM 供应商时余额行显示「余额不可用」。
- 高峰时段判定默认使用北京时间（与官方计费口径一致），可按需用 `DSH_HUD_PEAK_TZ` 修改。

## 开发

纯手写 JS，**无构建步骤**：

```text
dsh-token-rush/
├── package.json          # dsh.bundle.patch + dsh.client 声明
├── cordis.patch.yml      # 插件行：- insert - id: token-rush
├── lib/
│   ├── index.js          # host 半区：启动时段检查 + /api/token-rush/* 路由
│   └── client.js         # 浏览器半区：悬浮窗 UI（window.__ModuleLoader__ 工厂格式）
├── dev/host-smoke.mjs    # host 半区冒烟测试
├── dev/client-smoke.mjs  # 浏览器半区冒烟测试
└── README.md / README.en.md / CHANGELOG.md
```

```powershell
node --check lib\index.js      # host 半区语法校验
node --check lib\client.js     # 浏览器半区语法校验
node dev\host-smoke.mjs        # host 冒烟测试（高峰判定/节假日/计价/路由/访问控制/余额代理）
node dev\client-smoke.mjs      # 浏览器半区冒烟测试（挂载/可见性/计价与余额文案）
```

> 浏览器半区（`lib/client.js`）由 DSH 的 client-hmr 轮询监听：改完文件后运行中的页面会自动重载插件，无需重启。
> host 半区（`lib/index.js`）不参与热重载：DSH 的插件改动统一「下次启动生效」（插件管理页同此文案），改动后需重启 `dsh web` / 桌面端。
> 因此金额与高峰判定都以浏览器半区为准，host 半区只负责提供配置与余额代理——存在版本落差时，显示的数字依旧是新的。

> 版本控制遵循语义化版本 [SemVer](https://semver.org/lang/zh-CN/)：`主版本号.次版本号.修订号` 分别对应重大架构变更、向后兼容的功能新增、Bug 修复。
> 各版本变更见 [CHANGELOG.md](CHANGELOG.md)。

## License

[MIT](LICENSE)