dsh-whale-widget 0.3.17 → 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,
@@ -28,9 +30,71 @@ const IMAGE_CANDIDATES = [
   path.join(PACKAGE_ROOT, 'assets', 'DSniang02.png'),
 ]
 // 自定义角色图片存放目录（第一个可写的会被使用；roles.json 存角色元数据）
+// ⭐ 2026-10-02（用户要求"并成一份"）：**用户数据的候选表一律 $DSH_HOME 优先**，开发机路径降级为兜底。
+//   原因：桌面客户端加载的是 strip 过的发布副本（只认 $DSH_HOME），而开发版宿主原先把开发机路径排在第一位
+//   ⇒ 本机上网页端与桌面端**各写各的**（实测两端同时各写一份 .dshw-usage.json / .dshw-bubble.json），
+//   互相看不到对方的改动 —— 表现就是"删掉的模块又冒出来""记账数对不上"。
+//   ⚠️ 这个常量必须在**所有**用到它的候选表之前定义（const 有 TDZ），所以放在最前面。
+//   ⚠️ `_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'),
   path.join(DSH_HOME, 'profiles', 'web', 'whale-roles'),
+  DATA_CANDIDATES_TAIL[0] + 'whale-roles/',
+  DATA_CANDIDATES_TAIL[1] + 'whale-roles/',
 ]
 const ROLE_INDEX_NAME = 'roles.json'
 const ROLE_DEFAULT_ID = 'default'
@@ -38,6 +102,8 @@ const ROLE_DEFAULT_ID = 'default'
 const AUDIO_DIR_CANDIDATES = [
   path.join(DSH_HOME, 'whale-audio'),
   path.join(DSH_HOME, 'profiles', 'web', 'whale-audio'),
+  DATA_CANDIDATES_TAIL[0] + 'whale-audio/',
+  DATA_CANDIDATES_TAIL[1] + 'whale-audio/',
 ]
 const AUDIO_INDEX_NAME = 'audio.json'
 // 内置预设音效组（不可删、不可改），对应 assets 里的 Ya/D 系列
@@ -57,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 = {
@@ -67,12 +141,25 @@ 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），本文件不存明文。
+// ⭐ 2026-10-02（用户要求"并成一份"）：$DSH_HOME 优先（自定义 API 模型清单也属于用户数据，原先两端各存一份）。
 const API_FILE_CANDIDATES = [
   path.join(DSH_HOME, '.dshw-api.json'),
   path.join(DSH_HOME, 'profiles', 'web', '.dshw-api.json'),
+  DATA_CANDIDATES_TAIL[0] + '.dshw-api.json',
+  DATA_CANDIDATES_TAIL[1] + '.dshw-api.json',
 ]
 const API_BUILTIN_ID = 'deepseek'
 // 「充值 / 余额校正」只属于固定的 DeepSeek（内置）：模型条目下发 canAdjustBalance，路由层再校验一次。
@@ -163,7 +250,17 @@ const API_TEMPLATES = {
     quota: {
       url: 'https://open.bigmodel.cn/api/monitor/usage/quota/limit',
       auth: '{key}', // 智谱此接口不带 Bearer
-      json: { percent: 'data.limits[0].TOKENS_LIMIT.percentage', resetAt: 'data.limits[0].nextResetTime', level: 'data.level' },
+      // v789（issue #180/#181 修）：`data.limits[]` 是扁平条目数组，`TOKENS_LIMIT` 是条目的 `type` **值**，
+      //   且 5h 窗口不保证排在 [0]（pro 账号 [0] 是 TIME_LIMIT、max 账号 [0] 才是 TOKENS_LIMIT）
+      //   ⇒ 一律按 type(+unit) 选条目：unit=3 = 5 小时窗口、unit=6 = 周窗口；
+      //   新注册/credit 制账号的 type 是 CREDIT_LIMIT ⇒ 一并兼容。
+      json: {
+        level: 'data.level',
+        windows: [
+          { key: 'rolling', label: '5h', pick: { list: 'data.limits', types: ['TOKENS_LIMIT', 'CREDIT_LIMIT'], unit: 3 }, percent: 'percentage', resetAt: 'nextResetTime' },
+          { key: 'weekly', label: '周', pick: { list: 'data.limits', types: ['TOKENS_LIMIT', 'CREDIT_LIMIT'], unit: 6 }, percent: 'percentage', resetAt: 'nextResetTime' },
+        ],
+      },
     },
     probeUrl: 'https://open.bigmodel.cn/api/monitor/usage/quota/limit',
   },
@@ -239,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,
@@ -346,7 +446,14 @@ const API_TEMPLATES = {
     quota: {
       url: 'https://api.z.ai/api/monitor/usage/quota/limit',
       auth: '{key}', // 与国内站一样不带 Bearer
-      json: { percent: 'data.limits[0].TOKENS_LIMIT.percentage', resetAt: 'data.limits[0].nextResetTime', level: 'data.level' },
+      // v789：与国内站同一套 `data.limits[]` 结构（见 zhipu_glm_coding 的注释），一并按 type+unit 选条目
+      json: {
+        level: 'data.level',
+        windows: [
+          { key: 'rolling', label: '5h', pick: { list: 'data.limits', types: ['TOKENS_LIMIT', 'CREDIT_LIMIT'], unit: 3 }, percent: 'percentage', resetAt: 'nextResetTime' },
+          { key: 'weekly', label: '周', pick: { list: 'data.limits', types: ['TOKENS_LIMIT', 'CREDIT_LIMIT'], unit: 6 }, percent: 'percentage', resetAt: 'nextResetTime' },
+        ],
+      },
     },
     probeUrl: 'https://api.z.ai/api/monitor/usage/quota/limit',
   },
@@ -365,20 +472,28 @@ const API_TEMPLATES = {
   },
 }
 
