dsh-tokenlens 1.5.0 → 1.5.1

package/CHANGELOG.md

@@ -4,6 +4,16 @@
 
 **版本记录约定**：同一发布日只保留一个章节，标题取当日**最后一个**已发布版本号；当日多次发布的改动合并到该章节，并在标题下注明当日实际发布过的版本号（npm 上仍可安装这些独立版本）。若当日已有发布，后续小改动不再单独增加版本号，而是并入下一篇日志。这样日志按天规整、不出现同日多个小版本。
 
+## 1.5.1 — 2026-11-02
+
+（当日已发布版本：v1.3.5 / v1.3.6 / v1.3.7 / v1.3.8 / v1.3.9 / v1.4.0 / v1.5.0 / v1.5.1）
+
+- **feat(open-design): chip 直接显示月用量%**——官方没有月窗口，但**月度额度是 4 × 7 天窗口**（定价表全档位一致：Go $120 vs $30、Plus $160 vs $40、Pro $360 vs $90、Max $600 vs $150）。Host 据此把周期估算填进 `windows.monthly`，chip 沿用现有「月 N%」槽位显示，无需第二套 UI
+- feat(open-design): `designPlan` 增加 `periodLimitCredits`（= 周上限 × 4）与 `percent`；`limitPerWindow` 用账号**实测**上限而非公开价目表（本机 Go 实为 5h $5 / 7d $15，只有官方标价的一半），避免百分比整体偏大
+- fix(open-design): **部分覆盖的估算不冒充完整值**——`complete: false` 时月窗口 `status` 置为 `unknown`，百分比仍显示但**永不触发黄色/红色告警**，避免把下限当满额报警
+- feat(open-design): 月窗口的重置时间取账期结束（`subscriptionCurrentPeriodEnd`），与 5 小时 / 7 天窗口的倒计时并列显示
+- 测试：307 → 314（月额度 = 4 × 周窗口、31 天账期 5 个窗口时封顶 100%、无周上限时不臆造百分比、部分覆盖状态为 unknown、Host 推导月度窗口与 designPlan 一致、chip 显示「月 8.8%」）
+
 ## 1.5.0 — 2026-11-02
 
 （当日已发布版本：v1.3.5 / v1.3.6 / v1.3.7 / v1.3.8 / v1.3.9 / v1.4.0 / v1.5.0）

package/PROTOCOL.md

@@ -155,10 +155,20 @@ by observing the weekly windows it sees:
   "windows": 1,                                 // weekly windows observed
   "complete": true,                             // earliest window starts at periodStart
   "since": "2026-11-02T09:53:18.000Z",          // first window actually observed
