ankesu/dsh-live2d-pet

dsh-live2d-pet

一个用于 DeepSeek Harness 的 Live2D 伴侣宠物——在 Web UI 中将 Cubism 模型渲染为浮动伴侣，支持状态驱动的表情、鼠标跟踪、拖拽重新定位，以及顶栏切换按钮。

DSH 桌宠 Live2D 插件：在 Web UI 里渲染一个 Cubism 模型作为浮动桌宠，支持状态联动表情、鼠标跟随、拖拽摆位、顶栏一键开关。

🐱 Haru/ 人型（默认分支）

preview

The bundled official Haru sample model (Live2D Inc.):

附带官方 Haru 示例模型（© Live2D Inc.）：

haru sample

🐱 Tororo Cat pets / 白猫宠物（分支）

The official Tororo & Hijiki cat sample models
(Live2D Inc.) run as
pets on the feat/tororo
branch — cats with ear/tail/paw parameters, parameter-snapshot expressions
(no exp3 files needed), and the sample's Idle/Tap motions:

官方 Tororo & Hijiki 猫示例模型（© Live2D Inc.）在
feat/tororo
分支上作为宠物运行——猫有耳朵/尾巴/爪子参数、参数快照表情（无需 exp3 文件）、
以及自带 Idle/Tap 动作：

tororo cat pet

🐱 Hijiki Cat pets / 黑猫宠物（分支）

hijiki cat pet

Switch to a branch for cat pets: / 切到分支即可用猫宠物：
- White cat Tororo: git checkout feat/tororo → pnpm build → configure model: tororo/tororo.model3.json
- Black cat Hijiki: git checkout feat/hijiki → pnpm build → configure model: hijiki/hijiki.model3.json
(both branches use the same parameter-snapshot client; only the model path differs)

Table of Contents / 目录

- Features / 功能
- Cat pets (branch) / 猫宠物（分支）
- Install / 安装
- Enable / 启用（必读）
- Configuration / 配置
- State → Expression map / 状态表情映射
- Debug handles / 调试句柄
- Bring your own model / 换自己的模型
- Architecture & pitfalls / 架构与排雷
- Development / 开发
- License / 许可

Features / 功能

| | English | 中文 |
|---|---|---|
| 🐳 Real Live2D | Powered by pixi-live2d-display (Cubism 4), rendered on a transparent floating canvas | 基于 pixi-live2d-display（Cubism 4）渲染，透明浮动画布 |
| 👀 Mouse tracking | Head turns and gaze follow your cursor (ParamAngleX/Y, ParamEyeBallX/Y); the iris is written every frame so expression snapshots can't clobber it | 头部与视线跟随鼠标；瞳孔每帧写入，表情快照覆盖不了 |
| 😊 State-driven expressions | The model's .exp3.json expressions map to harness activity states (idle/waiting/thinking/tool/done/failed/sleep/…) plus hover & drag | 表情按 AI 活动状态切换（idle/waiting/thinking/tool/done/failed/sleep…）+ hover/拖拽反馈 |
| 🎬 待机动作 + 小动作 | 模型常驻待机动作；空闲时随机播放点击动作作为待机小动作 | 常驻待机动作；空闲时随机播小动作（发呆/挠头） |
| 🎛️ 配置驱动几何 | 大小 / 位置 / 偏移均来自 cordis.patch.yml —— 无需重新构建即可调整 | 大小/位置/偏移全在 cordis.patch.yml 配置，改配置不用重编译 |
| 🖱️ 拖拽重定位 | 可将宠物拖到任意位置；偏移持久化在 localStorage 中（带视口合理性钳制，防止跑出屏幕的 bug） | 可拖拽到任意位置，偏移持久化（带防怼出屏幕的钳制） |
| 💾 开关按钮与持久化 | 一个 ✨ 顶栏按钮（位于 dsh-emoji-wallet 💰 按钮旁边）即时显示/隐藏宠物；状态在刷新与重启后保留 | 顶栏 ✨ 按钮（dsh-emoji-wallet 钱包 💰 旁边）一键开关，状态跨刷新/重启保留 |
| 🔗 会话状态联动 | 监听 DSH 对话会话 —— 深度思考 / 睡觉 / 庆祝由时间驱动 | 监听 DSH 会话——深思考 / 睡觉 / 庆祝等按时间驱动 |

