Skip to main content

dsh-ui-web/packages/dsh-pet

34Stars2Forks0Issues0Watchers

A whale-girl pet on the bottom-right corner of the DSH Web interface. Animations switch based on chat activity. Pat and feed to increase intimacy and level up. Features include naming, dragging, hiding, and summoning.

Evidence5/5methodologySourceInstallMaintenanceDSH versionSecurity scan
Machine-auditedInstall commandRepo verifieddsh-plugin topicLicenseREADMEAI wiki
Language
TypeScript
License
Apache-2.0
Branch
main
dsh-plugindsh-plugin-marketdsh-plugins

Install

cmdweb profile
$ dsh plugin --profile web add @captain1275/dsh-pet

Run the command above in your terminal to install this plugin via the dsh CLI. You can switch Profile in the top-right corner. New to dsh? Read the beginner tutorial

Install via your agent

Install the DeepSeek Harness plugin CAPTAIN1275/dsh-ui-web/packages/dsh-pet for me: review the repository at https://github.com/CAPTAIN1275/dsh-ui-web first, then run the install command and verify the plugin loads successfully.

Paste this instruction to the DSH Web GUI assistant — it will install and verify for you.

One-Line Description

Raise a whale girl pet in the bottom-right corner of the DeepSeek Harness Web interface: she automatically switches animations when the model is thinking, waiting, using tools, or completed. You can pet her, feed her, rename her, and drag her around. Affinity grows from a baby whale all the way to "Deep Sea Bond."

Core Features

  • Follows model conversation state to switch animations: "working" when thinking/calling tools, idle when waiting, jumping celebration when completed, breathing when idle
  • Two interaction types: pet (10s cooldown, +1 affinity) and feed (30s cooldown, +5 affinity, -1 fish snack) with real-time bubble feedback
  • 4-level affinity system: Baby Whale → Companion → Best Friend → Deep Sea Bond (100 points max), with "Level Up!" popup on tier advancement
  • Fish snack economy: +1 for every 3 model turns completed, +1 naturally every 30 minutes, 20 max inventory
  • Custom naming (1-20 characters), floating panel for feed/rename/hide, drag to reposition (position persisted), "Summon {name}" button appears in input area when hidden
  • Global floating layer: always stays in bottom-right even outside session lifecycle (new session empty screen), not dependent on any specific session or UI slot

