审批提醒助手 renpengfei1027/dsh-web-notify

dsh-harness-notifier

License: MIT

英文版 · 默认中文

DeepSeek Harness 更新迭代很快，rc 版会破坏插件协议——本插件按当前部署的机制实现，挂载/升级后以「设置 → 插件」里能看到通知卡片、真实触发一次提醒为准。

DSH Web GUI 的注意力插件：待审批 / 待回答提问 / 回合结束 / 会话异常 / 连接恢复时，在浏览器内多通道提醒——提示音、标签页标题徽标 + PWA 徽标、OS 通知、通知中心 dock、toast。

纯手写 JS，零构建链：宿主半区为 ESM，客户端半区为
window.__ModuleLoader__.load({ id, factory }) 协议的 classic script，
require("react") 走客户端模块表 baseline。

原理

| 部分 | 职责 |
| lib/index.js（宿主，Node 侧） | 注册 notifications 设置节（插件页配置表单按该命名空间读写）；注册 systemPrompt presence 节告知模型 |
| lib/client.js（浏览器侧） | 订阅官方转发事件驱动提醒：approval/request、user-questions/request（waterfall 观察者，return next() 绝不代答）、api-session/status（回合结束 + 待处理清除）、api-session/error、api-session/activity（用户介入即清除）、settings/document-updated（配置热刷新）、connection/reset（恢复提醒）；UI 落点：shell.overlay（dock + toast）、plugins.bundle.config（插件页配置表单，key = 包名，双视图） |

行为细节

- waterfall 车道必须 prepend 抢位：cordis waterfall 的首个返回值即终止整条链。
官方审批/问答 UI 的应答器返回 await pending.result，普通 $on 注册的观察者排在它之后永远收不到事件（这就是“审批/提问没提醒”的典型根因）。$on 底下只是往 ctx 钩子表写 remote.events.eventPrefix + 事件名（前缀随启动随机，运行时可读），
插件直接以 { prepend: true } 向同一张表注册观察者：观察 → next() 放行 →
官方应答器应答 → 应答值原样回流，链返回时精确清除待处理项。内部面不可用时退化为 $on 并在诊断记一条（此时这两个车道可能不响）。
- 免打扰时段只静音（提示音 / OS 通知 / toast 不发），徽标与 dock 静默更新。
- 冷却：同类提醒（类别 + 会话）按 cooldownMs 去重。
- 待处理清除：会话重新开跑（api-session/status running=true）、用户发消息（activity）、dock/toast 点击「前往」、手动「忽略」。
- 回合结束不误报：若该会话还有待审批/提问在等用户，idle 边沿不报「回合结束」。
- 页面无人值守自动升级：最小化 / 被完全遮挡（visibilityState=hidden）或失焦
（点了别的窗口，document.hasFocus()=false）时，页内 toast 注意不到——此时即使
「OS 通知」开关关闭，任何提醒（审批 / 提问 / 回合结束 / 会话异常）都会自动升级为系统通知（escalateOnHidden，默认开；免打扰时段仍静音）。失焦但可见的窗口里页内 toast 与声音照常。
- 系统通知权限：首次页面手势（pointerdown）时若为 default 态自动索权一次；也可在设置表单手动申请。被浏览器拒绝后只能去站点权限设置里放开。
- 链路自证：设置表单「发送测试系统通知」一键验证 授权 → Windows 横幅 全链路； window.__NOTIFIER_DIAG__.os（attempt/sent/skipPermission/skipDisabled/lastSkip）与 lastVisibility 记录每次系统通知的派发结果和页面可见性变化。
- 提示音走 WebAudio，浏览器要求先有一次页面手势；插件在首次 pointerdown 时预热。
- 诊断：开启后 window.__NOTIFIER_DIAG__ 暴露配置、待处理、计数与最近错误。
- 模拟入口：控制台 __NOTIFIER_SIM__.help——本地驱动审批/提问/完成/异常提醒，不触碰真实会话，验证 UI 全链路用。

安装 / 更新（开发模式）