✨ 开关按钮位于会话头部，紧挨着来自 dsh-emoji-wallet 的 💰 钱包按钮
（一个可选的伴生插件 —— 没有它宠物也能正常工作；只是钱包恰好位于同一工具行中）：

顶栏 ✨ 开关按钮（会话头部，dsh-emoji-wallet
钱包 💰 旁边——钱包是可选伴生插件，不装它宠物也完全正常，只是同一个顶栏行里挨着）：

toggle button

安装 / Install

以下所有安装方式均已在干净 profile 中端到端验证（2026-08-28）：
haru 来自 npm registry，各猫分支来自 GitHub —— pnpm install
会自动运行 prepare 脚本构建 lib/client.js，且
随附的 cordis.patch.yml 已指向正确的模型。零额外配置。

以下安装方式均已在干净 profile 中完整实测（2026-08-28）：haru 走 npm registry，
黑白猫走 GitHub 分支——pnpm install 会自动执行 prepare 构建 lib/client.js，
包内 cordis.patch.yml 已默认指向对应模型，零额外配置。

方案 A —— npm registry（Haru，默认分支）/ npm 源安装（Haru 人型，默认）

install / 安装
dsh plugin --profile  add dsh-live2d-pet

or, in the profile dir directly / 或直接在 profile 目录里
cd ~/.dsh/profiles/
pnpm add dsh-live2d-pet

- 安装最新发布的 dsh-live2d-pet（haru 模型）。已验证：0.1.2。
- 安装最新发布版 dsh-live2d-pet（haru 模型）。已验证：0.1.2。
- ⚠️ 如果你之前安装过旧版本，pnpm add 可能会保留过期的 lockfile 条目
（例如 0.1.1）。请固定版本以强制更新：
pnpm add dsh-live2d-pet@0.1.2（或删除 pnpm-lock.yaml 后重新安装）。
- ⚠️ 若之前装过旧版，pnpm add 可能沿用旧 lock 条目（如 0.1.1）。指定版本强制更新：
pnpm add dsh-live2d-pet@0.1.2（或删掉 pnpm-lock.yaml 重装）。

方案 B —— GitHub 分支：白猫 Tororo / Git 分支：白猫 Tororo

cd ~/.dsh/profiles/
pnpm add "git+https://github.com/ankesu/dsh-live2d-pet.git#feat/tororo"

- 白猫 Tororo（猫客户端，PARAM_ 参数，参数快照式表情）。
已验证：安装 + 构建 + 补丁 → tororo 模型，一切正常。
- 白猫 Tororo（猫版 client，PARAM_ 参数 + 参数快照表情）。已验证：安装/构建/patch 全部正常。

Option C — GitHub branch: black cat Hijiki / Git 分支：黑猫 Hijiki

cd ~/.dsh/profiles/
pnpm add "git+https://github.com/ankesu/dsh-live2d-pet.git#feat/hijiki"

- Black cat Hijiki (same cat client, different model path). Verified.
- 黑猫 Hijiki（同一猫版 client，不同模型路径）。已验证。

Option D — GitHub branch: main (Haru) / Git 分支：main（Haru）

cd ~/.dsh/profiles/
pnpm add "git+https://github.com/ankesu/dsh-live2d-pet.git#main"

- Same as the npm registry build, from source. Verified.
- 与 npm registry 版相同，从源码装。已验证。

Notes for git-branch installs / Git 分支安装注意事项

