dsh-tokenlens 1.1.0 → 1.2.1

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 本项目遵循 [Semantic Versioning](https://semver.org/)：修复 = PATCH，新功能 = MINOR，不兼容变更 = MAJOR。发布时同步更新 `package.json` 的 `version`、`index.js` 的 `PLUGIN_VERSION` 与本文件（`node scripts/bump-version.mjs <version> "<note>"`）；已发布的条目保持原样。
 
+## 1.2.1 — 2026-10-31
+
+- feat(settings): 图表模式「明细」环形图的窗口选择（今日 / 最近7天 / 最近X天（或最近30天）/ 总计）持久化到插件设置：点击 pill 立即保存，重开弹窗、切换供应商或重启 DSH 后仍保留上次选择；当前供应商没有该窗口时自动回落到总计
+- feat(wire): `providers` 载荷与 `settingsUpdate` 增加 `settings.detailsWindow`（`today|last7Days|second|total`），旧 Host 会忽略未知字段、旧 client 读取时回落 `total`，双向兼容
+- 修复：请求进行中连续点击窗口时只保留最后一个选择（单定时器 200ms 重试）；「恢复默认设置」同时把窗口重置为总计
+- 测试：255 个自动化用例（新增 5 个持久化回归，更新 8 个既有设置/窗口用例）
+
+## 1.2.0 — 2026-10-31
+
+- feat(chart): 图表模式点击某一天的柱子可下钻查看**当天 24 小时**的 Token 消耗棒状图（横轴 00:00–23:00，悬浮显示小时与占比，回车/空格同样可操作，返回或再次点击回到日趋势）
+- feat(chart): 小时数据覆盖全部 5 个本机 harness（DSH、ZCode、OpenCode CLI、WorkBuddy、Qoder）；无小时数据的旧日期不可下钻，不伪造全零序列
+- feat(chart): 图表模式「明细」的三张环形图（按 Harness / 按供应商 / Top 模型）新增 **今日 / 最近7天 / 最近X天（或最近30天）/ 总计** 窗口切换，默认总计；切换 scope 或数据/图表视图时保持，缺失窗口自动隐藏
+- feat(wire): `stats.daily[]` 新增可选 `hours`（24 个本地小时 Token 整数）与 `providers[pid].hours`（v1.2.0 协议，已在 PROTOCOL 中写明）
+- 测试：250 个自动化用例（新增 13 个：小时聚合、外部 harness 小时分组、下钻交互与窗口切换的前后端回归）
+
 ## 1.1.0 — 2026-10-30
 
 - feat(providers): 接入 Open Design（OpenDesign）只读额度查询——Design Plan 的 5 小时 / 7 天窗口已用百分比与重置时间，以及独立的钱包 USD 余额

package/PROTOCOL.md

@@ -180,9 +180,19 @@ with `[path]`.
       { "key": "opencode-go/deepseek-v4.1-flash", "providerId": "opencode-go",
         "modelId": "deepseek-v4.1-flash",
         "today": { "total": …, "messages": … },
+        "last7Days": { "total": …, "messages": … },
         "last30Days": { "total": …, "messages": … },
         "allTime": { "total": …, "messages": … } }
     ],
