dsh-whale-widget 0.3.0 → 0.3.1

package/lib/index.js

@@ -3,6 +3,11 @@ import os from 'node:os'
 import path from 'node:path'
 import dns from 'node:dns'
 import { fileURLToPath } from 'node:url'
+import { createHash } from 'node:crypto'
+import {
+  preciseMoney, addMoney, sumMoney, beijingDay, dayOffset,
+  observeBalance, balanceSummary, daySummary, accountingDays, reconcileBalance,
+} from './accounting.mjs'
 
 // Node 的 fetch(undici) 可能优先 IPv6：个别域名(如 open.bigmodel.cn)有 AAAA 记录但本机 IPv6 不通，
 // 会直接报 "fetch failed"（curl 会自动回退 IPv4，所以看起来正常）。统一改为 IPv4 优先。
@@ -179,6 +184,24 @@ const API_TEMPLATES = {
     },
     probeUrl: 'https://api.minimaxi.com/v1/api/openplatform/coding_plan/remains',
   },
+  // OpenCode Go（订阅）：一次返回 rolling / weekly / monthly 三个窗口，值为「已用% + 重置时间」
+  // （usage.rolling|weekly|monthly.{percent,resetsAt}）。走多窗口路径 json.windows，见 fetchModelQuota。
+  // 鉴权只需 Authorization: Bearer <key>（2026-09 实测：x-api-key 单独使用返回 401，无需额外请求头）。
+  opencode_go: {
+    name: 'OpenCode Go（订阅）', currency: 'USD', keyRef: 'OPENCODE_GO_API_KEY', kind: 'quota',
+    quota: {
+      url: 'https://opencode.ai/zen/go/v1/usage',
+      auth: 'Bearer {key}',
+      json: {
+        windows: [
+          { key: 'rolling', label: '5h', percent: 'usage.rolling.percent', resetAt: 'usage.rolling.resetsAt' },
+          { key: 'weekly', label: '周', percent: 'usage.weekly.percent', resetAt: 'usage.weekly.resetsAt' },
+          { key: 'monthly', label: '月', percent: 'usage.monthly.percent', resetAt: 'usage.monthly.resetsAt' },
+        ],
+      },
+    },
+    probeUrl: 'https://opencode.ai/zen/go/v1/usage',
+  },
   openai_compat: {
     name: 'OpenAI 兼容中转站', currency: 'USD', keyRef: 'CUSTOM_API_KEY', needsBaseUrl: true,
     // OneAPI / New API 一类网关的经典账单接口：额度(美元) + 已用(美分)
@@ -611,13 +634,10 @@ export default {
         const input = Number(usage.inputTokens) || 0
         const cache = Number(usage.cacheReadTokens) || 0
         const output = Number(usage.outputTokens) || 0
-        const reasoning = Number(usage.reasoningTokens) || 0
         // 口径修正（issue #89 / PR #83）：dsh 保证 reasoningTokens ⊆ outputTokens
         // （见 dsh-token-meter 的校验 reasoningTokens > outputTokens 即判非法），
         // 所以 reasoning 不能再单独累加 —— 否则输出侧按输出价被重复计费（实测偏高约一倍）。
-        // 兜底：万一某 provider 上报的 reasoning 不是 output 的子集（reasoning > output），
-        // 就把差额补回计费输出，避免另一种口径下少算
-        const outputBilled = reasoning > output ? output + reasoning : output
+        const outputBilled = output // DSH outputTokens already includes reasoningTokens.
         const toks = input + cache + outputBilled
         agg.tokens += toks
         // 定价换算（CNY/百万 token；缓存命中=输入价，其余按各自档位），并按模型拆分
@@ -632,9 +652,9 @@ export default {
           const meta = customPriceMetaFor(model)
           if (meta && meta.cur === 'USD' && Number(meta.rate) > 0) costMsg = costMsg * Number(meta.rate)
         } catch (err) {}
-        agg.cost += costMsg
+        agg.cost = addMoney(agg.cost, costMsg)
         if (model) {
-          agg.byModel[model] = (agg.byModel[model] || 0) + costMsg
+          agg.byModel[model] = addMoney(agg.byModel[model] || 0, costMsg)
           agg.byModelTokens[model] = (agg.byModelTokens[model] || 0) + toks
         }
         agg.lastTs = Date.now()
@@ -726,12 +746,13 @@ export default {
           return { ok: false, code: 'PARSE', error: '余额接口返回不是合法 JSON' }
         }
         const info = pickBalanceInfo(data && data.balance_infos)
-        if (!info || info.total_balance === undefined) {
+        if (!info || info.total_balance === undefined || !Number.isFinite(Number(info.total_balance))) {
           return { ok: false, code: 'SHAPE', error: '余额接口返回结构异常' }
         }
         return {
           ok: true,
           totalBalance: Number(info.total_balance),
+          accountTag: createHash('sha256').update(String(cred.value)).digest('hex').slice(0, 24),
           currency: String(info.currency || 'CNY'),
           updatedAt: new Date().toISOString(),
         }
@@ -745,27 +766,46 @@ export default {
       }
     }
 
-    function todayKey() {
-      const d = new Date()
-      const p = (n) => String(n).padStart(2, '0')
-      return d.getFullYear() + '-' + p(d.getMonth() + 1) + '-' + p(d.getDate())
+    function todayKey() { return beijingDay() }
+    // Windows indexers can briefly hold a just-written file. Retry sharing
+    // conflicts; never treat an unreadable existing ledger as an empty ledger.
+    function ledgerIo(operation) {
+      for (let attempt = 0; ; attempt++) {
+        try { return operation() } catch (err) {
+          if (attempt >= 5 || !['EBUSY', 'EPERM', 'EACCES'].includes(err.code)) throw err
+          Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 20 * (attempt + 1))
+        }
+      }
     }
     function readUsageLedger() {
       for (const p of USAGE_FILE_CANDIDATES) {
         try {
-          const parsed = JSON.parse(fs.readFileSync(p, 'utf8'))
+          const parsed = JSON.parse(ledgerIo(() => fs.readFileSync(p, 'utf8')))
           if (parsed && typeof parsed === 'object' && typeof parsed.date === 'string') return parsed
-        } catch (err) {}
+          throw new Error('账本结构异常，已停止写入以保护原记录')
+        } catch (err) { if (err.code !== 'ENOENT') throw err }
       }
       return { date: todayKey(), lastBalance: null, todayUsage: 0, history: {} }
     }
     function writeUsageLedger(led) {
       const body = JSON.stringify(led)
       for (const p of USAGE_FILE_CANDIDATES) {
+        const temp = p + '.tmp-' + process.pid
         try {
-          fs.writeFileSync(p, body, 'utf8')
+          if (fs.existsSync(p)) {
+            const existing = JSON.parse(ledgerIo(() => fs.readFileSync(p, 'utf8')))
+            if (!existing.accounting || existing.accounting.version !== 1) {
+              try { ledgerIo(() => fs.copyFileSync(p, p + '.before-recharge-fix.bak', fs.constants.COPYFILE_EXCL)) }
+              catch (err) { if (err.code !== 'EEXIST') throw err }
+            }
+          }
+          ledgerIo(() => fs.writeFileSync(temp, body, 'utf8'))
+          ledgerIo(() => fs.renameSync(temp, p))
           return true
-        } catch (err) {}
+        } catch (err) {
+          try { if (fs.existsSync(temp)) fs.unlinkSync(temp) } catch (cleanupErr) {}
+          if (err.code !== 'ENOENT') console.error('[whale-ledger] 账本保存失败:', err.code || err.message)
+        }
       }
       return false
     }
