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.7K ·GitHub
Dsh-pet
What is this?dsh-pet is a transparent animated desktop pet plugin for DeepSeek Harness (DSH): it idles, naps, solves a Rubik's cube, codes, eats hot pot and more across 97 hand-drawn animations, with click/drag physics and an optional balance-display bubble.
Is this a standalone app or something I add to DSH?It's a plugin for the DSH agent harness, not a standalone app. It runs by default inside the DSH web interface, but can optionally break out into its own transparent, always-on-top Electron window per pet.
Do I need DSH already running to use this?Yes — dsh-pet is built on top of an existing DSH installation and was developed/tested against dsh 0.1.1-rc.2. For the optional desktop overlay it also needs Electron, which the plugin auto-downloads to ~/.dsh/electron/ if it isn't already installed.
Does the desktop overlay still work if DSH Desktop blocks plugin network requests?Yes — the desktop window talks to the host through its own process-pipe bridge instead of DSH's HTTP routes, so it isn't affected by newer DSH Desktop versions that gate plain HTTP requests from plugin subprocesses.
Does the desktop overlay work the same on Windows, macOS, and Linux?It's Electron-based so it runs cross-platform, but the window is deliberately never full-screen because a fullscreen transparent layered window triggers a black-screen bug in Windows' DWM compositor.
Can I create a totally custom pet species instead of the default one?Yes — the 'pet pack' system lets you add a new species with its own config file and animation folder under $DSHHOME/dsh-pet/pet/, and the project's built-in DIY material chain can even generate the custom animation set via AI video.
What does the balance display feature actually show?It polls your configured LLM provider (DeepSeek official or OpenCode Zen Go) and reflects account balance or quota usage as a six-tier pet animation plus a thought-bubble popup that auto-hides after 10 seconds.
How many animations does the pet ship with?97 hand-drawn, transparent VP9-alpha animations covering idle breathing, dozing, solving a Rubik's cube, coding, eating hot pot and more, chained seamlessly via weighted random selection.
Can I actually interact with the pet, or is it just decorative?You can click it for a bouncy squash reaction, drag-and-throw it with spring physics and screen-edge bouncing, or right-click for a cascading menu to trigger specific animations on demand.
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.7K
Updated
CommitOct 17Releasev0.3.7Oct 14
Age
2mo
Commits · 90 Days