1. Proxy — GitHub fetches can stall without one. If installs hang, configure
your proxy (e.g. npm config set proxy http://127.0.0.1:7897 / https-proxy),
or set HTTP_PROXY/HTTPS_PROXY env vars for the install command.
Git 拉取 GitHub 可能卡住。卡住时配代理（如 npm config set proxy http://127.0.0.1:7897
与 https-proxy），或在安装命令前设 HTTP_PROXY/HTTPS_PROXY 环境变量。
2. pnpm allowBuilds — pnpm blocks the prepare build script by default
(supply-chain protection). If you see ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED,
add the exact line it prints to pnpm-workspace.yaml under allowBuilds:.
pnpm 默认拦截 prepare 构建脚本（供应链保护）。若报
ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED，把报错打印的那一行加到
pnpm-workspace.yaml 的 allowBuilds: 下即可。
3. Enable the pet — after install, the pet does not show until enabled:
click the ✨ header button or run localStorage.setItem('dsh-live2d-pet','1')
in the browser console, then reload.
装完后宠物不会自动显示——点顶栏 ✨ 按钮或在浏览器 Console 执行
localStorage.setItem('dsh-live2d-pet','1')，然后刷新页面。

Use a different profile by changing --profile  (e.g. test).

换成自己的 profile 只需改 --profile （例如测试端 test）。

Enable / 启用（必读）

⚠️ The model does NOT appear automatically after install. You must enable
it first — either click the ✨ button in the session header, or run one line
in the browser console.
⚠️ 装完不会自动显示！ 必须先启用——点顶栏 ✨ 按钮，或在浏览器控制台执行下面这行：

localStorage.setItem('dsh-live2d-pet', '1')

1. Open the DSH web page (the profile where you installed the plugin)
2. Press F12 → Console tab
3. Paste localStorage.setItem('dsh-live2d-pet', '1') and press Enter
4. Reload the page (F5)

The pet then floats at the anchor position (default: bottom-right / above the
composer). The setting persists across refreshes and server restarts — you only
do this once per browser.

启用后宠物出现在锚定位置（默认：右下/输入框上方）。设置跨刷新和重启保留，每个浏览器只需设置一次。

To disable / 关闭：

localStorage.setItem('dsh-live2d-pet', '0')

Configuration / 配置

cordis.patch.yml (in the plugin package):

- insert:
- id: live2d-pet
name: dsh-live2d-pet
config:
model: haru/haru_greeter_t03.model3.json  # path under assets/live2d/
size: 320                                  # canvas size, px
right: 24                                  # 距右边缘距离，px
bottom: 100                                # 距底边缘距离，px
offsetX: 0                                 # 额外水平偏移，px
offsetY: 0                                 # 额外垂直偏移，px

| 键 | 含义 | 默认值 |
|---|---|---|
| model | assets/live2d/ 下 .model3.json 的路径 | haru/haru_greeter_t03.model3.json |
| size | 画布尺寸，单位 px（模型按高度缩放适配） | 320 |
| right | 未锚定时距右边缘的距离 | 24 |
| bottom | 未锚定时距底边缘的距离 | 20 |
| offsetX / offsetY | 在锚定位置之上额外施加的偏移（用于微调） | 0 |

宠物每帧锚定到聊天输入框（[data-composer-seat]）并跟随内部滚动；right/bottom
只是兜底位置。微调用 offsetX/offsetY。

宠物每帧锚定到聊天输入框（[data-composer-seat]）并跟随内部滚动；right/bottom
只是兜底位置。微调用 offsetX/offsetY。

状态 → 表情映射

附带模型 Haru 提供表情 f00..f08。默认映射如下（改 src/client/index.ts 的
PHASE_EXPRESSION 可自定义）：

附带模型 Haru 提供表情 f00..f08。默认映射如下（改 src/client/index.ts 的
PHASE_EXPRESSION 可自定义）：

| 状态 | 表情 | 含义 |
|---|---|---|
| idle | f00 | 中性 |
| waiting | f01 | 等待，微张嘴 |
| thinking | f02 | 思考，皱眉 |
| deep（思考 > 5s） | f02 | 深思考同款 |
| tool（有工具在运行） | f03 | 干活，咧嘴 |
| done（回合结束） | f04 | 完成，眯眼笑 |
| celebrate（完成 + ≥3 个工具） | f04 | 庆祝同款 |
| failed | f00 | 无委屈脸，用中性 |
| drag（被拖拽） | f05 | 拖拽，大笑 |
| sleep（空闲 > 60s） | f08 | 平静 |
| hover（idle/sleep） | f06 | 惊讶瞪眼 |

动作：Haru 只带 Idle + Tap 两组动作：待机动作常驻，空闲时随机播 Tap 小动作。
样例模型没有按状态的专属动作——自定义模型可加 TOOL_MOTION 映射。

Haru 只带 Idle + Tap 两组动作：待机动作常驻，空闲时随机播 Tap 小动作。
样例模型没有按状态的专属动作——自定义模型可加 TOOL_MOTION 映射。

调试句柄

在带有宠物的页面上打开浏览器控制台（F12）：

| 句柄 | 用途 |
|---|---|
| window.__dshLive2dPetModel | 已加载的模型实例 |
| pet('expr','motion') | 一句测试：设表情+播动作（可省略） |
| window.__dshLive2dPetToggle() | 编程式开关宠物 |
| window.__dshLive2dPetFreeze = true | 冻结自动联动（手动测试不被状态覆盖），false 恢复。⚠️ 冻结期间真实流程不会更新宠物 |
| window.__dshLive2dPetRoot | React 根句柄 |

示例：

pet('f02', 'Tap')   // 思考脸 + 随机小动作
pet('f04')          // 只切完成表情
window.__dshLive2dPetFreeze = false   // 恢复自动联动

换自己的模型

1. 把模型放进 assets/live2d//（.model3.json、.moc3、
贴图、.physics3.json、expressions/、motions/）。
2. 配置 cordis.patch.yml 的 config.model 指向它。
3. 改好 src/client/index.ts 里的 PHASE_EXPRESSION（以及可选的 TOOL_MOTION）
为你模型的表情/动作组名，然后 pnpm build。
4. 把 lib/ + assets/ 同步到目标 profile 的 node_modules/dsh-live2d-pet/，
重启服务端（patch/模型改动），硬刷新页面
（Ctrl+Shift+R，模型/表情改动必须硬刷新才加载）。

把模型放进 assets/live2d//，配置 model 指向它，改好表情/动作映射，
pnpm build 后同步到目标 profile，重启服务端（patch/模型改动），硬刷新页面
（Ctrl+Shift+R，模型/表情改动必须硬刷新才加载）。

架构与模型无关——宠物是壳，模型是皮。

架构与排雷

工作原理

DSH web page
├─  script src="/pet/live2d/live2dcubismcore.min.js"   ← host half, injected via tapIndex
├─ client bundle (lib/client.js, single inlined file)
│   ├─ pixi.js + pixi-live2d-display/cubism4 (fully inlined)
│   ├─ Live2DPet component: anchor / drag / expression / motion / mouse tracking
│   └─ apply(): mount + session-state linkage + ✨ toggle button (slots)
└─ host routes /pet/live2d/* (prefix, serves model assets)

关键约束（全部实战排雷）

1. 禁止动态 import——DSH 客户端模块系统不认分包，必须全内联单文件。
2. Cubism core 必须先行——pixi-live2d-display 在模块加载时检查
window.Live2DCubismCore；host 在 bundle 执行前注入到 head。
3. 只用 cubism4 子入口——绕过 Cubism 2 运行时检查。
4. 前缀路由不带尾斜杠——带尾斜杠会拼成双斜杠匹配不上。
5. React 必须 external——内联第二个 React 实例会破坏 slots 渲染组件中的
hooks（React error #321）。react/react-dom 来自
从 DSH 宿主模块表获取（与 dsh-emoji-wallet 相同）。/ React 必须
external——内联第二份 React 会让 slots 组件 hook 崩溃，从 DSH 模块表拿。
6. ctx.slots 需要 inject 声明——package.json 的
dsh.client.inject 条目（@deepseek-ai/dsh-client-ui-slots）以及
bundle 中的 export const inject = ['slots'] 两者都必需，否则会报
“cannot get property slots without inject”。/ slots 按钮要双重 inject——
package.json 包名 + bundle 里 export const inject = ['slots']。
7. 物理输出参数被锁定——在某些模型上，物理驱动的参数（例如尾巴的
Param_Angle_Rotation_）每帧都会被覆盖；动作无法移动它们。/ 物理输出参数被锁——物理每帧覆盖，动作曲线写不动。
8. 拖拽偏移合理性钳制——残留的异常 dsh-live2d-pet-drag
localStorage 值可能会把宠物推出屏幕；加载器会将其钳制到
视口范围内并丢弃错误值。/ 拖拽偏移钳制——异常残留偏移会被自动清除，
防止宠物被怼出屏幕。
9. Toggle 必须重置会话身份——tearDownSession() 会重置
currentSessionId/lastKey，否则将宠物关闭/开启一次会永久杀死
状态联动刷新循环（宠物能渲染但永不反应）。/
toggle 必须重置会话身份——否则开关一次后状态联动永久死亡（宠物能显示但不再反应）。

依赖中的 Node 内置模块

@pixi/utils 会导入 node 的 url；scripts/url-shim.js（
dsh-client-url-shim 插件的副本）
会在构建时将其重写为浏览器安全的模块。

开发 / Development

pnpm install
pnpm build        # tsdown → lib/client.js (browser) + lib/index.mjs (node)
pnpm typecheck    # tsc --noEmit

生成器脚本 / Generator scripts

该插件在 scripts/ 下提供了与模型无关的工具：

| 脚本 / Script | 用途 / Purpose |
|---|---|
| scripts/gen-motions.mjs  [--force] | 从代码定义生成 motion3.json 动作 + exp3.json 表情。默认会跳过已存在的 .exp3.json（手工调优的表情优先）；--force 会覆盖它们（谨慎使用）。/ 从代码定义生成动作/表情；默认跳过已存在的 exp3（手动调参优先），--force 才覆盖 |
| scripts/sync-expressions.mjs  | 从现成的 exp3 文件刷新生成器的表情默认值（使生成器与手工调优的资产保持同步）。/ 从资产现成 exp3 刷新生成器的表情默认值 |
| scripts/expressions-data.mjs | 生成的数据文件（请勿手动编辑）。/ 生成的数据文件，勿手改 |

编辑表情/动作的工作流 / Workflow for editing expressions / motions

1. 在 Live2D Cubism Viewer 中手工调优（打开 .model3.json，拖动
参数/关键帧，导出 exp3/motion3）——或编辑生成器
定义。
2. 运行 node scripts/sync-expressions.mjs  刷新表情
默认值（手工调优优先；生成器永不覆盖已存在的 exp3）。
3. pnpm build → 将 lib/ + assets/ 同步到目标 profile。
4. 硬刷新页面（Ctrl+Shift+R）——模型/表情更改需要这样做。

人工调参用 Live2D Cubism Viewer 打开 .model3.json 拖参数/摆关键帧，导出
exp3/motion3 即生效。表情手动调参后跑同步脚本刷新生成器默认值——生成器永不覆盖
已有表情文件。

许可 / License
MIT 许可。附带的 Haru 模型 © Live2D Inc.，按官方样例模型许可随附用于测试——
生产环境请替换为自己的模型。