+// ⭐ 2026-10-02（用户要求"并成一份"）：这些**用户数据文件一律 $DSH_HOME 优先**，开发机路径降级为只读兜底。
+//   原因见上方 AUDIO_DIR_CANDIDATES 的说明（桌面端只认 $DSH_HOME，两端原先各写各的）。
 // Size memory file: prefer writable DSH home locations, then legacy fallbacks.
 const SIZE_FILE_CANDIDATES = [
   path.join(DSH_HOME, '.dshw-size.json'),
   path.join(DSH_HOME, 'profiles', 'web', '.dshw-size.json'),
+  DATA_CANDIDATES_TAIL[0] + '.dshw-size.json',
+  DATA_CANDIDATES_TAIL[1] + '.dshw-size.json',
 ]
 // Usage ledger file (小鲸鱼记账 mode): same policy as the size file.
 const USAGE_FILE_CANDIDATES = [
   path.join(DSH_HOME, '.dshw-usage.json'),
   path.join(DSH_HOME, 'profiles', 'web', '.dshw-usage.json'),
+  DATA_CANDIDATES_TAIL[0] + '.dshw-usage.json',
+  DATA_CANDIDATES_TAIL[1] + '.dshw-usage.json',
 ]
 // 每轮消耗 seq 持久化文件：避免插件热重载后 seq 归零导致页面把新轮次误判为旧轮次吞掉
 const TURN_FILE_CANDIDATES = [
   path.join(DSH_HOME, '.dshw-turn.json'),
   path.join(DSH_HOME, 'profiles', 'web', '.dshw-turn.json'),
+  DATA_CANDIDATES_TAIL[0] + '.dshw-turn.json',
+  DATA_CANDIDATES_TAIL[1] + '.dshw-turn.json',
 ]
 // Sound assets: package-relative first (ship Ya1/Ya2/D1/D2.mp3 in assets/),
 // legacy absolute paths as fallback.
