dsh-tokenlens 1.0.9 → 1.2.0

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.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 余额
+- feat(providers): Open Design 使用工作区 `workspaceId` + Control Key（`OPENDESIGN_CONTROL_KEY` / `VELA_CONTROL_KEY`）鉴权；推理 API Key 不能查询计费接口
+- feat(ui): `windows` 快照现在可以附带钱包余额——详情弹窗在额度窗口下方多一行「账户余额」，chip 悬浮提示追加金额
+- docs: 中英 README 与 PROTOCOL 补充 Open Design；说明其余仅元数据供应商没有可用 API Key 查询的公开用量接口（千问/百炼额度仅官方 CLI 可查，腾讯混元/百度千帆只有云账户余额 API）
+
 ## 1.0.9 — 2026-10-29
 
 - ci: GitHub Actions 升级到 v7（actions/checkout、actions/setup-node），发布链路仅依赖 OIDC

package/PROTOCOL.md

@@ -95,10 +95,15 @@ Provider semantics:
 | `commandcode` | `windows` | rolling = 5-hour `used/cap`, weekly = `used/cap`, monthly = `(granted - remaining)/granted` (only when the API reports the grant) | `plan`, `credits` (USD), `account` |
 | `deepseek` (picker id `deepseek-official`) | `balance` | `null` | `balance` (API-key account balance, CNY/USD) |
 | `deepseek-account` | `balance` | `null` | `balance` from the composed Platform account service (signed-in wallets) |
+| `open-design` | `windows` | rolling = 5-hour Design Plan window, weekly = 7-day window, monthly = 30-day window when reported (used / limit credits, capped at 100%) | `balance` (independent wallet balance, USD) |
 
 `balance` is `{ amount, currency }` plus, for the account provider,
 `wallets: [{currency, amount}]` and `bonus: [{currency, amount}]`.
 
+A `windows` snapshot may also carry a non-null `balance` (Open Design reports
+allowance windows and a wallet independently); the Client renders it as one extra
+row at the end of the capacity card and appends the amount to the chip tooltip.
+
 Rules:
 
 - `percent` is clamped to `0..100`; an unknown percentage is `null` (render "—"), never a fake 0.
@@ -175,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,
@@ -258,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
 
@@ -411,9 +432,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.0.9. It keeps two kinds of numbers separate:
+**dsh-TokenLens** is a usage plugin for DSH (DeepSeek Harness), version v1.2.0. 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,10 +20,10 @@ 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.
+- **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.
 - **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 (15 with plan / balance adapters), read-only local data, no telemetry.
+- **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.
 
 ## Screenshots
 
@@ -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.0.9" },
+{ "dependencies": { "dsh-tokenlens": "^1.2.0" },
   "dsh": { "profile": { "bundles": ["…", "dsh-tokenlens"] } } }
 ```
 
@@ -105,11 +105,13 @@ Every option is optional. Override the `dsh-tokenlens` row in `$DSH_HOME/profile
 
 Credentials come from DSH itself: providers configured in DSH inherit their `apiKeyEnv`, or you can set environment variables such as `OPENCODE_GO_API_KEY`, `COMMANDCODE_API_KEY` and `DEEPSEEK_API_KEY`.
 
+Open Design (OpenDesign) is the exception: its read-only billing API needs a **workspace ID** plus a **Control Key** (`OPENDESIGN_CONTROL_KEY` or `VELA_CONTROL_KEY`), which is *not* the inference API key from the Cloud API Keys page. Set `providers.open-design.workspaceId` (or `OPENDESIGN_WORKSPACE_ID`) and provide the Control Key through the environment, DSH credentials, or the management page's key field.
+
 See the [Chinese README](README.md) for the full configuration reference, preview and provider tables.
 
 ## Supported providers and harnesses
 
