README

dsh-pet 🐾


  
  
  
  
  
  
  
  
  
  
  


一只住在 DeepSeek Harness 里的桌面宠物：待机呼吸、随机动作（打瞌睡、玩魔方、吃火锅……）、左右转向、屏幕漫游、点击 Q 弹、拖拽甩抛反弹、右键菜单点播——一百余个透明动画随时无缝衔接；还能跟随 DSH 会话事件切换工作状态动画、按档位播放余额动画 + 头顶气泡、碎碎念与对话聊天、窗口失焦时弹系统通知。可多开同屏，能脱离浏览器住上桌面（透明置顶小窗），也能自己添加全新宠物种类（pet pack）。

这不是一个普通插件，而是完整的三件套项目：


① 提示词（配方）    →  ② 素材生成链（引擎）  →  ③ 插件（成品）
AI 生成动画的配方     源视频 → 透明动画的管线    运行在 DSH 里的宠物


任何人 clone 本仓库，都可以从零生成自己的桌面宠物——换角色、换动作、换风格，全流程可复现。

---

 快速开始（安装插件）

两种装法，任选一种：

- 图形化（桌面应用内）：打开「插件管理」页，在安装框里填 dsh-pet，不用开终端。
- 命令行：dsh plugin --profile  add dsh-pet， 按你在用的界面填——dsh web 填 web，桌面应用（Electron 版）填 desktop。

不想装 DSH？ Release 里提供 Windows x64 绿色包 dsh-pet-win-x64.zip，解压后双击 dsh-pet.exe 就能跑——那是独立模式，不依赖 DSH 环境。

装完重开 DSH（dsh web 用户则重启 dsh web）才生效——运行中的进程持有内存里的旧插件。宠物默认落在界面右上角。

前置要求、源码安装、独立模式的用法与打包、Electron 首次下载、装完会看到什么，见 INSTALL.md。

 插件功能

只做桌宠本身，不碰 DSH 内核；能力就下面这些。

- 100+ 段动画资产：待机、走动漫游、玩耍、工作、对话等全部表现都由视频动画驱动，按权重首尾相接，也可换成自己的素材。
- 多开与种类：同时养多只，各自大小与位置；也能自定义宠物种类（pet pack），一类一套动画与素材。
- 三种运行形态：DSH web 的浏览器 overlay、DSH 桌面应用的透明置顶窗、完全不依赖 DSH 的独立模式。
- 交互与物理：点击回应、拖拽甩抛、双击弹弓、宠物互撞，同一套物理与 Q 弹挤压手感，参数可调。
- 手机与触屏：触屏直接拖拽甩抛，与鼠标共用同一套物理与挤压手感；手机浏览器上还能倾斜手机改变重力方向、摇一摇把宠物甩出去、碰撞时震动反馈——三项可在设置页「移动端效果」里分别关闭。传感器只在 HTTPS 或 localhost 下可用（iOS 还需点一次授权），iOS 与桌面端没有振动 API，会自动跳过。
- 碎碎念与对话：按周期自动说一句，也能随时聊；记忆持久化、可配图、可念出来。
- 语音（说与听）：对话回复与手动碎碎念会念出来，音色、音量与总开关可配；按住对话窗的话筒说一句，录音转成文字直接填进输入框。
- 余额展示：内置常见服务商的余额 / 额度查询，按剩余额度分档播动画并弹气泡；也可以登记自己的服务商。
- 工作状态联动：跟随 DSH 会话状态切档位动画，并在头顶常驻一句话。
- 待办事项：一句话加可选到期时间，清单挂在宠物头顶；越临近到期提醒越密，由宠物说出来。
- 睡觉：右键「睡觉」让它睡下，点一下或右键「起来」叫醒；睡着时完全安静——随机动作、碎碎念、余额、待办与工作状态都不打扰，还会按周期说梦话；睡姿可用 animations.sleep 配多套（蹲着睡、趴着睡…）。
- 系统通知：任务完成或需要确认时弹系统通知，点一下回到对应会话。
- 右键菜单：换动画、开聊、回到原位、打开 DSH / 网站、重载配置。
- 其他：点击音效、系统托盘与每只宠物的显示位置。

