hacxy/dsh-live2d

dsh-live2d

npm version
license MIT

让 DeepSeek Harness 的 Web 界面右下角多一只 Live2D 看板娘——带加载进度条的模型、可以随手拖到任意位置，尺寸、位置、透明度、音量……全部行为都在 Web 可视化设置界面进行调整。

特性

- 右下角 Live2D 角色：默认内置模型（Cubism 6），支持任意 .model.json（Cubism 2）与 .model3.json（Cubism 6）
- 加载进度条：模型资源下载时显示进度，加载完成自动隐藏
- 可拖拽：拖到屏幕任意位置；不想要拖拽也能关
- 全量配置 Web 化：模型地址、尺寸、位置、锚定边、缩放、透明度、层级、音量、日志级别、总开关——13 个字段全部在「设置 → Live2D」里完成，保存即生效，无需重启、无需改文件
- 跟随主题：面板配色与 DSH 界面（浅色/深色）自动一致
- 零依赖安装：l2d 运行时已打进插件包，用户装完即用
- 配置安全：多开页面/外部修改冲突时自动刷新为最新值，不会静默互相覆盖

安装

dsh plugin --profile web add dsh-live2d
dsh web

想先本地体验？git clone 后在包目录 pnpm install && pnpm run build，再
dsh plugin --profile web add /path/to/dsh-live2d，最后 dsh web。

使用

打开 DSH Web → 左下角侧边栏 → 设置 → Live2D。

| 分组 | 支持配置                             |
| ---- | ------------------------------------ |
| 开关 | 总开关 enabled（关闭后不显示角色） |
| 模型 | 模型地址 modelUrl                  |
| 外观 | 宽度、高度、透明度、层级             |
| 位置 | 锚定边（右下/左下）、水平/底部间距   |
| 渲染 | 模型缩放、动作音量、日志级别         |
| 交互 | 可拖拽                               |

几点说明：

- 保存即生效：改完点「保存」，尺寸/位置类改动原地应用，模型地址等改动会自动重载模型，无需重启。
- 恢复默认：一键清除你的自定义，回到部署默认值。
- 实时同步：其他标签页或外部对配置文件的修改，会自动热更到所有已打开页面。

卸载

dsh plugin --profile web remove dsh-live2d

配置（进阶）

插件采用 DSH 官方 settings 通道，「三层解析，后层优先」：

1. schema 默认（内置）
2. base 层：部署者的组合配置（cordis.patch.yml 的 live2d 行）
3. user 层：~/.dsh/settings.yaml 的 dsh-live2d 段——由设置面板写入，优先级最高

~/.dsh/settings.yaml（正常不需要手改，设置面板会代管）
dsh-live2d:
modelUrl: "https://example.com/model.model3.json"
width: 320

开发

pnpm install
pnpm run typecheck   # tsc --noEmit
pnpm run build       # tsdown → lib/index.mjs（Node 半）+ lib/client.js（浏览器半，l2d 内联）

浏览器端到端验证（需先安装进 web profile 并 dsh web --port 3090 运行，本机装有 Chrome；headless 软件渲染下请先换成 Cubism 2 模型如 shizuku 再验证画面）：

"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --headless=new \
--no-sandbox --disable-gpu --enable-unsafe-swiftshader --use-angle=swiftshader-webgl \
--disable-dev-shm-usage --no-first-run --user-data-dir=/tmp/dsh-chrome \
--remote-debugging-port=9224 about:blank &

DEBUG_PORT=9224 node scripts/e2e-verify-v2.mjs

scripts/e2e-verify-v2.mjs 覆盖：默认挂载定位、加载进度条、改模型地址 → 挂件重载、改尺寸/锚定/总开关 → 原地生效，结束后自动恢复默认配置。

架构速览

- Node half（src/index.ts）：Cordis entry，用 installSettingsSection（@deepseek-ai/dsh-settings）注册 dsh-live2d settings namespace，组合配置作 base 层；schema 同时承担持久层校验。
- 浏览器端（src/client/）：__ModuleLoader__ CJS bundle。挂件订阅 ctx.settingsScope 快照——布局字段原地更新 DOM（不重载模型），渲染字段重建 l2d；设置面板向官方 settings.section 注入全字段表单（逐字段 set，恢复默认 unset）。

免责声明

本插件不包含、不分发任何 Live2D 模型资源。默认模型 URL 指向模型 CDN，请确认你有权使用所配置的模型（商用需遵循模型许可与 Live2D Proprietary Software License）。

License

MIT