@@ -387,6 +502,8 @@ const BUBBLE_FILE_CANDIDATES = [
   // 否则清完这个数组会变成空的：泡泡配置读不了也存不了（自定义泡泡整体失效）。
   path.join(DSH_HOME, '.dshw-bubble.json'),
   path.join(DSH_HOME, 'profiles', 'web', '.dshw-bubble.json'),
+  DATA_CANDIDATES_TAIL[0] + '.dshw-bubble.json',
+  DATA_CANDIDATES_TAIL[1] + '.dshw-bubble.json',
 ]
 // 泡泡图库(独立于角色图库):图片文件目录 + 索引
 const BUBBLE_IMG_DIR_CANDIDATES = [
@@ -394,6 +511,8 @@ const BUBBLE_IMG_DIR_CANDIDATES = [
   // 空数组会让图库上传直接报错。
   path.join(DSH_HOME, 'whale-bubble-imgs'),
   path.join(DSH_HOME, 'profiles', 'web', 'whale-bubble-imgs'),
+  DATA_CANDIDATES_TAIL[0] + 'whale-bubble-imgs/',
+  DATA_CANDIDATES_TAIL[1] + 'whale-bubble-imgs/',
 ]
 const BUBBLE_IMG_INDEX_NAME = 'bubble-imgs.json'
 // 内置默认泡泡图(语义 id → assets 文件):面板常驻可选;全新安装无用户图库时
@@ -430,6 +549,8 @@ function soundSetFromUrl(url) {
 }
 const BALANCE_URL = 'https://api.deepseek.com/user/balance'
 const BALANCE_TTL_MS = 25000
+// v781：账号登录路的兜底超时（毫秒）。DSH 账号服务自身默认 30s，太长会把前端 FETCH_TIMEOUT_MS(25s) 先耗掉。
+const ACCOUNT_FALLBACK_MS = 5000
 const RUA_GIF_CANDIDATES = [
   path.join(PACKAGE_ROOT, 'assets', 'rua.gif'),
 ]
@@ -794,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 || {}
@@ -960,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'
@@ -1017,10 +1181,13 @@ export default {
     // ⚠️ 必须用 `ctx.get('deepseekAccount')` 读**可选服务**，**绝不能写进 inject** —— 老宿主根本没有这个服务，
     //    一旦进 inject，整个插件会永远等不到服务而**完全不 apply**（比没有这个功能严重得多）。
     // ⚠️ 与 API key 路径**互不干扰**（API key 永远优先；DSH 自己的注释也是 "Neither route falls back to the other"）。
+    // v781：账号余额路的失败原因（只用于错误文案，不参与任何判定）。fetchAccountBalance 每次开头清空。
+    let accountDiag = ''
     async function fetchAccountBalance() {
       let account = null
+      accountDiag = ''
       try { account = typeof ctx.get === 'function' ? ctx.get('deepseekAccount') : null } catch (err) { account = null }
-      if (!account || typeof account.getBalance !== 'function') return null
+      if (!account || typeof account.getBalance !== 'function') { accountDiag = '当前 DSH 没有账号服务'; return null }
       // 账户标识：优先用账号服务给的稳定 id（不同账号 → 不同账本 scope）；取不到就退回固定标识。
       // 一律 sha256[:24] 十六进制 —— accounting.mjs 校验 scope 必须匹配 /^[a-zA-Z0-9_-]{1,80}$/
       // （带冒号这种可读写法会直接抛「账户标识无效」，见 issue #157 报告人踩的坑 1）。
@@ -1036,25 +1203,52 @@ export default {
           locale: String(process.env.DSH_LOCALE || '') || 'zh_CN',
           timezoneOffsetSeconds: -new Date().getTimezoneOffset() * 60, // 东为正的整秒
         })
-      } catch (err) { return null }
+      } catch (err) {
+        accountDiag = '账号余额接口调用失败: ' + String((err && err.message) || err).slice(0, 120)
+        return null
+      }
       // 未登录 / 没有 grant / 平台失败 → 一律返回 null，让调用方退回原来的文案（**不缓存错误**）
-      if (!result || result.status !== 'ready' || !Array.isArray(result.value) || result.value.length === 0) return null
+      // v781：失败时记下**原因**（accountDiag），供 fetchBalance 把两条路的原因一起报给界面 ——
+      //   以前只有一个笼统的"账号余额不可用"，用户/支持方分不清"没登录"和"接口失败"。
+      if (!result) { accountDiag = '未登录 DeepSeek 账号（没有账号凭据）'; return null }
+      if (result.status !== 'ready') { accountDiag = '账号余额接口未就绪（' + String(result.status || 'unknown') + '）'; return null }
       const accNum = (v) => { const n = Number(v); return Number.isFinite(n) ? n : null }
-      const wallets = result.value.filter((w) => w && accNum(w.balance) !== null)
-      if (wallets.length === 0) return null
-      const currency = wallets.some((w) => String(w.currency || '').toUpperCase() === 'CNY')
-        ? 'CNY'
-        : String((wallets[0] && wallets[0].currency) || 'CNY').toUpperCase()
-      const sumOf = (list) => (Array.isArray(list) ? list : [])
-        .filter((w) => w && String(w.currency || 'CNY').toUpperCase() === currency && accNum(w.balance) !== null)
+      // v781：**"充值钱包为空、只有赠金"必须算成功** —— 这是"只登录客户端读不到余额"的主因。
+      //   平台把钱包拆成 `normal_wallets`（充值）与 `bonus_wallets`（赠金）；新用户/没充过值的用户
+      //   常常**只有赠金**（甚至 normal_wallets 是空数组）⇒ 旧代码要求 `result.value` 非空，
+      //   直接把这类账号判成"没有余额钱包"，界面就只显示"读取不到余额"。
+      //   判据对齐 DSH 自己的账号卡片（dsh-client-ui-settings-account）：
+      //     `[...balance.value, ...balance.bonusWallets].some(w => new Big(w.balance).gt(0))`
+      //   —— 两个钱包一起看，不再单看充值钱包。
+      const normRaw = Array.isArray(result.value) ? result.value : []
+      const bonusRaw = Array.isArray(result.bonusWallets) ? result.bonusWallets : []
+      const usable = (list) => list.filter((w) => w && accNum(w.balance) !== null)
+      const normWallets = usable(normRaw)
+      const bonusWallets = usable(bonusRaw)
+      const allWallets = normWallets.concat(bonusWallets)
+      if (allWallets.length === 0) {
+        // 两边都没有可用钱包 = 真的没有数据（未激活/账号没有任何钱包），不是"余额 0"
+        accountDiag = normRaw.length || bonusRaw.length ? '钱包字段不可用' : '账号没有余额钱包'
+        return null
+      }
+      // 币种：优先「有余额的那个钱包」的币种（CNY 优先），其次任何 CNY 钱包，最后第一个
+      const curOf = (w) => String((w && w.currency) || 'CNY').toUpperCase()
+      const nonzero = allWallets.filter((w) => Number(w.balance) > 0)
+      const curPick = nonzero.find((w) => curOf(w) === 'CNY') || nonzero[0]
+        || allWallets.find((w) => curOf(w) === 'CNY') || allWallets[0]
+      const currency = curOf(curPick)
+      const sumOf = (list) => list
+        .filter((w) => w && curOf(w) === currency && accNum(w.balance) !== null)
         .reduce((s, w) => s + Number(w.balance), 0)
