dsh-whale-widget 0.3.1 → 0.3.3

package/README.md

@@ -4,13 +4,28 @@
 
 DeepSeek Harness（DSH）Web 界面右下角的常驻挂件：小鲸鱼气泡图 + DeepSeek API 余额 + 今日已用 + 每轮对话消耗，并且**泡泡内容可以完全自定义**（点击序列、模块化排版、并列加权出泡、随机语句/随机图片）。标准 DSH bundle 插件，`dsh plugin` 一键安装，无需任何会话令牌。
 
+## 两条分支怎么选
+
+本仓库有两条**互不兼容**的产品线，按你要挂在哪里选一条：
+
+| 你要挂在哪 | 用哪条分支 | 安装方式 |
+|---|---|---|
+| **DSH Web 界面右下角**（就是这个 README 描述的插件） | `main`（默认分支） | `dsh plugin --profile web add dsh-whale-widget`（推荐，装 npm 已发布版）；也可以从本仓库装 `dsh plugin --profile web add github:MeteorNOX/DeepSeek-Balance-Whale-Widget`，但那样装的是 **main 当前状态、不跟随已发布版本** |
+| **Codex 桌面应用**（跟随 Codex 窗口、无独立网页） | [`For-Codex`](https://github.com/MeteorNOX/DeepSeek-Balance-Whale-Widget/tree/For-Codex) | 该分支的 `api-balance-whale`：解压到 `%USERPROFILE%\plugins\api-balance-whale`，再按分支内的 [安装说明](https://github.com/MeteorNOX/DeepSeek-Balance-Whale-Widget/blob/For-Codex/docs/INSTALL-AND-ROLLBACK-0.2.0.md) 注册计划任务（也可以直接交给 Codex 自己装喵~） |
+
+⚠️ **两条分支互不兼容**：`For-Codex` 的插件不能用 `dsh plugin … add` 装进 DSH 网页；本主分支的插件也不能在 Codex 桌面里运行。上表第一行是本仓库默认分支（`main`）的能力，第二行是另一个分支的能力。
+
+⚠️ 同一分支的两种安装方式（npm 名 / `github:`）**二选一、别混用** —— 它们是同一个包名，先后安装会并存冲突；已经是 `github:` 装的，要换 npm 名请先 `dsh plugin --profile web remove dsh-whale-widget`。
+
+> 两条产品线**各自独立维护**（无共享代码/无跨分支依赖）：`main` = DSH Web 插件，`For-Codex` = Codex 桌面端口，各自的版本线、发布方式与测试互不影响。
+
 ## 特性
 
 ### 记账与显示
 
 - 🐋 **常驻自启**：随 DSH Web 界面每次打开自动出现（标准 DSH bundle 插件）
 - 💰 **余额**：60 秒自动刷新 + 点击鲸鱼手动刷新；余额变化时数字**滚动动画**；瞬时网络抖动自动沿用最近余额不报错
-- 📊 **今日已用（小鲸鱼记账）**：不需要任何令牌。余额**下降**按观测累计为消费，余额**上升**（充值 / 赠金）单独记录、不会冲掉已有消费；检测到余额增加会提示「待核对余额调整」，可在「小鲸鱼记账 → 充值 / 余额校正」按实际累计到账金额与非调用扣减校正（逐轮明细保留 90 天或最多 2 万条、逐日归档保留 365 天，超期数据归档到 `.dshw-usage-archive.json`）；金额按 8 位小数记账、显示保留两位
+- 📊 **今日已用（小鲸鱼记账）**：不需要任何令牌。余额**下降**按观测累计为消费，余额**上升**（充值 / 赠金）单独记录、不会冲掉已有消费；检测到余额增加会提示「待核对余额调整」，可在「小鲸鱼记账 → **DeepSeek（内置）→ 设置 → 余额校正**」按实际累计到账金额与非调用扣减校正 —— **「已观测消费」与「余额校正」都是 DeepSeek 账户口径**（由该 API key 的余额观测得出，不含其它厂商；「本机模型费用」才是所有模型的本地估算）（逐轮明细保留 90 天或最多 2 万条、逐日归档保留 365 天，超期数据归档到 `.dshw-usage-archive.json`）；金额按 8 位小数记账、显示保留两位
 - 💬 **每轮对话消耗**：监听 DSH 本机会话事件，按模型**真实 usage**（input / cache / output / reasoning tokens）换算金额，每轮结束弹出消耗泡泡；可开关、自动关闭秒数可设（0 = 不自动关闭），**泡泡内容可自定义**（模块化，金额用 `{cost}` 引用），入口：菜单 → 每轮消耗提示 → 「自定义提示」
 - ⛰️ **峰谷定价**：工作日高峰 9:00–12:00、14:00–18:00（北京时间），其余空闲；2026-08-23 起**周末全天谷价**。峰谷模块支持状态文字、倒计时、"梁文峰谷 / !?强强?! / 简洁"等多种样式
 - 📒 **用量记录窗口**：今日模型消费、近 7 天、全部记录；模型占比条；按日期展开逐条明细（含时间与金额）；支持按日期或**模型名搜索**；模型名带友好标注（`deepseek-flash` → `DeepSeek-V4.1-Flash`，旧名标注"同 V4.1 Flash"）
@@ -341,7 +356,7 @@ curl http://127.0.0.1:3080/dsh-whale/audio.json
 - **图片/音效不显示、没声音**：确认插件包内 `assets/` 完整（`DSniang1.png`、`*.mp3`、`minecraft-exp-orb.wav` 等）；缺失时相关功能静默降级。
 - **余额报「未配置 DEEPSEEK_API_KEY」**：去 DSH 凭据里配置。
 - **今日已用显示 `--`**：先等一次成功的余额观测；统计从该观测时刻开始，起点之前的消费不在此区间内。
-- **今日已用与官网有差异**：先核对同一账户、同一币种与同一统计区间；若有充值或其它余额调整，用「小鲸鱼记账 → 充值 / 余额校正」填写实际到账金额。余额接口只返回余额快照、不提供充值流水，充值与消费发生在同一次刷新间隔时需要实际到账金额才能校正。
+- **今日已用与官网有差异**：先核对同一账户、同一币种与同一统计区间；若有充值或其它余额调整，用「小鲸鱼记账 → DeepSeek（内置）→ 设置 → 余额校正」填写实际到账金额。余额接口只返回余额快照、不提供充值流水，充值与消费发生在同一次刷新间隔时需要实际到账金额才能校正。
 - **充值后消费数字没变**：这是预期行为——充值不会增加消费；数字上方会出现「待核对余额调整」，提示你补充本统计区间的累计到账金额。
 - **每轮消耗不显示**：确认菜单里「每轮对话后自动显示消耗金额」已勾选；一轮对话要完整结束（`turn/end`）才结算。余额变化泡泡与消耗泡泡抢层时，提醒会退化为居中卡片。
 - **每轮消耗泡泡的内容**：菜单 → 每轮消耗提示 → 「自定义提示」里编辑（模块化，金额用 `{cost}`）；这里同时能设自动关闭秒数与任务结束音效。

package/assets/whale-widget.js

@@ -11,38 +11,145 @@ window.__dshWhaleWidget = true
 function dshwIsChatRoot(r) {
   return !!(r && (r.querySelector('textarea') || r.querySelector('[contenteditable="true"]')))
 }
-var dshwEnabled = false
+var dshwStarted = false
+function dshwStartOnce() {
+  if (dshwStarted) return
+  dshwStarted = true
+  try { dshwInit() } catch (err) {}
+}
+// 是否已到主聊天界面；是则启动（只启动一次，之后由 dshwInit 内部标记去重）
+var dshwLastCheck = 0
+function dshwTryStart(force) {
+  if (dshwStarted) return true
+  var now = Date.now()
+  // 连续 DOM 变化时合并检查，避免每次 mutation 都 querySelector
+  if (!force && now - dshwLastCheck < 200) return false
+  dshwLastCheck = now
+  try {
+    if (dshwIsChatRoot(document.getElementById('root'))) { dshwStartOnce(); return true }
+  } catch (err) {}
+  return false
+}
 try {
-  var dshwRoot = document.getElementById('root')
-  // 初始已有 composer → 主界面
-  if (dshwIsChatRoot(dshwRoot)) {
-    dshwEnabled = true
-  } else {
-    // 尚未渲染：轮询等待（主界面异步挂载），超过 5s 视为非主界面（市场/设置等）放弃
-    var dshwPollTries = 0
-    var dshwPoll = setInterval(function () {
-      dshwPollTries++
-      if (dshwIsChatRoot(document.getElementById('root'))) {
-        clearInterval(dshwPoll)
-        dshwEnabled = true
-        try { dshwInit() } catch (err) {}
-        return
+  if (!dshwIsChatRoot(document.getElementById('root'))) {
+    // 尚未渲染：MutationObserver 无限等待（v739 去掉原来的「5 秒死线」）。
+    // 原来 500ms × 10 次就永久放弃，而 window.__dshWhaleWidget 是一次性闸门 ——
+    // 慢启动机器、或页面最小化时定时器被浏览器节流，都会让"第一次没赶上"变成
+    // "这次会话永远不出现"（用户反馈 / issue #102 第 2 条）。
+    // 约束不变：检测到 composer 之前一行 DOM 都不碰、不注册任何全局监听。
+    var dshwObserver = null
+    try {
+      if (typeof MutationObserver === 'function') {
+        dshwObserver = new MutationObserver(function () {
+          if (dshwTryStart()) { try { dshwObserver.disconnect() } catch (err) {} }
+        })
+        dshwObserver.observe(document.documentElement || document.body, { childList: true, subtree: true })
       }
-      if (dshwPollTries >= 10) {
-        clearInterval(dshwPoll)
-        // 非主界面：直接退出，不初始化
+    } catch (err) {}
+    // 兜底：observer 不可用时低频轮询继续等（不设上限，找到即停）
+    var dshwFallbackPoll = setInterval(function () {
+      if (dshwTryStart(true)) {
+        clearInterval(dshwFallbackPoll)
+        try { if (dshwObserver) dshwObserver.disconnect() } catch (err) {}
       }
-    }, 500)
+    }, 2000)
   }
 } catch (err) {}
-if (!dshwEnabled) {
-  // 非主界面（或等待超时）：不初始化挂件
-  return
-}
 function dshwInit() {
 if (window.__dshWhaleInit) return
 window.__dshWhaleInit = true
 
+// ===== v739：音效改用 Web Audio 播放（不再用 <audio> / HTMLAudioElement）=====
+// 为什么改：HTMLAudioElement 会被 macOS 注册进系统「正在播放」，带 Touch Bar 的机器上
+// 每次按小鲸鱼都会弹出音频播放条并持续动画 → 明显卡顿（用户反馈）。AudioBufferSourceNode
+// 不经过媒体元素，系统媒体控件不会出现，也没有那层额外的解码/合成开销。
+// 兼容做法：给一个与 HTMLAudioElement 常用表面一致的 shim（play/pause/currentTime/volume/
+// onended/preload/src），这样既有的播放、音量、重播、结束回调逻辑一行都不用改。
+var dshwvAudioCtx = null
+function dshwvAudio() {
+  try {
+    if (!dshwvAudioCtx) dshwvAudioCtx = new (window.AudioContext || window.webkitAudioContext)()
+    if (dshwvAudioCtx.state === 'suspended') { try { dshwvAudioCtx.resume() } catch (err) {} }
+    return dshwvAudioCtx
+  } catch (err) { return null }
+}
+var dshwvAudioBuffers = {} // url -> Promise<AudioBuffer>（解码结果缓存，同一片段不重复下载/解码）
+function dshwvAudioBuffer(url) {
+  if (!url) return Promise.reject(new Error('empty url'))
+  if (!dshwvAudioBuffers[url]) {
+    dshwvAudioBuffers[url] = fetch(url, { cache: 'force-cache' })
+      .then(function (r) { if (!r.ok) throw new Error('HTTP ' + r.status); return r.arrayBuffer() })
+      .then(function (raw) {
+        var c = dshwvAudio()
+        if (!c) throw new Error('no audio context')
+        return new Promise(function (res, rej) { c.decodeAudioData(raw, res, rej) })
+      })
+      .catch(function (err) { delete dshwvAudioBuffers[url]; throw err })
+  }
+  return dshwvAudioBuffers[url]
+}
+function dshwvSoundStop(el) {
+  el._token = (el._token || 0) + 1
+  var node = el._node
+  el._node = null
+  if (node) {
+    try { node.onended = null } catch (err) {}
+    try { node.stop() } catch (err) {}
+  }
+}
+function dshwvSound(url) {
+  var el = { preload: 'auto', volume: 1, onended: null, loop: false, _url: String(url || ''), _node: null, _gain: null, _offset: 0, _token: 0 }
+  Object.defineProperty(el, 'src', {
+    get: function () { return el._url },
+    set: function (v) { dshwvSoundStop(el); el._url = String(v || ''); el._offset = 0 },
+  })
+  Object.defineProperty(el, 'currentTime', {
+    get: function () { return el._offset },
+    // 既有逻辑用「currentTime = 0」表示重播 → 这里顺手停掉正在播的那一份
+    set: function (v) { el._offset = Number(v) || 0; dshwvSoundStop(el) },
+  })
+  el.play = function () {
+    var c = dshwvAudio()
+    if (!c || !el._url) return Promise.resolve()
+    try {
+      if (!el._gain) { el._gain = c.createGain(); el._gain.connect(c.destination) }
+      el._gain.gain.value = Math.max(0, Math.min(1, Number(el.volume) || 0))
+    } catch (err) { return Promise.resolve() }
+    var token = (el._token = (el._token || 0) + 1)
+    var url = el._url
+    dshwvAudioBuffer(url).then(function (buf) {
+      if (token !== el._token) return // 期间被重播/暂停/换源 → 丢弃这次
+      try {
+        var src = c.createBufferSource()
+        src.buffer = buf
+        src.connect(el._gain)
+        src.onended = function () {
+          if (el._node !== src) return
+          el._node = null
+          if (typeof el.onended === 'function') { try { el.onended() } catch (err) {} }
+        }
+        el._node = src
+        var dur = Math.max(0.001, buf.duration)
+        src.start(0, Math.max(0, el._offset) % dur)
+      } catch (err) {}
+    }).catch(function () {})
+    return Promise.resolve()
+  }
+  el.pause = function () { dshwvSoundStop(el) }
+  return el
+}
+// 自动播放策略：AudioContext 初始是 suspended，要有一次用户手势才能出声。
+// 任务结束音不是手势触发的，所以先挂一次性解锁（首次点击/按键后移除）。
+try {
+  var dshwvAudioUnlock = function () {
+    dshwvAudio()
+    try { document.removeEventListener('pointerdown', dshwvAudioUnlock, true) } catch (err) {}
+    try { document.removeEventListener('keydown', dshwvAudioUnlock, true) } catch (err) {}
+  }
+  document.addEventListener('pointerdown', dshwvAudioUnlock, true)
+  document.addEventListener('keydown', dshwvAudioUnlock, true)
+} catch (err) {}
+
 var MIN_SCALE = 0.6
 var MAX_SCALE = 2.5
 var STEP = 0.1
@@ -293,7 +400,7 @@ var css = [
   '.dshwv-usagepanel{position:fixed;z-index:26020;background:#fff;border:1px solid rgba(32,49,112,.35);border-radius:10px;box-shadow:0 8px 22px rgba(15,23,42,.22);padding:10px 12px;color-scheme:light;max-height:70vh;overflow-y:auto}',
   // 用量作为主菜单内的子界面
   '.dshwv-menuview{display:block}',
-  '.dshwv-usage-sub{display:none;max-height:min(70vh,560px);overflow-y:auto;padding-right:2px;width:100%;box-sizing:border-box}',
+  '.dshwv-usage-sub{display:none;max-height:min(70vh,560px);overflow-y:auto;padding-right:2px;padding-bottom:12px;width:100%;box-sizing:border-box}',
   '.dshwv-usage-back{border:none;background:none;color:#203170;font-size:12px;font-weight:600;cursor:pointer;padding:0 0 2px;text-align:left;width:100%}',
   '.dshwv-usage-back:hover{color:#2f4488;text-decoration:underline}',
   '.dshwv-usagebody{display:flex;flex-direction:column;gap:2px;color:#203170;font-size:12px;min-width:0;overflow-x:hidden}',
@@ -1006,7 +1113,7 @@ function playTaskEndSound() {
       url = '/dsh-whale/sound/' + (parts[2] === 'release' ? 'release' : 'press') + '.mp3?set=' + parts[1]
     }
     if (!url) return
-    var a = new Audio(url)
+    var a = dshwvSound(url)
     try { a.volume = Number(soundVol) || 0.9 } catch (err) {}
     a.play().catch(function () {})
   } catch (err) {}
@@ -1025,7 +1132,7 @@ function playTaskEndGroupClick(groupId) {
     // 按压留空:无按下音,直接播松开(模拟按下即松开的完整点按);松开留空:只播按压
     if (pressEmpty) {
       if (!releaseEmpty) {
-        var relOnly = new Audio('/dsh-whale/sound/release.mp3?set=' + encodeURIComponent(groupId))
+        var relOnly = dshwvSound('/dsh-whale/sound/release.mp3?set=' + encodeURIComponent(groupId))
         try { relOnly.volume = vol } catch (err) {}
         relOnly.currentTime = 0
         var pr = relOnly.play()
@@ -1033,7 +1140,7 @@ function playTaskEndGroupClick(groupId) {
       }
       return
     }
-    var press = new Audio('/dsh-whale/sound/press.mp3?set=' + encodeURIComponent(groupId))
+    var press = dshwvSound('/dsh-whale/sound/press.mp3?set=' + encodeURIComponent(groupId))
     try { press.volume = vol } catch (err) {}
     if (releaseEmpty) {
       press.currentTime = 0
@@ -1041,7 +1148,7 @@ function playTaskEndGroupClick(groupId) {
       if (pp && pp.catch) pp.catch(function () {})
       return
     }
-    var release = new Audio('/dsh-whale/sound/release.mp3?set=' + encodeURIComponent(groupId))
+    var release = dshwvSound('/dsh-whale/sound/release.mp3?set=' + encodeURIComponent(groupId))
     try { release.volume = vol } catch (err) {}
     var relPlayed = false
     function playRel() {
@@ -1870,6 +1977,13 @@ function apiModelById(id) {
   for (var i = 0; i < apiModels.length; i++) if (apiModels[i] && apiModels[i].id === id) return apiModels[i]
   return null
 }
+// 「充值 / 余额校正」只属于固定的 DeepSeek（内置）：宿主在模型条目里下发 canAdjustBalance，
+// 前端据此决定要不要在设置菜单里给出入口 —— 手动新增的同名模型、Kimi 等其它厂商都不会有，
+// 新增模板也不会自动继承（宿主还会在路由层再校验一次，见 balance-adjustments.json）。
+function apiCanAdjustBalance(model) {
+  return !!(model && model.id === 'deepseek' && model.builtin === true &&
+    model.provider === 'deepseek' && model.canAdjustBalance === true)
+}
 // 今日已用金额自带的币种（host 下发的 todayUsageCurrency）：
 // 会话事件金额在 host 已按自定义单价折算成人民币，余额差则是厂商币种 → 显示必须按各自的币种，
 // 否则 USD 单价的模型会把人民币数值渲染成 $。
@@ -2800,7 +2914,7 @@ function openApiModelMenu(modelId) {
     else st.textContent = '余额 ' + apiFmtMoney(m.balance, m.currency) + ' · 今日已用 ' + apiFmtMoney(m.todayUsage, apiTodayCur(m))
     card.appendChild(st)
     var ms = (usageSet && usageSet.models && usageSet.models[modelId]) || {}
-    function rowOf(label, stateFn, onEdit) {
+    function rowOf(label, stateFn, onEdit, buttonLabel) {
       var r = document.createElement('div')
       r.className = 'dshwv-audiorow'
       var l = document.createElement('span')
@@ -2817,8 +2931,9 @@ function openApiModelMenu(modelId) {
       info.style.textOverflow = 'ellipsis'
       info.textContent = stateFn()
       r.appendChild(info)
-      r.appendChild(apiBtn('编辑', 'dshwv-roleimport', onEdit))
+      r.appendChild(apiBtn(buttonLabel || '编辑', 'dshwv-roleimport', onEdit))
       card.appendChild(r)
+      return r
     }
     rowOf('余额预警', function () {
       var a = ms.alert
@@ -2875,13 +2990,15 @@ function openApiModelMenu(modelId) {
       card.appendChild(pr)
     }
     // 只读行（复用现有 .dshwv-audiorow / .dshwv-usage-hint，不引入新颜色与字体）
-    function readonlyRow(label, text) {
+    function readonlyRow(label, text, hintHtml) {
       var r = document.createElement('div')
       r.className = 'dshwv-audiorow'
       var l = document.createElement('span')
       l.textContent = label
       l.style.flex = '0 0 auto'
       r.appendChild(l)
+      // 需要「?」说明时，说明收进圆圈（悬停显示、点击钉住），与挂件其它说明圈同一套组件
+      if (hintHtml) { try { r.appendChild(dshwvAskDot(hintHtml)) } catch (err) {} }
       var v = document.createElement('span')
       v.className = 'dshwv-usage-hint'
       v.style.flex = '1'
@@ -2914,6 +3031,32 @@ function openApiModelMenu(modelId) {
       pTxt = '未设置（沿用内置价目表）→ 在「密钥 / 接口」里填写'
     }
     readonlyRow('单价', pTxt)
+    // 「已观测消费」= DeepSeek 账户口径（余额观测），只在内置项的设置里显示，与下面的「余额校正」配套。
+    if (apiCanAdjustBalance(m)) {
+      var acc = m.accounting || null
+      var accAmt = (acc && typeof acc.amount === 'number') ? acc.amount : m.todayUsage
+      var accInfo = (acc && acc.firstObservedAt)
+        ? '统计起点（北京）：' + accountingTime(acc.firstObservedAt) + '。起点前的消费未计入；该账户的观测包含同一个 key 在别处的消费。'
+        : '尚无余额观测：先配置 DeepSeek API key 并成功刷新一次余额。'
+      readonlyRow('已观测消费', ((acc && acc.label) || m.usageLabel || '已观测消费') + ' ' +
+        (isFinite(Number(accAmt)) ? apiFmtMoney(accAmt, apiTodayCur(m)) : '--'), accInfo)
+      // 需要用户动手的提示仍然直接显示（不藏进「?」里）
+      if (acc && acc.needsReview) {
+        var accWarn = document.createElement('div')
+        accWarn.className = 'dshwv-usage-hint'
+        accWarn.style.cssText = 'line-height:1.65;white-space:normal;margin:2px 0 4px'
+        accWarn.textContent = '检测到余额增加，请用下面的「余额校正」核对本区间累计到账。'
+        card.appendChild(accWarn)
+      }
+    }
+    // 「充值 / 余额校正」入口：只给固定的 DeepSeek（内置），放在「单价」下方、沿用同一行布局与按钮样式。
+    // 其它厂商、手动新增的 DeepSeek、仅改名为「DeepSeek（内置）」的模型都不会走到这里。
+    if (apiCanAdjustBalance(m)) {
+      var adjustmentRow = rowOf('余额校正', function () {
+        return (m.accounting && m.accounting.label) || '充值与余额调整'
+      }, function () { openBalanceAdjustment(modelId) }, '校正')
+      adjustmentRow.lastElementChild.setAttribute('data-action', 'balance-adjustment')
+    }
     // 币种不一致提示：今日已用按「自带币种」显示（会话事件为 CNY）。若与模型币种不同且没填汇率，
     // 今日预算提醒会被跳过（见 A 方案），这里给出可见的补救提示。
     var tuc = String((m && m.todayUsageCurrency) || '').toUpperCase()
@@ -3009,94 +3152,92 @@ function accountingTime(at) {
   } catch (err) { return String(at || '') }
 }
 var accountingMask = null
-function openBalanceAdjustment() {
-  if (accountingMask) return
-  var previousFocus = document.activeElement
+function openBalanceAdjustment(modelId) {
+  // 只有固定的 DeepSeek（内置）能打开：入口由宿主下发的 canAdjustBalance 控制，这里再挡一次
+  if (!apiCanAdjustBalance(apiModelById(modelId)) || accountingMask) return
+  var adjustmentUrl = '/dsh-whale/balance-adjustments.json?modelId=' + encodeURIComponent(modelId)
+  closeApiModelPanel()
+  // 与「额度」「余额预警 / 今日预算」等窗口共用同一套骨架与样式：
+  // dshwv-usage-mask + dshwv-usage-card + dshwv-bubtitle/bubhint + apiPanelRow/apiTextInput + dshwv-bubbtns
   var mask = document.createElement('div')
   mask.className = 'dshwv-usage-mask'
-  mask.style.display = 'flex'
-  mask.style.zIndex = '2147483647'
+  mask.style.zIndex = '30000'
   var card = document.createElement('form')
   card.className = 'dshwv-usage-card'
-  card.style.cssText = 'width:min(520px,calc(100vw - 32px));box-sizing:border-box;max-height:calc(100vh - 40px);overflow:auto;padding:22px;color:#203170;background:#fff;border-radius:18px;line-height:1.65'
+  card.style.width = 'min(430px,94vw)'
+  card.style.padding = '14px 16px'
+  card.style.boxSizing = 'border-box'
+  card.style.textAlign = 'left'
   card.setAttribute('role', 'dialog')
   card.setAttribute('aria-modal', 'true')
-  card.setAttribute('aria-label', '充值与余额校正')
-  var title = document.createElement('h2')
-  title.textContent = '充值与余额校正'
-  title.style.cssText = 'font-size:20px;margin:0 0 8px'
-  card.appendChild(title)
-  var introduction = document.createElement('p')
+  card.setAttribute('aria-label', 'DeepSeek（内置）余额校正')
+  // 内容可能比 82vh 高：中间这段自己滚，按钮行固定在底部（与 .dshwv-reswrap 同一做法）
+  var body = document.createElement('div')
+  body.style.cssText = 'min-height:0;overflow-y:auto;flex:1 1 auto'
+  var title = document.createElement('div')
+  title.className = 'dshwv-bubtitle'
+  title.textContent = '余额校正 · DeepSeek（内置）'
+  body.appendChild(title)
+  var introduction = document.createElement('div')
+  introduction.className = 'dshwv-bubhint'
+  introduction.style.cssText = 'margin:0 0 8px;white-space:normal;line-height:1.6;text-align:left'
   introduction.textContent = '核对统计区间内的全部到账后，重新计算本地消费。此操作不会充值，也不会改变 DeepSeek 账户余额。'
-  introduction.style.cssText = 'font-size:13px;margin:0 0 14px'
-  card.appendChild(introduction)
-  function field(labelText, input) {
-    var label = document.createElement('label')
-    label.style.cssText = 'display:block;font-size:13px;margin:12px 0'
-    var text = document.createElement('span')
-    text.textContent = labelText
-    label.appendChild(text)
-    input.style.cssText = 'display:block;width:100%;box-sizing:border-box;min-height:40px;margin-top:5px;border:1px solid #b9c5e7;border-radius:8px;padding:8px;background:#fff;color:#203170;font:inherit'
-    label.appendChild(input)
-    card.appendChild(label)
-    return text
-  }
-  var dates = document.createElement('select')
-  field('记账日期（北京时间）', dates)
+  body.appendChild(introduction)
+  var dates = apiSelectEl([], '')
+  body.appendChild(apiPanelRow('日期', dates))
   var interval = document.createElement('div')
-  interval.style.cssText = 'font-size:13px;white-space:pre-line;background:#f1f5ff;padding:12px;border-radius:10px'
-  card.appendChild(interval)
-  var credits = document.createElement('input')
-  credits.type = 'text'
+  interval.className = 'dshwv-bubhint'
+  interval.style.cssText = 'margin:0 0 8px;white-space:pre-line;line-height:1.6;text-align:left'
+  body.appendChild(interval)
+  var credits = apiTextInput('', '未到账请填 0')
   credits.inputMode = 'decimal'
   credits.required = true
   credits.autocomplete = 'off'
-  var creditsLabel = field('本统计区间累计到账金额', credits)
-  var debits = document.createElement('input')
-  debits.type = 'text'
+  body.appendChild(apiPanelRow('累计到账', credits))
+  var creditsHint = document.createElement('div')
+  creditsHint.className = 'dshwv-bubhint'
+  creditsHint.style.cssText = 'margin:0 0 8px;white-space:normal;line-height:1.6;text-align:left'
+  body.appendChild(creditsHint)
+  var debits = apiTextInput('0', '没有请填 0')
   debits.inputMode = 'decimal'
   debits.autocomplete = 'off'
-  var debitsLabel = field('非调用造成的余额减少（没有请填 0）', debits)
-  var help = document.createElement('p')
-  help.style.cssText = 'font-size:12px;margin:8px 0;color:#4c5e87'
-  help.textContent = '到账包括充值、赠金等；多次到账请填合计，不要只填最后一笔。非调用减少可包含到期赠金、余额退回等。仅填写上方统计起点之后的金额；保存会替换之前的校正值。'
-  card.appendChild(help)
+  body.appendChild(apiPanelRow('非调用扣减', debits))
+  var debitsHint = document.createElement('div')
+  debitsHint.className = 'dshwv-bubhint'
+  debitsHint.style.cssText = 'margin:0 0 8px;white-space:normal;line-height:1.6;text-align:left'
+  body.appendChild(debitsHint)
   var preview = document.createElement('div')
-  preview.style.cssText = 'font-weight:600;font-size:15px;margin:14px 0'
+  preview.className = 'dshwv-bubhint'
+  preview.style.cssText = 'margin:0 0 8px;white-space:normal;line-height:1.6;text-align:left;font-weight:700;color:#203170'
   preview.setAttribute('aria-live', 'polite')
-  card.appendChild(preview)
+  body.appendChild(preview)
   var confirmRow = document.createElement('label')
-  confirmRow.style.cssText = 'display:flex;gap:8px;align-items:flex-start;font-size:13px;margin:12px 0;cursor:pointer'
+  confirmRow.style.cssText = 'display:flex;gap:6px;align-items:flex-start;flex:1;min-width:0;font-size:12px;color:#203170;cursor:pointer;line-height:1.5'
   var confirm = document.createElement('input')
   confirm.type = 'checkbox'
-  confirm.style.marginTop = '5px'
+  confirm.style.marginTop = '1px'
   confirmRow.appendChild(confirm)
   confirmRow.appendChild(document.createTextNode('我已核对本统计区间的全部到账和非调用扣减'))
-  card.appendChild(confirmRow)
+  body.appendChild(apiPanelRow('确认', confirmRow))
   var status = document.createElement('div')
+  status.className = 'dshwv-bubhint'
   status.setAttribute('role', 'status')
-  status.style.cssText = 'font-size:13px;white-space:normal;color:#b33333;margin:8px 0'
+  status.style.cssText = 'margin:0 0 6px;white-space:normal;line-height:1.6;text-align:left;color:#b33333'
   status.textContent = '正在刷新余额…'
-  card.appendChild(status)
-  var actions = document.createElement('div')
-  actions.style.cssText = 'display:flex;gap:8px;flex-wrap:wrap;justify-content:flex-end;margin-top:16px'
-  function button(text, callback) {
-    var btn = document.createElement('button')
-    btn.type = 'button'
-    btn.textContent = text
-    btn.className = 'dshwv-bubbtn dshwv-bubbtn-no'
-    btn.style.cssText = 'min-height:38px;padding:8px 12px;cursor:pointer'
-    if (callback) btn.addEventListener('click', callback)
-    actions.appendChild(btn)
-    return btn
-  }
+  body.appendChild(status)
+  card.appendChild(body)
   var busy = false
   function close() {
     if (busy) return
     document.removeEventListener('keydown', keyHandler)
     mask.remove()
     accountingMask = null
-    try { previousFocus.focus() } catch (err) {}
+    // 关掉校正窗口后回到同一个设置菜单，并把焦点放回「校正」按钮
+    openApiModelMenu(modelId)
+    try {
+      var returnButton = apiModelMaskEl && apiModelMaskEl.querySelector('[data-action="balance-adjustment"]')
+      if (returnButton) returnButton.focus()
+    } catch (err) {}
   }
   function keyHandler(e) {
     if (e.key === 'Escape') { e.preventDefault(); close() }
@@ -3109,25 +3250,17 @@ function openBalanceAdjustment() {
       else if (!e.shiftKey && document.activeElement === last) { e.preventDefault(); first.focus() }
     }
   }
-  var reload = button('重新读取', function () { load() })
-  var reset = button('撤销该日校正', function () { submit('reset') })
-  button('取消', close)
-  var save = button('保存校正')
-  save.type = 'submit'
-  save.style.background = '#315de8'
-  save.style.color = '#fff'
-  save.style.border = '1px solid #315de8'
+  // 按钮行与其它窗口完全一致：.dshwv-bubbtns + apiBtn 的标准按钮样式（不再自绘尺寸/配色）
+  var actions = document.createElement('div')
+  actions.className = 'dshwv-bubbtns'
+  var reload = apiBtn('重新读取', 'dshwv-bubbtn dshwv-bubbtn-no', function () { load() })
+  var reset = apiBtn('撤销该日校正', 'dshwv-bubbtn dshwv-bubbtn-no', function () { submit('reset') })
+  var save = apiBtn('保存校正', 'dshwv-bubbtn dshwv-bubbtn-ok', function () { submit('save') })
+  actions.appendChild(reload)
+  actions.appendChild(reset)
+  actions.appendChild(apiBtn('取消', 'dshwv-bubbtn dshwv-bubbtn-no', function () { close() }))
+  actions.appendChild(save)
   card.appendChild(actions)
-  var scrollBody = document.createElement('div')
-  scrollBody.style.cssText = 'min-height:0;overflow:auto;flex:1 1 auto;padding-right:3px'
-  while (card.firstChild && card.firstChild !== actions) scrollBody.appendChild(card.firstChild)
-  card.insertBefore(scrollBody, actions)
-  card.style.display = 'flex'
-  card.style.flexDirection = 'column'
-  card.style.overflow = 'hidden'
-  actions.style.flex = '0 0 auto'
-  actions.style.paddingTop = '10px'
-  actions.style.borderTop = '1px solid #e2e8f5'
   mask.appendChild(card)
   mask.addEventListener('click', function (e) { if (e.target === mask) close() })
   document.body.appendChild(mask)
@@ -3141,6 +3274,8 @@ function openBalanceAdjustment() {
     reset.disabled = !selected || !selected.correctedAt || busy
     if (!selected) {
       interval.textContent = '尚无可校正的余额观测。请先配置 DeepSeek API key 并成功刷新余额。'
+      creditsHint.textContent = ''
+      debitsHint.textContent = ''
       return
     }
     interval.textContent = '统计起点：' + accountingTime(selected.firstObservedAt) +
@@ -3148,8 +3283,8 @@ function openBalanceAdjustment() {
       '\n起点余额 ' + usageMoney(selected.openingBalance, selected.currency) +
       ' → 当前余额 ' + usageMoney(selected.currentBalance, selected.currency) +
       '\n当前：' + selected.label + ' ' + usageMoney(selected.amount, selected.currency)
-    creditsLabel.textContent = '本统计区间累计到账金额（' + selected.currency + '，未到账请填 0）'
-    debitsLabel.textContent = '非调用造成的余额减少（' + selected.currency + '，没有请填 0）'
+    creditsHint.textContent = '本统计区间累计到账金额（' + selected.currency + '，未到账请填 0）：包括充值、赠金等；多次到账请填合计，不要只填最后一笔。'
+    debitsHint.textContent = '非调用造成的余额减少（' + selected.currency + '，没有请填 0）：到期赠金、余额退回等。仅填写统计起点之后的金额；保存会替换之前的校正值。'
     credits.value = selected.credits == null ? '' : String(selected.credits)
     debits.value = selected.otherDebits == null ? '0' : String(selected.otherDebits)
     confirm.checked = false
@@ -3173,7 +3308,7 @@ function openBalanceAdjustment() {
     reset.disabled = true
     reload.disabled = true
     status.textContent = '正在刷新余额…'
-    fetch('/dsh-whale/balance-adjustments.json', { cache: 'no-store' })
+    fetch(adjustmentUrl, { cache: 'no-store' })
       .then(function (r) { return r.json() })
       .then(function (data) {
         if (!data.ok) throw new Error(data.error || '读取失败')
@@ -3198,16 +3333,29 @@ function openBalanceAdjustment() {
     reset.disabled = true
     reload.disabled = true
     status.textContent = '正在保存…'
-    fetch('/dsh-whale/balance-adjustments.json', {
+    fetch(adjustmentUrl, {
       method: 'PUT', headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify({
-        day: selected.day, revision: selected.revision, action: action,
+        modelId: modelId, day: selected.day, revision: selected.revision, action: action,
         credits: credits.value.trim(), otherDebits: debits.value.trim() || '0', confirmed: confirm.checked
       })
     })
       .then(function (r) { return r.json() })
       .then(function (data) {
         if (!data.ok) throw new Error(data.error || '保存失败')
+        // 保存后立刻用返回的摘要刷新该模型条目：关窗回到设置菜单时显示的就是新金额
+        var model = apiModelById(modelId)
+        var currentDay = new Date(Date.now() + 8 * 3600000).toISOString().slice(0, 10)
+        if (apiCanAdjustBalance(model) && data.summary && data.summary.day === currentDay) {
+          model.balance = data.summary.currentBalance
+          model.currency = data.summary.currency
+          model.todayUsage = data.summary.amount
+          model.todayUsageCurrency = data.summary.currency
+          model.usageSource = data.summary.source
+          model.usageLabel = data.summary.label
+          model.accounting = data.summary
+          model.error = null
+        }
         busy = false
         close()
         refresh(true)
@@ -3235,25 +3383,12 @@ function fillUsagePanel(d) {
   var today = d.today || {}
   var todayModels = today.models || []
   var hasEvToday = todayModels.length > 0
-  // ① 今日模型消费(独立容器+滚动)；标题不带下分隔线
-  var tToday = uSectionTitle(today.label || '今日消费', usageMoney(today.total, today.currency))
-  tToday.style.borderBottom = 'none'
-  wrap.appendChild(tToday)
-  var coverage = document.createElement('div')
-  coverage.className = 'dshwv-usage-hint'
-  coverage.style.cssText = 'line-height:1.65;white-space:normal;margin:4px 0'
-  coverage.textContent = today.firstObservedAt
-    ? '统计起点（北京）：' + accountingTime(today.firstObservedAt) + '。起点前的消费未计入。'
-    : '尚无余额观测；此处仅显示本机会话估算或旧版记录。'
-  if (today.needsReview) coverage.textContent += ' 检测到余额增加，请核对本区间累计到账。'
-  wrap.appendChild(coverage)
-  var adjustButton = document.createElement('button')
-  adjustButton.type = 'button'
-  adjustButton.className = 'dshwv-usage-more'
-  adjustButton.textContent = '充值 / 余额校正'
-  adjustButton.addEventListener('click', function (e) { e.stopPropagation(); openBalanceAdjustment() })
-  wrap.appendChild(adjustButton)
-  var modelTitle = uSectionTitle('本机模型费用 · 估算', usageMoney(today.modelTotal, 'CNY'))
+  // ① 本机模型费用（所有模型的本地会话估算）
+  // 「已观测消费」是 DeepSeek 账户口径（余额观测），已移到 小鲸鱼记账 → DeepSeek（内置）→ 设置 里，
+  // 与「余额校正」放在一起，避免在这里被误读成"全模型合计"。
+  var modelTitle = uSectionTitle('本机模型费用', usageMoney(today.modelTotal, 'CNY'))
+  // 标题与下方模型列表之间不再画分隔线（列表本身有边框，够了）
+  modelTitle.style.borderBottom = 'none'
   modelTitle.title = '按本机 DSH 会话计算，不按账户余额比例缩放；两者覆盖范围不同。'
   wrap.appendChild(modelTitle)
   var todayBox = document.createElement('div')
@@ -3456,7 +3591,7 @@ function resPlayFragment(fid) {
   try {
     if (!fid) return
     if (resAudEl) { try { resAudEl.pause() } catch (err) {} resAudEl = null }
-    var a = new Audio('/dsh-whale/audio-fragment.wav?id=' + encodeURIComponent(fid))
+    var a = dshwvSound('/dsh-whale/audio-fragment.wav?id=' + encodeURIComponent(fid))
     try { a.volume = Number(soundVol) || 0.9 } catch (err) {}
     a.onended = function () { resAudEl = null }
     resAudEl = a
@@ -8232,7 +8367,7 @@ var bubbleColorOpenMenu = null // 当前展开的颜色下拉(纯色/跑马灯,
 // —— 弹层/菜单层级统一助手(所有下拉与弹窗据此取高于当前可见层,避免互相压制) ——
 function visibleTopZ() {
   var top = 20500
-  var cand = [bubbleMask, bubbleItemMask, moduleMask, usageMoreMask, qeditEl, window.__dshwRemindMask]
+  var cand = [bubbleMask, bubbleItemMask, moduleMask, usageMoreMask, qeditEl, window.__dshwRemindMask, apiModelMaskEl, accountingMask]
   function eff(el) {
     try {
       if (!el) return 0
@@ -12108,6 +12243,16 @@ function artCenterAt(left, top, w, h, flipped) {
   var cy = top + h - iw / 2
   return { cx: cx, cy: cy }
 }
+// v739（用户反馈「每次新实例的第一次余额请求都失败」）：冷启动时凭据服务可能还没就绪，
+// 首次 DNS+TLS 也最慢；而客户端 25s 超时会先于宿主的两段重试结束 —— 结果是第一次必失败、
+// 只能干等 60 秒后的下一轮。这里失败后快速重试两次（1.5s / 3s），成功即重置计数。
+var balanceRetryLeft = 2
+function balanceRetryLater() {
+  if (balanceRetryLeft <= 0) return
+  var delay = balanceRetryLeft === 2 ? 1500 : 3000
+  balanceRetryLeft--
+  setTimeout(function () { try { refresh(false) } catch (err) {} }, delay)
+}
 function refresh(manual) {
   if (busy) return
   busy = true
@@ -12130,6 +12275,7 @@ function refresh(manual) {
         state.balance = nb
         state.currency = nc
         state.message = ''
+        balanceRetryLeft = 2
         state.todayUsage = data.todayUsage !== undefined ? data.todayUsage : null
         state.todayUsageCurrency = data.todayUsageCurrency || data.currency || 'CNY'
         state.usageLabel = data.usageLabel || '本地估算'
@@ -12165,12 +12311,14 @@ function refresh(manual) {
         state.status = 'error'
         state.message = (data && data.error) ? String(data.error) : '获取失败'
         render()
+        balanceRetryLater()
       }
     })
     .catch(function () {
       state.status = 'error'
       state.message = '获取失败'
       render()
+      balanceRetryLater()
     })
     .finally(function () {
       busy = false
@@ -12410,12 +12558,12 @@ function applySoundSet() {
     var pEmpty = audioGroupSlotEmpty(soundSet, 'press')
     var rEmpty = audioGroupSlotEmpty(soundSet, 'release')
     if (pEmpty) { pressAudio = null } else {
-      pressAudio = new Audio('/dsh-whale/sound/press.mp3?set=' + soundSet)
+      pressAudio = dshwvSound('/dsh-whale/sound/press.mp3?set=' + soundSet)
       pressAudio.preload = 'auto'
       pressAudio.volume = soundVol
     }
     if (rEmpty) { releaseAudio = null } else {
-      releaseAudio = new Audio('/dsh-whale/sound/release.mp3?set=' + soundSet)
+      releaseAudio = dshwvSound('/dsh-whale/sound/release.mp3?set=' + soundSet)
       releaseAudio.preload = 'auto'
       releaseAudio.volume = soundVol
     }
@@ -13449,12 +13597,12 @@ function audioEditPreviewEnsure(force) {
       if (audioEditPreviewRelease) { audioEditPreviewRelease.pause(); audioEditPreviewRelease = null }
     } catch (err) {}
     if (pressId) {
-      audioEditPreviewEl = new Audio('/dsh-whale/audio-fragment.wav?id=' + encodeURIComponent(pressId))
+      audioEditPreviewEl = dshwvSound('/dsh-whale/audio-fragment.wav?id=' + encodeURIComponent(pressId))
       audioEditPreviewEl.preload = 'auto'
       audioEditPreviewEl.volume = soundVol
     }
     if (releaseId) {
-      audioEditPreviewRelease = new Audio('/dsh-whale/audio-fragment.wav?id=' + encodeURIComponent(releaseId))
+      audioEditPreviewRelease = dshwvSound('/dsh-whale/audio-fragment.wav?id=' + encodeURIComponent(releaseId))
       audioEditPreviewRelease.preload = 'auto'
       audioEditPreviewRelease.volume = soundVol
     }
@@ -14616,8 +14764,6 @@ function pollLastTurn() {
 }
 setInterval(pollLastTurn, 1000)
 }
-// 主界面检测通过后执行挂件初始化（非主界面时 dshwInit 不会执行）
-if (dshwEnabled) {
-  try { dshwInit() } catch (err) {}
-}
+// 主界面检测通过（或稍后由 MutationObserver 检测到）后执行挂件初始化；非主界面不启动
+try { dshwTryStart(true) } catch (err) {}
 })()

package/lib/index.js

@@ -75,6 +75,11 @@ const API_FILE_CANDIDATES = [
   path.join(DSH_HOME, 'profiles', 'web', '.dshw-api.json'),
 ]
 const API_BUILTIN_ID = 'deepseek'
+// 「充值 / 余额校正」只属于固定的 DeepSeek（内置）：模型条目下发 canAdjustBalance，路由层再校验一次。
+// 新增厂商模板 / 手动新增的同名模型 / Kimi 等其它厂商都不会继承这个能力。
+function canAdjustBuiltinBalance(model) {
+  return !!(model && model.id === API_BUILTIN_ID && model.builtin === true && model.provider === 'deepseek')
+}
 // 内置厂商模板：balance 描述「怎么取余额」。json 路径支持 a.b[0].c；scale 为取值后的乘数。
 // 余额接口已按官方文档 / 社区参考核对（DeepSeek、OpenRouter、Kimi、阶跃、Novita、OpenAI 兼容中转站）；
 // 硅基流动的余额接口已官方下线（410），故改为「无余额接口 + /v1/models 探活」；
@@ -711,11 +716,19 @@ export default {
     }
 
     async function fetchBalance() {
-      let cred
-      try {
-        cred = await ctx.credentials.resolve('DEEPSEEK_API_KEY')
-      } catch (err) {
-        return { ok: false, code: 'NO_KEY', error: '凭据读取失败: ' + String((err && err.message) || err).slice(0, 160) }
+      // v739（用户反馈「每次新实例的第一次余额请求都失败」）：
+      // ① 冷启动时凭据服务可能尚未就绪（resolve 抛错），这与「确实没配置」不同 → 短延迟重试一次；
+      // ② 单次超时从 20s 收到 8s，保证「2 次尝试 + 退避」明显短于前端 FETCH_TIMEOUT_MS(25s) ——
+      //    否则前端先 abort，用户看到的永远是「第一次失败」，只能干等 60 秒后的下一轮。
+      let cred = null
+      for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+          cred = await ctx.credentials.resolve('DEEPSEEK_API_KEY')
+          break
+        } catch (err) {
+          if (attempt === 0) { await new Promise((r) => setTimeout(r, 700)); continue }
+          return { ok: false, code: 'NO_KEY', error: '凭据读取失败: ' + String((err && err.message) || err).slice(0, 160) }
+        }
       }
       if (!cred) {
         return { ok: false, code: 'NO_KEY', error: '未配置 DEEPSEEK_API_KEY' }
@@ -726,7 +739,7 @@ export default {
         try {
           res = await fetch(BALANCE_URL, {
             headers: { Authorization: 'Bearer ' + cred.value },
-            signal: AbortSignal.timeout(20000),
+            signal: AbortSignal.timeout(8000),
           })
         } catch (err) {
           lastErr = err
@@ -916,7 +929,7 @@ export default {
       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, version: '0.3.1', today: todayData, days7,
+        ok: true, version: '0.3.3', 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),
@@ -1824,6 +1837,7 @@ export default {
         let entry = {
           id: m.id, name: m.name, provider: m.provider, currency: m.currency,
           keyRef: m.keyRef, builtin: !!m.builtin, baseUrl: m.baseUrl || '',
+          canAdjustBalance: canAdjustBuiltinBalance(m),
           matchIds: m.matchIds || [], settings: settings.models && settings.models[m.id] ? settings.models[m.id] : null,
           price: m.price || null,
           // 手动额度（订阅/资源包）：总量、单位、已用、重置周期；前端据此显示额度模块
@@ -1959,7 +1973,7 @@ export default {
       const led = readUsageLedger()
       const summary = daySummary(led, todayKey())
       return {
-        ...visible, version: '0.3.1', isPeak: isPeakTime(Math.floor(Date.now() / 1000)),
+        ...visible, version: '0.3.3', 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()),
@@ -2498,9 +2512,23 @@ export default {
       path: '/dsh-whale/balance-adjustments.json',
       handler: async (req, res) => {
         try {
+          // 先核对身份再碰余额或账本：必须是唯一且明确的 DeepSeek（内置）。
+          // 新增厂商模板不会自动继承这个能力，也拒绝其它模型读写校正。
+          const targetIds = new URL(req.url || '/', 'http://localhost').searchParams.getAll('modelId')
+          const targetModelId = targetIds.length === 1 ? targetIds[0] : null
+          if (targetModelId !== API_BUILTIN_ID || !canAdjustBuiltinBalance(apiModelById(targetModelId))) {
+            const error = new Error('余额校正仅支持 DeepSeek（内置），请从该模型的设置菜单进入')
+            error.status = 403
+            throw error
+          }
           if (req.method === 'PUT') {
             const input = JSON.parse(await readBodyMax(req, 8192))
             if (!input || typeof input !== 'object') throw new Error('校正内容无效')
+            if (input.modelId !== targetModelId) {
+              const error = new Error('校正请求的模型不匹配，仅支持 DeepSeek（内置）')
+              error.status = 403
+              throw error
+            }
             if (input.day === todayKey()) {
               const fresh = await getBalance(true)
               if (!fresh.ok || fresh.stale) {

package/package.json

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