dsh-pet README

The project's README from github.com/PC2005-cloud/dsh-pet. As one markdown file: README.md.

dsh-pet 🐾

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

一只住在 DeepSeek Harness 里的桌面宠物：待机呼吸、随机动作（打瞌睡、玩魔方、写代码、吃火锅……97 个手绘风透明动画随时无缝衔接）、左右转向、屏幕漫游、点击 Q 弹、拖拽甩抛反弹、右键菜单点播动作、余额动画 + 头顶联想气泡——可多开同屏，能脱离浏览器住上桌面（透明置顶小窗），也能自己添加全新宠物种类（pet pack）。

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

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

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

快速开始（安装插件）

以下命令都在你的命令行终端（PowerShell / CMD 等）中运行。前提是 DSH 环境已就绪：

# ① 前置要求：确认 Node.js 已安装
node -v

# ② 安装 DSH 启动器与 pnpm（已装可跳过；装完请重新打开终端）
npm install -g @deepseek-ai/dsh pnpm
dsh --version   # 验证 dsh 命令可用

# ③ 安装本插件
dsh plugin --profile web add dsh-pet

重启 dsh web，宠物出现在界面右上角（默认配置角落，可在设置页修改）。

兼容性：本插件在 dsh 0.1.1-rc.2 下开发并测试（dsh --version 可查看你的版本）。建议使用相同版本；其他版本如遇问题欢迎反馈。

从源码安装（clone 本仓库后）

lib/ 构建产物不入库，clone 后需要先构建再安装：

# ① clone 本仓库，进入插件目录
git clone https://github.com/PC2005-cloud/dsh-pet.git
cd dsh-pet/dsh-pet

# ② 安装依赖
npm install

# ③ 构建（tsdown → lib）
npm run prepare     # 构建完整 lib（npm install / npm publish 时会自动执行）

# ④ 安装到 DSH（file: 指向本目录，用构建好的 lib）
dsh plugin --profile web add file:D:/path/to/dsh-pet

注：prepare（npm install / npm publish 时自动执行，也可手动 npm run prepare）才产出完整可安装的 lib——除 tsdown 构建外还构建桌面共享核心（shared-core.js）、生成类型声明并收敛发布 files 清单；裸 tsdown 构建会缺桌面运行时与类型。

插件功能

🪟 桌面模式（可选，脱离浏览器）

插件内建双模式：安装后默认会拉起独立透明置顶窗口——为每只桌面宠物各开一个局部小窗口（尺寸 = 宠物包围盒 + 四周外扩余量，为气泡/弹窗预留空间，跟随宠物移动；永不铺满屏幕：全屏透明分层窗会触发 Windows DWM 视频合成黑屏）。与浏览器 overlay 严格同行为——同一份纯逻辑源码（dsh-pet/src/shared/），两端的功能/动画/文案/配置完全对齐，不会出现"一个有另一个没有"：

⚙️ 余额展示（Balance）

余额是"事件动画"的一种：运行时按 eventsRefreshSec.balance（秒）周期拉取当前服务商（跟随 agent-default-model 的 provider）的余额/用量数据，每次刷新按档位触发一次余额动画，并在宠物头顶弹出联想气泡（气泡为角色"思考"式白泡，随宠物大小等比缩放，10 秒后自动消失）：

⚙️ 配置（大小 / 位置 / 多开）

桌宠的大小、位置、多开均可配置，两条途径：

💡 两条途径只是编辑入口不同，最终都是同一份用户配置——配置能力远不止设置页那几个选项：设置页可改大小/位置/边距/显示位置/余额开关/多开，但手动编写配置文件可以任意自由配置（动画池、播放权重、事件动画、刷新周期……），只要格式与包内默认配置 config.jsonc 一致即可，用户配置会整体覆盖对应字段的默认值。

方式一：设置页（推荐）

DSH 设置 → 「桌宠配置」：

方式二：config.jsonc（单一来源）

插件包内 dsh-pet/assets/config.jsonc 的 pets 数组定义默认宠物：

"pets": [
  { "id": "main", "size": 462, "balanceEnabled": true, "display": "both", "position": { "corner": "top-right", "marginX": 24, "marginY": 100 } }
]

方式三：手动编辑配置文件（高级，任意自由配置）

用户层配置文件位于 $DSH_HOME/dsh-pet/main-config.json。它和包内默认配置是同一套格式——想改什么直接照着 assets/config.jsonc 的结构写即可，写错的字段/缺失的字段回落默认，无需（也无法）写完整份：

字段 作用 格式与默认一致即可
pets 宠物列表（大小/位置/多开/余额开关） 数组，每项同 pets[] 结构
animations 动画池：idle / turn / drag / clicks / moves / categories / events（余额等事件动画） 同 animations 结构
animationWeights 动画链播放权重（idle / turn / move） 同 animationWeights 结构
eventsRefreshSec 事件刷新周期（秒） 同 eventsRefreshSec 结构
notificationsEnabled 系统通知总开关（布尔） 同 notificationsEnabled

覆盖语义：用户层给出即整体替换该字段（如写了 animations 就用你的整份动画池，替代默认），没写的字段回落包内默认。校验在插件加载时执行——格式错误会在 DSH 控制台显式报错，不会静默运行残缺配置。

方式四：额外宠物（pet pack）——添加新「种类」

方式一~三都只调整默认宠物的实例（数量/大小/位置），动画池始终是全局一份。要添加全新种类的宠物（独立动画池 + 自己的素材），在用户数据根下建 pet/ 目录：

