# dsh-usage · DeepSeek Harness (DSH) Token 用量明细、API 余额与成本监控插件

[English](README.md) | 中文

<p align="center">
  <img src="https://img.shields.io/npm/v/@linxin666/dsh-usage?style=flat-square" alt="Version">
  &nbsp;
  <img src="https://img.shields.io/badge/DSH-%3E%3D0.2.2--rc.1-4c6ef5?style=flat-square&amp;labelColor=454a54" alt="DSH">
  &nbsp;
  <img src="https://img.shields.io/badge/license-Apache--2.0-blue?style=flat-square" alt="License">
</p>

<p align="center">
  <strong>DeepSeek Harness（DSH）官方 Web GUI 与桌面客户端多模型 Token 用量与账单成本监控中心</strong><br>
  <em>每日 Token 消耗明细 · 多供应商 API 余额查询 · 编程套餐进度追踪 · 峰谷时段成本估算 · Token 银行鲸元券</em>
</p>

面向 DeepSeek Harness (DSH) Web GUI 与官方桌面客户端的多模型使用统计与成本监控插件：多 provider 余额与编程套餐用量检测，外加实时 Token 用量台账与成本估算，并在侧栏「设置」行上方提供紧凑的价格速览卡。

## 功能

插件由宿主侧服务与「设置 → Web 扩展 → 使用统计」页面组成（父级缺席时保留独立的一级「使用统计」分区）：

- **用量页签**：今日 token 分桶合计（输入 / 输出 / 缓存读 / 缓存写，按 provider 上报口径互不相加），分 provider 与模型细分，近 30 天以「提供方-模型」水平条形图展示，以及所有已配置 provider 的余额（同一适配器家族只渲染一行：被该家族运行时路由遮蔽的休眠目录别名不再单独出余额行）。卡片顶部的**日期选择器**可切换到保留期内任何有记录的一天（今日在最前，其余按新到旧排列），此时卡片展示该日自己的合计、分 provider 行与消费估算；峰谷计价时段行只跟随今日，因为它描述的是当前时段的计价。对 DeepSeek 官方路由，页签还展示当前峰谷计价时段（北京时间工作日 09:00-12:00、14:00-18:00 为高峰，按双倍计费）与今日消费估算（CNY）；该时段行按当时钟点着色——高峰为红、空闲为绿，并始终带「高峰 / 空闲」文字与圆点，颜色不是唯一信号。台账从 `session/event` 实时流折叠（`request/header` 归因路由 + `assistant/message` 用量），持久化到 `$DSH_HOME/dsh-usage/usage-ledger.json`，按本地日保留，因此历史日重启后仍在；统计自插件首次启用起计。
- **个人套餐页签**：每个已配置且暴露套餐端点的 provider 的配额窗口——已用百分比与重置时间（Kimi For Coding 5 小时/每周、GLM 编程计划 5 小时/每周/每月、OpenCode Go 滚动/每周/每月、MiniMax 5 小时/每周、Codex / ChatGPT 订阅 5 小时/每周）。没有真实套餐/订阅体系的厂商（DeepSeek、ZenMux、Moonshot、OpenRouter、SiliconFlow）不出现在此页签，其余额显示在用量页签。
- **Token 银行页签**：以台账里全部 provider 的用量铸造「鲸元券」，汇率按 100 万 tokens 兑 1 鲸元（防膨胀）：DeepSeek 官方家族（`deepseek` 目录别名、运行时路由 `deepseek-official`、登录账号使用的 `deepseek-account`）与订阅、中转路由一起计入 token 与调用次数。页签把这些保留台账内的 token 总量折算成票面面额印在钞票图上，附带走票窗口的序列号行，并提供保存图片按钮与（浏览器支持文件分享时的）系统分享按钮。消费行只统计官方家族：优先展示从官方余额观测到的真实累计花费——余额下降即计为消费，充值上涨不计——首次观测到下降之前回落为折叠时刻估算，订阅与中转路由没有价目表，永不计入消费。铸造总量优先取宿主的全台账聚合，旧宿主回落为近 30 天；台账没有任何用量时展示空状态。页签的日期选择器可把票券改为按某一天铸造（真实花费观测行是自首次余额观测起的累计值，只在整段窗口下展示，单日票券回落为该日的折叠时刻估算）。票面文字与语言无关（数字、拉丁小字、ISO 日期），导出图在浏览器本地渲染。
- **侧栏底部速览卡**：位于侧栏「设置」行上方、与更新/远程触发器同组的紧凑卡片——头条为今日消费估算（今日尚无可计价用量时回落为 tokens 总量），下方是 tokens/调用次数行，以及最多两个已配置 provider 的余额（超出折叠为 +N）。整张卡片主体是一个按钮，点击打开使用统计设置分区，细节只保留在一处；右上角箭头可把卡片收成一行摘要条（消费提供方名称 + 峰谷标记 + 标签 + 头条值），选择跨刷新保持。今日消费走 DeepSeek 官方路由时，卡片按当前钟点与日期标出峰谷（周末与中国法定节假日全天算空闲，红色只出现在工作日的高峰窗口）：红色圆点加「高峰」、绿色圆点加「空闲」，展开态另有一行注明当前时段何时结束（高峰）或何时进入高峰（空闲）；其他 provider 的卡片不出现该标记。标签页可见时以 30 秒的宽松周期轮询，侧栏折叠为 56px 栏轨时隐藏，插件停用时消失。
- 探测完全在宿主侧按轮询周期执行（默认 60 秒，可手动刷新）；API key 经宿主凭据缝解析（`llm-pi-ai` 记录、`apiKeyEnv` 引用），永不进入浏览器。