+    "daily": [                                  // <=120 days, ascending; chart series
+      { "day": "2026-10-25",
+        "total": { "total": 123456, "messages": 42 },
+        "hours": [0, 0, 0, 1234, 5678, …],      // 24 integers: local-hour token totals
+        "providers": {
+          "opencode-go": { "total": 1234, "messages": 5,
+                           "hours": [0, 0, 0, 500, 734, …] }
+        } }
+    ],
     "zcode": {                                  // extra-harness detail
       "dbPath": "C:\\Users\\…\\.zcode\\cli\\db\\db.sqlite",
       "available": true, "error": null, "rows": 65, "cached": false,
@@ -263,6 +273,12 @@ with `[path]`.
   breakdown and top models are labeled DSH-only.
 - An unavailable/disabled statistics service answers
   `{ ok: false, error: { code: "stats-unavailable" } }`.
+- **Hourly drill-down (v1.2.0)**: `daily[].hours` and
+  `daily[].providers[id].hours` are 24-element arrays of local-hour token totals
+  (`[0..23]`, rounded integers) used by the chart mode. Every bundled harness
+  contributes when it exposes event timestamps; a day without the field is not
+  drillable and the client must not invent an all-zero hour series. DST fall-back
+  hours collapse into one local hour slot.
 
 ## Error shape
 
@@ -302,7 +318,7 @@ needs no provider catalog of its own.
 
 The dialog 「供应商管理」 page talks to three additional actions:
 
-- `{action:"providers"}` → `{ok:true, providers:[{providerId,label,shortLabel,kind,enabled,hasKey,keySource,apiKeyRef,baseURL,consoleUrl,builtin,dshManaged,dshProviderId}], dshProviders:[{providerId,label,supported,usageProviderId}], settings:{labelStyle:"short"|"full"}, storeFile, storeFileDisplay}`. `storeFile` is the real path (local tooling); `storeFileDisplay` replaces the user's home directory with `~` and is what the management page renders.
+- `{action:"providers"}` → `{ok:true, providers:[{providerId,label,shortLabel,kind,enabled,hasKey,keySource,apiKeyRef,baseURL,consoleUrl,builtin,dshManaged,dshProviderId}], dshProviders:[{providerId,label,supported,usageProviderId}], settings:{labelStyle,defaultView,defaultScope,detailsExpanded,detailsWindow}, storeFile, storeFileDisplay}`. `storeFile` is the real path (local tooling); `storeFileDisplay` replaces the user's home directory with `~` and is what the management page renders.
 - `{action:"providerUpdate", providerId, update:{enabled?,apiKey?,apiKeyRef?,baseURL?,consoleUrl?,label?,shortLabel?}}` → same list payload;
   empty strings clear a stored value (falling back to the profile/default). `label` (全名, ≤40 chars) and
   `shortLabel` (短标签, ≤12 chars) let the management page rename a provider. The shipped management page no
@@ -310,9 +326,7 @@ The dialog 「供应商管理」 page talks to three additional actions:
   saves enabled/consoleUrl/label/shortLabel. Overrides are persisted atomically to
   `$DSH_HOME/dsh-tokenlens/providers.json` (plugin-owned, not the profile patch); the same file also
 - `{action:"providerTest", providerId}` → the normal snapshot envelope (`{ok,snapshot}` or `{ok:false,error}`), forcing one upstream read.
-- `{action:"settingsUpdate", settings:{labelStyle:"short"|"full"}}` → the same providers payload; the choice is
-  persisted in the store (`settings.labelStyle`) and controls whether the composer chip shows each
-  provider's `shortLabel` or full `label`. Invalid values answer `unsupported-provider`.
+- `{action:"settingsUpdate", settings:{labelStyle?:"short"|"full", defaultView?:"chart"|"data", defaultScope?:"provider"|"all", detailsExpanded?:"auto"|"expanded"|"collapsed", detailsWindow?:"today"|"last7Days"|"second"|"total"}}` → the same providers payload; every field is optional and persisted in the store (`settings.*`). `labelStyle` controls whether the composer chip shows each provider's `shortLabel` or full `label`; `defaultView` / `defaultScope` / `detailsExpanded` are the usage-dialog defaults; `detailsWindow` (v1.2.1) is the remembered 明细 donut window (falls back visually to `total` when that window is unavailable on the current provider/host). Invalid values answer `unsupported-provider`.
 
 `dshProviders` lists every route registered in DSH model settings (in order) with a `supported` flag (whether a usage adapter exists); the shipped management page renders those routes as the primary list and keeps unconfigured preset adapters in a collapsed secondary section. `dshManaged`/`dshProviderId` tell the management page that the route already exists in DSH model settings
 (opencode-go / commandcode / deepseek), so the page can inherit the key and base URL instead of asking for them
@@ -416,9 +430,13 @@ configure the `opencode-go` provider.
      or a balance card; Command Code also shows remaining/granted credits;
    - **token statistics**: tabs 「当前供应商 · 全部 Harness」 (default; cards = that
      provider's tokens across DSH + ZCode) / 「全部 Harness」 (all providers);
-     cards show 今日 / 最近30天 / 总计 (total tokens, input/output/cache, request
-     count); a 「按 Harness」breakdown for the active scope; DSH provider
-     breakdown and DSH top models; an unmapped-ZCode note when present;
+     cards show 今日 / 最近7天 / 最近X天(或最近30天) / 总计 (total tokens,
+     input/output/cache, request count); a 「按 Harness」breakdown for the active
+     scope; DSH provider breakdown and DSH top models; an unmapped-ZCode note when
+     present;
+   - **chart mode**: the daily bar chart, a click on a day bar drills into that
+     day's 24 local-hour bars (when the Host delivers `daily[].hours`), and the
+     明细 donuts switch between 今日 / 最近7天 / 最近X天 / 总计;
    - refresh (usage + stats), last-updated/stale line, error banners, console link.
 3. Everything client-side must work with only the shell's seeded modules
    (`react`, `react-dom`, `@deepseek-ai/dsh-client-ui-primitives`) — no build step.

package/README.en.md

@@ -9,7 +9,7 @@
 
 > One glance at your usage: plan capacity for the selected provider plus local token statistics across harnesses, right below the DSH composer.
 
-**dsh-TokenLens** is a usage plugin for DSH (DeepSeek Harness), version v1.1.0. It keeps two kinds of numbers separate:
+**dsh-TokenLens** is a usage plugin for DSH (DeepSeek Harness), version v1.2.1. It keeps two kinds of numbers separate:
 
 - **Plan capacity** — the provider's authoritative server-side values (percentage windows, used / cap, balance or remaining credit);
 - **Local token stats** — tokens consumed on this machine across every connected harness, for the selected provider or for all providers combined.
@@ -20,8 +20,8 @@ Everything is computed locally: zero runtime dependencies, no external database,
 
 - **Usage chip below the composer** — follows the selected model provider and shows its plan capacity; providers without an adapter or credentials stay hidden.
 - **Details dialog** — plan capacity windows with reset times (plus an optional "consumed · estimated consumable" hint) and local token stats for today / last 7 days / last 30 days / all-time, scoped to the current provider or all harnesses.
-- **Data and chart modes** — tables, a daily trend chart and ring charts; breakdowns by harness, provider, top model and unmapped providers.
-- **Provider management page** — enabled / built-in / all filters, enable switches, credential status, console links, label editing, connection tests, subscription badges and plugin settings.
+- **Data and chart modes** — tables, a daily trend chart and ring charts with breakdowns by harness, provider, top model and unmapped providers. In chart mode, clicking a day's bar drills into that day's 24 hourly bars; the 明细 rings switch between today / last 7 days / last X days (or last 30 days) / all time.
+- **Provider management page** — enabled / built-in / all filters, enable switches, credential status, console links, label editing, connection tests, subscription badges and plugin settings (label style, default view/scope, details expansion, default 明细 donut window).
 - **Auto-discovery and agent tool** — providers configured in DSH Settings → Model Services are detected by route id or base-URL host and reuse their DSH credentials; `tokenlens_usage` lets the model query snapshots, local stats and diagnostics.
 - **Local-only** — 5 harnesses (DSH, ZCode, OpenCode CLI, WorkBuddy / CodeBuddy CLI, Qoder CN CLI), 25 built-in providers (16 with plan / balance adapters), read-only local data, no telemetry.
 
@@ -66,7 +66,7 @@ dsh plugin --profile <profile> add dsh-tokenlens
 Then make sure `dsh.profile.bundles` in `$DSH_HOME/profiles/<profile>/package.json` contains `"dsh-tokenlens"`:
 
 ```jsonc
-{ "dependencies": { "dsh-tokenlens": "^1.1.0" },
+{ "dependencies": { "dsh-tokenlens": "^1.2.1" },
   "dsh": { "profile": { "bundles": ["…", "dsh-tokenlens"] } } }
 ```
 
@@ -134,7 +134,7 @@ Host bridge route: `/api/tokenlens`; agent tool: `tokenlens_usage`.
 
 ## Development
 
-Node.js ≥ 24, zero runtime dependencies: `node --test` runs the 237 tests.
+Node.js ≥ 24, zero runtime dependencies: `node --test` runs the 255 tests.
 
 Release: `node scripts/bump-version.mjs <version> "<note>"` updates `package.json`, `PLUGIN_VERSION` and `CHANGELOG.md`; see [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md).
 

package/README.md

@@ -9,7 +9,7 @@
 
 > **一眼看清你的用量**：在 DSH 输入框下方显示当前供应商的套餐容量，并汇总本机跨 Harness 的 Token 消耗。
 
-**dsh-TokenLens（词元透镜）** 是 DSH（DeepSeek Harness）的用量插件（v1.1.0，公开版本）。它把两类数字**按不同口径**分开呈现：
+**dsh-TokenLens（词元透镜）** 是 DSH（DeepSeek Harness）的用量插件（v1.2.1，公开版本）。它把两类数字**按不同口径**分开呈现：
 
 - **套餐容量**（供应商服务端权威值）：百分比窗口、`已用 / 上限`、账户余额或剩余额度；
 - **本机 Token 统计**（本机记录）：当前供应商在本机所有已接入 Harness 上的合计用量，也可切到「全部 Harness」看总账。
@@ -39,9 +39,9 @@
 - **详情弹窗**（点击 chip 打开）：
   - **套餐容量**：5 小时 / 本周 / 本月等原生窗口的已用百分比、重置时间与绝对重置日期；余额类供应商显示余额。每个窗口附带一行 `已消耗 · 预计可消耗` 估算（由本机 Token 记录 ÷ 套餐百分比推算，仅供参考）。
   - **本机 Token 统计**：今日 / 最近 7 天 / 最近 30 天 / 总计（订阅类供应商显示「最近 X 天」生效窗口），可按「当前供应商 · 全部 Harness」与「全部 Harness」两个视角查看。
-  - **明细与图表**：按 Harness、按供应商、Top 模型、未映射供应商分组；支持「数据」（表格）与「图表」（每日趋势柱状图 + 环形占比图）两种模式切换。
+  - **明细与图表**：按 Harness、按供应商、Top 模型、未映射供应商分组；支持「数据」（表格）与「图表」两种模式切换。图表模式里点击某一天的柱子可下钻查看**当天 24 小时**的 Token 消耗，底部「明细」环形图支持 **今日 / 最近 7 天 / 最近 X 天（或最近 30 天）/ 总计** 窗口切换。
   - **工作区徽标**（实验性）：左侧工作区列表的名称旁显示该工作区的本机 Token 合计，悬浮卡片显示今日 / 7 天 / 30 天 / 总计；纯展示，找不到对应 UI 时自动降级。
-- **供应商管理页**：「已配置 / 内置 / 全部」筛选、启用开关、凭据状态、控制台链接、短标签与全名编辑、测试连接、已订阅徽章；另有「插件设置」可配置标签样式、默认展示模式、默认统计范围与明细展开状态。
+- **供应商管理页**：「已配置 / 内置 / 全部」筛选、启用开关、凭据状态、控制台链接、短标签与全名编辑、测试连接、已订阅徽章；另有「插件设置」可配置标签样式、默认展示模式、默认统计范围、明细展开状态与图表「明细」环形图的默认窗口（今日 / 最近 7 天 / 最近 X 天 / 总计，记住上次选择）。
 - **自动识别**：在 DSH「设置 → 模型服务」中配置过的供应商会自动出现在管理页，并按路由 id 或 baseURL 主机匹配内置用量适配器，自动继承 DSH 中的凭据，无需重复填写。
 - **Agent 工具**：注册 `tokenlens_usage`，模型可以自行查询套餐容量与本机用量。
 
@@ -106,7 +106,7 @@ dsh plugin --profile <profile> add dsh-tokenlens
 ```jsonc
 {
   "dependencies": {
-    "dsh-tokenlens": "^1.1.0"
+    "dsh-tokenlens": "^1.2.1"
   },
   "dsh": {
     "profile": {
@@ -389,7 +389,7 @@ Host 半注册 `tokenlens_usage`，参数 `action`（默认 `snapshot`）与可
 
 ## 验证
 
-- `node --test`：**237 个自动化用例**，覆盖 Host 数据层、供应商适配器、统计折叠、各 harness 读取、插件集成与浏览器端渲染 / 交互。
+- `node --test`：**255 个自动化用例**，覆盖 Host 数据层、供应商适配器、统计折叠、各 harness 读取、插件集成与浏览器端渲染 / 交互。
 - 在真实环境中验证过 **5 个 harness** 的数据源；本机统计与独立的 SQLite 查询、独立的日志解析逐项对账（差额为 0），跨 harness 合并与供应商映射算术自洽。
 - 供应商接口按各官方文档与参考客户端行为验证；未配置凭据时 chip 静默隐藏，接口异常时按可重试错误降级。
 
@@ -400,7 +400,7 @@ Host 半注册 `tokenlens_usage`，参数 `action`（默认 `snapshot`）与可
 ```powershell
 git clone https://github.com/daigahou/dsh-tokenlens.git
 cd dsh-tokenlens
-node --test        # 237 个用例
+node --test        # 255 个用例
 ```
 
 本地联调安装方式见[方式 C](#方式-c本地开发从源码-link)。