dsh-usage-stats

面向 DeepSeek Harness Web GUI（dsh web）的本地用量中心：统一查看 Token、余额、套餐额度、DeepSeek 费用估算和每日趋势。

The local usage, balance, quota, and billing companion for DeepSeek Harness Web.

文档导航： 核心亮点 · Provider 支持 · 界面预览 · 快速安装 · 配置 · 数据与隐私

核心亮点 / Features

能力	你可以做什么
用量查询中心	有活动会话时从侧栏打开宿主原生右侧 Sidebar；无活动会话时打开宿主全局主面板；旧宿主再回退到 Modal
多供应商账户	展示 DeepSeek/Moonshot 余额、Z.ai/Kimi/MiniMax/OpenCode Go 套餐窗口、OpenRouter Key 额度与账户 Credits；小米及 MiMo Token Plan 提供官方查询入口；账户概览最多固定 3 个供应商
时间与模型分析	查看今日 / 本月 / 累计 Token、请求次数、24 小时输入输出、模型拆分、缓存命中率与自然年贡献热图
费用与限额	冻结 DeepSeek 官方调用费用，配置每日消费限额、余额提醒、预警比例、通知和可选超限停止
本机数据边界	API Key 只在服务端凭据服务中解析；统计账本、设置和告警保存在本机，插件 RPC 仅经宿主本机认证围栏访问

查询面板保持只读。默认展示供应商、计费、限额、通知和数据管理统一位于「设置 → 用量与计费」。切换默认展示供应商不会改变模型调用路由。会话过程显示由 Harness 原生「设置 → 通用设置 → Conversation display」控制。

数据口径

Token 来自 provider-reported usage（assistant/chunk、assistant/message 或 llm/stream usage chunk），统计 API 不使用本地 tokenizer 估算。
请求次数按 provider/model 的独立用量样本统计；同一 (turn, step) 的流式中间样本与最终样本只计一次。冻结归档沿用每个模型桶的 entryCount。
调用级 ledger 按 provider/model 归集；日期、小时、费用和「今日」限额均按请求完成时间对应的北京时间计算。
只有 deepseek-official 参与 CNY 费用估算和消费限额；其他供应商保留 Token、余额或套餐额度展示。
界面支持中文和英文；供应商列表来自 Harness 当前已经添加的可配置 provider route，不会猜测或探测未知远端接口。

Provider 支持

route 示例	远端查询	能否直接复用模型设置中的 Key	展示与额外操作
`deepseek-official`、`deepseek`	`/user/balance`	可以	余额、CNY 费用估算、每日消费限额与余额提醒
`moonshotai`、`moonshotai-cn`	`/v1/users/me/balance`	可以	USD/CNY 可用余额、现金与代金券余额；Key 必须与国际/国内站匹配
`openrouter`	`/api/v1/key`，可选 `/api/v1/credits`	Key 查询可复用	普通模型 Key 的消费上限、已用与剩余额度；账户 Credits 需额外配置 `OPENROUTER_MANAGEMENT_KEY`，不会拿普通模型 Key 试探该接口
`opencode-go`	`/zen/go/v1/usage`	可以	OpenCode Go 5 小时滚动 / 每周 / 每月订阅窗口；已有接口查询，不重复显示官网按钮
`opencode`	无 API-key 余额接口	不适用	不读取网页登录态；显示 OpenCode Zen workspace 查询入口
`kimi-coding`	`/coding/v1/usages`	可以	5 小时 / 每周 Token 窗口；月总额度不读取网页登录态，提供 Kimi 我的额度入口
`minimax`、`minimax-cn`	Token Plan 查询（兼容多个官方路径）	可以	5 小时 / 每周比例窗口
`zai`、`zai-coding-cn`	`/api/monitor/usage/quota/limit`	可以	5 小时 / 每周剩余比例与重置时间
`xiaomi`	无稳定的 API-key 用量接口	不适用	不读取网页登录态；显示 MiMo API Key 用量入口
`xiaomi-token-plan-cn`、`xiaomi-token-plan-ams`、`xiaomi-token-plan-sgp`	暂无稳定的 API-key 配额接口	不适用	不读取 Cookie/CDP；显示 MiMo Token Plan 官网查询入口

