dsh-pet 🐾

A desktop pet that lives inside DeepSeek Harness: idle breathing, random actions (dozing off, playing with a Rubik's cube, eating hot pot…), left/right turning, on-screen wandering, click with Q-bounce, drag-and-toss with bouncing, right-click menu on-demand—over a hundred hand-drawn transparent animations seamlessly chained together; it can also follow DSH session events to switch work-status animations, play balance-tier animations + overhead speech bubbles, mutter and converse with you, and pop system notifications when the window loses focus. Multiple instances can share the same screen, it can live on the desktop independent of the browser (a transparent always-on-top mini window), and you can add brand-new pet species (pet packs).

This is not just a regular plugin, but a complete three-piece project:

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

Anyone who clones this repo can generate their own desktop pet from scratch—swap characters, swap actions, swap styles; the whole pipeline is reproducible.

---

Quick Start (Installing the Plugin)

All the commands below run in your command-line terminal (PowerShell / CMD, etc.). Prerequisite: the DSH environment is already set up:

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

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

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

Restart dsh web, and the pet appears in the top-right corner (default; adjustable in settings).

Compatibility: this plugin is currently developed and tested on dsh 0.1.5-rc.1 (check your version with dsh --version). It is recommended to use the same version; if you run into issues on other versions, feedback is welcome.

Installing from Source (after cloning this repo)

lib/ build artifacts are not committed; build before installing after cloning:

# ① 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

Note: prepare (runs automatically on npm install / npm publish, and can also be invoked manually via npm run prepare) produces the fully installable lib—beyond the tsdown build, it also builds the desktop shared core (shared-core.js), generates type declarations, and finalizes the published files manifest; a bare tsdown build will be missing the desktop runtime and types.

Plugin Features

• Pure desktop pet: no weather, monitoring or other irrelevant features; never touches the DSH kernel. Optional capabilities: balance / whispers / chat / work status / system notifications
• Animation chain: when each animation (incl. idle) finishes, the next is picked by weight (defaults: idle 10 / turn 5 / move 5 + category weights, tunable via config.jsonc); segments connect head-to-tail seamlessly
• Event animations: balance / whisper / work status trigger tier-specific animations; a tier supports a candidate array — random pick on trigger, auto-rotation on loop to avoid back-to-back repeats
• Multi-instance: multiple pets visible simultaneously, each with independent size and position (add/remove via "Desktop Pet Config" on the settings page)
• Screen roaming: walks toward its facing direction, probes space first, never walks off-screen (multi-monitor: per-screen boundary checks)
• Click / drag / toss: click triggers a response with a squishy bounce; drag follows with an overdamped spring; toss = parabolic flight, screen-edge bounces, friction stop + one final squish; gentle placement stops in place; both ends share the same pure-function physics and squish curves (dsh-pet/src/shared/physics.ts)
• Right-click menu: "Action → Category → Specific Animation" on-demand (movement animations actually walk); tools — browser: whisper / chat / return to start; desktop: + open website, check balance (shown when balance enabled)
• Facing & landing: all animations can be mirrored (left / right); unified foot baseline keeps the pet grounded
• Smooth transitions: dual-buffer cross-fade, zero blank frames
• Balance display: tiered balance animations by used % + overhead bubble (10 s auto-dismiss); DeepSeek shows account balance, OpenCode Zen Go shows the most urgent quota window; providers without a balance endpoint show a text note instead (no silent failure); per-pet toggle
• Whispers & chat: whispers auto-generate on a cycle (talking anim + bubble, also manually triggerable); chat via right-click input box, persistent memory (browser / desktop share one copy)
• Work status: listens to DSH session events, switches "thinking / working / organizing / waiting / success / error" tier animations + persistent bubble; multi-turn tasks celebrate only on the true final round
• System notifications: system toast on window blur (chat done / gen failed / output truncated / permission request / user selection)
• Desktop mode (optional): each pet in its own transparent always-on-top small window, strictly matching browser behavior, sharing the same assets and pure logic (see next section)
• pet pack (new species): create 种类名-config.json + 种类名-animation/ under pet/ to add a new species with its own animation pool and assets, shared across instances (see "Config → Method 4")
• Custom animations: drop VP9-Alpha .webm into main-animation/webm/ for new animations, taking priority over bundled assets
• Accessibility: supports prefers-reduced-motion (skips squish bounce and fade-in when reduced motion is preferred)

Compatibility

• Operating systems: runs on all three—Windows / Linux / macOS—the browser overlay and desktop mode (Electron transparent always-on-top window) behave identically; Electron is auto-detected/downloaded per platform (electron.exe / Electron.app / linux single-file), no manual installation needed
• Headless / no desktop environment: supports graphless sessions like Linux headless—desktop mode auto-detects the display environment (when DISPLAY / WAYLAND_DISPLAY is absent on Linux, it's judged as no display, desktop windows are skipped, and only a log warning is emitted); the browser overlay is unaffected
• Browsers: the browser overlay is compatible with Chromium-based browsers (Chrome / Edge, etc.) and Firefox—transparent animations rely on VP9-Alpha webm, verified transparent on all three; Safari is not supported (macOS doesn't recognize webm alpha; transparency renders as a black background)—on macOS use .mov assets (GitHub Release assets-mov), download and place + change the ANIMATION_EXT variable (see "②.5 Safari/HEVC-compatible assets")
• Multi-monitor: multi-screen setups supported—cross-screen wandering/tossing uses each screen's workspace as the boundary; heterogeneous scaling (different DPI per screen), taskbar strips, and gaps between screens are all handled correctly (landscape / portrait / vertical stacking all work)

🪟 Desktop Mode (Optional, Browser-independent)

The plugin ships with dual modes: by default it launches independent transparent always-on-top small windows — one local window per desktop pet (follows the pet, not full-screen), strictly matching browser overlay behavior:

• Dependency: Electron is auto-detected/downloaded on first launch (~/.dsh/electron/, can also be triggered manually with cd dsh-pet && npm run ensure:electron); if missing, only a log warning is emitted; the browser form is unaffected
• Toggle = per-pet required field display: web = browser only / desktop = desktop only / both = both / none = neither; desktop mode renders all pets whose display includes desktop (multiple instances share the screen, consistent with the browser), edits on the settings page "Desktop Pet Config" take effect immediately
• Desktop-side data flows through an independent process pipe; it doesn't depend on DSH's HTTP routing and is unaffected by web access gates
• Local debugging: cd dsh-pet && npm run start:desktop -- http://127.0.0.1:3080/dsh-pet-7340/config (auto-falls back to the HTTP path when no host is available)

⚙️ Balance Display

Periodically fetches the current provider's balance/usage data every eventsRefreshSec.balance (seconds); each refresh triggers a balance animation per tier and pops an associative bubble above the pet's head (scales proportionally with the pet's size, auto-disappears after 10 seconds):

• DeepSeek official (deepseek-official): bubble shows account balance (e.g. 余额 ¥8.79); balance converted to used % on a ¥20 full scale, played across 6 tiers (overflowing bag → tinkling gold bag → normal bag → counting & frowning → empty bag → penniless)
• OpenCode Zen Go (opencode-go): bubble shows the most urgent of the 5h/weekly/monthly quota windows (e.g. 周额度已用 88% / 2.5 天重置), also tiered by used %
• Unsupported providers: providers without a balance endpoint (e.g. commandcode) skip tier animations and show a text note instead — line 1: "current provider does not support balance queries", line 2: reports the provider id (for self-diagnosis); missing credentials / fetch failure work the same. Auto-poll pops up only when the reason changes; manual /balance or desktop right-click "Check Balance" pops up every time
• Per-pet toggle: pets[i].balanceEnabled (required boolean) controls whether this pet triggers balance animations / shows the bubble
• Required credentials: the provider's API key (deepseek-official → DEEPSEEK_API_KEY; opencode-go → OPENCODE_GO_API_KEY), set in DSH credentials to enable; unmatched providers don't trigger animations, show the text-note bubble instead

⚙️ Muttering and Conversation

• Whispers: with pets[i].whisperEnabled turned on, a line is auto-generated on a eventsRefreshSec.whisper (seconds, default 300) cycle — each pet has its own cycle and its own copy; on trigger, it randomly picks a events.whisper animation + a talking bubble over the head (dismisses in 10 seconds). Off by default
• Manual trigger: right-click menu "Whisper" pops a line at any time — not gated by whisperEnabled (that field only disables the automatic cycle polling)
• Chat: right-click menu "Chat" or the /chat command opens the input box to chat with the pet — replies use the same presentation as whispers (talking animation + bubble); memory is persisted at $DSH_HOME/dsh-pet/memory.json, shared between browser and desktop; with multiple pets, first use /pet to select the chat target

⚙️ Work Status Linkage

When pets[i].workStatusEnabled is enabled, the pet follows DSH session activity to switch among the six tiers "thinking / working / tidying / waiting / success / error" animations + overhead bubble: non-terminal animations loop with a persistent bubble; success / error play once with the bubble auto-retracting after 10 seconds.

• Tier animations: the animations.events.workStatus array, where the index is the tier (do not insert a new tier in the middle; only append to the end)
• Bubble copy: workStatusTexts can hold multiple random lines per tier; task details (todo) take priority
• Tier candidate arrays: any tier slot can be written as string | string[]—array = random pick 1 within the tier, looping playback auto-rotates to avoid replaying the same segment back-to-back (applies to balance / mutter tiers as well)

⚙️ Configuration (Size / Position / Multiple Instances)

Configure pet size, position, multi-instance: two ways:

💡 The two paths differ only in editing entry point; they all write to the same user config — capability goes far beyond the settings page: settings page covers size/position/margin/corner/balance toggle/multi-instance, but manual config editing allows fully free configuration (animation pool, weights, event animations, refresh cycles…), as long as the format matches the bundled default config.jsonc; user config fully overrides defaults for each field.

Method 1: Settings Page (recommended)

DSH settings → "Desktop Pet Config":

• Size: width in px (height auto = width × 9/16)
• Position: four corners (corner) + horizontal/vertical margins (marginX / marginY)
• Display location (display): web = browser only / desktop = desktop only / both = both / none = neither
• Balance feature: once checked, that pet triggers balance animations and shows the balance bubble (providers without a registered balance API instead show a text-note bubble)
• Multiple instances: add/remove pets, each with its own independent id, size, and position
• Clicking "Save" takes effect immediately (no refresh needed); "Restore Defaults" reverts to the config.jsonc defaults

Method 2: config.jsonc (single source of truth)

The pets array in dsh-pet/assets/config.jsonc inside the plugin package defines the default pets:

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

• Per pet: id (identifier) / size (width px) / balanceEnabled (whether to enable the balance feature, required boolean) / display (web/desktop/both/none, required, see above) / position (one of the four corners + marginX/marginY margins)
• Balance refresh cycle: eventsRefreshSec.balance (seconds)—the interval between balance data refreshes and balance animation triggers; triggers once immediately on startup, then loops on this cycle (default 1800)
• Settings page edits are saved to the user layer $DSH_HOME/dsh-pet/main-config.json (the full pet list, overriding the bundled defaults); "Restore Defaults" clears the user layer and falls back to config.jsonc

Method 3: Hand-editing the Config File (advanced, fully free configuration)

The user-layer config file lives at $DSH_HOME/dsh-pet/main-config.json. It shares the same format as the bundled default config—just write whatever you want to change following the structure of assets/config.jsonc; wrong or missing fields fall back to defaults, and a complete file is not required (and cannot be):

Field	Role	Same format & default as
pets	Pet list (size/position/multiple instances/balance toggle)	Array, each item same as pets[] structure
animations	Animation pool: idle / turn / drag / clicks / moves / categories / events (balance and other event animations)	Same animations structure
animationWeights	Animation chain playback weights (idle / turn / move)	Same animationWeights structure
eventsRefreshSec	Event refresh cycle (seconds)	Same eventsRefreshSec structure
notificationsEnabled	System notification master toggle (boolean)	Same notificationsEnabled

Override: when the user layer specifies a field, it is replaced entirely (e.g. your full animations pool replaces the default); fields you leave out fall back to the in-package default. Validation runs at plugin load — format errors are reported explicitly in the DSH console, never silently running a partial config.

Method 4: Extra Pets (pet packs)—Adding a New "Species"

Methods 1–3 only adjust instances of the default pet (count/size/position); the animation pool remains a single global one. To add a brand-new pet species (independent animation pool + its own assets), create a pet/ directory under the user data root:

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

Each extra pet = one -config.json + one -animation/ directory, paired by the same prefix; pet/ is scanned and auto-discovered, taking effect on both browser and desktop. A -config.json defines one "species" (animation pool + assets directory); its pets array can hold any number of instances of that species (sharing the animation pool and assets):

// 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 }
}

Rules (strictly isolated from the main pet, never mixed):

• Assets only look up their own: assets dir name = filename prefix (pet/pig-config.json → pet/pig-animation/), shared by all instances of that species; animation URL is /thumb/<前缀>/<名>.webm, a miss is 404 — never falls back to main-animation or in-package assets
• Animation pool does not fall back globally: animations / animationWeights must be fully written (missing is a config error)
• Same structural constraints as main config: every pets field complete and valid, unique ids within the array, animations / animationWeights validated by the same rules; notificationsEnabled / eventsRefreshSec are global properties not managed by the pet file (if written, ignored; if omitted, no error)
• Invalid config / missing -animation/ dir / instance id conflicts with main pet → explicit error at load and skipped (doesn't affect other pets)
• Settings page does not list file-based pets (file changes take effect immediately, visible after refresh; save/restore defaults won't write them into main-config.json)
• Balance tier animations follow each pet's own events.balance

Runtime Behavior

What the pet actually looks like when running in the DSH Web UI:

Preview

All animations (640×360, the resources actually played by the plugin)—GIF previews are stored in the repo at dsh-pet/assets/preview/ (rendered via raw direct links; file names use pinyin for cross-platform convenience); for complete transparent videos see the plugin package at dsh-pet/assets/webm/ (VP9-alpha, the only published format):

Idle / Turn

Move

Micro-movements

Play

What to eat

Seasons

Text

Click response

Drag

Balance events (tiered by percentage of balance used: full → low → depleted)

Muttering animation (muttering / dialogue reply trigger, random 1)

Work state animations (follows DSH session events, six tiers: thinking / working / organizing / waiting / success / error)

Note: transparent background; GIF shows page color for transparent parts, actual webm is transparent.

Generate your own pet from scratch (complete workflow)

① Prompts → source video

Use an AI video generation tool (e.g. Kling, Runway, Doubao, etc.; this project's assets were generated with Doubao), following the recipe in prompts/桌面宠物 10 秒动作提示词.md, to generate one 10-second greenscreen video per action:

• Video aspect 16:9, pure greenscreen background (#00FF00)
• Character position/size fixed (top of head ~20% height, feet ~85% height)
• Action stays within frame throughout; first and last frames show standard front-facing stand
• Each animation is broken down by second (actions in each stage of 0-10s)

Save the generation results as one mp4 per action into video/.

Obtaining source videos: to keep the repo size down, the source videos in video/ are not committed to git. Releases provide a packaged archive that can be downloaded directly from the browser:

• assets-videos.zip — archive of all source videos (Chinese-named mp4s; after extracting, place them in video/)

Extract with: Expand-Archive assets-videos.zip (Windows) or unzip assets-videos.zip, then put the mp4s back into video/ to run the asset pipeline.

② Source video → transparent animation (asset pipeline)

step02 (transparent video) offers two routes, pick one as needed (default is automatic and reproducible; if results are poor, override with a manual PR cutout):

cd scripts
# 路线 A（默认）：自动绿幕抠像（HSV 色相，无需人工）
python watermark_step01.py   # 水印遮罩填充 → step01/
python chroma_step02.py      # 绿幕抠像转透明 → step02/

# 路线 B（可选）：PR 手工抠像覆盖（针对含第三方物品/自动抠像效果不佳的动作）
#   1. 在 PR 里手工抠像，导出带 alpha 的透明 .mov（如 ProRes 4444 with Alpha）
#   2. 放入 pr/，文件名与动作名一致（如 吃白饭.mov）
python pr_import_step02.py   # pr/*.mov → step02/（透明 webm，覆盖该动作自动抠像结果）

# 后续步骤两条路线共用：
python normalize_step03.py   # 归一化 2160×1215 统一站立居中 → step03/
python encode_thumbs.py      # 转码 640×360 播放变体 → step04/

Dependencies: Python 3 + ffmpeg + numpy + scipy (the asset pipeline scripts automatically use the ffmpeg under the workspace's .tools/).

This project uses route B for all actions (all manually cut out in PR): for actions "containing third-party objects or complex transparent edges", automatic HSV cutout tends to leave fringes or cut out wrongly; a manual mask in PR is more precise. Both routes produce the same level of step02/, and subsequent steps are identical; chroma_step02.py is kept as an automated fallback, and any action can still be auto-generated in one click.

②.5 🍎 Safari/HEVC-compatible assets (macOS-only mov)

The plugin only publishes .webm (VP9-alpha) by default; Safari/WKWebView doesn't support webm alpha (results in a black background). On macOS, you need to use the officially transcoded HEVC-with-Alpha .mov assets from the GitHub Release — three steps:

1. Download: https://github.com/PC2005-cloud/dsh-pet/releases/tag/assets-mov (fixed tag, kept up to date; zip filenames correspond one-to-one with webm files)
2. Place: put the .mov files into $DSH_HOME/dsh-pet/main-animation/mov/ (for pet-pack pets it is pet/<种类名>-animation/mov/)
3. Change the variable: search ANIMATION_EXT, change .webm to .mov — for the npm package, edit the artifact lib/client.js (for desktop also edit runtime/electron-helper/shared-core.js if needed); for self-built, edit the source src/shared/constants.ts and rebuild

Host routing already falls back with dual extensions (whitelist webm|mov, MIME, asset root dispatches by extension), no host changes required. See the plugin README's "Using mov on macOS" for details.

③ Animations → plugin

# 把 step04 的播放变体同步进插件包（webm 直接 cp）
cp step04/*.webm dsh-pet/assets/webm/   # 播放格式（VP9-alpha）

# 本地安装插件
dsh plugin --profile web add file:D:/path/to/dsh-pet

step01-04 intermediates: script-generated, not in repo; video/ sources + scripts are artifacts, maintained in repo.

🎯 Publish (single webm format)

The plugin publishes a single npm package with a single asset format (webm); files is constrained to a fixed manifest (lib / src / assets/webm / runtime/electron-helper / assets/fonts / assets/pic / assets/config.jsonc / scripts/ensure-electron.mjs / cordis.patch.yml, see prepare.js; shared by browser and desktop modes, minimizing package size):

cd dsh-pet
npm publish --tag latest   # npm publish 自动执行 prepare 钩子（构建完整产物 + 收敛 files），无需手动构建

• The client does no runtime browser detection — the only playback format (webm) is hardcoded in the source, no publish-time injection
• For the Safari/HEVC version (macOS): mov assets are officially published in the GitHub Release assets-mov; download and extract them into main-animation/mov/, then change the centralized playback extension constant ANIMATION_EXT to .mov (see ②.5 above)

Project structure

The three pieces are organized in blocks ①②③ (local directories gitignored are not listed):

├── prompts/           # ① 动画生成提示词配方（绿幕规范 + 按秒分解）
├── video/             # ② 素材源视频（绿幕 mp4；不入库，Releases 提供压缩包）
├── scripts/           # ② 素材生成链（Python/ffmpeg：水印 → 抠像 → 归一化 → 转码 → GIF 预览）
├── step01~04/         # ② 素材链中间产物（不入库）
├── pr/  prproj/       # ② 路线 B：PR 手工抠像输入与工程（本地工作数据，不入库）
├── tools/             # 开发小工具（素材链各阶段预览等）
├── assets/            # 仓库展示用截图
├── .github/workflows/ # CI：Safari/HEVC 转码流水线（macOS runner，手动触发 → 发布 assets-mov Release）
├── dsh-pet/           # ③ 插件（可独立 npm 发布）
│   ├── src/           #   TS 源码：host（配置/路由/工作状态）、client（动画链）、shared（双端共用纯逻辑）
│   ├── lib/           #   构建产物（prepare 自动构建，不入库）
│   ├── runtime/       #   桌面模式运行壳（Electron 透明窗）
│   ├── assets/        #   webm 动画 / preview GIF / 字体 / 图标 / config.jsonc 默认配置
│   └── scripts/       #   构建与发布脚本（prepare / prepack-check / ensure-electron 等）
└── LICENSE            # MIT

License

• Code: MIT
• Assets (animations / prompts / source videos): open-source use is permitted, commercial use is prohibited
• Fan-derivative (derivative works) agreement: any derivative / reworked / reskinned work based on this project must include the original author's GitHub address, https://github.com/PC2005-cloud/dsh-pet, in any introduction, showcase, or distribution of that work