Preface

DeepSeek Harness (DSH) and DSH Desktop support plugin-based extension. For developers or power users, the interface is not only an interaction container but also part of the workflow. While maintaining technical restraint, adding an immersive dynamic background to DSH without hurting performance is an effective way to improve the user experience.

dsh-particle-whale is a 3D particle whale background plugin based on Three.js and WebGL, maintained by zepeng-jin. It addresses the static, low-interaction nature of generic UI backgrounds and provides a high-framerate, state-aware visual enhancement solution.

Core Features

The plugin runs on the web platform of the dsh framework and includes the following capabilities:

  • Volumetric 3D particle mesh
    Uses distance transform mapping to convert DeepSeek’s 2D vector outline into volumetric 3D rod-like bodies. Particles have curved dorsal/ventral thickness, surface normals, highlights, and Fresnel rim lighting effects.
  • Head-first swimming
    Simulates real marine animal movement: the head leads the heading, and waves propagate along the spine to the tail fin. When switching windows, the whale turns smoothly.
  • Responsive intelligent states
    • Idle state: the whale cruises fullscreen at 1.05x scale and 1.1x speed, with subtle tail fin motion.
    • Active state: during thinking, streaming output, or tool execution, the whale swims to the top-right corner, shrinks to 0.45x as a mini indicator, and emits high-energy bioluminescent pulses.
  • New session dispersal effect
    Triggered only when creating a new session (Cmd+N / Ctrl+N or clicking the “New Chat” button), with a nebula explosion and reformation animation. Regular clicks are ignored to avoid disturbing reading.
  • Frosted glass compositor
    Adds an 88% opacity frosted glass effect to the chat input card (backdrop-filter: blur(20px)), ensuring the whale remains visible behind the input box while maintaining text contrast.
  • Theme adaptation
    Dark mode uses silver-cyan glowing particles (additive blending); light mode uses high-contrast deep sapphire particles.
  • Performance optimization
    Handles overlays with pointer-events: none, and uses precomputed jitter buffers, instanced mesh rendering, and asynchronous state polling to maintain 60–120 FPS.

Installation and Enablement

Installing the plugin requires operating in the Web configuration directory of DSH Desktop. Developers are advised to use symbolic links for local development and testing.

  1. Enter the Web configuration node_modules directory of DSH Desktop:
    cd ~/Library/Application\ Support/dsh-desktop/harness/profiles/web/node_modules
  1. Create a symbolic link for the project:
    ln -s /path/to/dsh-particle-whale dsh-particle-whale
  1. Register the plugin in ~/Library/Application Support/dsh-desktop/harness/profiles/web/package.json:
    {
      "dependencies": {
        "dsh-particle-whale": "*"
      },
      "dsh": {
        "profile": {
          "bundles": [
            "dsh-particle-whale"
          ]
        }
      }
    }
  1. Restart or reload DSH Desktop.

Method 2: Install via npm

Run the install command directly in the Web configuration directory:

cd ~/Library/Application\ Support/dsh-desktop/harness/profiles/web
npm install dsh-particle-whale

Typical Usage

After installation, the plugin automatically reads the toggle on the general settings page in the dsh configuration. In normal use:

  • Default cruising: The whale appears in the lower-center of the screen in a normal swimming posture.
  • Interaction feedback: When you start asking a question or the model starts thinking, the whale swims to the top-right corner and shrinks, acting as a state indicator.
  • New session: Clicking the new session button makes the whale burst into particles and reform, providing a clear visual cue for the start of a session.

Applicable Scenarios and Notes

  • Platform: Web platform.
  • Performance: The plugin uses pointer-events: none to ensure the UI layer does not block mouse events, making it suitable for high-load scenarios.
  • Dependency requirements: Before installation, ensure the following peer dependencies are satisfied:
    • react ^18.2.0
    • @deepseek-ai/cordis ^4.0.1
    • @deepseek-ai/dsh-client-runtime ^0.1.0-rc.6
    • @deepseek-ai/dsh-client-locale ^0.1.0-rc.6
    • @deepseek-ai/dsh-client-ui-slots ^0.1.0-rc.6
  • Security: The plugin is open source and follows the MIT license. It is recommended to review the source code before installation to confirm no malicious behavior.

Summary

dsh-particle-whale provides a lightweight, high-performance 3D visual enhancement solution. By simulating the swimming states of marine animals and particle effects, it enriches the interaction feedback layer of DSH Desktop.