dsh-whale-live2d

把 DSH Web 右下角的余额挂件（dsh-whale-widget）从一张静态 PNG 换成 Live2D 动态模型（默认：DS 鲸鱼娘，44 表情 / 8 动作）。

为什么是「叠加式插件」

dsh-whale-widget 装在 %DSH_HOME%\profiles\web\node_modules\ 里， 有两个硬约束：

1. 它由 dsh plugin add github:MeteorNOX/DeepSeek-Balance-Whale-Widget 安装， 升级时会覆盖该目录 —— 任何直接改它的改动都会丢；
2. 它只认一张静态 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 生成。换模型时：

1. 把新模型的原文件放进 _incoming/<你的模型>/；
2. 改 package-model.mjs 顶部的 SRC / EXPR / MOTION 映射；
3. 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。 换用其他模型时请自行确认授权。