@iasiv5/dsh-quota-watch 0.1.17 → 0.1.19

package/README.md

@@ -23,7 +23,7 @@
 - **🧩 侧边栏卡片（可选，默认隐藏）**：胶囊是默认界面；需要侧栏卡片时从面板底部按钮开启（Web profile 侧栏底部区块存在时才出现该按钮）。卡片提供摘要行 + 行点击开面板 + 行首 provider 名称点击立即探测。侧栏收起（Web 窄栏）或容器过窄（<160px，跨 profile 通用判据）时自动隐藏，侧栏整体不存在（Desktop 收起态）同样自然缺席、无报错——入口始终由悬浮胶囊承载。
 - **🌏 语言跟随宿主**：界面文案跟随 DSH「设置 → 语言」——宿主 locale 特性把解析结果实时镜像到 `<html lang>`，插件监听该属性，切换即热重渲染（无需刷新页面）；宿主未同步时回退浏览器语言。
 - **🛟 降级与容错**：凭据缺失的 provider 不渲染摘要行与胶囊分段（两者皆缺时悬浮胶囊与卡片一并隐藏）；探测失败时保留最后一次成功数据并在行上加 ⚠ 过期标记（⚠ 只出现在面板与卡片行内，不在胶囊上显示）。
-- **🔁 刷新节奏**：宿主默认每 60 秒探测（窗口 + 用量 + Copilot），profile 可配 30–3600 秒；浏览器页签可见时每 30 秒刷新视图，隐藏时暂停。所有 UI 收在 Shadow DOM 里（ADR 0001），颜色走 DSH 主题语义变量（含硬编码兜底），自动适配浅色 / 深色主题。
+- **🔁 刷新节奏**：宿主默认每 60 秒探测（窗口 + 用量 + Copilot），profile 可配 30–3600 秒；浏览器页签可见时每 30 秒刷新视图，隐藏时暂停。重启冷启动零等待：宿主 0 秒即发首轮探测（网络未就绪时以 5 秒冷重试直至拿到数据），客户端在无数据期间以 2 秒起步的指数退避快速重试、拿到数据后回到常规节奏——重启后数秒内胶囊即出现，不再有 ~30 秒空窗。所有 UI 收在 Shadow DOM 里（ADR 0001），颜色走 DSH 主题语义变量（含硬编码兜底），自动适配浅色 / 深色主题。
 
 ## 📸 界面巡礼
 
@@ -39,20 +39,16 @@ GLM 详情（双大数字 + 窗口网格 + 分模型用量）与 Copilot 详情
 
 ## 🚀 安装
 
-安装到 `web` profile：
+**方式一（推荐）· DSH 插件市场（dsh-m）**：打开 DSH 侧栏的「插件市场」，搜索 **Quota Watch**（或「额度」）一键安装——市场锁定精确版本、自动处理依赖，后续升级也在市场里完成。
 
-```sh
-dsh plugin --profile web add @iasiv5/dsh-quota-watch
-```
-
-更新与卸载：
+**方式二 · 命令行**（无市场环境或脚本化装机）：
 
 ```sh
-dsh plugin --profile web update @iasiv5/dsh-quota-watch   # 更新
-dsh plugin --profile web remove @iasiv5/dsh-quota-watch   # 卸载
+dsh plugin --profile web add @iasiv5/dsh-quota-watch      # web profile
+dsh plugin --profile desktop add @iasiv5/dsh-quota-watch  # desktop profile
 ```
 
-插件管理器会应用包内 `cordis.patch.yml`。宿主半区的插件变更需要重启 `dsh web` 后生效；客户端 bundle 随插件加载。装好后刷新页面，右下角即是额度胶囊。禁用插件请使用 DSH 插件管理器。
+**web 与 desktop 两种 profile 均已适配**：悬浮胶囊在两端都是常驻入口；侧边栏卡片是渐进增强——只要侧栏底部区块存在即可从面板按钮开启，侧栏收起或不存在（Desktop 收起态）时自动缺席。插件管理器会应用包内 `cordis.patch.yml`；宿主半区的变更需要重启 DSH 后生效（web 重启 `dsh web` 服务，desktop 重启应用），客户端 bundle 随插件加载，装好后刷新页面，右下角即是额度胶囊。npm 发布新版本后，市场 / 镜像同步可能略有延迟，立即装不到最新版时稍候重试即可。禁用插件请使用 DSH 插件管理器。
 
 ## ⚙️ 配置
 

