dsh-pet-live2d

给 DSH（DeepSeek Harness）Web GUI 用的 Live2D 桌宠插件 —— 一只可以拖动、跟着鼠标看、点她会害羞、
还会跟着会话状态换动作与表情的桌宠。自带 DS鲸鱼娘（8 组动作 + 44 个表情/道具），装完即用。

拖动定位 · 视线跟随 · 摸头互动 · 会话相位 · 右键换装 · 事件穿透
20 个互斥槽位 · 摸鱼随机演出 · 双半区插件，装完即用

是什么 · 快速上手 · 怎么玩 · 跟着会话走 · 设置 · 加一只宠物 · 目录结构 · 开发与验证 · 常见问题 · 交流群 · 许可

是什么

DSH 的 Web GUI 负责对话，而 dsh-pet-live2d 是挂在这块界面上的一只桌宠：她住在页面右下角，能拖、能缩、
跟着鼠标看，点她会有反应。更有意思的是她订阅 DSH 的真实事件（工具调用、审批请求、子代理、轮次结束……），
于是「在想」「在跑工具」「在等你批准」「出错了」这些状态会变成她的动作、表情和台词 —— 不用盯着日志看进度。

> 另有桌面端（dsh-live2d-pet-desktop/，Tauri 壳）：
> 把同一份宠物代码放进透明置顶窗口、逐像素穿透到壁纸。Windows x64 的单文件 exe
> 随插件包分发（装完在设置里选「桌面」）；macOS（Apple Silicon）的构建由 CI 产出，
> 尚未在真机验证 —— 平台支持与已知限制见它的 README。

快速上手

在 DSH 里点几下就装好了（不用命令行）：

1. 侧栏点「插件」→「添加插件」；
2. 包名框里输入 dsh-pet-live2d，回车或点「安装」；
3. 装完点「立即启用」—— 只关掉对话框的话，它会是"已安装但关闭"，插件不会被加载；
4. 重启一次 dsh web，她就站在那儿了（启用了 HMR 的 profile 会自己重组，重启最稳妥）。

> 官方插件页目前不支持自动更新：升级要在这里先卸载、再按上面装一次。

习惯命令行的话，等价的几条：

# 从 npm 装（推荐：插件和自带宠物一起下好）
dsh plugin --profile web add dsh-pet-live2d

# 或从仓库装（# 后面是 pnpm 的 path: 协议，注意那个斜杠）
dsh plugin --profile web add "github:A8Chann/dsh-pet-live2d#path:/dsh-live2d-pet"

# 或先克隆再装本地目录
git clone https://github.com/A8Chann/dsh-pet-live2d
dsh plugin --profile web add "link:./dsh-pet-live2d/dsh-live2d-pet"

> 仓库根目录没有 package.json：可安装的包在子目录 dsh-live2d-pet/ 里，所以从 Git 装必须带
> #path:/dsh-live2d-pet。从 npm 装不用管这些。

装完之后会发生什么：

1. 宠物随包自带。插件包里就带着那只鲸鱼娘，第一次运行时宿主半区把它复制进 %DSH_HOME%\pets\，
   重启 dsh web 就能看见。只在目标不存在时复制，或者内容与随包分发的那份逐字节相同时才同步升级 ——
   你自己改过的那份一个字都不会动。
2. Cubism Core 不用手动装。live2dcubismcore.min.js 是 Live2D 株式会社的专有运行时，不能随插件分发；
   插件第一次用到它时去 Live2D 官方 CDN
   取一份（校验过再发出去），缓存到 %DSH_HOME%\pets\.runtime\，之后离线也能用。
3. 重启 dsh web。bundle 不做热重载，重启之后她就站在那儿了。

dsh plugin --profile web update dsh-pet-live2d   # 升级（宠物默认值会一起同步）
dsh plugin --profile web remove dsh-pet-live2d   # 卸载（%DSH_HOME%\pets\ 里的宠物不会被删）

怎么玩

• 拖动 / 缩放：拖到哪就是哪，大小从 160px 到 760px（默认 300px，右键面板底部的滑杆调），
  两者都记在 localStorage，重启还在。
