본문으로 건너뛰기
A

dsh-pet-live2d

a8chann/dsh-pet-live2d

Live2D 데스크톱 펫 플러그인: DSH 웹 GUI에 드래그할 수 있고 마우스를 따라가며 동작과 표정을 바꿀 수 있는 Live2D 펫을 추가합니다.

설치

dsh plugin --profile web add github:a8chann/dsh-pet-live2d

README

dsh-pet-live2d

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

大肥鱼 pet-live2d —— Give your AI agent a face.

Release npm downloads Stars Forks dshfind

DSH platform Cubism 5 License Last commit

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

是什么

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

能力原生 DSH Web GUI装了 dsh-pet-live2d
界面陪伴无桌宠常驻页面，可拖动 / 缩放，位置和大小记在 localStorage
状态可视化文字与状态点8 个会话相位，各有一套动作 + 表情 + 台词，长任务持续播放
互动无摸头 / 摸尾巴 / 绕着转圈都有反应，按模型的三角面判定，不是方框
换装无20 个互斥槽位、44 个表情/道具，右键面板现场换，装扮跨会话保留
挡不挡 UI—只有角色剪影吃鼠标事件，方形画布的透明处穿透到底下页面
打扰程度—静置才会自己演一段；平时画面上没有任何常驻 UI，鼠标划过也不显示

另有实验性的桌面端（dsh-live2d-pet-desktop/，Tauri 壳，M0 已在 Windows 实测通过）： 把同一份宠物代码放进透明置顶窗口、逐像素穿透到壁纸。还没做打包，想尝鲜直接看它的 README。

快速上手

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

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

# 3. 或先克隆再装本地目录
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>= 0.1.5-rc.1，装在 web profile 上
浏览器支持 WebGL 的现代浏览器（无头 Edge / Chrome 也跑得动，见回归测试）
操作系统跟着 DSH 走：Windows / macOS / Linux 是同一套 Web 端代码
网络只在第一次取 Cubism Core 时需要外网；取不到就按 FAQ 手动放一份
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。
  • 都会自己收尾：动作、定格、表情到点全部回到初始待机，不会卡住。
  • 待机摸鱼：静置一会儿会自己随机演一段（不会演「点击」「出错」这类专属动作）。
互动怎么触发默认反应
摸头点在头部（含头发、耳朵等 21 个部件）重锤出击 / 问号 / 星星眼 随机一个，不脸红
摸尾巴点在看得见的鲸鱼尾鳍上（按贴图认那 5 块 drawable，可点区域跟着尾鳍摆动走）吐魂 / 问号 随机一个
转圈转晕鼠标绕着她转圈（默认 2 圈、1.6 秒内）演「晕晕」

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

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

六种造型：默认待机 / 爱心眼 / 星星眼吐舌 / 调皮猫猫手 / 重锤出击 / 挤番茄酱
同样的她，换一套槽位就是另一个样子（44 个表情/道具里的一小部分）

跟着会话走

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

相位thinkingtoolwaitingaskinghelperqueueddonefailed
什么时候模型在想 / 刚开工在调工具有操作等你批准它问了你一句、等你回答起了子代理你发的话排队了这一轮说完出错了
  • 事件来源：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 设置页 → 桌宠 那一节（卡片 / 药丸 / 权重条，浅色深色都能用）：

  • 摸鱼：每个槽位一张条目表，可增删、带权重 —— 权重就是「多久动一次」。
  • 会话相位：同一套池子机制，每个相位一组「槽位 → 条目表」，改动只在真的编辑时才落盘。
  • 关系：条目之间配「同时」（一起点亮）与「前提」（必须先处于那个状态才播得出来）。
  • 互动：摸头 / 摸尾巴 / 转圈各自的候选反应，行尾标明来历（宠物默认 / 内置默认 / 已改过）。
  • 气泡：所有台词逐条可改（一组用 | 分隔多个变体），位置、停留时长可调，也能整体关掉。
  • 手感：拖动、缩放、注视、点击、摸鱼开关等。

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

加一只宠物

宠物放在 %DSH_HOME%\pets\<id>\，最小结构是 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/：1 个纯 Node 的宿主契约 + 18 个无头 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()。 drivers/ 下是开发过程中用过的一次性诊断脚本，留作参考，不在回归套件里。

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

常见问题

问题答案
装完重启了，没看见宠物？看宿主日志里有没有 [live2d-pet]，并确认 %DSH_HOME%\pets\ds-whale-girl\ 存在。目录被删干净之后重启会重装一份。
一直转圈 / 拿不到运行时？这台机器访问不了 Live2D 官方 CDN。手动下载 Cubism SDK for Web，把 Core/live2dcubismcore.min.js 放到 %DSH_HOME%\pets\.runtime\。
她挡住 DSH 的按钮了？不会：只有剪影吃鼠标事件，透明处穿透到底下页面。真挡住了就拖走，或右键 →「归位」。
我改过 pet.json，升级会覆盖吗？不会。同步按内容指纹判定，逐字节等于随包那份才更新；想拿回随包版本，删掉目录再重启。
自己做的宠物加载失败？先查文件名：路径片段只允许 [A-Za-z0-9._-]，中文会让整个宠物加载不了；再照 pet.json 契约逐项对一遍。
支持别的模型吗？支持，放 %DSH_HOME%\pets\<id>\ 即可，动作与表情从 *.model3.json 读，插件代码不用改。
插件包为什么有好几 MB？里面装着那只宠物（moc3 + 贴图 + 8 组动作 + 44 个表情）。想换成自己的，替换 pets/ 就行。

交流群

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

大肥鱼 pet-live2d 交流群二维码（群号 974641848）

更新日志

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

许可

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

内容许可
插件代码、tools/MIT — 见 LICENSE
pixi.js / untitled-pixi-live2d-engineMIT（打包进 lib/live2d-vendor.js）
dsh-live2d-pet/pets/、model-packs/ 与 docs/ 里的模型、贴图与截图CC BY-NC-SA 4.0 — 署名 · 非商业 · 相同方式共享
Live2D Cubism CoreLive2D 株式会社专有，不在本仓库内；缺失时插件从官方 CDN 取一份并缓存到本地
版权所有人内容
上善无形鲸鱼娘角色形象原作，原创 OC「溟月」
ZipZipPipeDeepSeek 女仆鲸鱼娘二次设计
氵六青本仓库所用 Live2D 模型

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

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

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

관련 플러그인

Z

dsh-web-ui (dsh-pet)

zhu1090093659/dsh-web-ui

7.9k8일 전재미로 즐기기Apache-2.0
P

dsh-pet (dsh-pet)

pc2005-cloud/dsh-pet

8255일 전재미로 즐기기MIT
N

dsh-ads

nagi-ovo/dsh-ads

6363일 전재미로 즐기기BSD-3-Clause
D

dsh-ads

dsh-external/dsh-ads

626지난달재미로 즐기기BSD-3-Clause