纯手写 JS，无构建链：宿主为 ESM（"type": "module"），客户端为
window.__ModuleLoader__.load({ id, factory }) 协议的 classic script，
require("react") 走客户端模块表 baseline。无需 npm install / npm run build。

1. 克隆仓库
git clone https://github.com/renpengfei1027/dsh-web-notify.git
cd dsh-web-notify

2. 把插件目录挂进 web profile（link: 指向插件子目录，不是仓库根）
dsh plugin --profile web add link:"$PWD/harness-notifier"
Windows PowerShell: dsh plugin --profile web add link:"$PWD/harness-notifier"

3. 重启 dsh web
dsh web

设置卡片写入链路

所有保存都经 cardWrite：乐观回显（受控输入立即生效，不等服务端往返） → 150ms 合并（拖动音量/键入冷却只发最后一次）→
ctx.remote.settings.update(ns, patch, void 0)（网关按 descriptor 严格校验
参数数，第三参是 expectedRevision: number | undefined，传 undefined 表示无条件写）。服务器值经 describe 落地后清空乐观层。

配置 UI 挂载点（协议现况）

配置表单注册进插件页的 plugins.bundle.config keyed 槽位（key = 包名）：

- 插件列表的 Installed 卡片下方渲染 view: 'summary' 一行简介（实时显示已开启的通道）；
- 点进包详情页渲染 view: 'page' 完整表单（带保存语义的逐字段热写）。

旧的 settings.plugin.item 槽位已从 DSH 客户端移除；plugins.item 保留给官方宿主面配置页，第三方 bundle 不要注册。DSH 升级后若插件页协议再变，对照 ui-plugin-manager 的 slot-contract.ts 移植。

本地自检

假 DOM + 假 ctx，验证协议注册、事件订阅面、卡片写入三参调用：

cd harness-notifier && npm run check

安装后校验

| 校验项 | 位置 | 预期 |
| profile dependencies | ~/.dsh/profiles/web/package.json | dependencies 含 dsh-harness-notifier（link:） |
| bundle 列表 | 同上 dsh.profile.bundles | 含 dsh-harness-notifier |
| 配置表单 | 设置 → 插件 → dsh-harness-notifier | 详情页出现完整表单，卡片下有一行通道简介 |
| 全链路 | 表单「发送测试系统通知」 | Windows 通知横幅弹出 |

生效

插件集合变更 / 插件代码变更都必须重启 dsh web——boot graph 的 bundle rev 按启动时内容哈希计算，刷新页面拿不到新 bundle。

验证

1. 设置 → 插件 → dsh-harness-notifier：详情页出现完整配置表单
2. 控制台 __NOTIFIER_SIM__.pending("approval")（或真实触发一次审批）：提示音 + 标签页标题 (N) + 右下角铃铛 + toast
3. 铃铛展开通知中心，「前往」跳转对应会话
4. OS 通知：表单里申请权限后，浏览器窗口最小化也能收到系统通知

卸载

dsh plugin --profile web remove dsh-harness-notifier

配置参数

改完即生效（乐观回显 + 150ms 合并写，无需重启）。

| 字段 | 类型 | 默认 | 说明 |
| sound | boolean | true | 待审批/提问提示音 |
| volume | number 0–1 | 0.15 | 提示音音量 |
| badge | boolean | true | 标签页标题徽标 + PWA 徽标 |
| toast | boolean | true | 页内 toast 提醒 |
| notify | boolean | true | 浏览器 OS 通知（需授权） |
| escalateOnHidden | boolean | true | 页面无人值守时自动升级为系统通知 |
| dock | boolean | true | 右下角通知中心 |
| completion | boolean | true | ① 回合结束提醒 |
| completionSound | boolean | true | 回合结束提示音 |
| completionNotify | boolean | true | 回合结束 OS 通知 |
| connection | boolean | true | ② 连接恢复提醒 |
| agentError | boolean | true | ③ 会话异常提醒 |
| cooldownMs | number ≥0 | 5000 | 同类提醒冷却（毫秒） |
| alertKinds | string[] | ["approval","plan-review","question"] | 触发待处理提醒的 kind 白名单 |
| quiet | object | {enabled:false, start:"23:00", end:"08:00"} | 免打扰时段（仅静音，视觉通道照常） |
| diagnostics | boolean | false | 在 window.__NOTIFIER_DIAG__ 暴露诊断 |

