给 DSH Web GUI 加一只 Live2D 桌宠：镜像 agent 思考/空闲/出错/完成状态，支持分部位触摸、鼠标跟随与多套人设台词。
- 语言
- TypeScript
- 分支
- main
安装
$ dsh plugin --profile web add dsh-live2d-pets在终端中运行以上命令，通过 dsh CLI 安装此插件。可在右上角切换 Profile。 第一次用 dsh？看这篇新手教程
对话式安装
帮我安装 DeepSeek Harness 插件 cyanfish-x/dsh-live2d-pets：先查看仓库 https://github.com/cyanfish-x/dsh-live2d-pets.git 确认安全性，然后执行安装命令并验证插件加载成功。
把这段指令粘贴给 DSH Web GUI 里的助手，由它代你完成安装与验证。
一句话定位
给 DeepSeek Harness Web GUI 加一只 Live2D 桌宠，实时镜像 agent 思考/空闲/出错/完成状态并支持摸头摸腿的互动陪伴，让"等 agent 跑完"的这段时间不再干瞪眼。
核心能力
- 状态镜像：agent 思考/空闲/出错/完成/等审批时，宠物自动切换动画与气泡（思考与等审批为长状态气泡，按时间阶段推进文案）
- 分部位触摸互动：摸头/摸腿/摸手/摸身体各有专属台词与动作；模型命中区不足时按包围盒五矩形空间回退
- 鼠标跟随：宠物头、眼、身体随鼠标平滑看向，鼠标移出页面复位；拖动与动作期间暂停跟随
- 自由拖动：抓住宠物在任意位置拖拽松手即停靠，位置持久化
- 内置人设体系：六种二次元性格（傲娇/元气/天然呆/三无/温柔治愈/病娇）覆盖全部台词，支持 JSONC 文件自定义人设（含注释版女仆彩蛋）
- 自定义模型：可填任意 .model3.json 的 HTTP(S) URL 或本机绝对路径，插件宿主通过同源路由加载，无需把模型文件打进 npm 包
技术实现
- 语言: TypeScript（Node.js 宿主 + React 18 浏览器半区）
- 关键依赖: @deepseek-ai/schemastery（配置 schema）、@deepseek-ai/cordis（插件纤维）、@deepseek-ai/dsh-settings（配置 namespace）、@deepseek-ai/dsh-host-webserver（同源 HTTP 路由）
- 架构模式: 宿主半区订阅 agent 事件 + 注册 settings namespace + 注册同源路由；客户端半区通过 SSE 接收状态推送（
/api/live2d-pet/events），渲染走shell.overlayPopover 顶层（pixi-live2d-display 0.4.0 + PixiJS 6.5.10 + Cubism Core 4） - 入口文件:
src/index.ts（Host 入口，注册 services 与 routes）、src/client/index.ts（浏览器入口，挂载 Layer + 设置页）
适用场景
DSH 重度用户跑长任务时，希望在角落里看到一只小角色实时反映"还在想 / 跑完了"，顺手点两下摸头摸腿；以及想用二次元角色给 DSH 视频/直播/教程加点"看板娘"味的潜在用户。License 商用安全：默认模型 Hiyori 是 Live2D 官方示例模型，免费商用可。
前置依赖与兼容性
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| Node.js | ^22.19.0 | |
| @deepseek-ai/cordis | ^4.0.1 | 插件纤维，见 package.json#peerDependencies |
| @deepseek-ai/dsh-client-runtime | ^0.1.0-rc.6 | 客户端运行时 |
| @deepseek-ai/dsh-host-webserver | ^0.1.0-rc.6 | Host 同源 HTTP 路由 |
| @deepseek-ai/dsh-client-ui-slots | ^0.1.0-rc.6 | 用于挂载 shell.overlay 与 settings.section |
| @deepseek-ai/dsh-settings | ^0.1.0-rc.6 | settings namespace 注册 |
| 平台 | macOS / Windows / Linux | host 端 Node 跨平台；浏览器端看宿主正在运行的 Web GUI |
| 原生模块 | 无 | 纯 Node fs + 浏览器 WebGL |
安装方式
dsh plugin --profile web add dsh-live2d-pets
配置项
| 配置 | 类型 | 说明 | 默认值 |
|---|---|---|---|
| enabled | 布尔 | 宠物总开关，关闭后完全不渲染（零开销） | true |
| size | 数字 | 宠物尺寸（像素，滑杆 40–400） | 160 |
| maxFps | 数字 | 渲染帧率上限，三档自绘单选 | 30 |
| model | 字符串 | 选中模型：内置 id 或自定义模型 id（也直接兼容 URL） | hiyori |
| persona | 字符串 | 选中人设：内置（傲娇/元气/天然呆/三无/温柔治愈/病娇）或自定义人设 id | tsundere |
| developerMode | 布尔 | 开发者选项总开关，开启后显示调试面板入口与点击分区色块 | false |
| debug | 布尔 | 调试面板：实时状态/动画/FPS/演示状态切换 | false |
| showTapZones | 布尔 | 在模型上叠加空间回退色块（与 click 分档共用同一阈值） | false |
常见问题
Q: 首次启动看不到宠物怎么办？
A: 默认模型 Hiyori 从 jsDelivr CDN 拉取，需要联网；若加载失败宠物会显示静态头像占位，可去「桌宠配置」切换到内置 Haru/Mao/Mark/Natori 或换自定义模型。
Q: 怎么自定义人设台词？
A: 打开设置 → 桌宠配置 → 人设区点「自定义人设 ↗」编辑 $DSH_HOME/live2d-pet/personas.jsonc，保存后回设置页点「↻ 重新读取」即时生效，无需重启。文件首次启动会自动落下模板（含注释版女仆彩蛋）。
Q: 怎么加自己的 Live2D 模型？
A: 设置 → 桌宠配置 → 我的模型：填名称 + .model3.json 的 HTTP(S) URL，或填写本机绝对路径（如 C:/models/foo/foo.model3.json），插件宿主会通过同源虚拟路由 /pet-local-models/<id>/... 加载。
Q: 宠物会拖慢页面吗？
A: 标签页隐藏或窗口失焦时自动暂停渲染；渲染帧率默认 30fps，可在设置面板改为 60 或不限制；WebGL 不可用或加载失败时降级为静态头像，不影响其它 GUI 功能。
Q: 拖动后位置会保存吗？
A: 会的。拖动宠物到任意位置松手后停靠位置会持久化到 $DSH_HOME/live2d-pet.json，下次启动还在原位置。
Q: 只支持 Web GUI 吗？
A: 是的。该插件的 dsh.client.platform=web + inject=slots 限制它只在 DSH Web GUI 中工作；不适用于 headless/CLI 形态。
Q: 怎么卸载？
A: 终端执行 dsh plugin --profile web remove dsh-live2d-pets；卸载后 $DSH_HOME/live2d-pet/ 下的个性化文件与 $DSH_HOME/live2d-pet.json 可手动清理。
Q: 第三方模型在本插件的许可风险如何？
A: 插件默认 Hiyori 是 Live2D 官方示例模型，免费商用可、需标注著作权；自定义模型由用户自备，请遵守模型作者许可，非商用模型会被标注为"仅限非商用"。
上手难度
入门 — 安装即在右下角出现默认宠物，鼠标悬停即看跟随；想深挖点击分区、动画映射、JSONC 人设文件编辑时再翻 docs/，普通用户零配置即可用。
已知问题与限制
- 仅支持 Web GUI（
dsh.client.platform=web，inject=slots），headless/CLI 不可用 - v0.1 不含音效（资源与许可成本，v0.2 再议，见 docs/spec/live2d-pet-v01.md:78）
- v0.1 明确不做：人设混合/随机切换、设置页内文案编辑器、文件监听热重载（自定义人设改完需点「↻ 重新读取」）、可配置停靠角（固定右下角）、重置位置按钮、隐藏快捷键
- 自定义模型加载失败时降级为静态头像 + 错误气泡，GUI 其它功能不受影响
- 默认模型 Hiyori 首次加载依赖网络（jsDelivr CDN），离线环境请准备本地模型或预置自定义模型
- 自定义模型仅存名称 + URL，旧版
Cordis.patch.yml里的customModels字段已弃用，改用$DSH_HOME/live2d-pet/custom-models.jsonc；旧字段在首次启动时一次性迁移到新文件后清空 - 自定义人设文件由插件首次启动时落地模板后只读不写——注释会保留；用户直接编辑后点「↻ 重新读取」或刷新页面即可生效
English | 简体中文
给 DeepSeek Harness 请了个看板娘：你思考它歪头，你完成它撒花，还能摸头！
特性
- 模型加载：内置 5 条策展模型（Hiyori / Haru / Mao / Mark / Natori）+ 自定义条目；可用任意
.model3.json的 https / http URL，或填写本机绝对路径（如C:/models/foo/foo.model3.json，由插件 Host 转成同源 HTTP 加载）；自定义模型可配置动画映射，把模型原生动作组挂到状态/互动部位 - 状态镜像：宠物实时反映 agent 思考 / 空闲 / 出错 / 完成 / 等审批（动画 + 气泡，SSE 推送）
- 人设台词：内置六种人设（傲娇 / 元气 / 天然呆 / 三无 / 温柔治愈 / 病娇），可在插件独有 JSONC 中自定义并热切换
- 互动陪伴：分部位触摸反应 / 鼠标跟随（头、眼、身体看向鼠标）/ 拖动停靠，任务完成庆祝；HitArea 不足时按包围盒五矩形空间回退分档
- 桌宠配置设置面板：DSH 设置 →「桌宠配置」，开关 / 尺寸 / 渲染帧率 / 人设 / 模型列表 / 开发者选项；标量设置写入
~/.dsh/settings.yaml，自定义人设与自定义模型存于~/.dsh/live2d-pet/插件私有 JSONC 文件，即时生效 - 不打扰：默认右下角、小尺寸、可拖动、可隐藏、标签页隐藏暂停渲染、限帧渲染、低配降级静态头像
快速开始
方式一：复制提示词让 agent 安装（推荐）
把下面这段提示词复制给你的 DSH agent（在 Web GUI 对话中直接粘贴即可），它会自己安装并验证：
请帮我安装 dsh-live2d-pets 插件（DSH 的 Live2D 桌宠插件）：
1. 执行 dsh plugin --profile web add dsh-live2d-pets 安装
2. 执行 dsh plugin --profile web list，确认 dsh-live2d-pets 出现在已安装列表中
3. 告诉我安装结果；如果失败，请附上错误信息
方式二：手动安装
在终端执行（web profile 首次使用时自动初始化）：
dsh plugin --profile web add dsh-live2d-pets
安装后插件默认启用。启动 DSH：
dsh web
浏览器打开后，右下角会出现默认宠物（尺寸 160px）。当前默认模型为 Hiyori（Live2D 官方示例模型），首次加载需联网。
互动
- 鼠标跟随：默认开启。鼠标在页面任意位置移动时，宠物的头、眼睛、身体会平滑看向鼠标；鼠标移出页面后复位正视前方。拖拽中不跟随，隐藏或页面失焦时自动暂停。
- 触摸互动：摸头 / 摸腿 / 摸手 / 摸身体各有专属台词与动作；模型 HitArea 不足时按包围盒空间分区回退。
- 拖动：按住宠物拖动到任意位置，松手后停靠并持久化。
自定义模型：打开设置 →「桌宠配置」→「我的模型」，填写名称与 .model3.json 地址（外网 CDN、自建静态站、本机 HTTP 服务，或本机绝对路径如 C:/models/foo/foo.model3.json 均可；本地路径由插件 Host 通过 /pet-local-models/... 同源路由加载）。可展开 「空间分区覆盖」 按字段微调五矩形（头/身/腿居中列 + 左右臂；0–1，留空用默认），或展开 「动画映射」 实时解析模型动作组，为状态/互动部位选择动作组；建议配合开发者选项「显示点击分区」对照色块。内置 Hiyori 已带居中分区预设。
配置设置
打开 DSH 设置 →「桌宠配置」，改完立刻生效，无需重启。
- 显示：开关宠物
- 尺寸：40–400px（默认 160）
- 渲染帧率：30 / 60 / 不限制（默认 30）
- 人设台词：切换内置或自定义人设；「自定义人设 ↗」编辑
$DSH_HOME/live2d-pet/personas.jsonc，改完点「↻ 重新读取」 - 模型：选内置策展模型，或在「我的模型」添加名称 +
.model3.jsonURL（可选空间分区覆盖 / 动画映射）；自定义模型存于$DSH_HOME/live2d-pet/custom-models.jsonc - 开发者选项：总开关（默认关）；开启后可显示调试面板（含模型原生动画列表预览）、显示点击分区色块
卸载
dsh plugin --profile web remove dsh-live2d-pets
文档
| 需求 | 文档 |
|---|---|
| 英文 README | [README.en.md](README.en.md) |
| 产品意图 | [docs/intent/live2d-pet-plugin.md](docs/intent/live2d-pet-plugin.md) |
| 行为规格 | [docs/spec/live2d-pet-v01.md](docs/spec/live2d-pet-v01.md) |
| 架构决策 | [docs/adr/](docs/adr/)（渲染栈见 ADR-003） |
| 调研记录 | [docs/research/](docs/research/)（设置面板接入机制见 settings-tab.md） |
技术栈
- pixi-live2d-display 0.4.0 + PixiJS 6.5.10 + Cubism Core 4（ADR-003）
- 客户端渲染于 DSH Web GUI 的
shell.overlay悬浮层（视觉层 Popover 顶层，ADR-005），设置页注册于settings.section（ADR-002） - 状态推送：Host 订阅
agent/*事件 → 同源 SSE/api/live2d-pet/events（ADR-006）；标签页隐藏 / 失焦暂停渲染 - 设置持久化：标量设置走 Host
ctx.settings（~/.dsh/settings.yaml用户层覆盖 base）；自定义人设~/.dsh/live2d-pet/personas.jsonc、自定义模型~/.dsh/live2d-pet/custom-models.jsonc由插件直接读写；传输走插件自身 API/api/live2d-pet/settings（settingsScope wire 白名单限制，见 research 3.4/3.5）
许可
- 插件代码：MIT
- 模型清单：模型一律 URL 直载、不随包分发；清单门槛为「许可可标注」——每条记录许可类型与链接，NC（禁止商用）模型标注"仅限非商用"（清单见
[src/presets/presets.jsonc](src/presets/presets.jsonc)） - 内置模型 Hiyori / Haru / Mao / Mark / Natori：Live2D 官方示例模型，按示例模型条款使用（免费商用可，需标注著作权）
- Live2D SDK：按 Live2D 官方条款（免费商用，需遵守版权声明等）
收录徽章
[](https://deepseek-plugin.org/plugins/cyanfish-x/dsh-live2d-pets)把这段 markdown 粘贴到你的 GitHub README，链接回本插件详情页。徽章只声明已被本站收录，不代表安全认证。