# dsh-pet

> Adds a floating animated pet to the DSH Web interface: 51 transparent animations

## Metadata

- Author: [@PC2005-cloud](https://github.com/PC2005-cloud)
- Repo: <https://github.com/PC2005-cloud/dsh-pet.git>
- GitHub: [PC2005-cloud/dsh-pet](https://github.com/PC2005-cloud/dsh-pet)
- Stars: 242
- Language: JavaScript
- License: [MIT](https://spdx.org/licenses/MIT.html)
- Topics: `deepseek-harness`, `desktop-pet`, `dsh`, `dsh-plugin`
- Forks: 15
- Open Issues: 9
- Last push: 2026-08-19T08:44:02.000Z
- Added: 2026-08-16T00:00:00.000Z

## Install

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

## Wiki

## 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
```bash
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

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [dsh-pet](https://deepseek-plugin.org/plugins/PC2005-cloud/dsh-pet)
Wiki generated by AI (model: `MiniMax-M2.5`)