DSH Notifications Plugin / DSH 对话完成通知插件

Turns your finished turns into a ping. A DSH bundle plugin that pops a macOS system notification (and an optional synthesized chime) whenever a conversation turn completes — so you never miss the answer while your DSH Web GUI is in another window, minimized, or closed.

它解决什么 / The problem

Chatting with DSH and tabbing away means missing the moment the answer lands. You either keep staring at the window, or you miss the reply entirely. This plugin moves the "done" signal out of the browser and onto your desktop.

功能 / Features

• 在「设置 → 通用」中新增 对话完成通知 卡片。

• 启用后，任意根会话（跳过 subagent 与 automation）的一轮对话结束时，由 host 进程弹出 macOS 系统通知：标题为会话名（过长截断），内容为助手回复（过长截断）。即使 Web GUI / PWA 已关闭或切到其他窗口也照常通知。

• 可选提示音：host 侧按设置音调（柔和 / 清脆 / 低沉）程序合成 PCM → 临时 WAV → afplay 播放，波形与设置卡片里的「试听」Web Audio 预览完全一致；无需音频文件，离线可用。

• 「试听提示音」按钮同时用于触发浏览器的通知授权（浏览器要求用户手势才能申请权限）。

• Adds a Turn-complete notifications card to Settings → General.

• When enabled, the host process pops a macOS notification when any root session (subagents and automation runs skipped) finishes a turn — title = session name (truncated), body = the assistant response (truncated). Keeps working with the Web GUI / PWA closed or in another window.

• Optional chime: the host synthesizes PCM from the configured tone (soft / crisp / low) into a temp WAV played via afplay, with the same waveform as the card's Web Audio preview — the configured tone and the real sound always match. No asset files, works offline.

• The "Preview chime" button also triggers the browser's notification-permission prompt (browsers require a user gesture to request it).

行为说明 / How it works

• Host 端：注册持久化设置命名空间 notifications（写入 $DSH_HOME/settings.yaml，键 notifications）； 监听 agent/status 事件，在根 agent 的 running→idle 边沿弹通知（osascript display notification）并 afplay 播放合成提示音；暴露自有 HTTP API /notifications/status（读）与 /notifications/update（写）。

• Client 端：把卡片渲染进通用区的 settings.general.item 插槽；当 host 半已加载（hostNotify 标志）时， 浏览器侧 monitor 静默，由 host 负责弹通知，避免双重通知；host 未加载时退回浏览器侧 monitor + localStorage。

• 说明：Web 端的 settings.mutate RPC 只放行内置命名空间白名单，第三方命名空间无法走该通道； 因此本插件走自有 HTTP API（与 petdex / wechat-bridge 同模式）。host 半载入前（例如刚改完代码、 尚未重启 dsh web），卡片自动降级为浏览器 localStorage，交互与持久化在单浏览器内照常可用； host 半载入后自动切换到 settings.yaml 并同步最新值。

• Host half registers the durable notifications settings namespace ($DSH_HOME/settings.yaml, key notifications), listens to agent/status and fires osascript display notification + afplay on the running→idle edge, and exposes its own HTTP API — GET /notifications/status, POST /notifications/update — persisting through host-side settings.update.

• Client half renders the card into the General section's settings.general.item slot. When the host half advertises hostNotify, the browser monitor stays silent (host owns firing, no double notifications); otherwise it falls back to the browser monitor + localStorage.

• Note: the Web settings.mutate RPC only admits a built-in namespace allowlist, so third-party namespaces cannot ride it; this plugin uses its own HTTP API (same pattern as the petdex / wechat-bridge bundles). Until the host half is loaded (e.g. right after a code change, before restarting dsh web), the card degrades to browser localStorage — interaction and persistence keep working in that browser — and switches to settings.yaml once the host half is live.

设置 / Settings（写入 settings.yaml）

notifications:
  enabled: false   # 一轮对话完成后弹出系统通知 / pop a system notification on turn completion
  sound: true      # 同时播放提示音 / also play a chime
  tone: soft       # soft | crisp | low

启用方式 / Enable

1. 在本机 profile（$DSH_HOME/profiles/web）的 package.json 中：

   • dependencies 增加 "dsh-plugin-notifications": "file:<本仓库路径>"；
   • dsh.profile.bundles 增加 "dsh-plugin-notifications"。

2. 确保 node_modules/dsh-plugin-notifications 可解析到本仓库。

3. 重启 web profile（dsh web），使 host 半生效（否则只有浏览器侧 monitor，GUI 关闭后收不到）。

4. In the web profile ($DSH_HOME/profiles/web) package.json:

   • add "dsh-plugin-notifications": "file:<path-to-this-repo>" to dependencies;
   • add "dsh-plugin-notifications" to dsh.profile.bundles.

5. Ensure node_modules/dsh-plugin-notifications resolves to this folder.

6. Restart the web profile (dsh web) so the host half loads; until then only the browser monitor works (no notifications with the GUI closed).

提示：macOS 系统通知需要操作系统级通知授权（首次弹通知时 macOS 会请求）。 提示音由 host 进程经 afplay 播放，与浏览器授权无关。

Note: macOS asks for notification permission on first use. The chime plays via afplay from the host process and does not depend on browser permissions.

Repository layout / 仓库结构

dsh-plugin-notifications/
├── src/index.js          # Host: registers the `notifications` settings namespace
├── client/client.js      # Client: General card + turn-complete monitor + chime
├── cordis.patch.yml      # DSH bundle patch (host registration)
├── package.json
└── README.md

Topics / 标签

dsh, deepseek-harness, plugin, notification, web-audio

---

试一下： 装上、重启、开一条长会话，然后把窗口切走——回复落地时你的桌面会替你看着。有问题或想要更多音调？提 issue。