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.

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

1. Clone this repository somewhere permanent — the profile links to that folder.

2. 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>"
   

3. 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.