dsh-whale-widget 0.3.18 → 0.4.0

package/lib/index.js

@@ -4,6 +4,8 @@ import path from 'node:path'
 import dns from 'node:dns'
 import { fileURLToPath } from 'node:url'
 import { createHash } from 'node:crypto'
+import https from 'node:https'
+import { exec } from 'node:child_process'
 import {
   preciseMoney, addMoney, sumMoney, beijingDay, dayOffset,
   observeBalance, balanceSummary, daySummary, accountingDays, reconcileBalance,
@@ -36,6 +38,57 @@ const IMAGE_CANDIDATES = [
 //   ⚠️ `_strip-dev-paths.mjs` 会把发布副本里含开发机路径的行删掉，发布版只剩前两条 $DSH_HOME ✓
 const DATA_CANDIDATES_TAIL = [
 ]
+// v790（用户要求）：菜单底部那行小字显示什么版本。
+//   · 发布版：显示当前版本（= package.json 的 version）
+//   · 开发版：显示**下一个补丁号 + beta**（例如 0.3.18 的开发版显示 0.3.19-beta），
+//     因为开发版里的改动属于"将要发布的那一版"。
+//   ⚠️ BUILD_VERSION 与下面 payload 里两处 `version: '…'` 一起由 `_bump-version.mjs` 更新；
+//   ⚠️ BUILD_CHANNEL 由 `_strip-dev-paths.mjs` 在生成发布副本时改成 'release'（发布副本不带 dev 标记）。
+const BUILD_VERSION = '0.4.0'
+const BUILD_CHANNEL = 'release'
+function versionLabelOf(version, channel) {
+  const s = String(version == null ? '' : version)
+  if (String(channel) !== 'dev') return s
+  const m = /^(\d+)\.(\d+)\.(\d+)$/.exec(s)
+  if (!m) return s ? s + '-beta' : ''
+  return m[1] + '.' + m[2] + '.' + (Number(m[3]) + 1) + '-beta'
+}
+const VERSION_LABEL = versionLabelOf(BUILD_VERSION, BUILD_CHANNEL)
+// v793（用户要求）：点菜单底部的版号 → 「关于 / 自检」面板。这一层配套的敏感信息处理：
+//   面板与「复制诊断信息」只允许出现**白名单字段**；任何路径都先脱敏（用户名 → %USERPROFILE%、DSH 目录 → $DSH_HOME），
+//   **绝不包含** API key、账号 id、账本明细、会话内容。所有字段的组装集中在 aboutPayload()，便于审计。
+function maskPath(input) {
+  let s = String(input == null ? '' : input)
+  try {
+    // ⚠️ 顺序要紧：先替换**更长的、更具体的** DSH_HOME，再替换家目录。
+    //    反过来的话 `C:\Users\x\.dsh\...` 会先被压成 `%USERPROFILE%\.dsh\...`，$DSH_HOME 就再也匹配不到了（探针抓到过）。
+    if (DSH_HOME) {
+      s = s.split(DSH_HOME).join('$DSH_HOME')
+      s = s.split(String(DSH_HOME).replace(/\\/g, '/')).join('$DSH_HOME')
+    }
+    const home = os.homedir()
+    if (home) {
+      s = s.split(home).join('%USERPROFILE%')
+      s = s.split(home.replace(/\\/g, '/')).join('%USERPROFILE%')
+    }
+    // 兜底：任何盘符/家目录形态的用户名段
+    s = s.replace(/[A-Za-z]:\\Users\\[^\\/]+/g, '%USERPROFILE%')
+    s = s.replace(/\/(Users|home)\/[^\/]+/g, '%USERPROFILE%')
+  } catch (err) {}
+  return s
+}
+function fileFacts(file) {
+  try {
+    const st = fs.statSync(file)
+    return { bytes: st.size, mtime: st.mtimeMs }
+  } catch (err) { return null }
+}
+function firstExisting(list) {
+  for (const p of (list || [])) {
+    try { if (fs.existsSync(p)) return p } catch (err) {}
+  }
+  return ''
+}
 // ⭐ 2026-10-02（用户要求"并成一份"）：**角色图库目录也 $DSH_HOME 优先**（开发机路径降级为兜底）。
 const ROLE_DIR_CANDIDATES = [
   path.join(DSH_HOME, 'whale-roles'),
@@ -70,6 +123,14 @@ const PRESET_FRAGMENTS = {
   // 任务结束音 A(随包资源):原为用户音效库里的自导入片段，现作为内置预设随包发布。
   // 显示名与用户库里同名片段一致时，前端下拉按显示名去重（内置与前端的同名条目只出现一条）。
   end_a: { id: 'end_a', name: 'A', preset: true, mime: 'audio/wav' },
+  // v859（用户要求）：把"当前正在使用的"三个音效固化为**新的出厂默认**（随包发布，新装即此体验）
+  //   · cost_a    = 每轮消耗提示（走 taskEnd.sel）
+  //   · ask_a     = 提问提示（走 events.question.sel）
+  //   · approve_a = 授权提示（走 events.approval.sel）
+  //   与 end_a 同一套做法：原为用户音效库里的自导入片段，现作为内置预设随包发布。
+  cost_a: { id: 'cost_a', name: '每轮消耗·默认', preset: true, mime: 'audio/wav' },
+  ask_a: { id: 'ask_a', name: '提问·默认', preset: true, mime: 'audio/wav' },
+  approve_a: { id: 'approve_a', name: '授权·默认', preset: true, mime: 'audio/wav' },
 }
 // 内置片段的音频文件：包内 assets 优先，开发环境回退到 skin 目录
 const BUILTIN_FRAGMENT_FILES = {
@@ -80,6 +141,16 @@ const BUILTIN_FRAGMENT_FILES = {
   end_a: [
     path.join(PACKAGE_ROOT, 'assets', 'task-end-a.wav'),
   ],
+  // v859：三个新的出厂默认音效（随包 assets；开发环境回退到 skin 目录）
+  cost_a: [
+    path.join(PACKAGE_ROOT, 'assets', 'cost-default.wav'),
+  ],
+  ask_a: [
+    path.join(PACKAGE_ROOT, 'assets', 'ask-default.wav'),
+  ],
+  approve_a: [
+    path.join(PACKAGE_ROOT, 'assets', 'approve-default.wav'),
+  ],
 }
 // —— 自定义 API 模型（v655）：非 DeepSeek 厂商的余额 / 用量 / 提醒 ——
 // 注册表落在 $DSH_HOME/.dshw-api.json；密钥走 DSH 官方凭据（ctx.credentials），本文件不存明文。
@@ -265,9 +336,12 @@ const API_TEMPLATES = {
   },
   anthropic: {
     name: 'Anthropic Claude', currency: 'USD', keyRef: 'ANTHROPIC_API_KEY', noBalanceApi: true,
-    apiNote: '官方无余额接口；用量要走 Admin API（需 admin key）或控制台。注意其探活需要 x-api-key + anthropic-version 两个请求头，本挂件暂不支持 → 不提供探活',
+    // v791：请求头支持「分号分隔列表」后，探活这条路终于能走了 —— Anthropic 要求 x-api-key + anthropic-version 两个头。
+    //   官方**没有余额接口**（余额/用量只能去控制台或 Admin API），所以这里只提供探活与模型列表。
+    apiNote: '官方无余额接口（余额/用量见控制台，或按会话 token 估算）。探活走 /v1/models：需要 x-api-key + anthropic-version 两个请求头（v791 起支持，模板已预置）',
     matchIds: ['claude'],
-    balance: { url: '', auth: 'Bearer {key}', json: { remaining: '' } },
+    balance: { url: '', auth: 'x-api-key:{key};anthropic-version:2023-06-01', json: { remaining: '' } },
+    probeUrl: 'https://api.anthropic.com/v1/models',
   },
   gemini: {
     name: 'Google Gemini', currency: 'USD', keyRef: 'GEMINI_API_KEY', noBalanceApi: true,
@@ -841,9 +915,14 @@ export default {
     function finalizeTurn(sessionId) {
       const agg = turnAggs.get(sessionId)
       if (agg && agg.cost > 0) {
+        // v862/v862b：子智能体的会话**照常记账**（金额与用量事件都写），
+        //   只在「子智能体完成时不提示」开着时跳过 lastTurnSeq ⇒ 前端不会因为它响提示音。
+        const isSub = subagentSessions.has(String(sessionId || '')) && subagentMuteOn()
         lastTurn = { turn: agg.turn, amount: agg.cost, tokens: agg.tokens, ts: agg.lastTs }
-        lastTurnSeq++
-        writeTurnSeq(lastTurnSeq)
+        if (!isSub) {
+          lastTurnSeq++
+          writeTurnSeq(lastTurnSeq)
+        }
         // 按模型拆分写入用量事件(模型明细的唯一来源)
         const byModel = agg.byModel || {}
         const byModelTokens = agg.byModelTokens || {}
@@ -1007,6 +1086,44 @@ export default {
       } catch (err) {}
     }
 
+    // v862（用户实测确认：跑一次子智能体，last-turn 的 seq 会 +1 ⇒ 前端跟着响"任务结束音"）——
+    //   机制：finalizeTurn(sessionId) 对**每个 session 的 turn/end** 都推进 lastTurnSeq，
+    //   子智能体跑完自己的 turn 同样让 seq 变大 ⇒ 响。实测：seq 362 →（子智能体跑完）→ 363。
+    //   区分依据（DSH Host Event 契约，已用 Inspector 核对）：
+    //     'subagent/start'(info: SubagentRunInfo)   info = { runId, provider, id: SessionId, local }
+    //     'subagent/end'(info: SubagentRunEndInfo)  info = { runId, provider, id, local, stopReason, … }
+    //   ⇒ 子会话 id = info.id。
+    // v862b（用户要求）：做成**设置项**「子智能体完成时不提示」（键 = settings.subagent.mute，默认 true）。
+    let subagentMuteCache = { at: 0, val: true }
+    function subagentMuteOn() {
+      try {
+        const now = Date.now()
+        if (now - subagentMuteCache.at < 2000) return subagentMuteCache.val
+        const s = readUsageSettings() || {}
+        const sg = (s && typeof s.subagent === 'object' && s.subagent) ? s.subagent : {}
+        subagentMuteCache = { at: now, val: sg.mute !== false } // 缺省 = 不提示
+      } catch (err) {
+        subagentMuteCache = { at: Date.now(), val: true }
+      }
+      return subagentMuteCache.val
+    }
+    const subagentSessions = new Set()
+    const SUBAGENT_ID_MAX = 500
+    function rememberSubagentSession(info) {
+      try {
+        const id = info && info.id ? String(info.id) : ''
+        if (!id || subagentSessions.has(id)) return
+        if (subagentSessions.size >= SUBAGENT_ID_MAX) {
+          const keep = Array.from(subagentSessions).slice(-Math.floor(SUBAGENT_ID_MAX / 2))
+          subagentSessions.clear()
+          for (const k of keep) subagentSessions.add(k)
+        }
+        subagentSessions.add(id)
+      } catch (err) {}
+    }
+    try { disposers.push(ctx.on('subagent/start', (info) => rememberSubagentSession(info))) } catch (err) {}
+    try { disposers.push(ctx.on('subagent/end', (info) => rememberSubagentSession(info))) } catch (err) {}
+
     // 监听所有会话的追加事件；按会话 id 分桶，turn/end 时结算该会话本轮
     disposers.push(ctx.on('session/event', (session, event) => {
       const sid = session && session.id ? session.id : 'default'
@@ -1263,15 +1380,44 @@ export default {
         }
       }
     }
+    // v860（issue #232 / #225）：账本文件损坏时**不再抛错锁死**。
+    //   旧行为：JSON 解析失败或结构不对就 throw ⇒ 一个坏文件让"读不了、写不了、不自愈"，
+    //   余额/今日已用/额度/音效设置一起失效，只能用户手删文件。
+    //   新行为：把坏文件**改名备份**（.corrupt-<时间戳>.bak，数据不丢）→ 用默认结构继续跑，
+    //   插件立刻恢复可用；控制台留一条 message 方便排查。
+    function freshUsageLedger() {
+      return { date: todayKey(), lastBalance: null, todayUsage: 0, history: {} }
+    }
+    function ledgerBackupCorrupt(p, why) {
+      try {
+        const bak = p + '.corrupt-' + Date.now() + '.bak'
+        ledgerIo(() => fs.renameSync(p, bak))
+        console.error('[whale-ledger] 账本损坏（' + why + '）→ 已备份为 ' + bak + '，并用默认结构重建（原文件未删除）')
+      } catch (err) {
+        console.error('[whale-ledger] 账本损坏（' + why + '）且备份失败：', (err && err.code) || (err && err.message)) 
+      }
+    }
     function readUsageLedger() {
       for (const p of USAGE_FILE_CANDIDATES) {
+        let raw = null
+        try {
+          raw = ledgerIo(() => fs.readFileSync(p, 'utf8'))
+        } catch (err) {
+          if (err.code === 'ENOENT') continue // 该候选路径没有文件：试下一个（正常情况）
+          ledgerBackupCorrupt(p, (err && err.code) || 'read-error')
+          return freshUsageLedger()
+        }
         try {
-          const parsed = JSON.parse(ledgerIo(() => fs.readFileSync(p, 'utf8')))
+          const parsed = JSON.parse(raw)
           if (parsed && typeof parsed === 'object' && typeof parsed.date === 'string') return parsed
-          throw new Error('账本结构异常，已停止写入以保护原记录')
-        } catch (err) { if (err.code !== 'ENOENT') throw err }
+          ledgerBackupCorrupt(p, 'bad-structure')
+          return freshUsageLedger()
+        } catch (err) {
+          ledgerBackupCorrupt(p, 'bad-json')
+          return freshUsageLedger()
+        }
       }
-      return { date: todayKey(), lastBalance: null, todayUsage: 0, history: {} }
+      return freshUsageLedger()
     }
     function writeUsageLedger(led) {
       const body = JSON.stringify(led)
@@ -1402,7 +1548,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.18', today: todayData, days7,
+        ok: true, version: '0.4.0', versionLabel: VERSION_LABEL, 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),
@@ -1442,13 +1588,17 @@ export default {
         //    没有它就无法区分"默认 100%"与"用户设了 100%"，前端 soundVolumeOf() 靠它决定优先级。
         //    ⚠️ 与前端 soundEventDefaults().turnCost **必须逐字段一致**（探针 §⑥ 跨端一致钉住）。
         turnCost: { vol: 1, volSet: false, bubbleOn: true },
-        question: { on: true, soundOn: false, sel: 'frag:exp_orb', vol: 1, autoClose: true, ttlSec: 180, bubbleOn: true, lines: waitDefaultLines('question') },
-        approval: { on: true, soundOn: false, sel: 'frag:exp_orb', vol: 1, autoClose: true, ttlSec: 180, bubbleOn: true, lines: waitDefaultLines('approval') },
+        // v859：提问/授权的出厂默认音效改为随包内置的 ask_a / approve_a（= 当前正在用的那两个）
+        question: { on: true, soundOn: false, sel: 'frag:ask_a', vol: 1, autoClose: true, ttlSec: 180, bubbleOn: true, lines: waitDefaultLines('question') },
+        approval: { on: true, soundOn: false, sel: 'frag:approve_a', vol: 1, autoClose: true, ttlSec: 180, bubbleOn: true, lines: waitDefaultLines('approval') },
       }
     }
     function usageSettingsDefaults() {
       return {        // 任务结束音：v774 起出厂默认 = **开**（作者当前用法），默认音 = 内置 A（end_a）
-        taskEnd: { on: true, sel: 'frag:end_a' },
+        // v859：任务结束/每轮消耗音的出厂默认改为随包内置的 cost_a（= 当前正在用的那一个）
+        taskEnd: { on: true, sel: 'frag:cost_a' },
+        // v863：子智能体完成是否提示（默认 true = 不提示；键 = settings.subagent.mute）
+        subagent: { mute: true },
         // v777：「等待交互提示」的交互开关（用户 2026-09-26 要求）
         //   charClose=false（出厂默认）＝ 只有**点泡泡**能收起等待提示；true ＝ **点角色**也能收起。
         //   两种情况下"点掉的那条挂起"都不会再被每秒轮询自动弹回（前端 waitDismissedId）。
@@ -1502,6 +1652,15 @@ export default {
       if (s.alert && typeof s.alert === 'object') d.alert = Object.assign({}, d.alert, s.alert)
       if (s.budget && typeof s.budget === 'object') d.budget = Object.assign({}, d.budget, s.budget)
       if (s.turnCost && typeof s.turnCost === 'object') d.turnCost = Object.assign({}, d.turnCost, s.turnCost)
+      // v812（用户报"点按角色关闭提示气泡不会被保存"）：这一项**写进去了却读不回来** ——
+      //   写侧一直有（writeUsageSettings 的 `p.wait` 分支，磁盘上确实存着 {"charClose":true}），
+      //   但读侧漏了 ⇒ GET 永远下发默认 false ⇒ 面板显示与运行期行为都被"打回默认"，看着就像没保存。
+      //   ⚠️ 凡是 writeUsageSettings 支持的键，这里都必须有对应的读回分支（本轮核对过：
+      //   taskEnd / alert / budget / turnCost / wait / events / models —— 当时只漏了 wait）。
+      if (s.wait && typeof s.wait === 'object') d.wait = Object.assign({}, d.wait, { charClose: !!s.wait.charClose })
+      // v863：子智能体完成是否提示（默认 true = 不提示）。写侧有分支、读侧也必须合并，
+      //   否则刷新后前端读回的是默认值（"保存了但不生效"的经典半截活）。
+      if (s.subagent && typeof s.subagent === 'object') d.subagent = Object.assign({}, d.subagent, { mute: s.subagent.mute !== false })
       // v761（全局音效设置）：四个事件逐个合并（缺字段回落到默认，不整块替换）
       if (s.events && typeof s.events === 'object') {
         for (const k of Object.keys(d.events)) {
@@ -1537,6 +1696,12 @@ export default {
       if (p.turnCost && typeof p.turnCost === 'object') led.settings.turnCost = Object.assign({}, led.settings.turnCost || {}, p.turnCost)
       // v777：「等待交互提示」的交互开关（点角色是否也能关闭等待提示气泡）
       if (p.wait && typeof p.wait === 'object') led.settings.wait = Object.assign({}, led.settings.wait || {}, p.wait)
+      // v863（用户报"取消勾选保存后重开仍是勾选"）：**写侧原来没有 subagent 分支** ⇒
+      //   前端 PUT 的 { subagent: { mute:false } } 被静默丢掉，重开只能读到默认值(true=不提示)。
+      //   这里只放行 mute 一个键（与其它分支一样，白名单式合并）。
+      if (p.subagent && typeof p.subagent === 'object') {
+        led.settings.subagent = Object.assign({}, led.settings.subagent || {}, { mute: p.subagent.mute !== false })
+      }
       // v761（全局音效设置）：events 补丁逐事件合并（前端只发改动的那几个字段）
       if (p.events && typeof p.events === 'object') {
         led.settings.events = led.settings.events && typeof led.settings.events === 'object' ? led.settings.events : {}
@@ -1556,7 +1721,7 @@ export default {
         led.settings.wait = { charClose: false }
         // 任务结束音也属于「音效类键」：宿主重置与面板显示必须口径一致（否则面板显示与真实状态撕裂）
         // v774：重置目标 = 新的出厂默认（开 + 内置 A）
-        led.settings.taskEnd = { on: true, sel: 'frag:end_a' }
+        led.settings.taskEnd = { on: true, sel: 'frag:cost_a' }
       }      // 按模型保存提醒/预算：{ modelId, alert?, budget? }
       if (p.modelSettings && p.modelSettings.id) {
         const mid = String(p.modelSettings.id)
@@ -1854,7 +2019,13 @@ export default {
     let codexCatchupT = null
     // 配置变更（例如用户在设置里关掉 Codex 统计）后必须让快照失效，
     // 否则下一次请求还会命中关闭前的旧快照、开关看起来"没生效"。
-    function codexInvalidate() { codexSnap = null; codexSnapAt = 0; codexStatsOnV = null; codexStatsOnAt = 0 }
+    function codexInvalidate() {
+      codexSnap = null; codexSnapAt = 0; codexStatsOnV = null; codexStatsOnAt = 0
+      // v792：设置/注册表一变，**立刻**按新状态装载或摘掉预热定时器
+      // （开关打开 ⇒ 马上挂上并预热；关掉 / 删掉 Codex 模型 ⇒ 一个定时器都不留）。
+      // try/catch 是必要的：初始化期若在 `let codexPrewarmT` 求值之前走到这里，会撞 const/let 的 TDZ。
+      try { codexRearmPrewarm(true) } catch (err) {}
+    }
     // 开关读取加 2 秒缓存：codexBackgroundRefresh 可能被高频调用（快照过期时每次 payload
     // 构建都会试一次），而 readSizeConfig() 是同步文件读 —— 不能放在热路径上。
     // 用户改设置时 codexInvalidate() 会清掉缓存，所以开关仍然是"立刻生效"。
@@ -1871,18 +2042,17 @@ export default {
       } catch (err) {}
       return false
     }
+    function codexStatsEnabledFresh() {
+      try {
+        if (!hasCodexModel()) return false // 没有 Codex 模型 → 默认关闭（不是"用户关掉的"，见下面的提示文案）
+        const cfg = readSizeConfig()
+        return !cfg || cfg.codexStatsOn !== false
+      } catch (err) { return false }
+    }
     function codexStatsOn() {
       const now = Date.now()
       if (codexStatsOnV !== null && now - codexStatsOnAt < 2000) return codexStatsOnV
-      let v = true
-      try {
-        if (!hasCodexModel()) {
-          v = false // 没有 Codex 模型 → 默认关闭（不是"用户关掉的"，见下面的提示文案）
-        } else {
-          const cfg = readSizeConfig()
-          v = !cfg || cfg.codexStatsOn !== false
-        }
-      } catch (err) { v = true }
+      const v = codexStatsEnabledFresh()
       codexStatsOnV = v
       codexStatsOnAt = now
       return v
@@ -1930,21 +2100,38 @@ export default {
       try { await Promise.race([p, new Promise((r) => setTimeout(r, Math.max(200, maxWaitMs || 2500)))]) } catch (err) {}
       return codexSnap
     }
-    // 后台预热：启动后预热一次，并每 5 分钟刷新一次缓存（现在都是异步 + 有预算的，不再阻塞）。
+    // 后台预热：**只在真的配了 Codex 时才挂定时器**（v792，用户要求"没设置 Codex 就完全禁用扫描"）。
+    //   背景：真正读盘的 `codexScan()` 早已被 `codexStatsOn()` 拦住（没 Codex 模型 ⇒ 直接返回，一行 I/O 都不做），
+    //   但那两个定时器仍会照常触发、每次都去读一遍注册表判"有没有 Codex 模型"。既然用户明确要求"完全禁用"，
+    //   这里改成**惰性装载**：启动时没有 Codex 模型 ⇒ **连定时器都不挂**；之后用户添加/删除 Codex 模型时由
+    //   `codexRearmPrewarm()` 按需挂上/摘掉（见模型保存路径）。
     let codexPrewarmT = null, codexPrewarmI = null
+    function codexPrewarmArmed() { return codexPrewarmT !== null || codexPrewarmI !== null }
+    function codexDisarmPrewarm() {
+      try { if (codexPrewarmT !== null) { clearTimeout(codexPrewarmT); codexPrewarmT = null } } catch (err) {}
+      try { if (codexPrewarmI !== null) { clearInterval(codexPrewarmI); codexPrewarmI = null } } catch (err) {}
+      try { if (codexCatchupT !== null) { clearTimeout(codexCatchupT); codexCatchupT = null } } catch (err) {}
+    }
+    function codexRearmPrewarm(immediate) {
+      // ⚠️ 这里用**不带 memo** 的 fresh 判断：装载/改设置都要立刻生效，
+      //    也不能把结果写进 `codexStatsOnV` 那份 2 秒记忆（否则刚改完设置会被旧值挡住，v792 踩过）。
+      const on = codexStatsEnabledFresh()
+      if (!on) { codexDisarmPrewarm(); return false }
+      // 已经挂着就什么都不做（避免每次保存模型都触发一次扫描；5 分钟轮询 + 按需 codexSummaryEnsured 已够）
+      if (codexPrewarmArmed()) return true
+      try {
+        codexPrewarmT = setTimeout(function () { codexPrewarmT = null; try { codexBackgroundRefresh(0) } catch (err) {} }, immediate ? 0 : 1500)
+        codexPrewarmI = setInterval(function () { try { codexBackgroundRefresh(0) } catch (err) {} }, 5 * 60 * 1000)
+        // issue #109：句柄必须存下并进 disposers，否则插件 dispose 后 interval 仍在引用事件循环（退出 dsh 卡住）。
+        try { if (codexPrewarmT && codexPrewarmT.unref) codexPrewarmT.unref() } catch (err) {}
+        try { if (codexPrewarmI && codexPrewarmI.unref) codexPrewarmI.unref() } catch (err) {}
+      } catch (err) {}
+      return true
+    }
     try {
-      codexPrewarmT = setTimeout(function () { try { codexBackgroundRefresh(0) } catch (err) {} }, 1500)
-      codexPrewarmI = setInterval(function () { try { codexBackgroundRefresh(0) } catch (err) {} }, 5 * 60 * 1000)
-      // issue #109：这两个定时器原先不存句柄、也不进 disposers，插件树 dispose 之后
-      // 事件循环里仍有一个被引用的 interval → 用户退出 dsh 时进程不结束（只能 Ctrl+C）。
-      // 存句柄并纳入 disposers，卸载时一并清掉；unref 作为兜底（正常运行时由 HTTP 服务维持事件循环）。
-      try { if (codexPrewarmT && codexPrewarmT.unref) codexPrewarmT.unref() } catch (err) {}
-      try { if (codexPrewarmI && codexPrewarmI.unref) codexPrewarmI.unref() } catch (err) {}
-      disposers.push(function () {
-        if (codexPrewarmT !== null) { clearTimeout(codexPrewarmT); codexPrewarmT = null }
-        if (codexPrewarmI !== null) { clearInterval(codexPrewarmI); codexPrewarmI = null }
-        if (codexCatchupT !== null) { clearTimeout(codexCatchupT); codexCatchupT = null }
-      })
+      // 启动时按需装载：没配 Codex ⇒ 一个定时器都不建（这就是"完全禁用"）
+      codexRearmPrewarm(false)
+      disposers.push(function () { codexDisarmPrewarm() })
     } catch (err) {}
     // ===== 自定义 API 模型注册表（v655）=====
     // 文件：$DSH_HOME/.dshw-api.json → { version, models:[…], usage:{ [id]:{day,dayStart,lastBalance,delta,eventCost} } }
@@ -1964,10 +2151,14 @@ export default {
     }
     function writeApiRegistry(reg) {
       const body = JSON.stringify(reg, null, 2)
+      let ok = false
       for (const p of API_FILE_CANDIDATES) {
-        try { fs.writeFileSync(p, body, 'utf8'); return true } catch (err) {}
+        try { fs.writeFileSync(p, body, 'utf8'); ok = true; break } catch (err) {}
       }
-      return false
+      // v792（用户要求）：注册表变了 ⇒ 重新评估要不要挂 Codex 预热。
+      //   加了 Codex 模型 → 立刻挂上（并马上预热一次）；删掉了 / 用户关了开关 → 摘掉定时器（连定时器都不留）。
+      try { if (ok) codexRearmPrewarm(true) } catch (err) {}
+      return ok
     }
     function apiTemplateOf(provider) {
       return API_TEMPLATES[String(provider || '')] || null
@@ -2139,11 +2330,62 @@ export default {
       const m = String((cfg && cfg.method) || 'GET').trim().toUpperCase()
       return /^[A-Z]{3,7}$/.test(m) ? m : 'GET'
     }
+    // v791（用户要求 + 安全加固）：请求头支持「英文分号分隔的 头名:值 列表」。
+    //   语义：`auth` 从"Authorization 头的值"升级为**请求头列表**，例如
+    //     x-api-key:{key};anthropic-version:2023-06-01
+    //   向后兼容：**不带冒号**的写法（`Bearer {key}` / `{key}`）仍按 **Authorization 头**处理
+    //   ⇒ 30 个内置模板与所有老用户配置一个字都不用改。
+    //   ⚠️ 安全（这是本能力最容易出事的地方，逐条设防）：
+    //     ① 头名必须匹配 RFC7230 的 token 字符集（杜绝 `X: a` 这类含空格/控制字符的名字）；
+    //     ② **禁** Host / Content-Length / Connection / Transfer-Encoding / TE / Upgrade / Cookie /
+    //        Proxy-* / Keep-Alive —— 这些能绕过宿主的 Host 信任栅栏（`DSHW_TRUSTED_HOSTS`）、
+    //        或制造请求走私；被忽略的头会在日志里提示一次（不静默）；
+    //     ③ 头值去掉 CR/LF（防头注入）并限长；单次最多 10 个头；整串限长 2000；
+    //     ④ `{key}` 只在**值**里替换（头名不参与），且密钥永不回显/打日志。
+    const HEADER_NAME_RE = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/
+    const HEADER_DENY = new Set(['host', 'content-length', 'connection', 'transfer-encoding', 'te', 'upgrade',
+      'cookie', 'proxy-authorization', 'proxy-connection', 'keep-alive'])
+    const HEADER_MAX_COUNT = 10
+    const HEADER_NAME_MAX = 64
+    const HEADER_VALUE_MAX = 1000
+    const HEADER_RAW_MAX = 2000
+    const headerWarned = new Set()
+    function headerWarnOnce(name) {
+      const k = String(name)
+      if (headerWarned.has(k)) return
+      headerWarned.add(k)
+      try { console.warn('[dsh-whale] 已忽略请求头「' + k + '」（安全策略：非法头名或禁止的头）') } catch (err) {}
+    }
+    function headersFromAuth(auth, key) {
+      const out = {}
+      let raw = String(auth == null ? 'Bearer {key}' : auth)
+      if (raw.length > HEADER_RAW_MAX) raw = raw.slice(0, HEADER_RAW_MAX)
+      let count = 0
+      for (const seg of raw.split(';')) {
+        const s = seg.trim()
+        if (!s) continue
+        const i = s.indexOf(':')
+        if (i === 0) continue // 「:xxx」没有头名 → 跳过
+        const name = (i > 0 ? s.slice(0, i) : 'Authorization').trim()
+        let value = (i > 0 ? s.slice(i + 1) : s).trim()
+        if (!name || !value) continue
+        if (name.length > HEADER_NAME_MAX || !HEADER_NAME_RE.test(name)) { headerWarnOnce(name); continue }
+        if (HEADER_DENY.has(name.toLowerCase())) { headerWarnOnce(name); continue }
+        if (!Object.prototype.hasOwnProperty.call(out, name) && count >= HEADER_MAX_COUNT) continue
+        value = value.replace(/[\r\n]+/g, ' ').slice(0, HEADER_VALUE_MAX).replace('{key}', String(key == null ? '' : key))
+        out[name] = value
+        count++
+      }
+      return out
+    }
+    function headerNameExists(headers, lowerName) {
+      for (const k of Object.keys(headers)) if (k.toLowerCase() === lowerName) return true
+      return false
+    }
     async function apiFetchJson(url, auth, key, opts) {
       const o = opts || {}
-      const headers = {}
-      const a = String(auth == null ? 'Bearer {key}' : auth)
-      if (a) headers.Authorization = a.replace('{key}', key)
+      // v791：头列表（默认值仍是单个 Authorization，与老行为逐字节一致）
+      const headers = headersFromAuth(auth, key)
       // v724：URL 里也支持 {key}（如 Gemini 的 ?key=… 形式；auth 传空串时不带 Authorization 头）
       const u = String(url).replace('{key}', key)
       assertSafeApiUrl(u)
@@ -2153,7 +2395,8 @@ export default {
         init.method = method
         const raw = o.body
         if (raw !== undefined && raw !== null && String(raw).length) {
-          headers['Content-Type'] = 'application/json'
+          // 用户自己在头列表里写了 Content-Type 就用他的（不覆盖）
+          if (!headerNameExists(headers, 'content-type')) headers['Content-Type'] = 'application/json'
           init.body = bodyWithPlaceholders(raw, key, o.base, o.params)
         }
       }
@@ -2611,7 +2854,7 @@ export default {
         const qj = {}
         const pathOf = (v) => String(v || '').slice(0, 200)
         if (p.quota.url) qj.url = String(p.quota.url).slice(0, 500)
-        if (p.quota.auth !== undefined) qj.auth = String(p.quota.auth || '').slice(0, 200)
+        if (p.quota.auth !== undefined) qj.auth = String(p.quota.auth || '').slice(0, 1000)
         const jin = p.quota.json
         for (const k of ['percent', 'remainPct', 'weeklyRemainPct', 'remain', 'total', 'resetAt', 'resetAtMs', 'level']) {
           if (jin[k]) qj[k] = pathOf(jin[k])
@@ -2639,7 +2882,8 @@ export default {
         // 全部为空时直接删掉 model.balance，等于"完全用模板"
         const balIn = stripEmptyDeep({
           url: String(p.balance.url || '').slice(0, 500),
-          auth: String(p.balance.auth || '').slice(0, 200),
+          // v791：auth 现在是「头名:值」列表，比单个 Authorization 值长 ⇒ 上限 200 → 1000
+          auth: String(p.balance.auth || '').slice(0, 1000),
           // v789（issue #190）：可选的请求方法与请求体（留空 ⇒ 沿用模板/GET）
           method: String(p.balance.method || '').slice(0, 8).toUpperCase(),
           body: String(p.balance.body || '').slice(0, 4000),
@@ -2656,7 +2900,7 @@ export default {
           model.balance = model.balance || {}
           model.balance.usage = stripEmptyDeep({
             url: String(p.balance.usage.url).slice(0, 500),
-            auth: String(p.balance.usage.auth == null ? '' : p.balance.usage.auth).slice(0, 200),
+            auth: String(p.balance.usage.auth == null ? '' : p.balance.usage.auth).slice(0, 1000),
             json: { used: String((p.balance.usage.json && p.balance.usage.json.used) || '').slice(0, 200), scale: isFinite(Number(p.balance.usage.json && p.balance.usage.json.scale)) ? Number(p.balance.usage.json.scale) : undefined },
           })
         }
@@ -2869,7 +3113,7 @@ export default {
       const summary = daySummary(led, todayKey())
       const nowSec = Math.floor(Date.now() / 1000)
       return {
-        ...visible, version: '0.3.18', isPeak: isPeakTime(nowSec),
+        ...visible, version: '0.4.0', versionLabel: VERSION_LABEL, isPeak: isPeakTime(nowSec),
         // 峰谷切换点与节假日清单：前端倒计时要与宿主同源（否则法定节假日会算错切换点）
         peakNextChangeAt: nextPeakChangeAt(nowSec),
         peakHolidays: HOLIDAY_VALLEY_LIST,
@@ -2935,6 +3179,8 @@ export default {
               usageMode: normalizeUsageMode(parsed.usageMode),
               peakMode: parsed.peakMode === 'liangwen' || parsed.peakMode === 'qiangqiang' ? parsed.peakMode : 'default',
               bubbleOn: parsed.bubbleOn !== false,
+              // v866（用户要求）：按压/松开音的**独立**开关（原来是全局 soundOn 兼着当它用）
+              pressOn: parsed.pressOn !== false,
               turnCostOn: parsed.turnCostOn !== false,
               turnCostCloseMs: typeof parsed.turnCostCloseMs === 'number' ? parsed.turnCostCloseMs : 5000,
               scrollGapOn: parsed.scrollGapOn === true,
@@ -2950,10 +3196,11 @@ export default {
       return null
     }
 
-    function writeSizeConfig(scale, sound, vol, soundSet, usageMode, peakMode, bubbleOn, turnCostOn, turnCostCloseMs, scrollGapOn, scrollGapPx, menuBtnHide, codexStatsOnArg) {
+    function writeSizeConfig(scale, sound, vol, soundSet, usageMode, peakMode, bubbleOn, pressOnArg, turnCostOn, turnCostCloseMs, scrollGapOn, scrollGapPx, menuBtnHide, codexStatsOnArg) {
       const um = normalizeUsageMode(usageMode)
       const pm = peakMode === 'liangwen' || peakMode === 'qiangqiang' ? peakMode : 'default'
       const bo = bubbleOn !== false
+      const po = pressOnArg !== false // v866：按压/松开音独立开关（默认开）
       const tco = turnCostOn !== false
       const tcc = typeof turnCostCloseMs === 'number' ? (turnCostCloseMs > 0 ? turnCostCloseMs : 0) : 5000
       const sgo = scrollGapOn === true
@@ -2968,6 +3215,7 @@ export default {
         usageMode: um,
         peakMode: pm,
         bubbleOn: bo,
+        pressOn: po,
         turnCostOn: tco,
         turnCostCloseMs: tcc,
         scrollGapOn: sgo,
@@ -2989,6 +3237,7 @@ export default {
             usageMode: um,
             peakMode: pm,
             bubbleOn: bo,
+            pressOn: po,
             turnCostOn: tco,
             turnCostCloseMs: tcc,
             scrollGapOn: sgo,
@@ -3338,14 +3587,31 @@ export default {
       kind: 'exact',
       path: '/dsh-whale/balance.json',
       handler: async (req, res) => {
+        const t0 = Date.now()
         try {
           const refresh = new URL(req.url || '/', 'http://localhost').searchParams.get('refresh') === '1'
           const payload = await getBalance(refresh)
+          // v793：给「关于/自检」面板留一条最近的取数结果（只记状态与耗时，不记任何凭据）
+          try {
+            balanceLast = {
+              at: Date.now(),
+              ms: Date.now() - t0,
+              ok: !!payload.ok,
+              code: String(payload.code || ''),
+              error: payload.ok ? '' : String(payload.error || '').slice(0, 160),
+              hasBalance: payload.totalBalance !== null && payload.totalBalance !== undefined,
+              currency: String(payload.currency || ''),
+            }
+          } catch (err) {}
           res.writeHead(200, JSON_HEADERS)
-          res.end(JSON.stringify(payload))
+          // v794：成功失败都带上版本 ⇒ 客户端不必依赖"余额成功"才拿到版号
+          res.end(JSON.stringify(Object.assign({}, payload, { version: BUILD_VERSION, versionLabel: VERSION_LABEL })))
         } catch (err) {
+          try {
+            balanceLast = { at: Date.now(), ms: Date.now() - t0, ok: false, code: 'THROW', error: String((err && err.message) || err).slice(0, 160), hasBalance: false, currency: '' }
+          } catch (e2) {}
           res.writeHead(200, JSON_HEADERS)
-          res.end(JSON.stringify({ ok: false, code: 'ERROR', error: String((err && err.message) || err).slice(0, 200) }))
+          res.end(JSON.stringify({ ok: false, code: 'ERROR', error: String((err && err.message) || err).slice(0, 200), version: BUILD_VERSION, versionLabel: VERSION_LABEL }))
         }
       },
     }))
@@ -3398,6 +3664,7 @@ export default {
               typeof parsed.usageMode === 'string' ? parsed.usageMode : old.usageMode,
               typeof parsed.peakMode === 'string' ? parsed.peakMode : old.peakMode,
               pickB(parsed.bubbleOn, old.bubbleOn, true),
+              pickB(parsed.pressOn, old.pressOn, true),
               pickB(parsed.turnCostOn, old.turnCostOn, true),
               pickN(parsed.turnCostCloseMs, old.turnCostCloseMs, 5000),
               pickB(parsed.scrollGapOn, old.scrollGapOn, false),
@@ -3416,7 +3683,12 @@ export default {
           return
         }
         res.writeHead(200, JSON_HEADERS)
-        res.end(JSON.stringify(readSizeConfig() || {}))
+        // v794：GET 也带上版本（客户端启动就会读这份配置 ⇒ 菜单底部那行版本小字**不必等余额请求**，
+        //   余额首次请求失败时也不会一直空着 —— 这是用户报的"刚启动时版号消失"）
+        res.end(JSON.stringify(Object.assign({}, readSizeConfig() || {}, {
+          version: BUILD_VERSION,
+          versionLabel: VERSION_LABEL,
+        })))
       },
     }))
 
@@ -3434,6 +3706,290 @@ export default {
         }))
       },
     }))
+    // ===== v793（用户要求）：点版号 → 「关于 / 自检」面板 =====
+    // 数据来源全部是宿主已有状态；路径一律脱敏；**点开才请求，不轮询**。
+    let balanceLast = null // { at, ok, code, error, ms, hasBalance, keyRef, keyConfigured }
+    function aboutPayload(req) {
+      const client = clientKindOf(req)
+      const hostFile = (() => { try { return fileURLToPath(import.meta.url) } catch (err) { return '' } })()
+      const widgetFile = (() => {
+        for (const p of WIDGET_FILE_CANDIDATES) { try { if (fs.existsSync(p)) return p } catch (err) {} }
+        return ''
+      })()
+      const dataFiles = [
+        ['账本（记账）', USAGE_FILE_CANDIDATES],
+        ['模型注册表', API_FILE_CANDIDATES],
+        ['泡泡配置', BUBBLE_FILE_CANDIDATES],
+        ['外观/设置', SIZE_FILE_CANDIDATES],
+        ['轮次序号', TURN_FILE_CANDIDATES],
+        ['Codex 缓存', [path.join(DSH_HOME, '.dshw-codex.json')]],
+      ].map(([label, list]) => {
+        const p = firstExisting(list)
+        const f = p ? fileFacts(p) : null
+        return {
+          label: label,
+          found: !!p,
+          path: p ? maskPath(p) : '',
+          candidates: (list || []).length,
+          bytes: f ? f.bytes : null,
+          mtime: f ? f.mtime : null,
+        }
+      })
+      // 记账概览（只给统计，不给明细）
+      let ledger = null
+      try {
+        const led = readUsageLedger()
+        const today = todayKey()
+        const sum = daySummary(led, today)
+        let days = 0
+        try { days = accountingDays(led).length } catch (err) { days = Object.keys(led.history || {}).length }
+        ledger = {
+          days: days,
+          todayPartial: !!(sum && sum.partialDay),
+          todaySource: (sum && sum.source) || '',
+          lastObservedAt: (sum && sum.lastObservedAt) || null,
+          needsReview: !!(sum && sum.needsReview),
+        }
+      } catch (err) { ledger = { error: String((err && err.message) || err).slice(0, 120) } }
+      // Codex（v792 起：没配就完全禁用）
+      let codex = { enabled: false, reason: '' }
+      try {
+        codex = {
+          enabled: codexStatsOn(),
+          reason: codexStatsOn() ? '' : codexDisabledReason(),
+          snapAt: codexSnapAt || null,
+          ok: !!(codexSnap && codexSnap.ok),
+          files: (codexSnap && codexSnap.sessions) != null ? codexSnap.sessions : null,
+          skipped: (codexSnap && codexSnap.skipped) != null ? codexSnap.skipped : null,
+          deferred: (codexSnap && codexSnap.deferred) != null ? codexSnap.deferred : null,
+        }
+      } catch (err) {}
+      return {
+        ok: true,
+        plugin: {
+          name: 'dsh-whale-widget',
+          version: BUILD_VERSION,
+          channel: BUILD_CHANNEL,
+          label: VERSION_LABEL,
+          hostVersionLiterals: [...String(aboutPayloadSrc()).matchAll(/version: '([\d.]+)'/g)].map((m) => m[1]),
+        },
+        build: {
+          // v796：`found` 必须给（v795 前端简化后靠它判断"未找到"，缺了就会把宿主/前端文件误显示成"未找到"）
+          host: { found: !!hostFile, path: maskPath(hostFile), bytes: fileFacts(hostFile) ? fileFacts(hostFile).bytes : null, mtime: fileFacts(hostFile) ? fileFacts(hostFile).mtime : null },
+          widget: { found: !!widgetFile, path: maskPath(widgetFile), bytes: fileFacts(widgetFile) ? fileFacts(widgetFile).bytes : null, mtime: fileFacts(widgetFile) ? fileFacts(widgetFile).mtime : null },
+          // v819（自检发现）：这里原来写的是 `indexOf('<开发机目录名>')` —— 检测"开发版路径"的代码自己带了
+          //   那个字面量 ⇒ 发布包被 `tools/ci-audit.mjs` 判为"含开发机路径"（自己成了自己要检测的东西）。
+          //   改成**结构性判定**：宿主源码里有没有写死的绝对盘符路径（'D:/…' / "C:\\…"）。
+          //   开发版有 15+ 处（assets 兜底路径），strip 后的发布副本 0 处 ⇒ 判定更准，也不再出现那个字面量。
+          hostHasDevPaths: (() => {
+            try {
+              const src = fs.readFileSync(hostFile, 'utf8')
+              return /["'][A-Za-z]:[\\/]/.test(src)
+            } catch (err) { return null }
+          })(),
+        },
+        runtime: {
+          platform: process.platform,
+          arch: process.arch,
+          node: process.version,
+          dsh: dshVersionOf(),
+          uptimeSec: Math.round(process.uptime()),
+          dataHome: maskPath(DSH_HOME),
+          // profile 名（`profiles/web`、`profiles/desktop`…）：用来一眼看出"这份是哪个 profile 起来"的
+          profile: (() => { try { const m = /profiles[\\/]([^\\/]+)/.exec(hostFile); return m ? m[1] : '' } catch (err) { return '' } })(),
+        },
+        client: client,
+        data: dataFiles,
+        ledger: ledger,
+        balance: balanceLast,
+        codex: codex,
+      }
+    }
+    // 只用于读取源码里的两处上报版本字面量（判断"三处是否一致"）；不读敏感内容。
+    function aboutPayloadSrc() { try { return fs.readFileSync(fileURLToPath(import.meta.url), 'utf8') } catch (err) { return '' } }
+    // v796：DSH 版本**真的去读**，而不是只看环境变量（用户反馈"DSH 版本读取不到 (?)"）。
+    //   顺序：① 环境变量（部分启动方式会带）② 从 argv/execPath 往上找 `@deepseek-ai/dsh` 的 package.json
+    //   （npx 启动时 argv 就在 `_npx/<hash>/node_modules/@deepseek-ai/dsh/...` 里）③ 读不到就老实回 'unknown'。
+    //   全程 try/catch + 缓存（每个目录最多往上 8 层），绝不抛错。
+    let dshVersionCache = null
+    function dshVersionOf() {
+      if (dshVersionCache !== null) return dshVersionCache
+      let v = ''
+      try { v = String(process.env.DSH_CLIENT_VERSION || process.env.DSH_VERSION || '') } catch (err) {}
+      if (!v) {
+        try {
+          const roots = [process.argv[1], process.argv[0], process.execPath]
+          for (const r of roots) {
+            if (!r) continue
+            let dir = path.dirname(String(r))
+            for (let up = 0; up < 8; up++) {
+              try {
+                const pj = path.join(dir, 'package.json')
+                if (fs.existsSync(pj)) {
+                  const j = JSON.parse(fs.readFileSync(pj, 'utf8'))
+                  const nm = String((j && j.name) || '')
+                  if (nm === '@deepseek-ai/dsh' || nm === 'dsh' || nm === 'dsh-cli') {
+                    v = String((j && j.version) || '')
+                    if (v) break
+                  }
+                }
+              } catch (err) {}
+              const parent = path.dirname(dir)
+              if (parent === dir) break
+              dir = parent
+            }
+            if (v) break
+          }
+        } catch (err) {}
+      }
+      dshVersionCache = v || 'unknown'
+      return dshVersionCache
+    }
+    // v795（用户反馈）：客户端类型**看请求头的 UA**。前端用 `navigator.windowControlsOverlay` 判会误判 ——
+    //   Chrome 桌面浏览器也有这个 API，于是 `npx @deepseek-ai/dsh web` 起来也被认成"官方桌面客户端"。
+    //   官方桌面客户端是 Electron ⇒ UA 里必有 `Electron/`。判定只回 kind（不回完整 UA，避免带出多余指纹）。
+    function clientKindOf(req) {
+      try {
+        const ua = String((req && req.headers && (req.headers['user-agent'] || req.headers['User-Agent'])) || '')
+        const electron = /electron/i.test(ua)
+        return { kind: electron ? 'desktop' : 'web', via: electron ? 'ua-electron' : 'ua-browser' }
+      } catch (err) { return { kind: 'unknown', via: 'error' } }
+    }
+    disposers.push(registerRoute({
+      kind: 'exact',
+      path: '/dsh-whale/about.json',
+      handler: (req, res) => {
+        try {
+          res.writeHead(200, JSON_HEADERS)
+          res.end(JSON.stringify(aboutPayload(req)))
+        } catch (err) {
+          res.writeHead(200, JSON_HEADERS)
+          res.end(JSON.stringify({ ok: false, error: String((err && err.message) || err).slice(0, 160) }))
+        }
+      },
+    }))
+    // 检查更新：**点了才联网**。⚠️ 实测教训（用户报的 "The operation was aborted due to timeout" 就是它）：
+    //   ① 本机 Node 的 `fetch`(undici) 打 registry 会超时（npmmirror 6015ms / npmjs 6013ms 全挂），
+    //      而 `https` 模块同一时刻 244ms / 891ms 就回来了 ⇒ **这里必须用 https，而不是 fetch**；
+    //   ② 顺序上**镜像优先**；v802 再补两个 CDN 源（jsdelivr / unpkg 直接返回 package.json，同样带 version），
+    //      并把**所有失败源的原因一起报出来** —— 用户实测只看到最后一个源（`npmjs：超时`），看不出镜像也失败了。
+    // v802：跟随重定向（unpkg 的 `@latest` 会 302 到具体版本路径；实测就是这么被误判成失败的），最多 3 跳。
+    function httpsGetJson(url, timeoutMs, hop) {
+      return new Promise((resolve, reject) => {
+        let done = false
+        const finish = (err, val) => { if (done) return; done = true; if (err) reject(err); else resolve(val) }
+        try {
+          const req = https.get(url, { timeout: timeoutMs, headers: { 'user-agent': 'dsh-whale-widget', accept: 'application/json' } }, (res) => {
+            const code = res.statusCode
+            const loc = res.headers && res.headers.location
+            if (code >= 300 && code < 400 && loc && (hop || 0) < 3) {
+              try { res.resume() } catch (e) {}
+              let next = ''
+              try { next = new URL(loc, url).toString() } catch (e) { next = '' }
+              if (next) { httpsGetJson(next, timeoutMs, (hop || 0) + 1).then((v) => finish(null, v), (e) => finish(e)); return }
+            }
+            if (code !== 200) { try { res.resume() } catch (e) {} finish(new Error('HTTP ' + code)); return }
+            let body = ''
+            res.setEncoding('utf8')
+            res.on('data', (c) => {
+              body += c
+              if (body.length > 200000) { try { req.destroy() } catch (e) {} finish(new Error('响应过大')) }
+            })
+            res.on('end', () => { try { finish(null, JSON.parse(body)) } catch (e) { finish(new Error('响应不是 JSON')) } })
+          })
+          req.on('timeout', () => { try { req.destroy() } catch (e) {} finish(new Error('超时')) })
+          req.on('error', (e) => finish(e))
+        } catch (err) { finish(err) }
+      })
+    }
+    // v803：npm CLI 兜底源 —— 走 npm 自己的 registry/代理配置，在受限网络里往往比裸 https 更能出去
+    //   （实测本机 `npm view dsh-whale-widget version` 611~776ms 就回来了）。
+    //   ⚠️ 必须用**异步** exec：同步 spawnSync 会卡住宿主事件循环，把模型流一起拖住。
+    function npmCliVersion(timeoutMs) {
+      return new Promise((resolve, reject) => {
+        try {
+          exec('npm view dsh-whale-widget version', { timeout: timeoutMs, windowsHide: true }, (err, stdout) => {
+            if (err) { reject(new Error('npm 退出异常')); return }
+            const lines = String(stdout || '').trim().split(/\r?\n/).filter((x) => x.trim())
+            const v = lines.length ? lines[lines.length - 1].trim().replace(/^v/, '') : ''
+            if (!/^\d+\.\d+\.\d+/.test(v)) { reject(new Error('npm 输出里没有版本')); return }
+            resolve(v)
+          })
+        } catch (err) { reject(err) }
+      })
+    }
+    const UPDATE_SOURCES = [
+      { name: 'npmmirror', url: 'https://registry.npmmirror.com/dsh-whale-widget/latest' },
+      { name: 'jsdelivr', url: 'https://cdn.jsdelivr.net/npm/dsh-whale-widget@latest/package.json' },
+      { name: 'unpkg', url: 'https://unpkg.com/dsh-whale-widget@latest/package.json' },
+      { name: 'npmjs', url: 'https://registry.npmjs.org/dsh-whale-widget/latest' },
+      { name: 'npm-cli', cli: true },
+    ]
+    let updateCheckCache = null
+    disposers.push(registerRoute({
+      kind: 'exact',
+      path: '/dsh-whale/update-check.json',
+      handler: async (req, res) => {
+        const now = Date.now()
+        try {
+          if (updateCheckCache && now - updateCheckCache.at < 10 * 60 * 1000) {
+            res.writeHead(200, JSON_HEADERS)
+            res.end(JSON.stringify(updateCheckCache.payload))
+            return
+          }
+        } catch (err) {}
+        let payload = null
+        // v802：四个源**并行**试（单个源实测很不稳：npmmirror/jsdelivr 会超时、unpkg 会 302），
+        //   并行后最坏也就 5 秒（串行会是 20 秒），谁先成功用谁，全失败就把每个源的原因都列出来。
+        const results = await Promise.all(UPDATE_SOURCES.map(async (src) => {
+          // v803：失败得**很快**（<1.5s，多为 DNS/连接抖动）就再试一次；超时那种就不重试了（不然最坏翻倍）
+          const attempt = async () => {
+            const t0 = Date.now()
+            if (src.cli) return { v: await npmCliVersion(8000), ms: Date.now() - t0 }
+            const j = await httpsGetJson(src.url, 5000, 0)
+            const latest = String((j && j.version) || '')
+            if (!latest) throw new Error('返回里没有 version')
+            return { v: latest, ms: Date.now() - t0 }
+          }
+          try {
+            const a = await attempt()
+            return { ok: true, name: src.name, latest: a.v }
+          } catch (err1) {
+            // 只在"失败得很快"（<1.5s，多为连接抖动）时重试一次；超时那种不重试，避免最坏耗时翻倍
+            const fast = !(err1 && /超时/.test(String(err1.message || '')))
+            if (!fast) return { ok: false, name: src.name, why: String((err1 && err1.message) || err1).slice(0, 40) }
+            try {
+              const a2 = await attempt()
+              return { ok: true, name: src.name, latest: a2.v }
+            } catch (err2) {
+              return { ok: false, name: src.name, why: String((err2 && err2.message) || err2).slice(0, 40) }
+            }
+          }
+        }))
+        const hit = results.filter((r) => r.ok)[0]
+        if (hit) {
+          payload = {
+            ok: true,
+            current: BUILD_VERSION,
+            channel: BUILD_CHANNEL,
+            latest: hit.latest,
+            hasUpdate: hit.latest !== BUILD_VERSION,
+            source: hit.name,
+          }
+        } else {
+          // 全失败 ⇒ 把**每一个源**的原因都列出来（只报最后一个会让人以为只有 npmjs 挂了）
+          payload = {
+            ok: false,
+            current: BUILD_VERSION,
+            error: results.map((r) => r.name + '：' + r.why).join('；'),
+            tried: UPDATE_SOURCES.map((s) => s.name),
+          }
+        }
+        try { updateCheckCache = { at: now, payload: payload } } catch (err) {}
+        res.writeHead(200, JSON_HEADERS)
+        res.end(JSON.stringify(payload))
+      },
+    }))
     disposers.push(registerRoute({
       kind: 'exact',
       path: '/dsh-whale/usage-records.json',
@@ -3839,10 +4395,10 @@ export default {
       },
     }))
 
-    disposers.push(registerRoute({
-      kind: 'exact',
-      path: '/dsh-whale/audio-fragment.wav',
-      handler: (req, res) => {
+    // v860（issue #226）：路由**不再以 .wav 结尾** —— 带后缀的 URL 会被部分环境（下载器/扩展/反代）
+    //   当成"下载文件"劫持，导致试听与任务结束音无声。Content-Type 由 fragmentMime() 决定，
+    //   与 URL 后缀无关 ⇒ 改成无后缀路径，同时**保留旧路径作为兼容别名**（老客户端仍能用）。
+    const audioFragmentHandler = (req, res) => {
         try {
           const id = audioIdFromUrl(req.url)
           const bytes = loadAudioFragmentBytes(id)
@@ -3860,8 +4416,9 @@ export default {
           res.writeHead(404, { 'Content-Type': 'text/plain; charset=utf-8' })
           res.end('audio fragment unavailable')
         }
-      },
-    }))
+      }
+    disposers.push(registerRoute({ kind: 'exact', path: '/dsh-whale/audio-fragment', handler: audioFragmentHandler }))
+    disposers.push(registerRoute({ kind: 'exact', path: '/dsh-whale/audio-fragment.wav', handler: audioFragmentHandler }))
 
     // 片段字节对应的 MIME：内置/预设片段按声明，自定义片段一律 wav
     function fragmentMime(fragId) {
@@ -4013,6 +4570,169 @@ export default {
       }
       return null
     }
+    // ===== v815：自定义泡泡框 —— 宿主侧净化 =====
+    // 用户可以在"泡泡框"里写 SVG 代码 ⇒ 这些片段最终会进 innerHTML ⇒ **必须白名单化**：
+    //   · 只放行无脚本、无外链的几何标签；
+    //   · 标签属性只放行几何/描边类；
+    //   · 直接删掉 <script>/<foreignObject>/on* 事件/href(javascript:)/style 里的 url()、expression。
+    // 探针 `_v815-frame-lib-check.mjs` 带一批负样本（见 §验证），改这里必须同步那些断言。
+    const FRAME_SVG_TAGS = ['path', 'ellipse', 'circle', 'rect', 'polygon', 'polyline', 'g']
+    // v828：补 `r`（`<circle>` 的半径）—— 标签在白名单里却漏了属性，用户写 `<circle r="30"/>` 会被剥成画不出来
+    const FRAME_SVG_ATTRS = ['d', 'points', 'cx', 'cy', 'r', 'rx', 'ry', 'x', 'y', 'width', 'height', 'fill', 'stroke',
+      'stroke-width', 'stroke-dasharray', 'stroke-linejoin', 'stroke-linecap', 'transform', 'opacity', 'fill-opacity', 'stroke-opacity']
+    function frameColorOk(v, def) {
+      const s = String(v == null ? '' : v).trim()
+      if (/^#[0-9a-fA-F]{3}$/.test(s) || /^#[0-9a-fA-F]{6}$/.test(s)) return s
+      if (/^rgba?\(\s*\d{1,3}\s*,\s*\d{1,3}\s*,\s*\d{1,3}\s*(,\s*(0|1|0?\.\d+)\s*)?\)$/.test(s)) return s
+      if (s === 'transparent' || s === 'none') return s
+      return def
+    }
+    function frameNumIn(v, def, min, max) {
+      const n = Number(v)
+      let x = isFinite(n) ? n : def
+      if (typeof min === 'number' && x < min) x = min
+      if (typeof max === 'number' && x > max) x = max
+      return Math.round(x * 1000) / 1000
+    }
+    function frameSvgSanitize(code) {
+      let s = String(code == null ? '' : code).slice(0, 8000)
+      if (!s) return ''
+      // 整块危险元素直接删（含内容）
+      s = s.replace(/<\s*(script|foreignObject|style|iframe|image|use|animate|set)\b[\s\S]*?<\s*\/\s*\1\s*>/gi, '')
+      s = s.replace(/<\s*(script|foreignObject|style|iframe|image|use|animate|set)\b[^>]*\/?>/gi, '')
+      // 只保留白名单标签；其它标签（含自闭合）整体删除
+      s = s.replace(/<\s*\/?\s*([A-Za-z][\w:-]*)((?:[^>"']|"[^"]*"|'[^']*')*)\/?>/g, (m0, tag, attrs) => {
+        const t = String(tag)
+        if (FRAME_SVG_TAGS.indexOf(t) < 0) return ''
+        const closing = /^<\s*\//.test(m0)
+        // v823（P2）：**保住自闭合的斜杠**。P0 首版一律重拼成 `<tag …>`，而内联 SVG 里 `<path>` 不是空元素
+        //   ⇒ HTML 解析器会把后面的兄弟塞进它里面（`<path a/><path b/>` → path a > path b，子节点不渲染）
+        //   ⇒ 用户写的多形状自定义 SVG 只有第一个能显示。P2 才引入"自定义 SVG 代码"，所以坑到这时才暴露。
+        const selfClose = /\/\s*>$/.test(m0)
+        let out = '<' + (closing ? '/' : '') + t
+        if (!closing) {
+          const re = /([A-Za-z][\w:-]*)\s*=\s*("([^"]*)"|'([^']*)')/g
+          let m
+          let kept = 0
+          while ((m = re.exec(attrs))) {
+            const name = String(m[1]).toLowerCase()
+            const val = String(m[3] !== undefined ? m[3] : m[4])
+            if (FRAME_SVG_ATTRS.indexOf(name) < 0) continue
+            // 值里也不许出现 javascript:/url(/expression
+            if (/javascript:|url\s*\(|expression\s*\(/i.test(val)) continue
+            if (/[<>]/.test(val)) continue
+            out += ' ' + name + '="' + val.replace(/"/g, '&quot;') + '"'
+            kept++
+          }
+          void kept
+        }
+        return out + ((selfClose && !closing) ? '/>' : '>')
+      })
+      // v818（自检发现）：再**清掉标签之外的所有裸文本**。为什么必须做：`<script>alert(1)`（未闭合）这类输入，
+      //   块删除与标签白名单都只处理"标签"，会留下裸文本 `alert(1)` —— 它在 SVG 里是惰性文本、不会执行，
+      //   但把与形状无关的文字塞进 innerHTML 没有意义，也少留一条"文本被解释"的可能性。
+      //   属性值里不可能含 < >（上面的属性白名单已拒），所以按 <…> 切分是安全的。
+      s = s.replace(/[^<>]+(?=<|$)/g, '')
+      return s
+    }
+    function frameSanitizeOne(raw, idx) {
+      const s = raw && typeof raw === 'object' ? raw : {}
+      let id = String(s.id == null ? '' : s.id).trim().slice(0, 64)
+      if (!id) id = 'frame_' + Date.now().toString(36) + '_' + Math.random().toString(36).slice(2, 6)
+      const slotsIn = s.slots && typeof s.slots === 'object' ? s.slots : {}
+      function slot(kind) {
+        const d = slotsIn[kind] && typeof slotsIn[kind] === 'object' ? slotsIn[kind] : {}
+        const paint = d.paint && typeof d.paint === 'object' ? d.paint : {}
+        const out = {
+          dx: frameNumIn(d.dx, 0, -1026, 1026),
+          dy: frameNumIn(d.dy, 0, -700, 700),
+          scale: frameNumIn(d.scale, 1, 0.2, 4),
+          kind: d.kind === 'image' ? 'image' : 'svg',
+          svgPreset: ['classic', 'roundrect', 'zigzag', 'custom'].indexOf(String(d.svgPreset)) >= 0 ? String(d.svgPreset) : 'classic',
+          svgCode: frameSvgSanitize(d.svgCode),
+          imgId: String(d.imgId == null ? '' : d.imgId).slice(0, 64),
+          imgScale: frameNumIn(d.imgScale, 1, 0.1, 6),
+          imgOpacity: frameNumIn(d.imgOpacity, 1, 0, 1),
+          paint: {
+            bgOn: paint.bgOn === undefined ? true : paint.bgOn !== false,
+            bg: frameColorOk(paint.bg, '#FFFFFF'),
+            bgAlpha: frameNumIn(paint.bgAlpha, 1, 0, 1),
+            lineOn: paint.lineOn === undefined ? true : paint.lineOn !== false,
+            line: frameColorOk(paint.line, '#203170'),
+            lineW: frameNumIn(paint.lineW, 18, 0, 120),
+            lineAlpha: frameNumIn(paint.lineAlpha, 1, 0, 1),
+            dashOn: paint.dashOn === true,
+            dash: /^[0-9][0-9.,\s]*$/.test(String(paint.dash == null ? '' : paint.dash).trim()) ? String(paint.dash).trim().slice(0, 40) : '0',
+            cap: ['butt', 'square', 'round'].indexOf(String(paint.cap)) >= 0 ? String(paint.cap) : 'round',
+            join: ['miter', 'bevel', 'round'].indexOf(String(paint.join)) >= 0 ? String(paint.join) : 'round',
+          },
+        }
+        if (kind === 'small1' || kind === 'small2') out.on = d.on === undefined ? true : d.on !== false
+        return out
+      }
+      const safe = s.safe && typeof s.safe === 'object' ? s.safe : {}
+      const w = frameNumIn(safe.w, 646, 40, 1026)
+      const h = frameNumIn(safe.h, 400, 40, 700)
+      return {
+        id: id,
+        name: String(s.name == null ? '' : s.name).trim().slice(0, 24) || ('泡泡框' + (idx + 1)),
+        builtin: s.builtin === true,
+        pinned: Math.round(frameNumIn(s.pinned, 0, 0, 9999)),
+        createdAt: Math.round(frameNumIn(s.createdAt, Date.now(), 0, 1e15)),
+        textColor: frameColorOk(s.textColor, ''),
+        safe: { x: frameNumIn(safe.x, 190, 0, 1026 - w), y: frameNumIn(safe.y, 90, 0, 700 - h), w: w, h: h },
+        slots: { big: slot('big'), small1: slot('small1'), small2: slot('small2') },
+      }
+    }
+    // 整份框库净化：内置框强制只读（内容还原由前端做；宿主这里只保证"不许被改成非内置"）
+    function framesSanitize(list, defId) {
+      const arr = Array.isArray(list) ? list.slice(0, 50) : []
+      const out = []
+      for (let i = 0; i < arr.length; i++) {
+        const f = frameSanitizeOne(arr[i], i)
+        if (f.id === 'frame_classic') { f.builtin = true; f.name = '经典（内置）'; continue } // 内置框不进库（前端会补）
+        out.push(f)
+      }
+      let def = String(defId == null ? '' : defId).slice(0, 64)
+      if (!out.some((x) => x.id === def)) def = 'frame_classic'
+      return { frames: out, defaultFrameId: def }
+    }
+    // items 里的"框引用 / 外观覆盖"：只保留已知形状的字段（逐字段白名单）
+    function itemsSanitizeFrames(items) {
+      const list = Array.isArray(items) ? items : []
+      const cleanOne = (obj) => {
+        if (!obj || typeof obj !== 'object') return obj
+        const out = obj
+        if (typeof out.frameId === 'string') out.frameId = out.frameId.slice(0, 64)
+        else delete out.frameId
+        const ov = out.frameOverride
+        if (ov && typeof ov === 'object') {
+          const keep = {}
+          for (const slot of ['big', 'small1', 'small2']) {
+            const raw = ov[slot]
+            if (!raw || typeof raw !== 'object') continue
+            const p = {}
+            for (const k of ['bgOn', 'bg', 'bgAlpha', 'lineOn', 'line', 'lineW', 'lineAlpha', 'dashOn', 'dash', 'cap', 'join']) {
+              if (Object.prototype.hasOwnProperty.call(raw, k)) p[k] = raw[k]
+            }
+            // 颜色/数值仍然过一遍校验，避免脏值写进配置
+            const norm = frameSanitizeOne({ slots: { [slot]: { paint: p } } }, 0).slots[slot].paint
+            const only = {}
+            for (const k of Object.keys(p)) if (Object.prototype.hasOwnProperty.call(norm, k)) only[k] = norm[k]
+            keep[slot] = only
+          }
+          if (Object.keys(keep).length) out.frameOverride = keep
+          else delete out.frameOverride
+        } else delete out.frameOverride
+        return out
+      }
+      for (const it of list) {
+        if (!it || typeof it !== 'object') continue
+        cleanOne(it)
+        if (it.kind === 'choice' && Array.isArray(it.options)) for (const o of it.options) { if (o) { cleanOne(o); if (o.item) cleanOne(o.item) } }
+      }
+      return list
+    }
     function writeBubbleConfig(cfg) {
       const body = JSON.stringify(cfg, null, 2)
       for (const p of BUBBLE_FILE_CANDIDATES) {
@@ -4035,7 +4755,15 @@ export default {
               return
             }
             // v727：tapAdvance =「点按角色推进泡泡队列」（只存布尔值，不放行其它字段）
-            const cfg = { v: 1, items: parsed.items, lib: parsed.lib, tapAdvance: parsed.tapAdvance === true }
+            // v815：泡泡框（frames/defaultFrameId）与 items 上的框引用/外观覆盖走净化后落盘。
+            //   没带 frames 的老客户端 ⇒ 不写这两个键（老配置零 churn）。
+            const itemsClean = itemsSanitizeFrames(parsed.items)
+            const cfg = { v: 1, items: itemsClean, lib: parsed.lib, tapAdvance: parsed.tapAdvance === true }
+            if (Array.isArray(parsed.frames)) {
+              const fr = framesSanitize(parsed.frames, parsed.defaultFrameId)
+              cfg.frames = fr.frames
+              cfg.defaultFrameId = fr.defaultFrameId
+            }
             writeBubbleConfig(cfg)
             res.writeHead(200, JSON_HEADERS)
             res.end(JSON.stringify({ ok: true, config: cfg }))