• 右键面板：呼出「动作」「装扮」两个页签 + 大小滑杆 + 「归位」。面板跟随 DSH 的浅色 / 深色主题。
• 跟着鼠标看：视线和头部跟着指针走，移开（或窗口失焦）自动回正。
• 点击反应：点头部才挥锤撒娇，点身上其它地方只出气泡 —— 判定读的是模型自己的几何
  （当前帧变形后的三角面 + 作者在 cdi3 里写的部件名），不是画出来的区域。
• 事件穿透：只有角色剪影吃鼠标事件，方形画布的透明处穿到底下的页面，不挡 DSH 的 UI。
• 都会自己收尾：动作、定格、表情到点全部回到初始待机，不会卡住。
• 待机摸鱼：静置一会儿会自己随机演一段（不会演「点击」「出错」这类专属动作）。

三个互动各自可开关，反应也能改；共用的三句台词在设置页的「气泡」卡里。

右键呼出面板：「动作 8」是模型自带的动作，「装扮 20」是 20 个互斥槽位；底部是大小滑杆和「归位」

同样的她，换一套槽位就是另一个样子（44 个表情/道具里的一小部分）

跟着会话走

她订阅的是 DSH 的真实事件，不是猜的：

• 事件来源：agent/status、tools/pre-execute 与 tools/post-execute、approval/request、
  user-questions/request、subagent/start 与 subagent/end、agent/inbox/inserted、
  agent/turn-stopping、agent/error。
• 相位是「接管」不是「叠加」：相位点名的槽位按抽签换上，没点名的槽位让位收回；
  装扮槽永远归你；会话结束后你原来的样子回来（让位不是删除）。
• 每个相位的动作、表情、台词都能改，也能给每个槽位配权重和「同时 / 前提」关系。

设置

完整的配置都在 DSH 设置页 → 桌宠 那一节（卡片 / 药丸 / 权重条，浅色深色都能用）；
侧栏「插件」→ 本插件 的卡片上另有一节常用开关（气泡 / 提示音 / 三个互动 / 记住装扮）、
四根手感滑杆和「显示位置」，写的是同一份配置。

• 摸鱼：每个槽位一张条目表，可增删、带权重 —— 权重就是「多久动一次」。
• 会话相位：八个相位两列概览、点开一个再编辑台词与动作池；动作改动只在真的编辑时才落盘。
• 关系：条目之间配「同时」（一起点亮）与「前提」（必须先处于那个状态才播得出来）。
• 互动：摸头 / 摸尾巴 / 转圈各自的候选反应，行尾标明来历（宠物默认 / 内置默认 / 已改过）。
• 气泡：会话台词在相位里改，互动等其他台词在气泡卡里改（一组用 | 分隔多个变体）；位置、停留时长及总开关也在气泡卡。
• 手感：拖动、缩放、注视、点击、摸鱼开关等。
• 会话提示音：独立卡片控制总开关和音量（拖滑杆即试听）；每相位可静音、试听或上传 MP3 / WAV / OGG（按宠物分别保存），移除上传即可回到宠物默认音符。

完整的设置说明、20 个槽位的选项表、宠物契约与 HTTP 接口见
dsh-live2d-pet/README.md。

加一只宠物

宠物放在 %DSH_HOME%\pets\\，最小结构是 pet.json + 一个 *.model3.json +
model\、textures\、motions\、expressions\（catalog.json 可选，只影响显示名）。

pet.json 里 live2d.model 指向 model3.json，插件启动时从模型里读出全部动作与表情，所以
换模型不用改插件代码。

> ⚠️ 路径片段只允许 [A-Za-z0-9._-]，中文文件名会让整个宠物加载失败 —— 用
> tools/build-pet.mjs 转换（仓库里随包的宠物就是 model-packs/DS鼠控版 过一遍它的产物）。

槽位 / 池子 / 相位 / 动作语义的完整契约见
dsh-live2d-pet/README.md#做一只自己的宠物。

目录结构

