Preface¶

DeepSeek Harness (DSH) has written “everything is a plugin” into its official repository description. After the web interface is launched, most states such as task completion, session start, pending approval, and request errors are still displayed in panels and logs, and you have to stare at them to know what happened. Among plugins for themes and appearance, changing skins and layouts are common practices; making the workspace itself into a living companion is another path.

whale-girl follows this latter path. It places a QQ pet-style desktop companion in the bottom-right corner of the DSH web interface: it can be dragged, fed, and played with, and will also accumulate seniority based on tasks, sessions, and companion duration. This article is organized after cross-checking the community plugin directory page, repository README, growth system and state machine documentation, as well as package.json and configuration source code: what it is, what it can do, how to install it, and how to configure it.

First, it is necessary to clarify the boundaries: the community plugin directory (deepseek-harness-plugin.com) is an independent site and has no official affiliation with DeepSeek / Horizon Robotics, and should not be treated as an official app store. The main DSH repository is at deepseek-ai/deepseek-harness.

What it is¶

whale-girl is a theme and appearance plugin for the DSH web interface, maintained by vlln, with its GitHub repository at vlln/whale-girl. As of August 17, 2026, the repository has approximately 197 stars, uses the MIT license, and its primary language is JavaScript. The version number in the repository’s package.json is 0.1.0.

The problem it solves is very specific: placing a floating desktop pet in the Web GUI, turning what has already happened on the agent workspace into visible actions and an ever-increasing ledger. The positioning on the directory page is:

A QQ pet-style desktop companion for the DSH web interface: floating in the bottom-right corner, draggable/fed/playable accumulative partner.

The implementation form is also written in the dsh field of package.json: it is an official bundle plugin (dsh.bundle points to cordis.patch.yml), and the client declares platform: web. That is to say, it runs on the web client, not a terminal TUI plugin.

The default character is “Whale Girl”. The README states that the character image was created by ZipZipPipe (the “Whale Girl”表情包 character), and the sprites are generated based on its character design. In the asset manifest lib/assets/manifest.json, the credit for this character is also ZipZipPipe.

Core Features¶

Bottom-right floating, draggable, feedable, playable¶

After installation and web restart, the pet will appear in the bottom-right corner. The basic operations given in the README are:
- Click to bring up the menu: 🍗 Feed, 🎾 Play
- Drag to move
- Hover to display the status bar: seniority level, number of tasks, latest shared memory
- The pet is hidden during the initial configuration / onboarding phase

Feeding and playing do not grant experience points by themselves, only trigger the biting / ball-catching actions, then enter the happy state, and pop up a configurable speech bubble. The growth documentation explicitly categorizes such interactions as “pure fun, no numerical impact”.

15 states following the workspace¶

The pet does not just loop a single idle animation. The repository organizes its behavior into a 15-state state machine, and the character must provide assets for all 15 states (missing assets will be rejected by the verify-assets gate). The corresponding list in the README is as follows:

The state machine documentation also adds a few conversion rules worth remembering separately when writing this article:
1. Drag has the highest priority; there is a 1.5-second buffer after releasing before returning to the underlying state.
2. The failure emotion window will not be overridden by the welcome action of a new session.
3. When a session is thinking or pending approval, sleeping and walking will be suppressed.
4. think is the normal state of thinking companionship; working is a working posture randomly inserted by the client’s rhythm timer, not a task indicator light.

Please refer to the repository’s docs/state-machine.md for the complete priority and trigger sources.

Accumulative growth: Experience, titles, memories¶

The growth system is designed with “zero negative feedback”: no decay, no punishment, no mandatory requirements. Failures only count towards the tally and play a short disappointed animation, without deducting seniority. The authoritative description is in docs/growth-system.md.

The verified sources of experience points are as follows:

Request errors do not count towards XP or incur punishment, only trigger emotional states. The level is derived from experience points, with the formula xpForLevel(L) = 50·L·(L−1)/2, which translates to 50 XP for level 2, 150 XP for level 3, 300 XP for level 4. The documentation clearly states: level is always calculated from xp, and manual setting is prohibited.

Titles are a closed set, derived idempotently from statistical data, and unlocked when written to memory and triggering a celebration:

Memories are a circular log with a maximum of 8 entries, and the latest one is displayed when hovering over the status bar. Multiple characters share the same ledger: the seniority records the companion relationship, not a specific appearance.

XP values, level curves, title sets and thresholds belong to the semantic layer, and users are not allowed to modify them through configuration gates. The exact wording in the README is: changing these will break the consistency of the accumulated ledger.

Swappable characters, shared behavior grammar¶

There is a “🎭 Change Character” option in the menu, or you can modify the localStorage key whale-girl:character. Each character must provide assets for all 15 states; the mapping from events to actions is shared across all characters, and characters can only fill resource slots without modifying triggers or priorities.

The repository frames “adding a character” as a resource-level contribution: produce 15 sheets plus a manifest entry, no code changes required. The operation instructions are in docs/adding-a-character.md, and the verification command is:

node scripts/gates/verify-assets.mjs

The README also marks it as a complete template for the official repository-plugin format, and its structure and gates can be compared with AGENTS.md in the repository root directory. This is for plugin authors, and daily users of the desktop pet do not need to read these.

Installation and Activation¶

The installation command given on the community directory page is:

dsh plugin add github:vlln/whale-girl

