dsh-pet

One-Line Description

Raise a desktop pet that moves on its own in DeepSeek Harness's Web interface. It stays in the bottom right corner, breathing on its own, making random small movements, occasionally looking around at you or walking across the screen. You can also click or drag it to any position.

Core Features

A hand-drawn style transparent animated pet stays in the bottom right corner of the Web interface, no configuration required
51 animations automatically chain by probability: idle breathing, random actions (like humming, playing with a Rubik's cube, getting ruffled, violin performance, eating plain rice, seasonal actions, etc.), occasional turning
Screen roaming: walks in the current facing direction, automatically checks boundaries to stay on screen, roaming distance 60~240px per session
Click interaction: clicking on the character randomly triggers "happy jump / shy surprise / tsundere anger" response animations
Dragging: pick up and drag to any position on screen, pet stops at the new location and follows when window scales
Left/right facing: animations are CSS-mirrored based on facing direction, pet always faces you or turns away
Dual-buffer playback: cross-fade between two video segments when switching animations, never any blank frames
Accessibility: responds to system's "reduce motion" setting, automatically disables transition animations

Technical Implementation

Language: JavaScript (ESM host-side + official CJS bundle browser-side), with TypeScript type declarations
Key Dependencies: @deepseek-ai/cordis (plugin framework), @deepseek-ai/dsh-home-paths (parse DSH home directory), @deepseek-ai/dsh-host-webserver (register /pet routes), @deepseek-ai/dsh-client-runtime (browser-side runtime container), React 18 (injected by DSH shell)
Architecture Pattern: Dual-bundle —— host-side registers /pet/{thumb|full}/<file> routes in Node process to serve WebM resources; browser-side registers to shell.overlay list slot via window.__ModuleLoader__.load({id,factory}), mounted as floating layer (click-through, doesn't block UI operations)
Entry Files: host-side dsh-pet/lib/index.js, browser-side dsh-pet/lib/cordis.patch.yml

Use Cases

For users who want the DSH Web interface to feel more personable but don't want plugins to interrupt their workflow. The pet is purely decorative: no business functions like weather, monitoring, or Agent status awareness, zero LLM calls, no model quota consumption. Suitable for people who want a bit of companionship but worry about plugins affecting experience.

Prerequisites & Compatibility

Dependency	Minimum Version	Description
DeepSeek Harness	0.1.0-rc.6+	peerDependencies declares cordis, home-paths, host-webserver, client-runtime, client-ui-slots all ^0.1.0-rc.6
Node Runtime	Not declared	Package doesn't declare engines; host-side uses ESM with `node:fs`/`node:url`, needs Node ≥ 14 LTS supporting `import.meta.url`
Platform	web	`dsh.client.platform = "web"`; no desktop/terminal adaptation
Native Modules	None	Pure Node standard library + browser standard API

Installation

dsh plugin --profile web add github:PC2005-cloud/dsh-pet

Configuration Options

Config	Type	Description	Default
`size`	Number (px)	Pet display height. Currently uses code default on browser side, changes require source code modification; declared in patch but not yet passed to browser	260
`position`	String	Default corner: `bottom-right` or `bottom-left`. Same as above, not effective on browser side	bottom-right
`fullRoot`	Path String	High-res original asset directory (1200×1200 master). Requires downloading `assets-videos` from GitHub Releases before it takes effect, otherwise `/pet/full/` route returns 404	`$DSH_HOME/pet-assets`

FAQ

Q: Will it consume LLM or network resources when running?

A: No. Zero LLM, zero API requests during runtime; animations are locally played WebM files in browser, cached for 1 hour then not re-downloaded.

Q: Does it need extra configuration?

A: No. Install and use immediately. If you want to change corner, adjust height, or enable high-res original assets, you need to manually modify DSH_HOME or source code defaults—the browser-side configuration pipeline is not yet connected.

Q: Which platforms are supported?

A: DeepSeek Harness Web only (dsh web). The package declares web as the runtime platform, no adaptation for desktop/terminal.

Q: How to uninstall?

A: Run dsh plugin --profile web remove dsh-pet, restart dsh web to restore original state. The plugin won't leave any persistent data.

Q: Want to replace with my own character?

A: The repository includes a full "prompt → green screen video → transparent animation" pipeline (7 Python scripts + ffmpeg in scripts/). Generate source video according to prompts/ recipe, run through 4-step processing chain to get thumb resources, overwrite dsh-pet/assets/thumb/ to replace.

Q: Adjusting size / position has no effect?

A: This is a known limitation. The size/position declared by host-side (cordis.patch.yml) currently can't reach the browser, client actually receives an empty object, so behavior parameters use code defaults. Browser-side configuration is planned.

Q: Is seeing [dsh-pet] roll=... logs in browser console a bug?

A: Not a bug. Probability print log marked as "for testing" in source code (lib/client.js:339), convenient for checking animation distribution; can be removed in official version, author kept it.

Difficulty Level

Beginner — One-line install command, no configuration needed to see effect, no documentation reading or parameter adjustment required.

Known Issues & Limitations

Browser-side distribution of size/position config items is not connected; patch config currently only affects host-side, browser uses code defaults (lib/client.js:182-185, README.md:45-49)
Browser console continuously outputs [dsh-pet] roll=... debug log, marked as "can be removed in official version" but currently not removed (lib/client.js:338-339)
High-res original assets (1200×1200 master) not included in npm package, need to manually download assets-videos from Git Releases and extract to $DSH_HOME/pet-assets/ before use, otherwise /pet/full/ route returns 404 (DESIGN.md:25)
Hit area during dragging is limited by hardcoded HIT_BOX rectangle (lib/client.js:99), may affect click feel when animation character visual width differs significantly from hit width