package/lib/client.js

@@ -470,7 +470,9 @@ function mountQuotaCard({
   doc = globalThis.document,
   win = globalThis.window,
   fetchImpl = globalThis.fetch,
-  pollIntervalMs = CLIENT_POLL_INTERVAL_MS
+  pollIntervalMs = CLIENT_POLL_INTERVAL_MS,
+  retryNoDataMs = 2e3,
+  retryBackoff = 2
 } = {}) {
   if (!doc?.body || typeof fetchImpl !== "function") return () => {
   };
@@ -670,11 +672,12 @@ function mountQuotaCard({
   let snapshot;
   let requestSequence = 0;
   let timer;
+  let noDataRetries = 0;
   let disposed = false;
   let queuedPlace = false;
   let openKey;
   let panelNav = false;
-  let dataHidden = false;
+  let dataHidden = true;
   let surfaceFlags = loadSurfaceFlags(win.localStorage);
   const setCardHidden = (hidden) => {
     surfaceFlags = { cardHidden: hidden };
@@ -1059,6 +1062,13 @@ function mountQuotaCard({
       if (sequence === requestSequence && !disposed) render(next);
     } catch {
       if (sequence === requestSequence && !disposed) showTransportError();
+    } finally {
+      if (timer === void 0 && sequence === requestSequence && !disposed && doc.visibilityState !== "hidden") {
+        timer = win.setTimeout(() => {
+          timer = void 0;
+          if (!disposed && doc.visibilityState !== "hidden") void poll();
+        }, nextPollDelay());
+      }
     }
   };
   const place = () => {
@@ -1089,16 +1099,23 @@ function mountQuotaCard({
     if (!disposed) renderAll();
   }) : null;
   langObserver?.observe(doc.documentElement, { attributeFilter: ["lang"] });
+  syncFloatVisibility();
   place();
+  const nextPollDelay = () => {
+    if (!dataHidden) {
+      noDataRetries = 0;
+      return pollIntervalMs;
+    }
+    const delay = retryNoDataMs * retryBackoff ** noDataRetries;
+    noDataRetries += 1;
+    return Math.min(delay, pollIntervalMs);
+  };
   const startPolling = () => {
     if (timer !== void 0 || doc.visibilityState === "hidden" || disposed) return;
     void poll();
-    timer = win.setInterval(() => {
-      void poll();
-    }, pollIntervalMs);
   };
   const stopPolling = () => {
-    if (timer !== void 0) win.clearInterval(timer);
+    if (timer !== void 0) win.clearTimeout(timer);
     timer = void 0;
   };
   const onVisibilityChange = () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iasiv5/dsh-quota-watch",
-  "version": "0.1.17",
+  "version": "0.1.19",
   "description": "DSH Web sidebar monitor for GLM Coding Plan quotas and GitHub Copilot credits",
   "type": "module",
   "main": "./src/host.mjs",

package/src/client.mjs

@@ -373,6 +373,8 @@ export function mountQuotaCard({
   win = globalThis.window,
   fetchImpl = globalThis.fetch,
   pollIntervalMs = CLIENT_POLL_INTERVAL_MS,
+  retryNoDataMs = 2_000,
+  retryBackoff = 2,
 } = {}) {
   if (!doc?.body || typeof fetchImpl !== 'function') return () => {}
   if (doc.querySelector(CARD_SELECTOR) || doc.querySelector(FLOAT_SELECTOR)) return () => {}
@@ -610,11 +612,15 @@ export function mountQuotaCard({
   let snapshot
   let requestSequence = 0
   let timer
+  let noDataRetries = 0
   let disposed = false
   let queuedPlace = false
   let openKey
   let panelNav = false
-  let dataHidden = false
+  // Cold until the first successful render: a mount whose first poll fails or
+  // stalls must behave like the documented no-data state (hidden shell, fast
+  // retries), not like a warm client showing an empty capsule.
+  let dataHidden = true
   let surfaceFlags = loadSurfaceFlags(win.localStorage)
   const setCardHidden = (hidden) => {
     surfaceFlags = { cardHidden: hidden }
@@ -1052,6 +1058,18 @@ export function mountQuotaCard({
       if (sequence === requestSequence && !disposed) render(next)
     } catch {
       if (sequence === requestSequence && !disposed) showTransportError()
+    } finally {
+      // Self-scheduling chain (replaces the fixed interval): every completed
+      // poll — success OR transport error — arms the next one, so the no-data
+      // backoff also covers a cold start whose first request fails outright.
+      // timer === undefined guards against a concurrent force poll forking a
+      // second chain; the already-armed timer keeps the cadence.
+      if (timer === undefined && sequence === requestSequence && !disposed && doc.visibilityState !== 'hidden') {
+        timer = win.setTimeout(() => {
+          timer = undefined
+          if (!disposed && doc.visibilityState !== 'hidden') void poll()
+        }, nextPollDelay())
+      }
     }
   }
 
@@ -1091,15 +1109,33 @@ export function mountQuotaCard({
     ? new win.MutationObserver(() => { if (!disposed) renderAll() })
     : null
   langObserver?.observe(doc.documentElement, { attributeFilter: ['lang'] })
+  // Cold until data lands: keep the shell hidden so a slow or failed first
+  // probe never flashes an empty capsule (startPolling arms the retry chain).
+  syncFloatVisibility()
   place()
 
+  /** Cold-start cadence: while no provider has rendered any data, re-poll on
+   * a shortening backoff (retryNoDataMs × retryBackoffⁿ, capped at
+   * pollIntervalMs) so a desktop cold start surfaces the capsule in seconds
+   * instead of waiting out the fixed interval. A successful render resets the
+   * chain to the normal cadence; a transport error keeps the previous
+   * dataHidden state, so a cold client keeps retrying fast and a warm one
+   * stays calm. */
+  const nextPollDelay = () => {
+    if (!dataHidden) {
+      noDataRetries = 0
+      return pollIntervalMs
+    }
+    const delay = retryNoDataMs * (retryBackoff ** noDataRetries)
+    noDataRetries += 1
+    return Math.min(delay, pollIntervalMs)
+  }
   const startPolling = () => {
     if (timer !== undefined || doc.visibilityState === 'hidden' || disposed) return
     void poll()
-    timer = win.setInterval(() => { void poll() }, pollIntervalMs)
   }
   const stopPolling = () => {
-    if (timer !== undefined) win.clearInterval(timer)
+    if (timer !== undefined) win.clearTimeout(timer)
     timer = undefined
   }
   const onVisibilityChange = () => {

package/src/host.mjs

@@ -311,7 +311,18 @@ export function createQuotaService(ctx, options = {}) {
     timer = setTimeout(async () => {
       timer = undefined
       await refresh()
-      schedule(pollIntervalSec * 1000)
+      // Cold-start retry: until at least one provider has reached ready/stale,
+      // a failed or still-loading round re-arms shortly instead of waiting a
+      // full interval — a desktop cold start with a slow network would
+      // otherwise stare at no capsule for up to a minute. (updatedAt alone
+      // cannot signal "cold": refresh() stamps it even when every probe
+      // failed.) All-'missing' (no credentials configured) and warm states
+      // keep the normal cadence, so nobody without credentials gets
+      // high-frequency probing.
+      const states = [...providers.values()].map((provider) => provider.status)
+      const retryable = states.some((status) => status === 'loading' || status === 'error')
+        && states.every((status) => status !== 'ready' && status !== 'stale')
+      schedule(retryable ? (options.coldRetryMs ?? 5_000) : pollIntervalSec * 1000)
     }, delayMs)
     timer.unref?.()
   }
@@ -321,7 +332,9 @@ export function createQuotaService(ctx, options = {}) {
     refresh,
     start() {
       if (disposed || timer !== undefined) return
-      schedule(2_000)
+      // Routes register synchronously in apply() before start(), so probing
+      // immediately is safe; the legacy 2s delay only padded the cold start.
+      schedule(0)
     },
     stop() {
       disposed = true