dsh-whale-widget 0.3.13 → 0.3.15

package/README.md

@@ -11,6 +11,7 @@ DeepSeek Harness（DSH）Web 界面右下角的常驻挂件：小鲸鱼气泡图
 | 你要挂在哪 | 用哪条分支 | 安装方式 |
 |---|---|---|
 | **DSH Web 界面右下角**（就是这个 README 描述的插件） | `main`（默认分支） | `dsh plugin --profile web add dsh-whale-widget`（推荐，装 npm 已发布版）；也可以从本仓库装 `dsh plugin --profile web add github:MeteorNOX/DeepSeek-Balance-Whale-Widget`，但那样装的是 **main 当前状态、不跟随已发布版本** |
+| **官方桌面客户端（Electron）右下角** | `main`（同一个包） | ⚠️ **不能用** `--profile web`（桌面端读的是 `desktop` profile，CLI 也拒绝 `--profile desktop`）—— 在桌面端会话里**让 DSH 自己装**，见下方「官方桌面端（Electron 客户端）请先看这一节」 |
 | **Codex 桌面应用**（跟随 Codex 窗口、无独立网页） | [`For-Codex`](https://github.com/MeteorNOX/DeepSeek-Balance-Whale-Widget/tree/For-Codex) | 该分支的 `api-balance-whale`：解压到 `%USERPROFILE%\plugins\api-balance-whale`，再按分支内的 [安装说明](https://github.com/MeteorNOX/DeepSeek-Balance-Whale-Widget/blob/For-Codex/docs/INSTALL-AND-ROLLBACK-0.2.0.md) 注册计划任务（也可以直接交给 Codex 自己装喵~） |
 
 ⚠️ **两条分支互不兼容**：`For-Codex` 的插件不能用 `dsh plugin … add` 装进 DSH 网页；本主分支的插件也不能在 Codex 桌面里运行。上表第一行是本仓库默认分支（`main`）的能力，第二行是另一个分支的能力。
@@ -24,7 +25,7 @@ DeepSeek Harness（DSH）Web 界面右下角的常驻挂件：小鲸鱼气泡图
 ### 记账与显示
 
 - 🐋 **常驻自启**：随 DSH Web 界面每次打开自动出现（标准 DSH bundle 插件）
-- 💰 **余额**：60 秒自动刷新 + 点击鲸鱼手动刷新；余额变化时数字**滚动动画**；瞬时网络抖动自动沿用最近余额不报错
+- 💰 **余额**：60 秒自动刷新 + 点击鲸鱼手动刷新；余额变化时数字**滚动动画**；瞬时网络抖动自动沿用最近余额不报错。**两种取数方式，API key 优先**：① DSH 凭据里的 `DEEPSEEK_API_KEY`；② **DSH 账号登录态** —— 通过「设置 → 账号与余额」登录了 DeepSeek 账号、又没配 API key 时自动使用（**不需要去 platform 建 key**）
 - 📊 **今日已用（小鲸鱼记账）**：不需要任何令牌。余额**下降**按观测累计为消费，余额**上升**（充值 / 赠金）单独记录、不会冲掉已有消费；检测到余额增加会提示「待核对余额调整」，可在「小鲸鱼记账 → **DeepSeek（内置）→ 设置 → 余额校正**」按实际累计到账金额与非调用扣减校正 —— **「已观测消费」与「余额校正」都是 DeepSeek 账户口径**（由该 API key 的余额观测得出，不含其它厂商；「本机模型费用」才是所有模型的本地估算）（逐轮明细保留 90 天或最多 2 万条、逐日归档保留 365 天，超期数据归档到 `.dshw-usage-archive.json`）；金额按 8 位小数记账、显示保留两位
 - 💬 **每轮对话消耗**：监听 DSH 本机会话事件，按模型**真实 usage**（input / cache / output / reasoning tokens）换算金额，每轮结束弹出消耗泡泡；可开关、自动关闭秒数可设（0 = 不自动关闭），**泡泡内容可自定义**（模块化，金额用 `{cost}` 引用），入口：菜单 → 每轮消耗提示 → 「自定义提示」
 - ⛰️ **峰谷定价**：工作日高峰 9:00–12:00、14:00–18:00（北京时间），其余空闲；2026-08-23 起**周末全天谷价**。峰谷模块支持状态文字、倒计时、"梁文峰谷 / !?强强?! / 简洁"等多种样式
@@ -143,6 +144,33 @@ dsh-whale-widget/
 
 ## 安装
 
+### 官方桌面端（Electron 客户端）请先看这一节 ⚠️
+
+**桌面端读的不是 `web` profile。** 官方桌面客户端用的是 **`desktop` profile**（`%USERPROFILE%\.dsh\profiles\desktop`），而 `dsh plugin` 命令行**按设计拒绝**碰它：
+
+```
+error: profile "desktop" is managed exclusively by the Electron application
+```
+
+所以下面「方式 A~D」里的 `--profile web` 命令**对桌面端不适用** —— 按它装完，插件落在 `web` profile 里，而桌面窗口读的是 `desktop` profile，一个字也读不到。表现就是「右下角什么都没有（连 ☰ 也没有）、控制台也不报错」。
+
+**桌面端的正确装法：让桌面端里的 DSH 自己装。**
+
+在桌面客户端的会话里直接说一句就够了（例如「把 dsh-whale-widget 装上」）—— 它会调用内置的 `plugin_manager` 工具，而那个工具的**作用域就是当前 profile**（桌面端 = `desktop`），由客户端自带的插件管理器在 profile 目录内用**自带的 pnpm** 完成安装，并把 `dsh-whale-widget` 写进该 profile 的 `dsh.profile.bundles`。需要指定版本时也可以写 `dsh-whale-widget@<版本号>`（例如 `dsh-whale-widget@0.3.13`，**填当下的最新版**）这样的安装规格。
+
+> 等价的手工路径是在该 profile 目录里用客户端自带的 pnpm 装一次、再手工写进 `dsh.profile.bundles`，但**不推荐** —— 那是客户端自己管理的目录。
+
+**生效方式（实测）**：新装一个包通常**热生效**（工具返回 `"application":"applied"`）；**换版本（升级）需要重启客户端**（返回 `"restart-required"`）。
+
+**装完怎么自检**（两条分别对应宿主半区与客户端半区）：
+
+- **宿主半区**：`%USERPROFILE%\.dsh\.dshw-turn.json` 存在，且 `seq` 随对话递增；
+- **客户端半区**：桌面端 `%APPDATA%\@deepseek-ai\dsh-desktop\Local Storage\leveldb` 里出现 `dshw-pos` / `dshw-last-seq` —— 这两个键**只有挂件前端**会写。
+
+桌面端界面里看不到插件版本号时，可以看 `%USERPROFILE%\.dsh\profiles\desktop\package.json` 的 `dsh.profile.bundles` 和同目录的 `pnpm-lock.yaml`。
+
+> 下面方式 A~D 都是 **Web（`dsh web`）** 的安装方式。
+
 ### 方式 A：已有本插件的完整资源包（本地目录 / 压缩包）（推荐）
 
 适用于别人直接发给你一个 zip，或你手上已有一份解压好的插件目录（目录里应有 `package.json`、`cordis.patch.yml`、`lib/`、`assets/`、`README.md`）。
@@ -264,17 +292,33 @@ MeteorNOX/DeepSeek-Balance-Whale-Widget，或者我本地已经有这个插件
 - curl "http://127.0.0.1:3080/dsh-whale/audio-fragment.wav?id=end_a" 也应返回 200 audio/wav
   （用来确认资源包里的内置音效已随包就位；若是 404 说明 assets/ 不完整）
 
-另外请检查 DSH 凭据里是否配置了 DEEPSEEK_API_KEY（没有就提示用户配置）。
+另外请检查 DSH 凭据里是否配置了 DEEPSEEK_API_KEY（没有就提示用户配置；如果用户是用 DSH 账号登录的，较新 DSH 上不配 key 也能取余额，**别把"没 key"当成故障**）。
 ```
 
 ## 凭据（安装后必读）
 
-只需一个凭据：
+**余额有两种取数方式（API key 优先，两者互不干扰）：**
 
-- **`DEEPSEEK_API_KEY`（必需）**：DeepSeek API 密钥，用于拉取余额（`GET https://api.deepseek.com/user/balance`）。在 DSH 凭据服务里配置（凭据管理界面 / `.dsh/.credentials.yaml`）。
+- **`DEEPSEEK_API_KEY`（推荐）**：DeepSeek API 密钥，用于拉取余额（`GET https://api.deepseek.com/user/balance`）。在 DSH 凭据服务里配置（凭据管理界面 / `.dsh/.credentials.yaml`）。
+- **DSH 账号登录态（可选，**不需要** API key）**：如果你是通过 DSH 的「设置 → 账号与余额」**登录 DeepSeek 账号**的，插件会在**没有 API key 时自动**改用 DSH 自己的账号服务取余额（充值钱包 + 赠金钱包，两者相加作为记账基准）。token、平台请求头与失效清理都由 DSH 负责，**插件不接触你的账号令牌**。
+  - 需要**较新的 DSH**（如桌面端 `0.1.7-rc.2`）才有这个服务；老版本、未登录、或账号没有余额钱包时，会回到下面的「未配置」提示。
+  - 账号态与 API key 态的**账本是分开的**（按账号标识区分）：从 API key 换成账号登录后，"今日已用"会从新的观测重新起算。
 
 > **不需要** `DEEPSEEK_PLATFORM_TOKEN`。早期版本的"实时·令牌"模式已下线，今日已用统一由**小鲸鱼记账**（余额差 + 会话事件）计算，零令牌开箱即用。
 
+### 安全边界（0.3.15 起，**请务必一读**）
+
+插件会把凭据交给谁、以及谁能改这件事的规则：
+
+1. **凭据只会发往"该厂商内置模板里写死的端点"**。
+   自定义模型里如果填了一个**不在该厂商模板内**的接口地址（或者模板地址里用 `{base}` 指向你自己填的地址），插件**默认不会把凭据发过去**，而是返回一条明确提示。
+   - 自建网关（New API / 自托管 / Ollama 等）确实需要自定义地址：请**在这台机器本机**打开插件面板，对该模型勾选「**允许把凭据发送到自定义地址**」。这是按模型保存的一个显式标志。
+2. **配置与凭据的改动只能来自本机（回环地址）**。
+   所有写请求（保存模型、写/删凭据、改外观设置等）如果来源不是 `127.0.0.1` / `localhost` / `[::1]`，一律 `403`。
+   - 为什么：任意持有 DSH Web 会话的人如果能写模型配置，就等于能决定"凭据被发往哪里" —— 那会把你的 API key 直接送到对方服务器上。**只读接口不受影响**（局域网里照常能看挂件）。
+   - 需要远端管理？用环境变量显式声明：`DSHW_ADMIN_HOSTS=192.0.2.10:3080,myhost.lan`（逗号分隔，可带端口；默认空）。
+3. 接口地址不允许携带用户名/密码（`https://user:pass@host/`），凭据名只允许字母、数字与下划线。
+
 添加自定义模型时，还会按需用到各自厂商的凭据名（都可不配，用到哪个配哪个）：
 
 | 凭据名 | 用途 |
@@ -352,13 +396,18 @@ curl http://127.0.0.1:3080/dsh-whale/audio.json
 
 ## 常见问题
 
-- **挂件不出现**：确认安装命令成功；`dsh --profile web --dump-config` 里能看到 `dsh-whale-widget`；重启 `dsh web` 后 F5。
+- **挂件不出现**：
+  - **Web（`dsh web`）**：确认安装命令成功；`dsh --profile web --dump-config` 里能看到 `dsh-whale-widget`；重启 `dsh web` 后 F5。
+  - **官方桌面端**：先确认装对了 profile —— 桌面端读的是 **`desktop` profile**，**不能**用 `--profile web`（而 `--profile desktop` 会被 CLI 拒绝，这是设计如此）。正确入口见上面「**官方桌面端（Electron 客户端）请先看这一节**」，并用那里的**两条自检**判断是「没装到位」还是「装了但没渲染」。
 - **本插件所有接口（`/dsh-whale/*`）的访问校验**：默认只接受**回环地址**（`127.0.0.1` / `localhost` / `[::1]`）的请求，并拒绝跨站标记（`Sec-Fetch-Site: cross-site`）与 Origin 和 Host 不同源的请求 —— 这是防「恶意网页读写本机接口」的信任栅栏（issue #92 / #136）。如果你把 `dsh web` 放在**反向代理或局域网地址**后面，请用环境变量声明允许的 Host（逗号分隔，可带端口），否则会被 403：
   ```bash
   DSHW_TRUSTED_HOSTS=dsh.example.com,10.0.0.5:3080 dsh web
   ```
 - **图片/音效不显示、没声音**：确认插件包内 `assets/` 完整（`DSniang1.png`、`*.mp3`、`minecraft-exp-orb.wav` 等）；缺失时相关功能静默降级。
-- **余额报「未配置 DEEPSEEK_API_KEY」**：去 DSH 凭据里配置。
+- **余额报「未配置 DEEPSEEK_API_KEY」**：去 DSH 凭据里配置 API key；**或者**用「设置 → 账号与余额」登录 DeepSeek 账号（较新 DSH 支持）—— 没配 key 时插件会自动走账号态，不需要去 platform 建 key。
+- **余额拿到了、但提示「账本不可用 / 已停止写入以保护原记录」**：账本文件（`.dshw-usage.json`）被外部改坏或结构异常，插件**拒绝覆盖**它以免丢数据。先把它备份改名让插件重建，再按需用「余额校正」补账。
+- **保存设置报 `403` / 在别的机器上改了配置不生效**：0.3.15 起**写操作只能在运行 DSH 的那台机器上、用 `127.0.0.1`（本机地址）打开界面进行**。从局域网或反向代理访问时，读没问题、写会被拒。需要远端管理就用 `DSHW_ADMIN_HOSTS` 显式授权那台机器（见「凭据 → 安全边界」）。
+- **提示「该地址不是 … 的内置端点，已拒绝把凭据发出去」**：这是 0.3.15 的安全策略 —— **自定义接口地址默认拿不到凭据**。确认那是你自己的网关（New API / 自托管等）后，在**本机**打开面板，对该模型勾选「允许把凭据发送到自定义地址」。
 - **今日已用显示 `--`**：先等一次成功的余额观测；统计从该观测时刻开始，起点之前的消费不在此区间内。
 - **今日已用与官网有差异**：先核对同一账户、同一币种与同一统计区间；若有充值或其它余额调整，用「小鲸鱼记账 → DeepSeek（内置）→ 设置 → 余额校正」填写实际到账金额。余额接口只返回余额快照、不提供充值流水，充值与消费发生在同一次刷新间隔时需要实际到账金额才能校正。
 - **充值后消费数字没变**：这是预期行为——充值不会增加消费；数字上方会出现「待核对余额调整」，提示你补充本统计区间的累计到账金额。
@@ -389,6 +438,7 @@ curl http://127.0.0.1:3080/dsh-whale/audio.json
 
 ## 致谢
 
+- **DSH 账号登录态读余额**（端点与鉴权头、凭据记录的位置、DSH 自身 `deepseekAccount` 服务的推荐调用方式，以及三个集成坑：账户标识字符集、赠金要计入基准、服务可能不存在）由 GitHub 用户 [@yybai25](https://github.com/yybai25) 在 [#157](https://github.com/MeteorNOX/DeepSeek-Balance-Whale-Widget/issues/157) 中给出完整规格与**已在自己机器上验证过的参考实现**；**0.3.14 据此实现**（只调 DSH 服务、不接触账号令牌）。感谢他的贡献。
 - 充值记账修复方案（余额上升与下降分开记账、显式余额校正公式、按账户/币种隔离观测窗口、账本原子写入与迁移备份）由 GitHub 用户 [@Yang-huai406](https://github.com/Yang-huai406) 独立设计并实现为可运行的修复分支；**0.3.1 在该方案基础上移植合并**，并保留本项目既有的音效修复。感谢他的支持。
 - OpenCode Go 订阅额度（多窗口额度 `quota.json.windows`、按窗口展示与紧凑重置倒计时、「订阅额度」模块的窗口选择）由 GitHub 用户 [@ELFsay](https://github.com/ELFsay) 提交（[#99](https://github.com/MeteorNOX/DeepSeek-Balance-Whale-Widget/pull/99)），已合入 `main`。感谢他的贡献。
 - **历史合并 PR 的贡献者**（按合入顺序，均已进入本仓库代码 / 发布流程）：

package/lib/index.js

@@ -692,6 +692,38 @@ export default {
           + 'DSHW_TRUSTED_HOSTS 声明允许的 Host（逗号分隔，可带端口）。')
       } catch (err) {}
     }
+    // v761（安全修复 S1）：**写请求（POST/PUT/PATCH/DELETE）必须来自本机（回环）**。
+    // 为什么：任意持有 DSH Web 会话的人都能 `POST /dsh-whale/api-models.json` 写一个自定义模型，
+    // 而余额 / 探活 / 额度会**带着解析出来的真实凭据**去请求模型里那个 URL ⇒ 凭据外带。
+    // 「改配置」等于「决定把凭据发往哪里」，所以它必须与"坐在这台机器前"绑定；
+    // **只读接口不受影响**（局域网里仍能正常看挂件）。
+    // 运维若确实需要远端管理，显式声明 DSHW_ADMIN_HOSTS（逗号分隔，可带端口），默认为空。
+    const ADMIN_AUTHORITIES = String(process.env.DSHW_ADMIN_HOSTS || '')
+      .split(',').map((s) => s.trim().toLowerCase()).filter(Boolean)
+    const WRITE_METHODS = new Set(['POST', 'PUT', 'PATCH', 'DELETE'])
+    function writeRejection(req) {
+      try {
+        const method = String((req && req.method) || 'GET').toUpperCase()
+        if (!WRITE_METHODS.has(method)) return null
+        const headers = (req && req.headers) || {}
+        let hostUrl = null
+        try { hostUrl = new URL('http://' + String(headers.host || '')) } catch (err) { return 403 }
+        if (isLoopbackHostname(hostUrl.hostname)) return null
+        const authority = hostUrl.host.toLowerCase()
+        const hostname = hostUrl.hostname.toLowerCase()
+        if (ADMIN_AUTHORITIES.some((e) => (e.indexOf(':') >= 0 ? e === authority : e === hostname))) return null
+        if (!writeRejection.warned) {
+          writeRejection.warned = true
+          try {
+            console.warn('[whale-balance] 已拒绝一个来自非本机的**写请求**（Host=' + authority + '）。'
+              + '自 0.3.15 起，配置与凭据的改动只能在**本机**（回环地址）打开界面进行 —— '
+              + '否则任何拿到 Web 会话的人都能把凭据改指向自己的服务器，从而把真实 API key 带走。'
+              + '确需远端管理，请用环境变量 DSHW_ADMIN_HOSTS 声明允许的管理主机。')
+          } catch (err) {}
+        }
+        return 403
+      } catch (err) { return 403 } // 自身出错 → 拒绝（fail-closed）
+    }
     function rejected(req, res) {
       const deny = (code) => {
         try { res.statusCode = code || 403; res.end() } catch (err) {}
@@ -701,6 +733,9 @@ export default {
       // 先算栅栏可用性，再自校验：非回环 Host 在"栅栏可用"时交给栅栏判（它知道 --trusted-host）
       const self = selfRejection(req, { fenceAvailable: !!conn })
       if (self !== null) return deny(self)
+      // v761（安全修复 S1）：写完再放行 —— 读请求不受影响
+      const write = writeRejection(req)
+      if (write !== null) return deny(write)
       if (!conn) return false // 已通过自校验；此刻没有宿主栅栏可委托（加载时已 warn）
       let code
       try {
@@ -878,6 +913,60 @@ export default {
       )
     }
 
+    // v759（issue #157）：**DSH 账号登录态**的余额路径。
+    // 只通过 DSH 账号登录的用户没有 API key，余额在 DeepSeek 平台的账号接口上。
+    // **不要自己拼 HTTP**：token 注入、5 个 `x-client-*` 头、401/`40003` 失效清理全部由 DSH 的
+    // `deepseekAccount` 服务负责（DSH 自己的「账号与余额」设置卡片就是 `ctx.deepseekAccount.getBalance(client)`）。
+    // ⚠️ 必须用 `ctx.get('deepseekAccount')` 读**可选服务**，**绝不能写进 inject** —— 老宿主根本没有这个服务，
+    //    一旦进 inject，整个插件会永远等不到服务而**完全不 apply**（比没有这个功能严重得多）。
+    // ⚠️ 与 API key 路径**互不干扰**（API key 永远优先；DSH 自己的注释也是 "Neither route falls back to the other"）。
+    async function fetchAccountBalance() {
+      let account = null
+      try { account = typeof ctx.get === 'function' ? ctx.get('deepseekAccount') : null } catch (err) { account = null }
+      if (!account || typeof account.getBalance !== 'function') return null
+      // 账户标识：优先用账号服务给的稳定 id（不同账号 → 不同账本 scope）；取不到就退回固定标识。
+      // 一律 sha256[:24] 十六进制 —— accounting.mjs 校验 scope 必须匹配 /^[a-zA-Z0-9_-]{1,80}$/
+      // （带冒号这种可读写法会直接抛「账户标识无效」，见 issue #157 报告人踩的坑 1）。
+      let accountId = null
+      try {
+        const state = typeof account.getState === 'function' ? account.getState() : null
+        accountId = (state && (state.userId || (state.profile && state.profile.userId))) || null
+      } catch (err) { accountId = null }
+      let result
+      try {
+        result = await account.getBalance({
+          version: String(process.env.DSH_CLIENT_VERSION || process.env.DSH_VERSION || '') || 'unknown',
+          locale: String(process.env.DSH_LOCALE || '') || 'zh_CN',
+          timezoneOffsetSeconds: -new Date().getTimezoneOffset() * 60, // 东为正的整秒
+        })
+      } catch (err) { return null }
+      // 未登录 / 没有 grant / 平台失败 → 一律返回 null，让调用方退回原来的文案（**不缓存错误**）
+      if (!result || result.status !== 'ready' || !Array.isArray(result.value) || result.value.length === 0) 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)
+        .reduce((s, w) => s + Number(w.balance), 0)
+      const recharge = sumOf(result.value)
+      const bonus = sumOf(result.bonusWallets)
+      return {
+        ok: true,
+        // 充值 + 赠金：与 API key 路径的 `total_balance` 同口径（那个字段本身也是两者相加），
+        // 否则"按余额差"推算的今日已用会偏小（issue #157 报告人的坑 2）。
+        totalBalance: Number((recharge + bonus).toFixed(6)),
+        rechargeBalance: Number(recharge.toFixed(6)),
+        bonusBalance: Number(bonus.toFixed(6)),
+        currency,
+        balanceSource: 'account',
+        accountTag: createHash('sha256').update('dsh-account:' + (accountId === null ? 'default' : String(accountId))).digest('hex').slice(0, 24),
+        updatedAt: new Date().toISOString(),
+      }
+    }
+
     async function fetchBalance() {
       // v739（用户反馈「每次新实例的第一次余额请求都失败」）：
       // ① 冷启动时凭据服务可能尚未就绪（resolve 抛错），这与「确实没配置」不同 → 短延迟重试一次；
@@ -894,7 +983,13 @@ export default {
         }
       }
       if (!cred) {
-        return { ok: false, code: 'NO_KEY', error: '未配置 DEEPSEEK_API_KEY' }
+        // 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 账号，或该账号没有余额钱包）',
+        }
       }
       let lastErr = null
       for (let attempt = 0; attempt < 2; attempt++) {
@@ -930,6 +1025,7 @@ export default {
           totalBalance: Number(info.total_balance),
           accountTag: createHash('sha256').update(String(cred.value)).digest('hex').slice(0, 24),
           currency: String(info.currency || 'CNY'),
+          balanceSource: 'apikey',
           updatedAt: new Date().toISOString(),
         }
       }
@@ -1092,7 +1188,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.13', today: todayData, days7,
+        ok: true, version: '0.3.15', 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),
@@ -1671,6 +1767,71 @@ export default {
         if (a === 0) throw new Error('禁止访问该地址')
       }
       if (/^fe[89ab][0-9a-f]:/i.test(host)) throw new Error('禁止访问 link-local 地址')
+      // v761（安全修复 S1）：URL 里不允许带 userinfo（`https://user:pass@host/`）——
+      // 它是把凭据塞进 URL 的另一种写法，也会让日志/报错里出现凭据
+      if (parsed.username || parsed.password) throw new Error('接口地址不允许携带用户名/密码')
+    }
+    // —— v761（安全修复 S1）：**凭据目的地白名单** ——
+    // 规则：只有当目标 origin **恰好等于该厂商内置模板里写死的端点**时，才允许携带凭据；
+    // 其它地址（用户自定义 URL、以及由 `{base}` 展开出来的地址）都必须带 `model.allowCustomHost === true`
+    // 才放行 —— 而该标志**只能由本机（回环）来源的写请求设置**（见 writeRejection），
+    // 因此远端会话即使改了配置，也拿不到凭据。
+    // 注意：**含 `{base}` 的模板 URL 不算可信**（base 是用户可填字段），一律按自定义地址处理。
+    function originOfUrl(u) {
+      try {
+        const p = new URL(String(u))
+        if (p.protocol !== 'http:' && p.protocol !== 'https:') return ''
+        return p.origin.toLowerCase()
+      } catch (err) { return '' }
+    }
+    function templateOrigins(tpl) {
+      const out = new Set()
+      const add = (u) => {
+        const s = String(u == null ? '' : u)
+        if (!s || s.indexOf('{base}') >= 0) return
+        const o = originOfUrl(s.replace('{key}', 'placeholder'))
+        if (o) out.add(o)
+      }
+      add(tpl && tpl.probeUrl)
+      add(tpl && tpl.balance && tpl.balance.url)
+      add(tpl && tpl.balance && tpl.balance.usage && tpl.balance.usage.url)
+      add(tpl && tpl.quota && tpl.quota.url)
+      return out
+    }
+    function credentialMayGoTo(model, tpl, url) {
+      const o = originOfUrl(url)
+      if (!o) return false
+      if (templateOrigins(tpl).has(o)) return true
+      return !!(model && model.allowCustomHost === true)
+    }
+    function warnCredDestinationOnce(url) {
+      try {
+        const o = originOfUrl(url) || '(无效地址)'
+        if (!warnCredDestinationOnce.seen) warnCredDestinationOnce.seen = new Set()
+        if (warnCredDestinationOnce.seen.has(o)) return
+        warnCredDestinationOnce.seen.add(o)
+        console.warn('[whale-balance] 已拒绝把凭据发送到非内置端点：' + o
+          + '（若这是你自建/自托管的网关，请在**本机**打开插件面板，对该模型勾选「允许把凭据发送到自定义地址」）')
+      } catch (err) {}
+    }
+    // 解析凭据 + 目的地校验：所有"带凭据发请求"的地方都必须走这里
+    async function keyForDestination(model, tpl, url) {
+      let key = ''
+      try {
+        const cred = await ctx.credentials.resolve(model.keyRef || tpl.keyRef || '')
+        key = cred && cred.value ? String(cred.value) : ''
+      } catch (err) { key = '' }
+      if (!key) return { key: '', code: 'NO_KEY', error: '未配置 ' + (model.keyRef || tpl.keyRef || 'API key') }
+      if (!credentialMayGoTo(model, tpl, url)) {
+        warnCredDestinationOnce(url)
+        return {
+          key: '', code: 'DEST_NOT_ALLOWED',
+          error: '该地址不是 ' + String((tpl && tpl.name) || model.provider || '该厂商') + ' 的内置端点，'
+            + '已拒绝把凭据发出去。若这是你自建/自托管的网关，请**在本机**打开插件面板，'
+            + '对该模型勾选「允许把凭据发送到自定义地址」后重试。',
+        }
+      }
+      return { key, code: '', error: '' }
     }
     async function apiFetchJson(url, auth, key) {
       const headers = {}
@@ -1713,16 +1874,14 @@ export default {
         }
         return { ok: false, error: (cs && cs.error) || '未找到 Codex 会话目录' }
       }
-      let key = ''
-      try {
-        const cred = await ctx.credentials.resolve(model.keyRef || tpl.keyRef || '')
-        key = cred && cred.value ? String(cred.value) : ''
-      } catch (err) { key = '' }
-      if (!key) return { ok: false, error: '未配置 ' + (model.keyRef || tpl.keyRef || 'API key') }
       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)
       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 bizErr = apiBusinessError(data)
