@linxin666/dsh-usage 0.4.4 → 0.4.5

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   node scripts/verify-docs.mjs --write <dir>
-README.md: ce35e9cda06a1c0d34c1c37170eece47ffa2a80c
-README.zh.md: 4199ceccb73a627ba4bef72c4857d4a80c144020
+README.md: 6300aa8ace7fe2d26e7b1bf19627760731b3e9d8
+README.zh.md: 0ea06549aeea2a968655f42f2fb3287e38c01c40

package/README.md

@@ -1,16 +1,29 @@
-# dsh-usage
+# dsh-usage · Token Usage Breakdown, API Balance & Cost Monitor for DeepSeek Harness (DSH)
 
 English | [中文](README.zh.md)
 
-Usage statistics plugin for the dsh web GUI: per-provider balance and coding-plan quota detection plus a live token usage ledger, with a compact price glance card above the sidebar's Settings row.
+<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.0--rc.2-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>Token Usage Breakdown, Multi-Provider Balance & Cost Monitor for DeepSeek Harness (DSH)</strong><br>
+  <em>Daily Token Analytics · Provider API Balance · Subscription Quotas · Peak/Off-Peak Costing · Token Bank</em>
+</p>
+
+A dedicated token usage and cost monitoring plugin for DeepSeek Harness (DSH) Web GUI and official desktop client: multi-provider balances, coding subscription quota tracking, live token accounting ledgers, and a compact quick-glance card above settings in the sidebar.
 
 ## What it does
 
 The plugin runs a host-side service and a first-level settings section (使用统计, directly below the Workshop entry):
 
-- **Usage tab (用量)**: today's token totals per bucket (input / output / cache read / cache write, disjoint as the provider reports them) with per-provider and per-model breakdown, the last 30 days as a horizontal provider/model bar chart, and the balance of every configured provider (one row per adapter family: a dormant catalog alias shadowed by the family's live route no longer renders its own balance row). For the official DeepSeek family the tab also shows the current peak/off-peak pricing period (Beijing weekdays 09:00-12:00 and 14:00-18:00 are peak, billed at double) and today's estimated spend in CNY. The ledger folds live `session/event` streams (`request/header` route attribution plus `assistant/message` usage) into `$DSH_HOME/dsh-usage/usage-ledger.json` with day-based retention; counting starts when the plugin is first enabled.
+- **Usage tab (用量)**: today's token totals per bucket (input / output / cache read / cache write, disjoint as the provider reports them) with per-provider and per-model breakdown, the last 30 days as a horizontal provider/model bar chart, and the balance of every configured provider (one row per adapter family: a dormant catalog alias shadowed by the family's live route no longer renders its own balance row). A **day picker** switches that card to any retained day that recorded usage (today first, then the other days newest first) and the card then shows that day's own totals, provider rows, and estimated spend; the peak/off-peak line stays on today because it describes the pricing window now. The ledger folds live `session/event` streams (`request/header` route attribution plus `assistant/message` usage) into `$DSH_HOME/dsh-usage/usage-ledger.json` with day-based retention, so past days survive restarts; counting starts when the plugin is first enabled. For the official DeepSeek family the tab also shows the current peak/off-peak pricing period (Beijing weekdays 09:00-12:00 and 14:00-18:00 are peak, billed at double) and today's estimated spend in CNY.
 - **Plans tab (个人套餐)**: coding-plan quota windows for every configured provider that exposes one — used percent and reset time per window (Kimi For Coding 5h/week, GLM Coding Plan 5h/week/month, OpenCode Go rolling/weekly/monthly, MiniMax 5h/week, Codex / ChatGPT subscription 5h/week). Providers without a real plan or subscription (DeepSeek, ZenMux, Moonshot, OpenRouter, SiliconFlow) never appear on this tab; their balance shows on the usage tab instead.
