@mzzsfy/dsh-usage-panel 0.8.1 → 0.8.3

package/README.md

@@ -83,11 +83,11 @@ usage-panel:
 
 - webhook:host 直发(Slack-compatible `{text}` + 结构化字段),超时 10 秒不重试,fire-and-forget;面板「保存并测试」返回真实投递结果
 - dsh-im:安装 [@xmanrui/dsh-im](https://www.npmjs.com/package/@xmanrui/dsh-im) 后自动启用,面板粘贴 Bot ID 加载其已保存投递目标目录,勾选即自动保存;支持绑定多个 bot,已绑 bot 以标签展示,点标签加载该 bot 目录,× 一键取消注册(移除该 bot 全部目标);触发逻辑与 webhook 完全一致(fire-and-forget 不重试);目标的新建与平台测试仍在 dsh-im 设置页完成,此处仅选择;「测试 IM」逐目标返回真实结果
-- 页内 toast:host 内存投影(环形 20 条 / 60 秒过期,version 单调递增),浏览器半区长轮询挂起等待增量并经公共依赖 `@mzzsfy/dsh-toast` 展示(语义与 turn-notify 同构);localStorage 单元级认领锁保证多窗口只弹一次。**toast 依赖由 session-manager 插件代挂**,未安装 session-manager 时此通道静默不可用,其余通道不受影响
+- 页内 toast:host 内存投影(环形 20 条 / 60 秒过期,version 单调递增),浏览器订阅公共依赖 `@mzzsfy/dsh-common-tools` 的 WS 总线 `@mzzsfy/dsh-usage-panel` 插件通道,首连、重连与变更时拉取快照,经其 toast 展示(语义与 turn-notify 同构);同源窗口通过 IndexedDB 事务认领同一事件,提交后仅认领成功的窗口呈现;认领记录自认领起按浏览器本地时间保留 90 秒（60 秒投影窗口 + 30 秒请求消费窗口）,不按单窗旧快照删除。快照请求及后续认领共用超时信号,不比较宿主与浏览器时钟。IndexedDB 不可用时控制台通告降级,仅保证本窗口去重。公共依赖由 session-manager 插件代挂装载,为总线订阅的硬依赖。host/client 在 `apply(ctx)` 调用 `setupCommonTools(ctx)`,通道身份来自 `ctx.fiber.entry.options.name` 的完整 npm 包名;client 各实例退出时释放自己的订阅，同一 factory 的存活实例接管一次共享通知工作，最后实例退出才中止共享快照；跨 factory HMR 清理旧代
 
 ### 通知接口
 
-- `GET /api/usage-panel/notifications`:通知投影长轮询;`cursor` 缺省=首拉立即返回全量,`cursor` 等于当前版本时挂起至事件或超时,落后或超前(宿主重启版本回退)立即返回全量,客户端以响应 version 重置游标自愈;响应 `{units, version}`
+- `GET /api/usage-panel/notifications`:通知投影即时全量快照,响应 `{units, version}`;变更通知由公共 WS 总线插件空间推送
 - `GET|POST /api/usage-panel/notify-config`:全局通知规则;`webhookUrl` 原文随响应回显
 - `POST /api/usage-panel/test-webhook` / `POST /api/usage-panel/test-im`:测试投递,返回真实结果
 - `GET /api/usage-panel/im-targets?botId=`:列出 dsh-im 该 bot 已保存投递目标
@@ -110,7 +110,7 @@ custom 端点支持自定义请求方法(GET/POST/PUT/DELETE/PATCH)、请求头(
 ## 架构与依赖
 
 - Host 半区(`src/index.js`):Node ESM,`fetch` 直连平台 API(超时 20s),通过 `webServer` 服务暴露 `/api/usage-panel/*` 路由(accounts / query / history / settings / notifications / notify-config / test-webhook / test-im / im-targets);需要 DSH 提供 `webServer` 服务与 `settings` 服务(通知规则持久化);`timer` 服务(定期轮询)为软依赖,缺失时仅停用自动轮询
-- Client 半区(`src/client.js`):DSH client-modules 自注册格式(`__ModuleLoader__.load`),注册 `settings.section` 槽位;需要 `slots` 服务与 `react` 18;`@mzzsfy/dsh-toast` 可选消费(动态 require,模块表缺失即页内通道停用,操作反馈降级 `console.warn`)
+- Client 半区(`src/client.js`):DSH client-modules 自注册格式(`__ModuleLoader__.load`),注册 `settings.section` 槽位;需要 `slots` 服务与 `react` 18;公共依赖 `@mzzsfy/dsh-common-tools` 的 WS 总线为硬消费,toast 不可用时操作反馈降级 `console.warn`
 - 纯逻辑层(`src/parsers.mjs` / `src/poller.mjs` / `src/history.mjs` / `src/historyStore.mjs` / `src/notify.mjs`):无 IO 数据变换,`npm test` 覆盖解析、时间驱动调度与退避、快照留存、持久化守卫与规则合并 / 沿触发评估 / 投影认领 / 配置校验;趋势图 SVG 点位算法内联于 client.js(唯一实现)
 
 ## 安全提示
@@ -133,4 +133,4 @@ node scripts/dev-link.mjs dsh-usage-panel   # 仓库根执行:归一 profile 依
 
 ## dsh 版本兼容
 
-三版本(0.1.2-rc.1 / 0.1.5-rc.3 / 0.1.7-rc.1)全部通过:用量面板渲染(账号卡/通知规则折叠卡全控件)、API 面(pollArmed/通知投影)、激活 live。
+按仓库动态窗口验证(scripts/compat/window.mjs),不预置任何固定版本槽:主测 = 渠道 dist-tag 最新 rc,完全适配口径;基线 = npm latest,不崩溃底线口径;主测与基线同版时收敛单槽。兼容面以窗口实测为准,不逐版本承诺。逐轮实测结论见 `docs/兼容性测试/逐包测试进度.md` 与本包 `兼容性测试.md`。

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mzzsfy/dsh-usage-panel",
   "description": "多平台 LLM 账号余额与额度面板:支持 DeepSeek/OpenRouter/Kimi/智谱/MiniMax/NewApi 及自定义端点,自动定期查询,趋势图与历史快照,用量/余额阈值与窗口重置多通道通知",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "type": "module",
   "main": "src/index.js",
   "exports": {
@@ -16,12 +16,19 @@
     "client": {
       "platform": "web",
       "external": [
-        "@mzzsfy/dsh-toast/client"
+        "@mzzsfy/dsh-common-tools/client"
       ]
+    },
+    "compatibility": {
+      "dshReleases": {
+        "0.2.0-rc.1": "unknown",
+        "0.2.0-rc.2": "compatible",
+        "0.2.1-alpha.1": "unknown"
+      }
     }
   },
   "scripts": {
-    "test": "node --test \"test/*.test.mjs\"",
+    "test": "node --experimental-test-module-mocks --import ./test/_mocks.common-tools.mjs --test \"test/*.test.mjs\"",
     "npmPublish": "npm publish --access public --provenance=false --registry=https://registry.npmjs.org"
   },
   "license": "MIT",
@@ -33,7 +40,7 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@mzzsfy/dsh-toast": "^0.1.2"
+    "@mzzsfy/dsh-common-tools": "^0.2.0"
   },
   "peerDependencies": {
     "@deepseek-ai/dsh-settings": ">=0.1.2-alpha.2",

package/src/client.js

@@ -9,11 +9,14 @@ window.__ModuleLoader__.load({
     const React = require('react')
     const { useState, useEffect, useRef } = React
 
-    // 面板反馈出口:公共依赖 @mzzsfy/dsh-toast,可选消费——占位条目由
-    // session-manager 唯一代挂,权威方未安装时降级 console,不挂死不报错
+    // 公共依赖 @mzzsfy/dsh-common-tools:总线订阅硬消费(页内通知数据刷新唯一
+    // 通道;模块表缺失即本 client factory 抛错,由装载层判定失败,无轮询回退);
+    // toast 可选消费——占位条目由 session-manager 唯一代挂,权威方未安装时降级
+    // console,不挂死不报错
+    const tools = require('@mzzsfy/dsh-common-tools/client')
     let toast = null
     try {
-      toast = require('@mzzsfy/dsh-toast/client').show
+      toast = tools.toast.show
     } catch {
       // 模块表无 toast → 反馈降级 console.warn
     }
@@ -88,46 +91,100 @@ window.__ModuleLoader__.load({
     }
     /* LOGIC-END */
 
-    // 页内通知长轮询:client 激活即挂起等待,不依赖面板打开;toast 库缺失(权威代挂方
+    // 页内通知推送订阅:client 激活即订阅,不依赖面板打开;toast 库缺失(权威代挂方
     // session-manager 未安装)整段跳过;批内逐条认领防多窗口重复弹;
-    // 代际令牌自愈:HMR/闭包重建首挂 abort 旧代长轮询再启新代,旧代不滞留不叠加
+    // 代际令牌自愈:HMR/闭包重建首挂中止旧代快照请求与总线订阅再启新代,旧代不滞留不叠加
     const NOTIFY_REQUEST_TIMEOUT_MS = 30 * 1000
-    // 失败重连退避:指数增长至上限,防网络中断期间打爆服务端;须大于服务端挂起上限
-    const NOTIFY_RETRY_MIN_MS = 2 * 1000
-    const NOTIFY_RETRY_MAX_MS = 30 * 1000
     const NOTIFY_TOAST_MS = 6 * 1000
     const KEY_POLL_TOKEN = 'usage-panel:notify-poll'
-    if (toast) {
-      // 已有 AbortController 代即 abort 旧代长轮询;遗留非 AbortController 旧令牌
-      // (interval 形态)无法中止,由页面刷新自然清偿
-      if (window[KEY_POLL_TOKEN] instanceof AbortController) window[KEY_POLL_TOKEN].abort()
+    const KEY_POLL_DISPOSE = 'usage-panel:notify-poll:dispose'
+    const notificationOwners = new Set()
+    let activeNotificationOwner = null
+    let notificationWork = null
+    const NOTIFY_TTL_MS = 60 * 1000
+    const CLAIM_DB = 'dsh-usage-panel'
+    const CLAIM_STORE = 'claims'
+    const CLAIM_RETENTION_MS = NOTIFY_TTL_MS + NOTIFY_REQUEST_TIMEOUT_MS
+    const announcedIds = new Map()
+    let claimDegradeAnnounced = false
+    let claimDbPromise = null
+    function closeClaimDb() {
+      const pending = claimDbPromise
+      claimDbPromise = null
+      pending?.then(db => db.close(), () => {})
+    }
+    function openClaimDb() {
+      if (claimDbPromise) return claimDbPromise
+      const pending = new Promise((resolve, reject) => {
+        const request = window.indexedDB.open(CLAIM_DB, 1)
+        request.onupgradeneeded = () => { request.result.createObjectStore(CLAIM_STORE, { keyPath: 'id' }) }
+        request.onerror = () => reject(request.error)
+        request.onblocked = () => reject(new Error('通知认领库被阻塞'))
+        request.onsuccess = () => {
+          const db = request.result
+          if (claimDbPromise !== pending) { db.close(); reject(new Error('通知认领代已退出')); return }
+          db.onversionchange = () => { if (claimDbPromise === pending) closeClaimDb() }
+          resolve(db)
+        }
+      })
+      claimDbPromise = pending
+      pending.catch(() => { if (claimDbPromise === pending) claimDbPromise = null })
+      return pending
+    }
+    // 同库 readwrite 事务串行，提交终态后才呈现；HTTP LAN 同样可用。
+    async function claimNotification(unit, signal) {
+      if (signal?.aborted) return false
+      const now = Date.now()
+      try {
+        const db = await openClaimDb()
+        if (signal?.aborted) return false
+        const claimed = await new Promise((resolve, reject) => {
+          const transaction = db.transaction(CLAIM_STORE, 'readwrite')
+          const store = transaction.objectStore(CLAIM_STORE)
+          let winner = false
+          const abort = () => { try { transaction.abort() } catch { /* 已提交事务不能回滚 */ } }
+          const cleanup = () => signal?.removeEventListener('abort', abort)
+          signal?.addEventListener('abort', abort, { once: true })
+          transaction.oncomplete = () => { cleanup(); resolve(winner) }
+          transaction.onabort = transaction.onerror = () => { cleanup(); reject(transaction.error) }
+          const request = store.getAll()
+          request.onsuccess = () => {
+            const now = Date.now()
+            const rows = request.result
+            for (const row of rows) if (row.expiresAt <= now) store.delete(row.id)
+            if (signal?.aborted) return
+            if (rows.some(row => row.id === unit.id && row.expiresAt > now)) return
+            store.add({ id: unit.id, expiresAt: now + CLAIM_RETENTION_MS })
+            winner = localGet(KEY_DONE + unit.id) === null
+          }
+        })
+        return !signal?.aborted && claimed
+      } catch {
+        if (signal?.aborted) return false
+        if (!claimDegradeAnnounced) {
+          claimDegradeAnnounced = true
+          console.warn('[dsh-usage-panel] IndexedDB 不可用，跨窗口通知认领已降级')
+        }
+        for (const [id, at] of announcedIds) if (now - at >= NOTIFY_TTL_MS) announcedIds.delete(id)
+        if (announcedIds.has(unit.id) || !claimEvent(unit.id)) return false
+        announcedIds.set(unit.id, now)
+        return true
+      }
+    }
+    function createNotificationWork() {
+      const previousDispose = window[KEY_POLL_DISPOSE]
+      if (typeof previousDispose === 'function') previousDispose()
       const notifyController = new AbortController()
       window[KEY_POLL_TOKEN] = notifyController
-      // 已见投影版本:空即未首拉;长轮询续传游标,响应后随 payload 推进
+      // 已见投影版本:仅作观测;丢失恢复靠订阅 onReset 全量对账,不设游标重放
       let notifyCursor = null
-      const notifySleep = (ms, signal) => new Promise((resolve) => {
-        if (signal.aborted) {
-          resolve()
-          return
-        }
-        const timer = setTimeout(() => {
-          signal.removeEventListener('abort', onAbort)
-          resolve()
-        }, ms)
-        const onAbort = () => {
-          clearTimeout(timer)
-          resolve()
-        }
-        signal.addEventListener('abort', onAbort, { once: true })
-      })
       async function notifyPollOnce(signal) {
-        let payload
+        let payload, requestSignal
         try {
-          // cursor 为空即首拉,服务端立即返回全量;之后携带版本挂起等待增量
-          const query = notifyCursor === null ? '' : '?cursor=' + notifyCursor
+          // 恒全量快照(变更通知走总线);组合代际中止与请求超时防悬挂
           const timeoutSignal = AbortSignal.timeout(NOTIFY_REQUEST_TIMEOUT_MS)
-          const requestSignal = signal === undefined ? timeoutSignal : AbortSignal.any([signal, timeoutSignal])
-          const response = await fetch('/api/usage-panel/notifications' + query, { signal: requestSignal })
+          requestSignal = signal === undefined ? timeoutSignal : AbortSignal.any([signal, timeoutSignal])
+          const response = await fetch('/api/usage-panel/notifications', { signal: requestSignal })
           if (!response.ok) {
             void response.body?.cancel()
             return false
@@ -136,7 +193,8 @@ window.__ModuleLoader__.load({
         } catch {
           return false
         }
-        // 版本缺失即异常响应:按失败退避,防游标停滞退化成紧密首拉循环
+        if (requestSignal.aborted) return false
+        // 版本缺失即异常响应:按失败处理,由调用方决定是否通告
         if (typeof payload.version !== 'number') return false
         notifyCursor = payload.version
         const units = payload && Array.isArray(payload.units) ? payload.units : []
@@ -154,31 +212,47 @@ window.__ModuleLoader__.load({
           } catch { storageBroken = true }
         }
         for (const unit of units) {
-          if (!claimEvent(unit.id)) continue
+          const claimed = await claimNotification(unit, requestSignal)
+          if (requestSignal.aborted) return false
+          if (!claimed) continue
           markDone(unit.id)
           toast(unit.text, { kind: unit.kind === 'reset' ? 'ok' : 'error', holdMs: NOTIFY_TOAST_MS })
         }
         return true
       }
-      // 长轮询主循环:成功即立即重连(空闲期由服务端挂起兜底),失败指数退避;
-      // 循环体严格顺序,任何时刻至多一条在途请求
-      void (async () => {
-        let backoffMs = NOTIFY_RETRY_MIN_MS
-        while (!notifyController.signal.aborted) {
-          let ok = false
-          try {
-            ok = await notifyPollOnce(notifyController.signal)
-          } catch { ok = false }
-          if (notifyController.signal.aborted) break
-          if (ok) {
-            backoffMs = NOTIFY_RETRY_MIN_MS
-            await notifySleep(0, notifyController.signal)
-          } else {
-            await notifySleep(backoffMs, notifyController.signal)
-            backoffMs = Math.min(backoffMs * 2, NOTIFY_RETRY_MAX_MS)
-          }
-        }
-      })()
+      // 订阅插件空间 WS 总线:首连 onReset 即首拉,消息到达重拉;
+      // 公共总线重连成功再触发 onReset 全量对账自愈;快照失败不自动重试
+      const snapshot = tools.createSnapshotRefresh(() => notifyPollOnce(notifyController.signal))
+      const refresh = snapshot.refresh
+      const dispose = () => {
+        if (notificationWork?.dispose !== dispose) return
+        notificationWork = null
+        snapshot.dispose()
+        notifyController.abort()
+        closeClaimDb()
+        for (const item of notificationOwners) item.unsubscribe?.()
+        notificationOwners.clear()
+        activeNotificationOwner = null
+        if (window[KEY_POLL_TOKEN] === notifyController) delete window[KEY_POLL_TOKEN]
+        if (window[KEY_POLL_DISPOSE] === dispose) delete window[KEY_POLL_DISPOSE]
+      }
+      notificationWork = { refresh, dispose }
+      window[KEY_POLL_DISPOSE] = dispose
+    }
+    function startNotifications(bus) {
+      if (!toast) return
+      const owner = { unsubscribe: null }
+      if (notificationOwners.size === 0) createNotificationWork()
+      notificationOwners.add(owner)
+      if (activeNotificationOwner === null) activeNotificationOwner = owner
+      const refresh = () => { if (activeNotificationOwner === owner) void notificationWork.refresh() }
+      owner.unsubscribe = bus.subscribe(refresh, { onReset: refresh })
+      return () => {
+        if (!notificationOwners.delete(owner)) return
+        owner.unsubscribe()
+        if (activeNotificationOwner === owner) activeNotificationOwner = notificationOwners.values().next().value || null
+        if (notificationOwners.size === 0) notificationWork.dispose()
+      }
     }
 
     // 导航图标声明:交给 dsh-settings-nav-icons 统一渲染;双键 = 分区 label + 市场
@@ -189,13 +263,14 @@ window.__ModuleLoader__.load({
     else window.__navicIconQueue = [NAV_ICON]
 
 const CSS = [
-  // 设计令牌:状态色语义固定,面层色走宿主变量保暗亮自适应
-  '.up-panel { --up-warn:#d97706; --up-surface:var(--dsw-alias-surface-primary, #1b1d21);',
-  '  --up-border:var(--dsw-alias-separator-primary, rgba(128,128,128,0.28));',
-  '  --up-muted:var(--dsw-alias-label-secondary, rgba(160,166,178,0.9));',
-  '  --up-ok:var(--dsw-alias-state-success-primary, #1a9e55);',
-  '  --up-err:var(--dsw-alias-state-error-primary, #d43a3a);',
-  '  --up-focus:var(--dsw-alias-state-focus-primary, #4c8dff);',
+  // 设计令牌:直接引用宿主语义别名,禁止字面 fallback(暗色主题漏色);
+  // surface/separator 是宿主无定义的自造别名,迁移到 bg-layer-1/border-l2
+  '.up-panel { --up-warn:var(--dsw-alias-state-warn-primary); --up-surface:var(--dsw-alias-bg-layer-1);',
+  '  --up-border:var(--dsw-alias-border-l2);',
+  '  --up-muted:var(--dsw-alias-label-secondary);',
+  '  --up-ok:var(--dsw-alias-state-success-primary);',
+  '  --up-err:var(--dsw-alias-state-error-primary);',
+  '  --up-focus:var(--dsw-alias-brand-primary);',
   '  display:flex; flex-direction:column; gap:14px; color:inherit; font-size:13px; }',
   // ---- 顶栏 ----
   '.up-head { display:flex; align-items:center; gap:8px; flex-wrap:wrap; }',
@@ -206,11 +281,11 @@ const CSS = [
   '.up-btn { cursor:pointer; border:1px solid var(--up-border); background:transparent;',
   '  color:inherit; border-radius:8px; padding:5px 12px; font-size:12px; font-family:inherit;',
   '  transition:background 0.15s ease, border-color 0.15s ease, opacity 0.15s ease, transform 0.15s ease; }',
-  '.up-btn:hover { border-color:var(--up-focus); background:rgba(128,148,180,0.12); }',
+  '.up-btn:hover { border-color:var(--up-focus); background:color-mix(in srgb, var(--up-focus) 12%, transparent); }',
   '.up-btn:active { transform:translateY(1px); }',
   '.up-btn:disabled { opacity:0.45; cursor:default; transform:none; }',
   '.up-btn:focus-visible { outline:2px solid var(--up-focus); outline-offset:2px; }',
-  '.up-btn--primary { background:var(--up-focus); border-color:var(--up-focus); color:#fff; font-weight:600; }',
+  '.up-btn--primary { background:var(--up-focus); border-color:var(--up-focus); color:var(--dsw-alias-bg-base); font-weight:600; }',
   '.up-btn--primary:hover { background:var(--up-focus); opacity:0.88; }',
   '.up-btn--danger { color:var(--up-err); border-color:color-mix(in srgb, var(--up-err) 45%, transparent); }',
   '.up-btn--danger:hover { border-color:var(--up-err); background:color-mix(in srgb, var(--up-err) 12%, transparent); }',
@@ -219,19 +294,23 @@ const CSS = [
   '  display:flex; flex-direction:column; gap:10px;',
   '  transition:border-color 0.15s ease, background 0.15s ease; }',
   '.up-card:hover { border-color:color-mix(in srgb, var(--up-focus) 40%, var(--up-border));',
-  '  background:rgba(128,148,180,0.06); }',
+  '  background:color-mix(in srgb, var(--up-focus) 6%, transparent); }',
   '.up-card__row { display:flex; align-items:center; gap:8px; flex-wrap:wrap; }',
   '.up-card__name { font-weight:600; font-size:15px; }',
-  // 平台徽章:按平台固定色相着色的胶囊 pill;custom 走缺省灰底(低调平台共用)
+  // 平台徽章:按平台固定色相着色的胶囊 pill(品牌区分色,规范允许的 chart 类 token,
+  // 集中声明);custom 走缺省灰底(低调平台共用)
+  '.up-panel { --up-badge-default:color-mix(in srgb, var(--dsw-alias-label-tertiary) 55%, transparent);',
+  '  --up-badge-deepseek:var(--dsw-alias-brand-primary); --up-badge-kimi:var(--dsw-alias-state-success-primary);',
+  '  --up-badge-minimax:var(--dsw-alias-state-warn-primary); --up-badge-newapi:#8b5cf6; --up-badge-zhipu:#3859ff; }',
   '.up-badge { font-size:10px; font-weight:500; padding:1px 7px; border-radius:999px;',
-  '  line-height:1.5; border:1px solid transparent; color:#fff;',
-  '  background:var(--up-badge-color, rgba(128,128,128,0.55)); }',
-  '.up-badge[data-type="deepseek"] { --up-badge-color:#4d6bfe; }',
-  '.up-badge[data-type="openrouter"] { --up-badge-color:#57565b; }',
-  '.up-badge[data-type="kimi"] { --up-badge-color:#0d9488; }',
-  '.up-badge[data-type="minimax"] { --up-badge-color:#ea580c; }',
-  '.up-badge[data-type="newapi"] { --up-badge-color:#8b5cf6; }',
-  '.up-badge[data-type="zhipu"] { --up-badge-color:#3859ff; }',
+  '  line-height:1.5; border:1px solid transparent; color:var(--dsw-alias-bg-base);',
+  '  background:var(--up-badge-color, var(--up-badge-default)); }',
+  '.up-badge[data-type="deepseek"] { --up-badge-color:var(--up-badge-deepseek); }',
+  '.up-badge[data-type="openrouter"] { --up-badge-color:var(--dsw-alias-label-tertiary); }',
+  '.up-badge[data-type="kimi"] { --up-badge-color:var(--up-badge-kimi); }',
+  '.up-badge[data-type="minimax"] { --up-badge-color:var(--up-badge-minimax); }',
+  '.up-badge[data-type="newapi"] { --up-badge-color:var(--up-badge-newapi); }',
+  '.up-badge[data-type="zhipu"] { --up-badge-color:var(--up-badge-zhipu); }',
   // ---- 读数行:标签 + 渐变进度条 + 等宽数字 ----
   '.up-reading { display:flex; flex-direction:column; gap:6px; }',
   '.up-row { display:flex; align-items:center; gap:10px; position:relative; }',
@@ -239,10 +318,10 @@ const CSS = [
   '.up-bar { flex:1; min-width:120px; max-width:320px; height:8px; border-radius:999px; overflow:hidden; flex:none;',
   '  background:var(--up-border); }',
   '.up-bar__fill { display:block; height:100%; border-radius:999px;',
-  '  background:linear-gradient(90deg, var(--up-ok), color-mix(in srgb, var(--up-ok) 72%, #3ddc84));',
+  '  background:linear-gradient(90deg, var(--up-ok), color-mix(in srgb, var(--up-ok) 72%, var(--dsw-alias-bg-base)));',
   '  transition:width 0.4s ease; }',
-  '.up-bar__fill--warn { background:linear-gradient(90deg, var(--up-warn), #f0a13e); }',
-  '.up-bar__fill--crit { background:linear-gradient(90deg, var(--up-err), #f0574f); }',
+  '.up-bar__fill--warn { background:linear-gradient(90deg, var(--up-warn), color-mix(in srgb, var(--up-warn) 60%, var(--dsw-alias-bg-base))); }',
+  '.up-bar__fill--crit { background:linear-gradient(90deg, var(--up-err), color-mix(in srgb, var(--up-err) 60%, var(--dsw-alias-bg-base))); }',
   '.up-pct { font-variant-numeric:tabular-nums; font-weight:600; font-size:13px; min-width:44px; text-align:right; }',
   // ---- 数字与状态色 ----
   '.up-meta { color:var(--up-muted); font-size:12px; line-height:1.6; }',
@@ -256,30 +335,32 @@ const CSS = [
   '.up-dot--off { background:var(--up-err); box-shadow:0 0 0 3px color-mix(in srgb, var(--up-err) 18%, transparent); }',
   // ---- 悬浮提示(读数明细) ----
   '.up-tip { position:absolute; top:calc(100% + 8px); left:0; visibility:hidden; opacity:0;',
-  '  transition:opacity 0.15s ease; background:rgba(22,24,28,0.94); color:#f0f1f3;',
+  '  transition:opacity 0.15s ease; background:color-mix(in srgb, var(--dsw-alias-label-primary) 94%, transparent); color:var(--dsw-alias-bg-base);',
   '  font-size:11px; line-height:1.7; padding:7px 11px; border-radius:9px; white-space:nowrap; text-align:left;',
-  '  z-index:40; pointer-events:none; box-shadow:0 6px 20px rgba(0,0,0,0.35); }',
+  '  z-index:40; pointer-events:none; box-shadow:var(--dsw-shadow-lv2); }',
   '.up-row:hover .up-tip { visibility:visible; opacity:1; }',
   // ---- 趋势弹层:毛玻璃 ----
   '.up-trend { position:absolute; top:calc(100% + 8px); left:0; visibility:hidden; opacity:0;',
-  '  transition:opacity 0.15s ease; background:rgba(24,26,31,0.86); color:#f0f1f3;',
+  '  transition:opacity 0.15s ease; background:color-mix(in srgb, var(--dsw-alias-label-primary) 86%, transparent); color:var(--dsw-alias-bg-base);',
   '  backdrop-filter:blur(14px); -webkit-backdrop-filter:blur(14px);',
-  '  border:1px solid rgba(255,255,255,0.12);',
+  '  border:1px solid color-mix(in srgb, var(--dsw-alias-bg-base) 12%, transparent);',
   '  font-size:11px; line-height:1.6; padding:10px 12px; border-radius:12px; z-index:41;',
-  '  box-shadow:0 10px 36px rgba(0,0,0,0.45); }',
+  '  box-shadow:var(--dsw-shadow-lv3); }',
   '.up-trend__title { font-weight:600; margin-bottom:4px; font-size:12px; }',
   '.up-trend__chart { margin:2px 0 6px; }',
   '.up-trend__chart text { fill:currentColor; font-size:9px; }',
+  '.up-trend__line--ok { stroke:var(--up-ok); }',
+  '.up-trend__line--err { stroke:var(--up-err); }',
   '.up-trend__point:hover circle { r:4; }',
   '.up-card:hover .up-trend { visibility:visible; opacity:1; }',
   '.up-card:hover { cursor:default; }',
   // ---- 对话框:毛玻璃遮罩 + 提升卡片 ----
-  '.up-dialog-mask { position:fixed; inset:0; background:rgba(0,0,0,0.5); z-index:60;',
+  '.up-dialog-mask { position:fixed; inset:0; background:color-mix(in srgb, var(--dsw-alias-label-primary) 50%, transparent); z-index:60;',
   '  backdrop-filter:blur(4px); -webkit-backdrop-filter:blur(4px);',
   '  display:flex; align-items:center; justify-content:center; }',
   '.up-dialog { background:var(--up-surface); color:inherit; border:1px solid var(--up-border); border-radius:14px;',
   '  padding:18px 20px; max-width:680px; width:90%; max-height:80vh; overflow:auto;',
-  '  display:flex; flex-direction:column; gap:10px; box-shadow:0 16px 48px rgba(0,0,0,0.5); }',
+  '  display:flex; flex-direction:column; gap:10px; box-shadow:var(--dsw-shadow-lv3); }',
   '.up-dialog table { border-collapse:collapse; width:100%; font-size:12px; }',
   '.up-dialog th, .up-dialog td { text-align:left; padding:4px 10px;',
   '  border-bottom:1px solid var(--up-border); }',
@@ -297,7 +378,7 @@ const CSS = [
   '.up-field input:hover, .up-field select:hover, .up-field textarea:hover { border-color:color-mix(in srgb, var(--up-focus) 45%, var(--up-border)); }',
   '.up-field input:focus-visible, .up-field select:focus-visible, .up-field textarea:focus-visible {',
   '  outline:none; border-color:var(--up-focus); box-shadow:0 0 0 3px color-mix(in srgb, var(--up-focus) 22%, transparent); }',
-  '.up-field textarea { font-family:ui-monospace, Consolas, monospace; font-size:12px; min-height:52px; resize:vertical; }',
+  '.up-field textarea { font-family:var(--ds-font-family-code); font-size:12px; min-height:52px; resize:vertical; }',
   '.up-grid { display:grid; grid-template-columns:1fr 1fr; gap:10px; }',
   // ---- 通知与提示 ----
   '.up-notice { font-size:12px; padding:7px 11px; border-radius:9px;',
@@ -338,7 +419,7 @@ const CSS = [
   '.up-switch__track { width:30px; height:16px; border-radius:999px; flex:none; position:relative;',
   '  background:var(--up-border); transition:background 0.15s ease; }',
   '.up-switch__thumb { position:absolute; top:2px; left:2px; width:12px; height:12px; border-radius:50%;',
-  '  background:#fff; transition:left 0.15s ease; }',
+  '  background:var(--dsw-alias-bg-base); transition:left 0.15s ease; }',
   '.up-switch input[type="checkbox"]:checked + .up-switch__track { background:var(--up-ok); }',
   '.up-switch input[type="checkbox"]:checked + .up-switch__track .up-switch__thumb { left:16px; }',
   '.up-switch input[type="checkbox"]:focus-visible + .up-switch__track { outline:2px solid var(--up-focus); outline-offset:2px; }',
@@ -862,9 +943,9 @@ function TrendChart(props) {
       mode === 'abs'
         ? h('polyline', { points: polyline, fill: 'none', stroke: 'currentColor', strokeWidth: 1.5 })
         : plotted.map((p, index) => h('line', {
-            key: String(index), className: 'up-trend__point',
+            key: String(index), className: 'up-trend__point ' + (p.v >= 0 ? 'up-trend__line--ok' : 'up-trend__line--err'),
             x1: p.x, x2: p.x, y1: SPARK_HEIGHT / 2, y2: p.y,
-            stroke: p.v >= 0 ? '#1a9e55' : '#d43a3a', strokeWidth: 2,
+            strokeWidth: 2,
           }, h('title', null, fmtTimeFull(p.t) + ' ' + (p.v >= 0 ? '+' : '') + p.v))),
       mode === 'abs' ? plotted.map((p, index) => h('circle', {
         key: String(index), className: 'up-trend__point', cx: p.x, cy: p.y, r: 2, fill: 'currentColor',
@@ -1009,6 +1090,10 @@ function NotifyConfigCard() {
   }
   function fail(err) {
     notify('保存失败:' + (err && err.message ? err.message : String(err)), 'error')
+    // 失败权威回填:保存被拒时本卡展示态可能已偏离服务端(前序写/他人写生效),拉权威态收敛
+    api('/api/usage-panel/notify-config')
+      .then((res) => { if (res && res.notify) setConfig(res.notify) })
+      .catch(() => {})
   }
   function patch(part) {
     api('/api/usage-panel/notify-config', { method: 'POST', body: JSON.stringify(part) })
@@ -1429,6 +1514,8 @@ function UsagePanelApp() {
     return {
       inject: ['slots'],
       apply(ctx) {
+        const bus = tools.setupCommonTools(ctx)
+        ctx.effect(() => startNotifications(bus), 'usage-panel notifications')
         ctx.slots.inject('settings.section', () =>
           ctx.slots.register(
             { name: 'settings.section', id: 'usage-panel', order: 40, label: '账号余额' },

package/src/index.js

@@ -1,3 +1,4 @@
+import { setupCommonTools, createChangeNotifier } from '@mzzsfy/dsh-common-tools/host'
 // 用量面板 Host 半区:多平台余额查询 + 定期轮询 + 历史快照落盘。webServer 路由供浏览器半区调用,
 // fetch 直连平台 API,配置持久化在 ~/.dsh/dsh-usage-panel/accounts.json,快照在 history.json。
 
@@ -42,8 +43,6 @@ const MAX_ACCOUNTS = 20
 // 单轮轮询的受限并发:串行执行时单账号 20s 超时即可拖满整轮(pollInFlight 互斥
 // 使后续 tick 全部跳过,轮询事实停摆),并发上限同时压住上游瞬时压力
 const POLL_CONCURRENCY = 4
-// 通知长轮询服务端挂起上限,与 turn-notify 同值;客户端超时须大于此值
-const LONG_POLL_WAIT_MS = 25 * 1000
 // 数据目录支持 env 注入(测试隔离);缺省落 ~/.dsh/dsh-usage-panel
 const DATA_DIR = process.env.DSH_USAGE_PANEL_DATA_DIR || join(homedir(), '.dsh', 'dsh-usage-panel')
 const DATA_FILE = join(DATA_DIR, 'accounts.json')
@@ -339,9 +338,14 @@ async function queryAccount(account) {
 
 /** @param {import('@deepseek-ai/cordis').Context} ctx */
 // timer 为软依赖:不进 inject 声明,服务缺失时仅停用自动轮询,面板手动查询不受影响
+// 推送总线:页内通知刷新统一走公共依赖 common-tools,客户端长轮询已废除(不留双路径)
 export const inject = ['webServer']
 
 export function apply(ctx, configRef) {
+  const tools = setupCommonTools(ctx)
+  const changes = createChangeNotifier(() => tools.publish())
+  ctx.effect(() => () => changes.dispose(), '通知变更合并')
+  const notifyChange = changes.refresh
   let config = null
   let loadPromise = null
   let writeChain = Promise.resolve()
@@ -361,6 +365,26 @@ export function apply(ctx, configRef) {
     return resolvedNotifySettings(value && typeof value === 'object' ? value.notify : undefined)
   }
 
+  // 通知配置串行写链:读改写整体入链,任一失败不吞链(catch 后换行续链)
+  let notifyConfigWriteChain = Promise.resolve()
+
+  function persistNotifyPatch(patch) {
+    // 读出当前值做浅合并后整体写回,不依赖宿主写入的嵌套合并语义
+    const merged = { ...readNotifySettings(), ...patch }
+    // 双形写(maintain 同构,判定延迟到使用点):legacy 方法面以 register 为准
+    // (0.1.7 的 settings.update 名义在场但按命名空间找条目必败,不可作判据);
+    // 0.1.7+ 走 configEditor.edit 落 profile 条目(fiber.entry,与命名空间解耦)
+    const settings = ctx.get('settings')
+    requireOk(settings !== undefined, 'settings 服务不可用')
+    if (typeof settings.register === 'function' && typeof settings.update === 'function') {
+      return settings.update(NAMESPACE, { notify: merged })
+    }
+    const editor = ctx.get('configEditor')
+    const entry = ctx.fiber?.entry
+    requireOk(editor && typeof editor.edit === 'function' && entry, 'configEditor 服务不可用')
+    return editor.edit(entry, (current) => ({ ...current, notify: merged }))
+  }
+
   function ensureHistory() {
     return historyStore.ensure().then((sequences) => {
       history = sequences
@@ -424,8 +448,11 @@ export function apply(ctx, configRef) {
     notifySeq += outcome.events.length
     account.notifyState = outcome.state
     for (const event of outcome.events) {
-      // toast 开关在投影侧消费:关闭即浏览器半区轮询不到,出站通道不受影响
-      if (globalNotify.toast) projection.push(event)
+      // toast 开关在投影侧消费:关闭即浏览器半区订阅不到,出站通道不受影响
+      if (globalNotify.toast) {
+        projection.push(event)
+        notifyChange()
+      }
       void sendWebhook({ url: globalNotify.webhookUrl, payload: buildWebhookPayload(event) })
       deliverIm(event, globalNotify)
     }
@@ -616,20 +643,12 @@ export function apply(ctx, configRef) {
           sendJson(res, 405, { error: 'method not allowed' })
           return
         }
-        // 长轮询:cursor 缺省=首拉立即返回;仅版本恰等时挂起至事件 push / 超时;
-        // cursor 超前(宿主重启版本回退)立即返回全量,客户端以响应 version 重置游标自愈
-        const url = new URL(req.url, 'http://localhost')
-        const rawCursor = Number(url.searchParams.get('cursor'))
-        const cursor = Number.isFinite(rawCursor) ? rawCursor : 0
-        if (url.searchParams.has('cursor') && projection.version() === cursor) {
-          await projection.wait(cursor, LONG_POLL_WAIT_MS)
-        }
+        // 快照:恒全量返回(变更通知走总线,不再长轮询挂起);丢失恢复靠订阅 onReset 全量对账
         sendJson(res, 200, { units: projection.list(), version: projection.version() })
       },
     })
     return () => {
       disposeRoute()
-      // 唤醒全部挂起长轮询,以当前版本收尾,防卸载后连接悬挂
       projection.dispose()
     }
   }, 'usage-panel notifications route')
@@ -647,21 +666,12 @@ export function apply(ctx, configRef) {
           const body = JSON.parse(await readBody(req))
           const check = validateNotifyPatch(body)
           requireOk(check.ok, check.reason)
-          // 读出当前值做浅合并后整体写回,不依赖宿主写入的嵌套合并语义
-          const merged = { ...readNotifySettings(), ...check.patch }
-          // 双形写(maintain 同构,判定延迟到使用点):legacy 方法面以 register 为准
-          // (0.1.7 的 settings.update 名义在场但按命名空间找条目必败,不可作判据);
-          // 0.1.7+ 走 configEditor.edit 落 profile 条目(fiber.entry,与命名空间解耦)
-          const settings = ctx.get('settings')
-          requireOk(settings !== undefined, 'settings 服务不可用')
-          if (typeof settings.register === 'function' && typeof settings.update === 'function') {
-            await settings.update(NAMESPACE, { notify: merged })
-          } else {
-            const editor = ctx.get('configEditor')
-            const entry = ctx.fiber?.entry
-            requireOk(editor && typeof editor.edit === 'function' && entry, 'configEditor 服务不可用')
-            await editor.edit(entry, (current) => ({ ...current, notify: merged }))
-          }
+          // 读改写经串行链执行:重叠请求各自基于旧快照合并会互相覆盖
+          // (先写的 enabled 被后写基于旧 enabled=false 的合并抹掉),链式
+          // 追加保证任一写读取的总是前序写完成后的最新值;共享链以 catch
+          // 续接,单次失败只回报本次请求(抛错由 guardedRoute 统一转 400),
+          // 不阻断后续写
+          await notifyConfigWriteChain.then(() => persistNotifyPatch(check.patch))
           sendJson(res, 200, { ok: true, notify: publicNotify(readNotifySettings()) })
         }),
       }),

package/test/_mocks.common-tools.mjs

@@ -0,0 +1,20 @@
+// common-tools host 桩(经 --import 预载,先于被测模块实例化拦截 ESM):
+// publish 记入 busStub.published(断言点零改);onPresence 注册即报 0,
+// busStub.presence 供测试手动驱动连接计数
+import { mock } from 'node:test'
+
+export const busStub = { published: [], presence: new Set() }
+export function resetBusStub() {
+  busStub.published = []
+  busStub.presence = new Set()
+}
+
+mock.module('@mzzsfy/dsh-common-tools/host', {
+  namedExports: {
+    createChangeNotifier: refresh => ({ refresh, dispose() {} }),
+    setupCommonTools: () => ({
+      publish: (payload = null) => busStub.published.push(payload),
+      onPresence(fn) { busStub.presence.add(fn); fn(0); return () => busStub.presence.delete(fn) },
+    }),
+  },
+})

package/test/client-bus-lifecycle.test.mjs

@@ -0,0 +1,83 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+
+const source = readFileSync(new URL('../src/client.js', import.meta.url), 'utf8')
+
+function fixture() {
+  let definition
+  const window = {
+    __ModuleLoader__: { load: value => { definition = value } },
+    localStorage: { length: 0, getItem: () => null },
+  }
+  const subscriptions = new Set(), requests = [], shown = []
+  const tools = {
+    createSnapshotRefresh: refresh => ({ refresh, dispose() {} }),
+    toast: { show: (...args) => shown.push(args) },
+    setupCommonTools(ctx) {
+      assert.equal(ctx.fiber.entry.options.name, '@mzzsfy/dsh-usage-panel')
+      return { subscribe(onMessage, { onReset } = {}) {
+        const item = { onMessage, onReset }
+        subscriptions.add(item)
+        return () => subscriptions.delete(item)
+      } }
+    },
+  }
+  const fetch = (path, options) => new Promise(resolve => requests.push({ path, options, resolve }))
+  new Function('window', 'fetch', source)(window, fetch)
+  const instantiate = () => {
+    const effects = [], cleanups = []
+    const mod = definition.factory(name => name === 'react' ? {} : tools)
+    const ctx = {
+      fiber: { entry: { options: { name: '@mzzsfy/dsh-usage-panel' } } },
+      effect(fn) { effects.push(fn) },
+      slots: { inject() {}, register() {} },
+    }
+    return { apply() { mod.apply(ctx); for (const effect of effects) { const off = effect(); if (typeof off === 'function') cleanups.push(off) } },
+      dispose() { for (const off of cleanups.reverse()) off() } }
+  }
+  return { window, subscriptions, requests, shown, instantiate,
+    emit() { for (const item of subscriptions) item.onReset?.() } }
+}
+
+const flush = () => new Promise(resolve => setImmediate(resolve))
+
+test('Given 尚未激活的 client When factory 物化 Then 不订阅或拉取通知快照', () => {
+  const f = fixture()
+  f.instantiate()
+  assert.equal(f.subscriptions.size, 0)
+  assert.equal(f.requests.length, 0)
+})
+
+test('Given ctx 已激活且快照在途 When 卸载 Then 退订并中止请求且不呈现迟到快照', async () => {
+  const f = fixture(), plugin = f.instantiate()
+  plugin.apply()
+  assert.equal(f.subscriptions.size, 1)
+  f.emit()
+  assert.equal(f.requests.length, 1)
+  const request = f.requests[0]
+  plugin.dispose()
+  assert.equal(f.subscriptions.size, 0)
+  assert.equal(request.options.signal.aborted, true)
+  f.emit()
+  assert.equal(f.requests.length, 1)
+  request.resolve({ ok: true, json: async () => ({ version: 1, units: [{ id: 'late', text: '旧代通知' }] }) })
+  await flush()
+  assert.equal(f.shown.length, 0)
+  assert.equal(Object.hasOwn(f.window, 'usage-panel:notify-poll'), false)
+  assert.equal(Object.hasOwn(f.window, 'usage-panel:notify-poll:dispose'), false)
+})
+
+test('Given 旧代激活 When 新代 apply Then 仅保留新代订阅且旧代卸载不清新代令牌', () => {
+  const f = fixture(), old = f.instantiate()
+  old.apply(); f.emit()
+  const current = f.instantiate()
+  current.apply()
+  assert.equal(f.requests[0].options.signal.aborted, true)
+  assert.equal(f.subscriptions.size, 1)
+  const token = f.window['usage-panel:notify-poll']
+  old.dispose()
+  assert.equal(f.window['usage-panel:notify-poll'], token)
+  current.dispose()
+  assert.equal(f.subscriptions.size, 0)
+})

package/test/notify-poll.test.mjs

@@ -1,31 +1,174 @@
-// 页内通知长轮询 BDD:client 半区以顺序长轮询消费通知投影——
-// 任何时刻至多一条在途请求,失败指数退避,HMR/闭包重建重复装载时
-// 新代首挂 abort 旧代长轮询再启新代——旧代不滞留、不叠加、不告警。
-// 轮询段运行于 factory 闭包内(IO),守卫以源码契约断言锁定形态。
-
 import { test } from 'node:test'
 import assert from 'node:assert/strict'
 import { readFileSync } from 'node:fs'
-import { join, dirname } from 'node:path'
-import { fileURLToPath } from 'node:url'
 
-const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..')
-const source = readFileSync(join(PKG_ROOT, 'src', 'client.js'), 'utf8')
+const source = readFileSync(new URL('../src/client.js', import.meta.url), 'utf8')
+
+const flush = () => new Promise(resolve => setImmediate(resolve))
+const storageFixture = () => {
+  const rows = new Map()
+  return { get length() { return rows.size }, key: index => [...rows.keys()][index] ?? null,
+    getItem: key => rows.get(key) ?? null, setItem: (key, value) => rows.set(key, value), removeItem: key => rows.delete(key) }
+}
+
+function clientFixture({ storage = storageFixture(), indexedDB, abortSignalImpl = AbortSignal } = {}) {
+  let definition, payload = { version: 0, units: [] }
+  const shown = [], subscriptions = new Set(), pending = new Set()
+  const window = { localStorage: storage, indexedDB, __ModuleLoader__: { load: value => { definition = value } } }
+  const tools = {
+    createSnapshotRefresh: refresh => ({ refresh() {
+      const work = refresh(); pending.add(work); work.finally(() => pending.delete(work)); return work
+    }, dispose() {} }),
+    toast: { show: text => shown.push(text) },
+    setupCommonTools: () => ({ subscribe(onMessage, { onReset }) {
+      subscriptions.add(onReset); return () => subscriptions.delete(onReset)
+    } }),
+  }
+  const fetch = async () => ({ ok: true, json: async () => payload })
+  new Function('window', 'fetch', 'AbortSignal', source)(window, fetch, abortSignalImpl)
+  function generation() {
+    const mod = definition.factory(name => name === 'react' ? {} : tools)
+    return { apply() {
+      const cleanups = []
+      mod.apply({ fiber: { entry: { options: { name: '@mzzsfy/dsh-usage-panel' } } },
+        slots: { inject() {}, register() {} }, effect(fn) { const off = fn(); if (typeof off === 'function') cleanups.push(off) } })
+      return () => { while (cleanups.length) cleanups.pop()() }
+    } }
+  }
+  return { shown, window, generation, set(payloadNext) { payload = payloadNext },
+    poll() { for (const refresh of subscriptions) refresh(); return Promise.all([...pending]) } }
+}
 
-test('代际令牌承载 AbortController:新代启动前中止旧代长轮询', () => {
-  assert.match(source, /window\[KEY_POLL_TOKEN\] instanceof AbortController/, '缺少旧代 AbortController 判定')
-  assert.match(source, /window\[KEY_POLL_TOKEN\]\.abort\(\)/, '缺少旧代长轮询中止')
-  assert.match(source, /window\[KEY_POLL_TOKEN\] = notifyController/, '控制器未交接给令牌')
+// 同库事务串行，只有提交后才发布写入；事务取消丢弃整个草稿。
+function indexedDbFixture() {
+  let rows = new Map(), initialized = false, queue = Promise.resolve(), gate = null
+  const connections = []
+  const factory = { open() {
+    const request = {}
+    setImmediate(() => {
+      const db = { closed: false, createObjectStore() {}, close() { this.closed = true }, transaction() {
+        if (this.closed) throw new Error('closed')
+        const tx = {}, operations = []
+        let draft, aborted = false
+        tx.abort = () => { aborted = true }
+        const requestFor = run => {
+          const request = {}; operations.push(() => { request.result = run(); request.onsuccess?.() }); return request
+        }
+        tx.objectStore = () => ({ getAll: () => requestFor(() => [...draft.values()]),
+          delete: id => requestFor(() => draft.delete(id)), add: row => requestFor(() => {
+            if (draft.has(row.id)) throw new Error('ConstraintError')
+            draft.set(row.id, row)
+          }) })
+        queue = queue.then(async () => {
+          if (gate) await gate.promise
+          draft = new Map(rows)
+          try {
+            if (aborted) throw new Error('AbortError')
+            while (operations.length) operations.shift()()
+            rows = draft; tx.oncomplete?.()
+          } catch (error) { tx.error = error; tx.onabort?.() }
+        })
+        return tx
+      } }
+      connections.push(db); request.result = db
+      if (!initialized) { initialized = true; request.onupgradeneeded?.() }
+      request.onsuccess?.()
+    })
+    return request
+  } }
+  return { factory, connections, get rows() { return rows },
+    hold() { gate = {}; gate.promise = new Promise(resolve => { gate.resolve = resolve }) },
+    release() { const current = gate; gate = null; current?.resolve() } }
+}
+
+test('Given usage双窗共享storage When 新通知后旧空快照抵达再追平 Then 总呈现一次', async () => {
+  const storage = storageFixture(), idb = indexedDbFixture()
+  const a = clientFixture({ storage, indexedDB: idb.factory }), b = clientFixture({ storage, indexedDB: idb.factory })
+  const offA = a.generation().apply(), offB = b.generation().apply()
+  const payload = { version: 1, units: [{ id: 'new', text: '余额提醒', kind: 'balance', ts: Date.now() }] }
+  try {
+    a.set(payload); await a.poll(); await flush(); await flush()
+    await b.poll(); await flush(); await flush()
+    b.set(payload); await b.poll(); await flush(); await flush()
+    assert.equal(a.shown.length + b.shown.length, 1)
+  } finally { offA(); offB() }
 })
 
-test('消费形态为顺序长轮询:setInterval 短轮询不得回归', () => {
-  assert.ok(!source.includes('setInterval'), '残留 interval 短轮询形态')
-  assert.match(source, /AbortSignal\.timeout\(NOTIFY_REQUEST_TIMEOUT_MS\)/, '长轮询请求缺少超时上限')
-  assert.match(source, /\?cursor=' \+ notifyCursor/, '长轮询缺少续传游标')
+test('Given usage双窗storage观察均为空 When 同时消费首快照 Then 事务单赢家且过期记录清理', async () => {
+  const idb = indexedDbFixture()
+  idb.rows.set('expired', { id: 'expired', expiresAt: 0 })
+  const a = clientFixture({ indexedDB: idb.factory }), b = clientFixture({ indexedDB: idb.factory })
+  const offA = a.generation().apply(), offB = b.generation().apply()
+  const payload = { version: 1, units: [{ id: 'race', text: '并发余额提醒', kind: 'balance', ts: Date.now() }] }
+  try {
+    a.set(payload); b.set(payload)
+    await Promise.all([a.poll(), b.poll()])
+    assert.equal(a.shown.length + b.shown.length, 1, '首快照保留既有呈现语义但跨窗只呈现一次')
+    assert.deepEqual([...idb.rows.keys()], ['race'])
+  } finally { offA(); offB() }
+})
+
+test('Given usage事务在途 When 最后owner退出和HMR Then 回滚无late显示且同id可重激活', async () => {
+  const idb = indexedDbFixture(), f = clientFixture({ indexedDB: idb.factory }), generation = f.generation()
+  const offA = generation.apply(), offB = generation.apply()
+  const payload = { version: 1, units: [{ id: 'late', text: '待接手', ts: Date.now() }] }
+  f.set(payload); idb.hold()
+  const pending = f.poll()
+  await flush(); await flush()
+  offA(); assert.equal(idb.connections[0].closed, false)
+  offB(); idb.release(); await pending
+  assert.equal(idb.rows.has('late'), false)
+  assert.deepEqual(f.shown, [])
+  assert.equal(idb.connections[0].closed, true)
+  const offAgain = generation.apply()
+  await f.poll()
+  assert.deepEqual(f.shown, ['待接手'])
+  const current = f.generation(), offCurrent = current.apply()
+  await flush()
+  assert.equal(idb.connections[1].closed, true, '新代接管关闭旧代连接')
+  offAgain(); offCurrent()
+})
+
+test('Given 宿主时钟落后 When 消费有效快照 Then 正常呈现；IDB不可用时本窗同事件仍只呈现一次', async () => {
+  const idb = indexedDbFixture(), f = clientFixture({ indexedDB: idb.factory })
+  const off = f.generation().apply()
+  try {
+    f.set({ version: 1, units: [{ id: 'clock-skew', text: '有效通知', ts: Date.now() - 10 * 60 * 1000 }] })
+    await f.poll()
+    assert.deepEqual(f.shown, ['有效通知'])
+  } finally { off() }
+  const degraded = clientFixture({ storage: { get length() { throw new Error('blocked') }, getItem() { throw new Error('blocked') } } })
+  const offDegraded = degraded.generation().apply()
+  try {
+    degraded.set({ version: 1, units: [{ id: 'fallback', text: '降级', ts: Date.now() }] })
+    await degraded.poll(); await degraded.poll()
+    assert.deepEqual(degraded.shown, ['降级'])
+  } finally { offDegraded() }
 })
 
-test('失败退避与游标防呆:异常响应不退化成紧密首拉循环', () => {
-  assert.match(source, /backoffMs = NOTIFY_RETRY_MIN_MS/, '成功后未重置退避基数')
-  assert.match(source, /backoffMs = Math\.min\(backoffMs \* 2, NOTIFY_RETRY_MAX_MS\)/, '缺少指数退避')
-  assert.match(source, /typeof payload\.version !== 'number'\) return false/, '版本缺失未按失败退避')
+test('Given usage认领事务等待 When 本地快照消费超时 Then 回滚不留done且另窗能接手', async () => {
+  const idb = indexedDbFixture(), timeout = new AbortController()
+  const payload = { version: 1, units: [{ id: 'timeout', text: '可接手', ts: Date.now() - 10 * 60 * 1000 }] }
+  const a = clientFixture({ indexedDB: idb.factory,
+    abortSignalImpl: { timeout: () => timeout.signal, any: signals => AbortSignal.any(signals) } })
+  const offA = a.generation().apply()
+  a.set(payload); idb.hold()
+  const pending = a.poll()
+  await flush(); await flush()
+  timeout.abort(); idb.release(); await pending
+  assert.deepEqual(a.shown, [])
+  assert.equal(idb.rows.has('timeout'), false)
+  const b = clientFixture({ indexedDB: idb.factory }), offB = b.generation().apply()
+  try { b.set(payload); await b.poll(); assert.deepEqual(b.shown, ['可接手']) }
+  finally { offA(); offB() }
+})
+
+test('消费形态为推送总线订阅:setInterval 短轮询与长轮询游标不得回归', () => {
+  assert.ok(!source.includes('setInterval'), '残留 interval 短轮询形态')
+  assert.ok(!source.includes('while (!notifyController'), '残留长轮询主循环形态')
+  assert.match(source, /tools\.setupCommonTools\(ctx\)/, '缺少插件上下文绑定')
+  assert.match(source, /bus\.subscribe\(refresh, \{ onReset: refresh \}\)/, '缺少消息与重连快照入口')
+  assert.match(source, /AbortSignal\.timeout\(NOTIFY_REQUEST_TIMEOUT_MS\)/, '快照请求缺少超时上限')
+  assert.ok(!source.includes('?cursor='), '残留长轮询续传游标形态')
+  assert.ok(!source.includes('NOTIFY_RETRY'), '残留退避重试形态')
 })

package/test/notify.route.test.mjs

@@ -3,6 +3,7 @@
 
 import { test, after } from 'node:test'
 import assert from 'node:assert/strict'
+import { busStub, resetBusStub } from './_mocks.common-tools.mjs'
 import { EventEmitter } from 'node:events'
 import { mkdtemp, rm } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
@@ -20,13 +21,16 @@ after(async () => {
 
 const NOTIFY_ON = { notify: { enabled: true, quotaThresholdPct: 50 } }
 
-function makeCtx({ settingsValue = {}, dshIm = undefined } = {}) {
+function makeCtx({ settingsValue = {}, dshIm = undefined, beforeSettingsUpdate } = {}) {
   let value = settingsValue
   const routes = new Map()
+  resetBusStub()
+  const published = busStub.published
   const settingsService = {
     register() {},
     get: () => value,
     update: async (_ns, patch) => {
+      if (beforeSettingsUpdate) await beforeSettingsUpdate(patch)
       value = { ...value, ...patch }
     },
   }
@@ -49,7 +53,7 @@ function makeCtx({ settingsValue = {}, dshIm = undefined } = {}) {
       },
     },
   }
-  return { ctx, routes }
+  return { ctx, routes, published }
 }
 
 function makeReq(method, body, extraHeaders = {}) {
@@ -208,6 +212,58 @@ test('notify-config: 非法补丁 400, 合法补丁合并生效', async () => {
   assert.equal(view.payload.notify.webhookUrl, 'https://hooks.example.com/keep')
 })
 
+test('notify-config: 并发 POST 串行化读改写, 先写不被后写基于旧快照覆盖', async () => {
+  // Given 慢写 settings.update(可控闸门队列,落盘真实发生),初始通知关闭
+  const gates = []
+  const writes = []
+  const beforeSettingsUpdate = async (patch) => {
+    writes.push(patch)
+    await new Promise((resolve) => gates.push(resolve))
+  }
+  const { ctx, routes } = makeCtx({ settingsValue: { notify: { enabled: false, balanceThreshold: 20 } }, beforeSettingsUpdate })
+  apply(ctx)
+  // When 启用通知(写1)与保存阈值(写2)并发提交
+  const waitForGate = () => new Promise((resolve) => {
+    const poll = () => { gates.length === 1 ? resolve() : setImmediate(poll) }
+    poll()
+  })
+  const enable = call(routes, '/api/usage-panel/notify-config', makeReq('POST', { enabled: true }))
+  await waitForGate()
+  const threshold = call(routes, '/api/usage-panel/notify-config', makeReq('POST', { balanceThreshold: 5 }))
+  // Then 两写按提交序串行落盘:写2 须在写1 完成后才进入读改写(闸门二次出现),
+  // 且基于含 enabled=true 的快照合并
+  gates.shift()()
+  await waitForGate()
+  gates.shift()()
+  // 两写均已放闸,完成序颠倒也不影响断言(读快照序已由串行链锁定)
+  const [enableRes, thresholdRes] = await Promise.all([enable, threshold])
+  assert.equal(enableRes.status, 200)
+  assert.equal(thresholdRes.status, 200)
+  assert.equal(writes.length, 2)
+  assert.equal(writes[0].notify.enabled, true)
+  assert.equal(writes[1].notify.enabled, true, '写2 读改写须含写1 的 enabled=true')
+  assert.equal(writes[1].notify.balanceThreshold, 5)
+})
+
+test('notify-config: 单次写失败不阻塞后续写, 失败响应 400 且错误可见', async () => {
+  // Given settings.update 首次失败
+  let calls = 0
+  const flakyBefore = async () => {
+    calls += 1
+    if (calls === 1) throw new Error('disk full')
+  }
+  const { ctx, routes } = makeCtx({ settingsValue: { notify: { enabled: false } }, beforeSettingsUpdate: flakyBefore })
+  apply(ctx)
+  // When 第一次写失败后第二次写
+  const first = await call(routes, '/api/usage-panel/notify-config', makeReq('POST', { enabled: true }))
+  const second = await call(routes, '/api/usage-panel/notify-config', makeReq('POST', { enabled: true }))
+  // Then 首写 400 携带原因, 次写成功生效
+  assert.equal(first.status, 400)
+  assert.match(first.payload.error, /disk full/)
+  assert.equal(second.status, 200)
+  assert.equal(calls, 2)
+})
+
 test('test-webhook: 返回真实投递结果而非谎报成功', async () => {
   // Given webhook 已配置, fetch 桩标记调用
   const { ctx, routes } = makeCtx({ settingsValue: { notify: { enabled: true, webhookUrl: 'https://hooks.example.com/hook' } } })
@@ -414,32 +470,41 @@ test('长轮询: 无 cursor 首拉立即返回空投影与当前版本', async (
   assert.equal(res.payload.version, 0)
 })
 
-test('长轮询: cursor 追平当前版本时挂起, 事件 push 后唤醒并返回新版本', async () => {
-  // Given 通知启用
+test('快照: 恒立即返回全量投影与当前版本, 无挂起形态', async () => {
+  // Given 通知启用且投影为空
   const { ctx, routes } = makeCtx({ settingsValue: NOTIFY_ON })
   apply(ctx)
-  // When 以追平版本 0 发起长轮询
-  const { req, res } = notifyRequest('?cursor=0')
-  const pending = routes.get('/api/usage-panel/notifications')(req, res)
-  await new Promise((resolve) => setTimeout(resolve, 0))
-  // Then 未唤醒前不响应
-  assert.equal(res.payload, null, '未唤醒前不应响应')
+  // When 快照请求(带或带 cursor 均为全量形态)
+  const { req, res } = notifyRequest('')
+  await routes.get('/api/usage-panel/notifications')(req, res)
+  // Then 立即返回且携带版本号
+  assert.equal(res.status, 200)
+  assert.deepEqual(res.payload.units, [])
+  assert.equal(res.payload.version, 0)
+})
+
+test('变更发布: 事件 push 进入投影即发布总线变更', async () => {
+  // Given 通知启用
+  const { ctx, routes, published } = makeCtx({ settingsValue: NOTIFY_ON })
+  apply(ctx)
   // When 查询产生越阈事件入投影
   await produceNotifyEvent(routes)
-  await pending
-  // Then 唤醒返回新版本与事件
+  // Then 快照携带事件,总线收到发布
+  const { req, res } = notifyRequest('')
+  await routes.get('/api/usage-panel/notifications')(req, res)
   assert.equal(res.status, 200)
-  assert.equal(res.payload.version, 2, 'push 两条事件应各递增一次版本并唤醒等待者')
   assert.equal(res.payload.units.length, 2)
+  assert.ok(res.payload.version > 0)
+  assert.deepEqual(published, [null, null], '每条事件入投影各发布一次')
 })
 
-test('长轮询: cursor 落后当前版本时立即返回不挂起', async () => {
+test('快照: 投影已有事件时返回全量', async () => {
   // Given 投影已有事件(版本已前进)
   const { ctx, routes } = makeCtx({ settingsValue: NOTIFY_ON })
   apply(ctx)
   await produceNotifyEvent(routes)
-  // When 以落后 cursor 请求
-  const { req, res } = notifyRequest('?cursor=0')
+  // When 快照请求
+  const { req, res } = notifyRequest('')
   await routes.get('/api/usage-panel/notifications')(req, res)
   // Then 立即返回全量
   assert.equal(res.status, 200)