dsh-hybrid-notify

dsh-hybrid-notify

简体中文 · English

DeepSeek Harness (DSH) 多通道通知插件 —— 根据窗口可见性自动在页面内 toast、PWA 系统通知、浏览器通知之间切换，并附带 Web Audio 合成音效。

---

功能特性

• 三通道自动选择，按窗口可见性派发：
  • 页面内 toast —— 窗口前台且可见时
  • PWA 系统通知 —— 窗口后台且 PWA 通道可用时
  • 浏览器通知 —— 窗口后台且未注册 Service Worker 时的兜底
• 合成音效 —— Web Audio API 为每种通知级别合成不同音色（成功上行和弦、警告双脉冲等），零音频文件
• 事件级开关 —— 每类事件独立控制：
  • 任务完成
  • 子代理完成
  • 审批请求
  • 用户提问
  • 计划评审请求
  • Agent 出错
  • 后台任务完成
• 通道级开关 —— 分别启停页面内、PWA、浏览器通知
• 音效设置 —— 总开关、音量滑块、前台播放开关、试听按钮
• 持久通知 —— 重要事件（审批请求、错误）驻留直到手动关闭
• HMR 安全 —— 开发热重载后引擎状态不丢
• 自动播放策略合规 —— 首次用户交互后解锁 AudioContext

安装

从 npm 安装（推荐）

dsh plugin --profile web add dsh-hybrid-notify

从 GitHub 安装

dsh plugin --profile web add github:john-walks-slow/dsh-hybrid-notify
# 首次 add 可能被 pnpm 拦截：把 pnpm 提示的包名加入
# ~/.dsh/profiles/web/pnpm-workspace.yaml 的 allowBuilds 后重跑

从源码构建

git clone https://github.com/john-walks-slow/dsh-hybrid-notify.git
cd dsh-hybrid-notify
npm install
node build.mjs

构建产物会部署到 ~/.dsh/profiles/web/node_modules/dsh-hybrid-notify/。

配置

在 DSH Web UI 打开 设置 → 通知。所有设置持久化在 localStorage（键 dsh.notify.config），改完立即生效。

事件

事件	默认	说明
任务完成	开	会话一轮 turn 结束（running → idle）
子代理完成	关	subagent 会话完成
审批请求	开	Agent 请求批准操作
用户提问	开	Agent 向你提问
计划评审请求	开	Plan 模式等待评审
Agent 出错	开	Agent 遇到错误
后台任务完成	关	后台 bash 任务结束

你当前正在前台查看的会话不会弹出通知。

音效

插件用 Web Audio API（振荡器 + 包络整形，无音频文件）为每种通知级别合成独立音色：

级别	音效
成功	温暖大三和弦上行（C5 → E5 → G5）
错误	小调下行（E5 → A4）
警告	440 Hz 双脉冲
信息	柔和双音铃（G4 → B4）

权限与兼容

• 通知权限：PWA 与浏览器通知通道需要浏览器通知权限。首个后台事件到达时会自动请求（仅当权限状态还是 default 时）；设置页每个通道也有 Grant 按钮可手动授权。页面内 toast 通道无需任何权限。
• PWA / Service Worker：PWA 通道的 Service Worker 由插件宿主端在 /plugins/dsh-hybrid-notify/sw.js 提供（作用域 /plugins/dsh-hybrid-notify/）。不支持 Service Worker 的环境自动降级为浏览器通知通道，再降级为页面内 toast。
• 音效：Web Audio API 实时合成，无音频文件下载。受浏览器自动播放策略约束：AudioContext 在你第一次点击/按键时解锁，首次交互前不会有声音。音量可调，另有「前台也播放」开关。
• 零网络访问：插件不发起任何外部请求、不做任何上报。通知内容全部来自本地 DSH 会话列表快照，Service Worker 脚本由本地 DSH 宿主提供，所有设置仅存于 localStorage。
• 兼容性：需要支持 Notification API 与 Web Audio API 的现代浏览器（Service Worker 可选，仅 PWA 通道需要）。部分移动浏览器对 new Notification() 抛异常——这类环境会静默降级为页面内 toast。从源码构建需 Node.js ≥ 18。
• 纯客户端插件：运行时 dependencies 为空；@deepseek-ai/cordis 与 react 由 DSH 宿主运行时提供（以 peerDependencies 声明）。

架构

┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│   In-page    │    │     PWA      │    │   Browser    │
│   Toast      │    │ Notification │    │ Notification │
│  (foreground)│    │  (background)│    │  (fallback)  │
└──────┬───────┘    └──────┬───────┘    └──────┬───────┘
       │                   │                   │
       └───────────────────┬───────────────────┘
                           │
                    ┌──────▼──────┐
                    │   Engine    │
                    │  (singleton)│
                    └──────┬──────┘
                           │
                    ┌──────▼──────┐
                    │  DSH Session│
                    │  List       │
                    │  Snapshot   │
                    └─────────────┘

引擎订阅 DSH 会话列表快照，检测状态迁移（running → idle、待交互），并按窗口可见性把通知派发到合适的通道。

本地开发

前置要求

• Node.js 18+
• 任意 DSH profile

初始化

git clone https://github.com/john-walks-slow/dsh-hybrid-notify.git
cd dsh-hybrid-notify
npm install

构建

node build.mjs

构建 client bundle 与宿主入口，并部署到 web profile 的 node_modules。

类型检查

npm run typecheck

项目结构

src/
├── index.ts                    # 宿主端：SW 路由注册
├── client.ts                   # 客户端插件入口
├── notification-engine.ts      # 核心编排与差分检测
├── notify-config.ts            # 持久化配置存储
├── sound-manager.ts            # Web Audio 音效合成
├── toast-store.ts              # 页面内 toast 状态管理
├── visibility-detector.ts      # 页面可见性与焦点检测
├── types.ts                    # 共享类型定义
├── locales.ts                  # 中英词典
├── dts-shim.d.ts               # 环境类型声明
├── channels/
│   ├── inpage-toast.ts         # 页面内 toast 通道
│   ├── pwa-notification.ts     # PWA 通知通道
│   └── web-notification.ts     # 浏览器通知通道
└── components/
    ├── NotifySettings.tsx      # 设置页 UI（React）
    ├── Toast.tsx               # Toast 组件
    └── ToastContainer.tsx      # shell.overlay 的 Toast 容器

License

MIT

相关项目

• awesome-dsh-plugin —— DSH 插件精选列表
• dsh-notify-web —— 基础通知插件（单通道、无音效）