dsh-notify-hub 通知插件

DSH（DeepSeek Harness）的可分发插件包（npm：dsh-notify-hub）：在 Web GUI「设置」页新增「通知」分区， 实现事件驱动的声音提醒与企业微信 / 飞书消息推送。

安装 / 更新 / 重启

# npm
dsh plugin --profile web add dsh-notify-hub

# 或直接从 GitHub 安装
dsh plugin --profile web add git+https://github.com/wumu-366/dsh-notify.git

卸载用 dsh plugin --profile web remove dsh-notify-hub； 更新用 update（更新不改 lib/host.js 时自动热重载生效）。

功能

• 四类事件节点（均可独立启停，卡片默认折叠、点击卡片头部任意位置展开）： | 事件 | 检测信号 | 默认音效 | |---|---|---| | 任务完成 | 会话事件 turn/end · reason.kind === "completed" | success（上行三音） | | 需要回答问题 | tool/call · ask_user_question（问题 header 进入摘要） | question（疑问短句） | | 权限审核 | approval/asked（工具名 + 原因进入摘要） | alert（注意提示） | | 任务失败 | turn/end · reason.kind === "error"（错误信息进入摘要） | error（下行低鸣） |
• 声音：
  • 内置 6 种 Web Audio 合成音效：success / ding / alert / error / question / chime；
  • 自定义音频：上传 wav/mp3/ogg 等（≤2MB，存为 data URL）、https URL、本机绝对路径 （宿主读取后回传 data URL，≤4MB）；
  • 音量跟随系统（插件内不设音量调节）；「试听」按钮；「解锁音频」应对浏览器自动播放策略 （任意页面交互后自动解锁）。
• 消息推送：
  • 企业微信群机器人（https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=...，填 Key 或完整 URL）；
  • 飞书自定义机器人（https://open.feishu.cn/open-apis/bot/v2/hook/...，支持加签 secret： timestamp + "\n" + secret 作 HMAC-SHA256 密钥、空串为消息，base64 后拼 &timestamp=&sign=）；
  • 渠道卡片只保存凭据，不设启用开关；是否启用某渠道推送只在各事件的「消息推送」中按渠道勾选， 消息模板可自定义，占位符：{event} {task} {workspace} {time} {summary}；
  • 「发送测试消息」按钮（用当前输入框内容，无需先保存）。
• 去抖/去重：同一会话的同类事件 10 秒内只通知一次（宿主侧冷却 + 浏览器 seen 集合双保险）。
• 最近事件列表：时间 / 类型 / 任务 / 工作区 / 各渠道推送结果——游标增量轮询实时更新，无手动刷新。

架构（关键决策）

• 宿主是唯一事件检测与推送点：ctx.on("session/event") 火线覆盖全部会话（含后台 Agent 会话）， webhook 由宿主进程 Node fetch 直发——不受浏览器 CORS 限制（企业微信/飞书 webhook 均不允许 浏览器跨域直发），且浏览器标签页关闭后推送仍然有效（声音除外）。
• 浏览器只负责声音与配置 UI：插件以 1.5s 轮询宿主事件日志（notify/poll）触发播放； 以 settings.section slot（id notify，order 25）在设置页呈现「通知」分区。
• 轮询是游标增量的：请求带 since: lastId，平时响应只有新事件（空数组），不会每 1.5s 全量搬运 50 条环形日志；宿主响应附 bootId，宿主重启导致事件 id 重新计数时自动重扫一次 （浏览器 seen 集合去重）。浏览器侧 RPC 只有单向 request/response，插件无服务端推送通道 （mux/host 两条 WebSocket 下行流为会话管理器私有），轮询为当前架构下的最优解。
• 配置即时保存：localStorage（dsh.notify.config.v1）为主存，防抖 400ms 镜像到宿主 data/notify-config.json；浏览器存储清空后自动从宿主恢复。
• RPC：浏览器 ctx.connection.rpc.call("/api", "notify/<method>", { args }) → 宿主 Typert 服务 notify：getConfig / saveConfig / poll / test（渠道测试）/ readAudio（本地音频转 data URL）。

发布（维护者）

npm pack --dry-run          # 核对 tarball 内容：lib/ + cordis.patch.yml（data/、node_modules 不入包）
npm login
npm publish                 # unscoped 包默认公开；首次发布即占名

• 未发布也可分发：推到 GitHub 公开仓库后，用户即可 dsh plugin --profile web add git+https://github.com/<用户名>/dsh-notify-hub.git （pnpm 按 git spec 克隆打包，对账同样按真实包名 dsh-notify-hub 进行）。
• 推送 GitHub 后建议在 package.json 补上 repository 字段（npm publish 无此字段仅警告不失败）。
• 发新版本：改 version → 重新 npm publish；已装用户执行 dsh plugin --profile web update dsh-notify-hub（更新不改 lib/host.js 时核心自动热重载）。

目录结构

├── package.json        # 插件包声明（exports + dsh.bundle.patch + dsh.client + peerDependencies）
├── cordis.patch.yml    # 本包的 profile 补丁层：insert 行挂载 Host 半（dsh plugin add 的激活依据）
├── lib/
│   ├── host.js         # Host 半入口 shim（冻结层）：fs.watch + ?v= 缓存穿透 + 子 fiber 热重载
│   ├── core.js         # Host 半核心（可热替换）：事件检测 + 企业微信/飞书推送（含加签）
│   │                   #         + 配置持久化 + 事件日志 + Typert 远程服务 notify/*
│   └── client.js       # Client 半：settings.section「通知」分区 UI + Web Audio 声音引擎
│                       #         + 1.5s 游标增量事件轮询 + localStorage 即时保存
├── test/
│   ├── host.mjs        # 宿主核心逻辑测试（webhook 冒充 + shim 挂载 + ESM 缓存穿透）
│   └── smoke.mjs       # client bundle 冒烟测试（factory/apply/渲染/轮询去重）
├── data/               # notify-config.json（运行时生成；不入 npm 包，.gitignore 已忽略）
└── node_modules/@deepseek-ai -> ~/.dsh/profiles/node_modules/@deepseek-ai   # 仅本地开发/测试用

验证

node --check lib/host.js && node --check lib/core.js && node --check lib/client.js   # 语法
node test/host.mjs                                        # 宿主管线（推送格式/加签/去抖/门控/shim）
node test/smoke.mjs                                       # client bundle（注册/渲染/轮询）

使用

1. 首次安装后重启 dsh web，打开 http://127.0.0.1:3080 → 设置 → 「通知」；
2. 点击「解锁音频」（或任意页面交互一次）；取消勾选总开关「启用通知」会隐藏下方全部配置 （事件不检测、不推送、不响铃），重新勾选即恢复；
3. 启用需要的event（如「任务完成」）——卡片默认折叠，点击卡片头部展开后选择音效、可「试听」；
4. 在「推送渠道」卡片（同样默认折叠）配置凭据（企业微信 Key / 飞书 Hook + Secret）， 「发送测试消息」验证连通；
5. 在每个事件下勾选要推送的渠道，可改模板（留空用默认）；
6. 触发任意已启用事件后，「最近事件」实时显示各渠道推送结果。