Preface

DSH can extend the functionality of DSH Web through plugins. Below is an introduction to leavestring/awesome-dsh-background-plugin, a DSH background settings plugin maintained by leavestring.

It provides DSH Web with background settings that support image uploads / preset atmospheres, with persistent settings that survive restarts. If you want to adjust the workspace background in DSH Web, it places the background adjustment in the settings entry: you can upload JPG / PNG / WEBP / GIF, switch between three preset atmospheres (Aurora, Ember, Rice Paper), and preview changes in real-time within the settings panel.

What This Is

awesome-dsh-background-plugin is a DSH plugin licensed under MIT. The current version in the documentation is 0.1.9.

It solves the problem of providing a background settings option in DSH Web for adjusting background images, preset atmospheres, and display parameters.

Verified capabilities include:

  • Supports uploading images, processed locally in the browser without sending them to third-party image services.
  • Supports one-click switching between three preset atmospheres.
  • Supports fine-tuning across five dimensions: image presence, dark overlay, soft focus, fit mode, and focal point.
  • Real-time preview within the settings panel, what you see is what you get.
  • Persistent settings that survive restarts.
  • Supports bilingual interface in Chinese / English.
  • Works correctly in light / dark themes.

Core Features

Image Upload and Local Processing

The plugin supports uploading JPG / PNG / WEBP / GIF images.

Images are compressed locally in the browser, with the long edge ≤ 1600px, and output as WEBP. Images are processed locally in the browser without being sent to third-party image services.

Preset Atmospheres

Three preset atmospheres are supported:

  • Aurora
  • Ember
  • Rice Paper

Click a preset to switch instantly.

Fine-tuning Display Parameters

Supports fine-tuning across five dimensions:

  • Image presence
  • Dark overlay
  • Soft focus
  • Fit mode
  • Focal point

These parameters can be dragged and previewed within the settings panel, what you see is what you get.

Persistence and Removal

Settings are persistent and survive restarts. Automatic persistence upon upload is available from version 0.1.6 and above; the current version in the documentation is 0.1.9.

To remove the background, you can turn off the “Enabled” toggle or click “Restore Defaults”. The documentation states that turning off the “Enabled” toggle or clicking “Restore Defaults” completely removes it.

Installation and Activation

The documentation provides both a one-click installation command and a manual installation process, offering more than one installation method. First, prepare the environment, then follow the process in the documentation.

Environment Requirements

Node.js ≥ 18
pnpm
DSH

Getting the Code

Repository address:

https://github.com/leavestring/awesome-dsh-background-plugin

One-Click Installation

Run in the repository directory:

node scripts/install.mjs

Manual Installation

The manual installation command references the local plugin package awesome-dsh-background-plugin-0.1.9.tgz. After preparing this file according to the manual process in the documentation, run:

dsh plugin --profile web add ./awesome-dsh-background-plugin-0.1.9.tgz

This command installs the plugin into the web profile.

Whitelist Configuration

You must add ui-background to the WEB_SETTINGS_NAMESPACES whitelist of dsh-host-apiproxy, otherwise saving will be rejected.

The relevant namespace and field are as follows:

ui-background
WEB_SETTINGS_NAMESPACES

Restart and Refresh

After installation, you need to completely stop and restart DSH. The browser may require Ctrl+F5 to force refresh.

After the above steps, open:

Settings → General Settings → Background

to see the background settings.

Typical Usage

  1. Open Settings → General Settings → Background.

  2. Click a preset, or upload an image. It takes effect and persists immediately upon upload, no need to click save.

  3. Drag the “Image Presence / Dark Overlay / Soft Focus” sliders for real-time preview, and click Save Background to persist the parameters once satisfied.

  4. To remove the background: click Restore Defaults, or turn off the “Enabled” toggle and save.

Applicable Scenarios and Notes

Suitable for developers who use DSH Web, want to adjust the background appearance, and prefer local image processing. It is recommended to review the source code and license before installation; the plugin runs with the current dsh process permissions.

Things to note:

  • The current version in the documentation is 0.1.9, and automatic persistence upon upload is available from version 0.1.6 and above.
  • If the ui-background whitelist is not configured, saving will be rejected.
  • After installation, you need to completely stop and restart DSH, and the browser may require Ctrl+F5 to force refresh.
  • The community directory page is an independent site and has no official affiliation with DeepSeek / High-Flyer.

Links