各项能力的详细说明见 FEATURES.md；配置（大小 / 位置 / 多开 / 物理 / 模型 / 人设 / 宠物种类）见 CONFIG.md。

 🔌 对外接口（供其他插件调用）

桌宠不只自己玩，也对外开放两条调用通道，让别的插件或脚本能驱动它、读它的状态。

- 能做什么：让它说一句指定的话、播一段指定动画、与它对话；读它当前说的话、工作状态、系统通知与余额
- 为什么开放：桌宠不该只是个摆设——比如一个「女仆」插件巡检验完想说句话，就能让桌宠当它的「实体」开口；也方便任何人基于它做二次开发
- 通道一 · HTTP：挂在 DSH 自己的 Web 服务上（前缀 /dsh-pet-7340，只监听本机、无鉴权），跨进程、脚本可直接调。动作类接口只回 {ok}，数据统一从 GET /state 读
- 通道二 · Cordis 服务：客户端半侧在 DSH web 页面内注册，同页客户端插件用 ctx.get('petApi7340') 直接取，零网络、零端口；只在该页面实例内有效，方法与返回见 CORDIS.md

相关文件（HTTP 与 Cordis 各一套）：

- API.md —— HTTP 接口一览（每个接口一句话，功能预览）
- openapi.yaml —— 完整契约（OpenAPI 3.1，可直接导入 Swagger UI / Postman）
- CORDIS-API.md —— Cordis 服务一览（每个成员一句话，功能预览）
- CORDIS.md —— 对外 Cordis 服务（客户端半侧，页面内 ctx.get('petApi7340')，不走网络）
- tools/api-tester.html —— HTTP 侧示例：桌宠控制台，扮演第三方消费方，可直观试用（node tools/api-tester.cjs 启动）
- tools/cordis-probe —— Cordis 侧示例：扮演同页客户端插件，用 ctx.get() 消费服务

 兼容性

- 操作系统：Windows / Linux / macOS 三端均可运行——浏览器 overlay 与桌面模式（Electron 透明置顶窗）行为完全一致；Electron 按平台自动探测/下载（electron.exe / Electron.app / linux 单文件），无需手动安装
- 无头 / 无桌面环境：支持 Linux headless 等无图形会话——桌面模式自动检测显示环境（Linux 无 DISPLAY / WAYLAND_DISPLAY 时判定无显示、跳过桌面窗口，仅日志告警），浏览器 overlay 不受影响
- 浏览器：浏览器 overlay 兼容 Chromium 内核（Chrome / Edge 等）与 Firefox——透明动画依赖 VP9-Alpha webm，三者均已实测透明确认；不支持 Safari（macOS 不认 webm alpha，透明渲染为黑底）——macOS 用 .mov 素材（GitHub Release assets-mov），下载放入即可（见「②.5 Safari/

Latest release

dsh-pet v0.4.7

 📦 安装 / 更新

bash
dsh plugin --profile web add [email protected]


 显式指定版本安装，避免本地缓存命中旧版。桌面端把 --profile web 换成 --profile desktop。
 不想装 DSH 也能用：Release 附件里的 dsh-pet-win-x64.zip 解压双击即可运行（Windows x64）。

 ✨ 新功能

- 通知播报：任务完成、出错、等你确认时念一句工作状态台词。和系统通知同一取向：切走、最小化时才念，正看着屏幕不打扰。默认关闭，在设置页语音卡里打开。原来的「语音播报」现在叫「手动播报」，只管右键与斜杠命令触发的碎碎念和对话回复。

 🐛 修复

- Windows 标题栏拖不动、双击缩放失效：「吃白饭」的覆盖层改挂宿主插槽，不再压掉标题栏的拖拽区。（323 324）

Full Changelog: https://github.com/PC2005-cloud/dsh-pet/compare/v0.4.6...v0.4.7