给编程助手养一只会动的透明桌宠（dsh-pet）

在 DSH 里挂着任务跑的时候，界面能给到的只有文字流。助手是在思考、在等权限，还是已经收尾，得盯着输出自己判断。dsh-pet 把这些状态搬到一只动画宠物身上：它待在界面角落或者桌面的透明小窗里，按会话事件切动作，任务真正收尾的那一轮才庆祝。

dsh-pet 是 DeepSeek Harness 的桌面宠物插件，用 TypeScript 写成，装好后在网页界面或桌面透明置顶小窗里播放透明动画宠物，跟随会话状态切动作，也能多开与自造素材。

仓库里放的不只是插件。prompts/ 是生成动画的提示词配方，video/ 与 assets/ 是素材，tools/ 是配套工具，README 把这三部分合称三件套：提示词（配方）、素材生成链（源视频到透明动画的管线）、插件（成品）。换角色、换风格、换动作的过程在仓库内可复现，这是它和只提供一个固定形象桌宠的插件最大的区别。

它怎么做到的

插件以 DSH 插件的形式装进 profile，宿主半边跟着 DSH 的进程走，在 DSH 自己的 Web 服务上挂一组路由，前缀是 /dsh-pet-7340。前端 overlay 负责把宠物画出来，素材是 VP9-Alpha 编码的 .webm 透明动画，配置从 $DSH_HOME/dsh-pet/main-config.jsonc 读，读不到就回落到包内默认。DSH 把会话事件推过来，插件把事件映射成思考、工作、整理、等待、成功、出错六个档位，播放对应动画并挂上常驻气泡。

桌面模式另起一个 Electron helper 进程，每只宠物一个跟随移动的透明置顶局部窗口，不铺满屏幕，和浏览器 overlay 的行为对齐。拖拽、甩抛、落地摩擦这一套物理在浏览器端和桌面端共用同一份纯函数源码 dsh-pet/src/shared/physics.ts。事件订阅的具体接口与权重表的完整默认值，仓库未展开说明。

几个关键设计

插件功能清单

• 多开：同时显示多个宠物，各自独立大小与位置，在设置页「桌宠配置」里添加或删除。
• 屏幕漫游：朝当前朝向行走，先探测空间再走，不走出屏幕；多屏按各屏边界判定。
• 点击 / 拖拽 / 甩抛：点击触发回应动画并 Q 弹挤压；拖拽走阻尼弹簧跟手，甩出后抛物线飞行、碰屏幕边缘反弹、落地摩擦停稳并再 Q 弹一下。
• 右键菜单：按「动作 → 分类 → 具体动画」点播，移动类动画点播会真的走一段；浏览器端是碎碎念、对话、回到初始位置，桌面端再加打开网站、查看余额、重载配置。
• 余额展示：按已用百分比分档播动画，头顶弹联想气泡，10 秒后消失；每只宠物用 pets[i].balanceEnabled 单独开关。
• 碎碎念与对话：pets[i].whisperEnabled 开启后按 eventsRefreshSec.whisper（默认 300 秒）周期生成一句，记忆在浏览器与桌面之间共享同一份。
• 工作状态联动：监听 DSH 会话事件，切六个档位动画并挂常驻气泡；多轮任务只在真正收尾的轮次庆祝。
• 系统通知：窗口失焦时弹系统 toast，覆盖对话完成、生成失败、输出截断、权限申请、用户选择几种情况。

无障碍方面支持 prefers-reduced-motion，开启减少动效后会跳过 Q 弹挤压与淡入切换。

双形态运行与独立模式

安装后默认会拉起桌面透明小窗。开关是每只宠物的必填字段 display，取值 web 表示只在浏览器、desktop 表示只在桌面、both 表示两边都显示、none 表示都不显示。桌面端的数据走独立进程管道，不依赖 DSH 的 HTTP 路由。

独立模式让插件的宿主半边跑在一个伪 ctx 上，由一个本机 HTTP 服务接管路由，路由表仍然是插件自己那一份。启动方式是先 npm install -g dsh-pet（必须用 npm 装，dsh plugin add 装进 profile 的 bin 不在 PATH 上），再跑 dsh-pet-standalone，默认地址 http://127.0.0.1:3080/dsh-pet-7340/，端口被占用则顺延。可以用 --check 只体检，用 --port 换端口，退出靠 Ctrl+C 或 POST /shutdown。这种模式下余额、碎碎念、对话、系统通知四项不可用，接口会返回带 reason 的结构化失败。

动画链与档位触发

每个动画播完就按权重选下一个，待机也算在内，默认权重是 idle 10、turn 5、move 5 再加分类权重，写在 config.jsonc 里可以调。事件动画按档位触发，档位支持候选数组，触发时在档内随机、循环播放自动轮换，避免一直播同一段。切换用双缓冲交叉淡入，中间不留空白帧。

加新动画的方式是把 VP9-Alpha 的 .webm 放进 main-animation/webm/，这部分素材优先于包内自带的。加全新宠物种类（pet pack）则是在 pet/ 下建 种类名-config.json 加 种类名-animation/ 目录，多实例共享同一份素材。

对外 HTTP 接口

接口挂在 DSH 自己的 Web 服务上，前缀同样是 /dsh-pet-7340，只监听本机，没有鉴权。能做的事包括让它说一句指定的话、播一段指定动画、与它对话，以及读它当前说的话、工作状态、系统通知与余额。动作类接口只回 {ok}，数据统一从 GET /state 读。

三个配套文件：API.md 是接口一览，每个接口一句话；openapi.yaml 是完整的 OpenAPI 3.1 契约，可以直接导入 Swagger UI 或 Postman；tools/api-tester.html 是一个扮演第三方消费方的示例页面，用 node tools/api-tester.cjs 启动后可以直观试用。