-**Plan capacity / balance adapters:** OpenCode (`opencode-go`, `opencode`), Command Code, DeepSeek, DeepSeek Account, OpenRouter, Moonshot / Kimi, SiliconFlow, StepFun, Novita, Hyperbolic, DeepInfra, Z.ai GLM Coding Plan, MiniMax Coding Plan, Zhipu AI (GLM Coding Plan, CN), Volcengine (Coding / Agent Plan).
+**Plan capacity / balance adapters:** OpenCode (`opencode-go`, `opencode`), Command Code, DeepSeek, DeepSeek Account, OpenRouter, Moonshot / Kimi, SiliconFlow, StepFun, Novita, Hyperbolic, DeepInfra, Z.ai GLM Coding Plan, MiniMax Coding Plan, Zhipu AI (GLM Coding Plan, CN), Volcengine (Coding / Agent Plan), Open Design (Design Plan windows + wallet balance).
 
 **Harnesses:** DSH, ZCode, OpenCode CLI, WorkBuddy / CodeBuddy CLI, Qoder CN CLI.
 
@@ -132,7 +134,7 @@ Host bridge route: `/api/tokenlens`; agent tool: `tokenlens_usage`.
 
 ## Development
 
-Node.js ≥ 24, zero runtime dependencies: `node --test` runs the 231 tests.
+Node.js ≥ 24, zero runtime dependencies: `node --test` runs the 250 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.0.9，公开版本）。它把两类数字**按不同口径**分开呈现：
+**dsh-TokenLens（词元透镜）** 是 DSH（DeepSeek Harness）的用量插件（v1.2.0，公开版本）。它把两类数字**按不同口径**分开呈现：
 
 - **套餐容量**（供应商服务端权威值）：百分比窗口、`已用 / 上限`、账户余额或剩余额度；
 - **本机 Token 统计**（本机记录）：当前供应商在本机所有已接入 Harness 上的合计用量，也可切到「全部 Harness」看总账。
@@ -39,13 +39,13 @@
 - **详情弹窗**（点击 chip 打开）：
   - **套餐容量**：5 小时 / 本周 / 本月等原生窗口的已用百分比、重置时间与绝对重置日期；余额类供应商显示余额。每个窗口附带一行 `已消耗 · 预计可消耗` 估算（由本机 Token 记录 ÷ 套餐百分比推算，仅供参考）。
   - **本机 Token 统计**：今日 / 最近 7 天 / 最近 30 天 / 总计（订阅类供应商显示「最近 X 天」生效窗口），可按「当前供应商 · 全部 Harness」与「全部 Harness」两个视角查看。
-  - **明细与图表**：按 Harness、按供应商、Top 模型、未映射供应商分组；支持「数据」（表格）与「图表」（每日趋势柱状图 + 环形占比图）两种模式切换。
+  - **明细与图表**：按 Harness、按供应商、Top 模型、未映射供应商分组；支持「数据」（表格）与「图表」两种模式切换。图表模式里点击某一天的柱子可下钻查看**当天 24 小时**的 Token 消耗，底部「明细」环形图支持 **今日 / 最近 7 天 / 最近 X 天（或最近 30 天）/ 总计** 窗口切换。
   - **工作区徽标**（实验性）：左侧工作区列表的名称旁显示该工作区的本机 Token 合计，悬浮卡片显示今日 / 7 天 / 30 天 / 总计；纯展示，找不到对应 UI 时自动降级。
 - **供应商管理页**：「已配置 / 内置 / 全部」筛选、启用开关、凭据状态、控制台链接、短标签与全名编辑、测试连接、已订阅徽章；另有「插件设置」可配置标签样式、默认展示模式、默认统计范围与明细展开状态。
 - **自动识别**：在 DSH「设置 → 模型服务」中配置过的供应商会自动出现在管理页，并按路由 id 或 baseURL 主机匹配内置用量适配器，自动继承 DSH 中的凭据，无需重复填写。
 - **Agent 工具**：注册 `tokenlens_usage`，模型可以自行查询套餐容量与本机用量。
 
