DeepSeek Harness (DSH) adopts an “everything is a plugin” architectural philosophy. When using the Web GUI or desktop client (Electron) for extended work or development sessions, the default interface background can often be quite plain. The dsh-bg-plugin plugin allows developers to add custom background images or videos to DSH via remote URLs or local files. At the same time, through a semi-transparent overlay and an exemption mechanism, it ensures that the settings panel retains its default appearance and that the operational experience is not affected.

Core Features

  • Media Source Support: Supports remote URLs (images/videos) and local files (images/videos) as backgrounds.
  • Visual Adjustment: Supports background clarity adjustment (0–100%), achieving a semi-transparent effect by overriding DSH theme Tokens.
  • Settings Panel Exemption: The settings panel ([role="dialog"][aria-modal="true"]) is forced to restore its default appearance internally and is unaffected by the background.
  • Installation Modes: Provides a static installation version (recommended, persists after restart) and a dynamic plugin version (session-level, disappears after restart).
  • Multi-Platform Support: Supports both the DSH Web client and desktop client, but they must be installed separately.
  • Selection Display Area: For images only, supports selecting a display area on the preview image, with dragging, zooming, and aspect ratio locking.
  • Floating Ball Support: Provides a floating ball panel background patch and supports two-way synchronization with the main application background.

Installation and Activation

Static installation is the recommended approach. Use the dsh command to link the plugin directory to the Web profile.

  1. Ensure the plugin source directory is available locally.
  2. Run the install command and pass the absolute path of this directory as the argument:
    dsh plugin --profile web add link:<本目录绝对路径>
  1. Restart DSH (run dsh web) to load the plugin.

To uninstall:

dsh plugin --profile web remove dsh-bg-plugin

Desktop Client (Electron) Support

The desktop client and Web client are two independent DSH instances with different Profiles, so they must be installed separately.

  • Profile: $DSH_HOME/profiles/desktop
  • CLI: The desktop client’s built-in CLI is located at <install_directory>\resources\runtime\cli\bin\dsh.cmd

Desktop installation example (Windows):

& "D:\DeepSeek Harness\resources\runtime\cli\bin\dsh.cmd" plugin --profile desktop add link:D:\DSH插件\dsh-bg-plugin

The desktop client must be restarted after installation.

State Persistence

In static installation mode, all configuration items (media source, selection area, and clarity) are automatically saved to the state file:
$DSH_HOME/.dsh-bg-state.json

After refreshing the page or restarting DSH, the plugin automatically restores the previous settings and reapplies the background.

Floating Ball Panel Background Patch

The background rendering of the expanded floating ball panel is controlled by its own code. This plugin injects a background layer into the panel by writing a patch.

  1. Patch Mechanism: After confirmation via a browser dialog, the plugin backs up the original files to $DSH_HOME/.dsh-bg-orb-backup/<timestamp>/.
  2. Modified Files: Overrides dist/helper/assets/floating.html (relaxes CSP) and dist/helper/lib/main.js (injects the background controller).
  3. Rendering Approach: The background layer uses z-index: -1 to sit beneath the panel content and sets isolation: isolate to create a stacking context, ensuring the background moves with the panel expand/collapse animation and is clipped to the panel shape.
  4. Functionality: Supports floating ball background configuration, two-way synchronization with the main application background, and aspect ratio-locked selection.

Automatic Updates

The plugin includes a built-in automatic update feature, which is enabled by default.

  • Check: Opening the settings page triggers a check for the GitHub main branch version at the bottom of the page.
  • Download and Override: If a new version is detected, it is automatically downloaded and the plugin files are overridden (including package.json, lib/, and more).
  • Backup: Before overriding, existing files are backed up to $DSH_HOME/.dsh-bg-update-backup/<timestamp>/.
  • Manual Operation: Manually clicking “Check for Updates” or “Update Now” is supported.

Notes

  • Restart Required: Whether using static installation or dynamic installation, changes to configuration or installation usually require restarting DSH to take effect.
  • Dynamic Version Limitations: The dynamic plugin version is session-level, and its configuration disappears after DSH is restarted.
  • File Permissions: The floating ball patch involves modifying files under the DSH installation directory. Ensure you have write permission.
  • Path Limitations: The fs sandbox only intercepts write operations; reading any directory is allowed. If the system folder selector cannot be used, you can paste the path directly.