@mzzsfy/dsh-usage-panel 0.4.3

package/src/parsers.mjs

@@ -0,0 +1,327 @@
+// 用量面板纯解析层:各平台响应体 -> 归一化读数。
+// 只做数据变换,无 IO;host 半区直接 import 本模块。
+
+const QUOTA_PER_USD = 500000
+const PERCENT_BASE = 100
+
+function toStrictNumber(value) {
+  if (typeof value === 'number') return Number.isFinite(value) ? value : NaN
+  if (typeof value === 'string') {
+    const text = value.trim()
+    if (text.length > 0 && /^[+-]?(\d+(\.\d+)?|\.\d+)([eE][+-]?\d+)?$/.test(text)) return Number(text)
+    return NaN
+  }
+  return NaN
+}
+
+// 只读自有属性,阻断 __proto__/constructor 原型链逃逸。
+function getPath(root, path) {
+  if (typeof path !== 'string' || path.length === 0) return undefined
+  let current = root
+  for (const segment of path.split('.')) {
+    if (current === null || current === undefined || typeof current !== 'object') return undefined
+    if (!Object.hasOwn(current, segment)) return undefined
+    current = current[segment]
+  }
+  return current
+}
+
+function extractByRule(data, rule) {
+  if (rule === null || rule === undefined) return null
+  if (typeof rule === 'number' && Number.isFinite(rule)) return rule
+  if (typeof rule === 'string') {
+    const value = getPath(data, rule)
+    const num = toStrictNumber(value)
+    if (Number.isFinite(num)) return num
+    return typeof value === 'string' ? value : null
+  }
+  if (typeof rule === 'object' && !Array.isArray(rule)) {
+    if (rule.op === 'subtract' && Array.isArray(rule.paths)) {
+      if (rule.paths.length === 0) return null
+      const values = rule.paths.map((path) => toStrictNumber(getPath(data, path)))
+      if (!values.every(Number.isFinite)) return null
+      return values.reduce((acc, value) => acc - value)
+    }
+    if (rule.op === 'add' && Array.isArray(rule.paths)) {
+      const values = rule.paths.map((path) => toStrictNumber(getPath(data, path)))
+      if (!values.every(Number.isFinite)) return null
+      return values.reduce((acc, value) => acc + value, 0)
+    }
+    if (rule.op === 'divide' && typeof rule.path === 'string') {
+      const value = toStrictNumber(getPath(data, rule.path))
+      const by = toStrictNumber(rule.by)
+      if (!Number.isFinite(value) || !Number.isFinite(by) || by === 0) return null
+      return value / by
+    }
+    if (typeof rule.path === 'string') return extractByRule(data, rule.path)
+  }
+  return null
+}
+
+function requireOk(condition, message) {
+  if (!condition) throw new Error(message)
+}
+
+// limit/remaining 三元组 -> 已用百分比口径(对齐 cc-switch)。
+function makeTier(limitRaw, remainingRaw, resetsAt) {
+  const limit = toStrictNumber(limitRaw)
+  const remaining = toStrictNumber(remainingRaw)
+  const used = Number.isFinite(limit) && Number.isFinite(remaining) ? Math.max(limit - remaining, 0) : null
+  const utilization =
+    Number.isFinite(limit) && limit > 0 && used !== null ? (used / limit) * PERCENT_BASE : null
+  return { limit, remaining, used, utilization, resetsAt: typeof resetsAt === 'string' ? resetsAt : null }
+}
+
+function balanceEntry(currency, total, isAvailable, info) {
+  const numOrNull = (value) => {
+    const parsed = toStrictNumber(value)
+    return Number.isFinite(parsed) ? parsed : null
+  }
+  return {
+    currency,
+    total,
+    granted: numOrNull(info && info.granted_balance),
+    toppedUp: numOrNull(info && info.topped_up_balance),
+    isAvailable,
+  }
+}
+
+function parseDeepSeek(body) {
+  const error = body && body.error
+  if (error) {
+    throw new Error(String((error && error.message) || (error && error.type) || '接口返回错误'))
+  }
+  const infos = body && Array.isArray(body.balance_infos) ? body.balance_infos : null
+  requireOk(infos !== null, '响应缺少 balance_infos 字段')
+  const isAvailable = body.is_available !== false
+  return {
+    kind: 'balance',
+    entries: infos.map((info) =>
+      balanceEntry(String((info && info.currency) || 'CNY'), toStrictNumber(info && info.total_balance), isAvailable, info),
+    ),
+  }
+}
+
+function parseOpenRouter(body) {
+  const data = body && body.data
+  requireOk(data !== null && typeof data === 'object', '响应缺少 data 字段')
+  const total = toStrictNumber(data.total_credits)
+  const used = toStrictNumber(data.total_usage)
+  requireOk(Number.isFinite(total) || Number.isFinite(used), '响应缺少 total_credits/total_usage 字段')
+  return {
+    kind: 'balance',
+    entries: [
+      {
+        currency: 'USD',
+        total: Number.isFinite(total) ? total : null,
+        used: Number.isFinite(used) ? used : null,
+        remaining:
+          Number.isFinite(total) && Number.isFinite(used) ? Math.max(total - used, 0) : null,
+      },
+    ],
+  }
+}
+
+function parseKimi(body) {
+  const firstLimit = body && Array.isArray(body.limits) && body.limits.length ? body.limits[0] : null
+  const detail = firstLimit && firstLimit.detail ? firstLimit.detail : null
+  const usage = body && body.usage ? body.usage : null
+  requireOk(detail !== null || usage !== null, '响应缺少 usage/limits 字段')
+  const windows = []
+  if (detail) windows.push({ label: '5小时', ...makeTier(detail.limit, detail.remaining, detail.resetTime) })
+  if (usage) windows.push({ label: '7天', ...makeTier(usage.limit, usage.remaining, usage.resetTime) })
+  const level = body && body.user && body.user.membership && body.user.membership.level
+  return { kind: 'quota', windows, membership: typeof level === 'string' ? level : null }
+}
+
+// unit=3 -> 5小时窗,unit=6 -> 7天窗;未分类按重置时间升序回填空缺槽位。
+// TOKENS_LIMIT(token 窗口)与 CREDIT_LIMIT(Credit 计费窗口,Pro/Lite 套餐)语义一致,一并接受。
+function parseZhipu(body) {
+  if (body && body.success === false) {
+    throw new Error(String((body && body.msg) || '接口返回错误'))
+  }
+  const limits = body && body.data && Array.isArray(body.data.limits) ? body.data.limits : null
+  requireOk(limits !== null, '响应缺少 data.limits 字段')
+  const unclassified = []
+  let fiveHour = null
+  let weekly = null
+  let prompts = null
+  const seenTypes = []
+  for (const item of limits) {
+    if (!item || typeof item !== 'object') continue
+    if (seenTypes.indexOf(item.type) < 0) seenTypes.push(String(item.type))
+    const type = typeof item.type === 'string' ? item.type.toLowerCase() : ''
+    if (type === 'time_limit') {
+      // 工具用量窗口:currentValue/remaining 为调用次数,usageDetails 为按工具的次数明细
+      if (prompts === null) {
+        const details = Array.isArray(item.usageDetails)
+          ? item.usageDetails
+              .filter((d) => d && typeof d.modelCode === 'string' && Number.isFinite(toStrictNumber(d.usage)))
+              .map((d) => ({ model: d.modelCode, usage: toStrictNumber(d.usage) }))
+          : []
+        prompts = {
+          label: '工具用量',
+          utilization: zhipuPercent(item),
+          remaining: orNull(toStrictNumber(item.remaining)),
+          limit: orNull(toStrictNumber(item.usage)),
+          resetsAt: Number.isFinite(toStrictNumber(item.nextResetTime))
+            ? new Date(toStrictNumber(item.nextResetTime)).toISOString()
+            : null,
+          details,
+        }
+      }
+      continue
+    }
+    if (type !== 'tokens_limit' && type !== 'credit_limit') continue
+    const resetMs = toStrictNumber(item.nextResetTime)
+    const entry = {
+      label: '',
+      utilization: zhipuPercent(item),
+      remaining: orNull(toStrictNumber(item.remaining)),
+      limit: orNull(toStrictNumber(item.usage)),
+      resetsAt: Number.isFinite(resetMs) ? new Date(resetMs).toISOString() : null,
+    }
+    const unit = toStrictNumber(item.unit)
+    if (unit === 3 && fiveHour === null) fiveHour = entry
+    else if (unit === 6 && weekly === null) weekly = entry
+    else unclassified.push(entry)
+  }
+  unclassified.sort((a, b) => {
+    const at = a.resetsAt ? Date.parse(a.resetsAt) : Infinity
+    const bt = b.resetsAt ? Date.parse(b.resetsAt) : Infinity
+    return at - bt
+  })
+  for (const entry of unclassified) {
+    if (fiveHour === null) fiveHour = entry
+    else if (weekly === null) weekly = entry
+  }
+  requireOk(
+    fiveHour !== null || weekly !== null,
+    '响应缺少可解析的额度窗口,见到的类型: ' + (seenTypes.join(', ') || '无'),
+  )
+  const windows = []
+  if (fiveHour !== null) windows.push({ ...fiveHour, label: '5小时' })
+  if (weekly !== null) windows.push({ ...weekly, label: '7天' })
+  if (prompts !== null) windows.push(prompts)
+  const level = body && body.data && body.data.level
+  return { kind: 'quota', windows, level: typeof level === 'string' ? level : null }
+}
+
+// 已用百分比:percentage 优先;缺失时 currentValue/usage 反推;均无效为 null。
+function zhipuPercent(item) {
+  const percentage = toStrictNumber(item.percentage)
+  if (Number.isFinite(percentage)) return percentage
+  const current = toStrictNumber(item.currentValue)
+  const usage = toStrictNumber(item.usage)
+  if (Number.isFinite(current) && Number.isFinite(usage) && usage > 0) {
+    return (current / usage) * PERCENT_BASE
+  }
+  return null
+}
+
+function orNull(value) {
+  return Number.isFinite(value) ? value : null
+}
+
+function parseMiniMax(body) {
+  const baseResp = body && body.base_resp
+  const statusCode = baseResp ? toStrictNumber(baseResp.status_code) : NaN
+  if (baseResp && statusCode !== 0) {
+    throw new Error(String(baseResp.status_msg || '接口返回错误'))
+  }
+  const remains = body && Array.isArray(body.model_remains) ? body.model_remains : []
+  const item = remains.find((m) => m && m.model_name === 'general')
+  requireOk(item !== undefined, '响应缺少 general 条目')
+  const windows = []
+  const intervalRemain = toStrictNumber(item.current_interval_remaining_percent)
+  const endMs = toStrictNumber(item.end_time)
+  if (Number.isFinite(intervalRemain)) {
+    windows.push({
+      label: '5小时',
+      utilization: PERCENT_BASE - intervalRemain,
+      resetsAt: Number.isFinite(endMs) ? new Date(endMs).toISOString() : null,
+    })
+  }
+  if (toStrictNumber(item.current_weekly_status) === 1) {
+    const weeklyRemain = toStrictNumber(item.current_weekly_remaining_percent)
+    const weeklyEndMs = toStrictNumber(item.weekly_end_time)
+    if (Number.isFinite(weeklyRemain)) {
+      windows.push({
+        label: '7天',
+        utilization: PERCENT_BASE - weeklyRemain,
+        resetsAt: Number.isFinite(weeklyEndMs) ? new Date(weeklyEndMs).toISOString() : null,
+      })
+    }
+  }
+  requireOk(windows.length > 0, '响应缺少用量窗口字段')
+  return { kind: 'quota', windows }
+}
+
+function parseNewApi(body) {
+  if (body && typeof body.message === 'string' && body.code !== 200) {
+    throw new Error(body.message)
+  }
+  const data = body && body.data
+  requireOk(data !== null && typeof data === 'object', '响应缺少 data 字段')
+  if (data.unlimited_quota === true) {
+    throw new Error('无限额度 token 无 total_available,无法读取剩余')
+  }
+  const total = toStrictNumber(data.total_granted)
+  const used = toStrictNumber(data.total_used)
+  const remaining = toStrictNumber(data.total_available)
+  requireOk(
+    Number.isFinite(total) || Number.isFinite(remaining),
+    '响应缺少 total_granted/total_available 字段',
+  )
+  return {
+    kind: 'balance',
+    entries: [
+      {
+        currency: 'USD',
+        total: Number.isFinite(total) ? total / QUOTA_PER_USD : null,
+        used: Number.isFinite(used) ? used / QUOTA_PER_USD : null,
+        remaining: Number.isFinite(remaining) ? remaining / QUOTA_PER_USD : null,
+      },
+    ],
+  }
+}
+
+function extractCustom(data, extract) {
+  const remaining = extractByRule(data, extract && extract.remaining)
+  requireOk(remaining !== null && Number.isFinite(Number(remaining)), 'extract.remaining 缺失或非数值')
+  const num = (value) => {
+    // 规则解析失败(extractByRule 回 null)保持 null 语义,与真值 0 可区分
+    if (value === null || value === undefined) return null
+    const parsed = Number(value)
+    return Number.isFinite(parsed) ? parsed : null
+  }
+  const maxBudget = extract && extract.maxBudget !== undefined ? num(extractByRule(data, extract.maxBudget)) : null
+  const spend = extract && extract.spend !== undefined ? num(extractByRule(data, extract.spend)) : null
+  const unit =
+    extract && typeof extract.unit === 'string' && extract.unit.length > 0 ? extract.unit : 'USD'
+  // 与 balance 读数联合形态对齐:kind 判别使历史采样 / 通知评估 / 渲染三链路直接生效
+  return {
+    kind: 'balance',
+    entries: [
+      {
+        currency: unit,
+        remaining: Number(remaining),
+        total: maxBudget,
+        used: spend,
+      },
+    ],
+  }
+}
+
+export {
+  toStrictNumber,
+  getPath,
+  extractByRule,
+  parseDeepSeek,
+  parseOpenRouter,
+  parseKimi,
+  parseZhipu,
+  parseMiniMax,
+  parseNewApi,
+  extractCustom,
+}

