dsh-notify-desktop
· 中文文档 · English
Windows toast notifications for the DSH desktop app. A session finishes, fails, or stops to ask you
something — you get a native notification with a sound chosen for that situation, and clicking it brings
the DSH window back to the front.
Notification settings
What you get
- Told when it matters — turn ends (completed, error, aborted, blocked, max-tokens), approval
requests, questions, plan reviews, and one nudge for a wait that drags on.
- Quiet when you are there — nothing pops while the DSH window has focus, and each event notifies
once (three-second de-duplication).
- A sound per situation — four groups (finished, error, waiting on you, still waiting), each picked
from the Windows sounds, the author sounds shipped in
sounds/, or your own files.
- Your own sounds — Add sound… copies the file you pick into the plugin's folder, so several can
coexist and each can be removed later.
- Never a long ring — a file sound stops after eight seconds, and stops at once when you mute
notifications or come back to the window.
- Click to come back — the toast raises the DSH window; it deliberately does not jump to the session.
Requirements: Windows and the DSH desktop app (profile desktop), runtime 0.2.x. ffmpeg on PATH is
optional and only used to transcode custom sounds that are not .wav.
Install
From npm
& "<DSH desktop install>\resources\runtime\cli\bin\dsh.cmd" plugin --profile desktop add dsh-notify-desktop
Then restart the DSH desktop app and open Settings → Notifications (Ctrl+, while focused).
From a local checkout
-
Clone this repository somewhere permanent — the profile links to that folder.
-
Register it with the desktop app's own CLI:
& "<DSH desktop install>\resources\runtime\cli\bin\dsh.cmd" plugin --profile desktop add "link:<path-to-this-repo>"
-
Restart the DSH desktop app, then open Settings → Notifications (Ctrl+, while focused).
Settings
Every switch lives in one section of the settings page. Preferences are stored in the renderer's
localStorage and apply immediately.
| Control | What it does |
|---|
| Enable notifications | Master switch; nothing else fires while it is off |
| Sound | Mutes every situation group at once |
| Sounds | One picker per group, each with a preview button |
| Custom sounds | Add, list and remove your own files |
| Transcode cache | Shows what transcoded wavs occupy, and clears them |
| When to notify | One switch per turn-end reason |
| Waiting on you | One switch per interaction kind |
| Reminder | Minutes before the single nudge, plus a test button |
Sounds
Three sections. Every picker opens a two-level list: the source first, that source's sounds second.
- Windows sounds — twenty built-in choices: the five toast events plus the media library
(
chimes, ding, tada, Windows Error, Critical Stop, Alarm0x, Ring0x, …).
- Author sounds — the four
.wav files in sounds/. Drop another file in that folder and
it appears; no code change is involved.
- Custom sounds — your own imports.
Your own files. Add sound… copies the file into %LOCALAPPDATA%\dsh-notify\custom, so the
original can move or be deleted afterwards. Accepted formats are .wav, .mp3, .m4a, .aac,
.wma, .flac, .ogg and .opus.
When a sound stops. A .wav plays directly. Anything else is transcoded once with the ffmpeg on
your PATH and lands in the transcode cache below the list, which reports its size and can clear it. File
sounds are capped at eight seconds, and a sound already playing stops immediately when you switch sound
off or when the DSH window regains focus. Without ffmpeg, wav files and the two shipped libraries still
work; the diagnostics route reports media.ffmpeg: null.
Why custom sounds exist. A toast can only reference five ms-winsoundevent values, and on Windows 11
those resolve to four very similar chimes — Notification.IM and Notification.SMS are literally the
same file. Playing the audio from the host is the only way to get sounds that are actually distinguishable.
Compatibility
| |
|---|
| Verified on | DSH desktop 0.2.1-rc.2 (2026-10-18): version gate, plugin loading, projection delivery, host toast / sound / silence routes, dsh://open focus and a real Windows toast all pass (evidence); earlier runs on 0.2.1-rc.1 and 0.2.0-rc.2 also passed |
| Declared range | >=0.2.0-rc.2 <0.3.0-0 — the whole 0.2 line, prereleases included; the loader checks it with includePrerelease, so 0.2.1-rc.2 passes |
| Platform | Windows desktop profile only; the web profile has no toast channel and is untested |
| 0.2.1 seam check | The 0.2.1-rc.2 runtime image ships no .d.ts; every seam used here was checked against its compiled JS and still matches |
The profile loader reads the peerDependencies entries named @deepseek-ai/dsh or @deepseek-ai/dsh-*
and checks them with semver.satisfies(runtime, range, { includePrerelease: true }). A mismatch makes it
skip the plugin rather than load it. On another runtime, grant an exemption:
dsh.cmd plugin --profile desktop allow-version dsh-notify-desktop@0.1.1 --dsh-version <your-version> --accept-risk
How it works
Two halves, and no harness code is modified.
- The host half registers one session projection (
notify) and a few same-origin routes.
- The client half reads that projection from the session list, decides whether a notification is
warranted, and sends it: a host PowerShell toast while the window is unfocused, the renderer's own
notification as the fallback.
Questions arrive from two places on purpose, and neither can be dropped. Questions asked as tool calls
reach the projection; service-level asks such as the plan review never enter the session log, so the host
observes the user-questions/request waterfall with { global: true } and hands them to the client over
a bounded queue. A cross-source key keeps the two copies from double-toasting.
| Route | Purpose |
|---|
GET /dsh-notify/debug | Projection state, recent client reports, ffmpeg and player status |
POST /dsh-notify/toast | Raise one toast (title, body, sound id) |
POST /dsh-notify/focus | Raise the window through dsh://open |
POST /dsh-notify/silence | Stop the sound that is playing |
GET/POST /dsh-notify/sound-library | List the two library folders |
POST /dsh-notify/import-sound, /delete-sound | Add or remove a custom sound |
GET/POST /dsh-notify/sound-cache | Report or clear the transcode cache |
POST /dsh-notify/pick-file, GET /dsh-notify/foreground | Windows file picker; OS-level focus answer |
GET /dsh-notify/questions | Poll the host-side question queue |
Troubleshooting
Windows toasts never reach the Action Center, so the diagnostics route is the only evidence channel:
Invoke-WebRequest http://127.0.0.1:19387/dsh-notify/debug
It returns the projection registration state, the last 40 client reports (every decision, channel choice
and platform result), and the sound plumbing (media.ffmpeg, media.soundPlayers).
Development
pnpm install
pnpm run check # typecheck + vitest + build
lib/ is committed on purpose: the profile links to this folder, so the built bundles ship with the
source. AGENTS.md holds the repository rules and the measured constraints that must not be
"optimised" away — the host bundle stays self-contained, the toast spawn keeps piped stdio, and audio goes
through System.Media.SoundPlayer only.
Known limits
- No tray badge, taskbar badge or window flashing; those need main-process APIs a plugin cannot reach.
- Clicking a toast raises the window, it does not navigate to the session.
- The
error and max-tokens turn ends are covered by unit tests only; they were never reproduced live.
- A toast cannot be observed being dismissed, so file sounds are capped rather than tied to the toast.
- Windows desktop profile only.
License
MIT · third-party notices in THIRD-PARTY-NOTICES.md.
Unofficial plugin: not affiliated with, endorsed by, or sponsored by DeepSeek. "DeepSeek", "DSH" and
"DeepSeek Harness" are used descriptively, to say what this plugin plugs into.
