🔔 DSH 主动通知插件（proactive-notify）
一个运行在 DeepSeek Harness（DSH）Web GUI 上的永久组合插件：
当 Agent 遇到权限问题（工具等待审批 / 被沙箱或审批拒绝）或完成任务（每轮处理结束）时，通过浏览器系统通知（Notification API）主动提醒你——即使你在其他网页、其他软件中，也能看到通知弹窗，并自带系统通知音效。
✨ 功能
| 场景 | 通知标题 | 通知正文 |
|---|
| 工具需要用户审批 | ⚠️ 需要审批 | 需要审批：工具「××」正在等待你的授权（含原因） |
| 工具被沙箱/审批/权限规则拒绝 | ⚠️ 权限问题 | 权限问题：工具「××」执行被拒绝 — 原因 |
| 任务完成（Agent 转为 idle） | ✅ 任务完成 | 任务完成：本轮处理已结束 |
- 跨应用可见：通过浏览器 Notification API 弹出系统级通知（Windows 上显示在通知中心，覆盖任何软件）
- 自带系统音效：使用 Windows 系统通知声音，无需额外配置
- 审批通知不错位：「需要审批」通知会等页面上的审批弹窗出现后才弹出——你看到通知切回页面时，审批面板一定已经在那儿了；若页面 WebSocket 一直未连上，3 秒后兜底强制弹出，提醒绝不丢失
- 平时零打扰：通知正常工作后，页面内不显示任何 UI，纯系统级提醒（仅权限未就绪时出现右下角引导卡片）
- 开页即引导：打开网页时若通知权限未授权，页面右下角会出现「开启通知」卡片，点击即弹出浏览器授权窗口（浏览器要求权限请求必须由一次真实点击触发，无法在打开页面时静默弹出）
- 永久加载：一次安装，随 DSH 启动自动生效，无需重复安装
📋 前置条件
- DSH Web GUI（组合插件，随 DSH 进程永久加载）
- pnpm（
dsh plugin 命令通过它安装插件，装一次即可）
- 浏览器：Chrome / Edge（推荐）或 Firefox
- ⚠️ DSH 标签页必须保持打开（后台运行即可），关闭标签页后收不到通知
🚀 安装
一条命令，直接从本 GitHub 仓库安装：
dsh plugin --profile web add "github:DemoJ/proactive-notify#main"
然后重启 DSH（重新运行 dsh web）即可生效。无需手动复制文件、编辑任何配置。
原理：本包在 package.json 中声明了 "dsh": { "bundle": { "patch": "./cordis.patch.yml" } }。
dsh plugin add 会用 pnpm 把 GitHub 仓库克隆、打包进 profile 的 node_modules，检测到 bundle 声明后自动把它追加到
profile 的 dsh.profile.bundles 组合层列表；下次启动时组合器自动应用包内的 cordis.patch.yml。
本插件是纯 JS、无构建步骤的包，安装时不执行任何构建脚本，不会触发 pnpm 的「允许构建」确认
（TS 等需要 prepare 构建的插件才会遇到那一步）。
更新
GitHub 方式没有 npm 版本号，「最新版」就是 #main 指向的最新提交。更新到最新：
dsh plugin --profile web update proactive-notify
pnpm 会重新从 main 分支拉取并替换已安装的包，之后重启 dsh web 生效。
若 update 后内容没有变化（可能命中 pnpm 的 git 解析缓存），卸载重装一次即可强制刷新：
dsh plugin --profile web remove proactive-notify
dsh plugin --profile web add "github:DemoJ/proactive-notify#main"
卸载
dsh plugin --profile web remove proactive-notify
卸载后重启 dsh web；bundle 随依赖一起移除，profile 组合层列表会自动同步。
锁定版本（可选）
#main 表示始终跟随 main 分支最新提交。也可以按标签或提交 hash 固定在某个状态：
dsh plugin --profile web add "github:DemoJ/proactive-notify#v1.0.0" # 按标签（需先 git tag 并推送）
dsh plugin --profile web add "github:DemoJ/proactive-notify#11bf8dc" # 按提交 hash
从本地源码安装（开发调试）
改代码后想立刻在本机验证，不用先推 GitHub。在本仓库的上级目录执行（相对路径会锚定到你执行命令时所在的目录）：
dsh plugin --profile web add ./proactive-notify
📦 发版方式（维护者）
不需要发布 npm——提交并推送到 GitHub 就等于发版：
git add -A
git commit -m "feat: ..."
git push origin main
已安装的用户随后执行 dsh plugin --profile web update proactive-notify 即可拿到新版。
建议每次顺手递增 package.json 的 version 字段（或直接用 npm version patch，它会自动改号并打 tag），方便用户核对自己装的版本。
🎯 使用
- 首次打开网页：若尚未授权通知权限，页面右下角会出现「🔔 开启通知」卡片
- 点击 开启通知，浏览器会弹出权限请求，点击 允许（浏览器安全策略要求授权必须由一次点击触发，所以无法在打开页面时自动弹出）
- 之后遇到权限问题或任务完成时，会自动弹出系统通知；若通知到来时权限仍未开启，「开启通知」卡片会再次出现提醒你
⚠️ 注意事项
- 若误点了「拒绝」，请到地址栏左侧站点设置 → 通知 → 允许，刷新页面后插件会重新检测；权限被拒后浏览器不会再弹授权窗，只能从站点设置手动开启
- 系统通知未授权时不会弹系统通知，但页面右下角会保留「开启通知」引导卡片提醒你
- DSH 标签页必须保持打开（后台可用，关闭则收不到通知）
🔧 工作原理
Host 半区（Node 进程内，index.js）：
- 监听
tools/result：工具执行失败且错误包含 sandbox / permission / denied 等关键词 → 推送 approval-denied 通知（立即弹出）
- 监听
approval/request：工具正在等待用户审批 → 推送 approval-waiting 通知，并在 3 秒后追加一条 approval-waiting-force 兜底通知
- 监听
agent/status：Agent 状态变为 idle（本轮处理结束）→ 推送 task-complete 通知（立即弹出）
- 通过
webServer 服务注册 HTTP 路由 GET /api/notify/queue，供 Client 轮询取走通知队列
Client 半区（浏览器页面内，client.js）：
- 打开网页时检测通知权限：未授权（
default）→ 显示「开启通知」卡片；已拒绝（denied）→ 显示去站点设置手动开启的指引卡片
- 点击卡片按钮时（用户手势上下文内）调用
Notification.requestPermission()，浏览器才会弹出授权窗口；授权成功后弹一条系统通知确认
- 每秒轮询一次
GET /api/notify/queue 拉取通知队列
- 按通知类型区分系统通知标题：
approval-waiting / approval-waiting-force →「⚠️ 需要审批」，approval-denied →「⚠️ 权限问题」，task-complete →「✅ 任务完成」
- 审批通知就位机制：
approval-waiting 先缓存在本地，每轮轮询检查页面 DOM 中是否已出现审批面板（[data-approval-key]，由 WebSocket 实时推送渲染），就位后才弹系统通知——保证你看到通知切回页面时审批弹窗已经在那里；若 WebSocket 一直未连上（页面未打开/断连），Host 3 秒后追加的 approval-waiting-force 会强制弹出通知并清掉本地缓存，提醒绝不丢失
- 权限已授予时调用浏览器
Notification API 弹出系统通知（跨应用可见，自带系统音效）；权限未授予时把引导卡片重新拉起来
为什么权限引导放在页面内、且必须由点击触发？
浏览器安全策略要求 Notification.requestPermission() 必须由用户手势（user activation）发起，否则会被静默忽略、不显示授权窗。因此无法在打开页面或收到通知时自动弹出授权，只能通过页面内按钮引导点击。Host 侧也无法代劳：Web 端的 userQuestions 提问要求 agent-owned session（插件加载时不存在 agent），而且任何经 Host 中转的流程到达 Client 时手势早已失效。
为什么用 HTTP 轮询而不是动态插件的 harness.handle/host.call？
组合插件没有动态插件的 Package-private RPC 通道，因此改用 webServer 注册 HTTP 路由 + Client fetch() 轮询的方式通信。
📁 文件说明
| 文件 | 说明 |
|---|
package.json | 包声明（dsh.bundle 声明 bundle patch 层，dsh.client 标记 Client 半区，exports 声明入口） |
cordis.patch.yml | bundle patch 层：安装时自动把插件行插入 profile 组合树 |
index.js | Host 半区：事件监听、通知队列、HTTP 路由 |
client.js | Client 半区：权限引导卡片、系统通知、队列轮询 |
README.md | 本文档 |
LICENSE | MIT 开源许可 |
📄 License
MIT