-      const recharge = sumOf(result.value)
-      const bonus = sumOf(result.bonusWallets)
+      const recharge = sumOf(normWallets)
+      const bonus = sumOf(bonusWallets)
+      accountDiag = ''
       return {
         ok: true,
         // 充值 + 赠金：与 API key 路径的 `total_balance` 同口径（那个字段本身也是两者相加），
         // 否则"按余额差"推算的今日已用会偏小（issue #157 报告人的坑 2）。
         totalBalance: Number((recharge + bonus).toFixed(6)),
+        // v781：两个分量单独下发，供「赠金 / 账户余额」两个自定义模块使用（见 SPEC §25）
         rechargeBalance: Number(recharge.toFixed(6)),
         bonusBalance: Number(bonus.toFixed(6)),
         currency,
@@ -1064,30 +1258,64 @@ export default {
       }
     }
 
+    // v781：账号路的兜底（**两条路都失败才报错，并把两条路的原因都带上**）。
+    //   为什么需要它：旧实现只在"完全没有 API key"时才试账号路 ⇒ 曾经配过 key（过期/写错/被删）
+    //   但现在只用客户端登录的用户，余额**永远读不到**（"只登录客户端读不到余额"报告里的另一大类）。
+    //   ⚠️ 超时上限：账号路走 DSH 自己的服务（默认 30s）⇒ 我们用 ACCOUNT_FALLBACK_MS 截断，
+    //   保证"API key 两次 8s + 退避"之后仍在**前端的 25s** 之内回来，不让界面先 abort。
+    async function accountFallback(keyErr) {
+      let acc = null
+      try {
+        acc = await Promise.race([
+          fetchAccountBalance(),
+          new Promise((r) => setTimeout(() => { accountDiag = '账号余额请求超时'; r(null) }, ACCOUNT_FALLBACK_MS)),
+        ])
+      } catch (err) {
+        acc = null
+        accountDiag = accountDiag || ('账号余额异常: ' + String((err && err.message) || err).slice(0, 120))
+      }
+      if (acc) return acc
+      const keyPart = keyErr
+        ? ('API key 路：' + String((keyErr.error || keyErr.code || '失败')).slice(0, 160))
+        : '未配置 DEEPSEEK_API_KEY'
+      return {
+        ok: false,
+        code: keyErr ? 'BOTH_FAILED' : 'NO_KEY',
+        error: keyPart + '；账号登录路：' + (accountDiag || '拿不到余额'),
+      }
+    }
     async function fetchBalance() {
       // v739（用户反馈「每次新实例的第一次余额请求都失败」）：
       // ① 冷启动时凭据服务可能尚未就绪（resolve 抛错），这与「确实没配置」不同 → 短延迟重试一次；
       // ② 单次超时从 20s 收到 8s，保证「2 次尝试 + 退避」明显短于前端 FETCH_TIMEOUT_MS(25s) ——
       //    否则前端先 abort，用户看到的永远是「第一次失败」，只能干等 60 秒后的下一轮。
       let cred = null
+      let credErr = null
       for (let attempt = 0; attempt < 2; attempt++) {
         try {
           cred = await ctx.credentials.resolve('DEEPSEEK_API_KEY')
+          credErr = null
           break
         } catch (err) {
+          credErr = 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) }
+          // v781：凭据服务报错时**也要试账号路**（以前直接 return，登录态用户就被这条挡住）
+          return await accountFallback({ code: 'NO_KEY', error: '凭据读取失败: ' + String((err && err.message) || err).slice(0, 160) })
         }
       }
       if (!cred) {
         // v759（issue #157）：没有 API key 时退回 DSH 账号登录态；两条路互不干扰，API key 始终第一优先。
-        const accountPayload = await fetchAccountBalance()
-        if (accountPayload) return accountPayload
-        return {
-          ok: false, code: 'NO_KEY',
-          error: '未配置 DEEPSEEK_API_KEY，且账号余额不可用（未登录 DeepSeek 账号，或该账号没有余额钱包）',
-        }
+        return await accountFallback(null)
       }