-支持 5 个 Harness：**DSH、ZCode、OpenCode CLI、WorkBuddy / CodeBuddy CLI、Qoder CN CLI**；内置 25 家供应商元数据，其中 15 家带套餐 / 余额适配器。
+支持 5 个 Harness：**DSH、ZCode、OpenCode CLI、WorkBuddy / CodeBuddy CLI、Qoder CN CLI**；内置 25 家供应商元数据，其中 16 家带套餐 / 余额适配器。
 
 ## 效果截图
 
@@ -106,7 +106,7 @@ dsh plugin --profile <profile> add dsh-tokenlens
 ```jsonc
 {
   "dependencies": {
-    "dsh-tokenlens": "^1.0.9"
+    "dsh-tokenlens": "^1.2.0"
   },
   "dsh": {
     "profile": {
@@ -190,6 +190,7 @@ dsh plugin --profile <profile> remove dsh-tokenlens
 - 在 DSH「设置 → 模型服务」中配置过的供应商会被自动识别，插件按路由 id 或 baseURL 主机匹配内置适配器，并继承该路由的 `apiKeyEnv` 凭据。
 - 也可以直接用环境变量提供，例如 `OPENCODE_GO_API_KEY`、`COMMANDCODE_API_KEY`、`DEEPSEEK_API_KEY`、`MOONSHOT_API_KEY` 等（每家供应商的引用见 `lib/providers.mjs`）。
 - 或写入 `$DSH_HOME/.credentials.yaml` 的 `refs:` 映射（与 DSH 凭据服务同一份文档）。
+- **Open Design（OpenDesign）** 的额度查询需要 OpenDesign Cloud 的 **workspace ID + Control Key**（`OPENDESIGN_CONTROL_KEY` 或 `VELA_CONTROL_KEY`），**不是** Cloud API Keys 页的推理 Key（推理 Key 只能调用模型）。workspace ID 写在 provider 配置里，或用 `OPENDESIGN_WORKSPACE_ID` 环境变量；Control Key 也可以在供应商管理页的 Key 输入框填写。
 
 解析顺序（先命中先用）：DSH 凭据服务 → 环境变量 → `$DSH_HOME/.credentials.yaml` → OpenCode CLI 的 `auth.json`（仅默认的 `OPENCODE_GO_API_KEY` 引用）。
 
@@ -239,6 +240,10 @@ dsh plugin --profile <profile> remove dsh-tokenlens
       opencode-go: { enabled: true, apiKeyRef: OPENCODE_GO_API_KEY }
       commandcode: { enabled: true, apiKeyRef: COMMANDCODE_API_KEY }
       deepseek: { enabled: true, apiKeyRef: DEEPSEEK_API_KEY }
+      open-design:                      # 额度查询需要工作区 + Control Key
+        enabled: true
+        workspaceId: '<open-design-workspace-id>'   # 空 = 环境变量 OPENDESIGN_WORKSPACE_ID
+        controlKeyRef: OPENDESIGN_CONTROL_KEY        # 也可用 VELA_CONTROL_KEY
 ```
 
 覆盖规则：
@@ -269,13 +274,15 @@ dsh plugin --profile <profile> remove dsh-tokenlens
 | `minimax` | `GET https://api.minimax.io/v1/api/openplatform/coding_plan/remains`（订阅 Key；国内站 `api.minimaxi.com`） | 5 小时 / 每周 已用百分比（best-effort） |
 | `zhipu-cn` | `GET https://open.bigmodel.cn/api/monitor/usage/quota/limit`（`ZHIPU_API_KEY`） | GLM Coding Plan：5 小时 / 本周 / 每月 百分比 + 方案 |
 | `volcengine` | Coding Plan / AgentPlan：`POST https://open.volcengineapi.com/?Action=GetCodingPlanUsage&Version=2024-01-01`（Signature V4，`VOLCENGINE_ACCESS_KEY_ID` + `VOLCENGINE_SECRET_ACCESS_KEY`） | 5 小时 / 本周 / 每月 百分比 + 档位 |