支持的余额端点：DeepSeek（官方运行时路由 `deepseek-official` 与目录别名 `deepseek` 均可解析）、Moonshot（国内/国际）、OpenRouter、SiliconFlow（国内/国际）、ZenMux。支持的套餐端点：Kimi For Coding、GLM 编程计划（国内 open.bigmodel.cn、国际 api.z.ai——即 pi-ai 目录注册的 `zai` 路由，另兼容 `zai-coding` / `zai-coding-cn` 别名；覆盖 5 小时 / 每周 / 每月窗口与 token 制、积分制套餐）、OpenCode Go、MiniMax、Codex / ChatGPT 订阅（OAuth access token 取自 pi-ai grant；token 过期时显示错误行，宿主下次跑 Codex 请求自动刷新后恢复）。没有程序化端点的 provider（Qwen token 套餐、OpenCode Zen 按量、Anthropic、OpenAI）仅列出，不展示数据。

### 消费估算口径

今日消费是折叠时刻按 DeepSeek 公布的峰谷价目表（CNY / 百万 tokens；高峰即上表时段，空闲为高峰一半）做出的估算。当前生效的是 `deepseek-flash`（DeepSeek-V4.1-Flash）与 `deepseek-v4-pro` 两档：已下线的 flash 系列 id（`deepseek-v4-flash`、`deepseek-v4-flash-vision-exp`）按 flash 档计价，`deepseek-v4-pro` 在北京时间 2026-09-14 12:00 被 DeepSeek 路由到 V4.1-Flash 后同样按该档计价。

估算仅覆盖 DeepSeek 官方路由——其他渠道转发的流量（ZenMux、SiliconFlow 等）不计价；未识别的 DeepSeek 模型 id 按 flash 档估算。价目表调整前记录的桶保留旧价，因此调价从发布时点起生效，不追溯历史数据。

官方口径对中国法定节假日全天按空闲计费（即使落在周一至周五），落在周六周日的调休上班日同样按空闲计费。因此周末天然就是空闲时段；本包内置国务院办公厅公布的节假日表（`src/core/holidays.ts`，2020 至 2026 年，取自 MIT 许可的 [chinese-holidays-node](https://github.com/bastengao/chinese-holidays-node) 年度数据、只取 `holiday` 条目），法定节假日的工作日按空闲档估算，不再出现约两倍的高估。表中没有的年份（晚于 2026）按公布的峰谷时段处理，即工作日按高峰档——估算偏高而非偏低，是更安全的误差方向。

## 安装

要求 DSH 0.2.2-rc.1 或更高：插件基于 0.2.2-rc.1 DSH cohort 开发（其设置页即宿主根据插件自身 Config schema 生成的页面），`@deepseek-ai/*` 运行时导入由宿主本体提供。

在 profile（如 `~/.dsh/profiles/web`）中：

```bash
pnpm add @linxin666/dsh-usage
```

并插入 `cordis.patch.yml`（或使用 bundle patch）：

```yaml
- insert:
    - id: usage
      name: '@linxin666/dsh-usage'
```

宿主半区需要重启 `dsh web`；客户端半区刷新页面即生效。完整家族安装的入口在 `设置 -> Web 扩展 -> 使用统计`，独立安装时保留 `设置 -> 使用统计`。

## 配置

| 键 | 默认 | 含义 |
| --- | --- | --- |
| `enabled` | `true` | 总开关；关闭后不监听、不探测、不注册路由 |
| `pollIntervalSec` | `60` | provider 探测周期（30-3600 秒；改动由宿主重载插件行生效） |
| `retainDays` | `180` | 台账按本地日保留天数（7-730） |

## 已知限制

- 用量统计自插件首次启用起计，不回填历史会话。
- OAuth 类路由（如 qwen OAuth 授权）仅识别类型，不做探测；插件不消耗第三方 OAuth 额度。
- 探测失败时保留上一次数据并展示错误行；过于频繁的轮询可能触发 provider 限流。
- 鲸元券面额只覆盖台账保留窗口（`retainDays`）内的用量：被清理的天同时退出趋势图与票面。
- 日期选择器只列出台账有记录的天：没有用量的那天不会出现，被保留期清理掉的那天点开只会得到空态或全零卡片，而不会显示成别的日期。
- 真实花费观测从第一次官方余额观测开始：更早的消费不回补，且只有观测到的余额下降才累计（余额上涨是充值，永不计费）。