@mzzsfy/dsh-usage-panel 0.7.1 → 0.8.1

package/README.md

@@ -130,3 +130,7 @@ node scripts/dev-link.mjs dsh-usage-panel   # 仓库根执行:归一 profile 依
 ```
 
 工作副本以 junction 挂进 profile,改代码保存即热重载(host 半区)或刷新页面生效(client 半区),无需发版;规约与全仓归一见仓库根 `node scripts/dev-link.mjs all`。
+
+## dsh 版本兼容
+
+三版本(0.1.2-rc.1 / 0.1.5-rc.3 / 0.1.7-rc.1)全部通过:用量面板渲染(账号卡/通知规则折叠卡全控件)、API 面(pollArmed/通知投影)、激活 live。

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mzzsfy/dsh-usage-panel",
   "description": "多平台 LLM 账号余额与额度面板:支持 DeepSeek/OpenRouter/Kimi/智谱/MiniMax/NewApi 及自定义端点,自动定期查询,趋势图与历史快照,用量/余额阈值与窗口重置多通道通知",
-  "version": "0.7.1",
+  "version": "0.8.1",
   "type": "module",
   "main": "src/index.js",
   "exports": {

package/src/client.js

@@ -565,6 +565,9 @@ function AccountCard(props) {
   const armed = props.deleteArmed === true
   const reading = account.last && account.last.ok ? account.last.reading : null
   const level = reading && (reading.level || reading.membership) ? levelLabel(reading.level || reading.membership) : null
+  const queriedAt = account.last && typeof account.last.queriedAt === 'number' && Number.isFinite(account.last.queriedAt)
+    ? account.last.queriedAt
+    : null
 
   return h('div', { className: 'up-card' },
     h('div', { className: 'up-card__row' },
@@ -572,6 +575,7 @@ function AccountCard(props) {
       h('span', { className: 'up-badge', 'data-type': account.type }, TYPE_LABELS[account.type] || account.type),
       level ? h('span', { className: 'up-badge', 'data-type': 'custom' }, level) : null,
       h('span', { className: 'up-spacer' }),
+      queriedAt !== null ? h('span', { className: 'up-meta', title: fmtTimeFull(queriedAt) }, '上次更新 ' + fmtTime(queriedAt)) : null,
       h('button', { className: 'up-btn', disabled: busy, onClick: props.onRefresh }, busy ? '查询中…' : '刷新'),
       h('button', { className: 'up-btn', disabled: busy, onClick: props.onEdit }, '编辑'),
       h('button', {

package/src/index.js

@@ -66,6 +66,21 @@ const SETTINGS_SCHEMA = z.object({
   }).default({}),
 })
 
+// 0.1.7 宿主以静态 Config 导出生成设置节表单(maintain 同构);legacy 宿主经
+// settings.register 注册命名空间。根级 volatile 包装:整节 live 表单,节写经
+// loader 原地热更;旧宿主 schemastery 无 volatile 方法,特性检测原样返回
+export const Config = volatileWrap(SETTINGS_SCHEMA)
+
+function volatileWrap(schema) {
+  return typeof schema.volatile === 'function' ? schema.volatile() : schema
+}
+
+// volatile ref 动态解包(get 协议):0.1.7 下 apply 入参 config 为整节单 ref;
+// legacy 宿主 config 为普通对象原样透传
+function unwrapVolatile(value) {
+  return typeof value?.get === 'function' ? value.get() : value
+}
+
 const TYPE_DEEPSEEK = 'deepseek'
 const TYPE_OPENROUTER = 'openrouter'
 const TYPE_KIMI = 'kimi'
@@ -269,7 +284,7 @@ function normalizeAccounts(input) {
             ? lastSource.reading
             : null,
           error: typeof lastSource.error === 'string' ? lastSource.error : null,
-          queriedAt: Number.isFinite(Number(lastSource.queriedAt)) ? Number(lastSource.queriedAt) : null,
+          queriedAt: typeof lastSource.queriedAt === 'number' && Number.isFinite(lastSource.queriedAt) ? lastSource.queriedAt : null,
         }
       : null
     const id = typeof raw.id === 'string' && raw.id.length > 0 ? raw.id : 'acct-' + String(index)
@@ -326,7 +341,7 @@ async function queryAccount(account) {
 // timer 为软依赖:不进 inject 声明,服务缺失时仅停用自动轮询,面板手动查询不受影响
 export const inject = ['webServer']
 
-export function apply(ctx) {
+export function apply(ctx, configRef) {
   let config = null
   let loadPromise = null
   let writeChain = Promise.resolve()
@@ -340,7 +355,9 @@ export function apply(ctx) {
 
   function readNotifySettings() {
     const settings = ctx.get('settings')
-    const value = settings ? settings.get(NAMESPACE) : undefined
+    // 双形读(maintain 同构):legacy settings 命名空间 get;0.1.7+ apply 入参
+    // config 整节解包。方法面守卫兼防:服务在但缺 get 时回落默认值,防路由 handler 抛错
+    const value = settings && typeof settings.get === 'function' ? settings.get(NAMESPACE) : unwrapVolatile(configRef)
     return resolvedNotifySettings(value && typeof value === 'object' ? value.notify : undefined)
   }
 
@@ -630,11 +647,21 @@ export function apply(ctx) {
           const body = JSON.parse(await readBody(req))
           const check = validateNotifyPatch(body)
           requireOk(check.ok, check.reason)
-          // 读出当前值做浅合并后整体写回,不依赖 settings.update 的嵌套合并语义
+          // 读出当前值做浅合并后整体写回,不依赖宿主写入的嵌套合并语义
           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 服务不可用')
-          await settings.update(NAMESPACE, { notify: merged })
+          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 }))
+          }
           sendJson(res, 200, { ok: true, notify: publicNotify(readNotifySettings()) })
         }),
       }),
@@ -765,6 +792,14 @@ export function apply(ctx) {
   })
 
   ctx.inject(['settings'], (settingsCtx) => {
+    // 方法面守卫:settings 服务缺 register 面(0.1.7 已移除)即走新形态分支;
+    // 0.1.7 关闭原生自动设置页,设置面由本包自带分区承担(maintain 同构)
+    if (typeof settingsCtx.settings.register !== 'function') {
+      if (typeof settingsCtx.settings?.configure === 'function') {
+        settingsCtx.effect(() => settingsCtx.settings.configure({ auto: false }, ctx.fiber))
+      }
+      return
+    }
     settingsCtx.settings.register(NAMESPACE, SETTINGS_SCHEMA)
   })
 }

package/src/notify.mjs

@@ -6,6 +6,9 @@ export const PROJECTION_CAPACITY = 20
 export const PROJECTION_TTL_MS = 60 * 1000
 export const CLAIM_LOCK_TTL_MS = 30 * 1000
 export const WEBHOOK_TIMEOUT_MS = 10 * 1000
+// 轮转判定容差:远小于最短真实窗口量级,远大于服务端毫秒级抖动;
+// 容差内视为同窗口静默跟随
+export const RESET_DRIFT_TOLERANCE_MS = 60 * 1000
 
 export const KIND_QUOTA = 'quota'
 export const KIND_BALANCE = 'balance'
@@ -63,6 +66,13 @@ export function normalizeNotifyState(raw) {
 
 const PERCENT_BASE = 100
 
+// 窗口轮转判定:resetsAt 数值差超容差才算轮转;parse 失败无法证伪,保守按轮转。
+// 容差内静默跟随,峰值与武装状态不重建
+function windowRotated(prevResetsAt, resetsAt) {
+  const driftMs = Math.abs(Date.parse(resetsAt) - Date.parse(prevResetsAt))
+  return !(Number.isFinite(driftMs) && driftMs < RESET_DRIFT_TOLERANCE_MS)
+}
+
 // 沿触发评估:刷新读数越过逻辑点(阈值穿越/窗口重置)时产出事件,返回新状态不改入参。
 // 仅在 last.ok 时由 host 调用;reading 缺失按无读数处理。
 export function evaluateAccount({ account, rule, state, seq, ts }) {
@@ -88,8 +98,9 @@ function evaluateQuota({ account, rule, state, reading, events, next }) {
     const prev = state.windows[label] || null
     let armed = prev === null ? true : prev.armed !== false
     let peak = prev === null ? null : prev.peak
-    // 窗口轮转:两侧 resetsAt 均有效且值不同;上一窗口峰值随 reset 事件上报
-    if (prev !== null && resetsAt !== null && prev.resetsAt !== null && prev.resetsAt !== resetsAt) {
+    // 窗口轮转:两侧 resetsAt 均有效、字符串不等且数值差超容差;上一窗口峰值随 reset 事件上报
+    if (prev !== null && resetsAt !== null && prev.resetsAt !== null && prev.resetsAt !== resetsAt
+      && windowRotated(prev.resetsAt, resetsAt)) {
       if (rule.resetNotice !== false && prev.peak !== null) {
         events.push({
           kind: KIND_RESET,

package/test/notify.route.test.mjs

@@ -446,3 +446,105 @@ test('长轮询: cursor 落后当前版本时立即返回不挂起', async () =>
   assert.equal(res.payload.units.length, 2)
   assert.ok(res.payload.version > 0)
 })
+
+// --- 0.1.7 settings 面双形适配(maintain a913c2c 同构) ---
+
+test('Config 导出契约:根级 volatile 包装,validate 产整节单 ref,默认值对拍', async () => {
+  const mod = await import('../src/index.js')
+  assert.ok(mod.Config, 'Config 导出必须在场')
+  const resolved = mod.Config['~standard'].validate({})
+  assert.equal(resolved.issues, undefined)
+  const section = resolved.value.get()
+  assert.equal(section.notify.enabled, false)
+  assert.equal(section.notify.toast, true)
+  assert.equal(section.notify.imTargets.length, 0)
+})
+
+// 0.1.7 形态装配:settings 无 register/get(宿主已移除),configRef 为整节单 ref 桩
+function makeRc17Ctx({ configStore = {}, configEditorAvailable = true } = {}) {
+  const routes = new Map()
+  const editCalls = []
+  const configureCalls = []
+  const disposers = []
+  const configRef = { get: () => ({ ...configStore }) }
+  const settingsService = { configure: (presentation, owner) => { configureCalls.push({ presentation, owner }); return () => {} } }
+  const configEditor = {
+    async edit(entry, change) {
+      editCalls.push(entry)
+      const next = change({ ...configStore }, {})
+      for (const key of Object.keys(next)) configStore[key] = next[key]
+    },
+  }
+
+  const ctx = {
+    get(name) {
+      if (name === 'settings') return settingsService
+      if (name === 'configEditor') return configEditorAvailable ? configEditor : undefined
+      return undefined
+    },
+    fiber: { entry: { options: { id: 'usage-panel', name: '@mzzsfy/dsh-usage-panel' } } },
+    effect(fn) { fn() },
+    inject(_deps, fn) {
+      fn({
+        settings: settingsService,
+        interval: () => {},
+        effect(stubEffect) {
+          const disposer = stubEffect()
+          if (typeof disposer === 'function') disposers.push(disposer)
+        },
+      })
+    },
+    webServer: {
+      register(route) {
+        routes.set(route.path, route.handler)
+        return () => routes.delete(route.path)
+      },
+    },
+  }
+  return { ctx, routes, configRef, configStore, editCalls, configureCalls, disposers }
+}
+
+test('0.1.7 形态:notify-config GET 读 configRef 节值,POST 经 configEditor.edit 落 fiber.entry', async () => {
+  // Given configRef 携带用户值 + configEditor 桩
+  const { ctx, routes, configRef, configStore, editCalls } = makeRc17Ctx({
+    configStore: { notify: { enabled: true, quotaThresholdPct: 88 } },
+  })
+  apply(ctx, configRef)
+  // When GET notify-config
+  const read = await call(routes, '/api/usage-panel/notify-config', makeReq('GET'))
+  // Then 返回 configRef 节值
+  assert.equal(read.status, 200)
+  assert.equal(read.payload.notify.enabled, true)
+  assert.equal(read.payload.notify.quotaThresholdPct, 88)
+  // When POST 部分补丁
+  const saved = await call(routes, '/api/usage-panel/notify-config', makeReq('POST', { enabled: true, balanceThreshold: 12 }))
+  // Then 整节合并落本条目
+  assert.equal(saved.status, 200)
+  assert.equal(saved.payload.ok, true)
+  assert.equal(editCalls.length, 1)
+  assert.equal(editCalls[0].options.id, 'usage-panel')
+  assert.equal(configStore.notify.enabled, true)
+  assert.equal(configStore.notify.balanceThreshold, 12)
+  assert.equal(configStore.notify.quotaThresholdPct, 88, '未提交字段整节保留')
+})
+
+test('0.1.7 形态:configEditor 缺失即 400 拒写,不崩溃', async () => {
+  // Given configEditor 服务缺席
+  const { ctx, routes, configRef } = makeRc17Ctx({ configEditorAvailable: false })
+  apply(ctx, configRef)
+  // When POST 写配置
+  const denied = await call(routes, '/api/usage-panel/notify-config', makeReq('POST', { enabled: true }))
+  // Then 400 错误响应,进程存活(测试走完即证)
+  assert.equal(denied.status, 400)
+  assert.ok(denied.payload.error)
+})
+
+test('0.1.7 形态:settings.configure 在场即关闭原生自动页,register 缺失不抛错', () => {
+  // Given settingsForms 带 configure 无 register
+  const { ctx, configRef, configureCalls } = makeRc17Ctx()
+  // When apply
+  apply(ctx, configRef)
+  // Then 关闭自动页且 owner 为本插件 fiber
+  assert.equal(configureCalls.length, 1)
+  assert.deepEqual(configureCalls[0].presentation, { auto: false })
+})

package/test/notify.test.mjs

@@ -23,6 +23,7 @@ import {
   KIND_QUOTA,
   KIND_BALANCE,
   KIND_RESET,
+  RESET_DRIFT_TOLERANCE_MS,
 } from '../src/notify.mjs'
 
 test('规则合并: 账号覆盖键生效, 其余继承全局', () => {
@@ -106,6 +107,50 @@ test('窗口重置: resetsAt 轮转产生 reset 事件报上一窗口峰值并
   assert.equal(again.events[0].kind, KIND_QUOTA)
 })
 
+test('窗口重置: 毫秒级服务端抖动视为同窗口不发事件且峰值保留', () => {
+  // Given 阈值 90, 首轮 utilization 40 以 ISO 时刻建立基线
+  const rule = { quotaThresholdPct: 90, balanceThreshold: null, resetNotice: true }
+  let state = createNotifyState()
+  state = evaluateAccount({ account: quotaAccount(quotaReading(40, '2026-10-17T09:10:04.999Z')), rule, state, seq: 1, ts: 1000 }).state
+  // When 次轮 resetsAt 仅漂移 1ms(智谱 TIME_LIMIT 实测抖动), utilization 回落
+  const next = evaluateAccount({ account: quotaAccount(quotaReading(30, '2026-10-17T09:10:04.998Z')), rule, state, seq: 2, ts: 2000 })
+  // Then 无事件, 峰值保留 40 不误报, 基线静默跟随新值
+  assert.equal(next.events.length, 0)
+  assert.equal(next.state.windows['5小时'].peak, 40)
+  assert.equal(next.state.windows['5小时'].resetsAt, '2026-10-17T09:10:04.998Z')
+})
+
+test('窗口重置: 超容差的 resetsAt 变化仍判定为轮转', () => {
+  // Given 阈值 90, 首轮 92 建立基线
+  const rule = { quotaThresholdPct: 90, balanceThreshold: null, resetNotice: true }
+  let state = createNotifyState()
+  state = evaluateAccount({ account: quotaAccount(quotaReading(92, '2026-10-17T09:10:04.999Z')), rule, state, seq: 1, ts: 1000 }).state
+  // When resetsAt 前移 1 小时(真实轮转)
+  const next = evaluateAccount({ account: quotaAccount(quotaReading(5, '2026-10-17T10:10:04.999Z')), rule, state, seq: 2, ts: 2000 })
+  // Then 产生 reset 事件报上一窗口峰值 92
+  assert.equal(next.events.length, 1)
+  assert.equal(next.events[0].kind, KIND_RESET)
+  assert.equal(next.events[0].text, '[dsh] 账号A 5小时窗口已重置,上一窗口峰值用量 92%')
+})
+
+test('窗口重置: 漂移恰好容差内静默, 达到容差即轮转', () => {
+  // Given 阈值 90, 基线 resetsAt 为固定时刻
+  const rule = { quotaThresholdPct: 90, balanceThreshold: null, resetNotice: true }
+  const baseMs = Date.parse('2026-10-17T09:10:04.999Z')
+  const isoOf = (ms) => new Date(ms).toISOString()
+  const baselineState = evaluateAccount({ account: quotaAccount(quotaReading(40, isoOf(baseMs))), rule, state: createNotifyState(), seq: 1, ts: 1000 }).state
+  // When 漂移为容差减 1ms(容差内)
+  const inside = evaluateAccount({ account: quotaAccount(quotaReading(40, isoOf(baseMs + RESET_DRIFT_TOLERANCE_MS - 1))), rule, state: baselineState, seq: 2, ts: 2000 })
+  // Then 无事件, 基线跟随
+  assert.equal(inside.events.length, 0)
+  assert.equal(inside.state.windows['5小时'].resetsAt, isoOf(baseMs + RESET_DRIFT_TOLERANCE_MS - 1))
+  // When 漂移恰好等于容差(边界,严格小于判定不吸收,独立从原始基线评估)
+  const boundary = evaluateAccount({ account: quotaAccount(quotaReading(40, isoOf(baseMs + RESET_DRIFT_TOLERANCE_MS))), rule, state: baselineState, seq: 3, ts: 3000 })
+  // Then 判定轮转产生 reset 事件
+  assert.equal(boundary.events.length, 1)
+  assert.equal(boundary.events[0].kind, KIND_RESET)
+})
+
 test('窗口重置: resetNotice 关闭时不产生 reset 事件但仍重建基线并重新武装', () => {
   // Given 阈值 90 已触发, 重置通知关闭
   const rule = { quotaThresholdPct: 90, balanceThreshold: null, resetNotice: false }