前言¶
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
