Preface¶

The philosophy of DSH is “everything is a plugin.” When an interactive character needs to be added to the DSH Web GUI, display, interaction, and material management can be converged into the plugin, rather than maintaining a separate set of static resources.

awesome-dsh-pet is designed for this scenario: it displays a desktop pet within the DSH Web GUI, positioned at the bottom right of the page, while also allowing for the continued addition of custom characters.

The community directory is an independent site with no official affiliation to DeepSeek or Fangfang; it should not be understood as an official app store.

What is this¶

awesome-dsh-pet is an extensible multi-character desktop pet plugin within the DSH Web GUI, maintained by Awesome-AI-Pedia, with an MIT license.

It addresses lightweight character display and interaction within DSH Web pages: displaying pets, feeding, playing, switching characters, and supporting custom character assets.

GitHub repository:

https://github.com/Awesome-AI-Pedia/Awesome-DSH-Pet

Core Features¶

Display desktop pets within the DSH Web GUI, positioned at the bottom right of the page.
Provides two characters: jingyu-zongcai (Whale CEO) and lulu-capybara.
The menu allows feeding, playing, and switching characters.
Supports configuring enabled, size, opacity, walk.enabled, and sleepAfterMs via the awesome-dsh-pet section in settings.yaml.
Supports quickly adding custom pets: place assets, modify manifest, run gates.
Supports two asset formats: Codex atlas 8×9 spritesheet and single-action sheet.
Requires 15 states: idle / working / celebrate / error / disappointed / joy / eat / play / drag / walk / sleep / wake / welcome / think / wait.

Installation and Enablement¶

The plugin runs with the permissions of the current dsh process. You should check the source code, scripts, assets, and license before installation. The license is MIT.

Below is the command to install or update the plugin using a local path:

dsh plugin --profile web add /Users/icourt/Desktop/DSH-plugin/Awesome-DSH-Pet

After installation or update, restart web.

Basic Configuration¶

Use the awesome-dsh-pet section in settings.yaml:

awesome-dsh-pet:
  enabled: true
  size: 110
  opacity: 1
  walk:
    enabled: true
  sleepAfterMs: 60000

The configuration items include:

enabled: Whether to enable the plugin.
size: Size.
opacity: Opacity.
walk.enabled: Whether to enable walking.
sleepAfterMs: Sleep-related time parameters.

Adding Custom Characters¶

Taking the character id my-cat as an example, the overall process is: place assets, modify manifest, run gates.

Determine the character id

The character id only allows [a-z0-9-] because it will be used as a URL path. The example uses my-cat.
Place assets

Place assets in the character directory, for example:

    lib/assets/characters/my-cat/spritesheet.webp

The asset format supports two types:

- `Codex atlas 8×9 spritesheet`
- Single-action sheet

Modify manifest

Add the character key under characters in lib/assets/manifest.json, for example:

    my-cat

If you wish for the new character to become the default character, change the top-level `default` from `jingyu-zongcai` to the new character id.

Run gates

First run the gates and tests:

    node scripts/gates/verify-assets.mjs
    node --test 'tests/*.test.mjs'

If the front-end source code has been modified, a rebuild is required:

    node scripts/build-client.mjs

Restart

Restart web after installation or update.

Asset and State Constraints¶

Custom characters must provide all 15 states:

idle / working / celebrate / error / disappointed / joy / eat / play / drag / walk / sleep / wake / welcome / think / wait

None may be missing.

Common constraints are as follows:

sheet is relative to lib/assets/characters/<id>/, allowing .png / .webp / .svg / .jpg / .jpeg / .gif / .json.
frames must be a positive integer.
Multi-frame PNGs must satisfy width = frames × height.
atlas must satisfy row < rows.
playback is optional: loop / pingpong / once / blink; pingpong and blink require at least 2 frames, others require at least 1 frame.
motion is optional: bob / wiggle / squash / shake / sigh / hop / tilt / float / wave, and requires frames === 1; error is the only exception, allowing multiple frames and superimposed motion.

Development and Maintenance¶

lib/client.js is the build artifact. After modifying lib/client/index.mjs, run:

node scripts/build-client.mjs

To regenerate the front-end artifact.

Applicable Scenarios and Notes¶

This plugin is suitable for developers who wish to add lightweight desktop pets, custom characters, or state assets to the DSH Web GUI.

Points to note when using:

The plugin runs with the permissions of the current dsh process.
Check source code, scripts, assets, and license before installation.
Custom assets must satisfy constraints such as 15 states, frame counts, playback, and motion.
License is MIT.