dsh-live2d-pet/          插件包本身（就是要装的东西）
lib/                     宿主半区 + 浏览器半区 + vendor 分包
src/                     vendor 分包入口（esbuild）
docs/                    图片（门面横幅 / 面板实拍 / 清晰度对比 / 交流群二维码）
pets/
ds-whale-girl/          随包自带的宠物（首次运行自动复制进 %DSH_HOME%\pets）
CHANGELOG.md             用户可见的变化（市场页与 Release 读它）
dsh-live2d-pet-desktop/  桌面端壳（Tauri，M0）：同一份宠物代码放进透明置顶窗
tools/
build-pet.mjs            模型源包 -> 可安装宠物包
browser-test/            无头 Edge + CDP 的端到端回归测试
make-release.mjs         按 CHANGELOG 生成 GitHub Release
verify-npm-package.mjs   发布前校验 npm 包里的内容
market-pr.mjs            给 awesome-dsh-plugin 提收录 PR
model-packs/               宠物构建用的源模型包（DS鼠控版）
.dsh/skills/               工程记录，按主题归位；硬规则与索引见 AGENTS.md

开发与验证

插件是双半区包，没有前端构建步骤：lib/index.js 是宿主半区（宠物发现 / 引用闭包资产路由 /
运行时分发），lib/client.js 是手写的 __ModuleLoader__ 工厂，改完重启 dsh web 即可生效。
只有 vendor 分包需要构建（改动 src/vendor-entry.ts，或升级 pixi.js / 引擎时）：

cd dsh-live2d-pet
npm install
npm run build:vendor

回归测试在 tools/browser-test/：4 个纯 Node 的测试 + 20 个无头 Edge + CDP 的 driver，
在真实 WebGL 里跑插件，覆盖状态机、点击剪影、注视、相位映射、渲染倍率、动作语义、装扮合成、
设置界面等契约。断言一律读引擎在帧内写进模型的参数值，不做截图逐像素 / 哈希比对：

cd tools/browser-test
npm install          # 提供 React UMD
npm run suite        # 起测试服 -> 并发跑全部 driver -> 输出 PASS/FAIL 表

> 设置界面只挂在 DSH 设置页那一节里，所以 driver 用 window.__pluginSections["pet-settings"]
> 把那一节渲染进探针容器（#dsh-settings-probe）再操作它，见 cdp-gaze.mjs 里的 openSettings()。
> 官方「插件」页那一节同理，键是包名（__pluginSections["dsh-pet-live2d"]，容器
> #plugin-page-probe），见 cdp-plugin-page.mjs。宿主侧的展示元信息（标题 / 描述 / 图标）
> 由 dsh-live2d-pet-desktop/tools/probe-plugin-page-meta.mjs 用宿主自己的读取器验。
> drivers/ 下是开发过程中用过的一次性诊断脚本，留作参考，不在回归套件里。

> 工程记录不写在 README 里：踩坑、帧序、测量陷阱、验证写法按主题放在
> .dsh/skills/（cubism-engine / pet-domain-model / client-state /
> verification-signals / browser-cdp / docs-and-workflow），硬规则与索引见
> AGENTS.md；用户可见的变化写 CHANGELOG。

常见问题

交流群

🐟 大肥鱼 pet-live2d 交流群
QQ 群号 974641848
装不上、模型不对劲、想投稿自己的宠物 —— 都欢迎进群说

更新日志

用户可见的变化都写在 dsh-live2d-pet/CHANGELOG.md
（市场页与 GitHub Release 读的就是它）。当前 v2.3.4：摸尾巴终于点得到了 ——
尾巴的判定从「名字里带尾/鳍/翅的 15 个部件」按贴图收窄到真正的尾鳍五块 drawable，
可点区域也跟着摆动走。

许可

两类内容，两套许可 —— 完整说明见 NOTICE.md。

⚠️ 可以分享、改编；必须署名、不得商用、改编后须以同一协议分发。
商业使用需分别取得上述所有人的授权 —— 氵六青同意转载不等于可以商用。

喜欢这只桌宠？点个 Star，她会开心。 ⭐

报告 Bug · 请求功能 · Releases · 更新日志 · 交流群