几个常用调法：

- 只要审批：completion=false、connection=false、agentError=false
- 只想听响：toast=false、notify=false，保留 sound + badge + dock
- 夜间免打扰：quiet.enabled=true、start=22:00、end=09:00
- 嫌系统通知吵、但要离开窗口时不错过：保持 notify=false，escalateOnHidden=true

限制

- 提醒粒度是会话级；被委派的子代理在委派边界即固定「审批永不、提问拒答」策略，不会产生待审批/提问条目，只有父会话的审批会进通知中心
- 提示音需要页面有过用户手势（浏览器音频策略）；无手势时静默降级为视觉通道
- 检测在浏览器侧：页面关闭时页内提醒天然失效——这正是 M2/M3 出页通道的动机

路线图

| 阶段 | 内容 |
| M1（本版） | 零补丁页内六通道 + 插件页配置表单 |
| M2 | 宿主权威决策层（pending 状态机 / 去重 / 免打扰下沉宿主）+ Windows toast 出页通道 |
| M3 | Webhook 手机推送（Bark / ntfy / Server酱 / 自定义模板，secrets 走 role('secret')） |
| M4 | notify 模型工具：agent 在长任务关键节点主动呼叫人 |

项目结构

dsh-web-notify/
├── README.md # 本文件 ├── LICENSE └── harness-notifier/ # 插件本体（零构建，手写 JS） ├── package.json # dsh.bundle.patch + dsh.client（platform: web, immediately） ├── cordis.patch.yml # 插件行：id notifications / name dsh-harness-notifier ├── lib/index.js # 宿主半区（settings 节 + presence） ├── lib/client.js # 浏览器半区（检测 + 六通道 + 插件页配置表单） └── scripts/smoke.mjs # 假 DOM 冒烟（node --check + npm run check）

License

MIT

dsh-harness-notifier (English)

中文版 · Chinese by default

DeepSeek Harness 迭代很快，rc 版本会破坏插件协议——本插件是针对当前已部署的机制实现的。挂载/升级后，请以“通知卡片出现在 设置 → 插件 下，并且真实告警会触发”为准。

DSH Web GUI 的提醒插件：在待审批 / 待回答问题 / 回合完成 / 会话错误 / 连接恢复时，它会在浏览器内响铃——提示音、标签页标题徽标 + PWA 徽标、系统通知、通知停靠栏、toast。

手写 JS，零构建链：宿主半区是 ESM，客户端半区是经典脚本，使用 window.__ModuleLoader__.load({ id, factory }) 协议，
require("react") 通过客户端模块表基线解析。

工作原理

| 部分 | 职责 |
| lib/index.js（宿主，Node） | 注册 notifications 设置节点（由插件页配置表单读/写）；注册一个 systemPrompt presence 节点，告知模型该通知器存在 |
| lib/client.js（浏览器） | 订阅官方转发事件：approval/request、user-questions/request（waterfall 观察者，return next()，绝不代替用户作答）、api-session/status（回合完成 + 待处理清除）、api-session/error、api-session/activity（用户活动时清除）、settings/document-updated（热配置刷新）、connection/reset（恢复告警）；UI 挂载：shell.overlay（停靠栏 + toast）、plugins.bundle.config（插件页配置表单，以包名为键，双视图） |

行为细节

