deepseek-harness-background

DeepSeek Harness Background

English | 中文

A custom background image plugin for the DeepSeek Harness Web GUI (dsh web): upload a local picture, or paste an image URL, and render it behind the whole app surface with adjustable opacity, readability scrim, panel transparency and frosted-glass blur — everything live-previewed inside the settings panel and committed automatically on release.

The look (fixed wallpaper layer + theme-aware scrim + translucent glass panels driven by --dsw-* design tokens) is modeled on the community dsh-wallpaper-engine implementation.

Screenshots

Home
Conversation
Settings

Features

• Local upload — pick a JPG / PNG / WebP / GIF from your computer; the plugin stores it under the harness home and serves it over a same-origin route (admitted only when the declared MIME, detected signature and extension all agree).
• Paste a URL — drop an http(s) image link and press Enter.
• In-panel live preview — a preview surface at the top of the row renders the image + scrim + a frosted glass bubble; dragging any slider repaints it instantly.
• Stepped sliders — ratio controls snap in 5% steps, blur radii in 1/2px steps; dragging only repaints, release commits (one write per gesture, no jank).
• Five controls — wallpaper opacity, readability scrim, panel opacity, frosted-glass blur, and wallpaper blur.
• Fit modes — cover (fill, crop) or contain (whole image).
• Theme-aware scrim — the light theme uses a white veil (lifts the art so dark text keeps contrast); the dark theme automatically switches to a black veil (dims the art so light text keeps contrast).
• Frosted glass — while a background is active, the composer card and message bubbles turn into translucent glass over the wallpaper (specular sheen + backdrop-filter), with the blur radius driven by the glass-blur slider. panelOpacity at 100% restores the official opaque surfaces.
• Persisted in the official settings document ($DSH_HOME/settings.yaml), waits out restarts.
• Clean teardown — disabling, clearing or uninstalling restores the original background exactly; the plugin only ever removes what it wrote.

Install

The plugin is a standard out-of-tree dsh bundle:

dsh plugin --profile web add /path/to/deepseek-harness-background

From a source checkout:

pnpm dsh plugin --profile web add /path/to/deepseek-harness-background

Or from git:

dsh plugin --profile web add github:<you>/deepseek-harness-background#<commit>

Restart to load it:

dsh --profile web

Usage

1. Start the Web UI (dsh --profile web) and open it in a browser.
2. Open Settings (bottom-left) → General → the Custom Background row (in the same area as the Appearance row).
3. Upload an image or paste a URL — the background applies immediately and the preview surface above updates in sync.
4. Tune the controls — sliders snap in steps and commit on release:

Control	Meaning
不透明度 / Opacity	0..100% image opacity (5% steps); lowering it fades the wallpaper toward the surface.
遮罩 / Scrim	0..95% readability veil over the image (5% steps); white in light mode, black in dark mode.
面板不透明度 / Panel opacity	0..100% surface transparency (5% steps); at 100% the official panels stay opaque (no glass).
毛玻璃模糊 / Glass blur	0..40px backdrop-filter blur on the translucent surfaces (1px steps).
壁纸模糊 / Wallpaper blur	0..60px blur of the wallpaper image itself (2px steps).
填充方式 / Fit	cover or contain.

5. 清除背景 removes the background and restores the stock look.

How it works

• The settings row lives in the official General settings section (settings.general.item slot), next to the Appearance row. Its chrome uses only --dsw-alias-* design tokens (buttons / pills / segmented control / slider track match the official shell); sliders are native input[type=range] with 5% / 1–2px steps and release-commit.
• The plugin's own host routes (/api/bg-wallpaper/*: settings, upload, image/<id>) read/write the section and serve uploads with same-origin + size caps + MIME/signature checks + a path-escape fence. A custom route family is used because the api-proxy settings allowlist does not expose third-party namespaces over the settings RPC.
• The background is drawn as a fixed z-index:-2 wallpaper layer plus a z-index:-1 scrim on body, toggled by the data-dsh-bg attribute; the scrim switches white/black by data-ds-dark-theme in the injected stylesheet; the frosted-glass effect overrides the shell's surface design tokens.
• Uploads live under $DSH_HOME/deepseek-harness-background/ (content-addressed ids). Switching to a new image or clearing the background deletes the superseded upload file, so the directory never accumulates dead images. Disable / uninstall leaves nothing behind.

Development

pnpm install          # first time; runs prepare (build)
pnpm run typecheck    # tsc
pnpm test             # vitest contract tests
pnpm run build        # tsdown: lib/index.js (host) + lib/client.js (browser bundle)

deepseek-harness-background/          # the plugin repo (package name stays the npm-style id)
├── package.json          # dsh.bundle.patch + dsh.client.inject declarations
├── cordis.patch.yml      # inserts the deepseek-harness-background row into the web roster
├── tsdown.config.ts      # official clientBundle preset
├── src/
│   ├── index.ts          # host half: ui-background namespace + API routes
│   ├── routes.ts         # /api/bg-wallpaper/{settings,upload,image/<id>}
│   ├── schema.ts         # host-side schemastery schema
│   ├── settings.ts       # constants/types shared with the client
│   ├── harness-home.ts   # $DSH_HOME / ~/.dsh resolution
│   └── client/
│       ├── index.ts          # painter lifecycle + settings row registration
│       ├── backdrop.ts       # fixed wallpaper layer + scrim + glass surface + preview vars
│       ├── background-css.ts # injected stylesheet (layers, glass, light/dark scrim, variables)
│       ├── SettingsRow.tsx   # the General-settings row (preview surface + stepped sliders)
│       ├── SettingsRow.module.css # row styles (official tokens)
│       ├── settings-client.ts# fetch transport (read/write/upload)
│       └── locales.ts        # zh/en copy
└── tests/                  # schema, routes, apply (painter), settings-row contracts

License

MIT