$DSH_HOME/dsh-pet/
├─ main-config.json            ← 主宠物配置（现有，不动）
├─ main-animation/webm/*.webm  ← 主宠物素材（现有，只属于 main）
└─ pet/
   ├─ pig-config.json          ← 额外宠物 pig 的配置（命名词干 = 种类名，实例 id 任意）
   └─ pig-animation/*.webm     ← pig 自己的动画素材（直接平铺，仿 main-animation）

每只额外宠物 = 一个 -config.json + 一个 -animation/ 目录，同前缀配对；扫描 pet/ 自动发现，浏览器与桌面同时生效。一个 -config.json 定义一个「种类」（动画池 + 素材目录），pets 数组可放该种类的任意多只实例（共享动画池与素材）：

// pet/pig-config.json —— 与 main-config.json 同构的完整配置
{
  "notificationsEnabled": true,
  "pets": [
    {
      "id": "pig1",              // 实例 id（可多只；不必等于文件名前缀）
      "size": 420,
      "balanceEnabled": true,
      "display": "both",        // web / desktop / both / none
      "position": { "corner": "top-right", "marginX": 24, "marginY": 100 }
    },
    { "id": "pig2", "size": 360, "balanceEnabled": false, "display": "web", "position": { "corner": "top-left", "marginX": 24, "marginY": 100 } }
  ],
  "animations": {
    "idle": ["待机"], "turn": [], "drag": [], "clicks": ["打滚"],
    "moves": { "default": { "minDist": 80, "maxDist": 360, "margin": 20, "leadSec": 2, "tailSec": 2 }, "actions": [] },
    "categories": [],
    "events": { "balance": ["余额-钱袋满溢", "余额-金袋叮当", "余额-钱袋如常", "余额-数金皱眉", "余额-袋空如洗", "余额-分文不剩"] }
  },
  "animationWeights": { "idle": 80, "turn": 0, "move": 0 },
  "eventsRefreshSec": { "balance": 1800 }
}

规则（与主宠物严格隔离，绝不混用）：

运行效果

宠物实际运行在 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，唯一发布格式）：

待机 / 转向

待机呼吸休闲 东张西望

移动

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

小动作

悠闲哼歌 超大伸懒腰 原地敲击桌面互动

dsh-pet (PC2005-cloud/dsh-pet)

Searching Database…

1.8K ·GitHub
Dsh-pet
Что это?dsh-pet — плагин прозрачного анимированного питомца для рабочего стола в DeepSeek Harness (DSH): он бездельничает, дремлет, собирает кубик Рубика, программирует, ест хого и не только — 97 рисованных анимаций, физика кликов и перетаскивания и опциональный пузырь с отображением баланса.
Это отдельное приложение или дополнение к DSH?Это плагин для agent-оболочки DSH, а не отдельное приложение. По умолчанию он работает внутри веб-интерфейса DSH, но при желании может выйти в собственное прозрачное окно Electron поверх всех окон — по одному на питомца.
Нужен ли уже работающий DSH?Да — dsh-pet строится поверх установленного DSH и разрабатывался и тестировался с dsh 0.1.1-rc.2. Для опционального десктопного оверлея нужен ещё Electron, который плагин автоматически скачает в ~/.dsh/electron/, если его ещё нет.
Будет ли работать десктопный оверлей, если DSH Desktop блокирует сетевые запросы плагинов?Да — окно на рабочем столе общается с хостом через собственный мост на process-pipe вместо HTTP-маршрутов DSH, поэтому его не затрагивают новые версии DSH Desktop, ограничивающие обычные HTTP-запросы из подпроцессов плагинов.
Одинаково ли десктопный оверлей работает на Windows, macOS и Linux?Он на Electron, поэтому кроссплатформенный, но окно намеренно никогда не бывает полноэкранным: полноэкранное прозрачное многослойное окно вызывает баг чёрного экрана в композиторе DWM Windows.
Можно ли создать полностью свой вид питомца вместо стандартного?Да — система «pet pack» позволяет добавить новый вид со своим конфигом и папкой анимаций в $DSHHOME/dsh-pet/pet/, а встроенная DIY-цепочка материалов проекта умеет даже сгенерировать набор анимаций через ИИ-видео.
Что именно показывает функция отображения баланса?Она опрашивает настроенного провайдера LLM (официальный DeepSeek или OpenCode Zen Go) и отражает баланс аккаунта или расход квоты шестиступенчатой анимацией питомца плюс всплывающий пузырь с мыслью, который сам скрывается через 10 секунд.
Сколько анимаций у питомца из коробки?97 рисованных прозрачных анимаций в VP9-alpha: дыхание в простое, дремота, сборка кубика Рубика, программирование, поедание хого и другое, бесшовно связанные взвешенным случайным выбором.
С питомцем можно реально взаимодействовать или он чисто декоративный?По нему можно кликнуть, чтобы получить пружинистую реакцию сжатия, перетащить и швырнуть его с пружинной физикой и отскоком от краёв экрана или кликнуть правой кнопкой — появится каскадное меню для запуска конкретных анимаций по запросу.
What are similar projects?dsh-dafeiyu, dsh_desktop, Bigfish, deepseek-harness-desktop, EAC-Desktop, DSH-Launcher, cocode, oh-dsh
Which topics is it in?desktop-pet, dsh, dsh-plugin, deepseek-harness, video-generation, electron, animation, customization, plugin, desktop, gui, desktop-app
Creator
PC2005-cloud
Size
131.1 MB
Stars
1.8K
Updated
CommitOct 18Releasev0.3.7Oct 14
Age
2mo
Commits · 90 Days