前言¶
DeepSeek Harness (DSH) 的核心理念是「一切皆插件」。默认的 dsh-whale-widget 余额挂件采用静态 PNG，交互功能（拖拽、吸附、气泡）虽完整，但视觉表现固定。dsh-whale-live2d 插件的目标是将这张静态图替换为 Live2D 动态模型，同时保留原有的所有交互逻辑。
本插件通过叠加模式实现，不修改挂件代码，不破坏其原有结构，仅做视觉层替换。
安装与启用¶
安装插件需要使用 DSH 的插件管理命令。
dsh plugin --profile web add github:harmless0819-dev/dsh-whale-live2d
安装完成后，必须重启 dsh web 服务。重启后，在浏览器刷新页面（F5）即可看到效果。
工作原理：叠加模式¶
dsh-whale-widget 安装在 %DSH_HOME%\profiles\web\node_modules\ 目录下，该目录会被 dsh plugin add 命令覆盖，因此不能直接修改其源码。此外，挂件内部只支持静态 PNG 加载，没有 Live2D 引擎。
本插件采用叠加模式解决上述问题：
- 注入脚本：插件通过挂件已有的
tapIndex机制注入一段客户端脚本。 - 元素透明化：脚本找到挂件中的
<img>元素，将其设为透明（opacity: 0），但保留元素本身。 - Canvas 叠加：在同一几何位置叠加一个 Live2D 渲染的
<canvas>。
保留 <img> 元素至关重要。挂件的命中测试依赖 img.getBoundingClientRect() 和 PNG 的 Alpha 通道取样。如果删除 <img>，rect 将变为 0，挂件将失去拖拽和点击响应能力。通过叠加模式，挂件的所有交互行为保持不变，仅视觉被替换。
依赖与降级¶
Live2D 的专有许可不允许分发 live2dcubismcore.min.js，因此插件不内置该核心文件。
- 获取 Core：请从 Live2D 官方渠道（Cubism SDK for Web）下载
live2dcubismcore.min.js。 - 放置路径：将其放置在宿主环境的
%DSH_HOME%\pets\.runtime\live2dcubismcore.min.js。
如果未找到 Cubism Core，插件会优雅降级：页面上的静态 PNG 保持可见，并会弹出一个提示卡片，告知用户落点路径和安装指引。渲染栈使用的 pixi.js + Live2D 引擎为 MIT 许可，随插件包发布，无需额外安装。
模型管理与更换¶
插件默认集成了 DS 鲸鱼娘模型（44 表情 / 8 动作）。如需更换模型，使用提供的打包脚本 package-model.mjs。
- 将新模型的原文件放入
_incoming/<你的模型>/目录。 - 修改
package-model.mjs顶部的SRC（源文件）、EXPR（表情）、MOTION（动作）映射配置。 - 运行打包脚本：
node package-model.mjs。
脚本会对路径进行严格校验：模型文件必须是纯 ASCII 路径，否则会硬性失败，不会生成不可用的模型文件。
验证与自测¶
插件提供了一套离线自测脚本，可在不启动完整宿主服务的情况下验证逻辑。
- 宿主侧自测（检查路由、穿越防护、模型完整性）：
node test-harness.mjs
- 客户端侧自测（检查缺 Core 时的降级逻辑）：
node test-client.mjs
在宿主服务运行时，可以通过以下接口检查状态：
curl http://127.0.0.1:3080/dsh-live2d/health.json
state 字段返回状态值：
* ready：模型已上屏，PNG 已透明化。
* core-missing：缺少 Cubism Core；静态挂件保持可见 + 指引卡。
* error：加载失败；已退回静态挂件。
* no-widget：未找到挂件元素（挂件被禁用或未加载）。
模型授权¶
本仓库包含的 DS 鲸鱼娘模型由 B站 @氵六青（11272072）无偿分享。作者声明：商用直播、自印物料均允许。严禁盗用与出售。
若作者反对本插件再分发模型文件，插件将移除 assets/whale-girl/ 目录，届时仅保留叠加模式代码，模型部分会优雅降级为静态 PNG。使用其他模型时，请自行确认其授权协议。
插件目录：https://www.skillhub.cn/plugins/harmless0819-dev/dsh-whale-live2d
GitHub 仓库：https://github.com/harmless0819-dev/dsh-whale-live2d