Technical Implementation

  • Languages: TypeScript (with JSX) + Node.js (host half) + React 18 (browser half)
  • Key Dependencies: @deepseek-ai/cordis (plugin framework), @deepseek-ai/dsh-host-webserver (mount /api/pet/* and /pet/whale/* routes), @deepseek-ai/dsh-client-runtime + @deepseek-ai/dsh-client-ui-settings (browser half + settings card), schemastery (DSH settings schema validation), React 18 (injected by DSH shell)
  • Architecture Pattern: Dual-half cordis bundle. src/index.ts is the host half, exports name='pet' with cordis apply: construct PetService to listen to session/event (turn/start, step/start, tool/call, turn/end dispatch to five phases: idle/waiting/thinking/tool/done), register settings section named pet via installSettingsSection, mount routes based on enabled state. src/client/index.ts is the browser half, createRoot → document.body globally mounts floating layer, polls /api/pet/state every 800ms, combined with visibilitychange to immediately fetch when tab returns to foreground, register i18n dictionary and mount settings card to web-ui.plugin.item slot
  • Entry Files: Host half at packages/dsh-pet/src/index.ts, browser half at packages/dsh-pet/src/client/index.ts, bundle declaration in packages/dsh-pet/cordis.patch.yml:8-10 (inserts id: pet), browser dependency injection in packages/dsh-pet/package.json:37-49

Use Cases

Users who spend long periods running model tasks on DSH Web and want some companionship: the whale girl works at your feet when the model is thinking, jumps to celebrate when completed, and affinity naturally grows with usage time and work turns. Also suitable for those who want to add some "raising" feel to the DSH interface without complex configuration—just install and use. Disable, hide, and rename are all directly accessible in settings.

Prerequisites & Compatibility

DependencyMinimum VersionDescription
DSH Host0.1.0-rc.6+peerDependencies locked to @deepseek-ai/dsh-* ^0.1.0-rc.6; runtime only depends on 4 browser-side @deepseek-ai/dsh-client-* packages
Node.js^22.19.0 or >=24.0.0Explicitly required in engines.node field
Platformweb (DSH browser side)Package has dsh.client.platform: "web", no desktop/terminal adaptation
Native ModulesNoneRuntime only imports clsx + schemastery (pure JS); CSS Modules inlined by lightningcss as <style data-plugin>
React^18.2.0peerDependency, injected by DSH shell

Installation

dsh plugin --profile web add github:CAPTAIN1275/dsh-ui-web/packages/dsh-pet

Configuration Options

ConfigTypeDescriptionDefault
Enable Pet (enabled)ToggleMaster switch for plugin: when disabled, floating layer, polling, and API routes all stopOn
Show Pet (visible)ToggleWhether to display floating layer on screen; when hidden, "Summon {name}" button appears in chat input areaOn
SizeNumber (32-512, px)Pet display size, equals single frame height of sprite sheet160
Right OffsetNumber (0-10000, px)Horizontal offset from viewport right edge (real-time sync during drag)24
Bottom OffsetNumber (0-10000, px)Vertical offset from viewport bottom edge (real-time sync during drag)20
NameString (1-20 characters)Pet's display name, appears in floating panel and "Summon {name}" button"鲸鱼娘"
Pet CooldownInternal constant (affinity.petCooldownMs)Minimum interval between pets, adjustable in source10000 ms
Feed CooldownInternal constant (affinity.feedCooldownMs)Minimum interval between feeds, adjustable in source30000 ms
Fish Snack CapInternal constant (treats.maxTreats)Hard inventory cap20
Affinity CapInternal constant (affinity.AFFINITY_MAX)Cap on cumulative affinity points100

Note: Cooldown times, fish snack economy parameters, and affinity cap are constants built into source code in affinity.ts / treats.ts. Default values work fine for regular users; if adjustment is needed, host can override via affinity / treats fields in PetConfig.

FAQ

Q: I don't see the pet in the bottom-right after installation. What should I do?

A: First confirm you've restarted dsh web—cordis bundle injection only takes effect on host startup. If it still doesn't show, open the browser console to check for pet.state transport error, then go to Settings → Plugin Config → Pet and turn on "Enable Pet".

Q: Pet/feed isn't responding. Is it broken?

A: Most likely on cooldown. Clicking pet within 10 seconds or feed within 30 seconds will cause the whale girl to bubble "Already petted enough today" or "I'm full", and it won't work again until cooldown ends. Feed may also be rejected if fish snack inventory is zero.

Q: How do I replenish fish snacks when they're all used up?

A: No direct recharge. Two supply paths: +1 for every 3 model turns completed, +1 naturally every 30 minutes. Stops at 20, but affinity still grows slowly over time (+1 point every 30 minutes).

Q: Will I lose affinity and fish snacks when uninstalling the plugin?

A: No. All state (name, affinity, inventory, position, custom) is written to $DSH_HOME/pet.json (default ~/.dsh/pet.json). Uninstalling the plugin won't delete this file, and progress automatically restores upon reinstall.

Q: Can I swap to my own character or add multiple pets?

A: Not supported in current version. This plugin only has the built-in whale girl; there's no multi-pet registry or custom sprite sheet deployment mechanism. To change the character, you need to directly modify the sprite geometry definitions in spritesheet.ts and the sprite assets in source code.

Q: I can't see the pet config card in settings. What happened?

A: This means the current DSH version hasn't exposed the pet settings namespace to the settings page (some deployments limit WEB_SETTINGS_NAMESPACES whitelist). In this case, you can directly edit $DSH_HOME/settings.yaml, or add pet to the whitelist in dsh-host-apiproxy and restart.

Q: Can I rename the pet? Is there a length limit?

A: Yes, directly through the "Rename" entry in the floating panel, 1-20 characters, cannot be all whitespace. After renaming, both the summon button and floating panel will display the new name.

Difficulty Level

Beginner — Install and use immediately, zero config startup; optional advanced settings (size, position, naming) are all accessible in the settings card with a few clicks, no need to touch code or config files.

Known Issues & Limitations

  • The failed animation already occupies a row (row 5) in the 9-state sprite sheet contract, but current rc.6 has no DSH event source to trigger it—model failures behave the same as idle
  • Plugin depends on rc.6's session/event (turn/start, step/start, tool/call, turn/end) to derive animation phases; if host version is below rc.6 or session events are missing, the pet will stay in idle
  • When pet.json file is corrupted, the plugin silently falls back to default values and continues running; user's affinity, name, inventory, and position will be lost but no error is shown
  • packages/dsh-pet/package.json declares "license": "Apache-2.0", but subpackage LICENSE files are BSD-3-Clause—license metadata inconsistency; use repository root LICENSE as the authoritative source
  • Browser half outputs console.log and console.warn debug logs during apply and mount, which creates noise in production use scenarios

Read the usage guide →

Install steps, key points, FAQ and compatibility for this plugin — auto-derived from indexed fields.

Listing badge

Listed on deepseek-plugin.org
[![Listed on deepseek-plugin.org](https://img.shields.io/badge/listed_on-deepseek--plugin.org-007EC6)](https://deepseek-plugin.org/plugins/CAPTAIN1275/dsh-ui-web/packages/dsh-pet)

Paste this markdown into your GitHub README to link back to this listing. The badge only states the listing — not a security endorsement.

← Back to plugin directory