@@ -828,26 +868,18 @@ export default {
         return true
       } catch (err) { return false }
     }
-    function dayKeyOfDate(d) {
-      const p = (n) => String(n).padStart(2, '0')
-      return d.getFullYear() + '-' + p(d.getMonth() + 1) + '-' + p(d.getDate())
-    }
-    function dayKeyFromTs(ts) { return dayKeyOfDate(new Date(Number(ts))) }
-    function dayAdd(baseDayStr, delta) {
-      const d = new Date(baseDayStr + 'T00:00:00')
-      d.setDate(d.getDate() + delta)
-      return dayKeyOfDate(d)
-    }
-    function round2(x) { return Math.round((Number(x) || 0) * 100) / 100 }
+    function dayKeyOfDate(d) { return beijingDay(d.getTime()) }
+    function dayKeyFromTs(ts) { return beijingDay(Number(ts)) }
+    function dayAdd(baseDayStr, delta) { return dayOffset(baseDayStr, delta) }
     // 每轮结算后追加一条用量事件(模型明细/7天/全部记录的来源;上限 8000 条)
     function appendUsageEvent(ev) {
       const led = readUsageLedger()
       led.events = Array.isArray(led.events) ? led.events : []
       led.events.push({
         ts: Number(ev.ts) || Date.now(),
-        day: dayKeyFromTs(ev.ts),
+        day: dayKeyFromTs(Number(ev.ts) || Date.now()),
         model: String(ev.model || '未知'),
-        cost: round2(ev.cost),
+        cost: preciseMoney(Number(ev.cost) || 0),
         tokens: Math.round(Number(ev.tokens) || 0),
       })
       // 保留策略：events 90 天 / 最多 2 万条（超期或超量归档到 .dshw-usage-archive.json）
@@ -858,88 +890,38 @@ export default {
     function usageRecordsPayload() {
       const led = readUsageLedger()
       const events = Array.isArray(led.events) ? led.events : []
-      const history = led.history && typeof led.history === 'object' ? led.history : {}
-      const today = dayKeyFromTs(Date.now())
-      function sumEv(d) { let s = 0; for (const e of events) if (e.day === d) s += Number(e.cost) || 0; return s }
-      // 当日真实消费 = 零点起始余额 − 当前余额(官方按真实扣款计,事件漏记时用它兜底)
-      function realDelta() {
-        if (typeof led.dayStart === 'number' && typeof led.lastBalance === 'number') {
-          const d = led.dayStart - led.lastBalance
-          if (d > 0) return d
-        }
-        return 0
-      }
-      // 单日合计:事件合计优先,其次历史归档值;今天以真实余额差为准——
-      // 官方账单按真实扣款计,事件计价可能出现系统性偏高(如重复/口径差异),
-      // 而余额差(零点余额−当前余额)与官网几乎一致,故今日不再与事件取大。
-      function totalDay(d) {
-        if (d === today) {
-          const dd = realDelta()
-          if (dd > 0) return round2(dd)
-          // 余额差不可用(充值/退款/无基准)时退回事件/历史
-          let v = sumEv(d)
-          const h = history[d]
-          if (typeof h === 'number' && h > v) v = h
-          return round2(v)
-        }
-        let v = sumEv(d)
-        const h = history[d]
-        if (typeof h === 'number' && h > v) v = h
-        return round2(v)
-      }
-      function modelsFor(d) {
-        const map = {}
+      const today = todayKey()
+      function modelsFor(day) {
+        const map = new Map()
         for (const e of events) {
-          if (e.day !== d) continue
-          const k = e.model || '未知'
-          map[k] = (map[k] || 0) + (Number(e.cost) || 0)
-        }
-        const names = Object.keys(map).sort((a, b) => map[b] - map[a])
-        const tot = totalDay(d)
-        const evSum = names.reduce((s, k) => s + map[k], 0)
-        const arr = names.map((k) => ({ model: k, cost: map[k] }))
-        // 今天:模型明细需与合计一致——
-        // 事件合计 > 余额差(事件偏高)时按比例压缩到合计;
-        // 事件合计 < 合计(事件漏记/余额差兜底)时补一行「未入明细」。
-        if (d === today && evSum > 0.0001 && evSum > tot + 0.004) {
-          const k = tot / evSum
-          for (const it of arr) it.cost = round2(it.cost * k)
-          const now = arr.reduce((s, it) => s + it.cost, 0)
-          const diff = round2(tot - now)
-          if (Math.abs(diff) > 0.004) {
-            if (diff > 0) arr[0].cost = round2(arr[0].cost + diff)
-            else arr[0].cost = round2(Math.max(0, arr[0].cost + diff))
-          }
+          if (e.day !== day) continue
+          const name = String(e.model || '未知')
+          map.set(name, addMoney(map.get(name) || 0, Number(e.cost) || 0))
         }
-        arr.forEach((it) => { it.cost = round2(it.cost) })
-        // 今天若有“未入明细”的真实消费(事件漏记部分),补一行使合计对得上
-        if (d === today) {
-          const gap = tot - evSum
-          if (gap > 0.004) arr.push({ model: '(未入明细)', cost: round2(gap) })
+        return Array.from(map, ([model, cost]) => ({ model, cost, source: 'events', currency: 'CNY' }))
+          .sort((a, b) => b.cost - a.cost)
+      }
+      function forDay(date) {
+        const summary = daySummary(led, date)
+        const models = modelsFor(date)
+        return {
+          ...summary, date, total: summary.amount, models,
+          modelTotal: sumMoney(models.map(m => m.cost)), modelCurrency: 'CNY',
         }
-        arr.sort((a, b) => b.cost - a.cost)
-        return arr
       }
-      const days7 = []
-      let total7 = 0
-      // 今天在最上,往后退 6 天
-      for (let i = 0; i <= 6; i++) {
-        const d = dayAdd(today, -i)
-        const t = totalDay(d)
-        total7 += t
-        days7.push({ date: d, total: round2(t), models: modelsFor(d) })
-      }
-      const daySet = {}
-      Object.keys(history).forEach((d) => { if (/^\d{4}-\d{2}-\d{2}$/.test(d)) daySet[d] = 1 })
-      events.forEach((e) => { if (/^\d{4}-\d{2}-\d{2}$/.test(e.day)) daySet[e.day] = 1 })
-      const allDays = Object.keys(daySet).sort().reverse().map((d) => ({ date: d, total: totalDay(d), models: modelsFor(d) }))
-      const latestEvents = events.slice().sort((a, b) => b.ts - a.ts).slice(0, 500)
+      const todayData = forDay(today)
+      const days7 = Array.from({ length: 7 }, (_, i) => forDay(dayAdd(today, -i)))
+      const total7ByCurrency = {}
+      for (const d of days7) total7ByCurrency[d.currency] = addMoney(total7ByCurrency[d.currency] || 0, d.total)
+      const days = new Set([today, ...Object.keys(led.history || {}), ...accountingDays(led)])
+      for (const e of events) if (/^\d{4}-\d{2}-\d{2}$/.test(e.day)) days.add(e.day)
       return {
-        ok: true,
-        today: { total: totalDay(today), models: modelsFor(today) },
-        days7: days7,
-        total7: round2(total7),
-        all: { days: allDays, events: latestEvents },
+        ok: true, version: '0.3.1', today: todayData, days7,
+        total7: total7ByCurrency[todayData.currency] || 0, total7Currency: todayData.currency, total7ByCurrency,
+        all: {
+          days: Array.from(days).filter(d => /^\d{4}-\d{2}-\d{2}$/.test(d)).sort().reverse().map(forDay),
+          events: events.slice().sort((a, b) => b.ts - a.ts).slice(0, 500),
+        },
         settings: readUsageSettings(),
       }
     }
@@ -1472,10 +1454,41 @@ export default {
         if (j.resetAt) resetAt = pickJsonPath(data, j.resetAt)
         if (j.resetAtMs) { const ms = num(pickJsonPath(data, j.resetAtMs)); if (ms !== null) resetAt = ms }
         if (j.level) level = String(pickJsonPath(data, j.level) || '')
-        if (usedPct === null && remainPct === null && !resetAt) {
+        // v0.3.1：多窗口额度 —— 有些订阅额度接口一次返回多个窗口（如 OpenCode Go 的
+        // rolling / weekly / monthly），每个窗口各有「已用% + 重置时间」。模板用
+        // json.windows: [{ key, label, percent, resetAt }] 描述；这里归一成 windows 数组，
+        // 并把第一个窗口回填成主窗口 usedPct / resetAt，保持原有单窗口链路的兼容。
+        let windows = null
+        if (Array.isArray(j.windows)) {
+          const list = []
+          for (const w of j.windows) {
+            if (!w) continue
+            let wp = w.percent ? num(pickJsonPath(data, w.percent)) : null
+            if (wp !== null) wp = Math.max(0, Math.min(100, wp))
+            let wr = null
+            if (w.resetAt) {
+              const rv = pickJsonPath(data, w.resetAt)
+              if (rv !== undefined && rv !== null && rv !== '') wr = rv
+            }
+            if (wp === null && wr === null) continue
+            list.push({ key: String(w.key || ''), label: String(w.label || ''), usedPct: wp, resetAt: wr })
+          }
+          if (list.length) windows = list
+        }
+        if (windows) {
+          const w0 = windows[0]
+          if (usedPct === null && w0.usedPct !== null) usedPct = w0.usedPct
+          if (!resetAt && w0.resetAt !== null) resetAt = w0.resetAt
+          if (weeklyUsedPct === null) {
+            for (const w of windows) {
+              if ((w.key === 'weekly' || w.label === '周') && w.usedPct !== null) { weeklyUsedPct = w.usedPct; break }
+            }
+          }
+        }
+        if (usedPct === null && remainPct === null && !resetAt && !windows) {
           return { ok: false, code: 'PARSE', error: '额度接口返回无法解析（字段路径不匹配）' }
         }
-        return { ok: true, usedPct, remainPct, resetAt, level, weeklyUsedPct }
+        return { ok: true, usedPct, remainPct, resetAt, level, weeklyUsedPct, windows }
       } catch (err) {
         return { ok: false, code: 'HTTP', error: '额度接口请求失败: ' + String((err && err.message) || err).slice(0, 140) }
       }
@@ -1551,7 +1564,7 @@ export default {
         if (!cur || cur.day !== day) cur = apiUsageNewDay(cur, day, todayKey())
         if (typeof remaining === 'number' && isFinite(remaining)) {
           if (cur.dayStart === null || cur.dayStart === undefined) cur.dayStart = remaining
-          if (typeof cur.lastBalance === 'number' && remaining < cur.lastBalance - 0.000001) cur.delta = round2(cur.delta + (cur.lastBalance - remaining))
+          if (typeof cur.lastBalance === 'number' && remaining < cur.lastBalance) cur.delta = addMoney(cur.delta, cur.lastBalance - remaining)
           cur.lastBalance = remaining
         }
         reg.usage[id] = cur
@@ -1568,8 +1581,8 @@ export default {
         const reg = readApiRegistry()
         const cur = reg.usage && reg.usage[id]
         if (!cur || cur.day !== todayKey()) return { amount: 0, source: 'none', currency: mcur }
-        if (typeof cur.delta === 'number' && cur.delta > 0.004) return { amount: round2(cur.delta), source: 'balance', currency: mcur }
-        return { amount: round2(Number(cur.eventCost) || 0), source: 'events', currency: 'CNY' }
+        if (typeof cur.lastBalance === 'number' && isFinite(cur.lastBalance)) return { amount: preciseMoney(cur.delta || 0), source: 'balance', currency: mcur }
+        return { amount: preciseMoney(Number(cur.eventCost) || 0), source: 'events', currency: 'CNY' }
       } catch (err) { return { amount: 0, source: 'none', currency: mcur } }
     }
     function apiUsageRaw(id) {
@@ -1625,7 +1638,7 @@ export default {
         const day = todayKey()
         let cur = reg.usage[hit.id]
         if (!cur || cur.day !== day) cur = apiUsageNewDay(cur, day, todayKey())
-        cur.eventCost = round2((Number(cur.eventCost) || 0) + (Number(cost) || 0))
+        cur.eventCost = addMoney(Number(cur.eventCost) || 0, Number(cost) || 0)
         cur.eventTokens = (Number(cur.eventTokens) || 0) + (Number(tokens) || 0)
         // 累计量：额度（资源包/订阅）按它算已用；跨天不清零
         const tk = Number(tokens) || 0
@@ -1838,9 +1851,13 @@ export default {
             const p = await getBalance()
             if (p && p.ok) {
               entry.balance = Number(p.totalBalance)
-              entry.todayUsage = ledgerTodayTotal(readUsageLedger())
-              entry.todayUsageCurrency = 'CNY' // 内置 DeepSeek 走账本，一律人民币
-              entry.usageSource = 'ledger'
+              const summary = daySummary(readUsageLedger(), todayKey())
+              entry.currency = p.currency
+              entry.todayUsage = summary.amount
+              entry.todayUsageCurrency = summary.currency
+              entry.usageSource = summary.source
+              entry.usageLabel = summary.label
+              entry.accounting = balanceSummary(readUsageLedger(), todayKey())
             } else if (p) entry.error = p.error || p.code || '余额获取失败'
           } catch (err) { entry.error = String((err && err.message) || err) }
         } else {
@@ -1923,107 +1940,55 @@ export default {
       }
     }
 
-    // 记账：跨天时以当天第一次观测到的余额为“当日零点起始余额 dayStart”；
-    // 当天内每次观测都滚动刷新 lastBalance,不再因“今天已有事件”而提前返回——
-    // 事件明细可能因会话中断/重启漏记,真实余额差(dayStart−lastBalance)始终可算。
-    // 归档以真实余额差为准(与官网一致,事件计价偏高时不被带高);余额差不可用时才用事件。
-    function recordLedgerUsage(currentBalance) {
-      const t = todayKey()
-      let led = readUsageLedger()
-      const events = Array.isArray(led.events) ? led.events : []
-      function sumEv(d) { let s = 0; for (const e of events) if (e.day === d) s += Number(e.cost) || 0; return s }
-      if (led.date !== t) {
-        // 跨天:归档旧日真实合计(优先当日余额差;不可用/为0时退事件与历史),并重置当天基准
-        const oldDay = led.date
-        if (oldDay) {
-          led.history = led.history || {}
-          let oldTotal = 0
-          if (typeof led.dayStart === 'number' && typeof led.lastBalance === 'number' && led.lastBalance < led.dayStart) {
-            oldTotal = Math.max(oldTotal, led.dayStart - led.lastBalance)
-          }
-          oldTotal = Math.max(oldTotal, sumEv(oldDay))
-          if (typeof led.todayUsage === 'number') oldTotal = Math.max(oldTotal, led.todayUsage)
-          led.history[oldDay] = round2(oldTotal)
-        }
-        led.date = t
-        led.dayStart = currentBalance
-        led.todayUsage = 0
-        led.lastBalance = currentBalance
-      } else {
-        // 兼容旧账本:当天尚无 dayStart 时,把已冻结的 lastBalance 视为当天起始余额
-        if (typeof led.dayStart !== 'number' && typeof led.lastBalance === 'number') {
-          led.dayStart = led.lastBalance
-        }
-        led.lastBalance = currentBalance
-      }
-      // 归档/裁剪统一由 pruneLedgerUsage 负责（history 保留 365 天，events 90 天/2 万条）
+    // Each currency/key has its own timed observation window. An increase is
+    // recorded separately and never subtracts previously observed consumption.
+    function recordLedgerUsage(currentBalance, currency, scope, at) {
+      const led = readUsageLedger()
+      observeBalance(led, { balance: currentBalance, currency, scope, at })
       pruneLedgerUsage(led)
-      writeUsageLedger(led)
+      if (!writeUsageLedger(led)) throw new Error('账本保存失败，请检查 DSH 数据目录写入权限')
       return led
     }
     function normalizeUsageMode() {
       return 'ledger' // 小鲸鱼记账为唯一记账方式
     }
-    // 今日已用:以“当日真实余额差(零点起始余额−当前余额)”为准——
-    // 官方账单按真实扣款计,事件计价可能出现系统性偏高(14.49 vs 余额差 13.91 vs 官网 13.88),
-    // 余额差与官网几乎一致;事件合计仅在余额差不可用(充值/退款/无基准)时作兜底。
-    function ledgerTodayTotal(led) {
-      const events = Array.isArray(led.events) ? led.events : []
-      const t = dayKeyFromTs(Date.now())
-      let s = 0
-      for (const e of events) if (e.day === t) s += Number(e.cost) || 0
-      if (typeof led.dayStart === 'number' && typeof led.lastBalance === 'number') {
-        const d = led.dayStart - led.lastBalance
-        if (d > 0.004) return round2(d)
-      }
-      return round2(s)
-    }
+    function ledgerTodayTotal(led) { return daySummary(led, todayKey()).amount }
 
-    async function getBalancePayload() {
-      const payload = await fetchBalance()
-      if (!payload.ok) {
-        // 余额接口失败（含限流 429）时仍附上今日已用：事件优先，其次账本余额差
-        const led = readUsageLedger()
-        return { ...payload, todayUsage: ledgerTodayTotal(led), usageMode: 'ledger' }
-      }
-      recordLedgerUsage(Number(payload.totalBalance))
-      // 必须在写入后重读账本:否则 todayUsage 会按“上一轮 lastBalance”计算,
-      // 造成泡泡与用量记录(后者直接读文件)数值不一致(如 4.99 vs 5.05)
+    function publicBalance(payload) {
+      const { accountTag, ...visible } = payload
       const led = readUsageLedger()
-      const full = { ...payload }
-      full.isPeak = isPeakTime(Math.floor(Date.now() / 1000))
-      full.todayUsage = ledgerTodayTotal(led)
-      full.usageMode = 'ledger'
-      return full
+      const summary = daySummary(led, todayKey())
+      return {
+        ...visible, version: '0.3.1', isPeak: isPeakTime(Math.floor(Date.now() / 1000)),
+        todayUsage: summary.amount, todayUsageCurrency: summary.currency,
+        usageSource: summary.source, usageLabel: summary.label, usageMode: 'ledger',
+        accounting: balanceSummary(led, todayKey()),
+      }
     }
 
-    function getBalance() {
+    function getBalance(force = false) {
       const now = Date.now()
-      if (balanceCache && now - balanceCache.at < BALANCE_TTL_MS) {
-        return Promise.resolve(balanceCache.payload)
+      if (!force && balanceCache && now - balanceCache.at < BALANCE_TTL_MS) {
+        return Promise.resolve(publicBalance(balanceCache.payload))
       }
       if (balanceInFlight) return balanceInFlight
-      balanceInFlight = getBalancePayload()
+      balanceInFlight = fetchBalance()
         .then((payload) => {
           if (payload.ok) {
-            balanceCache = { at: now, payload }
-            return payload
+            recordLedgerUsage(payload.totalBalance, payload.currency, payload.accountTag, Date.parse(payload.updatedAt))
+            balanceCache = { at: Date.now(), payload }
+            return publicBalance(payload)
           }
           if (payload.transient && balanceCache) {
-            // transient network/API blip: keep serving the last known balance
-            return { ...balanceCache.payload, stale: true, error: payload.error }
+            return { ...publicBalance(balanceCache.payload), stale: true, error: payload.error }
           }
-          if (!payload.transient) console.error('[whale-balance]', payload.code, payload.error)
-          return payload
+          return publicBalance(payload)
         })
         .catch((err) => ({
-          ok: false,
-          code: 'ERROR',
+          ok: false, code: 'ERROR',
           error: '余额服务异常: ' + String((err && err.message) || err).slice(0, 200),
         }))
-        .finally(() => {
-          balanceInFlight = null
-        })
+        .finally(() => { balanceInFlight = null })
       return balanceInFlight
     }
 
@@ -2435,7 +2400,8 @@ export default {
       path: '/dsh-whale/balance.json',
       handler: async (req, res) => {
         try {
-          const payload = await getBalance()
+          const refresh = new URL(req.url || '/', 'http://localhost').searchParams.get('refresh') === '1'
+          const payload = await getBalance(refresh)
           res.writeHead(200, JSON_HEADERS)
           res.end(JSON.stringify(payload))
         } catch (err) {
@@ -2472,14 +2438,33 @@ export default {
               res.end(JSON.stringify({ ok: false, error: 'missing scale' }))
               return
             }
+            // issue #97：缺字段一律「沿用现有值」，绝不落默认 —— 否则任何不全的 PUT
+            // （旧客户端 / 手写 curl / 加载竞态）都会把用户的设置洗成默认值。
+            // 特别注意 scrollGapPx：读取默认是 17，而写入缺省曾是 0，会静默把避让宽度改掉。
+            const old = readSizeConfig() || {}
+            const pickB = (v, cur, dflt) => (typeof v === 'boolean' ? v : (typeof cur === 'boolean' ? cur : dflt))
+            const pickN = (v, cur, dflt) => (typeof v === 'number' ? v : (typeof cur === 'number' ? cur : dflt))
+            const pickS = (v, cur, dflt) => (typeof v === 'string' && v ? v : (typeof cur === 'string' && cur ? cur : dflt))
             // 用量模式变化时让余额缓存失效，下次请求立即按新模式计算
             if (typeof parsed.usageMode === 'string') {
-              const old = readSizeConfig()
-              if (!old || normalizeUsageMode(old.usageMode) !== normalizeUsageMode(parsed.usageMode)) {
+              if (normalizeUsageMode(old.usageMode) !== normalizeUsageMode(parsed.usageMode)) {
                 balanceCache = null
               }
             }
-            const result = writeSizeConfig(scale, parsed.sound !== false, parsed.vol, parsed.soundSet, parsed.usageMode, parsed.peakMode, parsed.bubbleOn, parsed.turnCostOn, parsed.turnCostCloseMs, parsed.scrollGapOn, parsed.scrollGapPx, parsed.menuBtnHide)
+            const result = writeSizeConfig(
+              scale,
+              pickB(parsed.sound, old.sound, true),
+              pickN(parsed.vol, old.vol, 0.9),
+              pickS(parsed.soundSet, old.soundSet, 'duck'),
+              typeof parsed.usageMode === 'string' ? parsed.usageMode : old.usageMode,
+              typeof parsed.peakMode === 'string' ? parsed.peakMode : old.peakMode,
+              pickB(parsed.bubbleOn, old.bubbleOn, true),
+              pickB(parsed.turnCostOn, old.turnCostOn, true),
+              pickN(parsed.turnCostCloseMs, old.turnCostCloseMs, 5000),
+              pickB(parsed.scrollGapOn, old.scrollGapOn, false),
+              pickN(parsed.scrollGapPx, old.scrollGapPx, 17),
+              pickB(parsed.menuBtnHide, old.menuBtnHide, false)
+            )
             res.writeHead(result.ok ? 200 : 500, JSON_HEADERS)
             res.end(JSON.stringify(result))
           } catch (err) {
@@ -2498,16 +2483,8 @@ export default {
       path: '/dsh-whale/usage-records.json',
       handler: async (req, res) => {
         try {
-          // 与余额路由同源:请求到来时若持有较新的余额缓存(≤70s,覆盖两次 60s 轮询间隙),
-          // 先用它刷新账本 lastBalance 再算汇总,保证“今日合计”与泡泡“今日已用”读同一份数据;
-          // 缓存太旧(挂件长时间未开)则跳过,避免把过期余额写回账本。
-          try {
-            if (balanceCache && balanceCache.payload && balanceCache.payload.ok &&
-                isFinite(Number(balanceCache.payload.totalBalance)) &&
-                Date.now() - balanceCache.at <= 70000) {
-              recordLedgerUsage(Number(balanceCache.payload.totalBalance))
-            }
-          } catch (err) {}
+          // Reports read the committed ledger. Replaying cached balance samples
+          // here could roll back a correction or create a false midnight baseline.
           res.writeHead(200, JSON_HEADERS)
           res.end(JSON.stringify(usageRecordsPayload()))
         } catch (err) {
@@ -2516,6 +2493,50 @@ export default {
         }
       },
     }))
+    disposers.push(registerRoute({
+      kind: 'exact',
+      path: '/dsh-whale/balance-adjustments.json',
+      handler: async (req, res) => {
+        try {
+          if (req.method === 'PUT') {
+            const input = JSON.parse(await readBodyMax(req, 8192))
+            if (!input || typeof input !== 'object') throw new Error('校正内容无效')
+            if (input.day === todayKey()) {
+              const fresh = await getBalance(true)
+              if (!fresh.ok || fresh.stale) {
+                res.writeHead(503, JSON_HEADERS)
+                res.end(JSON.stringify({ ok: false, error: '暂时无法刷新余额，请稍后再保存校正' }))
+                return
+              }
+            }
+            const led = readUsageLedger()
+            const summary = reconcileBalance(led, input)
+            if (!writeUsageLedger(led)) throw new Error('校正保存失败，请检查 DSH 数据目录写入权限')
+            balanceCache = null
+            res.writeHead(200, JSON_HEADERS)
+            res.end(JSON.stringify({ ok: true, summary }))
+            return
+          }
+          if (req.method !== 'GET' && req.method !== undefined) {
+            res.writeHead(405, { ...JSON_HEADERS, Allow: 'GET, PUT' })
+            res.end(JSON.stringify({ ok: false, error: '不支持的请求方法' }))
+            return
+          }
+          const fresh = await getBalance(true)
+          const led = readUsageLedger()
+          const days = accountingDays(led).sort().reverse().map(day => balanceSummary(led, day))
+          res.writeHead(200, JSON_HEADERS)
+          res.end(JSON.stringify({
+            ok: true, days, today: todayKey(), fresh: !!fresh.ok && !fresh.stale,
+            error: !fresh.ok || fresh.stale ? (fresh.error || '余额暂未刷新') : null,
+          }))
+        } catch (err) {
+          res.writeHead(err.status || 400, JSON_HEADERS)
+          res.end(JSON.stringify({ ok: false, error: String((err && err.message) || err).slice(0, 240) }))
+        }
+      },
+    }))
+
     // 用量设置(任务结束音/余额预警/今日预算)
     disposers.push(registerRoute({
       kind: 'exact',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-whale-widget",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "DSH Web 界面右下角的 DeepSeek 余额小鲸鱼挂件:余额/今日已用/峰谷定价、自定义泡泡点击序列(文本/余额/今日/峰谷/图片/随机语句与并列加权选择)、逐行样式与字体、悬浮快捷编辑、音效与每轮消耗、自定义角色/动图/音效、吸附与翻转自定义",
   "keywords": [
     "dsh",
@@ -15,7 +15,8 @@
     "lib",
     "assets",
     "cordis.patch.yml",
-    "README.md"
+    "README.md",
+    "PROVENANCE.md"
   ],
   "repository": {
     "type": "git",