前言¶

DeepSeek Harness（DSH）把智能体能力拆成可安装的插件：会话里能调用的工具、设置页、HTTP 接口都可以挂在同一套 profile 上。若你希望角色不只在聊天窗口里出现，而是常驻桌面、能说话、能抬眼点头换表情，通常要自己拼 Electron 浮窗、动作引擎和 AI 回调。dsh-live2d-pet 把 鲸语 jingyu-live2d-agent 的舞台裁成透明桌宠外壳，并向 DSH 注册一组工具，让模型驱动气泡与动作。模型自备：插件包不含 Live2D 模型文件；示例「大肥鱼」公皮禁止重新分发，需按原作者许可自行放置 .moc3 与 model3.json。

这是什么¶

维护者 11454zaw，社区目录分类为「趣味换装」。当前版本 0.2.0（MIT，仅覆盖本仓库代码）。插件不打包鲸语源码，也不打包模型；分工是：鲸语负责渲染、动作编译、物理与口型；本插件负责 Electron 外壳、气泡与聊天文件、把动作计划 POST 给鲸语，并提供四个 DSH 工具与设置页。

核心功能¶

DSH 工具¶

装完并重启 DSH 后，工具列表会出现：

• live2d_pet_status：外壳是否在跑、舞台是否通、模型名称等
• live2d_pet_say：显示一句气泡（默认停留 9 秒，可在配置里改）
• live2d_pet_perform：组合语义动作（抬眼、点头、摇头、偏头、笑、眨眼、表情、手势），可带台词
• live2d_pet_restart：重启外壳

设置页（设置 → 桌宠）¶

无需开终端即可调整外观与行为：窗口宽度 260–900 px、不透明度 0.25–1、本机头像路径、视线跟随、待机开关与间隔（最短 8–300 秒、随机范围）、气泡停留 1–60 秒、九个待机动作白名单（全不勾等于全开）。启动相关项包括鲸语舞台地址、Electron 路径、.ps1/.cmd 启动脚本、开机自启。页面还提供 23 个表情、3 套手势与常用组合的动作试玩，以及「说一句」输入框。保存并套用会写配置、写 shell/pet-settings.json 并重启外壳（舞台不动）。

HTTP 接口¶

均要求本机同源并通过 DSH 信任栅栏：GET /api/live2d-pet/status；POST 的 /start、/restart、/config、/apply、/perform、/say（0.2.0 起新增 /config、/apply、/perform、/say，旧路由仍保留）。

桌宠外壳交互¶

透明浮窗、置顶、无任务栏图标；拖左上角头像移动，点击可收起为 84×84 圆头像。右键可切换置顶、鼠标穿透、预设大小、位置、打开完整工作台等。快捷键含 Ctrl+Alt+L 穿透、Ctrl+Alt+T 置顶、Ctrl+Alt+-/= 缩放、Ctrl+Alt+H 收起。气泡读 $DSH_HOME/live2d-pet/shell/say.txt；聊天面板使用 chat.jsonl 与 stats.json。

安装与启用¶

前置条件¶

1. 鲸语按自身 README 启动，http://127.0.0.1:61942/ 可访问且模型能显示。
2. Electron：DSH 桌面版自带 $DSH_HOME/electron/electron.exe，或在配置里用 electron 字段指向本机可执行文件。
3. DSH ≥ 0.2.0-rc.2（作者在 0.2.1-rc.5 上测过）；Node ≥ 20.18；profile 支持 desktop 与 web（桌宠外壳以 desktop 场景为主）。

安装命令¶

下面命令来自仓库 README，请按你的路径替换本地目录：

# 本地目录
dsh plugin --profile desktop add file:/path/to/dsh-live2d-pet

# 或者从 npm（发布后）
dsh plugin --profile desktop add dsh-live2d-pet

安装后重启 DSH。插件以当前 DSH 进程权限运行，安装前建议阅读源码与 LICENSE，并确认鲸语与模型各自的许可条款。

主配置¶

首次加载会在 $DSH_HOME/live2d-pet/config.json 建目录；缺省示例：

{
  "stageUrl": "http://127.0.0.1:61942",
  "electron": "",
  "launchScript": "",
  "autoStart": false,
  "avatar": "",
  "width": 435,
  "opacity": 1,
  "follow": true,
  "idleEnabled": true,
  "idleMinMs": 22000,
  "idleSpreadMs": 45000,
  "idleActions": [],
  "bubbleHoldMs": 9000
}

stageUrl 为鲸语地址；launchScript 在设置页点「全部拉起」时先执行；idleActions 空数组表示允许全部待机动作。外壳另维护 shell/pet-window.json（位置、置顶、穿透）与 shell/pet-settings.json（设置页写入、供外壳读取）。

典型用法¶

1. 按前置条件拉起鲸语与模型，安装插件并重启 DSH。
2. 打开 设置 → 桌宠，确认舞台在线后点「全部拉起」或「只重启宠物窗」；需要一键连舞台时配置 launchScript。
3. 在会话中让智能体调用 live2d_pet_say 或 live2d_pet_perform，或在设置页动作区点试玩、在「说一句」框输入文字。
4. 改外观或待机节奏后点 保存并套用；仅持久化不重启外壳时用 只保存。

动作能力取决于模型与舞台开放的语义动作、23 个表情名与三套手势（举手 hand_on_chest、竖手指 point、狗尾草 grass）；不能任意播放未开放的 motion 文件。

适用场景与注意¶

适合已在 DSH desktop profile 上跑智能体、并希望桌面 Live2D 与工具联动的开发者或个人使用者。社区插件目录 SkillHub 上的 dsh-live2d-pet 与 DeepSeek / 幻方无官方从属关系，安装来源以你信任的仓库或 npm 包为准。

务必知晓的边界：

• 不含实时回话器：仓库内 realtime.mjs 未打进插件，需自行对接或等待后续版本。
• 改插件 JS 须重启 DSH；热重载不覆盖插件自身代码。
• DSH 会话环境带 ELECTRON_RUN_AS_NODE=1，插件启动外壳时会清除；手工启动外壳时需自行处理。
• Cubism SDK、鲸语与模型版权各自独立，MIT 只覆盖本插件仓库。

结尾¶

dsh-live2d-pet 把鲸语舞台裁成桌面透明浮窗，并用 DSH 工具与设置页把「说话、表演、重启、状态查询」接到同一套 Harness 里；模型与舞台仍由你本地准备与授权。详情与更新见 GitHub：11454zaw/dsh-live2d-pet，目录页见 SkillHub 插件页。