Introduction¶

Staring at the DeepSeek Harness (DSH) Web interface for extended periods while coding or running agents can make even the most professional interface feel cold: tasks progress in the background, the progress bar moves, but the screen lacks a sense of “presence” that responds to your actions. In the early days, QQ Pet accompanied the desktop with a small sprite in the corner; whale-girl brings a similar experience to the DSH Web GUI—a draggable, feedable, and playable whale girl sprite that hovers in the bottom right corner of the page, switching expressions and actions based on task success, session status, and whether you’re idle.

Maintained by community developer vlln, whale-girl is categorized under “Fun Skins” in the SkillHub plugin repository and has approximately 281 stars on GitHub as of the verification date. This article is compiled based on cross-verification of the SkillHub directory page, the deepseek-harness-plugin.com details page, and the GitHub README.zh.md: what it is, its core capabilities, how to install it, and what to note when using it.

What is This¶

whale-girl is a desktop pet (deskpet) plugin designed for the DSH Web GUI, inspired by QQ Pet. The character resides in the bottom right corner of the page, can be dragged to reposition, and clicking it brings up a menu for feeding (🍗) or playing (🎾). It is not a skinning plugin but an “accumulative companion” with interaction and growth logic—completing tasks, starting sessions, and duration of companionship accumulate into experience levels, titles, and shared memories. Hovering over the status bar reveals the level, task count, and a summary of recent memories.

Technically, whale-girl uses the official bundle plugin format (with package.json declaring dsh.bundle + dsh.client in the root directory, alongside cordis.patch.yml). The repository’s README positions it as a complete reference implementation of the bundle mechanism. It is licensed under MIT; the character design comes from Bilibili uploader ZipZipPipe’s “whale girl” sticker design.

It’s important to note that DeepSeek Harness’s core philosophy is “everything is a plugin.” Community directories (such as SkillHub and deepseek-harness-plugin.com) are independently maintained by the community and have no official affiliation with DeepSeek or幻方 (High-Flyer). whale-girl is a community-curated plugin, and it’s recommended to review the source code before installation.

Core Features and Highlights¶

15-State State Machine, Synced with Workstation Rhythms¶

The pet features a built-in state machine with 15 states, covering scenarios such as idle, working, celebrating, surprised, fed, played, walking, sleeping, and more. Some typical mappings are as follows:

For complete priority, transition semantics, and triggers, see docs/state-machine.md in the repository; for the growth system (XP, title thresholds), see docs/growth-system.md. The README clearly states: Semantics like XP/titles cannot be modified via configuration to maintain the consistency of the accumulation ledger.

Accumulative Companionship: Levels, Titles, and Memories¶

Unlike purely decorative GIFs, whale-girl integrates “working together” into data: task completion, session activity, and companionship duration drive experience upgrades and unlock titles, with the status bar displaying level, task count, and recent shared memories. Developers who use DSH for extended periods will notice “this pet remembers what you’ve done”—rather than resetting to the same static image every time you refresh.

Optional Desktop Companion: Beyond the Browser Window¶

In addition to the in-page pet, the desktop/ folder in the repository provides a standalone desktop companion application (Node engine + Tauri rendering shell, approximately 12MB in size). It is not installed via dsh plugin but requires manual installation via npm install -g whale-girl-desktop and compiling the shell from Tauri source. The desktop version communicates with DSH through public endpoints (/state, /events, /presence, etc.), and during runtime, the in-page pet automatically hides based on the presence contract, reappearing after exit or crash (TTL 45 seconds). It is suitable for users who want the pet to reside on the OS desktop rather than just embedded in the browser.

Bundle Plugin Template¶

For readers planning to develop DSH plugins, whale-girl’s value extends beyond “being fun”: the lib/ (entry/logic/client/assets) and docs, decisions, scripts are clearly layered, with gatekeeping scripts scripts/gates/run.mjs and a full asset contract (docs/sprites-spec.md). vlln’s plugin-registry also provides the make-dsh-plugin skill and cookbook, which can be studied alongside this repository.

Installation and Enabling¶

whale-girl targets the web profile. The general installation command from the community directory page is:

dsh plugin add github:vlln/whale-girl

The repository README provides a clearer command for the web scenario (git source in one line, build artifacts are already in the repo):

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

You can also use npm sources or local directories:

# npm source
dsh plugin --profile web add whale-girl@0.1.0

# Local directory
dsh plugin --profile web add <whale-girl local path>

For reproducible installation, you can pin the commit hash, as suggested on the directory page: dsh plugin add github:vlln/whale-girl#commit.

After installation, you must restart the web (the bundle layer is synthesized at startup). After restarting, the pet will appear in the bottom right corner: clicking brings up the menu, dragging repositions it; hovering displays the status bar. During initial configuration or onboarding, the pet will be hidden to avoid interfering with the first-time guide.

To update the plugin:

dsh plugin --profile web update whale-girl

Or change the git ref and restart the web again.

Typical Usage Examples¶

Daily In-Page Interaction¶

1. Open the DSH Web GUI and confirm that whale-girl is installed and the web has been restarted.
2. Click the pet in the bottom right corner, select 🍗 to feed or 🎾 to play, and observe the eat/play → joy animation chain.
3. Drag the pet to a position that doesn’t block code; after one minute of idleness, it will sleep, and clicking again will wake it.
4. Run agents normally: a new session triggers welcome, contemplative companionship during thinking (think), celebrate on task success, and error → disappointed on failure.

Hot-Reloading Configuration (No Restart Required)¶

Adjust in the whale-girl: section of <dshHome>/settings.yaml or in the settings UI; changes take effect immediately:

whale-girl:
  enabled: true      # Web switch; set to false when coexisting with desktop companion to avoid double pets
  size: 110          # Size in px, range 64–160
  opacity: 1         # Opacity 0.2–1
  walk:
    enabled: true    # Allow periodic wandering
  sleepAfterMs: 60000

Changing Characters (When Multiple Characters Are in the Manifest)¶

The menu “🎭 Change Character” cycles through available characters; you can also set the localStorage key whale-girl:character. If the manifest contains only one character, the button will be grayed out with the message “No other characters available.” Contributing a new character requires producing 15 state sheets as per docs/adding-a-character.md and passing verify-assets validation.

Applicable Scenarios and Precautions¶

Who is it for:

• Developers who frequently code, review diffs, or monitor agents in the DSH Web GUI and want a bit of light, companionship in the interface.
• Plugin authors who want to learn the official bundle plugin structure, client injection, and state machine design.
• Users who enjoy QQ Pet / desktop pet culture but don’t want to leave the DSH workflow.

Precautions:

1. Permissions and Security: The plugin runs with the current dsh process permissions, and the installation process may execute code. Please read the GitHub repository source code and MIT license before installation; for production environments, it’s recommended to pin the commit.
2. Web GUI Only: The core experience is tied to the web profile; the pet will not appear automatically in TUI or pure CLI scenarios.
3. Restart Web: After installing a bundle plugin, you must restart the web; otherwise, the character in the bottom right corner won’t be visible.
4. Desktop Companion is Optional: whale-girl-desktop requires Node ≥18 and Rust (cargo); the first Tauri compilation may take 5–15 minutes and is unrelated to the dsh plugin installation path.
5. Stars and Categorization: GitHub stars fluctuate (approximately 281 at verification); SkillHub categorizes it under “Fun Skins,” and the deepseek-harness-plugin.com directory page labels it “Themes & Appearance”—both are community directory tags, so refer to the functional description for accuracy.

Conclusion¶

whale-girl brings the QQ Pet-style bottom-right-corner companionship into the DeepSeek Harness Web interface: it’s draggable, feedable, playable, and can sync with task and session states. For DSH users who spend long hours in the frontend, it serves as a lightweight yet lasting “interface temperature regulator”; for plugin developers, it’s a living textbook on the bundle format and client state machines.

• SkillHub directory page: https://www.skillhub.cn/plugins/vlln/whale-girl
• Community directory details: https://deepseek-harness-plugin.com/zh-CN/plugins/whale-girl/
• GitHub repository: https://github.com/vlln/whale-girl