The repository README recommends installing via the web profile and pinning to the main branch (noting that build artifacts are included in the repository):

dsh plugin --profile web add "github:vlln/whale-girl#main"

You can also install from a local directory:

dsh plugin --profile web add <local path to whale-girl>

After installation, you must restart the web interface, since the bundle layer is synthesized at startup, and the pet will only appear in the bottom-right corner afterwards. To update later, use:

dsh plugin --profile web update whale-girl

Again, a restart is required for changes to take effect.

For reproducible installations, the directory page recommends fixing the commit hash, using the syntax:

dsh plugin add github:vlln/whale-girl#<commit>

Replace <commit> with the actual commit hash. Both the directory page and the official DSH documentation remind users: plugins run with the permissions of the current dsh process, and may execute code during installation; you should inspect the source code repository and license before installing.

Typical Usage¶

Daily Interaction¶

After restarting the web interface, you can reproduce the following steps as per the README:
1. Check if the pet appears in the bottom-right corner. If you are still on the initial configuration or onboarding page, the pet will be hidden, and you can check again after entering the workspace.
2. Click the pet to open the menu, select Feed or Play, and observe the biting / ball-catching actions, followed by the happy animation and speech bubble.
3. Hold and drag to move it elsewhere, and it will return to its idle or current companion state after a buffer period when released.
4. Hover the mouse over it to view the level, number of tasks, and the latest memory.
5. Start a new session, and you should see the wave welcome animation; the pet will enter the meditating state when the session is thinking, and the waiting expectantly state when pending approval.
6. A successful task will trigger a cheer and record the event in the ledger; a failed task will trigger a startle then disappointed animation, without deducting experience points.

It will doze when idle for the configured sleepAfterMs (default 60 seconds). Drag, feed, play, or opening the menu will count as user presence, and the idle timer will restart from the time of this interaction.

Configuration (changes take effect hot)¶

Parameters are set via the host’s settings, written in the whale-girl: section of /settings.yaml, or adjusted via the settings UI. The README states that modifications take effect hot without restarting. The example given in the repository is as follows:

whale-girl:
  enabled: true      # Web rendering switch (set to false to disable the web pet when running alongside a desktop companion to avoid double pets)
  size: 110          # Pet size in px (64–160)
  opacity: 1         # Normal state transparency (0.2–1)
  walk:
    enabled: true    # Wandering switch
  sleepAfterMs: 60000

These default values can be cross-referenced in lib/src/config.mjs. The same source code also exposes more granular experience options, such as wandering interval, wandering speed, duration of each emotion window, and the speech bubble copy pool for feeding / playing. The semantic layer (XP, titles, maximum number of memories) is not included in this schema, and the configuration gate will block attempts to modify them.

The enabled option specifically handles the scenario where both a web pet and a desktop companion exist: turn off the web pet when both are running to avoid having two pets on screen.

Applicable Scenarios and Notes¶

It is suitable for the following situations:
- Mainly running agents in the DSH web interface, and hope that tasks, sessions, and pending approvals have visible feedback at a glance
- Wanting to add an accumulative, ever-increasing lightweight companion to the workspace beyond themes and appearance
- Preparing to draw new characters for whale-girl, or using it as a structural template for repository-plugin development

Before using, please note the following points, all from the directory page, repository documentation, or official DSH installation instructions, not additional elaborations:
1. Only covers web. package.json declares dsh.client.platform as web. Installing it on terminals or profiles without a Web GUI will not activate it as a desktop pet.
2. The plugin runs with the permissions of the current dsh process. The directory page notes: the plugin may execute code during installation. Inspect the repository and MIT license before installing; for production or shared environments, it is recommended to fix the commit hash instead of using main to avoid silent changes to the actual running code from subsequent pushes to the main branch.
3. The community directory is not an official store. whale-girl is a community open source project maintained by vlln. The directory site has no official affiliation with DeepSeek / Horizon Robotics.
4. Do not confuse it with skin plugins. The “Related Plugins” section of the directory includes dsh-deep-whale (a Whale Girl skin series), which is a separate set of skins and not this desktop pet.
5. Growth rules cannot be configured. Levels, titles, and XP sources are code-level closed sets. What can be adjusted are experience options such as size, transparency, wandering, sleep delay, and copy text.
6. Web restart is required after installation. Configuration hot updates only apply to settings; the plugin’s bundle synthesis occurs at startup.
7. Character images have attribution. The default Whale Girl image is derived from ZipZipPipe’s character design, and secondary use or creation should refer to the repository’s acknowledgments and license for judgment.

The repository’s growth documentation also lists some unimplemented directions (such as granting XP based on token consumption, more title dimensions). These are just plans in the documentation and should not be treated as existing features in the current version.

Summary¶

whale-girl turns the DSH web workspace into a QQ-style desktop pet: floating in the bottom-right corner, draggable, feedable, and playable; tasks, sessions, and companion duration are translated into levels, titles, and memories. The state machine has 15 actions, the growth ledger only increases, and the configuration interface only opens up experience-level options. It does not solve problems such as accelerating inference or supplementing tools, but adds a layer of visible companionship and feedback to the long-running Web GUI.

Related addresses:
- Community directory page: https://deepseek-harness-plugin.com/zh-CN/plugins/whale-girl/
- GitHub repository: https://github.com/vlln/whale-girl
- DeepSeek Harness official repository: https://github.com/deepseek-ai/deepseek-harness