DSH HUB
HomePlugin StorePlugin PacksCommunityRankingsResourcesPublish Guide
Plugin source
Back to catalog

pengtang1024 /

pengtang1024/dsh-clipboard-png

Verified

DSH host plugin: normalize non-PNG clipboard images (WeChat BMP screenshots) to real PNG on Linux Wayland, so pasting into the composer works.

★ 0 Stars0 Forks2 IssuesN/A Community rating0 Confirmed installs
View on GitHub
READMESource: master@e15a7510

dsh-clipboard-png

CI License: MIT Node.js >= 20

A DeepSeek Harness host plugin for Linux Wayland. It rewrites clipboard images that are not PNG into real PNG before the browser reads them, so pasting a WeChat / Qt screenshot stops failing with "Only PNG, JPG, WebP, and GIF images are supported".

Table of contents

  • Why
  • How it works
  • Requirements
  • Install
  • Verify
  • Limits
  • Privacy and safety
  • Documentation
  • Contributing
  • License

Why

DeepSeek Harness accepts exactly four image MIME types in its attachment pipeline — image/png, image/jpeg, image/webp, image/gif — and it trusts the type the browser reports: it never sniffs the bytes. A lot of Linux clipboard producers break that contract:

  • WeChat and other Qt applications put BMP (DIB) bytes on the clipboard while announcing image/png among the ten targets they offer, so the browser hands DSH a "PNG" whose bytes start with BM;
  • some screenshot tools and browsers publish a capture as image/bmp only.

Either way the paste is rejected before an attachment is ever created, and the red toast is the same one a genuinely unsupported format produces — even though the pixels are fine.

This plugin normalizes the clipboard before the browser reads it, on the host side, so no browser-side hook is involved.

How it works

 copy a screenshot           dsh-clipboard-png                    paste into the composer
 ─────────────────►  poll wl-paste ──────────────►  wl-copy -t image/png ──────────►  real PNG
 (BMP bytes,          every 600 ms;                (decoded by ImageMagick,            → accepted
  claimed as PNG)     sniff magic bytes,            capped at 4096 px per side)
                      convert only if needed
  • It polls on a 600 ms cadence, reading the clipboard type list each round (one short wl-paste --list-types process), and pulls the bytes only when the offered targets or the first 16 bytes change — a text clipboard is never read. Polls are serialised, and while wl-paste keeps failing the delay backs off exponentially (600 ms → 1.2 s → … → 30 s) until a round succeeds.
  • It inspects the first image/* target in that list. If the only offered target is image/png and the bytes really are a PNG, it does nothing.
  • Anything else image-like is decoded and re-encoded as PNG (metadata stripped, long side capped at 4096 px), verified by magic bytes, and only then written back with wl-copy -t image/png.
  • It never publishes an empty or unverified image: a failed conversion leaves the clipboard alone.
  • Every helper runs in its own process group and is killed as a group on timeout, so a stuck wl-paste cannot leave an orphan behind.
  • Both wl-paste and magick are checked at startup; if either is missing the plugin logs disabled: missing … and stays idle instead of polling.

The full design — including why the plugin cannot use wl-paste --watch on GNOME — is in docs/how-it-works.md.

Requirements

  • Linux with Wayland (native wl-clipboard). X11 sessions are not supported; the plugin never touches display-server configuration.
  • wl-clipboard — provides wl-paste and wl-copy.
  • ImageMagick 7 — provides magick.
  • DSH with profile-based plugin installs (any current version).
  • Node.js 20 or newer to run the host, as declared in package.json.
sudo apt install wl-clipboard imagemagick

Install

dsh plugin --profile <profile> add github:pengtang1024/dsh-clipboard-png

Examples: --profile web, --profile desktop (the desktop app's bundled profile).

Restart is not required on host-side HMR builds; if your build does not hot-reconcile plugins, restart the app once after installing.

To remove it:

dsh plugin --profile <profile> remove dsh-clipboard-png

Verify

The host log should contain, once:

[dsh-clipboard-png] watching Wayland clipboard for non-PNG images

and after the next conversion:

[dsh-clipboard-png] converted clipboard image (image/bmp, 11802 bytes) to PNG

If wl-clipboard or ImageMagick is missing you get, instead of the first line:

[dsh-clipboard-png] disabled: missing wl-paste (install wl-clipboard)
[dsh-clipboard-png] disabled: missing magick (install imagemagick)

Manual check without DSH — put a BMP on the clipboard and watch the plugin turn it into PNG:

magick -size 64x48 gradient:red-blue /tmp/x.bmp
wl-copy -t image/bmp < /tmp/x.bmp
sleep 2 && wl-paste --list-types && wl-paste -t image/png | head -c8 | xxd -p
# expect: image/png   and   89504e470d0a1a0a

The expected magic bytes are the eight-byte PNG signature. If the plugin is not running, the same commands show image/bmp and the bytes 424d (BM) instead.

Symptoms and fixes are collected in docs/troubleshooting.md.

Limits

  • Linux Wayland only. On macOS, Windows and X11 sessions the plugin stays inert.
  • Conversion happens within one poll interval (~0.6 s). Pasting in the same instant as copying can still race it — wait a moment after copying.
  • Only raster formats ImageMagick can decode (BMP, TIFF, TGA, PCX, Netpbm, PSD, most RAW, …).
  • One image at a time: the clipboard carries a single image, and wl-copy replaces the selection as a whole.
  • Metadata is stripped deliberately; if you need the original palette or EXIF, do not use this plugin.
  • A clipboard payload larger than 24 MiB exceeds the read cap (MAX_READ) and is not converted; send such images as files.
  • Failed conversions are not retried for unchanged clipboard content; copy again to trigger a new attempt.
  • The plugin only looks at the first image/* target a producer offers.
  • After 20 consecutive failed polls the watcher stops and logs clipboard became unavailable, stopping; restart the host to arm it again.

Privacy and safety

The bytes never leave your machine: wl-paste, magick and wl-copy are local processes, there is no network code in this plugin, and no file is written outside a temporary directory that is removed immediately. It does read whatever image you put on the clipboard — that is the entire point — so treat it like any other clipboard tool. ImageMagick parses that image, so keep ImageMagick updated.

See SECURITY.md for the threat model and how to report a vulnerability.

Documentation

Document Contents
docs/how-it-works.md The four-type whitelist, WeChat's BMP masquerade, the polling and fingerprint design, and the empty-content guard.
docs/configuration.md Why there are no user options, and where the source constants live.
docs/troubleshooting.md Symptom → check → fix matrix.
CHANGELOG.md Release history (Keep a Changelog).
CONTRIBUTING.md Development setup, tests, commit conventions, review checklist.
SECURITY.md Private reporting and threat model.
CODE_OF_CONDUCT.md Contributor Covenant 2.1.

A Chinese translation of this file is available at README.zh.md.

Contributing

Issues and pull requests are welcome. Please read CONTRIBUTING.md first; it covers the local setup, how to run the test suite, the commit message format and the manual conversion check. This project follows CODE_OF_CONDUCT.md.

License

MIT — see LICENSE.

DSH HUB

A community index for DSH plugins. Not an official GitHub or DeepSeek AI product.

CommunityResourcesAPIAbout
—/ 5

No ratings yet

Verified DSH bundle

Commit e15a75102e3f

Community comments

No comments yet. Be the first to write one.