- waterfall 通道必须前置：cordis waterfall 的第一个返回值会终止链条。官方审批/问题响应器返回 await pending.result，因此在其之后注册的普通 $on 观察者永远看不到事件（这是“没有审批/问题告警”的经典根因）。本插件
使用 { prepend: true } 注册到同一个 hook 表：观察 → next()
透传 → 官方响应器作答 → 答案原样流回，并且待处理项会在链条返回时被准确清除。当内部接口不可用时，回退到普通 $on（记录一条诊断信息）——此时这两个通道可能会保持静默。
- 免打扰时段只会静音（提示音 / 系统通知 / toast）；徽标和停靠栏会静默更新。
- 冷却：同类型提醒（类别 + 会话）按 cooldownMs 去重。
- 待清除：会话恢复（api-session/status running=true）、用户发送消息（活动）、dock/toast “go”，或手动“ignore”。
- 无误判回合完成：如果该会话仍有待处理的审批/问题，空闲边缘保持静默。
- 无人值守页面升级：最小化 / 完全被遮挡（visibilityState=hidden）或未聚焦（document.hasFocus()=false）的页面无法显示页内 toast——在该状态下，即使 OS-notify 开关关闭，每个警报都会升级为系统通知（escalateOnHidden，默认开启；静默时段仍会静音）。在聚焦但可见的窗口中，页内 toast 和提示音正常运作。
- OS-notify 权限：在默认状态下，首次页面手势（pointerdown）时自动请求一次；也可从设置表单中请求。如果浏览器已拒绝，只有站点权限页面才能重新启用。
- 链路自检：在设置表单中点击一次“send test notification”即可端到端验证权限 → Windows 横幅；window.__NOTIFIER_DIAG__.os（attempt/sent/skipPermission/skipDisabled/lastSkip）和 lastVisibility 记录每次分发结果和可见性变化。
- 提示音依赖 WebAudio，需要先有用户手势；插件在首次 pointerdown 时预热。
- 诊断：启用后，window.__NOTIFIER_DIAG__ 会暴露配置、待处理项、计数器和近期错误。
- 模拟控制台：__NOTIFIER_SIM__.help 在本地驱动审批/问题/完成/错误警报，而不触碰真实会话。

安装 / 更新（开发模式）

手写 JS，无构建链：宿主端为 ESM（"type": "module"），客户端为经典脚本，使用 window.__ModuleLoader__.load({ id, factory }) 协议，require("react") 通过客户端模块表基线解析。无需 npm install / npm run build。

1. clone
git clone https://github.com/renpengfei1027/dsh-web-notify.git
cd dsh-web-notify

2. link the plugin subdirectory (not the repo root) into the web profile
dsh plugin --profile web add link:"$PWD/harness-notifier"

3. restart dsh web
dsh web

设置写入路径

每次保存都经过 cardWrite：乐观回显（受控输入立即生效，无需等待服务器往返）→ 150ms 合并（拖动音量或输入冷却时间只发送最后一个值）→
ctx.remote.settings.update(ns, patch, void 0)（网关严格校验参数数量；第三个参数是 expectedRevision: number | undefined，undefined 表示无条件写入）。服务器值通过 describe 落地后清除乐观层。

配置 UI 挂载点（当前协议）

表单注册到插件页面的 plugins.bundle.config 键控槽位（key = 包名）：

- view: 'summary' 在 Installed 卡片下渲染一行摘要（启用通道的实时列表）；
- view: 'page' 在包自身的详情页上渲染完整表单。
旧的 settings.plugin.item 槽位已从 DSH 客户端中移除； plugins.item 保留给官方宿主平面配置页面——第三方 bundle 不应在此注册。如果 DSH 升级再次更改插件页面协议，请针对 ui-plugin-manager 的 slot-contract.ts 进行移植。

本地冒烟测试

伪造 DOM + 伪造 ctx；验证协议注册、事件订阅接口，以及三参数卡片写入：

cd harness-notifier && npm run check

安装后检查清单

| 检查项 | 位置 | 预期结果 |
| profile 依赖 | ~/.dsh/profiles/web/package.json | dependencies 包含 dsh-harness-notifier（link:） |
| bundle 列表 | 同一文件，dsh.profile.bundles | 包含 dsh-harness-notifier |
| 配置表单 | 设置 → 插件 → dsh-harness-notifier | 详情页显示完整表单，卡片下方显示一行摘要 |
| 端到端 | 表单中的“发送测试通知” | 弹出 Windows 通知横幅 |

