dsh-notify-hub

Readme

# dsh-notify-hub 通知插件

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

## 安装 / 更新 / 重启

```sh
# 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 web` |
|---|---|
| **首次安装 / 卸载** | ✅ 必须——插件进入 profile `dsh.profile.bundles` 列表只在 boot 时读取，插件自身尚未运行，无法参与自己的激活 |
| **更新宿主核心**（`lib/core.js`） | ❌ 不用——入口 shim 会热重载（见下） |
| **更新浏览器半**（`lib/client.js`） | ❌ 不用，连页面都不用刷新（DSH 的 client-hmr 轮询 bundle 文件，SSE 通知浏览器热替换） |
| 更新入口 shim 自身（`lib/host.js`）/ package.json / 依赖 / `cordis.patch.yml` | ✅ 必须 |

卸载用 `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）。

## 发布（维护者）

```sh
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   # 仅本地开发/测试用
```

## 验证

```sh
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. 触发任意已启用事件后，「最近事件」实时显示各渠道推送结果。