这样设计的代价

和 DSH 版本强绑。v0.3.0 起 peerDependencies 从 ^0.1.1-rc.2 提到了 ^0.2.0-rc.1，dsh 0.1.x 不再适配，插件当前在 0.2.0-rc.2 下开发并测试。升级顺序是先升 DSH 再更新插件，反过来做会直接报依赖不兼容。

浏览器支持有明确边界。透明动画依赖 VP9-Alpha 的 webm，Chromium 内核与 Firefox 都实测确认能透明，Safari 不支持：macOS 不认 webm alpha，会把透明部分渲染成黑底。要在 macOS 上用，得改用 .mov 素材（GitHub Release 的 assets-mov），下载放入后改 ANIMATION_EXT 变量。夸克这类套壳内核也曾出现过黑背景遮挡界面的情况。

桌面模式要额外下载运行时。Electron 由插件首次启动时自动探测或下载到 ~/.dsh/electron/，也可以手动跑 npm run ensure:electron。仓库体积 134049 KB，按 GitHub 的算法约 131 MB，大部分是素材与视频。

本地接口没有鉴权。接口只监听本机，但没有鉴权层，同机上的其他进程可以调用它读状态、驱动宠物。别把端口暴露到本机之外。

两条运行路径会共用缓存目录。独立模式与 DSH 内运行可以同时开，但共用 %APPDATA%\dsh-pet-electron-helper，可能互相踩缓存，仓库说明里这种情况只给告警。

可选能力依赖外部凭据。余额只登记了三家服务商：deepseek-official 显示账户余额，opencode-go 与 commandcode 显示 5h/周/月三个额度窗口里最先告急的那一个，凭据分别是 DEEPSEEK_API_KEY、OPENCODE_GO_API_KEY、COMMANDCODE_API_KEY。未登记的服务商不播档位动画，改成弹一句文字说明并报出当前 provider id。

同类桌宠的定位差异

如果你的 DSH 停在 0.1.x，或者主力浏览器是 Safari 又不想折腾 .mov 素材，装 dsh-pet 会比预期麻烦，dsh-whale-musume 的说明里写明支持旧版 Web，这种场景它更省事。只想在网页里放一只跟随鼠标的 Live2D 形象，dsh-pet-live2d 是更直接的选择，它在 Web GUI 里工作，不涉及 Electron 下载和桌面窗口，代价是没有脱离浏览器的那一层。

对你的实际影响

先把安装走一遍。前置是 Node.js，命令都在终端里跑：

node -v
npm install -g @deepseek-ai/dsh pnpm
dsh --version
dsh plugin --profile desktop add dsh-pet

--profile 填你实际在用的那个，桌面应用填 desktop，dsh web 用户填 web。装完必须重开桌面应用或重启 dsh web，运行中的进程持有内存里的旧插件。宠物默认出现在界面右上角。

改配置后不用回设置页点保存，桌面端右键宠物选「重载配置」，全部桌面宠物窗口会按最新配置重建，它走的是和保存同一条重启路径。独立模式则用 npm install -g dsh-pet 加 dsh-pet-standalone，看结果的地方是 http://127.0.0.1:3080/dsh-pet-7340/；接口取数看 GET /state，更直观的是打开 tools/api-tester.html 那个控制台。

机器方面，桌面模式需要能跑 Electron 的环境；无头 Linux 这类没有图形会话的机器，插件会探测不到 DISPLAY 或 WAYLAND_DISPLAY，自动跳过桌面窗口只留日志告警，浏览器 overlay 不受影响。

多屏环境可用，跨屏漫游和抛掷以各屏工作区为界，异构缩放、任务栏条带、屏幕之间的空洞都会判定，横屏竖屏上下叠放都行。这类场景历史上出过问题：右键菜单在屏幕边缘被裁剪、拖到另一块屏时动画来回闪现，都属于已解决的 Issue。

主题插件冲突值得留意。带全屏效果层的主题或皮肤插件，其效果层 z-index 可以到 21 亿级，会把宠物完全盖住，宠物本身其实工作正常。这条也已经修复。

自造宠物的门槛在素材侧。仓库给了 prompts/ 与 video/ 两套东西，但要把一段源视频转成可用的透明动画，仓库没有说明一键脚本这一步，得自己对着目录和文档摸索。

想做二次开发的话，对外的 HTTP 接口够用，别的插件可以让桌宠替它开口说话。接口无鉴权，别把端口往外暴露。

适合谁：同时使用网页端和桌面端 DSH、想要多只宠物同屏、需要屏幕漫游和拖拽物理、或者打算自己造一个新宠物的人。

不适合谁：主力浏览器是 Safari 且不愿意换素材格式的人；DSH 版本停在 0.1.x 又不打算升级的人；只想要一个静态看板娘、不想引入 Electron 下载的人。

仓库在 https://github.com/PC2005-cloud/dsh-pet，MIT 许可证，主要语言 TypeScript，仓库 Topics 是 deepseek-harness、desktop-pet、dsh、dsh-plugin，Star 1066，Fork 80，开放 Issue 3 个。

焚评：这个项目的量化评分

本项目的选题来自 焚.com（一个按公开公式给 GitHub 项目打分的站）。焚评当前总分 9.4 分（满分 10）。下表是各维度的得分：

评分口径、权重与计算方式见焚.com 的评分方法页；数据随 GitHub 指标刷新，具体数值以焚.com 当前页面为准。本文正文为诀.com 独立撰写，评分数据由焚.com 授权引用。