@@ -1744,14 +1903,12 @@ export default {
       const tpl = apiTemplateOf(model.provider) || {}
       const q = tpl.quota
       if (!q || !q.url) return { ok: false, code: 'NO_QUOTA', error: '该厂商没有订阅额度接口' }
-      let key = ''
-      try {
-        const cred = await ctx.credentials.resolve(model.keyRef || tpl.keyRef || '')
-        key = cred && cred.value ? String(cred.value) : ''
-      } catch (err) { key = '' }
-      if (!key) return { ok: false, code: 'NO_KEY', error: '未配置 ' + (model.keyRef || tpl.keyRef || 'API key') }
       const base = String(model.baseUrl || '').replace(/\/+$/, '')
       const url = String(q.url).replace('{base}', base)
+      // v761（安全修复 S1）：额度 URL 虽来自模板，但 `{base}` 会被用户字段改写，同样要校验目的地
+      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, q.auth, key)
         const bizErr = apiBusinessError(data)
@@ -1838,14 +1995,12 @@ export default {
       const tpl = apiTemplateOf(model.provider) || {}
       const b = mergeNonEmpty(tpl.balance, model.balance) // v724：模型侧空串不再覆盖模板
       if (!b.url) return { ok: false, code: 'NO_URL', error: '未配置余额接口地址' }
-      let key = ''
-      try {
-        const cred = await ctx.credentials.resolve(model.keyRef || tpl.keyRef || '')
-        key = cred && cred.value ? String(cred.value) : ''
-      } catch (err) { key = '' }
-      if (!key) return { ok: false, code: 'NO_KEY', error: '未配置 ' + (model.keyRef || tpl.keyRef || 'API key') }
       const base = String(model.baseUrl || '').replace(/\/+$/, '')
       const url = String(b.url).replace('{base}', base)
+      // 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 j = b.json || {}
@@ -1857,9 +2012,13 @@ export default {
         if (j.used) { const v = apiNum(pickJsonPath(data, j.used), j.scale); if (v !== null) used += v }
         if (b.usage && b.usage.url) {
           const u = b.usage
-          const d2 = await apiFetchJson(String(u.url).replace('{base}', base), u.auth || b.auth, key)
+          // v761（安全修复 S1）：usage 是可选增强 —— 目的地不可信就跳过，绝不把凭据发出去
+          const usageUrl = String(u.url).replace('{base}', base)
+          if (credentialMayGoTo(model, tpl, usageUrl)) {
+          const d2 = await apiFetchJson(usageUrl, u.auth || b.auth, key)
           const j2 = u.json || {}
           if (j2.used) { const v = apiNum(pickJsonPath(d2, j2.used), j2.scale); if (v !== null) used += v }
+          } else { warnCredDestinationOnce(usageUrl) }
         }
         if (remaining === null && total !== null) remaining = total - used
         if (remaining === null) return { ok: false, code: 'SHAPE', error: '接口返回里没找到配置的字段（检查 JSON 路径）' }
@@ -2063,6 +2222,8 @@ export default {
       if (!tpl) return { ok: false, error: '未知的厂商模板' }
       const name = String(p.name || '').trim().slice(0, 30) || tpl.name
       const keyRef = String(p.keyRef || tpl.keyRef || '').trim().slice(0, 64) || tpl.keyRef
+      // v761（安全修复 S1）：凭据名加白名单 —— 原实现接受任意字符串，理论上能写到别的键名上
+      if (!/^[A-Za-z0-9_]{1,64}$/.test(keyRef)) return { ok: false, error: '凭据名只能包含字母、数字与下划线（≤64 字符）' }
       const id = p.id ? String(p.id) : ('api_' + Date.now().toString(36) + '_' + Math.random().toString(36).slice(2, 7))
       const reg = readApiRegistry()
       let model = reg.models.find((m) => m && m.id === id)
@@ -2074,6 +2235,11 @@ export default {
       model.provider = p.provider
       model.currency = String(p.currency || tpl.currency || 'CNY').toUpperCase().slice(0, 8)
       model.keyRef = keyRef
+      // v761（安全修复 S1）：**允许把凭据发往自定义地址**（自建/自托管网关需要）。
+      // 该标志是"凭据目的地白名单"的唯一例外，而所有写请求都被限制为**本机来源**（见 writeRejection），
+      // 所以远端会话即使能改配置，也无法给自己开这个口子。缺省不动（前端局部更新不会误抹）。
+      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)
       if (p.balance && typeof p.balance === 'object') {
         // v724：空字段不写入（stripEmptyDeep）→ 模板默认值继续生效；
@@ -2153,6 +2319,17 @@ export default {
         let entry = {
           id: m.id, name: m.name, provider: m.provider, currency: m.currency,
           keyRef: m.keyRef, builtin: !!m.builtin, baseUrl: m.baseUrl || '',
+          // v761（安全修复 S1）：该模型当前的目的地拿不到凭据（非厂商内置端点且未在本机确认过），
+          // 前端据此提示用户"要去本机面板确认"，而不是让余额莫名其妙地空着。
+          needsHostConfirm: (() => {
+            try {
+              const tpl2 = apiTemplateOf(m.provider) || {}
+              const b2 = mergeNonEmpty(tpl2.balance, m.balance) || {}
+              const base2 = String(m.baseUrl || "").replace(/\/+$/, "")
+              const u2 = String(tpl2.probeUrl || b2.url || "").replace("{base}", base2)
+              return !!u2 && !credentialMayGoTo(m, tpl2, u2)
+            } catch (err) { return false }
+          })(),
           canAdjustBalance: canAdjustBuiltinBalance(m),
           matchIds: m.matchIds || [], settings: settings.models && settings.models[m.id] ? settings.models[m.id] : null,
           price: m.price || null,
@@ -2292,7 +2469,7 @@ export default {
       const summary = daySummary(led, todayKey())
       const nowSec = Math.floor(Date.now() / 1000)
       return {
-        ...visible, version: '0.3.13', isPeak: isPeakTime(nowSec),
+        ...visible, version: '0.3.15', isPeak: isPeakTime(nowSec),
         // 峰谷切换点与节假日清单：前端倒计时要与宿主同源（否则法定节假日会算错切换点）
         peakNextChangeAt: nextPeakChangeAt(nowSec),
         peakHolidays: HOLIDAY_VALLEY_LIST,
@@ -2311,9 +2488,26 @@ export default {
       balanceInFlight = fetchBalance()
         .then((payload) => {
           if (payload.ok) {
-            recordLedgerUsage(payload.totalBalance, payload.currency, payload.accountTag, Date.parse(payload.updatedAt))
-            balanceCache = { at: Date.now(), payload }
-            return publicBalance(payload)
+            // v759（issue #157 报告人踩到）：**"记不了账"不该吞掉已经拿到的余额**。
+            // 以前 recordLedgerUsage 抛错会被最外层 .catch 包成「余额服务异常: …」，
+            // 界面看起来像"接口没通"，其实余额已经拿到了（accountTag/币种不合法就会这样）。
+            // 但要与"**账本整个读不出来**"区分开：那种情况必须保持 fail-closed（见下面的 rethrow）——
+            // 一边是"余额拿到了、只是没记上账"，一边是"账本已经坏了、连今日已用都算不出来"，
+            // 后者若也回 ok:true，用户会以为一切正常，而账本其实不可用。
+            let ledgerError = ''
+            try {
+              recordLedgerUsage(payload.totalBalance, payload.currency, payload.accountTag, Date.parse(payload.updatedAt))
+            } catch (err) {
+              ledgerError = String((err && err.message) || err).slice(0, 160)
+            }
+            let visible
+            try {
+              visible = publicBalance(payload) // 读账本算今日已用/近 7 天
+            } catch (err) {
+              throw err // 账本读不出来（结构损坏等）→ 交给最外层 .catch，报 ok:false 并保留原记录
+            }
+            balanceCache = { at: Date.now(), payload } // 先缓存：之后即使记账失败，余额也继续显示
+            return ledgerError ? { ...visible, ledgerError } : visible
           }
           if (payload.transient && balanceCache) {
             return { ...publicBalance(balanceCache.payload), stale: true, error: payload.error }

package/package.json

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