-- **Token Bank tab (Token 银行)**: the whale-yuan voucher (鲸元券) minted from the official DeepSeek family's ledger at an anti-inflation exchange rate of 1,000,000 tokens per whale yuan. The tab sums the family's retained-ledger tokens (the `deepseek` catalog alias and the live `deepseek-official` route combined), stamps the minted face value onto the banknote artwork with a serial line carrying the minting window, and offers a save-image button plus a native share button when the browser supports sharing files. The spend line shows the real CNY total observed from the official balance once available — balance decreases accrue as spend, top-ups never count — and falls back to the fold-time estimate before the first observation. The minted total prefers the host's whole-ledger aggregate and falls back to the last 30 days on an older host; with no official DeepSeek usage the tab shows its empty state. The on-note text is locale-neutral (digits, latin captions, ISO dates) and the export is rendered locally in the browser.
+- **Token Bank tab (Token 银行)**: the whale-yuan voucher (鲸元券) minted from the official DeepSeek family's ledger at an anti-inflation exchange rate of 1,000,000 tokens per whale yuan. The tab sums the family's retained-ledger tokens (the `deepseek` catalog alias and the live `deepseek-official` route combined), stamps the minted face value onto the banknote artwork with a serial line carrying the minting window, and offers a save-image button plus a native share button when the browser supports sharing files. The spend line shows the real CNY total observed from the official balance once available — balance decreases accrue as spend, top-ups never count — and falls back to the fold-time estimate before the first observation. The minted total prefers the host's whole-ledger aggregate and falls back to the last 30 days on an older host; with no official DeepSeek usage the tab shows its empty state. A day picker mints the note from one picked day instead of the whole retention window (the observed-spend line, which accrues from the first balance reading, is whole-window only and falls back to that day's fold-time estimate on a single day). The on-note text is locale-neutral (digits, latin captions, ISO dates) and the export is rendered locally in the browser.
 - **Sidebar foot card**: a compact glance seated above the sidebar's Settings row — today's estimated spend as the headline (today's tokens when nothing priced is recorded yet), the tokens/calls line, and up to two configured-provider balances with a +N overflow. The whole card is one button that opens the usage settings section, so detail stays in one place, and the corner chevron folds it into a one-line strip (the spending provider's name, the label, and the headline value), a choice persisted across reloads. It polls at a relaxed 30 s cadence while the tab is visible, hides in the collapsed 56 px rail, and disappears while the plugin is disabled.
 - Probes run entirely host-side on a poll cycle (default 60 s, manual refresh button); API keys are resolved through the harness credential seam (`llm-pi-ai` records, `apiKeyEnv` references) and never reach the browser.
 
@@ -22,9 +35,11 @@ Today's spend is an estimate priced at fold time from the published DeepSeek pea
 
 It covers the official DeepSeek routes only — relay traffic billed elsewhere (ZenMux, SiliconFlow, ...) stays unpriced — and unknown DeepSeek model ids take the flash-class row. Buckets recorded before a price change keep the old pricing, so a price-book update is reflected from the moment it ships, not retroactively.
 