+| `open-design` | 只读计费接口：`GET https://amr-api.open-design.ai/api/v1/workspaces/{workspaceId}/billing/coding-plan-usage` + `…/wallet/balance`（workspace ID + Control Key：`OPENDESIGN_CONTROL_KEY` / `VELA_CONTROL_KEY`，非推理 Key） | Design Plan 的 5 小时 / 7 天 已用百分比 + 重置时间；钱包余额（USD） |
 
 - OpenCode 的额度定义见[官方文档](https://opencode.ai/docs/go/#usage-limits)（5h = 月度额度的 20%、周 = 50%、月 = 100%）；接口只返回百分比，插件也只画百分比。
 - Command Code 的 `/alpha/*` 是官方 CLI 自用的私有计费路由；免费 / 无方案账户返回空窗口（显示 `—`），插件不会用方案目录猜额度。
+- Open Design 的窗口按账户实际返回的时长渲染：Go 同时有 5 小时和 7 天窗口，Plus / Pro / Max 只有 7 天窗口；钱包余额是独立于窗口的 USD 额度，用尽后继续扣钱包。查询要求工作区权限，鉴权失败会明确显示错误而不是 0。
 - 未配置凭据的供应商 chip 静默隐藏；`zai`、`minimax`、`deepinfra` 属 best-effort 适配（未公开接口，失败时按可重试错误优雅降级）。
 - 各供应商的元数据（`kind` / `label` / `shortLabel` / `baseURL` / `apiKeyRef` / `consoleUrl`）集中在 `lib/providers.mjs` 的 `PROVIDER_DEFAULTS` 与 `ADAPTERS` 中，新增适配器只需在该文件登记并补测试。
 
-另有 10 家**仅元数据**的内置供应商（管理页「内置」中可见）：`sensenova`（商汤 SenseNova）、`qwen`（通义千问）、`qianfan`（百度千帆）、`intern-ai`、`agnes-ai`、`open-design`、`hunyuan`（腾讯混元）、`spark`（讯飞星火）、`yi`（零一万物）、`baichuan`（百川智能）。它们暂缺公开的套餐 / 余额接口适配器，chip 静默隐藏；社区补齐适配器后即可自动生效。
+另有 9 家**仅元数据**的内置供应商（管理页「内置」中可见）：`sensenova`（商汤 SenseNova）、`qwen`（通义千问）、`qianfan`（百度千帆）、`intern-ai`、`agnes-ai`、`hunyuan`（腾讯混元）、`spark`（讯飞星火）、`yi`（零一万物）、`baichuan`（百川智能）。它们没有可用 API Key 查询的公开套餐 / 余额接口：千问 / 百炼的订阅额度只能通过官方 CLI 的控制台登录查询，腾讯混元 / 百度千帆只有云账户余额 API（需云账号 AK/SK），其余供应商仅控制台可见。chip 对它们静默隐藏，后续有稳定接口时再补适配器。
 
 ### 自动识别 DSH 模型设置
 
@@ -382,7 +389,7 @@ Host 半注册 `tokenlens_usage`，参数 `action`（默认 `snapshot`）与可
 
 ## 验证
 
-- `node --test`：**231 个自动化用例**，覆盖 Host 数据层、供应商适配器、统计折叠、各 harness 读取、插件集成与浏览器端渲染 / 交互。
+- `node --test`：**250 个自动化用例**，覆盖 Host 数据层、供应商适配器、统计折叠、各 harness 读取、插件集成与浏览器端渲染 / 交互。
 - 在真实环境中验证过 **5 个 harness** 的数据源；本机统计与独立的 SQLite 查询、独立的日志解析逐项对账（差额为 0），跨 harness 合并与供应商映射算术自洽。
 - 供应商接口按各官方文档与参考客户端行为验证；未配置凭据时 chip 静默隐藏，接口异常时按可重试错误降级。
 
@@ -393,7 +400,7 @@ Host 半注册 `tokenlens_usage`，参数 `action`（默认 `snapshot`）与可
 ```powershell
 git clone https://github.com/daigahou/dsh-tokenlens.git
 cd dsh-tokenlens
-node --test        # 231 个用例
+node --test        # 250 个用例
 ```
 
 本地联调安装方式见[方式 C](#方式-c本地开发从源码-link)。