dsh-live2d-pet

dsh-pet-live2d

给 DSH（DeepSeek Harness）Web GUI 用的 Live2D 桌宠插件：一只可以拖动、跟着鼠标看、 点她会害羞、还会跟着会话状态换动作的桌宠。

自带 DS鲸鱼娘（8 组动作 + 44 个表情/道具），开箱即用。

宠物会跟着插件一起更新：随包的那只（以及它的默认设置：台词、互动反应、

会话相位、摸鱼槽位）在插件升级时自动同步到 %DSH_HOME%\pets\ds-whale-girl。

你自己改过的那份不会被覆盖（判定是内容指纹，改过就一个字都不碰），

想拿回随包版本就把目录删掉、重启 dsh web，它会重新装一份。更新日志见 CHANGELOG.md。

功能

• 拖动 / 缩放：位置和大小记在 localStorage，重启还在
• 跟随鼠标：视线和头部跟着指针，移开（或窗口失焦）自动回正
• 点击反应：点头部才挥锤撒娇，点身上其它地方只出气泡
• 事件穿透：只有角色剪影吃鼠标事件，方形画布的透明处穿透到底下的页面，不挡 DSH 的 UI
• 跟着会话走：订阅 DSH 的真实事件（tools/* 等），思考/工具/等待/完成/出错换动作与表情，

长任务持续播放对应动画

• 待机摸鱼：静置一会儿自己演一段（不会演「点击」「出错」这类专属动作）
• 都会自己收尾：动作、定格、表情到点全部回到初始待机，不会卡住
• 全都可配：20 个互斥槽位（装扮 + 表情），每个槽位一张可增删、带权重的条目表，

条目之间还能配「同时 / 前提」关系；会话相位是同一套池子机制

安装

在 DSH 的「插件」页里装（不用命令行，推荐）

1. 侧栏点「插件」；
2. 点「添加插件」，在包名框里输入 dsh-pet-live2d，回车或点「安装」

（输入框下面可展开「插件安装引导和示例」；没手动指定安装源时，Host 会先探测官方源与 国内镜像哪个快，再从那一个装）；

1. 装完点「立即启用」—— 只关掉对话框的话，它会是"已安装但关闭"，插件不会被加载；
2. 重启一次 `dsh web`：插件在启动时加载，客户端 bundle 也不做热重载

（启用了 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"

装到哪个 profile？ 取决于你在哪里用它：

- 浏览器里跑的 dsh web ⇒ `--profile web`（上面几条都是这个）；

- DeepSeek Harness 官方桌面客户端 ⇒ 它用的是 `--profile desktop`，例如

dsh plugin --profile desktop add dsh-pet-live2d。

装完重启一次（插件在启动时加载，客户端 bundle 也不做热重载）。

Cubism Core：不用手动装

live2dcubismcore.min.js 是 Live2D 株式会社的专有运行时，不能随插件分发 —— 但你也不 用自己去找：插件第一次用到它时，宿主半区会去 Live2D 官方 CDN 取一份 （校验过再发出去），并缓存到 %DSH_HOME%\pets.runtime\live2dcubismcore.min.js，之后离线也能用。

只有当这台机器访问不了外网时，才需要手动下载 Cubism SDK for Web、把 Core/live2dcubismcore.min.js 放到上面那个路径。

宠物：随包自带

插件包里就带着一只可用的宠物（pets/ds-whale-girl/，CC BY-NC-SA 4.0）。第一次运行时 宿主半区会把它复制进 `%DSH_HOME%\pets`，所以装完插件、重启 dsh web 就能看见。 升级时原封不动的随包宠物会同步新版默认值（包括提示音）；你自己改过的宠物目录优先，不会被覆盖。

怎么用

• 右键点宠物 呼出面板：「动作」「装扮」两个页签，底部是大小滑杆和「归位」。

平时画面上没有常驻 UI。

• 改配置 两个入口：DSH 设置页 → 桌宠（完整设置），或侧栏「插件」→ 本插件（常用开关）。

设置说明

官方「插件」页上的那一节

侧栏点「插件」，「已安装」里那张带图标的卡片就是本插件。点进详情，描述与插件行之间是它 自己的配置区：

• 常用开关：气泡、会话提示音、摸头 / 摸尾巴 / 转圈、跨启动记住装扮；
• 四根滑杆：注视满偏、收回倍数、静置多久开始摸鱼、提示音音量；
• 显示位置：自动 / 页面内 / 桌面。

改的是与设置页同一份配置（%DSH_HOME%\pet-settings.json），两边随时一致。相位台词、 池子编辑器、装扮与台词文案仍在 设置 → 桌宠 里改 —— 那里才是完整设置。

摸鱼：每个槽位一张条目表

摸鱼 = 静置一会儿之后，宠物自己换个样子。每个槽位各掷一次骰子（不是"这次只动一两个"）， 条目上的权重就是"多久动一次"。

• 一张表里的条目可以增删：＋ 名字 是虚线药丸，行尾 × 删掉。

宠物给的那套只是建议，你加进来的运行时真的会抽到。

• 摸鱼默认盯宠物声明的那几个槽位（这只宠物是七个：右手 / 左手 / 情绪 / 脸红 / 嘴部 /

眼部 / 自拍，写在 pet.json 的 live2d.fidgetSlots 里），其余槽位在卡片底部点一下就 加进来（＋ 槽位）。

• 「默认」＝回到默认（把这个槽位清空）。默认 10 : 脸红 1 = 大约每 11 次摸鱼脸红一次、

其余时间回到没有。想让某个槽位完全不动，把它的条目删光或权重归 0。

会话相位：动作、气泡与提示音放在一起

设置页「会话提示音」卡统一控制开关和音量；紧邻的「会话相位」卡将八个相位排成宽屏两列、窄屏单列的概览，默认收起，点开一个相位后才显示它的「气泡与提示音」「动作槽位」编辑区。行头「重置动作」只恢复动作槽位；台词用自己的「恢复默认」按钮，提示音可单独静音、试听或上传文件。动作池子仍是"槽位 → 条目表"，机制和摸鱼一样。宠物跟着 DSH 的真实事件换相位：

相位 · 什么时候 · 这只宠物演什么 thinking · 模型在想 / 刚开工 · 抬头看 tool · 调工具（detail 带工具名） · 写本本 + 流汗 waiting · 有操作等你批准 · 问号 asking · 它问了你一个问题、在等你回答 · 举手 + 问号 helper · 起了子代理（一段长活） · 喵喵手 + 调皮 queued · 你发的话排队了（它还在忙） · 感叹号（短促一下） done · 这一轮说完（庆祝 3.5 秒） · 开心 + 情绪花花 failed · 出错了 · 大哭 + 流汗

来源是 agent/status、tools/pre-execute|post-execute、approval/request、 user-questions/request、subagent/start|end、agent/inbox/inserted、 agent/turn-stopping、agent/error —— 按主题折成上面这几个相位。

相位表一开始就列出全部相位，显示的是有效池子：

行头概览 · 含义 · 恢复方式 动作默认 / 已改 · 动作槽位沿用宠物默认 / 用你的池子 · 动作改过才显示「重置动作」，只重置动作池 台词默认 / 已改 · 该相位台词是否被你修改 · 展开后点「恢复默认」 音频宠物默认 / 已上传 / 已静音 / 未配置 · 宠物音符、当前宠物的上传文件、单独静音或未声明 · 展开后上传、移除上传或勾选提示音

改动只在真的编辑时才落盘，所以"看一眼"不会留下覆盖 —— 以后宠物更新了默认值， 没改过的相位照样吃得到。

相位是"接管"，不是"叠加"：会话一开始，宠物换相位那一套样子 ——

• 相位点名的槽位用它抽到的（thinking 就是头顶鲸 + 画笔）；
• 相位没点名的槽位一律让位（收回）：你手选的掏出手机、爱心眼、自拍不会在整场

会话里一直挂着。挂在槽位上的动作（掏出手机是定格动作）也会跟着交还身体，手放下来；

• 装扮槽永远归你：眼镜 / 发饰 / 魔爪 / 巴菲 / 桌布 / 手机换色 会话不碰；
• 会话进行中想改也能改：手点一下会临时盖过相位的那一格（这场会话里有效）；
• 会话结束后，你原来的样子回来（让位不是删除）。

右键面板的「装扮」页签跟着相位走 —— 会话中它显示的是相位抽到的，不是你上次手选的。

提示音：完成 / 失败 / 需要你处理

在 DSH 设置页 → 桌宠 → 会话提示音 打开总开关并调节音量（默认关闭）；到紧邻的「会话相位」卡点开相位，在「提示音」处选 上传音频。支持 MP3 / WAV / OGG，单文件最多 1 MB；每只宠物、每个相位分别保存到 $DSH_HOME/pet-sounds/，换宠物不会沿用另一只的上传音频。「移除上传」恢复宠物默认音符，静音勾选框也能关闭已上传音频；上传成功会解除该相位先前的静音，但不会替你打开总开关。上传音频比宠物音符优先，两个窗口最多 3 秒同步一次。

上传的文件是按容器结构校验的（不是看扩展名，也不是只看开头几个字节）：MP3 要有合法的帧头、Ogg 要过页校验、WAV 的 fmt/data 块要自洽 —— 网页端与桌面端用的是同一套判据（同一份合同向量在两边测试里跑）。长度字段写成 0 或 0xFFFFFFFF 的"流式" WAV 也收；明显不是音频、或被截断的文件会在上传时就报错，不会写进 $DSH_HOME/pet-sounds/。

旁边的 「试听」 让你不必等会话真的跑到那个相位：点一下直接听这一相位会响的那段声音（有上传听上传，否则听宠物/内置音符）。它故意不受总开关与单相位静音影响 —— 默认总开关就是关的，跟着它走等于"点了没反应"；音量用当前提示音音量，音量为 0 时按 0.35 试听。没有任何音源（未配置、也没上传）的相位，按钮是灰的。

拖动「会话提示音」卡里的音量滑杆也会即时试听一小段（防抖：停手才响，响的是最终音量；这只宠物一个音源都没有时只给数字反馈）。音量滑杆这条按真实音量响 —— 拖到 0 就是静音，不会像「试听」按钮那样兜底发声，否则你听到的就不是"0 有多大声"了。

未上传时，内置宠物的 done、failed、waiting（待批准）、asking（待回答）各有一段合成短音；别的宠物可在 pet.json 的 live2d.sounds 声明自己的音符，空数组表示该相位不响，未声明整个字段的旧宠物沿用内置四声。音量拉到 0 会静音；首次播放前浏览器需要你点击一次页面解锁音频。初次连接的状态快照和重复状态不会响；若两个窗口同时接收相位，两边都开启时可能各响一次。

互动：摸头 / 摸尾巴 / 转圈

点她身上会有反应，判定用的是模型自己的几何，不是画出来的区域：

互动 · 怎么触发 · 默认反应 摸头 · 点在头部（含头发、耳朵 —— 宿主读 cdi3 里作者的部件命名认出来的 21 个部件） · 重锤出击 / 问号 / 星星眼 随机一个，不脸红 摸尾巴 · 点在尾巴/翅膀上（狐狸尾 / 猫尾 / 狼尾 / 大翅膀…15 个部件） · 吐魂 / 问号 随机一个 转圈转晕 · 鼠标绕着角色转圈：默认 2 圈、1.6 秒内 · 演「晕晕」

• 摸头/摸尾巴按三角面判定：圆顶带耳朵尖的头部轮廓、尾巴的边缘都对得上，不是方框。

顶点是当前帧变形后的，所以头歪着、身体摆着也准。

• 尾巴只认"鲸鱼尾鳍"那一块：这只模型有 16 块 drawable 的名字里带"尾/翅/翼"，但其中

11 块是可选配件（狐狸尾 / 猫尾 / 狼尾 / 天使翅膀…）的几何、一直留在原地、横跨全身。 全算成尾巴的话"点到哪儿都是尾巴"，而摸头又优先，可见的尾鳍反而摸不到。所以尾巴是按 贴图认的：texture_00.png 上鲸鱼尾鳍那一块对应的 5 块 drawable（都属部件 尾巴(蒙皮)）。

• 可点区域跟着尾巴动：决定事件归谁的那层轮廓是开机抓一次的，尾鳍摆动时会摆出去 ——

现在尾巴有一块实时跟随的可点矩形并进轮廓里，所以摆到哪儿都点得到。

• 摸头优先于摸尾巴：尾巴判定收紧之后两者基本不再重叠，重叠处仍然算摸头。
• 尾巴/翅膀是可选配件：没戴的时候它们的几何是退化的，"摸尾巴"就是没反应 ——

这是对的，不是坏了。戴上尾巴（装扮槽）之后才摸得到。

• 转圈看的是累计转角（不是位置绕了几圈），所以贴着角色转小圈、远远转大圈都算。
• 三个互动各自可开关，反应也能改（见下）。共用的三句台词在「气泡」设置里。

上表那三组是默认反应，来源分两层：宠物 pet.json 里声明了就用它的；**没声明就用

插件内置的这几个**（重锤出击 / 问号 / 星星眼、吐魂 / 问号、晕晕）—— 自己做的宠物不写