dsh-pet

dsh-pet 🐾

一只住在 [DeepSeek Harness](https://github.com/deepseek-ai/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](INSTALL.md)。

插件功能

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

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

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

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

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

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

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

• [API.md](API.md) —— HTTP 接口一览（每个接口一句话，功能预览）
• [openapi.yaml](openapi.yaml) —— 完整契约（OpenAPI 3.1，可直接导入 Swagger UI / Postman）
• [CORDIS-API.md](CORDIS-API.md) —— Cordis 服务一览（每个成员一句话，功能预览）
• [CORDIS.md](CORDIS.md) —— 对外 Cordis 服务（客户端半侧，页面内 ctx.get('petApi7340')，不走网络）
• [tools/api-tester.html](tools/api-tester.html) —— HTTP 侧示例：桌宠控制台，扮演第三方消费方，可直观试用（node tools/api-tester.cjs 启动）
• [tools/cordis-probe](tools/cordis-probe/README.md) —— 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/HEVC 兼容素材」）
• 多显示器：支持多屏环境——跨屏漫游/抛掷以各屏工作区为界，异构缩放（各屏 DPI 不同）、任务栏条带、屏幕之间空洞均正确判定（横屏 / 竖屏 / 上下叠放皆可）；设置页「锁定在当前屏幕」可让宠物（抛掷与漫游）只在当前所在那块屏内活动

运行效果

宠物实际运行在 DSH Web 界面中的样子：

效果预览

全部动画（640×360，插件实际播放用的资源）——GIF 预览存放于仓库 dsh-pet/assets/preview/（raw 直链渲染，文件名采用拼音便于跨平台）；完整透明视频见插件包 dsh-pet/assets/webm/（VP9-alpha，唯一发布格式）：

待机 / 转向

移动

小动作

玩耍

吃什么

时节

文字

点击回应

拖拽

余额事件（按余额已用百分比分档，满格 → 告急 → 耗尽）

碎碎念说话动画（碎碎念 / 对话回复触发，随机抽 1 段）

工作状态动画（跟随 DSH 会话事件，六档：思考 / 工作 / 整理 / 等待 / 成功 / 出错）

睡觉（右键「睡觉」或鼠标停上去按 S；睡着时点一下叫醒）

> 注：动画为透明背景；GIF 预览中透明部分显示为页面底色，实际 webm 播放为透明。

从零生成你自己的宠物

AI 提示词 → 绿幕视频 → 透明动画 → 插件，换角色、换动作、换风格，全流程可复现。

完整步骤见 [MAKE-YOUR-OWN-PET.md](MAKE-YOUR-OWN-PET.md)（提示词配方、素材链、Safari 兼容、发布）。

项目结构

只列代码与发布相关目录；素材链的 video / scripts / step / pr 见 [MAKE-YOUR-OWN-PET.md](MAKE-YOUR-OWN-PET.md) 的 ② 章节（gitignore 的本地目录不列）：

├── README.md  INSTALL.md  FEATURES.md  MAKE-YOUR-OWN-PET.md  CONFIG.md  API.md  CORDIS.md  openapi.yaml   # 说明 / 安装 / 功能详解 / 宠物制作指南 / 配置 / HTTP 接口 / Cordis 服务 / OpenAPI 规范
├── prompts/           # ① 动画生成提示词配方（绿幕规范 + 按秒分解）
├── assets/            # 仓库展示用截图
├── tools/             # 开发工具：API 调试页、cordis-probe mock 服务商、DPI 探针
├── .github/workflows/ # CI：Safari/HEVC 转码流水线（macOS runner，手动触发 → 发布 assets-mov Release）
├── dsh-pet/           # ③ 插件（可独立 npm 发布）
│   ├── src/
│   │   ├── host/       # 宿主半侧：配置 / 路由 / 余额 / 工作状态
│   │   ├── client/     # 浏览器半侧：宠物渲染 / 动画链 / 设置页
│   │   ├── shared/     # 双端共用纯逻辑（物理 / 菜单 / 取数）