+      const apiFail = await fetchApiKeyBalance(cred)
+      if (apiFail.ok) return apiFail
+      // v781：key 路**任何**失败都再试一次账号路（401/结构异常/超时都算）
+      void credErr
+      return await accountFallback(apiFail)
+    }
+
+    // API key 路（原 fetchBalance 的主体，v781 抽出来以便"失败后回退账号路"）
+    async function fetchApiKeyBalance(cred) {
       let lastErr = null
       for (let attempt = 0; attempt < 2; attempt++) {
         let res
@@ -1117,9 +1345,15 @@ export default {
         if (!info || info.total_balance === undefined || !Number.isFinite(Number(info.total_balance))) {
           return { ok: false, code: 'SHAPE', error: '余额接口返回结构异常' }
         }
+        const numOr = (x) => { const n = Number(x); return Number.isFinite(n) ? n : null }
         return {
           ok: true,
           totalBalance: Number(info.total_balance),
+          // v781：官方 /user/balance 除 total_balance 外还给了 granted_balance（**未过期**赠金）与
+          //   topped_up_balance（充值）。取不到就是 null（界面显示 —，**不臆造 0** —— 0 会被记账
+          //   当成"余额真的见底"，那是另一种语义）。两个分量供自定义模块里的「赠金 / 账户余额」使用。
+          bonusBalance: numOr(info.granted_balance),
+          rechargeBalance: numOr(info.topped_up_balance),
           accountTag: createHash('sha256').update(String(cred.value)).digest('hex').slice(0, 24),
           currency: String(info.currency || 'CNY'),
           balanceSource: 'apikey',
@@ -1146,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)
@@ -1285,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.17', 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),
@@ -1325,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）。
@@ -1385,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)) {
@@ -1420,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 : {}
@@ -1439,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)
@@ -1737,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() 会清掉缓存，所以开关仍然是"立刻生效"。
@@ -1754,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
@@ -1813,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} } }
@@ -1847,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
@@ -1999,14 +2307,100 @@ export default {
       }
       return { key, code: '', error: '' }
     }