package/src/poller.mjs

@@ -0,0 +1,60 @@
+// 轮询纯逻辑层:时间驱动调度 / 失败指数退避 / 档位间隔。无 IO,host 半区与单测共用。
+// 历史教训:旧 round 分频形态(round 仅在查询时递增)构成死锁——余额类账号首查后
+// round 恒 1 永不再查;短窗账号每 tick 必查使用户间隔设置完全失效。改为时间驱动:
+// 上次尝试查询时刻(成功失败均记)+ 档位间隔判定到点,退避独立叠加。
+
+export const BACKOFF_CAP_MULTIPLE = 8
+// 短窗口档(5h 序列)查询间隔 = 序列快照粒度(history.mjs GRANULARITY_MS['10m'])
+export const SHORT_TIER_INTERVAL_SEC = 10 * 60
+// 长窗口档(日/月/余额序列)查询间隔 = 序列快照粒度(history.mjs GRANULARITY_MS['1h'])
+export const LONG_TIER_INTERVAL_SEC = 60 * 60
+
+// 失败退避状态机:基期 = 账号档位间隔,×2 封顶;成功即恢复。
+export function createBackoff({ baseSec }) {
+  let failures = 0
+  let nextRetryAt = null
+  return {
+    get nextRetryAt() {
+      return nextRetryAt
+    },
+    onFailure(nowSec) {
+      failures += 1
+      const delaySec = baseSec * Math.pow(2, Math.min(failures - 1, Math.log2(BACKOFF_CAP_MULTIPLE)))
+      nextRetryAt = nowSec + delaySec
+    },
+    onSuccess() {
+      failures = 0
+      nextRetryAt = null
+    },
+    isBlocked(nowSec) {
+      return nextRetryAt !== null && nowSec < nextRetryAt
+    },
+  }
+}
+
+// 短窗口档账号判定:从未查询成功(含最近一次失败)或最近成功读数含短窗序列。
+// 失败归短档:保持 10 分钟调度节奏与 600s 退避基期,避免一次瞬时失败把含 5h
+// 窗口的账号塌缩到 1 小时档,造成短窗序列长时间空洞;轰炸由退避指数压制。
+export function isShortWindowTier(last, readingHasShort) {
+  if (last === null) return true
+  return last.ok !== true || readingHasShort
+}
+
+// 账号档位间隔:含短窗口序列走短档,否则长档。
+export function tierIntervalSec(hasShortWindow) {
+  return hasShortWindow ? SHORT_TIER_INTERVAL_SEC : LONG_TIER_INTERVAL_SEC
+}
+
+// 上次尝试查询时刻(秒):queriedAt 毫秒历元;缺失/非法(旧数据)回 null 视为立即到点。
+export function lastQuerySecOf(last) {
+  const queriedAt = last !== null && typeof last === 'object' ? last.queriedAt : undefined
+  return typeof queriedAt === 'number' && Number.isFinite(queriedAt)
+    ? Math.floor(queriedAt / 1000)
+    : null
+}
+
+// 时间驱动到点判定:lastQuerySec 为 null(从未查询或旧数据缺时刻)即到点。
+export function isDue({ lastQuerySec, nowSec, intervalSec }) {
+  if (lastQuerySec === null) return true
+  return nowSec - lastQuerySec >= intervalSec
+}

