对话完成通知aokamoaki/dsh-notify

🔔 dsh-notify

简体中文 | English

DeepSeek Harness 对话完成通知插件 —— 回合完成、出错、目标完成、提问、审批时，在你离开应用时弹出 Windows 通知（toast + 提示音），前台自动静默。零配置，会话头部铃铛即控制中心。

Check version license node dsh tests

📖 简介

在 DeepSeek Harness（DSH）里跑长任务时，你常常切去别的窗口。dsh-notify 会在对话回合结束、出错、目标达成时用 Windows 原生 toast + 提示音提醒你，只在应用处于后台时打扰：页面可见或桌面壳任一窗口聚焦时，完成类通知自动静默；而「需要你回来操作」的提问 / 审批类通知始终提醒——那正是要打断你的场景。

✨ 功能特性

- 🔔 会话头部铃铛：通知总开关（点击静音/恢复）+ 音量滑块（0–100%），实时落盘
- 🛌 仅后台触发：web 页面可见 或 桌面壳任一窗口聚焦时，完成类通知静默
- ⚠️ 提问/审批始终提醒：ask_user_question、approval/asked 不因前台而静默
- 🔇 总开关：关闭后所有通知（含提问/审批）全部静默，重启仍生效
- 🌐 双语：toast 文案跟随 Windows 显示语言（中文 / English）
- ⚙️ 零配置起步，配置文件热更新，无需重启
- 🧵 智能去重：同会话 5 秒内不重复打扰；回合完成仅在 agent 保持空闲时提醒（800ms 去抖）；subagent 内部会话不通知

📦 安装

dsh plugin --profile web add github:aokamoaki/dsh-notify

重启 dsh web 生效。

本地开发（link 方式）：把仓库放到任意目录，然后在 profile 的 package.json 中以 link 引入：

"dependencies": { "dsh-notify": "link:C:/path/to/dsh-notify" }

并确保 dsh.profile.bundles 含 "dsh-notify"。

🚀 快速开始

安装并重启后无需任何配置即生效。默认行为：

- 对话回合完成 → 「对话」完成 · 耗时（仅后台）
- 回合出错 → 「对话」出错 · 耗时（仅后台）
- 目标完成 → 目标完成（仅后台）
- agent 提问（ask_user_question）→ 需要你选择（始终）
- 审批请求（approval/asked）→ 需要你批准 : 工具名（始终）

不想被打扰？点会话头部的 🔔 铃铛即可一键静音，悬停可调音量。

⚙️ 配置

配置文件：~/.dsh/dsh-notify.json（不存在时用默认值；铃铛操作实时写回）。

| 字段 | 默认 | 说明 | 控制入口 |
| :-- | :-- | :-- | :-- |
| notifications | true | 通知总开关（关 = 全部静默） | 铃铛点击 |
| volume | 1 | 提示音音量 0–1 | 铃铛滑块 |
| sound | true | 提示音开关 | 配置文件 |
| toast | true | 系统弹窗（toast）开关 | 配置文件 |
| serviceNotify | true | 服务类通知开关（桌面壳读取） | 配置文件 |

📡 HTTP API

| 端点 | 方法 | 说明 |
| :-- | :-- | :-- |
| /dsh-notify/config | GET | 读取当前配置 |
| /dsh-notify/config | POST | 局部更新配置（{"volume": 0.5}），原子写盘 |
| /dsh-notify/foreground | GET | 前台状态快照（{page, shell, foreground}） |
| /dsh-notify/foreground | POST | 上报前台状态（{"page": bool} 页面 / {"shell": bool} 桌面壳） |

所有端点仅接受同源请求（sec-fetch-site 校验），非浏览器来源会被拒绝。

🏗️ 架构

web 页面 (lib/client.js)  ──visibilitychange / focus──►  POST /dsh-notify/foreground {page}
桌面壳 (Electron)         ──任意窗口 focus/blur──────►  POST /dsh-notify/foreground {shell}
│ 合并：foreground = page || shell
宿主插件 (lib/index.js)  ──notify()──┐                        ▼
session/event、goal/changed 事件  │   done/error/goal 前台静默、ask 始终弹
└─► notify.ps1 ──► Windows toast + 提示音

- host（lib/index.js）：事件驱动；配置 / 前台状态 API；notify() 读取配置 → 调用 notify.ps1
- client（lib/client.js）：会话头部铃铛 UI；页面可见性 / 焦点上报
- notify.ps1：toast 与提示音执行器（-SoundType done|error|ask、-Volume、-NoSound、-NoToast）
- 前台状态为内存态（不落盘）；初始态为后台，确保上报链路故障时不会静默吞掉通知

🔌 兼容性

- 平台：Windows（toast 经 PowerShell + Windows 通知）
- DSH：web 版（dsh web），桌面壳可选（上报 shell 前台状态）
- Node：>=22.13

🛠️ 开发

dsh-notify/
├── lib/
│   ├── index.js      # 宿主入口（事件 + API；纯决策/参数逻辑可单测）
│   ├── client.js     # 浏览器端（铃铛 UI + 前台上报）
│   ├── notify.ps1    # toast / 提示音执行器
│   └── activate.ps1  # toast 点击处理（仅打开本机 DSH 地址，安全校验）
├── test/notify.test.mjs  # 22 个用例（node:test，零依赖，spawn 注入间谍）
├── cordis.patch.yml  # bundle 注册
└── package.json

client 构建约束：lib/client.js 必须是 DSH client-bundle 产物格式——
window.__ModuleLoader__.load({ id, factory })，禁止 import / JSX。修改后保持该包装结构，否则浏览器加载会报 "loaded without registering"。

验证：

npm run check        # node --check lib/index.js lib/client.js
npm test             # 22 个用例（配置/决策/事件接线/HTTP 路由；不真起 powershell）
npm run pack:check   # 发布包内容检查

运行时 API 自检：curl http://127.0.0.1:3080/dsh-notify/config。

🩺 故障排查

| 现象 | 处理 |
| :-- | :-- |
| 完全收不到通知 | 检查 ~/.dsh/dsh-notify.json 的 notifications/sound/toast 是否被关闭；页面是否处于可见状态（前台静默是设计行为） |
| 前台也弹通知 | 上报链路可能中断（/dsh-notify/foreground 被同源校验拦截）；刷新页面后应恢复 |
| 铃铛不见了 / GUI 启动异常 | 若 dsh-startup-guard 检测到本插件损坏会自动禁用并在 cordis.patch.yml 追加 disabled: true（附原因注释）；修复源码后删除该条目并重启即可 |
| 通知延迟 | 回合完成类有 800ms 去抖 + 空闲判断；同会话 5 秒去重 |

📄 许可

MIT

DeepSeek Harness 社区插件，与 DeepSeek 官方无关。