declared 只表示 Harness 目录来源，不代表官方认证。插件仅过滤 vision-toolkit-* facade，其余已添加 route 按 Harness 原名展示；没有内置远端适配器的 provider 仍可统计本地 Token。

设置结构

「设置 → 用量与计费」按职责拆分为四个标签：

标签	内容
供应商与账户	选择默认供应商和最多 3 个账户概览项，查看账户快照，配置额外只写查询凭据、刷新周期与侧栏摘要；不会修改模型调用路由
供应商用量与计费	DeepSeek 限额、余额提醒、峰谷价格与可选硬停止；套餐 provider 的窗口状态阈值
通知与提示	侧栏状态点、页面 Toast、预警/超限/余额不足/恢复事件、冷却时间和进程内告警历史
数据管理	近期精细记录、冻结金额精确归档与历史估算范围；按北京日历裁剪、恢复估算或二次确认清空本地数据

每日消费进度只表达「今日消费 / 每日限额」，不会被余额提醒状态改变。套餐阈值仅控制状态提示颜色，不会修改供应商真实额度。

界面预览 / Screenshots

查询中心首次打开进入「概览」并聚焦默认展示供应商；「全部」以多模型趋势、跨供应商模型排行和工作区 Token 分布汇总全局用量；「明细」可从全部供应商历史用过的模型中筛选最近日期用量。套餐供应商显示窗口额度和重置时间，余额型供应商显示余额；年度热图、小时趋势和模型拆分适用于各类已记录用量。点击任意缩略图可查看原始截图。

