📄 仓库 README

来自 GitHub 仓库自述文件 · 版权归原作者所有

dsh-pet 🐾

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

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

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

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

快速开始（安装插件）

两种装法，任选一种：

图形化（桌面应用内）：打开「插件管理」页，在安装框里填 dsh-pet，不用开终端。
命令行：dsh plugin --profile <profile> add dsh-pet，<profile> 按你在用的界面填——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 弹挤压手感，参数可调。
碎碎念与对话：按周期自动说一句，也能随时聊；记忆持久化、可配图、可念出来。
余额展示：内置常见服务商的余额 / 额度查询，按剩余额度分档播动画并弹气泡；也可以登记自己的服务商。
工作状态联动：跟随 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/HEVC 兼容素材」）
多显示器：支持多屏环境——跨屏漫游/抛掷以各屏工作区为界，异构缩放（各屏 DPI 不同）、任务栏条带、屏幕之间空洞均正确判定（横屏 / 竖屏 / 上下叠放皆可）；设置页「锁定在当前屏幕」可让宠物（抛掷与漫游）只在当前所在那块屏内活动