package/test/client-id.test.mjs

@@ -0,0 +1,16 @@
+// client.js 注册 id 守卫:loader 按 graph row id(完整包名)匹配注册,短名即加载失败。
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import test from 'node:test'
+import assert from 'node:assert/strict'
+
+const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..')
+const { name } = JSON.parse(readFileSync(join(PKG_ROOT, 'package.json'), 'utf8'))
+
+test('client.js 注册 id 为完整包名', () => {
+  const source = readFileSync(join(PKG_ROOT, 'src', 'client.js'), 'utf8')
+  const match = source.match(/__ModuleLoader__\.load\(\{\s*id:\s*'([^']+)'/)
+  assert.ok(match, 'client.js 缺少 __ModuleLoader__.load 注册')
+  assert.equal(match[1], name)
+})

package/test/history.test.mjs

@@ -0,0 +1,170 @@
+// 历史快照纯逻辑 BDD:序列键映射 / 档位对齐去重 / 时间修剪 / 硬上限 / 月窗口聚合 / 读数取样。
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import {
+  SEQUENCE_TIERS,
+  GRANULARITY_MS,
+  RETENTION_POINTS,
+  HARD_POINT_CAP,
+  labelToSuffix,
+  granularityOf,
+  alignTs,
+  appendPoint,
+  pruneSequence,
+  readingToSnapshots,
+  buildMonthSequence,
+  newSequenceStore,
+} from '../src/history.mjs'
+
+const MIN = 60 * 1000
+const TEN_MIN = 10 * MIN
+const HOUR = 60 * MIN
+
+test('场景: 窗口 label 与序列键后缀映射', () => {
+  assert.equal(labelToSuffix('5小时'), '5h')
+  assert.equal(labelToSuffix('7天'), '7d')
+  assert.equal(labelToSuffix('月'), 'month')
+  assert.equal(labelToSuffix('未知窗口'), null)
+})
+
+test('场景: 序列档位映射', () => {
+  assert.equal(granularityOf('5h'), '10m')
+  assert.equal(granularityOf('7d'), '1h')
+  assert.equal(granularityOf('month'), '1h')
+  assert.equal(granularityOf('balance'), '1h')
+  assert.equal(Object.keys(SEQUENCE_TIERS).length, 4)
+})
+
+test('场景: 时间就近对齐到最近档', () => {
+  assert.equal(alignTs(Date.UTC(2026, 0, 1, 10, 7), TEN_MIN), Date.UTC(2026, 0, 1, 10, 10))
+  assert.equal(alignTs(Date.UTC(2026, 0, 1, 10, 0), TEN_MIN), Date.UTC(2026, 0, 1, 10, 0))
+  assert.equal(alignTs(Date.UTC(2026, 0, 1, 14, 5), HOUR), Date.UTC(2026, 0, 1, 14, 0))
+})
+
+test('场景: 短窗口 10 分钟档采样并记录档内最前一次', () => {
+  const store = newSequenceStore()
+  const seqKey = 'acct-1:5h'
+  appendPoint(store, seqKey, Date.UTC(2026, 0, 1, 10, 7), 80)
+  appendPoint(store, seqKey, Date.UTC(2026, 0, 1, 10, 14), 70)
+  const points = store[seqKey].points
+  assert.equal(points.length, 1)
+  assert.equal(points[0].t, Date.UTC(2026, 0, 1, 10, 10))
+  assert.equal(points[0].v, 80, '档内只保留最前一次的值')
+})
+
+test('场景: 跨档落新点', () => {
+  const store = newSequenceStore()
+  const seqKey = 'acct-1:5h'
+  appendPoint(store, seqKey, Date.UTC(2026, 0, 1, 10, 10), 80)
+  appendPoint(store, seqKey, Date.UTC(2026, 0, 1, 10, 21), 70)
+  const points = store[seqKey].points
+  assert.equal(points.length, 2)
+  assert.equal(points[1].t, Date.UTC(2026, 0, 1, 10, 20))
+  assert.equal(points[1].v, 70)
+})
+
+test('场景: 超期快照修剪', () => {
+  const store = newSequenceStore()
+  const seqKey = 'acct-1:5h'
+  const oldT = Date.UTC(2026, 0, 1, 10, 0)
+  const newT = oldT + RETENTION_POINTS['10m'] * TEN_MIN + TEN_MIN
+  store[seqKey] = { granularity: '10m', points: [{ t: oldT, v: 1 }, { t: newT, v: 2 }] }
+  pruneSequence(store, seqKey, newT)
+  assert.equal(store[seqKey].points.length, 1)
+  assert.equal(store[seqKey].points[0].v, 2)
+})
+
+test('场景: 硬点数上限丢最旧', () => {
+  const store = newSequenceStore()
+  const seqKey = 'acct-1:balance'
+  const start = Date.UTC(2026, 0, 1, 0, 0)
+  const cap = HARD_POINT_CAP['1h']
+  // 直接构造超上限序列:异常高频写入场景,正常轮询由时间修剪收敛
+  store[seqKey] = {
+    granularity: '1h',
+    points: Array.from({ length: cap + 1 }, (_, i) => ({ t: start + i * 10 * 1000, v: i })),
+  }
+  appendPoint(store, seqKey, start + (cap + 1) * 10 * 1000, cap + 1, start + (cap + 1) * 10 * 1000)
+  assert.equal(store[seqKey].points.length, cap, '序列长度不超上限')
+  assert.equal(store[seqKey].points[0].v, 1, '最旧点被丢弃')
+})
+
+test('场景: 追加快照时先时间修剪后点数上限', () => {
+  const store = newSequenceStore()
+  const seqKey = 'acct-1:5h'
+  const start = Date.UTC(2026, 0, 1, 0, 0)
+  const cap = HARD_POINT_CAP['10m']
+  const retentionMs = RETENTION_POINTS['10m'] * GRANULARITY_MS['10m']
+  // 构造留存期内的超上限序列(高频异常),验证修剪后仍受硬上限约束
+  store[seqKey] = {
+    granularity: '10m',
+    points: Array.from({ length: cap + 1 }, (_, i) => ({ t: start + i * 30 * 1000, v: i })),
+  }
+  appendPoint(store, seqKey, start + retentionMs, 999, start + retentionMs)
+  const points = store[seqKey].points
+  assert.ok(points.length <= cap)
+  assert.equal(points[points.length - 1].v, 999)
+  assert.ok(points.every((p) => p.t >= start + retentionMs - retentionMs), '全部点在留存期内')
+})
+
+test('场景: 读数取样产出序列键与数值', () => {
+  const quota = {
+    kind: 'quota',
+    windows: [
+      { label: '5小时', remaining: 30, utilization: 70 },
+      { label: '7天', remaining: null, utilization: 40 },
+    ],
+  }
+  const snaps = readingToSnapshots(quota)
+  assert.deepEqual(snaps, [
+    { suffix: '5h', value: 30, tier: '10m' },
+    { suffix: '7d', value: 40, tier: '1h' },
+  ])
+  const balance = { kind: 'balance', entries: [{ currency: 'USD', remaining: 12.5, total: 20 }] }
+  assert.deepEqual(readingToSnapshots(balance), [{ suffix: 'balance', value: 12.5, tier: '1h' }])
+  const balanceTotalOnly = { kind: 'balance', entries: [{ currency: 'CNY', remaining: null, total: 88 }] }
+  assert.deepEqual(readingToSnapshots(balanceTotalOnly), [{ suffix: 'balance', value: 88, tier: '1h' }])
+})
+
+test('场景: 月窗口按余额快照聚合当月日历月', () => {
+  const store = newSequenceStore()
+  appendPoint(store, 'acct-1:balance', Date.UTC(2026, 0, 3, 0, 0), 100)
+  appendPoint(store, 'acct-1:balance', Date.UTC(2026, 0, 5, 0, 0), 80)
+  appendPoint(store, 'acct-1:balance', Date.UTC(2025, 11, 20, 0, 0), 150)
+  const now = Date.UTC(2026, 0, 6, 0, 0)
+  buildMonthSequence(store, 'acct-1', now)
+  const month = store['acct-1:month']
+  assert.ok(month)
+  assert.equal(month.granularity, '1h')
+  assert.deepEqual(month.points, [
+    { t: Date.UTC(2026, 0, 3, 0, 0), v: 100 },
+    { t: Date.UTC(2026, 0, 5, 0, 0), v: 80 },
+  ], '仅保留当月日历月的余额点,跨月点剔除')
+})
+
+test('场景: 月窗口档内对齐去重与留存同规则', () => {
+  const store = newSequenceStore()
+  appendPoint(store, 'acct-1:balance', Date.UTC(2026, 0, 3, 0, 30), 100)
+  const now = Date.UTC(2026, 0, 4, 0, 0)
+  buildMonthSequence(store, 'acct-1', now)
+  assert.deepEqual(store['acct-1:month'].points, [{ t: Date.UTC(2026, 0, 3, 1, 0), v: 100 }])
+})
+
+test('场景: 月窗口月界取本地时区月初零点,跨月点剔除', () => {
+  const store = newSequenceStore()
+  const monthStart = new Date(2026, 2, 1).getTime()
+  const beforeMonth = monthStart - HOUR
+  appendPoint(store, 'acct-1:balance', beforeMonth, 10)
+  appendPoint(store, 'acct-1:balance', monthStart, 20)
+  buildMonthSequence(store, 'acct-1', monthStart + HOUR)
+  assert.deepEqual(store['acct-1:month'].points, [{ t: monthStart, v: 20 }], '上月末尾点不进本月窗口')
+})
+
+test('场景: 粒度毫秒与留存点数表', () => {
+  assert.equal(GRANULARITY_MS['10m'], 10 * MIN)
+  assert.equal(GRANULARITY_MS['1h'], HOUR)
+  assert.equal(RETENTION_POINTS['10m'], 7 * 24 * 6)
+  assert.equal(RETENTION_POINTS['1h'], 30 * 24)
+  assert.equal(HARD_POINT_CAP['10m'], 2 * 7 * 24 * 6)
+  assert.equal(HARD_POINT_CAP['1h'], 2 * 30 * 24)
+})

package/test/historyStore.test.mjs

@@ -0,0 +1,107 @@
+// 历史文件持久化守卫 BDD:坏文件备份与写入拒绝、恢复解除损坏标记。真实 fs + 临时目录。
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { createHistoryStore, HISTORY_BROKEN_MESSAGE } from '../src/historyStore.mjs'
+
+test('场景: 坏 JSON 注入触发落盘保护,坏文件备份为 .bak 且 persist 拒绝写入', async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'usage-panel-history-'))
+  const file = join(dir, 'history.json')
+  try {
+    await writeFile(file, '{broken json', 'utf8')
+    const store = createHistoryStore({ file })
+    await store.ensure()
+    assert.equal(store.broken, true)
+    await assert.rejects(store.persist(), (error) => error.message === HISTORY_BROKEN_MESSAGE)
+    const backup = await readFile(file + '.bak', 'utf8')
+    assert.equal(backup, '{broken json', '坏文件完整保留在备份中')
+    await assert.rejects(readFile(file, 'utf8'), (error) => error.code === 'ENOENT', '原坏文件已被移走')
+  } finally {
+    await rm(dir, { recursive: true, force: true })
+  }
+})
+
+test('场景: 备份后重读成功解除损坏标记,写入恢复', async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'usage-panel-history-'))
+  const file = join(dir, 'history.json')
+  try {
+    await writeFile(file, 'not json', 'utf8')
+    const store = createHistoryStore({ file })
+    await store.ensure()
+    assert.equal(store.broken, true)
+    await store.ensure()
+    assert.equal(store.broken, false, '坏文件已备份,重读 ENOENT 视为恢复')
+    store.sequences['acct-1:balance'] = { granularity: '1h', points: [] }
+    await store.persist()
+    const saved = JSON.parse(await readFile(file, 'utf8'))
+    assert.ok(saved.sequences['acct-1:balance'])
+  } finally {
+    await rm(dir, { recursive: true, force: true })
+  }
+})
+
+test('场景: 文件不存在视为首次使用,不标记损坏', async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'usage-panel-history-'))
+  const file = join(dir, 'history.json')
+  try {
+    const store = createHistoryStore({ file })
+    await store.ensure()
+    assert.equal(store.broken, false)
+    await store.persist()
+    assert.ok(JSON.parse(await readFile(file, 'utf8')).sequences)
+  } finally {
+    await rm(dir, { recursive: true, force: true })
+  }
+})
+
+test('场景: 写链毒化防护——单次写入失败不永久断写', async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'usage-panel-history-'))
+  const file = join(dir, 'history.json')
+  const writes = []
+  try {
+    const store = createHistoryStore({
+      file,
+      io: {
+        mkdir: async () => {},
+        readFile: async () => { const e = new Error('no'); e.code = 'ENOENT'; throw e },
+        rename: async () => {},
+        // 首次写失败(模拟瞬时 ENOSPC/占用),之后成功;写入内容记录供断言
+        writeFile: (() => {
+          let calls = 0
+          return async (_file, text) => {
+            calls += 1
+            if (calls === 1) throw new Error('ENOSPC')
+            writes.push(text)
+          }
+        })(),
+      },
+    })
+    await store.ensure()
+    store.sequences['a:balance'] = { granularity: '1h', points: [] }
+    await assert.rejects(store.persist(), /ENOSPC/, '调用方感知单次失败')
+    store.sequences['b:balance'] = { granularity: '1h', points: [] }
+    await store.persist()
+    // 后续写入不受毒化链影响,内容含两次写入的全部序列
+    assert.equal(writes.length, 1)
+    const saved = JSON.parse(writes[0])
+    assert.ok(saved.sequences['a:balance'] && saved.sequences['b:balance'])
+  } finally {
+    await rm(dir, { recursive: true, force: true })
+  }
+})
+
+test('场景: 落盘为紧凑 JSON(无缩进)', async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'usage-panel-history-'))
+  const file = join(dir, 'history.json')
+  try {
+    const store = createHistoryStore({ file })
+    await store.ensure()
+    await store.persist()
+    const text = await readFile(file, 'utf8')
+    assert.equal(text, JSON.stringify({ sequences: {} }), '序列化无第三参缩进')
+  } finally {
+    await rm(dir, { recursive: true, force: true })
+  }
+})