-    async function apiFetchJson(url, auth, key) {
-      const headers = {}
-      const a = String(auth == null ? 'Bearer {key}' : auth)
-      if (a) headers.Authorization = a.replace('{key}', key)
+    // v789（issue #190）：余额/额度接口不再局限于 GET —— 模板或模型条目可声明 method / body。
+    //   ① method 默认 GET；非 GET 时带 `Content-Type: application/json` 并把 body 发出去；
+    //   ② body 支持占位符：`{key}`（凭据）、`{base}`（Base URL）、以及 `model.params` 里的任意键（如 `{uuid}`）
+    //      —— 这样"POST /v1/enterprise/account {"uuid":"…"}" 这类自建网关不需要再额外挂一层转换服务；
+    //   ③ 安全边界不变：body 只来自配置（不接受请求方传入），目的地仍走 credentialMayGoTo() 白名单，
+    //      URL 仍过 assertSafeApiUrl()。
+    function bodyWithPlaceholders(body, key, base, params) {
+      let s = String(body == null ? '' : body)
+      s = s.split('{key}').join(String(key == null ? '' : key))
+      s = s.split('{base}').join(String(base == null ? '' : base))
+      if (params && typeof params === 'object') {
+        for (const k of Object.keys(params)) {
+          const v = params[k]
+          if (v === undefined || v === null || typeof v === 'object') continue
+          s = s.split('{' + k + '}').join(String(v))
+        }
+      }
+      return s
+    }
+    function httpMethodOf(cfg) {
+      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 || {}
+      // v791：头列表（默认值仍是单个 Authorization，与老行为逐字节一致）
+      const headers = headersFromAuth(auth, key)
       // v724：URL 里也支持 {key}（如 Gemini 的 ?key=… 形式；auth 传空串时不带 Authorization 头）
       const u = String(url).replace('{key}', key)
       assertSafeApiUrl(u)
-      const res = await fetch(u, { headers, signal: AbortSignal.timeout(15000) })
+      const init = { headers, signal: AbortSignal.timeout(15000) }
+      const method = httpMethodOf(o)
+      if (method !== 'GET') {
+        init.method = method
+        const raw = o.body
+        if (raw !== undefined && raw !== null && String(raw).length) {
+          // 用户自己在头列表里写了 Content-Type 就用他的（不覆盖）
+          if (!headerNameExists(headers, 'content-type')) headers['Content-Type'] = 'application/json'
+          init.body = bodyWithPlaceholders(raw, key, o.base, o.params)
+        }
+      }
+      const res = await fetch(u, init)
       if (!res.ok) throw new Error('HTTP ' + res.status)
       return await res.json()
     }
@@ -2042,14 +2436,17 @@ export default {
       }
       const b = mergeNonEmpty(tpl.balance, model.balance) // v724：模型侧空串不再覆盖模板
       const base = String(model.baseUrl || '').replace(/\/+$/, '')
-      const url = String(tpl.probeUrl || b.url || (base ? base + '/v1/models' : '')).replace('{base}', base)
+      // v789（issue #190）：声明了 POST 等非 GET 方法时，测试就直接打**用户配置的余额接口**（带同一个 body）——
+      // 否则会拿 GET 去打一个只支持 POST 的地址、误报"测试失败"（probeUrl 多是 models 列表，body 不通用）。
+      const nonGet = httpMethodOf(b) !== 'GET'
+      const url = String(nonGet ? (b.url || tpl.probeUrl || '') : (tpl.probeUrl || b.url || (base ? base + '/v1/models' : ''))).replace('{base}', base)
       if (!url) return { ok: false, error: '没有可测试的接口（请填余额接口或 Base URL）' }
       // v761（安全修复 S1）：只在目的地可信时才带上凭据
       const k = await keyForDestination(model, tpl, url)
       if (!k.key) return { ok: false, code: k.code, error: k.error }
       const key = k.key
       try {
-        const data = await apiFetchJson(url, b.auth, key)
+        const data = await apiFetchJson(url, b.auth, key, { method: b.method, body: b.body, base: base, params: model.params })
         const bizErr = apiBusinessError(data)
         if (bizErr) return { ok: false, error: '测试失败: ' + bizErr }
         let detail = 'HTTP 200'
@@ -2060,14 +2457,41 @@ export default {
         return { ok: false, error: '测试失败: ' + String((err && err.message) || err).slice(0, 140) }
       }
     }
+    // v789（issue #180/#181）：额度接口里"多窗口 + 数组顺序不保证"的通用取数。
+    //   智谱 `GET /api/monitor/usage/quota/limit` 返回的 `data.limits[]` 是**扁平条目数组**：
+    //   `TOKENS_LIMIT` 是每条的 `type` 字段值（不是 `limits[0]` 的子对象），5h 窗口不保证排在 `[0]`
+    //   （实测：pro 账号 `limits[0]` 是 TIME_LIMIT，max 账号 `limits[0]` 是 TOKENS_LIMIT ⇒ 按位置取数必然出错过），
+    //   而且新注册/credit 制账号把 `type` 改成了 `CREDIT_LIMIT`。
+    //   所以模板可以声明 `pick: { list, type/types, unit, number }`：先选中**那一条**，再把它的字段当作取数根。
+    function pickQuotaEntry(data, pick) {
+      try {
+        if (!pick || !pick.list) return null
+        const arr = pickJsonPath(data, pick.list)
+        if (!Array.isArray(arr)) return null
+        const types = []
+        if (pick.type) types.push(String(pick.type))
+        if (Array.isArray(pick.types)) for (const t of pick.types) types.push(String(t))
+        const unit = (pick.unit === undefined || pick.unit === null) ? null : Number(pick.unit)
+        const number = (pick.number === undefined || pick.number === null) ? null : Number(pick.number)
+        for (const it of arr) {
+          if (!it || typeof it !== 'object') continue
+          if (types.length && types.indexOf(String(it.type)) < 0) continue
+          if (unit !== null && Number(it.unit) !== unit) continue
+          if (number !== null && Number(it.number) !== number) continue
+          return it
+        }
+        return null
+      } catch (err) { return null }
+    }
     // 订阅额度（Coding Plan）解析：各厂商字段不同，统一归一成「已用% + 重置时间 + 档位」
-    //   zhipu:    data.limits[0].TOKENS_LIMIT.percentage（已用%）+ nextResetTime
+    //   zhipu:    data.limits[] 里 type=TOKENS_LIMIT/CREDIT_LIMIT + unit=3(5h)/6(周) 的条目（v789 起按 pick 选）
     //   kimi:     usage.remaining / usage.limit（剩余/总量）
     //   minimax:  model_remains[0].current_interval_remaining_percent（剩余%）+ end_time(ms)
     async function fetchModelQuota(model) {
       if (!model) return { ok: false, error: '模型不存在' }
       const tpl = apiTemplateOf(model.provider) || {}
-      const q = tpl.quota
+      // v789（issue #180 建议 3）：模型条目也能覆盖额度配置 —— 厂商接口变动时用户可自救（不留空即覆盖）
+      const q = mergeNonEmpty(tpl.quota, model.quota)
       if (!q || !q.url) return { ok: false, code: 'NO_QUOTA', error: '该厂商没有订阅额度接口' }
       const base = String(model.baseUrl || '').replace(/\/+$/, '')
       const url = String(q.url).replace('{base}', base)
@@ -2076,31 +2500,33 @@ export default {
       if (!k.key) return { ok: false, code: k.code, error: k.error }
       const key = k.key
       try {
-        const data = await apiFetchJson(url, q.auth, key)
+        const data = await apiFetchJson(url, q.auth, key, { method: q.method, body: q.body, base: base, params: model.params })
         const bizErr = apiBusinessError(data)
         if (bizErr) return { ok: false, code: 'BIZ', error: bizErr }
         const j = q.json || {}
         const num = (v) => { const n = Number(v); return isFinite(n) ? n : null }
+        // v789：若模板声明了顶层 pick（单窗口 + 数组筛选），先把取数根换成选中的那条
+        const jroot = j.pick ? (pickQuotaEntry(data, j.pick) || {}) : data
         let usedPct = null, remainPct = null, resetAt = null, level = '', weeklyUsedPct = null
-        if (j.percent) { const p = num(pickJsonPath(data, j.percent)); if (p !== null) usedPct = p }
+        if (j.percent) { const p = num(pickJsonPath(jroot, j.percent)); if (p !== null) usedPct = p }
         if (j.remainPct) {
-          const p = num(pickJsonPath(data, j.remainPct))
+          const p = num(pickJsonPath(jroot, j.remainPct))
           if (p !== null) { remainPct = p; if (usedPct === null) usedPct = Math.max(0, 100 - p) }
         }
         if (j.weeklyRemainPct) {
-          const p = num(pickJsonPath(data, j.weeklyRemainPct))
+          const p = num(pickJsonPath(jroot, j.weeklyRemainPct))
           if (p !== null) weeklyUsedPct = Math.max(0, 100 - p)
         }
         if (j.remain && j.total) {
-          const r0 = num(pickJsonPath(data, j.remain))
-          const t0 = num(pickJsonPath(data, j.total))
+          const r0 = num(pickJsonPath(jroot, j.remain))
+          const t0 = num(pickJsonPath(jroot, j.total))
           if (r0 !== null && t0) {
             remainPct = Math.max(0, Math.min(100, r0 / t0 * 100))
             usedPct = Math.max(0, 100 - remainPct)
           }
         }
-        if (j.resetAt) resetAt = pickJsonPath(data, j.resetAt)
-        if (j.resetAtMs) { const ms = num(pickJsonPath(data, j.resetAtMs)); if (ms !== null) resetAt = ms }
+        if (j.resetAt) resetAt = pickJsonPath(jroot, j.resetAt)
+        if (j.resetAtMs) { const ms = num(pickJsonPath(jroot, j.resetAtMs)); if (ms !== null) resetAt = ms }
         if (j.level) level = String(pickJsonPath(data, j.level) || '')
         // v0.3.1：多窗口额度 —— 有些订阅额度接口一次返回多个窗口（如 OpenCode Go 的
         // rolling / weekly / monthly），每个窗口各有「已用% + 重置时间」。模板用
@@ -2111,11 +2537,13 @@ export default {
           const list = []
           for (const w of j.windows) {
             if (!w) continue
-            let wp = w.percent ? num(pickJsonPath(data, w.percent)) : null
+            // v789：每个窗口可以各自 pick 一条（智谱 5h=unit3 / 周=unit6），选中后以该条为取数根
+            const wroot = w.pick ? (pickQuotaEntry(data, w.pick) || {}) : data
+            let wp = w.percent ? num(pickJsonPath(wroot, w.percent)) : null
             if (wp !== null) wp = Math.max(0, Math.min(100, wp))
             let wr = null
             if (w.resetAt) {
-              const rv = pickJsonPath(data, w.resetAt)
+              const rv = pickJsonPath(wroot, w.resetAt)
               if (rv !== undefined && rv !== null && rv !== '') wr = rv
             }
             if (wp === null && wr === null) continue
@@ -2168,7 +2596,8 @@ export default {
       if (!k.key) return { ok: false, code: k.code, error: k.error }
       const key = k.key
       try {
-        const data = await apiFetchJson(url, b.auth, key)
+        // v789（issue #190）：把 method / body / params 一并交给取数层（默认 GET，与以前完全一致）
+        const data = await apiFetchJson(url, b.auth, key, { method: b.method, body: b.body, base: base, params: model.params })
         const j = b.json || {}
         let remaining = null
         let total = null
@@ -2407,12 +2836,57 @@ export default {
       if (p.allowCustomHost === true) model.allowCustomHost = true
       else if (p.allowCustomHost === false) delete model.allowCustomHost
       if (p.baseUrl !== undefined) model.baseUrl = String(p.baseUrl || '').slice(0, 300)
+      // v789（issue #190）：请求体里可用的 `{占位符}`（如 {uuid}）—— 只允许标量，键名受限
+      if (p.params && typeof p.params === 'object') {
+        const pr = {}
+        for (const k of Object.keys(p.params)) {
+          if (!/^[A-Za-z_][A-Za-z0-9_]{0,30}$/.test(k)) continue
+          const v = p.params[k]
+          if (v === undefined || v === null || typeof v === 'object') continue
+          pr[k] = String(v).slice(0, 300)
+        }
+        if (Object.keys(pr).length) model.params = pr
+        else delete model.params
+      }
+      if (p.quota && typeof p.quota === 'object' && p.quota.json && typeof p.quota.json === 'object') {
+        // v789（issue #180 建议 3）：允许模型条目覆盖额度配置（厂商接口变动时用户可自救）。
+        // 只收 JSON-safe 的形状，且路径字符串限长 —— 与模板同构，不做二次校验的滥用面。
+        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, 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])
+        }
+        if (Array.isArray(jin.windows)) {
+          qj.windows = jin.windows.slice(0, 6).map((w) => {
+            const o = { key: String((w && w.key) || '').slice(0, 20), label: String((w && w.label) || '').slice(0, 20) }
+            if (w && w.percent) o.percent = pathOf(w.percent)
+            if (w && w.resetAt) o.resetAt = pathOf(w.resetAt)
+            if (w && w.pick && typeof w.pick === 'object') {
+              const pk = { list: pathOf(w.pick.list) }
+              if (w.pick.type) pk.type = String(w.pick.type).slice(0, 40)
+              if (Array.isArray(w.pick.types)) pk.types = w.pick.types.slice(0, 4).map((t) => String(t).slice(0, 40))
+              if (w.pick.unit !== undefined) pk.unit = Number(w.pick.unit)
+              if (w.pick.number !== undefined) pk.number = Number(w.pick.number)
+              o.pick = pk
+            }
+            return o
+          })
+        }
+        if (qj.url && (Object.keys(qj).length > 1)) model.quota = qj
+      }
       if (p.balance && typeof p.balance === 'object') {
         // v724：空字段不写入（stripEmptyDeep）→ 模板默认值继续生效；
         // 全部为空时直接删掉 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),
           json: {
             remaining: String((p.balance.json && p.balance.json.remaining) || '').slice(0, 200),
             total: String((p.balance.json && p.balance.json.total) || '').slice(0, 200),
@@ -2426,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 },
           })
         }
@@ -2513,6 +2987,10 @@ export default {
         // entry.balance 是数值，不能当描述用（否则面板保存会用空值覆盖描述）
         const tplE = apiTemplateOf(m.provider) || {}
         entry.balanceDesc = mergeNonEmpty(tplE.balance, m.balance) // v724：空串不覆盖模板
+        // v789（issue #189）：把当前的凭据放行标志也下发 —— 前端勾选框要能**显示现状**，
+        //   否则"看不到 → 保存时显式传 false"会把用户手改文件开的口子又关掉（反而更糟）。
+        entry.allowCustomHost = m.allowCustomHost === true
+        entry.params = (m.params && typeof m.params === 'object') ? m.params : null
         if (m.id === API_BUILTIN_ID) {
           entry.balanceMode = 'api'
           entry.hasBalanceApi = true
@@ -2635,7 +3113,7 @@ export default {
       const summary = daySummary(led, todayKey())
       const nowSec = Math.floor(Date.now() / 1000)
       return {
-        ...visible, version: '0.3.17', isPeak: isPeakTime(nowSec),
+        ...visible, version: '0.4.0', versionLabel: VERSION_LABEL, isPeak: isPeakTime(nowSec),
         // 峰谷切换点与节假日清单：前端倒计时要与宿主同源（否则法定节假日会算错切换点）
         peakNextChangeAt: nextPeakChangeAt(nowSec),
         peakHolidays: HOLIDAY_VALLEY_LIST,
@@ -2701,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,
@@ -2716,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
@@ -2734,6 +3215,7 @@ export default {
         usageMode: um,
         peakMode: pm,
         bubbleOn: bo,
+        pressOn: po,
         turnCostOn: tco,
         turnCostCloseMs: tcc,
         scrollGapOn: sgo,
@@ -2755,6 +3237,7 @@ export default {
             usageMode: um,
             peakMode: pm,
             bubbleOn: bo,
+            pressOn: po,
             turnCostOn: tco,
             turnCostCloseMs: tcc,
             scrollGapOn: sgo,
@@ -3104,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 }))
         }
       },
     }))
@@ -3164,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),
@@ -3182,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,
+        })))
       },
     }))
 
@@ -3200,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',
@@ -3605,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)
@@ -3626,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) {
@@ -3779,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) {
@@ -3801,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 }))