dsh-plugin-notifications

<!-- Hero --> <div align="center"> <b style="font-size: 1.15em;">Turn 完成 → macOS 系统通知(可选合成提示音)。即使 Web GUI 已关闭或切到其他窗口,照常提醒。</b><br /><br /> <a href="https://github.com/NattoCB/dsh-plugin-notifications/blob/main/LICENSE"><img alt="License" src="https://img.shields.io/badge/License-MIT-yellow.svg" /></a> <img alt="platform" src="https://img.shields.io/badge/platform-macOS-blue" /><br /><br /> <img alt="对话完成通知" src="https://img.shields.io/badge/-对话完成通知-4d6bfe" /> <img alt="macOS系统通知" src="https://img.shields.io/badge/-macOS系统通知-4d6bfe" /> <img alt="合成提示音" src="https://img.shields.io/badge/-合成提示音-4d6bfe" /> <img alt="Settings卡片" src="https://img.shields.io/badge/-Settings卡片-4d6bfe" /> <img alt="离线可用" src="https://img.shields.io/badge/-离线可用-4d6bfe" /><br /><br /> <a href="https://awesome-dsh-plugin.com"><img src="https://awesome-dsh-plugin.com/badge.svg" alt="awesome · DSH 插件" /></a><br /><br />

<b>监听 <code>agent/status</code> 根会话 running→idle 边沿 · 自有 HTTP API <code>/notifications/status|update</code> · 配置落 <code>$DSH_HOME/settings.yaml</code></b> —— <code>ctx.on('agent/status')</code>

</div>

> 一个 DSH bundle 插件:在「设置 → 通用」新增对话完成通知卡片。启用后,任意根会话(跳过 subagent 与 automation)一轮对话结束时,由 host 进程弹出 macOS 系统通知——标题为会话名、正文为助手回复(过长截断),并可选播放与卡片试听完全一致的合成提示音。接入:在 web profile 声明依赖与 bundle,重启 dsh web。 > > A DSH bundle plugin that adds a Turn-complete notifications card to Settings → General. When any root session (subagents and automation runs skipped) finishes a turn, the host process pops a macOS notification — title = session name, body = the assistant reply (truncated) — with an optional chime identical to the in-card preview. Install by declaring it as a dependency and bundle in your web profile, then restart dsh web.

✨ 功能一览 / Features

• 🔔 对话完成通知 — host 监听 agent/status,在根会话 running→idle 边沿用 terminal-notifier 弹系统通知:标题 = 会话名(session/title → 首条用户消息 → agent id,UTF-8 安全截断 60B),正文 = 最新助手回复(截断 200B);GUI 关闭也照常。subagent 与 automation 驱动的回合不触发;通知仅提示,点击不打开任何窗口。 / Host fires on the running→idle edge of root sessions; subagent and automation-driven turns are skipped. Clicking the banner does nothing (no -activate).
• 🔊 合成提示音 — 按音调(柔和 / 清脆 / 低沉)进程内合成 16-bit PCM 单声道 WAV(44.1kHz;20ms 线性起音 + 指数衰减;音符间隔 120ms),经 terminal-notifier -sound 播放;与卡片「试听」的 Web Audio 波形参数完全一致,听到即所得。无音频资源,离线可用。 / Chime synthesized to WAV with the exact profiles the card previews in Web Audio — no asset files, works offline.
• 🎛️ Settings 卡片 — 渲染进「设置 → 通用」的 settings.general.item 插槽,提供启用 / 提示音开关、音调选择与「试听提示音」按钮(该按钮同时作为用户手势触发浏览器通知授权);UI 中英双语。 / Card in Settings → General (zh/en) with enable, sound, tone and a preview button that doubles as the browser's notification-permission gesture.
• 💾 持久化与降级 — 配置写入 $DSH_HOME/settings.yaml(命名空间 notifications),经自有 HTTP API GET /notifications/status、POST /notifications/update(settings.mutate RPC 只放行内置命名空间,第三方走自有路由,与 petdex / wechat-bridge 同模式);host 半未加载时自动降级为浏览器 monitor + localStorage,host 加载后接管,避免双重通知。 / Persists via its own HTTP API into settings.yaml; before the host half loads, the browser monitor + localStorage takes over, then defers to the host.

Quick Start

前置 / Prerequisites

• macOS(host 使用 Homebrew 前缀路径 /opt/homebrew)
• terminal-notifier:brew install terminal-notifier(host 弹通知与播放提示音的二进制,路径硬编码 /opt/homebrew/bin/terminal-notifier)
• DSH web profile($DSH_HOME/profiles/web)

安装 / Install

1. 在 $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 关闭后收不到通知。

启用 / Enable

1. 打开 Web GUI → 设置 → 通用 → 对话完成通知,开启「启用系统通知」。 2. 可选:开启提示音、选择音调(柔和 / 清脆 / 低沉);点「试听提示音」试听。 3. macOS 首次弹通知时,在系统提示中授予通知权限。

Configuration

写入 $DSH_HOME/settings.yaml(也可直接在设置卡片中修改):

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

---

<div align="center">

GitHub · Issues · [Changelog](CHANGELOG.md) · MIT License

</div>