-  "limitPerWindow": 150000                      // the account's real weekly cap
+  "limitPerWindow": 150000,                     // the account's real weekly cap
+  "periodLimitCredits": 600000,                 // limitPerWindow * 4
+  "percent": 8.80                               // usedCredits / periodLimitCredits
 }
 ```
 
+`windows.monthly` is then filled from that estimate (v1.5.1), with `resetsAt` taken
+from `periodEnd`, so the existing monthly row and the chip's `月 N%` piece carry it
+without a second UI. The ×4 monthly-to-weekly ratio is the **one documented
+derivation**: the published pricing table states the monthly cap as exactly four
+weekly windows for every tier (Go $120/$30, Plus $160/$40, Pro $360/$90, Max
+$600/$150). A partial estimate still reports a percentage but sets the window
+`status` to `unknown`, so it can never paint a warning/critical dot.
+
 Rules the Host guarantees:
 
 - **Only the 7-day window is counted.** The 5-hour window measures the same spend

package/README.md

@@ -327,7 +327,7 @@ Control Key 是 **Open Design 桌面端/CLI 登录时写入本机的会话凭据
 - 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；工作区 ID 与 Control Key 缺任一项时，弹窗会指出缺哪一项并给出「去配置」入口（v1.3.5）。窗口、余额、套餐档位是**三层独立读取**（v1.4.0）：任一接口不可用时只少那一块数据，不会整套报错。
-- **「本期 Design Plan 累计」是插件本机算的估算值**（v1.5.0）。Open Design 有月度额度（Go 为每月 $120 = 4 × 每周 $30），但**没有「本账期已用」接口**——控制台的 `/billing/usage`、`/billing/coding-plan-usage` 都靠浏览器 Cookie 鉴权，Control Key 一律 401。于是插件累加它观测到的 **7 天窗口**（只记 7 天，因为 5 小时窗口测量的是同一笔消耗，相加会重复计数），按 `creditsPerUsd` 折算成美元；弹窗会标注覆盖情况（「已覆盖本账期全部窗口」或「仅统计已观测的 N 个窗口」），插件没运行期间错过的窗口无法计入。
+- **chip 的「月 N%」与「本期 Design Plan 累计」是插件本机算的估算值**（v1.5.0 / v1.5.1）。Open Design 有月度额度（Go 为每月 $120 = 4 × 每周 $30），但**没有「本账期已用」接口**——控制台的 `/billing/usage`、`/billing/coding-plan-usage` 都靠浏览器 Cookie 鉴权，Control Key 一律 401。于是插件累加它观测到的 **7 天窗口**（只记 7 天，因为 5 小时窗口测量的是同一笔消耗，相加会重复计数），再按官方「月度 = 4 × 周额度」的比例折算成百分比填进 chip 的「月」槽位，并按 `creditsPerUsd` 折算美元。弹窗会标注覆盖情况（「已覆盖本账期全部窗口」或「仅统计已观测的 N 个窗口」）；覆盖不完整时百分比仍显示但**不会触发告警配色**，插件没运行期间错过的窗口无法计入。
 - 未配置凭据的供应商 chip 静默隐藏；`zai`、`minimax`、`deepinfra` 属 best-effort 适配（未公开接口，失败时按可重试错误优雅降级）。
 - 各供应商的元数据（`kind` / `label` / `shortLabel` / `baseURL` / `apiKeyRef` / `consoleUrl`）集中在 `lib/providers.mjs` 的 `PROVIDER_DEFAULTS` 与 `ADAPTERS` 中，新增适配器只需在该文件登记并补测试。
 
@@ -439,7 +439,7 @@ Host 半注册 `tokenlens_usage`，参数 `action`（默认 `snapshot`）与可
 
 ## 验证
 
-- `node --test`：**307 个自动化用例**，覆盖 Host 数据层、供应商适配器、统计折叠、各 harness 读取、Design Plan 周期账本、插件集成与浏览器端渲染 / 交互。
+- `node --test`：**314 个自动化用例**，覆盖 Host 数据层、供应商适配器、统计折叠、各 harness 读取、Design Plan 周期账本、插件集成与浏览器端渲染 / 交互。
 - 在真实环境中验证过 **5 个 harness** 的数据源；本机统计与独立的 SQLite 查询、独立的日志解析逐项对账（差额为 0），跨 harness 合并与供应商映射算术自洽。
 - 供应商接口按各官方文档与参考客户端行为验证；未配置凭据时 chip 静默隐藏，接口异常时按可重试错误降级。
 

package/index.js

@@ -83,7 +83,7 @@ export const inject = []
 export const PLUGIN_NAME = 'dsh-tokenlens'
 
 /** Plugin version; mirrors package.json (kept here so diagnostics need no fs read). */
-export const PLUGIN_VERSION = '1.5.0'
+export const PLUGIN_VERSION = '1.5.1'
 
 /** Documented defaults; every field of the raw row config is optional. */
 const DEFAULTS = {
@@ -439,6 +439,40 @@ export function apply(ctx, rawConfig) {
     return summarizeDesignPlan(designPlanLedger, periodStart)
   }
 
+  /**
+   * Fill the `monthly` window from the period estimate (v1.5.1).
+   *
+   * Open Design reports only rolling 5h/7d windows, so `windows.monthly` is
+   * always null upstream — yet the dialog already knows how to render a monthly
+   * row (label, bar, reset countdown) and the chip already knows how to show a
+   * monthly percentage. Rather than inventing a parallel UI, place the estimate
+   * in the slot it belongs to. The `designPlan` field stays on the wire as the
+   * machine-readable source, including its `complete` coverage flag; the client
+   * uses it to qualify the number as an estimate.
+   *
+   * The percentage is `usedCredits / (weeklyLimit * 4)`; the ×4 is the published
+   * monthly-to-weekly ratio (see design-plan-ledger.mjs) and the only derived
+   * step. Without a usable weekly limit there is no honest denominator, so the
+   * monthly slot stays empty instead of showing a made-up percentage.
+   */
+  function withMonthlyWindow(windows, designPlan) {
+    if (designPlan === null || designPlan.percent === null) return windows
+    const base = windows !== null && typeof windows === 'object' ? windows : { rolling: null, weekly: null }
+    return {
+      ...base,
+      monthly: {
+        id: 'monthly',
+        percent: designPlan.percent,
+        // A partial estimate must not raise an alarm: only a complete period is
+        // allowed to reach the warning/critical thresholds downstream.
+        status: designPlan.complete === true ? 'ok' : 'unknown',
+        resetsAt: designPlan.periodEnd === '' ? null : designPlan.periodEnd,
+        remainingMs:
+          designPlan.periodEnd === '' ? null : Math.max(0, Date.parse(designPlan.periodEnd) - Date.now()),
+      },
+    }
+  }
+
   /** Built-in defaults + profile config + management-page overrides. */
   function effectiveProviderConfig(providerId) {
     const id = canonicalProviderId(providerId)
@@ -1174,7 +1208,7 @@ export function apply(ctx, rawConfig) {
     return buildSnapshot({
       provider: providerInfo(providerId),
       plan: read.result.plan ?? null,
-      windows: read.result.windows ?? null,
+      windows: withMonthlyWindow(read.result.windows ?? null, designPlan),
       balance: read.result.balance ?? null,
       credits: read.result.credits ?? null,
       account: read.result.account ?? null,

package/lib/design-plan-ledger.mjs

@@ -221,14 +221,28 @@ export function observeDesignPlan(ledger, input) {
   }
 }
 
+/**
+ * How many weekly windows make up one monthly allowance.
+ *
+ * The published pricing table states it for every tier — Go $120/mo vs $30
+ * weekly, Plus $160 vs $40, Pro $360 vs $90, Max $600 vs $150 — so the monthly
+ * cap is always exactly four weekly windows. This is the ONLY step in the
+ * estimate that is a documented ratio rather than an observed number.
+ */
+export const WEEKS_PER_PERIOD = 4
+
 /**
  * Summarize one period: the estimated Design Plan usage the Host has observed.
  *
  * @returns `null` when the period has no observations at all, else
- *   `{ usedCredits, estimatedUsd, windows, complete, since, periodStart, periodEnd, limitPerWindow }`.
- *   `complete` is true only when the earliest observed window starts at the
- *   period start — otherwise earlier windows of this period were never seen and
- *   the number is a lower bound.
+ *   `{ usedCredits, estimatedUsd, windows, complete, since, periodStart,
+ *      periodEnd, limitPerWindow, periodLimitCredits, percent }`.
+ *   `percent` is `usedCredits / periodLimitCredits`, where the period limit is
+ *   `limitPerWindow * WEEKS_PER_PERIOD` (the published monthly cap); it is null
+ *   when the upstream reported no usable weekly limit. `complete` is true only
+ *   when the earliest observed window starts at the period start — otherwise
+ *   earlier windows of this period were never seen and both numbers are lower
+ *   bounds.
  */
 export function summarizeDesignPlan(ledger, periodStart) {
   const key = isoOf(periodStart)
@@ -248,6 +262,9 @@ export function summarizeDesignPlan(ledger, periodStart) {
     Number.isSafeInteger(creditsPerUsd) && creditsPerUsd > 0 ? usedCredits / creditsPerUsd : null
   const since = entries[0][0]
   const limitPerWindow = entries[entries.length - 1][1].limitCredits
+  const usableWindowLimit = Number.isSafeInteger(limitPerWindow) && limitPerWindow > 0 ? limitPerWindow : null
+  const periodLimitCredits = usableWindowLimit === null ? null : usableWindowLimit * WEEKS_PER_PERIOD
+  const percent = periodLimitCredits === null ? null : (usedCredits / periodLimitCredits) * 100
   return {
     periodStart: key,
     periodEnd: period.periodEnd || '',
@@ -256,7 +273,9 @@ export function summarizeDesignPlan(ledger, periodStart) {
     windows,
     complete: since === key,
     since,
-    limitPerWindow: Number.isSafeInteger(limitPerWindow) && limitPerWindow > 0 ? limitPerWindow : null,
+    limitPerWindow: usableWindowLimit,
+    periodLimitCredits,
+    percent: percent === null ? null : Math.min(100, Math.max(0, percent)),
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-tokenlens",
-  "version": "1.5.0",
+  "version": "1.5.1",
   "type": "module",
   "description": "dsh-TokenLens (词元透镜) — provider-aware plan capacity plus local token statistics (today/7d/30d/all-time, by harness/provider/model/workspace) for DSH.",
   "license": "MIT",