luweiyabo/dsh-whale-pet

dsh-whale-pet

Bring the whale girl into DeepSeek Harness: react to agent activity, respond to interaction, and roam around the screen.

中文 · Preview · Install · Usage · Features · Development · Issues

dsh-whale-pet is an open-source desktop-pet plugin for the DeepSeek Harness Web UI. It reacts to agent thinking, coding, tool calls, waiting states, and errors. It also supports click reactions, dragging, screen roaming, custom animations, and event-triggered rules.

The package includes 95 transparent 640×360 WebM animations, a Chinese and English interface, and settings that save automatically and take effect immediately.

Preview

Settings and action management

Desktop interaction and status

See the complete gallery of all 95 actions.

Installation

Requirements

Item	Requirement
DeepSeek Harness	^0.1.0-rc.6 || ^0.1.2-rc.1 || ^0.2.0-rc.2 (developer preview; Web profile)
Node.js	^22.19.0 || >=24.0.0 (follows DSH's official engines.node)
pnpm	Available on the command line; dsh plugin delegates package management to pnpm

Plugin 0.1.3 keeps DSH 0.1.x compatibility and adds support for DSH 0.2.0-rc.2: 0.1.x keeps using connection.api / connection.rpc, while 0.2.0-rc.2 reads and writes settings through the typert Remote subservice remote.settings, takes session activity from uiSession.sessionStatus, normalizes model streaming from assistant-stream frames, and targets the official plugin-page slot plugins.row.config for its settings card. Session events, model selection, and pending approvals/questions behave the same on both hosts; restoring state after a reconnect does not fire rules for historical messages. Balances still come from official provider endpoints; missing credentials produce a query failure.

Install from npm

dsh plugin --profile web add @luweiyabo/dsh-whale-pet
dsh web

The pet appears in the lower-right corner by default.

Alternatively, install directly from GitHub:

dsh plugin --profile web add github:luweiyabo/dsh-whale-pet

Keep only one installation source in a Web profile. Before switching between the npm, GitHub, and local-checkout variants, uninstall the current variant; otherwise multiple packages declare the same whale-pet loader entry and DSH cannot start.

Install from a local checkout

dsh plugin --profile web add .

Update

dsh plugin --profile web update @luweiyabo/dsh-whale-pet

Uninstall

dsh plugin --profile web remove @luweiyabo/dsh-whale-pet

Restart dsh web after uninstalling. User-uploaded actions remain in $DSH_HOME/whale-pet/actions/ and are not removed automatically.

Development

Client source lives in src/client/: animations.js owns the animation catalog, activity.js owns events, rules and arbitration, and index.js owns the UI and player. Run npm run build after editing source and commit the generated lib/client.js alongside it. npm run check verifies that the bundle matches the source. React is still supplied by DSH.

git clone https://github.com/luweiyabo/dsh-whale-pet.git
cd dsh-whale-pet
npm ci
npm run build
dsh plugin --profile web add .
dsh web

Run tests and inspect the npm package contents:

npm run check
npm run format:check
npm test
npm pack --dry-run

The project uses DSH's split host/client plugin architecture:

• lib/index.js: host-side settings, static animations, custom actions, and balance API
• lib/client.js: browser-side playback, interaction, intent arbitration, and settings UI
• cordis.patch.yml: DSH bundle registration
• assets/plugin-logo.png: plugin logo
• assets/thumb/: built-in transparent animations
• docs/images/screenshots/: README feature-preview screenshots
• docs/images/actions/: low-frame-rate GIF previews for all 95 actions
• materials/references/: character first frames and visual references
• materials/videos/: AI-generated source MP4 files for traceability and reprocessing, not runtime playback
• materials/prompts/: animation-generation prompts

Contributions are welcome through issues and pull requests. Run the tests before submitting and never commit API keys, private configuration, or large source videos.

Usage

Basic interaction

Action	Result
Hover	The pet faces the pointer side and restores its previous direction on leave; disabled while dragging or coasting
Hover (effects)	The pet leans subtly toward a nearby cursor; can be disabled in settings
Single-click the pet	Plays a head, body, or tail reaction and toggles selection; when interactive effects are enabled, each click also triggers a Q-style squash-and-bounce effect; while selected, click the page to choose a destination
Double-click the pet	Plays the “Blue Whale Appears” special animation and clears selection
Drag and bounce	Moves and places the pet; squash-and-stretch follows drag speed, and a quick throw starts the “Turn Into a Ball” animation at its ball-shaped frame and continues with momentum; the character bounds bounce off screen edges, collisions add a Q-style squash when interactive effects are enabled; momentum is disabled when Reduce Motion is enabled
Drag fully off-screen	Enters edge-hidden mode; move the pointer to that screen edge to reveal the recall handle
Right-click	Opens shortcuts for Home, Settings, and Hide

Settings

Open Settings → Plugins → Whale Pet to configure:

• Visibility, text bubbles, and account-balance bubbles
• Interactive effects (cursor tilt-follow, click bounce, drag squash)
• Pet size, default corner, and session-awareness scope
• Quiet, balanced, or lively autonomous activity
• Animations for working, coding, reading, researching, thinking, waiting, listening, and error states
• Autonomous, movement, and click-reaction pools
• Custom action upload, preview, and deletion
• Custom event-triggered rules

Settings are saved automatically and applied without restarting.

Features

Agent-aware animations

The pet reads Harness session activity and selects suitable actions through nine configurable intent arbiters:

Harness activity	Default behavior
Coding or file operations	Coding at a computer
Thinking and reasoning	Deep thought
Reading and research	Taking notes
Waiting for approval or an answer	Looking around
User message	Attentive listening
Tool or agent error	Startled reaction
No activity	Idle, turn, random action, or roam

Debounce and linger intervals prevent rapid animation switching. User interaction, errors, and other high-priority events can interrupt the current animation.

Autonomous behavior and roaming

• Continuous autonomous animation chain while no session event is active
• Default probabilities: idle 30%, turn 10%, action 40%, movement 20%
• Direction-aware movement with available-space checks
• Relative position persistence across window resizing
• Double-buffered video crossfades
• Interactive effects layer: cursor tilt-follow (rAF spring), click bounce, drag squash-and-stretch, and bouncy squash during coasting/bounces, globally toggleable
• Support for prefers-reduced-motion

Custom trigger rules

• Built-in templates for tool calls, failures, agent errors, turn completion, and approval requests
• Multiple conditions per rule
• Configurable priority, cooldown, and hold duration
• Test-trigger action and last-triggered status
• Shared priority arbitration with built-in intents

Account-balance bubble

When meter is enabled, the plugin detects the provider used by the current session and displays the balance returned by that provider's official API. It does not estimate token costs.

• Reads the current Harness model configuration, credential store, and provider default environment variables
• Supports DEEPSEEK_API_KEY, MOONSHOT_API_KEY, and STEPFUN_API_KEY, plus provider-specific apiKeyEnv settings
• Sends a provider key only to that provider's allowlisted official endpoint, from the local host process
• Disabled by default
• Gracefully reports unsupported providers

Action configuration

See the complete gallery of all 95 actions for all built-in actions. The action selector follows the Harness language and shows Chinese or English names, with search by category, English ID, or name; both built-in and user-uploaded actions can join autonomous pools, bind to event intents, or be used in trigger rules.

Custom actions

Upload a .webm or .mp4 file in the settings card, or copy it to:

$DSH_HOME/whale-pet/actions/

Recommended format:

Item	Requirement
Canvas	640×360
Background	Transparent
Foot line	y=330
Format	WebM or MP4
Upload limit	64 MiB per file
Total custom storage	512 MiB
Action ID	Filename; Unicode is supported and existing files are not overwritten

Uploaded actions appear under the “Custom” category and can be added to autonomous pools, assigned to intents, or selected by trigger rules.

Configuration and data

Settings are stored in the DSH whale-pet namespace. Custom animations are stored in $DSH_HOME/whale-pet/actions/. The plugin does not upload animations, settings, or API keys to the project maintainer.

Environment variable	Purpose
DSH_HOME	Overrides the DSH data directory
DEEPSEEK_API_KEY	One credential source for DeepSeek balance queries
MOONSHOT_API_KEY	One credential source for Moonshot balance queries
STEPFUN_API_KEY	One credential source for StepFun balance queries

Troubleshooting

Restart dsh web, then open Settings → Plugins → Whale Pet and ensure the pet is enabled. You can also run dsh --profile web --dump-config and confirm the plugin appears in the merged configuration.

Move the pointer to the screen edge where it disappeared. You can also enable it again in settings or use Home from the context menu.

Check whether the current model provider exposes a public balance API and whether the relevant Harness credential or environment variable is configured. Unsupported providers fall back safely.

Asset sources and licensing

• Original source code is licensed under the MIT License.
• Most animations under assets/thumb/ come from PC2005-cloud/dsh-pet and are not covered by this project's MIT code license.
• The upstream project currently allows these assets in open-source projects but prohibits commercial use. Review the third-party asset notice and the latest upstream terms before use, redistribution, or modification.
• Because the npm package combines MIT-licensed code with separately licensed media, its package license is SEE LICENSE IN LICENSE rather than plain MIT. The root LICENSE (standard MIT) covers only original code; the media terms are in the third-party asset notice shipped with the package. The complete package must not be treated as purely MIT-licensed.

This is an independent community plugin and is not affiliated with DeepSeek.