# dsh-pet 🐾

npm version npm monthly downloads total downloads release downloads stars license awesome dsh plugin repo size issues platform assets AtomGit

一只住在 [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，会自动跳过。 - **碎碎念与对话**：按周期自动说一句，也能随时聊；记忆持久化、可配图、可念出来。 - **语音（说与听）**：对话回复与手动碎碎念会念出来，音色、音量与总开关可配；按住对话窗的话筒说一句，录音转成文字直接填进输入框。 - **余额展示**：内置常见服务商的余额 / 额度查询，按剩余额度分档播动画并弹气泡；也可以登记自己的服务商。 - **天气与位置**：右键「查询天气」查一次当前城市与天气（按出口 IP 粗定位 + Open-Meteo，免 key、免配置），气泡里给气温、体感、湿度、风速和对应天气图标；这份环境也会作为背景交给对话。 - **工作状态联动**：跟随 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 界面中的样子：

dsh-pet 运行效果 1 dsh-pet 运行效果 2 dsh-pet 运行效果 3 dsh-pet 运行效果 4 dsh-pet 运行效果 5 dsh-pet 运行效果 6 dsh-pet 运行效果 7 dsh-pet 运行效果 8

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

待机呼吸休闲 东张西望

**移动**

螃蟹走路 原地漂浮踏步 原地左转奔跑

**小动作**

悠闲哼歌 超大伸懒腰 原地敲击桌面互动 原地重力下蹲压缩 哈欠连天 原地小憩沉眠 女仆屈膝礼仪 被吓一跳 小幅度原地360度旋转展示 偷吃零食被抓住 用鲸鱼尾巴拍打地面 打瞌睡被惊醒 照镜子 整体换装试色 轻快记录 写代码 摇扇纳凉 晨间刷牙

**玩耍**

原地专心玩魔方 原地蹲下玩玩具汽车 鲸鱼吐泡泡特效 原地跳跃抓碎头顶物品 玩游戏气急败坏 玩水枪 小提琴演奏 蓝鲸现世 优雅女仆舞 轻快摇摆舞 可爱宅舞 吹气球 动物环绕 放风筝 拆礼物 变鸽子 扑克魔术 抽陀螺 吹笛子 蝴蝶蜜蜂环绕头顶开花 撸猫 凭空生花 骑木马 三球抛接 踢毽子 下五子棋 荡秋千

**吃什么**

吃白饭 大口吃零食 吃Token 吃早餐 吃午餐 吃晚餐 吃冰淇淋融化 吃大闸蟹 吃糖葫芦 吃长寿面 吃西瓜 涮火锅

**时节**

被落叶淹没 中秋赏月吃月饼 堆雪人 放烟花 吃粽子 吃年糕 吃青团 吃腊八粥 吃重阳糕 收红包 写福字 穿针乞巧 舞狮头 讨糖南瓜灯 插茱萸赏菊 放河灯 萌化小幽灵 装点圣诞树 放孔明灯 吃汤圆 吃饺子

**文字**

是啊，吃什么 深度思考碎碎念

**点击回应**

点击回应-开心跃动 点击回应-害羞惊讶 点击回应-傲娇生气 点击回应-挠痒咯咯笑 点击回应-元气挥手

**拖拽**

被鼠标拖拽悬空反馈

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

余额-钱袋满溢 余额-金袋叮当 余额-钱袋如常 余额-数金皱眉 余额-袋空如洗 余额-分文不剩

**碎碎念说话动画**（碎碎念 / 对话回复触发，随机抽 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/ # 双端共用纯逻辑（物理 / 菜单 / 取数） │ │ └── standalone/ # 独立模式 CLI（不依赖 DSH 直接跑桌宠） │ ├── lib/ # 构建产物（npm run build 生成，不入库） │ ├── runtime/ # 桌面模式运行壳（Electron 透明窗） │ ├── assets/ # webm 动画 / preview GIF / 字体 / 图标 / config.jsonc 默认配置 │ └── scripts/ # 构建、发布与开发脚本 └── LICENSE # MIT ``` ## 相关项目 - **[aipets](https://github.com/kallen-noelle/aipets)** —— Windows 11 桌面宠物，五个角色可多开，透明置顶、点击穿透、甩动带惯性。特色在**动作由大模型决定**：每轮对话后模型结合时间、天气、电量与好感度挑动作，无人说话时还能排出接近一整天的编排，模型不可用时回退内置规则。聊天接任意 OpenAI 兼容接口，带长期记忆、贴纸、画图与工具调用（联网搜索 / Home Assistant / MCP），支持语音朗读与语音输入；同一套代码既有单文件 `aipets.exe` 桌面版，也有浏览器里的整页舞台版。 ## 💬 反馈与发版节奏 欢迎提 [issue](https://github.com/PC2005-cloud/dsh-pet/issues) 与 PR——bug、体验问题随时反馈。**新功能请先开 issue** 说明使用场景，确认后再动手，不要在确认前直接提交实现 PR。这个插件专注桌宠与 DSH 本身，偏离太远的需求一般不会做。动手前也请先翻一眼 [提交记录](https://github.com/PC2005-cloud/dsh-pet/commits/main)，确认不是已经修掉的同款问题（有些问题可能已经在 `main` 上修好了，只是还没发版）。 - **小修不单独发版**：不影响使用的小 bug 与优化会**累计**到下一个版本一起发，避免版本更迭过于频繁。所以「`main` 上已经修了」不等于「你装的这版已经包含」——`latest` 没更新时，以 `main` 的提交记录为准。 - **想立刻用上未发布的修复**：按 [INSTALL.md](INSTALL.md) 的「从源码安装」把插件指向本地仓库即可；注意**宿主半侧**的代码改动要**重开 DSH** 才生效（浏览器半侧刷新页面即可）。 - **报 bug 时请带上**：插件版本、`dsh` 版本、操作系统、复现步骤（有日志或截图更好）。 ## 许可 - 代码：MIT - 素材（动画/提示词/源视频）：允许开源使用，具体授权参考角色原型的形象授权（见下方「形象授权」） - **二次创作（二创）约定**：基于本项目的衍生 / 改版 / 换皮作品，在 **GitHub 仓库、产品官网等公开渠道**上须附上原作者 GitHub 地址： - **形象出处**：宠物形象为社区二创的 DeepSeek「大肥鱼」（鲸鱼娘），**非 DeepSeek 官方形象**；原型「溟月」出自 B 站 [@上善无形](https://space.bilibili.com/4456176)，DeepSeek 版（女仆鲸鱼娘）设计出自 B 站 [@ZipZipPipe](https://space.bilibili.com/4168597) - **形象授权**：[CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/deed.zh-hans)（署名 · 非商业 · 相同方式共享），[声明原文](https://www.bilibili.com/opus/1247156596114456581)：「大肥鱼是遵守CC BY-NC-SA 4.0协议的形象，不可以以任何形式商业化。若您非常喜爱该形象，希望其拥有实体，您可以自行定制。」