[![全部供应商用量概览](https://raw.githubusercontent.com/wannanbigpig/dsh-usage-stats/eda4a27734878d5839854c2834b50e61005388dd/docs/assets/screenshots/usage-overview-all.png)](https://raw.githubusercontent.com/wannanbigpig/dsh-usage-stats/eda4a27734878d5839854c2834b50e61005388dd/docs/assets/screenshots/usage-overview-all.png)

全部供应商概览 DeepSeek 余额与用量 Z.ai 套餐额度

[![MiMo Token Plan 用量概览](https://raw.githubusercontent.com/wannanbigpig/dsh-usage-stats/eda4a27734878d5839854c2834b50e61005388dd/docs/assets/screenshots/usage-overview-xiaomi-token-plan.png)](https://raw.githubusercontent.com/wannanbigpig/dsh-usage-stats/eda4a27734878d5839854c2834b50e61005388dd/docs/assets/screenshots/usage-overview-xiaomi-token-plan.png)

MiMo Token Plan 按日明细供应商与账户设置

快速安装 / Quick start

0.5.1 已按 DeepSeek Harness dsh-v0.1.5-rc.2 的最新 master（c291e7961a）核对并适配。包清单使用 dsh.manifestVersion: 1，并通过顶层 engines.dsh 声明完整 UI 兼容范围 >=0.1.5-rc.1 =0.1.5-rc.1 与 @deepseek-ai/dsh-client-ui-primitives >=0.1.3-alpha.2，独立 RPC channel 依赖 @deepseek-ai/dsh-host-webserver >=0.1.3-alpha.2，插件自身支持 Node.js >=18，运行最新宿主应遵守其 Node.js ^22.19 || >=24 要求。插件直接依赖 storageDomain、settings、connection.rpc、webServer 与 sessionPersistence，不再兼容缺少这些官方 seam 的旧 Harness。服务端仍保留 dsh-v0.1.2-alpha.3 与 dsh-v0.1.1-rc.2 的接口读取路径，但旧宿主不再属于完整 UI 兼容范围。适配内容：宿主 RPC 通道自 0.1.2-alpha.1 起改由传输层统一认证（旧的通道级 authority 参数被忽略）；最新 Connection 契约要求独立 channel 的调用方同时注入 connection 与 webServer，使 route 归调用插件 Fiber 所有并随其卸载；当前 master 又将 Connection 自身对 webServer 改为可选子注入，而专用 channel 注册仍从 Connection owner Fiber 读取该服务，因此插件的 bundle patch 会同步给 Web profile 的 connection 行补充 webServer；settings 自 0.1.2-alpha.2 起移除 settingsNamespace() 运行时 brand，插件改用纯字符串 namespace（两代宿主均接受）；persistence 读路径对未知事件类型 fail-closed——用量重建遇到由更新宿主写入、当前 Harness 运行时无法解读的 session 时会跳过并在 unreadableSessions 中计数，数据管理页会给出跳过提示，不再整体失败；session-persistence 自 0.1.2-alpha.4 起替换为 handle 化 API（list/open('read')），最新宿主的 handle.read() 返回 { eventState, events }，插件会先归一化其中的 events 再重建；过渡版本直接返回事件数组、旧宿主使用 listSnapshots/readFrom 的路径仍可读取，所有新宿主只读句柄都会在读取后必达关闭；存储域声明 invalidRecords: 'backup-and-skip'（0.1.2-alpha.5 起），单日记录损坏时宿主自动备份该记录并继续打开，旧宿主保持原有的整体拒绝行为。存储格式同步升级到 v4（per-record 按日布局），首次打开自动拆分迁移既有 v3 单文件数据，升级前仍请保留 $DSH_HOME/storages 备份。

最新宿主适配还包括：历史重建按只读句柄的 inheritedEventCount 跳过 fork 继承前缀，避免父会话用量重复统计；读取 assistant/attempt 内嵌流的最后一份 usage，每个已结算尝试分别计入；实时重试以已结算尝试划分账本身份，成功消息只与自己的流式样本去重。旧宿主未提供继承边界时仍按旧读路径处理，不能保证 fork 历史去重。已有重建估算可在「数据管理」重新执行重建以更新，已冻结的实时历史不会被追溯改价或自动修正。

查询面板优先注册到最新宿主的原生右侧 Sidebar，可与主会话并排常驻；没有活动会话时使用宿主 main Slot 的全局主面板，布局服务或面板尚不可用时再回退到原生 Modal。Modal 继续支持 Escape、点击遮罩关闭和焦点返回侧栏。开关、状态标签、状态点与页面通知分别复用宿主 Switch、Tag、StateDot、Toast；右侧栏和全局面板使用宿主基础背景，侧栏入口高度、hover token 和窄栏尺寸与当前宿主 footer 对齐。插件不扫描或替换宿主设置图标，也不修改宿主布局。

升级前请保留 $DSH_HOME/storages 备份。首次启动会为旧 usage-settings.json、usage-limits.json、usage-stats-cache.json 创建固定 .pre-v3.bak 并迁移到官方存储；降级只能恢复升级前备份，0.2.0 期间新增的 v3 数据不会双写回旧格式。

本地 checkout 安装（开发推荐）：在包含插件目录的父目录中执行（官方文档：从包含该包的目录运行），或已在插件根目录内用 .：


# 在 dsh-usage-stats 的父目录中执行
dsh plugin --profile web add ./dsh-usage-stats

## 配置 / Configuration

所有配置都是可选的，默认值即可开箱使用：

| 字段 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `keys` | `string[]` | `["DEEPSEEK_API_KEY"]` | 余额查询使用的凭据引用列表 |
| `defaultKeyRef` | `string` | `DEEPSEEK_API_KEY` | 默认选中的 Key |
| `baseURL` | `string` | `https://api.deepseek.com` | DeepSeek API 地址（`/user/balance` 相对此地址） |
| `refreshMs` | `number` | `300000` | 启动配置中的余额缓存/刷新基线（毫秒，最小 5000）；设置页可选“关闭”停用服务端周期刷新 |
| `pricing.pricing` | `object` | 见下 | `deepseek-official` 模型单价（CNY / 1M tokens）覆盖 |
| `pricing.peakMultiplier` | `number` | `2` | 官方高峰时段价格为低谷时段的 2 倍 |
| `pricing.peakHours` | `[start,end)[]` | `[[9,12],[14,18]]` | 工作日高峰时段，北京时间 09:00–12:00、14:00–18:00；周末规则见下文 |
| `pricing.currency` | `string` | `CNY` | 消费金额显示货币；与 DeepSeek 中国区余额默认币种保持一致 |
| `keyProviders` | `object` | `{}` | Key → provider 路由列表；开启后今日消费按 Key 归集、限额按 Key 判定 |
| `maxLedgerEntries` | `number` | `5000` | 近期完整调用记录容量，可在数据管理页设置为 `100–5000`；超出后旧记录折入冻结金额精确归档 |
| `allowInsecure` | `boolean` | `false` | 允许非 HTTPS `baseURL`（不推荐） |

页面中的“默认展示供应商”和“账户概览显示”属于 Harness 官方 `usage-stats` settings namespace。配置按 schema defaults → 插件 Config base → 用户 section 合成；默认供应商初始为 `deepseek-official` 且始终包含在账户概览中。账户概览最多选择 3 个，这些设置不会修改模型调用路由。

当前内置远端适配器为：DeepSeek `GET /user/balance`、Moonshot/Kimi Open Platform `/v1/users/me/balance`、OpenRouter `/api/v1/key` 与可选 `/api/v1/credits`、OpenCode Go `/zen/go/v1/usage`、Kimi Coding `/coding/v1/usages`、MiniMax Token Plan（包含旧路径回退）、Z.ai `/api/monitor/usage/quota/limit`。普通小米 `xiaomi` 与 `xiaomi-token-plan-{cn,ams,sgp}` 当前没有稳定的 API-key 用量/配额接口，分别显示 API Key 用量页和 Token Plan 管理页；OpenCode Zen 仅显示固定 workspace 查询入口。插件不读取 Cookie、浏览器登录态或外部 CLI 配置；接口失败时保留明确状态，不会把错误当作零额度。

### 按 API Key 统计（keyProviders）

会话日志不记录「用哪个 API Key」，但每个请求都记录 provider 路由。当前只有 `deepseek-official` 路由参与 DeepSeek 消费归集和限额；外部 provider 的映射不会让其 Token 变为 DeepSeek 消费：

```yaml

## 使用 / Usage

1. 侧栏底部 **用量/余额** 会直接显示默认账户余额与今日消费（今日消费为 0 时不显示该段）：本地账本每次成功写入后，今日消费会在约 1 秒内更新；远端余额遵循账户刷新周期，查询面板打开时每分钟同步摘要，关闭时每 5 分钟同步。点击整行优先在宿主右侧 Sidebar 打开查询中心；没有活动会话时打开宿主全局主面板，宿主不提供该能力时再回退到 Modal。窄侧栏模式只显示数据图标。
2. 查询中心分「全部 / 概览 / 明细」三个标签，默认打开「概览」：全部 = 跨供应商 Token 汇总、多模型趋势、供应商/模型排行、工作区 Token 分布与年度热图；概览 = 默认供应商的账户卡、摘要、小时统计、模型拆分与年度热图；明细 = 全部供应商历史已用模型的筛选与最近日期按日明细（点击日期可联动概览小时图）。
3. 顶部余额卡片：DeepSeek 官方余额 + 充值/赠送明细；多个 Key 时可切换；右上角刷新时图标会持续旋转到请求结束，旁边有「前往设置」链接。余额查询失败会缓存错误快照并在 `refreshMs`（默认 5 分钟）内复用，网络错误时余额显示「暂不可用」。
4. 「年度每日用量」：默认只展示今年 1–12 月；右上角切换年份，悬停方块查看整日日期、Token、输入/输出、缓存、费用和模型摘要，点击方块联动当天明细。
5. 「按小时统计」：展示所选日期的 24 小时输入/输出柱状图；零用量小时不渲染数据柱，工作日高峰时段以跨全图的浅色背景区段提示，周末不显示高峰区段并标注全天低谷价；鼠标悬停、键盘聚焦或触屏点击某小时可查看总 Token、输入、输出、缓存、费用和模型拆分。费用与 Token 按**请求完成时间（usage 上报时间）**（北京时）归入对应日期与小时：跨整点或跨日边界的流式请求同样按完成时间归属（如 17:59 发起、18:01 完成的请求计入 18 点小时并按低谷价计费，而不是计入 17 点高峰价），与官方账单口径一致。
6. 限额、价格、通知和展示配置请在「设置 → 用量与计费」中操作；「供应商用量与计费」可独立选择正在编辑的供应商。DeepSeek 可按 Key（或全局）配置每日或每月消费限额、余额提醒线、预警百分比与是否停止新调用；套餐供应商只显示其支持的窗口阈值；开启硬停止时会弹出确认。

@wannanbigpig/dsh-usage-stats

安装

说明文档