🔔 DSH 主动通知插件（proactive-notify）

一个运行在 DeepSeek Harness（DSH）Web GUI 上的永久组合插件：

当 Agent 遇到权限问题（工具等待审批 / 被沙箱或审批拒绝）或完成任务（每轮处理结束）时，通过浏览器系统通知（Notification API）主动提醒你——即使你在其他网页、其他软件中，也能看到通知弹窗，并自带系统通知音效。

✨ 功能

场景	通知内容
工具需要用户审批	⚠️ 需要审批：工具「××」正在等待你的授权
工具被沙箱/审批/权限规则拒绝	⚠️ 权限问题：工具「××」执行被拒绝 — 原因
任务完成（Agent 转为 idle）	✅ 任务完成：本轮处理已结束

• 跨应用可见：通过浏览器 Notification API 弹出系统级通知（Windows 上显示在通知中心，覆盖任何软件）
• 自带系统音效：使用 Windows 系统通知声音，无需额外配置
• 平时零打扰：通知正常工作后，页面内不显示任何 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），方便用户核对自己装的版本。

🎯 使用

1. 首次打开网页：若尚未授权通知权限，页面右下角会出现「🔔 开启通知」卡片
2. 点击 开启通知，浏览器会弹出权限请求，点击 允许（浏览器安全策略要求授权必须由一次点击触发，所以无法在打开页面时自动弹出）
3. 之后遇到权限问题或任务完成时，会自动弹出系统通知；若通知到来时权限仍未开启，「开启通知」卡片会再次出现提醒你

⚠️ 注意事项

• 若误点了「拒绝」，请到地址栏左侧站点设置 → 通知 → 允许，刷新页面后插件会重新检测；权限被拒后浏览器不会再弹授权窗，只能从站点设置手动开启
• 系统通知未授权时不会弹系统通知，但页面右下角会保留「开启通知」引导卡片提醒你
• DSH 标签页必须保持打开（后台可用，关闭则收不到通知）

🔧 工作原理

Host 半区（Node 进程内，index.js）：

• 监听 tools/result：工具执行失败且错误包含 sandbox / permission / denied 等关键词 → 推送「权限问题」通知
• 监听 approval/request：工具正在等待用户审批 → 推送「需要审批」通知
• 监听 agent/status：Agent 状态变为 idle（本轮处理结束）→ 推送「任务完成」通知
• 通过 webServer 服务注册 HTTP 路由 GET /api/notify/queue，供 Client 轮询取走通知队列

Client 半区（浏览器页面内，client.js）：

• 打开网页时检测通知权限：未授权（default）→ 显示「开启通知」卡片；已拒绝（denied）→ 显示去站点设置手动开启的指引卡片
• 点击卡片按钮时（用户手势上下文内）调用 Notification.requestPermission()，浏览器才会弹出授权窗口；授权成功后弹一条系统通知确认
• 每秒轮询一次 GET /api/notify/queue 拉取通知队列
• 权限已授予时调用浏览器 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