dsh-clipboard-png
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/pngamong the ten targets they offer, so the browser hands DSH a "PNG" whose bytes start withBM; - some screenshot tools and browsers publish a capture as
image/bmponly.
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-typesprocess), 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 whilewl-pastekeeps 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 isimage/pngand 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-pastecannot leave an orphan behind. - Both
wl-pasteandmagickare checked at startup; if either is missing the plugin logsdisabled: 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— provideswl-pasteandwl-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-copyreplaces 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.
No comments yet. Be the first to write one.