桌面上一个透明、无边框、置顶的小鲸鱼挂件，常驻显示 DeepSeek API 余额 与 今日已用。移植自 DSH 版 DeepSeek-Balance-Whale-Widget，改为独立的 uTools 插件（Vue 3 + Vite 6）。
个人衍生版声明
本插件是个人衍生版，基于 MeteorNOX/DeepSeek-Balance-Whale-Widget（MIT License，Copyright (c) 2026 MeteorNOX）移植改造。
非官方版本，与 DeepSeek、uTools 官方均无关联，不代表官方立场，也不使用任何官方名义。没有官方支持与售后：上游作者不对本衍生版负责；本衍生版的问题请提到 本仓库 Issues，由本衍生版自行处理。
余额与用量
- 💰 余额：60 秒自动刷新（窗口隐藏暂停、可见即刷新），点鲸鱼手动刷新；变化时数字滚动动画，网络抖动自动沿用最近余额
- 📊 今日已用（双模式）：小鲸鱼记账（推荐，免令牌）按余额差值本地记账、跨天自动归档，保留期可配（默认 365 天，35–730 天）；实时·令牌填平台令牌后按峰谷定价精确换算，令牌失效自动回落记账
- 🛡️ 记账防误判：赠送额度到期、短时间异常跳变、更换 API Key 三种情况不会误记为「今日用量」，被拦下的变动单列为「未计入的余额变动」
- 🎯 手动校准今日已用：漏采或误判后可一键改成真实金额（只改当天累计、留校准记录，不动余额基准；令牌模式下无需校准）
- 📈 用量趋势与账本：柱状图可选 7 / 14 / 30 天（不超过保留期），下方给出本月累计 / 日均 / 最高单日 / 累计已用；支持导出 / 导入 CSV（UTF-8 BOM，Excel 直接打开）
- 🔎 账本明细与筛选：按日列出用量，标出「未计入的余额变动」（红）与「手动校准」（灰），点开可见每条的时间与原因；支持类型下拉（全部 / 只看未计入 / 只看校准）与关键词检索（日期或原因），命中做到条目级、自动展开
- 🥧 今日模型占比（仅实时·令牌模式）：按模型列出今日金额占比，模型名显示友好名称（悬浮可见原始 id）
- 🎫 额度进度：填「资源包 / 订阅」总量并选重置周期（每月 / 每日 / 不重置），显示「已用 / 总量 · 剩余（百分比）」进度条（≥90% 换暖色）；只做展示，不影响余额、记账与预警口径
- 🧩 多厂商余额 / 额度：除内置 DeepSeek 外最多再添加 9 个模型，可切换挂件主显示 —— 余额型显示原币种余额（附「~今日已用」估算），额度型显示剩余百分比与重置时刻。内置 11 个厂商模板，只收录能用 API key 直接查到余额或额度的厂商；低余额阈值按币种分开（人民币 10 / 美元 2）。其它模型不参与记账、不写账本
- 🧾 Codex 订阅窗口：直接读 Codex CLI 的本地会话日志（
~/.codex/sessions下的 rollout JSONL），取出 5 小时 / 周窗口的已用百分比与重置时刻 —— 不用配 Key、不发请求、不碰账号；按文件 size / mtime 增量缓存 - ⏰ 峰谷时段提醒：进入峰时 / 谷时（周一至周五 9–12、14–18 点为峰时，周末与法定节假日全天谷价）时气泡提示当前时段与价格区间（可单独关闭），并显示距下次切换的倒计时
- ⏱️ 计时 / 定时 / 倒计时：气泡内每秒刷新 —— 正计时、按分钟倒计时、指定时刻定时；支持暂停 / 继续 / 重置，模式与参数会被记住；到点响提示音、可选系统通知；开启「记住计时状态」后重载插件仍继续计时
- 🫧 计时气泡显示方式：「只显计时」开启时气泡只显示计时；「气泡常驻」控制计时气泡是否自动收起
⚠️ 低余额预警：余额低于可配阈值时数字变红，并弹提醒气泡 + 每天一次系统通知（阈值单位跟随账本币种，默认人民币 10 / 美元 2）- 📉 余额大幅波动通知：单次采样余额下降 ≥ 阈值就弹系统通知（不做每天一次去重），文案区分「正常消费」与「被防误判拦下的变动」；受免打扰约束
- 🎯 今日预算提醒：可设每日预算，当天超出时气泡提醒一次 + 第三行常驻「超预算 ¥x」，并每天一次系统通知（金额为 0 视为未设置）
- ⏳ 提醒停留时长可调：峰谷切换 / 今日预算 / 低余额 / 穿透说明几类提醒气泡可选 常驻 / 5 / 8 / 15 秒（默认 8 秒）
- 🌙 免打扰时段：可设一段（如
23:00–07:00，支持跨午夜）只弹气泡、不弹系统通知；时段内不占用当天提醒名额，出时段后补发一次 - 📮 邮件通知（SMTP）：所有提醒统一走一个出口，按配置分流到系统通知（默认开）与邮件通知（默认关）。邮件用 Node 内置
net/tls手写最小 SMTP 客户端（不引第三方依赖），支持 465 直连 TLS 与 25 / 587STARTTLS；服务器 / 端口 / 加密 / 账号 / 授权码加密存储，设置页提供「发送测试邮件 / 测试通知」两个按钮。邮件失败绝不影响主流程 - ⏱️ 计时增强：到点留言（≤60 字，到点气泡大字优先显示）、休息档（0–120 分钟，到点动作条多一个「休息 N 分钟」接下一轮）、到点动作条（气泡旁弹出独立操作条，与气泡同生共死）
窗口与交互
- 🐋 桌面常驻小窗：独立透明置顶窗口（置顶可关），不依附任何网页；透明区域点击穿透，不挡桌面操作
- 🫥 窗口透明度：20%–100%（设置页滑块实时预览 + 挂件菜单档位 100/80/60/40/20%），作用于整个窗口
- 🚫 鼠标穿透：开启后挂件完全不接收鼠标，点击 / 拖拽 / 菜单都穿透给下层应用；在鲸鱼上停留约 1 秒临时接管，移开约 0.7 秒自动交回。穿透中菜单按钮以半透明虚线常显作提示
- 🖱️ 拖拽 + 四边吸附：松手时挂件中心落进某条边的吸附区就贴边（四角可组合），否则自由摆放；吸附区宽度可调（1–45%，默认 25%）也可关闭；朝向自动水平镜像（锚在屏幕左半边朝右、右半边朝左）；滚轮可直接缩放
- 🔒 锁定位置：禁止拖拽与滚轮缩放，避免误操作；点击刷新照常可用
- 🧲 任务栏避让 + 贴边间距：可关的「自动避让任务栏」（实时识别任务栏隐藏 / 显示），另有上 / 右 / 下 / 左四边贴边间距（0–400px，0＝紧贴）
- 🧭 一键复位窗口位置：换显示器、改分辨率或把挂件拖出屏幕后，一键挪回右下角默认位置
- 🧸 按压 Q 弹 + 按压 / 松手双段音效（音效开关与音色可选）；💬 思考气泡（含 rua.webp 随机台词，长文案自动缩放字号）；拖动挂件甩出去会触发拖拽台词（「哇——轻点轻点！」，60 秒内不重复，计时 / 提醒时不打扰）
- 🐳 挂件形象可选 + 形象画廊：随包 1 张内置形象（默认
DSniang1），另有 1 张可选下载（「资源」Tab「形象」卡下段「可下载形象」里一键下载，见下文）；也可自定义（导入 png / jpg / jpeg / webp / gif / apng，≤5MB，图片复制到本地数据目录）。「资源」Tab 里是缩略图网格：单击选中、双击切换使用，可拖拽排序，卡头「整理」下拉可批量使用 / 置顶 / 移到底部 / 参与随机 / 删除，当前使用中的带角标；删掉当前那张自动顺延，全删光回退默认形象；最多 20 张。导入时可框选裁剪（含一键「自动裁掉透明边」，导出保留透明通道的 PNG），GIF / APNG 不裁剪、原样复制以保住动画；换形象后穿透轮廓按新图重算 - 🖼️ 自定义气泡图（「资源」Tab）：导入自己的图片（png / jpg / jpeg / webp / gif / apng，≤5MB），点小鲸鱼抽到「气泡图」那组台词时随机显示一张；一律原样复制、不裁剪不重编码（避免动图丢帧）；最多 8 张，没有「当前用哪张」，删光回退内置
rua.webp - 🎨 气泡主题：默认（蓝白）/ 深色 / 樱花三套配色，只改气泡与文字颜色（低余额的红色是状态色，不随主题变）
- 🌓 界面深浅色：设置页与挂件菜单面板可选「跟随 uTools」（默认，随 uTools 深浅主题实时切换）/ 浅色 / 深色；与「气泡主题」是两条线，互不影响
- 🎵 自定义音效：按压 / 释放两段可分别导入（mp3 / wav / ogg / m4a / flac，≤5MB，建议 1 秒左右），文件复制到本地数据目录；导入时可看波形拖选一段（最多 10 秒，可试听选区，导出 WAV）并支持试听；释放音可缺（松手静音），按压音缺失时回退「小黄鸭」
- 🔔 提醒音效：低余额 / 今日预算 / 峰谷切换 / 鼠标穿透四类提醒可各导一段提醒音。与音色不同，留空即静音，且不受「音色」下拉影响，只要音效开关为开、音量不为 0 就会响；每类还可单独调音量（默认跟随全局，拖动即独立生效，可「恢复跟随」）
- 🔁 音效组：六个槽位（音色两段 + 四类提醒音）每个只保留一段，重新导入即顶掉旧的；老数据读取时自动归一化
- 🗂️ 素材集中管理（「资源」Tab）：形象 / 气泡图 / 音效 / 共享素材的导入 / 下载 / 试听 / 删除都在这里，每项显示体积与导入时间，不随形象 / 音色的选择隐藏；卡头有「清除未使用（n）」（只删当前设置不会用到的素材）与「清除全部素材」（只删素材、不动其它设置）；另有折叠的素材包
- 🎁 共享素材包（按需下载）：「资源」Tab「形象」卡下段的可下载形象（随包内置 1 张 + 共享角色 36 张）与「音效」卡下段的可下载音效（45 段音效）不再随包分发，改挂 GitHub Release 按需下载 —— 需要时点一次，装到本地即可用，插件体积更小。下载走多源候选链逐个兜底：用户自填加速前缀 → 内置默认前缀（
ghfast.top）→ 真源直连 → raw 直连 → raw 走默认 / 自填前缀，任一源取到合法包即停。取回的包做整包 + 逐项双重 sha256 校验，不合格自动顺延下一源。共享音效落进独立的「素材池」，下载后默认不参与播放（不打扰），要到「音效」卡里给这段勾选「参加哪些槽位播放」，它才会在这些槽位的随机播放里被抽到（同一段落盘一份，不复制副本） - 🕐 小鲸鱼报时：点击鲸鱼时气泡首行报当前时间（鲸鱼娘语气，深夜 / 清晨换台词）
- 🔀 点按依次播放泡泡：开启后点气泡按顺序播放自定义泡泡队列（含并列泡按权重随机），关闭则每次随机弹一个（默认关闭）
- 🫧 按压气泡（自定义泡泡）可配置（「按压气泡」卡片）：点挂件弹出的泡泡是可增删的队列 —— 每个泡泡由若干「行」拼成，行内可放文本 / 余额 / 今日已用 / 峰谷 / 随机语句 / 超链接 / 图片等模块，模块可设字号、颜色（含渐变跑马灯）、粗体斜体；队列还支持并列泡（A/B 按权重随机抽一个）；卡内另含报时与动图降级的固定文案池。开关关掉则点挂件不弹泡泡
- ✏️ 提醒文案可编辑（「用量 → 提醒与通知」卡片）：四类提醒的气泡与系统通知共用一份文案，六条都能改，最多三行对应「标题 / 大字 / 说明」；支持
{balance}{threshold}{used}{budget}{over}{schedule}占位符，写错的会原样显示；清空某一条＝恢复内置默认
设置与集成
- 🔑 凭据加密存储（uTools
dbCryptoStorage）；「测试连接」分项验证 API Key 与平台 Token - 🎚️ 挂件菜单（悬停鲸鱼右上角按钮，或右键）：大小 / 音效 / 音量 / 透明度 / 模型 / 用量 / 峰谷文案 / 气泡 / 峰谷提醒 / 报时 / 计时 / 锁定 / dsh / 打开设置 / 隐藏挂件
- ⌨️ 全局快捷键：可为「显示/隐藏挂件」与「切换鼠标穿透」绑定 uTools 全局快捷键，触发时不弹搜索框；后者是穿透开启后的快捷逃生通道
- 🔀 进入方式可选：设置窗口 + 挂件（默认）/ 只显示挂件 / 只显示设置窗口
- 🔄 自动检查更新：每次呼出插件检查一次（12 小时内最多一次），发现新版本弹系统通知（默认关闭）
- 🚀 GitHub 加速（hosts 方案）：一键改写系统 hosts 让 GitHub 相关域名直连可用 IP，浏览器 / git / 下载全生效，不装代理、不改系统代理、不占常驻进程。写入前逐条做 DoH 实时解析 → HTTPS 探测 + 证书 SAN 校验（避免解析到被劫持的 IP），只写真正可用且证书确实匹配该域名的 IP，同一域名保留多个备用 IP 做运行期回退；写入需一次 UAC 确认，关闭即删块、不动你原有的 hosts 内容。另有「检测连接」「刷新 IP 表」「重新写入 hosts」、IP 表手动编辑、操作日志与来源追踪表，位于设置页「帮助」Tab
开发者集成（dsh，可选）
- 🧩 DeepSeek Harness 一键管理：挂件菜单「dsh」分组可直接启动 / 重启 / 结束 / 更新 dsh 并打开 Web UI（自动使用带 token 的地址）
- 🔍 外部进程也能管：按
127.0.0.1:<端口>（默认 3080，可在高级选项里改）探测运行中的 dsh，别的终端里启动的也能被结束 / 重启；端口被非 dsh 进程占用时拒绝操作，不会误杀 - 🛡️ 权限兜底：普通权限被系统拒绝时自动改用管理员权限重试一次（Windows 弹一次 UAC 确认，macOS / Linux 走提权）
- ⚙️ 可配置：dsh 优先复用你已全局安装的那份，没有才装到插件数据目录；启动直接跑
node，不经过npx。另有「启动时不自动打开浏览器」、npm 注册源、dsh 版本（默认「自动」）、Node.js 目录、Web UI 端口（默认 3080）、更新前重新下载、uTools 退出后是否保留 dsh - 💾 备份与恢复：一键导出「挂件设置 / 账本 / 窗口位置 / 计时」为 JSON；凭据默认不导出，勾选后需设密码并用 scrypt + AES-256-GCM 加密写入；导入时列出备份内容、勾选要恢复的项，同名覆盖
- 📜 运行日志：带时间戳、自动清理 ANSI 转义并识别中文 Windows 的 GBK 输出；启动后显示「<端口> 已就绪（用时 x.xs）」（默认 3080）与最近执行的命令
- uTools 桌面端（开发调试需在 uTools 内安装官方「uTools 开发者工具」）
- Node.js 18+：仅本地开发与打包需要；使用 dsh 功能时本机也需要 Node.js（插件会自动探测 PATH 与常见安装位置，也可在设置页手动指定目录）
- PowerShell / 任意终端（示例命令为 PowerShell 写法，其他 shell 等价）
在 uTools 中搜索「插件应用市场」，搜 小鲸鱼余额挂件 安装即可。
plugin.json 不含 development 字段，uTools 一律按正常模式加载插件目录 = 开发态与发布态同源（本地所见即用户所得）。
npm install
npm run dev # Vite watch 构建到 dist/（改 src/ 自动重建）在 uTools 中：打开 开发者工具 → 新建项目，插件入口目录选本项目的 dist/ → 用指令 余额挂件 / 小鲸鱼 呼出。
改了 src/ 后 npm run dev 会自动重建 dist/，在 uTools 里重新加载插件即可看到效果；preload/ 与悬浮窗页面改动同样需要重新加载插件（不走 Vite）。
npm run build # 产物输出到 dist/（prebuild 会先同步版本号 + 校验跨文件常量副本）
npm run lint # 可选：eslint . 静态检查（未定义 / 未使用变量、Vue 模板错误用法等）
npm run typecheck # 可选：vue-tsc --noEmit 类型检查
npm test # 可选：Node 内置 node --test 跑单测（覆盖业务模块 / dsh 一族 / 资源与素材包 / 构建闸门等）uTools 开发者工具中把插件入口目录指向 dist/。需要分发时可再「打包」为 .upx，拖入 uTools 主输入框即可安装。
不想自己敲命令时，把下面整块内容复制给任意 AI 助手（Trae / Cursor / Claude / ChatGPT 等），让它在你机器上装好并告诉你最后两步怎么点。前提是本机已有 uTools 桌面端（没装它会让你先去 u.tools 下载）：
帮我在这台电脑（Windows）上安装 uTools 插件「小鲸鱼余额挂件」，仓库：https://github.com/Berge520/Balance-Whale-Widget
1. 环境检查：确认已装 uTools 桌面端和 Node.js 18+（node -v 能看到版本号）。缺哪个先告诉我怎么装。
2. 取源码：优先 git clone 上面这个仓库；没有 git 就下载 zip 解压，放到一个固定目录（别放临时目录，以后升级要用）。
3. 在项目根目录依次执行 npm install、npm run build。构建失败就把完整报错原样贴给我，不要自己改源码绕过。
4. 构建产物在 dist/ 目录，记下它的绝对路径（开发热更入口是 public/，不要用那个）。
5. 剩下两步只能我手动做，请一步步引导我：
a. uTools → 插件应用市场 → 安装官方「uTools 开发者工具」；
b. 开发者工具里「新建项目」，插件入口目录选第 4 步的 dist/ 绝对路径，起个名字保存。
6. 最后告诉我怎么用：在 uTools 主输入框输入「余额挂件」或「小鲸鱼」呼出；首次使用要在设置页「数据」Tab 填 DeepSeek API Key（sk- 开头，去 platform.deepseek.com 创建）。
7. 以后升级：回源码目录 git pull（或重新下载）→ 再跑一次 npm run build → 在开发者工具里点「重新加载」，项目不用重建。
要求：只做上面这些，不要改仓库里的任何文件，不要跑 npm run dev（那是需要常驻窗口的开发模式）。
只想拿到成品、不折腾命令行的，直接走上面的「方式一：插件应用市场」。
呼出插件后，主窗口即设置页。设置页按主题分 7 个顶部 Tab：外观（挂件外观 · 按压气泡）、资源（我的素材：资源概览 · 气泡图 ｜ 下载素材：形象 · 音效）、用量（用量与账本 · 提醒与通知 · 模型与余额）、窗口（挂件窗口：显隐 · 位置 · 透明度 · 穿透）、数据（DeepSeek 凭据 · 清除数据 · 备份与恢复）、帮助（使用帮助 · 关于与更新 · GitHub 加速）、开发者（DeepSeek Harness（dsh） · dsh 环境诊断 · dsh 配置转储 · dsh 全量导出 · dsh 用量统计 · dsh 插件开关 · dsh 插件市场 ｜ Codex 会话统计），Tab 条吸顶、下方一行小字说明本组内容。
- DeepSeek API Key（必需）：platform.deepseek.com →「API keys」创建（
sk-开头）→ 粘贴到 API Key 框 →「保存凭据（加密存储）」。 - 平台 Token（可选，仅「实时·令牌」用量模式）：登录 platform.deepseek.com →
F12→ Network → 打开「用量」页 → 找usage/by_api_key/amount请求 → 复制其 Request Headers 里Authorization的值（形如Bearer eyJ...，前缀可带可不带）→ 粘贴到 平台 Token 框保存。
令牌是网页会话，重新登录平台后可能失效（届时会自动回落记账模式）。填好后点「测试连接」可分别验证两项凭据。
- 呼出：
余额挂件/小鲸鱼/小鲸鱼余额/DeepSeek余额/whale - 点鲸鱼：弹余额气泡 + 手动刷新 + 报时；点气泡按队列切下一条自定义泡泡（或随机一条），再点关闭（默认 5 秒自动收起）。开启「点按依次播放」后按队列顺序轮流播放
- 拖鲸鱼：松手时挂件中心落进某条边的吸附区就贴边，否则自由摆放；吸附区宽度与开关见设置页「挂件窗口」。拖出一段距离（约 100px）以上松手，小鲸鱼会吐一句「被拖拽」台词（一分钟内最多一句，计时或提醒气泡优先）
- 滚轮缩放：指针停在鲸鱼上滚动即可放大 / 缩小（1–20 档），停手后自动保存（锁定位置时禁用）
- 锁定位置：禁止拖拽与滚轮缩放；点击刷新气泡不受影响
- 吸附与翻转：选「比例吸附 / 关闭（自由摆放）」，「吸附区宽度」（1–45%，默认 25）决定离边多近才吸走；选「关闭」则停在哪就是哪（位置仍会被记住）。朝向不单独配：锚在屏幕左半边朝右、右半边朝左
- 贴边间距：上 / 右 / 下 / 左四个数值（0–400px，0＝紧贴该边），吸附 / 贴到该边时按它留出距离，改了立即生效；开着「自动避让任务栏」时任务栏那条边自动让位
- 复位窗口位置：把挂件挪回右下角默认位置，换显示器、改分辨率或拖出屏幕导致找不到时用它
- 调整透明度：设置页滑块（20%–100%，拖动实时预览）或挂件菜单「透明度」档位，两处共用同一设置
- 鼠标穿透：勾选后挂件完全不接收鼠标，把鼠标停在鲸鱼上约 1 秒即可临时接管（菜单按钮由虚线变实心），移开约 0.7 秒自动交回；也可为「切换鼠标穿透」绑定全局快捷键一键开关。注意：穿透开启后挂件菜单也点不到，绑快捷键是最稳的退出方式
- 自定义音效（「资源」Tab → 「音效」卡上段「我的音效」）：分别导入「按压音」与「释放音」（可缺），支持 mp3 / wav / ogg / m4a / flac、≤5MB；选完文件会弹出波形图，拖手柄选一段（最多 10 秒）试听确认后导出 WAV 落盘，中途取消不留半成品；已导入的可点「试听」。每个槽位只保留一段，重新导入即顶掉旧的
- 提醒音效（「资源」Tab → 「音效」卡上段「我的音效」）：四类提醒可各导一段，导入方式与按压音相同。留空即静音，播放只看音效开关与音量，不受「音色」下拉影响。「提醒与通知」Tab 里每类提醒音有独立音量滑块：默认跟随全局音量（「外观」页），单独拖动后即独立生效，点「恢复跟随」回到随全局变化
- 可下载音效（「资源」Tab → 「音效」卡下段）：45 段共享音效（34 MP3 + 11 OGG）不随包分发，改挂 GitHub Release 按需下载，落进独立「素材池」，不参与挂件随机播放；需要哪段点「下载这一段」即可，卡头「下载剩余 N 段」可一次补齐。每段自带一组「参加哪些槽位播放」的勾选：点行头「参加 N 个槽位」展开六个槽位 chip 勾选（按压 / 释放 + 四类提醒音），勾上即插进对应实播槽位随机播放（共用同一段落盘，不再另存副本）
- 自定义气泡图（「资源」Tab → 「导入的气泡图」）：导入图片（png / jpg / jpeg / webp / gif / apng，≤5MB），不裁剪、原样复制（动图保住动画），导入即参与随机；网格里只有缩略图与「删」，最多 8 张
- 挂件形象 / 气泡主题（「外观」Tab「挂件外观」卡片）：「形象」下拉可选内置形象或「自定义」，选「自定义」但还没导入图片时会提示前往「资源」Tab。自定义形象的导入 / 删除 / 切换都在「资源」Tab（缩略图网格）：导入后立即生效并自动切到这张，最多 20 张。网格交互：单击缩略图切换选中、双击切换使用，可拖拽排序；卡头「整理」下拉里「选中的 N 张」（单击选中的那批，含使用 / 置顶 / 移到底部 / 参与随机 / 删除）与「全部 N 张」（悬停展开，含全部参与随机 / 全部移到底部 / 恢复默认顺序）。「气泡主题」可选默认（蓝白）/ 深色 / 樱花，改完立即生效
- 素材集中管理（「资源」Tab）：四张卡 —— 「资源概览」（项数 / 占用体积 / 两个清除按钮 / 折叠的素材包）、「形象」（上段「我的形象」＝导入的 + 已下载的，下段「可下载形象」＝随包内置与共享角色两组网格，两段都可折叠）、「导入的气泡图」、「音效」（上段六个实播音效槽位 + 下段 45 段可下载共享音效，整卡可折叠）。与「外观」Tab 的分工：那边只管用哪个，这里管导了什么、占多大、要不要删；切回内置形象或音色后素材仍列在这里。两个清除按钮：「清除未使用」只删当前设置不会用到的素材（正在使用的一律保留，气泡图不参与统计）；「清除全部素材」把导入的素材全删并把形象 / 音色回退内置（整批删除不可撤销，需连点两次确认）。两者都只动素材，素材删除也只在「资源」页有入口
- 形象卡（「资源」Tab）：卡头四个按钮 —— 「随机一张」（从随机池挑一张并切换使用）、「导入图片…」、「整理」下拉（批量使用 / 置顶 / 移到底部 / 参与随机 / 删除）、「下载剩余 N 张」（把随包内置与共享角色里尚未下载的一次补齐）。下段「可下载形象」里的缩略图点一下就只下这一张，下完自动切到它；两组共用一个「形象下载源」输入框
- 素材包（「资源」Tab · 资源概览内的折叠区）：「导出素材包…」把导入的形象 / 气泡图 / 音效打包成一个
.whaleassets文件（单文件、不压缩）；换机器时「导入素材包…」选中后列出包内条目、勾选要写入的项即可。形象与气泡图是追加，音效是同槽位覆盖（会二次确认） - 按压气泡（自定义泡泡）（「外观」Tab「按压气泡」卡片）：点击挂件弹出的泡泡按「队列」播放，队列可增删泡泡、用 ↑↓ 调整顺序（第 1 个固定为「首次点击」内容）。每个泡泡由若干行组成，行内可放文本 / 余额 / 赠金 / 今日已用 / 峰谷 / 对话名 / 随机语句 / 超链接 / 图片 / 随机图等模块，模块可设字号、颜色（纯色或渐变跑马灯）、字体、粗体斜体、段后换行；还能建并列泡（A/B 两个候选项按权重随机抽一个）。卡内的固定文案池负责报时与动图降级取词
- 提醒文案（「用量」Tab「提醒与通知」卡片）：六条
textarea对应低余额 / 今日预算 / 进入峰时 / 进入谷时 / 穿透开启 / 穿透关闭，气泡与系统通知共用同一份文案；最多三行对应「标题 / 大字 / 说明」（超过三行并入说明行），系统通知取全文并合并换行。占位符写错的会原样保留便于发现；「保存」立即生效，「恢复默认」填回内置文案，清空某一条＝恢复内置默认 - 用量趋势图（「用量」Tab「用量与账本」卡片）：右上角切 7 / 14 / 30 天，下方「本月汇总」给出本月累计、日均（按已过天数摊）、最高单日与累计已用。柱顶金额只在 7 / 14 天档显示
- 历史保留：账本按天归档的保留期可配（35–730 天，默认 365）。改小后趋势图档位、CSV 区间上限、明细记录一并跟着缩；累计已用不参与裁剪
- 账本明细：点「展开账本明细」按日列出每日用量；右上角类型下拉 + 检索框（日期或原因）可叠加使用，命中是条目级的且自动展开；区间跟随上方档位，明细只在展开时读取一次
- 校准今日已用（仅记账模式）：填入真实金额点「校准」即可改当天累计，同时显示「今日另有 ¥x 余额变动未计入用量」及原因与时间
- 今日模型占比（仅「实时·令牌」模式）：按模型列出今日花费占比（按金额降序），标题行显示「共 ¥x · 更新于 HH:MM」；未填平台 Token 时显示「读取失败：未配置平台 Token」
- 额度：填「额度总量」（元）并选重置周期，下方出现进度条与「已用 / 总量 · 剩余（百分比）」。总量填 0 即不显示；额度只做展示
- 多厂商余额 / 额度（「用量」Tab「模型与余额」卡片）：点「添加模型」→ 选厂商模板 → 填名称与 API Key → 保存；列表里点行首单选即设为挂件主显示，行尾「设置 / 刷新 / 删除」。行内表单可改类型、币种，「高级设置」可改认证方式、字段路径、倍数与低余额提醒；「测试连接」立即拉一次，「刷新全部」批量拉取。只有内置 DeepSeek 时挂件菜单的「模型」分组整组隐藏
- 今日预算提醒（「提醒与通知」卡片）：勾选后填金额（元），当天用量超出时弹一次提醒气泡、第三行常驻「超预算 ¥x」，并每天一次系统通知；同一天内多次超出不重复通知
- 低余额预警（「提醒与通知」卡片）：勾选后填阈值（单位跟随账本币种，默认人民币 10 / 美元 2），余额低于阈值时数字变红并弹提醒气泡 + 每天一次系统通知；与今日预算同时命中时以低余额为准
- 余额大幅波动通知（「提醒与通知」卡片）：勾选后填下降阈值（元，默认 5），单次采样下降 ≥ 阈值就弹系统通知，不做每天一次去重（每次下降只会被采样到一次）
- 提醒停留时长 / 免打扰时段（「提醒与通知」卡片）：停留时长控制峰谷切换 / 今日预算 / 低余额 / 穿透说明几类气泡的收起时间（计时到点气泡单独控制）；免打扰可设起止时刻（可跨午夜），时段内三类自动通知都不弹系统通知、且不占用当天名额，出时段后补发一次
- 悬停鲸鱼 → 右上角菜单按钮：大小 / 音效开关 / 音色 / 音量 / 透明度 / 模型 / 用量模式 / 峰谷文案 / 气泡 / 峰谷提醒 / 报时 / 计时 / 锁定 / dsh / 打开设置 / 隐藏挂件（菜单按钮本身可在设置页隐藏，隐藏后右键鲸鱼仍可打开）
- 计时 / 定时 / 倒计时：菜单「计时」选模式 →「目标」填时长或
HH:MM（已过点顺延到明天）→ 点「开始」，气泡立即显示并每秒刷新；「暂停 / 继续 / 重置」齐全，点气泡收起不中断计时。菜单里「到点通知」「只显计时」「气泡常驻」「计时保存」分别控制系统通知、计时是否独占气泡、计时气泡是否自动收起与重载插件后是否继续计时 - dsh：菜单「dsh」分组有
启动/重启/结束/更新四个按钮 +打开页面，下面两行显示运行状态与最近执行的命令。启动后端口（默认 3080，可在高级选项里改）就绪前显示「启动中…」（该分组只在本机装了 dsh 或 dsh 正在运行时才出现） - dsh 设置页（「开发者」Tab）：「DeepSeek Harness（dsh）」卡片可配置 npm 注册源、dsh 版本（可先「查询可用版本」，结果会缓存；可选「进入开发者页自动刷新版本」，勾选后每次切到该 Tab 重查一次 npm）、Node.js 目录、
--no-open、Web UI 端口（默认 3080）、更新前重新下载、uTools 退出后是否保留 dsh；首次查询到版本列表时下拉默认指向实装版本（而不是「自动」），避免误装到更旧的稳定版；卡片里还能看到插件目录 / 全局安装 / 实际使用、npm latest（点「更新」会装到的版本）、状态 / 最近命令 / 页面地址，并支持复制地址 / 查看日志 / 复制日志。版本明细与日志收进「诊断信息」折叠，只读诊断与可写配置分开 - 「使用帮助」卡片：显示 / 隐藏挂件；使用说明与故障排查两组折叠；「复制指令名」「新增快捷键」用于绑定全局快捷键；进入设置页时自动检查挂件状态，仅在创建失败时展开错误详情
- 全局快捷键：按
Ctrl+,打开 uTools 设置 → 全局功能 → 新增 → 指令填「显示/隐藏挂件」（可点「复制指令名」快速复制）→ 按下组合键
「实时·令牌」模式按平台用量接口返回的 token 数 × 下表单价换算今日已用。金额单位 元 / 百万 token，写成 [谷价, 峰价]。
- 高峰：周一至周五（不含法定节假日）9:00–12:00、14:00–18:00（北京时间）
- 谷价：其余时间，恰为峰价的一半；周末全天按谷价；中国法定节假日全天按谷价（元旦 / 春节 / 清明 / 劳动 / 端午 / 中秋 / 国庆，表在 constants.js 的
CN_HOLIDAYS；次年的放假安排公布后在此追加） - 时段判定与定价实现在 constants.js（
PEAK_HOURS/BASE_PRICE/PRO_PRICE）与 pricing.js，官方调价时改这里；「小鲸鱼记账」模式不依赖本表
| 模型 | 缓存命中 | 缓存未命中 | 输出 |
|---|---|---|---|
deepseek-flash（当前模型名，含旧名 deepseek-v4-flash / deepseek-v4-flash-vision-exp） |
0.02 / 0.04 | 1 / 2 | 4 / 8 |
deepseek-v4-pro |
0.15 / 0.3 | 4.5 / 9.0 | 13.5 / 27.0 |
模型名按子串匹配上表（键的顺序即优先级）；
deepseek-chat/deepseek-reasoner以及匹配不到的模型名一律按 Flash 价计，未收录的模型名会在开发者日志里留一条记录，便于官方上新 / 改名后及时发现。对不上实际账单时（比如走了中转站或官方调价），可在设置页「用量与账本」勾选自定义单价：按百万 token 填谷价并选币种，峰价自动按官方规则（谷价 × 2）翻倍，选美元再填汇率（元/USD）；账本与挂件显示统一按人民币，不受填的币种影响。
只改了几个模型的价时，用下面的**「按模型覆盖」：点「＋ 添加模型」填模型名（按子串匹配，如
deepseek-v4-pro）与该模型的三个单价，最多 20 条。取价是三级顺序** —— 按模型覆盖 → 全局自定义单价 → 内置价目表，前者没命中就继续往下看（不是「填了就整表覆盖」）。模型名留空的条目保存时会被丢掉。
- 存了什么：凭据（API Key / 平台 Token / 各厂商模型各自的 API Key，一模型一份，均在 uTools
dbCryptoStorage加密存储）、挂件设置（含模型列表与主显示）、本地账本（用量 / 余额基准 / 校准与「未计入」记录）、计时状态、窗口位置与更新缓存，以及导入的音效 / 形象 / 气泡图文件（复制到插件数据目录userData/whale-sounds/、whale-skins/、whale-bubbles/）。全部只保存在本机，不会上传第三方；除余额接口（api.deepseek.com）、用量接口（platform.deepseek.com）、你添加的厂商模型自己的余额 / 额度接口与更新检查外无任何外部请求；邮件通知开启后会连接你自己配置的 SMTP 服务器。模型的余额 / 额度是运行时快照（whale:models），只是缓存，不进备份、清除「挂件设置」时一并清掉。 - 更新检查默认关闭（设置页「帮助」→「自动检查更新」手动开启，开启后每次呼出最多 12 小时查一次）：向
ghfast.top（GitHub 内容加速代理）拉一次本项目的package.json比版本号，请求里不含任何用户数据（无 body、无 Cookie、不带 Key），不开即完全不出网。 - GitHub 加速（设置页「帮助」→「GitHub 加速」，默认关闭）：开启后才出网 —— 向 2 个公共 DoH（DNS over HTTPS）端点查询待加速域名的 A 记录，并从社区 hosts 源表（GitHub520 及其镜像）拉取 IP 列表；请求只含要解析的域名，不含任何用户数据。改写的只有 hosts 文件里本插件自己的标记块（
whale-ghaccel start/end之间，上限 64 条），关闭即整块删除，你原有的 hosts 内容一字不动；写入需一次 UAC 提权确认（复用 dsh 的提权通道，临时脚本落在系统临时目录、不写仓库）。本功能只在本机改 hosts，不安装任何常驻进程、不改系统代理。 - 导出 / 导入账本：设置页「用量与账本」卡片右上角可在 CSV 与账本之间互转（日期 / 用量 / 币种三列，带 BOM，Excel 直接打开）；导入按日期合并（同日覆盖），只保留最近「历史保留」设置的天数（默认 365）。
- 卸载不删数据（步骤见 卸载）：在 uTools 里移除插件不会自动清除上述数据。设置页「数据与隐私」可勾选要清除的项目（凭据 / 挂件设置 / 账本用量记录 / 窗口位置与更新缓存），点「清除选中数据」并二次确认后只清除勾选项（确认时会列出将清除哪些项）；清除挂件设置或窗口位置后会按默认值重建挂件，只想重置挂件外观时不必重填凭据。导入的素材（音效 / 形象 / 气泡图）不在这里清除，请到「资源」页用「清除全部素材」（删掉文件并把音色回退「小黄鸭」、形象回退内置鲸鱼娘，气泡图删光后随即回退内置动图）。模型相关：清除「凭据」会一并清掉各模型的 API Key（模型列表还在，但需重新填密钥），清除「挂件设置」会连模型列表与余额快照一起清掉（挂件回到只显示 DeepSeek）。
- 备份与恢复（设置页「数据与隐私」→「备份与恢复」）：
- 导出会把「挂件设置 / 账本 / 窗口位置 / 计时」写成一个 JSON 文件（不含 dsh 开发者配置与 Node 路径）。
- 凭据默认不导出；勾选「包含凭据」后必须设密码（≥6 位），凭据（含各厂商模型的 API Key）用 scrypt 派生密钥 + AES-256-GCM 加密后才写入文件——文件里没有明文，改一位就解不开；密码不保存在任何地方，忘记只能放弃凭据（其余项仍可恢复）。旧备份（不含模型密钥）恢复时不会抹掉你已保存的模型密钥。
- 导入时先读取备份并列出「导出时间 / 插件版本 / 包含项」，勾选要恢复的项后写入（同名覆盖，账本同日覆盖并保留最近「历史保留」设置的天数）；恢复「挂件设置」或「窗口位置」会重建一次挂件，立即生效。
- 备份文件本身含你的设置与用量记录（凭据除外为加密块），请妥善保管。
- dsh 相关：只在本机执行（
node运行 dsh / 需要时用npm安装或更新它 /taskkill），不会把任何内容发到第三方服务器。dsh 的输出日志仅保存在内存（最多 160 行，供设置页查看），重新加载插件即清空；「打开页面」所用带 token 的地址取自 dsh 自身的输出，同样只存内存、不写入本地存储。dsh 自己的配置与数据由 dsh 管理（默认在用户目录~/.dsh），本插件不做改动。
在 uTools 里移除（卸载）本插件即可，没有额外的清理步骤。
- 移除插件不会删除数据：凭据、挂件设置、账本、窗口位置与更新缓存、导入的自定义音效与形象图片都留在本机，重新装回来照旧可用。
- 想连数据一起清掉，请在卸载前到设置页「数据与隐私」→「清除数据」按项勾选并确认（可只清凭据 / 只清账本，或全选）；卸载后插件界面就没了，只能重装一次再清。
- 换机器或重装后想还原设置，先用「数据与隐私」→「备份与恢复」导出备份，详见 数据与隐私。
- 挂件不出现：确认 uTools 开发者工具的入口目录指向本项目的
dist/（开发与打包同源，不要选public/）；点设置页「显示挂件」；点「挂件异常？查看错误详情」看宿主记录的失败原因并复制，或主窗右键 → 检查看[whale][widget]日志。 - 悬浮窗调试：焦点在挂件窗口上按
Ctrl+Shift+I。 - 开启鼠标穿透后挂件点不动：这是预期行为（连挂件菜单也穿透了）。用「切换鼠标穿透」全局快捷键关掉，或把鼠标停在鲸鱼上约 1 秒临时接管后，从挂件菜单「打开设置」回设置页关闭。建议先在设置页「挂件窗口 → 鼠标穿透」处点「新增快捷键」绑好，再开启穿透。
- 听不到自定义音效：确认「音效开关」为开、音量不为 0、音色选的是「自定义」且已导入「按压音」（未导入时会回退「小黄鸭」）；只导入按压音、没导入释放音时，松手那一下是静音（这是预期）。若导入的是 flac/m4a 而系统解不了码，换 mp3 / wav 再试。
- 提醒时没声音：四类提醒音（低余额 / 预算 / 峰谷 / 穿透）留空就是静音，与音色无关，得先去「资源」Tab 的「音效」卡上段「我的音效」里各导一段；导了还听不到再查「音效开关」与音量。
- 今日已用突然变大：v1.4.0 起「赠送额度整块到期 / 被平台收回」与「短时间异常跳变」不会再计入；若仍异常，说明下降幅度落在可信范围内被判成了消费，可用设置页「用量与账本」卡片的「校准今日已用」改成真实金额（会留校准记录），并把「今日另有 … 未计入用量」那行提示一起反馈回来。
- 透明度调了没反应 / 挂件整窗看不见：请确认版本为 v1.4.0 且已在 uTools 里重新加载插件（preload 与
floating.css都不热更）。旧实现用窗口级setOpacity，在 Windows 的分层透明窗上会导致整窗不显示，v1.4.0 已改为页面 CSS 透明度。 - 401 API Key 无效：确认填的是
sk-开头的 API Key（不是平台 Token）；用「测试连接」看服务器原文。 - 添加的模型一直显示
--：点该行「设置 → 测试连接」看服务器原文。常见原因：密钥没填（或填错厂商，注意 Moonshot 大陆站与国际站是两套账号、两套密钥）、字段路径与该厂商返回不一致（可用「高级设置」改路径）、自定义 HTTP 模板没填{base}、或接口需要特殊认证（智谱系要选「原始值」）。挂件里显示--说明该模型这条还没取到值，其它模型不受影响。 - 今日已用显示
--：记账模式需先有一次余额观测（60 秒内）；令牌模式需配好平台 Token，失败会回落记账。 - 峰谷提醒不出现：提醒依赖思考气泡，需同时开启「思考气泡」与「峰谷切换提醒」；且只在时段切换的瞬间提示一次，刚启动时不会补弹。
- 今日预算提醒没弹 / 只弹了一次：系统通知每天只发一次（同一天内继续超支不再重复，跨天自动恢复）；气泡提醒同样需要「思考气泡」开着，且计时进行中不打断计时；刚呼出插件时若已超预算不会补弹气泡，但第三行「超预算 ¥x」常驻提示照常显示。注意「每日预算」金额为 0 等于未设置，可在设置页「提醒与通知」卡片里改。
- 低余额预警没弹 / 只弹了一次：系统通知同样每天只发一次（跨天自动恢复）；气泡提醒需要「思考气泡」开着，且计时进行中不打断计时。与「今日预算提醒」同时命中时只弹低余额那条。若在免打扰时段内，通知会推迟到出时段后补发。
- 免打扰时段内还是弹了通知：免打扰只静默「今日预算」与「低余额」两类自动通知；计时到点是你在挂件菜单里主动设的一次性提醒，照常通知。另外请确认起止时刻不是同一个值（相同时视为未开启）。
- 提醒气泡一闪而过 / 一直不消失：停留时长在设置页「提醒与通知」卡片的「提醒停留时长」里改（常驻 / 5 / 8 / 15 秒）；选「常驻」需手动点气泡收起。该设置不影响计时到点气泡（由挂件菜单「到点通知」旁的档位控制）。
- 计时到点没声音 / 没通知：提示音走挂件音效，需「音效开关」为开且音量不为 0；系统通知由「计时到点通知」开关控制（关闭时只响提示音 + 气泡）。挂件窗口在后台被系统节流时，到点可能略有延迟，切回挂件即会立即补响。
- 重载插件后计时没了：确认「记住计时状态」为开；关闭后计时只在本次运行内有效。
- 没声音：音量不为 0；Electron 首次需先有一次交互。
- 改了 preload 不生效：preload 不热更，需在 uTools 开发者工具里重新加载插件。
- dsh 提示「未找到 Node.js」：设置页「DeepSeek Harness」→「选择目录」指定 Node.js 安装目录（如
D:\nodejs），或点「改为自动探测」；卡片里会显示实际生效的目录与版本。 - dsh 提示端口被占用（默认 3080）：说明已有 dsh 在运行（可能是在别的终端里启动的）。点「结束」或「重启」即可接管；若占用端口的是非 dsh 程序，插件会拒绝操作并提示，避免误杀。若该端口被系统预留（Windows 动态端口段常预留 3080），可在卡片「高级选项」里把 Web UI 端口改成别的值（如 4080）再启动。
- 点「结束」提示「权限不足 / 拒绝访问」：那个 dsh 是管理员权限启动的。插件会自动改用管理员权限重试（弹一次 UAC 确认框）；也可以管理员身份运行 uTools，或直接在 dsh 自己的终端里按
Ctrl+C。 - 打开页面提示 authentication required：dsh 的 Web UI 首次访问需要带
?token=的地址。由插件启动的 dsh 会自动捕获该地址（设置页「页面地址」可查看 / 复制）；外部终端启动的 dsh 请使用它自己打印的地址，或在插件里「重启」一次以接管。 - dsh 首次启动很慢 / 「启动中…」很久：首次会自动下载安装（约 500 多个包，之后启动就快了）；国内建议把「npm 注册源」改成淘宝镜像。启动完成后状态会变成「运行中」，并在日志里记录「<端口> 已就绪（用时 x.xs）」（默认 3080）。
- 结束 dsh 后 dsh 又起来了：说明它有守护进程 / 你是在某个会自动重启它的工具里启动的，请在它自己的终端里
Ctrl+C关闭。
public/ # 开发入口目录（打包时整体复制进 dist/）
├─ plugin.json # uTools 插件清单（版本号由构建自动同步）
├─ floating.html/.css # 悬浮窗页面与样式
├─ floating-page.js # 悬浮窗页面逻辑（纯浏览器 IIFE，不用 require）
├─ preload/
│ ├─ services.js # 主窗宿主 preload 入口
│ ├─ floating.js # 悬浮窗 preload（contextBridge 暴露 window.whale）
│ └─ lib/ # 宿主能力：api / widget / ipc / store / pricing / codex / dsh 一族 / dsh-usage / notify / hosts / skins / skin-packs / bubbles / sounds / assets / assets-packs / backup / settings / download-progress / log / constants
├─ whale/ # 基础挂件素材（默认形象 / 内置音效 / 气泡图）
├─ whale-pack/ # 内置形象包（thumbs/ + manifest 随包分发，大图按需下载）
└─ shared/ # 共享角色 / 共享音效原文件（入库但不进插件包，按需单张下载）
resources/ # 共享素材缩略图（thumbs/ 随包分发；素材源 skins-src/ 为发布者本地保留、不入库亦无此目录）
src/ # 设置页（Vue 3 单文件组件）
├─ App.vue # 设置页主界面与逻辑
├─ views/ # 按 Tab 拆分的视图组件（AccelView.vue = GitHub 加速）
├─ components/ # 可复用控件（裁剪器 / 试听 / 下载框 / 首启引导 / 气泡编辑等，以目录实际内容为准）
└─ types/services.d.ts # 宿主注入 API 的类型声明
test/ # 单元测试（node --test，npm test）
scripts/ # 构建与发布脚本（sync-version / check-shared / check-dead-settings / gen-search-index / check-orphan-css = prebuild 五道闸门；另有 release / verify-release-zip / build-skin-pack.py / export-shared-assets，以目录实际内容为准）
eslint.config.js # ESLint 扁平配置（npm run lint）
.github/workflows/ci.yml # 持续集成（push / PR 依次跑 lint + typecheck + test + build）
.github/workflows/release.yml # 发版（打 v* tag 时校验版本 → 跑同一套检查 → 构建打包 zip → 建 Release）
docs/whale-widget-spec.md # 开发维护规格（架构 / IPC / 存储 / 视觉参数）
npm install
npm run dev # Vite watch 构建到 dist/（改 src/ 自动重建，入口仍指向 dist/）
npm run lint # eslint . 静态检查
npm run typecheck # vue-tsc --noEmit 类型检查
npm test # node --test 单测（test/*.test.mjs）
npm run build # 构建到 dist/（prebuild 自动同步版本号 + 校验跨文件常量副本）
npm run release # 一键发版（见下）-
一键发版（
npm run release，脚本在scripts/release.mjs）：npm run release # 发 package.json 里当前 version npm run release -- 1.7.0 # 先把版本号写成 1.7.0，再发 npm run release -- 1.7.0 --dry-run # 只跑前置检查与四关，不提交不推送
脚本按顺序做：前置检查（版本递增 / README 有该版本章节 / tag 未占用 /
gh已登录 / 在main上）→ 写版本号并同步 → 跑四关 → 用 README「### <版本>」章节当正文建 release commit → pushmain并等 CI 绿 → 打附注 tag 并推送 → 等 Release 工作流绿 → 核对 Release 与 zip 资产（scripts/verify-release-zip.mjs解压核对plugin.json顶层、版本号、preload 关键文件在位）。任一步失败即中止。 因为正文取自 README，发版前先把版本记录写好（### <版本>章节），否则前置检查会拦下。 -
改动
preload/或floating-*：不热更，需在 uTools 开发者工具里重新加载插件才能看到效果。 -
preload 文件为 CommonJS，不可压缩混淆，发布时保持原样。
-
npm run lint的配置在eslint.config.js：只查真问题（未定义 / 未使用变量、重复键、不可达代码、Vue 模板里的错误用法），不含格式规则（缩进 / 引号交给编辑器）；按四套运行环境分块声明全局变量（设置页 / preload / 悬浮窗页面 / 构建脚本）。 -
同一份常量在宿主 / 设置页 / 浮动页 / 样式表里各有一份副本（preload 不参与打包、浮动页没有
require、CSS 变量宿主读不到），scripts/check-shared.mjs会在构建前比对，不一致直接构建失败；新增这类副本时记得把这一对加进它的CHECKS。 -
持续集成（
.github/workflows/ci.yml）：push 到main、任何 PR、手动触发时，依次跑npm run lint→npm run typecheck→npm test→npm run build（Node 24 +npm ci）。这四关就是上面这些本地命令本身，CI 不额外引入工具链，所以「本地能过」和「CI 能过」是同一件事；构建产物dist/不上传、不发布。 -
发版（
.github/workflows/release.yml）：只改package.json的version→ 提交 → 打同名 tag（如v1.5.1）并推送。工作流会先校验 tag 与package.json版本一致（不一致直接失败），再跑与 CI 同一套检查、构建，把dist/打包成balance-whale-widget-<tag>.zip并建 Release（变更说明由 GitHub 按 commit / PR 自动生成）。uTools 市场的.upx仍需人工在开发者工具里打包上传。
修复 · 打开挂件先闪一下内置形象
- 挂件不再「先闪一下内置形象」：窗口改为配置落地后再显示。以前窗口一创建就把首帧亮出来，那一刻用户设置的形象还没送到，页面画的是随包内置的那张，随后才被换成设置的形象——表现就是「打开挂件先闪一下」。现在改成窗口先隐形创建，页面把配置（含自定义形象本体）落地后再请求显示；万一页面因资产缺失 / 报错始终没就绪，有个几秒的兜底显示，不会出现「挂件永远看不见」。
修复 · 自动隐藏任务栏的避让不归位
- 挂件的任务栏避让不再「赖着不走」：之前用完自动隐藏的任务栏后，挂件有时要愣在原位好几秒才落回，甚至出现「任务栏都收回了、挂件还留在上面」。现在把「让位」和「落回」拆成两个独立节奏——光标一压到任务栏就立刻让位，光标离开后短暂等一下（等任务栏收回动画走完）再落回，不再各说各话。设置页「任务栏」一栏的状态显示也顺带说明：自动隐藏时它只能靠「光标是否贴过边」推断，状态会比实际稍晚翻转。
修复 · 拖动大小滑块闪屏
- 拖动大小滑块不再闪烁：宿主侧给实时缩放加了一层帧合并，把一帧内多余的重绘省掉，拖得快时不再抖/闪。同时修掉松手瞬间可能被「上一帧的旧位置」拉回去、以及刚从拖拽转到缩放时窗口停在旧尺寸的毛病。
修复 · 邮件提醒发不出去
- 邮件 SMTP 更稳：修了几处会让邮件静默发失败或报错看不懂的问题——多行服务器响应解析、STARTTLS 升级后漏挂超时、超时后残留响应串到下一次命令；另外端口和加密方式填错时（如 587 配「SSL/TLS 直连」）现在会给一句明确提示，而不是丢一个 TLS 层的原始报错。
修复 · 今日模型占比误报读取失败
- 「今日模型占比」不再误报失败：当天确实没用过时，之前会被当成「读取失败」显示。现在区分了「连通但今天没消耗」与「真的取不到」，前者安静显示「今日暂无用量记录」。用量接口的各种失败原因（没填 Token / Token 失效 / 服务端错误 / 网络不通 / 返回不是合法 JSON）也都换成了中文说明，并区分「可重试」与「需改配置」。
修复 · 副屏任务栏避让判错屏幕
- 挂件在副屏也能贴到屏幕最下沿：以前任务栏避让总是拿「主屏任务栏」的数据去套所有屏幕，挂件拖到副屏最下沿时会被当成「不能放」而卡住 / 回弹。现在改为按挂件当前所在的那块屏判断，副屏任务栏（无论常显还是自动隐藏）都能正确让位。副屏任务栏若设成自动隐藏，收起时不再让位——这点与主屏不同，因为注册表里没有副屏任务栏的记录，实在拿不到它的方向与厚度，按「常显内缩」处理更稳。
改进
- 挂件右上角菜单默认全收起：以前「模型与余额」组默认展开，会把别的组挤出视野；现在全部默认收起，一屏能看全所有分组，点开哪组看哪组。
- 大小倍率统一到整数档：挂件大小改用统一的 15 档刻度，不再出现 1.3 / 1.6 这类非整档值；老配置里存过的非整档值会在下次读写时自动归到最近一档，滑块和数字框从此对得上。
- dsh 开发者区各卡片的「说明」默认收起：用量、诊断、隔离、市场四张卡的说明文字默认折叠起来，卡片首屏少占几行、更清爽。
- 设置页长卡片统一默认收起：关于与更新、提醒与通知、备份与恢复、数据与隐私四张正文很长的卡片改为默认收起，收起时标题栏留一行摘要（如「已开启 2/4 类自动提醒」「已勾选 3/6 项」），扫一眼就知道状态；「资源」页的资源概览与气泡图两张卡同样默认收起，并补上一行汇总（张数 / 体积）。一屏能看全更多卡片，需要改哪张点开哪张。
改进 · 界面细节
- 清理了一批卡片抽出后遗留的重复样式（裁剪器 / 音频剪辑器的提示文字样式统一由全局样式表提供）。
注：本版引入的台词库（富文本编辑器 / 条件行 / 组级音效 / 台词组导入导出）已在 v1.12.x 整体移除，改由「按压气泡（自定义泡泡）」承载。此节保留为历史记录，特性现不存在。
新功能 · 台词库富文本编辑器（行 × 段）
- 台词从「一行一条」升级为「行 × 段」自由拼装：自定义台词组可一键升级为富文本组——每行由多个「段」拼成（文字 / 气泡图 / 链接 / 实时数据四类），每段独立设置 11 档字号、纯色或渐变、粗体斜体、段后换行；升级按原字号自动换算、零损失，但不可逆（界面已注明）。嫌麻烦可以不升级，老的「一行一条」照常用。
- 段用「chips」管理：每段显示为一枚彩色小片（文字 / 图 / 链 / 数据四色），点选编辑、× 删除，桌面端可直接拖拽调顺序，触屏用段编辑区的左右按钮兜底。余额 / 今日已用 / 当前时段 / 距高峰四个占位符做成了可点就插入的小按钮，不用再手打花括号。
- 气泡图与实时数据也能混进台词：文字行里可以插一段气泡图（指定第几张或随机）、一个可点击的链接按钮、或直接引用某个模型的实时余额——设置页预览里也能看到它们的真实排版效果。
- 旧配置自动迁移：保存过的台词、气泡图组升级后原样保留，无需手动处理。
新功能 · 条件行
- 每行台词可以设「出现条件」：仅峰时 / 仅谷时 / 余额低于某值 / 主显模型为某模型 / 星期几，五类可组合。条件不满足时该行整行不出现（不参与抽选），比如「余额不足 ¥10 时的哭穷台词」只在真低余额时冒出来；组内所有行都不满足时这次自动换组重抽（至多 3 次），仍不行就安静收起，不会弹空气泡。
- 全不选 / 全选自动退回无条件：星期几全勾或全不勾等于没有条件，界面会自动清掉并提示，避免写出「恒真恒假」的摆设条件。
新功能 · 组级音效
- 每组台词可挂一段专属配音：在「资源」页导入过共享音效库（素材包）后，台词组头部多一枚音效下拉，选中某段后抽到这组时先播这段音。音效段被删除或未下载共享库时静音不报错，配置里留着的名字不影响其它功能。
新功能 · 台词组导入导出
- 素材包现在能带走台词组：「资源」页的素材包导出会包含全部自定义台词组，换机器导入后追加到现有组尾部（超过 12 组上限自动截断）。老素材包没有台词组也能正常导入，不受影响。
改进
- 成品组模板 3 套扩到 6 套：新增「低余额提醒」（带组级音效与余额条件行）、「工作时段问候」（峰谷条件行）、「周末快乐」（星期几条件行）三套，顺带演示条件行与组级音效的用法，从模板新建即可照着改。
- 导入的台词组做完整清洗：包里的组在导入落库时过一遍与手动保存相同的校验（超限裁剪、空行丢弃、条件规范形），坏数据进不来。
注：本节的「台词库真预览」随台词库在 v1.12.x 一并移除，现由「按压气泡」的试播取代。此节保留为历史记录。
新功能 · 提醒音独立音量
- 四类提醒音可各调各的音量：「提醒与通知」Tab 新增四个滑块（低余额 / 预算 / 峰谷 / 穿透），默认跟随全局音量（「外观」页的「音量」滑块）；单独拖动某一类后即独立生效（不再随全局变化），点旁边的「恢复跟随」回到随全局音量变化。想要「提醒音比音色小声一点」或「峰谷提醒单独静音」这类效果，现在不用再整体调音量了。
新功能 · 台词库真预览
- 每组台词可以「预览」了：「文案」Tab 的台词库每组行头多一枚「预览」按钮，点开后用与挂件完全相同的渲染器真渲染一组气泡——所见即挂件所得；文本组可逐条翻看，检查每条台词的排版效果，不用再保存后碰运气。
- 预览位置自己选：预览区上方可切「设置页 / 挂件气泡」两个档位。「挂件气泡」会把整组台词发到真挂件上试播：点挂件气泡按顺序逐条翻看，末条再点收起；占位符（余额 / 时段等）按本机实时数据替换，比设置页里的示例值更接近真实效果。
修复 · 智谱 GLM Coding 余额取不到
- 修复智谱 Coding 模型（国内 / 国际 z.ai）额度一直显示
--的问题：智谱额度接口返回的是无序列表（pro 账号排最前的往往是时段条目而非用量条目），旧版按固定位置取数必然取空。现改为按条目类型定位，5 小时窗口与周窗口两个百分比及重置时间都能正常显示；新注册的 credit 制账号也兼容。若此前手改过该模型的字段路径，可到「高级设置」里恢复模板默认。
改进
- 气泡不再赖着不走：挂件气泡显示期间若息屏 / 休眠 / 长时间切走，回来后到时的气泡会立即自动收起（此前定时器被系统暂停，气泡会一直挂着）。
- 中文输入法不再误触发：用输入法给 dsh 快照起中文名时，按回车确认候选词不再被误认成「保存」、按 Esc 取消组字不再误关菜单；设置页搜索框同样受保护。
- 接口报错看得懂了：模型余额 / 额度接口返回 HTTP 200 但业务层报错时（如未订阅 Coding Plan、令牌无效），直接显示服务器给出的原因，不再笼统报「字段路径取不到数值」。
开发
- 新增「死键体检」构建门禁：每次构建自动扫描全部设置键，防止出现「设置页能改、运行时没人读」的配置项；门禁自身配有自检测试（临时样本仓库逐项验证「该红的写法必红」），门禁被改坏时会立刻暴露而不是静默放行。
新功能 · 拖拽台词
- 拖着玩会说话了：把挂件拖出一段明显距离（约十分之一屏宽）再松手，气泡会随机冒一句「哇——轻点轻点！」「起飞咯——」等被拖拽台词；日常小距离挪位置不触发。每分钟最多弹一句，不打扰余额提醒与计时气泡。
- 台词库新增一条默认闲聊台词：「终有一天，终有一天……」（保存过台词配置的用户需点「恢复默认」才会看到）。
新功能 · 界面深浅色
- 设置页与挂件菜单面板跟随 uTools 深浅主题：「外观」Tab 新增「界面深浅色」，默认「跟随 uTools」，uTools 切深色模式时挂件界面实时跟着变深；也可手动固定浅色 / 深色。与「气泡主题」互相独立，之前「打开插件界面隔一会才变色」的首帧闪烁也一并消除。
改进 · 设置页台词库
- 卡头内容预览：每组卡片头部直接显示该组内容概要（台词条数与首句 / 气泡图说明），不用逐个展开就能找到目标组。
- 「恢复默认」确认文案：明确提示恢复的是内置默认（含版本新增台词），自定义内容会被丢弃。
- 占位符指引：台词占位符说明末尾新增一句——想要「余额/时段卡」的自定义文字版，新建「自定义台词」组写占位符即可。
- 设置页搜索支持多词：搜索框输入「界面 深色」这类带空格的多词也能命中（各词都命中才算），标题命中的卡片排在前面。
- 开发者 Tab 版本选择更省心：新增「进入开发者页自动刷新版本」开关（默认关，勾选后每次切到开发者 Tab 自动重查 npm 版本）；首次查到版本列表时下拉默认指向当前实装版本，避免被「自动」指到更旧的稳定版。
修复
- 余额气泡不再顶掉正在看的台词：自动刷新发现余额变动时，若用户正在查看点击触发的随机台词（或拖拽台词），余额变动气泡改为让位不再弹出，数字滚动照常；想看余额点一下挂件即可。
- dsh 插件市场误报「不兼容」：形如
^0.1.0 || ^0.2.0-rc的多段版本范围此前被整条按第一段判断，宿主装着0.2.0-rc.2也被拦成「与插件不兼容」；现按标准 semver 语义逐段判断，落在任一段内即放行。
新功能 · 形象画廊批量整理
- 选中与批量操作：画廊网格改为单击缩略图切换选中、双击切换使用；卡头新增「整理」下拉，分「选中的 N 张」（使用 / 置顶 / 移到底部 / 参与随机 / 删除）与「全部 N 张」（悬停展开：全部参与随机 / 全部移到底部 / 恢复默认顺序）两段。选中态不随画廊刷新丢失。
- 拖拽排序：缩略图支持直接拖拽调整顺序，落位即时生效（乐观更新，失败才回读）。
- 内置形象是否参与随机：新增开关（存储键
randomIncludeBuiltin，默认开），可把内置形象排除出随机池；随机池为空时有明确提示与「整理 → 全部参与随机」的找回入口。
修复 · 画廊缩略图「无预览」（bug 10）
- 根因三层：① 共享角色下载链路把缩略图写死为
null；②readThumb只认.thumb.png、认不出 webp 缩略图；③ 回落读原图作缩略图的体积预算（8MB）把大图挡在外面。现三处一并修好：下载尊重opts.thumb、读写支持 png / webp 双格式、老数据懒补缩略图（进设置页自动补齐缺失的内置形象缩略图）。
改进
- 音效槽位语义收敛：六个实播槽位由「可叠多段、随机播一条」改回一段一槽位（重新导入即顶替）；共享音效库仍可容多段。老数据读取时自动归一化。
- 删除共享音效的连带清理：删除素材池里某段时，按
from标记一并清掉各槽位上由它复制而来的副本，不再出现「删了池里那段、槽位照旧在响」。（该机制已于 v1.13.x 随音效卡合并退役：改为roles关联同一份落盘、删段即连勾选一起消失。） - dsh 市场预发布准入：
^/~范围的上界补-0排他语义，并统一应用预发布准入闸门（此前可能误纳预发布版）。 - 设置页样式令牌收敛：设计令牌集中到
main.css的:root，去掉App.vue/AccelView.vue/ 三个弹层的重复副本，并修正AccelView.vue里两处未定义的var(--fg2)/var(--bd)。
测试
- 新增回归测试：
test/skins.test.mjs（缩略图双格式读回 / 懒补 / 搬运 / 批量删 / 批量随机等）、test/assets-packs.test.mjs（opts.thumb落盘、共享音效按file取用与删除）、test/skin-packs.test.mjs（thumbOff/thumbLen切片）、test/dsh-market.test.mjs（预发布准入闸门）、test/build-gates.test.mjs。
新功能 · 共享角色与共享音效包
- 可下载素材包：内置形象只保留
DSniang02一项，其余角色与音效改由「共享角色包」与「共享音效包」提供，用户按需从 Release 下载。共享角色包提供 36 个角色、共享音效包提供 45 首音效，两者共用同一套候选链、容器解析与双重校验（SHA256 + 清单核对）。 .whaleassets容器格式：[11 字节魔数][4 字节清单长度 uint32LE][JSON 清单][各文件字节平铺]，一个文件装完整个素材包，避免散件下载。
新功能 · dsh 留言（dsh-notes）
- dsh 留言：新增留言功能，含长度上限（
TIMER_NOTE_MAX）与新鲜度判定。
修复 · 开发链路
- 开发态与发布态路径不一致：
plugin.json原先带development.main = http://localhost:5173，而vite.config.js的publicDir: false使 dev server 不服务public/下的素材，请求./whale/DSniang1.webp落到 SPA fallback、返回 333 字节index.html，表现为设置页内置形象缩略图碎图。现删除development字段，uTools 一律按正常模式加载插件目录 = 开发与打包同源（本地所见即用户所得）。npm run dev相应改为vite build --watch，持续构建到dist/。
改进
- 素材入库口径：素材源（
assets-src/、resources/skins-src/）与包产物大件（resources/*.whaleassets、resources/manifest.json）不入库，仅resources/thumbs/（36 张缩略图，约 404KB）入库——它随插件包分发，供设置页下载前预览。
测试
- 新增
test/assets-packs.test.mjs/test/skin-packs.test.mjs/test/skins.test.mjs：覆盖共享包候选链、容器解析、双重校验与缩略图落盘。 - 新增
test/dsh-notes.test.mjs/test/dsh-notes-config.test.mjs/test/dsh-notes-freshness.test.mjs：覆盖留言配置、长度上限与新鲜度判定。 - 新增
test/ipc-parity.test.mjs（自 1.7.3 起沿用）：校验宿主 IPC 通道与设置页类型声明一一对应。
新功能 · 开发者 Tab（dsh）
- 更新说明（区间聚合）：版本说明区不再调上游的
releases/latest只取最新一篇 —— 那篇只讲「相对它上一版改了什么」，而用户装的可能是几个月前的版本、中间隔着好几个版本，跟他没关系。现按「实装版本 → 目标版本」聚合整个区间的 release notes，节标题沿用官方原文（「✨ 新增 / 🐛 修复 /⚠️ 调整」等，不自己再判风险）。同一篇 release 是中文块 + 英文块两份等价内容，只取中文块，条目数不会翻倍。实装即最新时区间为空，一个请求都不发；正文按版本号持久缓存（whale:dshNotes，最多 40 版），第二次看同一区间 0 请求出结果。说明是附注，取不到时整行不出现、不标红版本行，也不影响更新按钮。 - 说明按需拉取：「查询可用版本」只查版本号，不再顺带打一趟说明（实测白等 2.9s、多数时候用户根本不展开）。改为点开「版本说明」时才发起。
修复 · 开发者 Tab（dsh）
- 切换版本后说明一直卡在「正在获取说明…」：
loadNotes是对外 IPC 入口，却没有像其余对外操作那样先syncConfig()。用户改完「dsh 版本」下拉就直接展开说明，中间没有任何操作会顺带同步配置，于是宿主拿着上一次操作时的旧版本去算区间，与界面按当前cfg.dshVersion算的对不上，新鲜度判定恒为过期、界面永远停在「正在获取」。现入口处先同步配置，两边同源。 - 说明请求被在飞的上一趟吞掉：上一趟请求还在飞时又发起一次，早先直接
return丢弃 —— 在飞那趟是按上一组版本发的，落地后仍是旧值被判过期，而此刻目标已稳定、不会再触发新请求，于是没有任何一方会再取数。现记下notesDirty标记，待在飞那趟 settle 后按当前版本补一次。 - 「有新版本」提示的判据错位：原先拿
targetVersion()（会优先返回用户手选的固定版本）去比，导致「实装 alpha.2、下拉也选 alpha.2 → 判定没有新版」，而 npm latest 明明是 rc.2。用户选哪个版本只决定「更新时装成哪一版」，不该反过来改写「npm 上有没有新版」这个事实。现只比 npm latest。 - 换 API Key 后余额差额被误记成用量：模型运行时状态新增密钥指纹（
keyId），换 Key 时只重置记账基准、不把两边余额差记成用量（同 DeepSeek 内置 Key 的既有口径，见whale:models的keyId字段）。
改进
- dsh 提权跨平台：Windows 走 UAC、macOS / Linux 走
pkexec或sudo，超时结束 pnpm 时 POSIX 用负 pid 杀整个进程组（Windows 仍用taskkill /T）。非 Windows 平台的提示文案里不再是「请在 UAC 弹窗点『是』」。 - 市场镜像 tarball 非 gzip 的报错可定位：宿主 undici 会污染全局
fetch（上游 issue #742），拿到被剥了 content-encoding 的体时，报错明确标注「疑似宿主 undici 污染」并带上 Node 版本，便于一眼区分「是宿主不是镜像坏了」。
测试
- 新增
test/dsh-notes.test.mjs/test/dsh-notes-config.test.mjs/test/dsh-notes-freshness.test.mjs：覆盖说明区间聚合（中英块只取中文、区间上下界、空区间零请求）、正文持久缓存复用与版本上限淘汰、以及「换所选版本 / 换实装版本 / 版本列表重查」三种情形下的新鲜度判定。 - 新增
test/models-usage.test.mjs：覆盖换 Key 时keyId指纹变更只重置基准、不把余额差计入用量。 - 新增
test/ipc-parity.test.mjs：校验宿主settings.js暴露的 IPC 通道与设置页src/types/services.d.ts的声明一一对应，防止「宿主加了通道、类型声明漏了」这类静默不一致。
新功能 · 开发者 Tab（dsh）
- Web UI 端口可配置：dsh 的监听端口从写死的 3080 改为可配置项（「高级选项」里填，默认仍 3080）。此前端口在代码里写死，遇到系统动态端口段预占 3080 时无从避让；现在可改成任意端口再启动。改动覆盖配置读取 / dsh 启动参数 / 端口探测 / 挂件菜单与设置页状态文案 / 只读诊断的端口项，一处改、全链路跟着走。
- 快照备注：dsh 市场安装 / 卸载 / 禁用 / 更新自动建的快照，此前只记动作类别，短时间能堆十几份、光看列表分不出「这份是为哪个包建的」。现新增备注字段记下具体对象（如「安装 dshmarket@1.65.1」），只写进快照清单、不顶替用户自己的命名；老快照缺这个字段时按空串读回，不会因升级报错。
修复
- 运行中改端口误报「启动中…」：dsh 正在某个端口上运行时（如 3080），去设置里把端口改成别的值（如 3081）——还没点「启动」——状态就直接变成「启动中…（3081 未就绪，已等待 N 秒）」。根因是把「配置端口」与「运行端口」混成一个状态：改配置时无条件把
ready置回未就绪，而旧进程还活着，于是出现了「进程在跑 + 未就绪」这个本不该存在的组合，界面按它渲染成「新端口正在启动」。现把两者分开记录（新增runPort：进程实际监听的端口），改配置端口只改配置、不动运行端口上的就绪事实；界面据此显示「运行中 · 端口已改为 X（现监听 Y），点『重启』生效」，与实际语义一致 —— 在跑的进程只会停在旧端口上，要切端口必须重启。 - 端口设置提示措辞：运行中改端口后，设置页提示与挂件菜单状态行统一说明「当前进程仍在 Y 上运行」，避免用户以为端口已切一半。
- 外部 dsh 运行中改端口误报「未运行」：dsh 是别的终端启的（界面显示「外部 dsh · pid N」）时，去设置里改端口（如 3081 → 3080）——还没点「启动」——状态直接变成「未运行」，而 3081 上的进程明明还在跑，连「结束」「重启」两个按钮都一并被禁用（等于连那个还在的进程都结束不掉）。根因与上一条同源：外部 dsh 的判定完全依赖「当前配置端口」的探测结果，改端口时必须清空重探（探的是新端口），清空后旧端口上的外部进程就再也认不出来了。现为外部进程也留一份「实际运行端口」的档，改配置端口时先搬运、之后按 pid 校验它是否还活着；界面显示「外部 dsh · pid N（现监听 3081）· 端口已改为 3080，点『重启』生效」，「结束」「重启」保持可用，重启会先结束旧端口上的进程再在新端口启动。
- 拖拽挂件时窗口被「越拖越大」：按住挂件拖动时，滚轮 / 触控板会误触发实时缩放，而实时缩放那一路不写存储、不回推配置，于是窗口尺寸被改大了、设置页里的「大小」却还是旧值 —— 表现为拖着拖着变大、松手后大小描述对不上。现拖拽一开始就冻结缩放（含页面侧送来的实时请求），期间只记下最后一个目标值、松手后在吸附位置补做一次并落库广播，与手动拖滑块走完全相同的持久化路径；拖拽几何也改为会话内缓存，去掉每帧的同步取窗口尺寸 / 工作区，拖动更跟手。
改进
- 启动提速：dsh 一族与设置页改为惰性加载：
preload在启动路径上必加载，而它顶层require的 dsh 一族（dsh/dsh-market/dsh-export/dsh-backup/dsh-usage）与 Codex 统计合计 300KB+，这些只在运行时才用得到（菜单操作、退出清理、统计解析）。现改为首次用到才加载：Codex 统计、提权写 hosts、设置窗订阅各自按需require，避免把它们压进每次加载的求值阶段、拖慢首帧。纯性能改动，行为不变。
测试
- 新增
test/dsh-port-change.test.mjs（8 项）：锁死「配置端口 ≠ 运行端口」的语义，核心断言是运行中 + 未就绪这个组合永不允许出现；另一组锁死外部 dsh 的同款语义 —— 改配置端口后「在跑」这件事不许凭空消失（仍报外部进程、如实给出它实际所在的端口、并提示需重启），进程确证退出后留档按 pid 校验清掉、不再误报。测试走真实路径syncConfig → readConfig() → configure()，而非直接构造半份配置。 - 新增
test/build-gates.test.mjs（5 项）：构建门禁的自身守卫。测的不是产品逻辑，而是「门禁还在链路上」——prebuild必须同时挂sync-version.mjs与check-shared.mjs，ci.yml/release.yml必须真的执行npm run build且 CI 三关（lint / typecheck / test）齐全，Release 必须校验 tag 与package.json版本一致。防的是「门禁静默退役」：若有人精简scripts或工作流把某一环删掉，四关仍全绿、构建照样成功，却没有信号。 check-shared.mjs新增一项校验：dsh 默认端口DSH_PORT_DEFAULT的三处副本一致性（宿主constants.js、设置页DEFAULT_DSH_PORT、挂件页状态行的|| 3080兜底字面量）；CHECKS由 26 项增至 27 项。挂件页那份是「快照缺 port 才走的兜底路径」，正常拿不到，漏了极难被人工发现，故一并纳入校验。- 测试文件由 20 个增至 22 个、用例 514 项。
新功能 · 开发者 Tab（dsh）
- dsh 全量导出：把整个 dsh profile 目录（插件、配置、patch、数据）打成一个 zip 包，支持按目录 / 类型勾选，导出前先统计文件与体积，
.git等无关目录自动排除；「重新统计」与「打开导出目录」就地可用。打包为手写 zip 实现，附带回读校验（verifyZip）确保产物可解析。 - profile 写锁孤儿检测与清理：dsh 的 profile 写锁在上游存在已知缺陷 —— 进程被强杀时锁会永久残留，导致后续所有 dsh 操作空转到超时（表现为「卸载 / 更新失败」「市场卡片一张都不渲染」），且升级 dsh 无法解决。现提供只读检测（三重判据：锁文件存在 + 内容为纯数字 pid + 该 pid 确证不存在）与用户确认后的显式清理，检测到活动锁或内容读不懂时一律不清理。
新功能 · dsh 插件市场
- 排序方向可切换：各排序轴支持升 / 降序切换，默认方向按轴区分。
- 关键词分词与排除：搜索支持空格分词（多段「与」关系，可跨字段命中），
-词表示排除（只有排除词也成立时才算全目录减去命中）。 - 分类 chip 常用优先 + 折叠：分类按命中条数排序，常用分类常显、其余折叠；计数为 0 的分类置灰不可点。
改进
- 市场卡分类名预建 Map：分类中文名改为一次建成、模板 O(1) 取，避免每条记录都做一次线性查找。
- Codex 卡指标格统一：Codex 卡字段区跟进 dsh 用量卡的等宽指标格（
.stat-grid），同一 Tab 观感一致。 - 挂件任务栏避让重申：非 dsh 配置下也确保不占用任务栏（
ensureSkipTaskbar）。 - 菜单长文本不再撑破面板：菜单「组 → grid 体 → inner → 行」四层补
min-width:0，dsh 命令文本这类长行不再越出面板右缘，行内省略号才真正生效。 - 诊断日志改为轮转 + 重复抑制：日志超 1MB 不再「截断只留末尾」（那会把出错前的第一现场一起冲掉），改为整份改名成
whale-debug.log.1保住上下文；同一处代码在 5 秒内反复失败只落首条，窗口过去后补一行重复计数，既不刷爆日志也不丢线索。诊断卡「复制日志」在主文件只剩轮转头时自动改读.1。 - 悬浮页错误写入宿主日志：新增
whale:page-log通道，页面侧logErr除控制台外转交宿主落盘（%TEMP%\whale-debug.log），打包版没有 DevTools 时用户也能取证。
修复
- 市场卡按钮失效：市场卡片按钮判据修正，未安装 / 已安装 / 可更新各状态按钮正确可用。
- 诊断卡空态：诊断卡在无数据时不再渲染空卡与空报告。
- Codex 卡空指标格错位：无金额口径时留空的指标格不再多占一行导致错位。
- 挂件菜单贴错边：宿主主动挪窗（任务栏避让、改贴边间距、复位位置）与缩放提交后，新增
whale:snapped回推，页面据此重算菜单贴边方向 —— 菜单不再按旧位置摆到屏幕外或贴错边。 - 关闭鼠标穿透时菜单未收起：关闭穿透与开启穿透现在对称收菜单，避免菜单留在屏上、窗口却已
ignoreMouse=true导致点击穿透到下层应用。
构建与测试
- 新增
lib/dsh-export.js+test/dsh-export.test.mjs、test/dsh-lock.test.mjs、test/dsh-verify.test.mjs、test/dsh-host-compat.test.mjs、test/log.test.mjs、test/config.test.mjs；测试文件由 14 个增至 20 个、用例 486 项。 - 新增配置契约测试
test/config.test.mjs（8 项）：把defaultConfig/readConfig/writeConfig/patchConfig四份平行键表用机器钉死 —— 键集不一致、patchConfig分支漏键、非法值写入都直接失败（这几处漏掉是静默的：加进defaultConfig忘patchConfig，保存后永远是默认值）。顺带修掉一个真实缺陷：timerAt原先只判格式不判范围，99:99能一路写进配置，挂件把它塞进<input type="time">时会被清空导致定时刻静默失效，现三处调用点统一改用带范围校验的normHm。 check-shared.mjs新增五项校验：气泡字号BUBBLE_FONT、气泡默认配色THEMES.default、气泡字号单位除数--dshw-u，以及补上原先遗漏的TIMER_NOTE_MAX、QUOTE_GROUP_MAX；CHECKS由 22 项增至 27 项。同时修掉一处门禁绕过：某一份副本读不到时不再静默放行，改为独立计数并判定失败。（注：台账此后继续增长，当前为 30 组；QUOTE_GROUP_MAX已随台词库于 v1.12.x 下线而移出校验表，上列「27 项」为 1.7.1 当次口径。）- 新增配置字段
dshExportCred/dshExportNoMod（存于whale:config）：分别记住导出时「是否含凭据」（默认false）与「是否跳过node_modules」（默认true）。
新功能 · 三步向导
- 首次运行三步向导：全新安装不再面对一整页散开的卡片，而是按「① 填 API Key → ② 选显示什么 → ③ 试一下」三步走，每步只显示当前需要的最小配置，填完能立刻看到挂件反应；跳过与「以后再说」都保留（跳过即按默认档位建挂件）。默认档位由「完整」改为 6（刚好看得清又不挡桌面）。
- 首次运行引导：全新安装时挂件先弹一段引导气泡，说明怎么点、怎么拖、怎么打设置页，避免「装完不知道要干嘛」。
新功能 · 开发者 Tab（dsh）
- dsh 只读诊断与配置转储：新增只读诊断卡，把 Node / dsh 版本、npm 注册源、插件目录与全局安装的实际来源、dsh 端口归属（默认 3080，可在高级选项里改）、最近命令与最近日志一次列全；「配置转储」把 dsh 的配置文件解析成可读条目（含嵌套子条目），便于对着报错定位。只读，不改 dsh 任何配置。
- dsh 插件市场：设置页可直接搜索 / 安装 / 更新 / 卸载 dsh 插件市场里的插件，安装进度就地反馈（当前阶段 + 包名），更新前先比对目标版本，避免「点更新其实版本没变」。
- dsh 配置备份与可撤销（E1）：改动 dsh 配置前先自动留一份快照，可随时回滚；快照支持命名与展开查看（显示实际份数），保留份数可配（E4）。
- 单个插件禁用 / 启用（E2）：可单独禁用某个市场插件而不卸载，禁用即移出加载、启用即装回。
- 我的一键隔离（E3）：出问题时一键把本次涉及的插件隔离出去，隔离候选按「影响面」分档列出（不再截断），确认前能看到将被隔离的全部条目。
新功能 · dsh 挂件菜单收敛
- 挂件菜单 dsh 分组收敛：原先
启动 / 重启 / 结束 / 更新四个按钮平铺，现收成「状态行 + 主操作（启动 / 打开页面）+ 更多」两层；快照相关操作收进「更多」，菜单不再一屏排不下。
新功能 · 其它
- 法定节假日全天谷价：定价表补上法定节假日，节假日全天按谷价计（原先只认周末）。
- 多厂商模型模板：模型模板扩充，添加自定义模型时可从模板一键带出常见的 base URL 与字段映射。
改进
- 设置页按 Tab 分组：整页拆成 7 个 Tab（概览 / 用量 / 提醒与通知 / 文案 / 资源 / 数据与隐私 / 开发者），卡片归位、不再一页滚到底。
- GitHub 加速抽独立视图：
AccelView.vue从App.vue拆出，加速页的逻辑与样式独立，App.vue只保留装配。 - 按钮 / 卡片样式统一：统一到
src/main.css的utils-*基类，各卡片不再各写一份；柱状图纵轴参考线与方向修正。 - 开发者 Tab 降轮询：状态轮询不再固定高频拉取，改为按需触发 + 长间隔兜底，减少无谓的进程与网络开销。
- 版本口径改 npm latest：dsh「可更新版本」改为读 npm latest 而非本地已装版本推断，与「点更新会装到的版本」一致。
修复
- dsh 安装走 pnpm：原先
cmd /s /c拼命令会被引号截断，且pnpmArgs少--ignore-scripts（可能执行包内脚本）；现改走 pnpm 并显式关脚本，resolvePnpm找不到 pnpm 时降级回 npm。 - 供应链白名单拦截：命中白名单之外的包时给出
blockedByPolicy明确提示，不再静默照装。 marketUpdate假成功：原先只要命令退出码为 0 就报成功，现在按目标版本复核，版本没变如实报「已是最新」。dryRun漏判版本：dry-run 下不再跳过版本比对，演练结果与实际执行一致。selectBatch静默丢勾选：批量选择时原先会丢掉已勾选项（审计项 B9），现合并保留。parseDump漏收嵌套子条目：配置转储只取第一层，嵌套配置整段丢失，现递归收全。dsh-isolate谎报条数：隔离结果把未实际处理的条目也算进「已隔离」，现按真实处理数报。- C5 端口归属两处误判：3080 被非 dsh 进程占用时可能被当成 dsh（会误杀），现按进程命令行二次确认，占用者不是 dsh 则拒绝操作。
- 全量审计三处静默失效：2026-09-22 全量审计（26 条发现）中三处「看起来生效、实际没生效」的路径修复。
- 写配置失败留痕：写 dsh 配置失败原先静默吞掉，现
logErr留痕并在界面提示。 - 快照展开显示 0 份：「更多 → 快照」展开时份数取错，现读实际目录。
- 「立即清理」用旧值清：清理按打开面板那一刻的旧快照列表执行，现取当前值。
构建与测试
- 新增
lib/dsh-market.js（插件市场）+test/dsh-market.test.mjs、test/settings-allowbuilds.test.mjs；测试文件由 6 个增至 14 个、用例 348 项（原先 6 文件 / 约 60 项）。 check-shared.mjs新增两项校验：MAX_BATCH与NEWEST_VERSION的跨文件副本一致性。- 新增
.gitattributes：全仓统一 LF，避免 Windows 换行在 diff 与构建产物里来回翻转。 - 一键发版脚本（
scripts/release.mjs）：npm run release一把跑完前置检查 → 写版本号 → 本地四关 → 建 release commit → push → 等 CI → 打附注 tag → 等 Release 工作流 → 核对 zip 资产；--dry-run只检查不提交。
新功能
- GitHub 加速 · IP 获取来源可配置：「获取方式（高级）」三来源开关（DoH / 社区源表 / 当前 IP 表，默认全开，全关则拒绝开启）+ 行序即优先级；新键
ghAccelSrc进whale:config。候选链按「来源优先级 → 实测延迟 → 链内位置」排序。 - GitHub 加速 · 自定义源表：可粘贴自建 hosts 源表链接（http(s)，上限 10 个），默认不参与，勾选后才进
sources。 - 操作就地进度：各动作在按钮 / 开关旁显示当前阶段，开关加呼吸圆点，执行中按钮改亮度脉动 + 描边（
prefers-reduced-motion只放慢不关掉）。 - 更新检查跳插件市场：新增
redirectToMarket(keyword)，检出更新时结果行可点直达市场搜索页。
改进
- GitHub 加速 · 刷新走同一条候选链：原先无条件先解析 DoH、再全拉社区源，优先级只影响合并那一步（实测白等 13s）；现逐段推进、凑齐即停。
- GitHub 加速 · 探测复用与并发上限：结果由布尔扩为
{ ok, ms }，跨段复用同一(域名, IP)；新增PROBE_CONCURRENCY = 6（原先上百条请求一次全推出去，卡住设置页渲染线程）。 - GitHub 加速 · DoH 入口改并发竞速：阿里 DNS 提到首位（实测国外两家在很多网络下
:443不通），单入口超时 2s，失败原因如实写日志。 - GitHub 加速 · 窄窗不再顶破：来源追踪表改
table-layout: fixed+ 断长串；原理说明与操作日志默认收起。 saveConfig反向回推归一化配置：不回推emitConfigChange()，设置页手里还是未归一化值（表现为「点『上移』没反应」）。
修复
- 刷新沿用失效旧值：旧值原先无条件写回，可能留下解析不通的映射；现旧值也要过探测，不通就不写这个域名。
- 社区源表顺序静默失效：
normSources未剥落盘的'community:'前缀，比对恒不等致退回默认序。 - 「当前 IP 表」排首位不生效：
refreshIps的manual段原先与community共用源结果，从不读当前表。 - 补测轮候选丢优先级：补测候选原先固定排在 DoH 之后，「源表优先」静默失效。
github.com兜底漏探：兜底只加在filterReachable，刷新路径下 4 个兜底 IP 从未被探测。
构建与测试
- 新增 hosts 模块单元测试（
test/hosts.test.mjs），测试文件由 5 个增至 6 个。
改进
- 日志恒落盘：正式版也写
%TEMP%\whale-debug.log；超 1MB 保留末尾 200KB、超 7 天启动即清空。开发者工具恒开（打包版也可Ctrl+Shift+I）。 - GitHub 加速 · hosts 读写改异步：原先同步读会冻住设置页渲染线程；清理时循环删除多段残留块，关闭且文件未变时不再无谓提权。
- GitHub 加速 · 状态与进度：新增
broken（头标记在、尾标记不在）红字提示，只按第一段块判断生效；回显「已测 n/m 个」+ 呼吸圆点实时步骤；提权脚本补ipconfig /flushdns。 - GitHub 加速 · 冲突来源可识别：
127.0.0.1/0.0.0.0标为「本地反代类工具」，提示第三方条目像是谁写的。 - 精简
GH_DOMAINS：移除 5 个低频域名（每个都要单独解析探测，表越长开启越慢）。
修复
- 挂件每次启动重跑菜单迁移：不带
menuGroupsRev的补丁会把版本号冲回 0，现改为只增不减。 - 打包版 dsh 菜单组整节消失：原先按开发者模式建组，现按「这台机器有没有 dsh」显隐。
- 用量区间不记忆：改存
localStorage（whale:usageRange）。 - Codex 测试跨日偶发失败：原用例用
Date.now() - 26h，凌晨会跨到前天。
新功能 · 提醒与通知
- 通知统一出口：新增宿主叶子模块
lib/notify.js，把原先散在 7~8 处的utools.showNotification收成一个分发点，按配置分流到系统通知（默认开）与邮件通知（默认关）。两条铁律：免打扰由调用方判断（各提醒口径不同）；邮件失败绝不影响主流程（不 await，错误只logErr）。 - 邮件通知（SMTP）：用 Node 内置
net/tls手写最小 SMTP 客户端（不引第三方依赖），支持 465 直连 TLS 与 25 / 587STARTTLS。收件人 / 发件人 / 主题前缀进whale:config；服务器 / 端口 / 加密 / 账号 / 授权码进dbCryptoStorage的whale:secrets.notifyMail（不在顶层，别取s.mailHost）。设置页提供可折叠 SMTP 区（没配过默认展开）与「发送测试邮件 / 测试通知」两个按钮。 - 计时能力扩展：① 到点留言（
timerNote，≤60 字），到点气泡大字优先显示；② 休息档（timerBreakMin，0–120 分钟，0 为隐藏），到点动作条多一个「休息 N 分钟」接下一轮；③ 到点动作条：气泡旁弹出独立定位操作条（position: fixed+ 毛玻璃，与气泡同生共死），刻意不复用菜单样式、也不跟随挂件透明度。
新功能 · GitHub 加速（hosts 方案）
- 一键加速 GitHub：新增宿主叶子模块
lib/hosts.js与设置页组件src/views/AccelView.vue，走改 hosts 文件这条路（不装代理、不改系统代理）。流程：DoH 实时解析（2 个公共端点，按 5 分钟缓存）→ HTTPS 探测 + 证书 SAN 校验（避免解析到被劫持的 IP）→ UAC 提权写入 hosts（复用dsh.js导出的psExe()）。 - 标记块必须写在文件最前：改写范围严格限制在
MARK_START/MARK_END之间（上限 64 条），且块要落在文件最前 —— Windows 是 first-match 语义，写在后面会被其它工具的127.0.0.1条目抢先命中；块被挤出最前时degraded报警。按字节读写（不解码原文），避免中文注释被按 UTF-8 回写成乱码。 - 多来源 IP + 可追溯：多个社区 hosts 源共同供表，另备 4 个
github.com已知 IP；每个域名保留所有可达候选做运行期回退。支持手动编辑 IP 表、「检测连接」（不可达但仍是 DNS 当前答案的标stale黄而不红）、「刷新 IP 表」、「重新写入 hosts」，另有操作日志（50 条）与来源追踪表。 - 不走 IPC：GitHub 加速与邮件通知的能力都通过
window.services暴露（同dsh/ 备份），设置页侧未为它们新增 IPC 通道。
改进
- 设置页「提醒与通知」卡片成组：「更多提醒设置」折叠区收拢提醒停留时长 / 免打扰 / 提醒文案，卡片不再一屏拉不到底。
- 挂件菜单计时组改为两层：把「仅显示 / 置顶 / 记住状态」收进「更多（显隐与保存）」子分组；分组「外观」默认改回收起（一次性迁移
MENU_GROUPS_REV）。 - 新增输入焦点通道（
whale:input-focus）：挂件窗口以focusable:false创建，Electron 下根本不收键盘事件，新的留言 / 时长输入框点得进去却打不出字，光w.focus()无效。现改为开菜单时setFocusable(true)夺焦、关闭时置回并显式唤回 uTools 主窗（否则设置窗会因被抢过焦点而被 uTools 自动隐藏）。 - 菜单面板与标签列自适应宽：面板改
max-content夹取 260–320px、标签列 50–72px，容纳「留言 / 休息时长」这类长标签。 lib/codex.js缓存升到 v2（加rl/rlTs）：version不符当空缓存重扫 —— 老缓存指纹没变不会触发重解析，不升版本订阅窗口会永久缺失。codex.js先分桶再花预算：原先边扫边判预算，耗尽时进度永不前进；单轮上限由CODEX_MAX_FILE_BYTES/CODEX_MAX_ROUND_FILES/CODEX_MAX_ROUND_BYTES给出。- 菜单输入框改「回车才生效」：原先绑
change边打字边存，数字框打到一半就被钳制，根本打不完。 saveCfg()原样带回邮件开关：菜单任何改动都会回写配置，不带回timerMailOn/notifyMailOn就会用undefined把用户在设置页开的邮件通知悄悄关掉；applyConfig同时跳过持有焦点的输入框。- 新增配置项：
timerNote/timerBreakMin/menuGroupsRev，以及通知与加速相关字段（notifySystemOn/notifyMailOn/mailFrom/mailTo/mailFromName/mailSubjectPrefix/ghAccelOn/ghAccelIps/ghAccelRefreshedAt），旧配置自动兜底；ghAccelIps由normIps归一（domain 转小写限长 253、IP 必须合法 v4、上限 64 条并按 domain 去重）；notifyMail密钥传undefined时沿用现值，避免恢复备份抹掉授权码。 - 计时时长由
timerMin（分钟）改为timerSec（秒），配合三段式 h/m/s 输入。
修复
- 修复超大 Codex 会话文件每轮重读：超上限的文件被跳过后必须照样落指纹，否则每轮扫描都重读、永久复发。
- 修复邮件配置反复弹回空表格：
mailConfigured早先要求账号与授权码齐备，而折叠态下不填也合法，导致每次重载都被判成「没配过」。 - 修复邮件凭据回填恒为空：
applyMailSecrets早先取的是whale:secrets顶点，应统一收凭据本体。 - 修复测试邮件被判格式错误：
testMail早先漏传mailFrom/mailTo/mailFromName。 - 修复测试通知误报失败：
testNotify早先漏传收件人，邮件没发出去就报错。 - 修复来源列上色完全失效：
ghTraceSrcCls早先拿宿主给的长串做全等比较，永远不相等，导致所有来源都落进默认灰；改为startsWith前缀匹配。 - 修复计时到点气泡残留：
startTimer先收起上一轮气泡；syncTimerMenu把「刚结束」排除在忙碌态之外；timerTakesBubble()/timerBubbleAutoMs()单独决定到点气泡是否占位与自动收起时长，避免留言弹一下就没了。 - 修复预算 / 波动开关打开时金额为空：
onBudgetToggle/onDropToggle补默认金额。 - 挂件页多处补齐
aria-label（title只在悬停可见，辅助技术读的是aria-label）。
构建与测试
- 新增 Codex 解析单元测试（
test/codex.test.mjs，6 个用例，覆盖指纹复用 / 超限跳过仍落指纹 / 预算耗尽下轮续扫 / 增量解析 / 清缓存重扫 / 按本地时区归日），测试文件由 4 个增至 5 个。
新功能 · 余额与用量
- 多厂商余额 / 额度：除内置 DeepSeek 外最多再加 9 个模型，内置 11 个厂商模板，只收录能用 API key 直接查到余额或订阅额度的厂商 —— 其余厂商没有这类接口，搬过来只会是空壳。可切换挂件主显示：余额型显示原币种余额（附「~今日已用」，按相邻两次余额差估算），额度型显示剩余百分比与重置时刻；主显示非 DeepSeek 时「用量与峰谷」整组收起。挂件菜单新增「模型」分组（只有内置 DeepSeek 时隐藏），点行即设主显示。密钥每模型一份存
dbCryptoStorage，运行时快照存whale:models（不进备份）。 - Codex 订阅窗口（5 小时 / 周）：Codex CLI 会把每次请求的额度快照写进自己的会话日志（
~/.codex/sessions），宿主顺带解析，不用配 Key、不发请求、不碰账号。挂件说明行与设置页「开发者」Tab 的 Codex 卡片各显示一行（含重置倒计时）。窗口名优先按日志里的窗口分钟数推断，日志没给才按位置叫「5h / 周」。 - 额度进度：填总量（元）+ 选重置周期（每月 / 每日 / 不重置）后显示进度条与剩余（≥90% 换暖色）。已用不落配置、按周期现算。额度只做展示，不影响余额、记账与任何预警口径。
- 今日模型占比（仅实时·令牌模式显示）：按模型列出今日金额占比（模型名 + 占比条 + 百分比 + 金额，按金额降序），标题行显示「共 ¥x · 更新于 HH:MM」。模型明细只有平台用量接口会给，记账模式拿不到。
- 自定义单价（仅「实时·令牌」模式生效）：可覆盖内置价目表，按百万 token 填谷价（缓存命中 / 未命中 / 输出），峰价沿用官方规则自动翻倍；支持 CNY / USD（选美元时填汇率），账本与挂件显示统一按人民币。
- 峰谷倒计时：峰谷台词第三行在「今日已用」后追加「距峰时 / 距谷时 1h20m」（不足 1 小时显示分钟）。
- 账本明细与检索（设置页「用量与账本」卡片，可折叠）：按日列出每日用量，并标出当天「未计入用量的余额变动」（红）与「手动校准」（灰）记录，点某天展开看每条的时间与原因，支持按日期或原因本地检索；区间跟随上方 7 / 14 / 30 天档位。
新功能 · 提醒与通知
- 今日预算提醒：可设每日预算金额，当天用量超出时弹一次提醒气泡 + 第三行常驻「超预算 ¥x」，并每天弹一次系统通知。气泡与通知互不依赖（气泡可能正被计时 / 峰谷提醒占用）。
- 低余额预警升级为完整提醒：余额低于阈值时除了数字变红，还会弹一次提醒气泡 + 每天弹一次系统通知。与「今日预算提醒」各自独立；两者同时命中时以低余额为准（更紧急）。
- 余额大幅波动通知：可设下降阈值（默认 5 元），单次采样余额下降 ≥ 阈值就弹系统通知。不做「每天一次」去重（基准随采样更新），只受免打扰约束。
- 提醒停留时长：峰谷切换 / 今日预算 / 低余额 / 穿透说明这几类提醒气泡可选常驻 / 5 / 8 / 15 秒（默认 8 秒）。注意：计时到点气泡由挂件菜单「到点通知」旁的档位单独控制，两者互不影响。
- 免打扰时段：可设起止时刻（支持跨午夜如
23:00–07:00），时段内「今日预算」「低余额」「余额波动」三类自动通知都不弹系统通知（前两类的气泡照常），且不占用当天名额（出时段后仍会补发一次）。 - 提醒文案可编辑：低余额 / 今日预算 / 峰谷切换 / 鼠标穿透四类提醒的气泡与系统通知共用同一份模板，六条（峰谷与穿透按状态各分两条）都能改。气泡只有三行，模板按行映射：第 1 行标题 / 第 2 行大字 / 第 3 行说明，超过三行并入说明行；系统通知取全文并把换行合并成空格。占位符
{balance}{threshold}{used}{budget}{over}{schedule}，未提供的原样保留（能一眼看出写错）；空模板 = 恢复内置默认。多厂商模型的余额通知与余额大幅波动通知有意保持写死。
新功能 · 素材与形象
- 素材集中管理（独立「资源」Tab）：形象 + 六段音效（音色两段 + 四类提醒音）导入素材的集中管理入口，四张卡 —— 「资源概览」、「导入的形象」、「导入的音效」、「内置资源」（可预览 / 试听、不可删）。此前这些按钮藏在
skin === 'custom'/soundSet === 'custom'的条件里，一旦切回内置形象 / 音色，素材在界面上就「消失」（磁盘上还占着），既看不到也删不掉；现在这块不做任何门控。每项显示文件名 +体积 · 导入时间。清除分两档：「清除未使用（n）」按「当前设置会不会用到」挑出未使用项，先快照再逐个删，正在使用的一律保留；「清除全部素材」逐个删，全清后把形象回退默认、音色回退「小黄鸭」。两者都只删素材、不动其它设置。 - 素材包（导出 / 导入）：把导入的形象与音效打包成一个
.whaleassets文件，换机器时一次带走。导入是两段式（与「备份与恢复」同一套）：先解析并列出条目让用户勾选，确认后才真正写入。写入语义：形象是「补充」（每张生成新 id 进画廊，不动已有画廊）、音效是「同槽位覆盖」（换格式不留旧文件）。素材包不落任何存储键、不新增配置项。 - 挂件形象切换：内置形象（默认
DSniang1随包；DSniang02按需下载；形象 id 即public/whale/下的图片文件名） / 自定义（png / jpg / jpeg / webp / gif / apng、≤5MB，不收 SVG）。图片复制进插件数据目录，推送时读成 base64 data URL（挂件页面加载不了插件包外的file://）；导入后自动切到这张，删除后若正用「自定义」自动回退默认形象。 - 自定义形象升级为画廊：由「只存一张」改为多张（最多 20）。界面是缩略图网格：点缩略图即切换、「置顶」挪到第一位、「删」删掉该张（删的是当前那张时顺延到剩余第一张），当前那张带「使用中」角标。老数据就地归一化，不做数据迁移。GIF / APNG 走原样复制以保住动画，静态图走裁剪层。
- 形象裁剪：两段式（选文件不落盘 → 裁剪层 → 确认才写入；GIF / APNG 绕过裁剪层）。裁剪层支持 8 手柄拖拽缩放、框内平移、框外压暗，一键**「自动裁掉透明边」，导出保留透明通道**。
- 音效试听与裁剪：已导入的按压 / 释放音可点「试听」；导入改为「选文件 → 弹波形裁剪层 → 确认落盘」两段式。裁剪层用 canvas 画峰值波形，拖手柄选段（上限 10 秒，下限防长音频里手柄叠死），可试听选区，确认后导出 16-bit PCM WAV。
- 音效槽位由两段扩到六段：新增**「提醒音效」分组**，低余额 / 今日预算 / 峰谷切换 / 鼠标穿透四类提醒各可导一段，合成六个槽位。与音色的关键差别：四段提醒音没有内置回落，留空即静音；播放只看全局「音效开关 + 音量」，不受「音色」下拉影响。
- 音效槽位升级为音效组：每个槽位由「一段」改为「一个数组」，同一槽位可导多段、挂件每次随机播一条且不连续重复同一条，删到只剩一段就固定播它。老结构就地升级成单元素数组、不主动写回存储。
- 自定义气泡图：最多 8 张。点小鲸鱼抽到「气泡图」那组台词时从图里随机显示一张，删光回退内置
rua.webp。与形象的四处有意不同：① 不裁剪、不重编码（过一次 canvas 就把动画帧丢了）；② 没有「当前用哪张」（有图就随机抽，网格里没有「使用中」角标与「置顶」）；③ 因此不参与「清除未使用」统计，只能靠「清除全部素材」删；④ 推送总量有预算（超出即跳过）。 - 气泡配色主题：默认（蓝白）/ 深色 / 樱花。只重写 CSS 变量、不重建 DOM；「低余额」红色是状态色，不随主题变。换形象后命中测试画布会按新图重建（透明区穿透判定跟随新轮廓）。
- 「数据与隐私 → 清除选中数据」新增独立的自定义形象项：删图片与元信息并把空形象推给挂件；若形象正为「自定义」且未同时清「挂件设置」，会顺带回退为默认形象并广播给挂件。
新功能 · 文案与交互
- 台词库可编辑（与「提醒文案」合并为设置页「文案」一张卡）：六组文案各一个输入框，一行一条，卡片头右侧「保存 / 恢复默认」。空组 = 恢复内置默认（空数组会让气泡没字）。
- 随机台词由写死的六组升级为可配置的「组列表」：每组可选
card（内置余额 / 时段卡，内容现算、文字不可编辑）/text（用户台词）/image（抽一张自定义气泡图），并可调权重与字号档（普通字号自动换行 / 大字不换行、整体缩放）。没配过时回退内置六组，顺序与权重与升级前完全一致；老配置就地升级，不做单独的迁移步骤。 - 点按依次播放台词：开启后点气泡从第一组起按顺序播放六组台词，每点一次切下一组、播完最后一组才收起；关闭保持「每次随机一组」。
- 挂件菜单末行新增「隐藏挂件」（与「打开设置」同排的次要按钮）：与设置页「隐藏挂件」同一路径；下次用设置页「显示挂件」或全局快捷键唤回时重建窗口。
- 一键复位窗口位置：把挂件挪回右下角默认位置，用于换显示器、改分辨率或拖出屏幕后找回挂件。
- 吸附与翻转设置：① 吸附区宽度改为可调（1–45%，默认 25 保持原手感）；② 新增「关闭吸附」档，松手停在哪就是哪 —— 位置仍按「最近边 + 净距离」记锚点，照旧能原样还原；③ 吸附与翻转解耦：朝向（镜像）跟着位置走，关掉吸附后照样生效。缩放的不动点也复用同一判定，自由位缩放不会朝边缘挤。
改进
- 用量趋势升级（原「近 7 天用量」）：柱状图可选 7 / 14 / 30 天（宿主一次给 31 天，前端只切片、切档位不重新请求），下方新增本月汇总（本月累计 / 日均 / 最高单日 / 累计已用）。账本保留天数由写死的 30 天改为可配（35–730 天，默认 365）。
- 「本月汇总」补上累计已用（账本滚动累计，跨天只增不减，不受历史保留期裁剪与上方区间影响）。
- 账本明细筛选增强：原检索只有「关键词命中即保留整天」一条路。现加一个类型下拉（全部记录 / 只看未计入 / 只看校准），命中口径改为条目级（整天没有命中条目就整天不显示），筛选态下强制展开。无任何筛选时行为与原先完全一致。
- 今日模型占比的模型名改为显示友好名称，鼠标悬浮可见原始模型 id；只做显示层映射，不合并数据、不改金额。
- 低余额阈值的默认值来源统一（内置 DeepSeek 与多厂商模型走同一份：人民币 10 / 美元 2）；阈值单位跟随账本币种显示「元 / 美元」。
- 自定义单价支持按模型覆盖：按模型名子串匹配，只填三个单价。取价改为三级顺序：按模型覆盖 → 全局覆盖 → 内置价目表。
- 更新检查改为默认关闭：原先默认开启，装完插件什么都不配、第一次呼出就会向第三方 GitHub 加速代理发一次请求。请求本身不含任何用户数据，但仍是「零配置状态下就有外发」，公开分发按隐私优先处理 —— 用户主动勾选才联网。
- 设置页结构整理：原先 12 张卡片竖排一屏到底，找一项要滚很久。现按主题分 7 个顶部 Tab（外观 / 资源 / 用量 / 窗口 / 数据 / 帮助 / 开发者），Tab 条吸顶。同时按主题合并 / 拆分卡片：「台词库」+「提醒文案」合并为「文案」；「挂件行为」拆开 —— 用量口径并入「用量与账本」，其余归入新的「提醒与通知」。纯前端结构调整，配置项与存储键一个没动。
- 气泡三行字号整体上调约 9%，可用区域没动：长文案照旧自动等比缩小兜住，所以既不会撑出气泡，气泡也不用跟着变大。
- 随机台词改为不连续重复：同一句撞上就在其余条目里等概率重抽（不是简单取相邻那条）。组内只有 1 条时无从避免。
- 把散在 3 处的「今日已用 ¥x」措辞收进同一个函数（常驻主显示 / 峰谷组台词 / 多厂商模型的说明行），以后改文案只改一处。
修复
- 修复挂件贴在屏幕上边时三点菜单看不见：菜单原先固定往按钮上方展开，而窗口留白只有上 / 左单侧，挂件吸附到屏幕顶部后菜单上半截落在屏幕外。现改为窗口四周各留透明留白、挂件本体在窗口内居中，页面据此算出上 / 下真正可见的高度：上方装不下且下方更宽就改向按钮下方展开，高度不足时压
max-height在菜单内滚动。 - 三点菜单的开关顺手做了几处修正：关菜单那一下立即重算鼠标穿透与菜单按钮显隐（原先要等下一次
pointermove，导致这一下点击被窗口吞掉）；点鲸鱼本体关菜单时这一下照常当点击 / 拖拽用；菜单开着时滚轮缩放挂件会重新贴回按钮；重开菜单回到顶部。 - 修复峰谷组气泡的说明行太小（挂件缩得越小越明显）：三行字号共用同一个缩放系数，而第 3 行是三行里唯一不换行的长行，按它算出的系数会把第 2 行的大字金额一起压小（最大尺寸下实测由 114u 压到约 61u）。现允许第 3 行折成两行并抬高说明行档位，625px 实测渲染字号由 23.6 / 37.4 / 20.3px 变为 43.9 / 69.4 / 43.9px。
- 修复常驻主显示的说明行太小（同一机制漏掉的另一条路径）：上一条只让气泡台词换行，常驻主显示走的是另一段代码、从不带折行类名，于是「今日已用 ¥x · 超预算 ¥y」与「已用 x% · M-D HH:MM 重置」仍按不换行撑宽、把三行一起压小（缩放系数仅 0.518 / 0.630）。现默认允许折行，两者回到 0.973 / 1；常规文案本来就不满一行宽，不受影响、也不会折行。
- 修正 Flash 定价偏高 50%：内置价目表原先每项都正好是正确值的 1.5 倍，导致「实时·令牌」模式算出的今日已用偏高 50%。同时补上当前模型名，并让取价在价目表未收录时留一条日志，便于官方上新 / 改名后及时发现。
- 修复多厂商模型的 DeepSeek 模板可能取到美元余额：该字段会同时给多种币种且顺序不固定，按下标取可能拿到美元那条，金额取错不报错、只把钱显示错。现改为按币种挑条目；条件不匹配时提示「字段取不到数值」，比静默取错币种好。
构建与测试
- 新增构建期副本一致性校验（挂在
prebuild上）：同一份常量在宿主 / 设置页 / 浮动页 / 样式表里各有一份副本，这些副本消不掉（preload 不参与打包、浮动页没有require、CSS 变量宿主读不到），改一处忘另一处只会静默不一致。脚本逐对比对，不一致直接让构建失败。已知盲区：音效六个槽位比不了，加槽位要手动核对两处。 - 新增单元测试（
npm test，Node 内置node --test，零依赖）：覆盖四组纯函数 —— 峰谷判定与模型定价、取余额的多币种挑选与字段路径解析、配置归一化、凭据加解密。前三组被用来算今日用量，算错不报错、只会把钱算错；第四组是备份打开的唯一保障。单测从 7 个扩到 23 个。 - 新增 ESLint 静态检查（
npm run lint）：只为发现真问题（未定义 / 未使用变量、重复键、不可达代码、Vue 模板里的错误用法），不含缩进 / 引号这类格式规则。首次接入即清掉 5 处真问题（多余参数、无人调用的函数、只赋值不使用的变量等）。 - 新增持续集成：push 到
main、任何 PR、手动触发时，依次跑lint→typecheck→test→build（Node 24 +npm ci）。刻意只调用本地已有的 npm script、不额外引入工具链 —— 保证「本地能过」与「CI 能过」是同一件事。产物dist/不上传、不发布。 - 新增发版自动化：打
v*tag 时自动校验 tag 与package.json版本一致（不一致直接失败）→ 跑与 CI 同一套检查 → 把dist/打成 zip 并建 Release。边界：uTools 市场的发布仍需人工打包.upx上传；README 的「版本记录」仍是人工整理的对外口径。
素材、文档与许可
- 内置形象图改为 WebP，插件包从 11.5 MB 降到约 1.7 MB：这些是带透明通道的插画，PNG 无损格式极不划算（13 张占打包体积 94%）。统一转成 WebP（有损 q90，带 alpha） 后合计约 1.0 MB；分辨率、宽高比与透明通道逐张核对一致。形象 id 就是文件名主干、不含扩展名，所以老用户配置与各处副本一个都没动。
- 内置音效剥离 ID3 标签：原先带的打包工具与上传者信息随仓库分发毫无用处。只切掉 ID3v2 标签段，不重编码、不动音频帧数据，音质与时长完全不变。
- 新增 PROVENANCE.md（素材来源与许可范围）：逐文件列出与上游的对应关系、许可范围划分、已做的元数据清理与 Takedown 承诺；README「许可证」段原先那段长声明改为指向它。
- README 补充定价表（峰谷价原先只写在代码里，列成表便于核对）与美术素材授权声明。
- README 新增 卸载 独立小节：原先「移除插件不会删数据」只写在「数据与隐私」的一条里，从目录搜「卸载」找不到入口。
- README 新增**「方式四：把下面这段粘给 AI」**安装说明（安装）：面向只想拿到成品的用户 —— 复制一段话粘给任意 AI 助手，由它代为完成「克隆 →
npm ci→npm run build→ 在 uTools 开发者工具里把入口指向dist/」。
- 新增鼠标穿透（设置页「挂件窗口」开关）：开启后挂件完全不接收鼠标 —— 点击 / 拖拽 / 菜单全部穿透给下层应用；鼠标在鲸鱼上停留约 1 秒可临时接管，移开约 0.7 秒自动交回穿透。穿透中菜单按钮以半透明虚线常显作提示，切换时弹一次说明气泡 + 系统通知
- 新增「切换鼠标穿透」指令：可绑 uTools 全局快捷键一键开关，作为穿透后的快捷逃生通道；设置页内提供「复制指令名 / 新增快捷键」直达绑定
- 新增窗口透明度（20%–100%）：设置页滑块（拖动实时预览）+ 挂件菜单档位，作用于整窗（含气泡与菜单）
- 新增自定义音效：按压 / 释放两段可分别导入（mp3 / wav / ogg / m4a / flac，单文件 ≤5MB），文件复制到插件数据目录（不引用源文件）；释放音可缺（松手静音），按压音缺失时回退「小黄鸭」；挂件菜单音色新增「自定义」。「清除选中数据」新增独立的自定义音效项，清除时若音色正为「自定义」，会顺带把它**回退为「小黄鸭」**并广播给挂件
- 修复记账误判（对齐同源桌面端实现）：赠送额度整块到期 / 被平台收回、短时间异常跳变、更换 API Key 三种情况不再被记成「今日已用」—— 判据分别取自余额接口的赠送额度字段、间隔放宽的可信上限、API Key 指纹（换 Key 只重置比较基准，差额不入账）
- 账本新增赠送 / 充值 / 采样时间 / Key 指纹等字段（旧账本自动兜底兼容）；今日被拦下的变动在设置页列出「今日另有 ¥x 余额变动未计入用量（原因 / 时间）」，并在挂件气泡第三行解释一句
- 新增手动校准今日已用（记账模式）：只改当天累计并留记录，不动余额基准，之后继续实时累加；令牌模式下以平台返回为准，不显示该入口
- 修复挂件菜单里 dsh 状态不自动更新：原先挂件只在点击操作时同步收一次快照，「3080 就绪」「进程退出」「安装 / 版本查询完成」等异步变化会让菜单一直停在「启动中…」，需点一下「打开页面」才刷新；现改为宿主主动推给挂件
- 性能：鼠标穿透开关双向去重（页面侧值没变不发 IPC，宿主侧值没变不重复调系统接口）；页面侧鼠标命中的像素判定合并到每帧一次
- dsh 新增「启动时不自动打开浏览器」勾选（默认勾选）：启动命令默认带
--no-open，由插件的「打开 Web UI」按钮打开带 token 的地址；取消勾选则交给 dsh 自己弹浏览器 - dsh 改为直接用
node跑它的 CLI，不再经过npx：- 优先复用你已全局安装的那份（PATH / Node 目录附近 / npm 默认 prefix 都能识别到），没有全局安装才装一份到插件目录 —— 不会再出现「同一份 dsh 装好几遍」
- 不再受
npx缓存影响（此前每次换参数就可能新建一个完整副本，还会出现「子依赖已是新版、CLI 本体还是旧版」，重启也不生效） - 卡片里明确显示插件目录 / 全局安装 / 实际使用（含来源）
- 「dsh 版本」默认「自动」＝安装 / 更新时取
latest，也可固定某个具体版本（可先「查询可用版本」） - 「更新」＝结束正在运行的 dsh（含别的终端启的）→ 重新安装所选版本 → 原本在跑就用新版重新启动；日志逐步写清每一步结果
- 新增「更新前重新下载」勾选（仅在用插件目录那份时生效）：先删掉插件目录里的 dsh 再装，强制重新拉取
- dsh 卡片重排：状态 + 启动 / 重启 / 结束 / 更新 / 打开 Web UI 置顶，版本信息改为「实际使用 / 全局安装 / 插件目录 / 最新」四行；「版本 / 注册源 / Node 目录 / 三个勾选项」收进「高级选项」折叠，卡片明显变短
- dsh 体验：查询过版本后若比当前新，状态行直接提示「有新版本 x.y.z，点「更新」」；启动 / 重启 / 更新时自动展开日志并跟随滚到底部，未就绪时显示「已等待 x 秒」；日志框支持清空日志
- 新增两个维护按钮（「故障排查」里，点击一次变确认）：删除插件目录的 dsh（回收约 214 MB）、清理 npx 旧缓存（可回收数百 MB）；两个安装路径可一键复制
- 修复全局安装失败 EPERM：Windows 上全局 npm 目录常只对管理员可写。现在插件会先真写一次做探测（只读权限检查不可靠），不可写就直接用管理员权限安装（弹一次 UAC，取消 UAC 不会被误判成功）；卡片会标出「只读，更新会弹一次 UAC」
- 「更新」更省事：所选固定版本与当前一致时直接提示「已是最新，无需更新」，不再白跑一次安装
- 新增备份与恢复（设置页「数据与隐私」→「备份与恢复」）：导出「挂件设置 / 账本 / 窗口位置 / 计时」为一个 JSON 文件；凭据默认不导出，勾选后必须设密码，用 scrypt 派生密钥 + AES-256-GCM 加密后才写入（无明文、防篡改，密码不保存）；导入时先列出导出时间 / 插件版本 / 包含项，勾选要恢复的项后按同名覆盖写入，恢复设置或窗口位置会重建挂件立即生效
- 「清除选中数据」二次确认时会列出将清除哪些项，并提示「清除前建议先导出备份」
- 新增「自动避让任务栏」（默认开，可关）：摆放 / 吸附 / 缩放统一走「可用区」计算（系统工作区 + 四边贴边间距），并每 250ms 采样一次任务栏此刻是弹出还是收起 —— 收起时挂件贴满边，任务栏一弹出就按锚点重摆让位，收起后再贴回（顺带覆盖改分辨率 / 缩放 / 换屏）。识别方式：Windows 上 Electron/uTools 的工作区不随任务栏显隐刷新（electron#6312），所以自动隐藏的任务栏只能看光标；方向与厚度仍读注册表。设置页会显示识别结果
- 新增「贴边间距」：上 / 右 / 下 / 左四个数值（0–400px，0＝紧贴），吸附 / 贴边按它留距离，改完立即重摆
- 新增计时 / 定时 / 倒计时：在思考气泡里每秒刷新 —— 正计时、按分钟倒计时、指定时刻定时；支持暂停 / 继续 / 重置并记住模式与参数；到点响提示音 + 可选系统通知并显示「时间到！」（停留时长可选 5 / 8 / 15 秒或常驻，跨天定时显示「明天 HH:MM」）；开启「记住计时状态」后重载插件继续计时
- 新增「只显计时」「气泡常驻」开关：计时期间气泡可只显示计时，也可照常显示余额 / 今日用量等全部内容（计时状态变化时先弹 2 秒计时，再切回常规内容）
- 思考气泡按内容自适应：长文案自动等比缩小字号、不再撑出气泡
- 新增**「dsh」集成**：挂件菜单与设置页可直接 启动 / 重启 / 结束 / 更新 DeepSeek Harness 并打开 Web UI（自动使用 dsh 打印的带 token 地址）
- 结束 / 重启支持外部终端启动的 dsh（按本地端口探测；端口被非 dsh 进程占用时拒绝操作）；普通权限被拒时自动提权重试（UAC）
- dsh 可配置：运行方式（
npx/ 全局安装）、npm 注册源、指定版本、Node.js 目录、更新前清理 npx 缓存、uTools 退出后保留进程 - 修复「实时·令牌」模式下刷新今日总量后，设置页近 7 天用量不更新、当天柱与挂件显示不一致的问题
- 修复：只选计时模式未开始却重载插件就误报「时间到」；三点菜单被长文本撑宽、面板顶部圆角被裁成直角
- 体验：气泡圆圈整体放大 18%；计时每秒只刷新时钟文本；设置页打开即自动探测 dsh 状态（并每 4 秒刷新）
- 新增峰谷时段切换提醒（气泡提示当前时段，可单独开关）
- 新增账本 CSV 导入（与导出互转，同日覆盖，保留最近 30 天）
- 新增「只显示挂件 / 只显示设置窗口」进入方式与位置锁定
- 「数据与隐私」改为按项勾选清除（凭据 / 挂件设置 / 账本用量记录 / 窗口位置与更新缓存）
- 设置页说明分「使用说明 / 故障排查」折叠展示，新增留言与反馈入口
- 首次发布：余额与今日已用双模式、低余额预警、近 7 天用量趋势、拖拽吸附、音效与气泡、检查更新。
- 本 README 面向使用者与安装；
- 开发 / 维护向的完整规格（架构、窗口几何、IPC 通道、存储结构、视觉参数、峰谷定价、踩坑结论）见 docs/whale-widget-spec.md；
- 美术素材（形象 / 动图 / 音效 / 图标）的逐项来源、上游对应关系、许可范围与元数据清理见 PROVENANCE.md。
挂件视觉、台词与交互原型来自 MeteorNOX/DeepSeek-Balance-Whale-Widget。
本项目基于 GNU Affero General Public License v3.0（AGPL-3.0-only） 开源，详见 LICENSE。
本项目移植自 MeteorNOX/DeepSeek-Balance-Whale-Widget（MIT License，Copyright (c) 2026 MeteorNOX），上游代码的 MIT 许可条款保留在 LICENSE-MIT。
public/whale/ 下的挂件形象、随机动图与内置音效，以及 public/logo.png 图标（由 DSniang1 缩放而来），均来自上游开发者（上游同样声明其素材不在 MIT 覆盖范围内）：其中四个音效在上游仓库中与上游逐字节一致（Ya2.mp3 是，Ya1.mp3/D1.mp3/D2.mp3 已剥离 ID3 标签、不再是），rua.webp 由上游 bubble-petpet.gif 改名并转成无损动 WebP（逐帧像素一致、非逐字节一致），随包形象 DSniang1 与可下载形象 DSniang02 画面内容与上游一致、但已重新编码为 WebP（DSniang02 自 v1.8.0 起改为按需下载，不随包）。这些素材按「原样（as-is）」分发，仅供运行本插件使用 —— 不随本项目代码一起再许可，也不声明为本项目原创作品。另有可下载的共享形象与音效来自上游交流 QQ 群分享，同按 as-is 提供。逐文件的来源与许可范围见 PROVENANCE.md；需要干净授权时不必改代码，设置页「资源」Tab 支持导入自定义形象与音效。
发布 / 分发前逐条核对：
- 来源与署名：
LICENSE（AGPL-3.0-only）与LICENSE-MIT（保留上游Copyright (c) 2026 MeteorNOX）随包；README 顶部与设置页「帮助 → 关于与更新」标注个人衍生版（非官方、与 DeepSeek / uTools 无关联、无官方售后）；PROVENANCE.md 逐文件列出素材来源、许可范围、元数据清理与 Takedown 承诺；不以「官方」「官方授权」等名义自我描述。 ⚠️ 内置素材有授权问题（需自行准备，且须有权限分发）：public/whale/下的内置形象图（默认DSniang1.webp）、rua.webp与四个内置音效来自上游开发者，不在本项目任何许可覆盖范围内，仅按「原样（as-is）」随插件分发；另有 1 张可选下载形象（v1.8.0 起）打成素材包挂在 GitHub Release 上（同样属上游开发者素材）。公开发布 / 分发前必须删掉这部分素材或换成你有权分发的素材，并据实说明来源与许可；不想折腾授权时，功能上可直接去掉内置素材，让用户用设置页「资源」Tab 导入自己的形象与音效。- 隐私：源码无本机绝对路径与内网 IP；无硬编码密钥（代码里只有凭据名
apiKey/platformToken/models，密钥值存dbCryptoStorage，不进代码 / 注释 / 示例 / 默认值 / 报错文案）；素材内无个人 id 与个人截图（代码中出现的作者 GitHub 用户名仅用于本项目自身仓库地址）；素材无归属元数据（WebP 无EXIF/XMP/ICCP，PNG 无tEXt/iTXt/zTXt/eXIf，MP3 已剥离 ID3）；.gitignore覆盖密钥、备份文件、证书。 - 网络：零配置状态下无任何外发请求（自动检查更新默认关闭）；全部外发请求已在「数据与隐私」中列出地址、用途与发送内容；无隐蔽数据回传，无第三方统计 / 埋点。
- 代码：preload 与挂件页面原样分发（不打包、不压缩、不混淆，
node --check全部通过）；无eval/ 动态执行 / 后门 / 远控 / 挖矿，账本只写本机；不改 DSH 本体与其它插件，全局挂载带前缀（window.whale/window.__dshWhaleWidget）；只新增配置字段、旧配置由readConfig兜底；新功能异常均有try/catch兜底（挂件不白屏、dsh 进程不被拖垮）；npm run lint/typecheck/test/build全部通过。 - 内容：无广告、拉群、代充、收款内容；无违规内容。
本清单同时提供给其他 fork / 二次分发的使用者作参考（尤其是上一条
⚠️ ）。