+The published rule bills a Chinese public holiday entirely off-peak even on a Monday-Friday, and bills an adjusted workday falling on a Saturday or Sunday off-peak too. Weekends are therefore already off-peak by construction, and this package ships the State Council holiday table (`src/core/holidays.ts`, 2020 through 2026, taken from the MIT-licensed [chinese-holidays-node](https://github.com/bastengao/chinese-holidays-node) yearly data with only its `holiday` entries), so a public-holiday weekday is estimated at the off-peak row instead of reading up to about twice the real spend. A year the table does not cover (later than 2026) falls back to the published windows, which reads high rather than low — the safer direction to be wrong in.
+
 ## Install
 
-Requires DSH 0.2.0-rc.1 or later: the plugin is developed against the 0.2.0-rc.1 DSH cohort (its settings page is the Host-generated page of the plugin's own Config schema) and its `@deepseek-ai/*` runtime imports are provided by the host itself.
+Requires DSH 0.2.0-rc.2 or later: the plugin is developed against the 0.2.0-rc.2 DSH cohort (its settings page is the Host-generated page of the plugin's own Config schema) and its `@deepseek-ai/*` runtime imports are provided by the host itself.
 
 In your profile (e.g. `~/.dsh/profiles/web`):
 
@@ -56,4 +71,5 @@ Restart `dsh web` for the host half; the client half applies on refresh. The sec
 - OAuth-based routes (for example qwen OAuth grants) are detected as such but not probed; the plugin does not spend third-party OAuth budgets.
 - A failed probe keeps the previous fact visible and reports the error line; providers may rate-limit aggressive polling.
 - The voucher's face value covers the ledger's retention window (`retainDays`): pruned days drop out of both the trend chart and the note.
+- The day pickers list only days the ledger recorded usage on: a day without usage is never offered, and a day pruned by retention leaves an empty or zeroed card rather than a different one.
 - The real-spend watch starts at the first official balance observation: earlier consumption is not backfilled, and only observed balance decreases accrue (a balance rise is a top-up and never counts).

package/README.zh.md

@@ -1,16 +1,29 @@
-# dsh-usage
+# dsh-usage · DeepSeek Harness (DSH) Token 用量明细、API 余额与成本监控插件
 
 [English](README.md) | 中文
 
-dsh Web GUI 的使用统计插件：多 provider 余额与编程套餐用量检测，外加实时 token 用量台账，并在侧栏「设置」行上方提供紧凑的价格速览卡。
+<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.0--rc.2-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 用量台账与成本估算，并在侧栏「设置」行上方提供紧凑的价格速览卡。
 
 ## 功能
 
 插件由宿主侧服务与设置页一级分区（使用统计，位于创意工坊下方）组成：
 
-- **用量页签**：今日 token 分桶合计（输入 / 输出 / 缓存读 / 缓存写，按 provider 上报口径互不相加），分 provider 与模型细分，近 30 天以「提供方-模型」水平条形图展示，以及所有已配置 provider 的余额（同一适配器家族只渲染一行：被该家族运行时路由遮蔽的休眠目录别名不再单独出余额行）。对 DeepSeek 官方路由，页签还展示当前峰谷计价时段（北京时间工作日 09:00-12:00、14:00-18:00 为高峰，按双倍计费）与今日消费估算（CNY）。台账从 `session/event` 实时流折叠（`request/header` 归因路由 + `assistant/message` 用量），持久化到 `$DSH_HOME/dsh-usage/usage-ledger.json`，按本地日保留；统计自插件首次启用起计。
+- **用量页签**：今日 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 银行页签**：以 DeepSeek 官方家族的台账用量铸造「鲸元券」，汇率按 100 万 tokens 兑 1 鲸元（防膨胀）。页签把该家族保留台账内的 token 总量（`deepseek` 目录别名与运行时路由 `deepseek-official` 合并计算）折算成票面面额印在钞票图上，附带走票窗口的序列号行，并提供保存图片按钮与（浏览器支持文件分享时的）系统分享按钮。消费行优先展示从官方余额观测到的真实累计花费——余额下降即计为消费，充值上涨不计——首次观测到下降之前回落为折叠时刻估算。铸造总量优先取宿主的全台账聚合，旧宿主回落为近 30 天；无官方用量时展示空状态。票面文字与语言无关（数字、拉丁小字、ISO 日期），导出图在浏览器本地渲染。
+- **Token 银行页签**：以 DeepSeek 官方家族的台账用量铸造「鲸元券」，汇率按 100 万 tokens 兑 1 鲸元（防膨胀）。页签把该家族保留台账内的 token 总量（`deepseek` 目录别名与运行时路由 `deepseek-official` 合并计算）折算成票面面额印在钞票图上，附带走票窗口的序列号行，并提供保存图片按钮与（浏览器支持文件分享时的）系统分享按钮。消费行优先展示从官方余额观测到的真实累计花费——余额下降即计为消费，充值上涨不计——首次观测到下降之前回落为折叠时刻估算。铸造总量优先取宿主的全台账聚合，旧宿主回落为近 30 天；无官方用量时展示空状态。页签的日期选择器可把票券改为按某一天铸造（真实花费观测行是自首次余额观测起的累计值，只在整段窗口下展示，单日票券回落为该日的折叠时刻估算）。票面文字与语言无关（数字、拉丁小字、ISO 日期），导出图在浏览器本地渲染。
 - **侧栏底部速览卡**：位于侧栏「设置」行上方、与更新/远程触发器同组的紧凑卡片——头条为今日消费估算（今日尚无可计价用量时回落为 tokens 总量），下方是 tokens/调用次数行，以及最多两个已配置 provider 的余额（超出折叠为 +N）。整张卡片主体是一个按钮，点击打开使用统计设置分区，细节只保留在一处；右上角箭头可把卡片收成一行摘要条（消费提供方名称 + 标签 + 头条值），选择跨刷新保持。标签页可见时以 30 秒的宽松周期轮询，侧栏折叠为 56px 栏轨时隐藏，插件停用时消失。
 - 探测完全在宿主侧按轮询周期执行（默认 60 秒，可手动刷新）；API key 经宿主凭据缝解析（`llm-pi-ai` 记录、`apiKeyEnv` 引用），永不进入浏览器。
 
@@ -22,9 +35,11 @@ dsh Web GUI 的使用统计插件：多 provider 余额与编程套餐用量检
 
 估算仅覆盖 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.0-rc.1 或更高：插件基于 0.2.0-rc.1 DSH cohort 开发（其设置页即宿主根据插件自身 Config schema 生成的页面），`@deepseek-ai/*` 运行时导入由宿主本体提供。
+要求 DSH 0.2.0-rc.2 或更高：插件基于 0.2.0-rc.2 DSH cohort 开发（其设置页即宿主根据插件自身 Config schema 生成的页面），`@deepseek-ai/*` 运行时导入由宿主本体提供。
 
 在 profile（如 `~/.dsh/profiles/web`）中：
 
@@ -56,4 +71,5 @@ pnpm add @linxin666/dsh-usage
 - OAuth 类路由（如 qwen OAuth 授权）仅识别类型，不做探测；插件不消耗第三方 OAuth 额度。
 - 探测失败时保留上一次数据并展示错误行；过于频繁的轮询可能触发 provider 限流。
 - 鲸元券面额只覆盖台账保留窗口（`retainDays`）内的用量：被清理的天同时退出趋势图与票面。
+- 日期选择器只列出台账有记录的天：没有用量的那天不会出现，被保留期清理掉的那天点开只会得到空态或全零卡片，而不会显示成别的日期。
 - 真实花费观测从第一次官方余额观测开始：更早的消费不回补，且只有观测到的余额下降才累计（余额上涨是充值，永不计费）。