生效

任何插件名单或插件代码变更都需要重启 dsh web——启动图中的 bundle rev 是启动时计算的内容哈希；刷新页面永远不会加载新的 bundle。

验证

1. 设置 → 插件 → dsh-harness-notifier：出现完整配置表单
2. __NOTIFIER_SIM__.pending("approval")（或真实审批）：提示音 + 标签页标题 (N)
+ 角落铃铛 + toast
3. 展开 dock，“go”跳转到会话
4. 操作系统通知：在表单中授予权限，然后最小化浏览器——系统通知仍会到达

卸载

dsh plugin --profile web remove dsh-harness-notifier

配置

更改会热应用（乐观回显 + 150 ms 合并写入，无需重启）。

| 字段 | 类型 | 默认值 | 描述 |
| sound | boolean | true | 审批/提问提示音 |
| volume | number 0–1 | 0.15 | 提示音音量 |
| badge | boolean | true | 标签页标题徽标 + PWA 徽标 |
| toast | boolean | true | 页内 toast 提醒 |
| notify | boolean | true | 浏览器操作系统通知（需要权限） |
| escalateOnHidden | boolean | true | 页面无人值守时升级为系统通知 |
| dock | boolean | true | 角落通知 dock |
| completion | boolean | true | ① 回合完成提醒 |
| completionSound | boolean | true | 回合完成提示音 |
| completionNotify | boolean | true | 回合完成操作系统通知 |
| connection | boolean | true | ② 连接恢复提醒 |
| agentError | boolean | true | ③ 会话错误提醒 |
| cooldownMs | number ≥0 | 5000 | 同类型去重窗口（毫秒） |
| alertKinds | string[] | ["approval","plan-review","question"] | 待处理提醒的类型白名单 |
| quiet | object | {enabled:false, start:"23:00", end:"08:00"} | 免打扰时段（仅静音；视觉提醒保留） |
| diagnostics | boolean | false | 暴露 window.__NOTIFIER_DIAG__ |

常用配方：
- 仅审批：completion=false、connection=false、agentError=false
- 仅提示音：toast=false、notify=false，保留 sound + badge + dock
- 深夜静音：quiet.enabled=true、start=22:00、end=09:00
- 系统 toast 太吵，但不想在离开时错过任何内容：保留
notify=false、escalateOnHidden=true

限制

- 粒度是会话级的；被委派的子代理的审批策略被固定为 “never”，且问题在委派边界处被拒绝，因此只有父会话的审批才可能到达 dock
- 提示音需要先有用户手势（浏览器自动播放策略）；没有手势时，它会静默降级为视觉界面
- 检测运行在浏览器中：页面关闭后，页内提醒自然会失效——这正是 M2/M3 页外通道的动机

路线图

| 阶段 | 范围 |
| M1（本版本） | 零补丁页内六通道 + 插件页配置表单 |
| M2 | 宿主权威决策层（待处理状态机 / 去重 / 静音时段汇聚）+ 页外 Windows toast |
| M3 | Webhook 手机推送（Bark / ntfy / ServerChan / 自定义模板，密钥通过 role('secret')） |
| M4 | 一个 notify 模型工具：代理在长任务的关键节点呼叫人类 |

项目结构

dsh-web-notify/
├── README.md # 本文件 ├── LICENSE └── harness-notifier/ # 插件（零构建，手写 JS） ├── package.json # dsh.bundle.patch + dsh.client（platform: web, immediately） ├── cordis.patch.yml # 插件行：id notifications / name dsh-harness-notifier ├── lib/index.js # 宿主半部分（settings node + presence） ├── lib/client.js # 浏览器半部分（检测 + 六通道 + 插件页表单） └── scripts/smoke.mjs # 假 DOM 冒烟测试（node --check + npm run check）

许可证

MIT