dsh-whale-live2d
把 DSH Web 右下角的余额挂件（dsh-whale-widget）从一张静态 PNG
换成 Live2D 动态模型（默认：DS 鲸鱼娘，44 表情 / 8 动作）。
为什么是「叠加式插件」
dsh-whale-widget 装在 C:\Users\Harmless\.dsh\profiles\web\node_modules\ 里，
有两个硬约束：
- 它由
dsh plugin add github:MeteorNOX/DeepSeek-Balance-Whale-Widget 安装，
升级时会覆盖该目录 —— 任何直接改它的改动都会丢；
- 它只认一张静态 PNG（
/dsh-whale/image.png），内部没有任何 Live2D 支持。
所以本插件不改挂件一个字节，而是照 dsh-whale-emote 已验证的模式：
- 自己注册路由（
/dsh-live2d/*）；
- 用挂件自己也在用的
tapIndex 机制注入一段客户端脚本；
- 客户端脚本把挂件那张
<img> 透明化（但保留元素本身），
在完全相同的几何位置叠一块 Live2D canvas。
保留 <img> 元素这一点很关键：挂件的命中测试是
img.getBoundingClientRect() + PNG alpha 取样（isWhaleHit），
元素一旦删除，rect 全为 0，挂件会整个点不动、拖不动。
保留它，则拖拽 / 吸附 / 气泡 / 音效 / 每轮消耗统计全部照旧。
依赖：Cubism Core 必须由你自己提供
Live2D 的专有许可不允许再分发 live2dcubismcore.min.js，所以本插件不内置、
不代下。请从 Live2D 官方渠道获取（Cubism SDK for Web），放到：
%DSH_HOME%\pets\.runtime\live2dcubismcore.min.js
没有它也不会坏：挂件会优雅降级成原本的静态鲸鱼娘，页面上弹出一张
写明落点路径的安装指引卡。（渲染栈 pixi.js + Live2D 引擎是 MIT 许可，
已作为 lib/live2d-vendor.js 随本插件发布，无需另装。）
安装
# 从 GitHub（推荐）
dsh plugin --profile web add github:harmless0819-dev/dsh-whale-live2d
# 或从本地克隆
dsh plugin --profile web add link:<本仓库绝对路径>
装完重启 dsh web（Settings → 重启 DSH，或 dsh-whale-emote\restart-web.ps1
在你自己的终端里跑），然后浏览器 F5。
重启是必须的：插件的挂载声明（cordis.patch.yml）只在启动时读取。
装好之后，改 lib/client.js 只要 F5，不用再重启 —— 宿主路由每次请求都从磁盘读。
卸载
dsh plugin --profile web remove dsh-whale-live2d
挂件会立刻回到原来的静态 PNG（本插件从未改动它）。
怎么确认装好了
三个层次，从粗到细：
# 1. 宿主侧就绪状态（core 是否为 true 是决定性的一条）
curl http://127.0.0.1:3080/dsh-live2d/health.json
# 2. 模型本体可服务
curl -o NUL -w "%{http_code}" http://127.0.0.1:3080/dsh-live2d/asset/c_0120.moc3
# 3. 浏览器侧实况（F12 控制台）
# window.__dshLive2d → { state: 'ready' | 'core-missing' | 'error' | 'no-widget', ... }
state 的含义：
| state | 含义 |
|---|
ready | 模型已上屏，PNG 已透明化 |
core-missing | 缺 Cubism Core；静态挂件保持可见 + 指引卡 |
error | 加载失败（.detail 有原因）；已退回静态挂件 |
no-widget | 没找到 .dshwv-body（挂件被禁用或未加载） |
换成别的 Live2D 模型
模型目录是 assets/whale-girl/，由 package-model.mjs 生成。换模型时：
- 把新模型的原文件放进
_incoming/<你的模型>/；
- 改
package-model.mjs 顶部的 SRC / EXPR / MOTION 映射；
node package-model.mjs。
脚本会断言：源文件缺失、引用闭包不完整、或目录里残留非 ASCII 文件名
（宿主路由与 Live2D 清单只接受 /^[A-Za-z0-9._-]+$/ 的路径段）都会硬失败，
不会静默产出一个加载不了的模型。
文件结构
dsh-whale-live2d/
├── package.json # DSH bundle 插件元数据
├── cordis.patch.yml # 插件挂载声明
├── README.md # 本文件
├── package-model.mjs # 模型打包：ASCII 重命名 + 生成 model3.json 清单
├── test-harness.mjs # 宿主侧离线自测（路由 / 穿越防护 / 模型完整性）
├── test-client.mjs # 客户端离线自测（缺 Core 时优雅降级）
├── lib/
│ ├── index.js # 宿主侧：路由 + 模型服务 + 注入
│ ├── client.js # 客户端：把静态 img 换成 Live2D canvas
│ └── live2d-vendor.js # pixi.js + Live2D 引擎（MIT，随包发布）
└── assets/
└── whale-girl/ # 打包好的 Live2D 模型（3.95 MB，纯 ASCII 路径）
├── c_0120.model3.json
├── c_0120.moc3
├── c_0120.physics3.json
├── c_0120.cdi3.json
├── c_0120.2048/ # 贴图
├── motions/ # 8 个动作
└── *.exp3.json # 44 个表情
自测
node D:\deepseek\dsh-whale-live2d\test-harness.mjs # 27 项
node D:\deepseek\dsh-whale-live2d\test-client.mjs # 11 项
两个都是离线跑（mock ctx / 最小 DOM 桩），不碰 profile、不启服务。必须保持全绿。
模型授权
DS 鲸鱼娘模型由 B站 @氵六青（11272072）无偿分享，作者声明：商用直播 √、
自印物料 √，禁止盗用与出售。
⚠️ 本仓库确实包含了模型文件（assets/whale-girl/），以便插件开箱即用。
我们没有出售它，也不主张对它的任何权利；若作者反对这一再分发，
assets/whale-girl/ 会被移除 —— 缺模型时插件会优雅降级成静态挂件。
完整的第三方声明见 THIRD-PARTY-NOTICES.md。
换用其他模型时请自行确认授权。
