任务通知 TaoYe599/dsh-notify

dsh-notify

用系统通知告诉你「任务结束了」或「有问题等你回答」——浏览器开着时弹网页通知，浏览器关掉时由 DSH Host 直接弹 Windows 原生通知。

它解决什么

DSH 只在两种状态下需要你：

| 状态 | 表现 | 通知 |
| 它在等你 | ask_user_question 提问、审批请求、计划确认 | 「需要你的回复 / 确认」 |
| 它不用你了 | 会话从 running 变为空闲（这一轮跑完了） | 「任务已完成」 |

覆盖范围按「任务结束时谁还活着」划分：

| 你的状态 | 谁来通知 | 说明 |
| 看着 DSH 页面 | 不通知 | 状态变化你已经看见了 |
| 切到别的标签页 / 别的应用 / 最小化浏览器 | 客户端（网页通知） | 点击通知可回到标签页；标签页标题出现 (N) 未读徽标 |
| 关掉浏览器 | Host（Windows 原生通知） | 页面没了，但 DSH 进程还在跑，由它接管 |

设计原则

- 按存活进程分层：通知必须由「任务结束时仍然活着的那个进程」发出。浏览器关掉后网页通知在物理上不可能，所以 Host 半用 Windows PowerShell 5.1 的 WinRT ToastNotification 直接弹原生 toast（PowerShell 7 已移除该类型投影，因此特意用 5.1）。
- 两个通道不重复：靠一个存在性握手。每个页面持有插件期间每 20 秒 ping 一次 /dsh-notify/presence，页面关闭时用 sendBeacon 发告别；Host 只要发现还有活着的页面就保持沉默，完全让客户端负责（只有页面知道你是否正在看）。
- 对界面无感：没有常驻设置项。首次使用时浮出一张小卡问一次「是否允许通知」；若浏览器没给权限或当时漏掉了通知，卡片会带着原因回来（三态），而不是静默失效。
- 不丢事件：客户端检测直接读权威状态（会话 running 标志与待处理交互表），由 DSH 自己的连接推送驱动，不用轮询——后台标签页的定时器会被节流。
- 不误报子任务：Host 侧只对 agents.roots() 里的顶层会话通知；子 agent 必然带 owning agent context，因此天然被排除。

安装

本包是一个标准 DSH bundle（声明 dsh.bundle.patch，随包提供一层配置补丁）。安装请用官方 CLI —— dsh plugin 会把参数转发给 profile 目录下的 pnpm，并在包声明了 dsh.bundle 时自动把它追加进 dsh.profile.bundles。

1) 从本地目录安装（开发时最常用）
dsh plugin --profile web add <本包所在目录>

2) 从 tarball 安装（分发给同事时最省事）
pnpm pack # 生成 dsh-notify-0.1.0.tgz
dsh plugin --profile web add ./dsh-notify-0.1.0.tgz

3) 从 npm 或 GitHub 安装（需先发布/建仓）
dsh plugin --profile web add dsh-notify
dsh plugin --profile web add github:<你>/dsh-notify

验证（不用启动即可确认层已生效）：

dsh --profile web --dump-config # 输出中应出现 「# == dsh-notify」 层

安装或更新后必须重启 dsh web：bundle 列表与 Host 半都在 profile 启动时加载（客户端 bundle 改动只需刷新页面）。

卸载

dsh plugin --profile web remove dsh-notify

随后重启 dsh web。若只是临时停用，也可在该 profile 的 cordis.patch.yml 里对本插件的行加 disabled: true。

分发给同事测试

三种方式，按推荐顺序：

| 方式 | 你要做的 | 同事要执行的 |
| tarball（推荐） | pnpm pack → 把 .tgz 发过去 | dsh plugin --profile web add ./dsh-notify-0.1.0.tgz |
| npm 发布 | npm publish（需账号；建议改成分域包名避免重名） | dsh plugin --profile web add dsh-notify |
| GitHub 仓库 | 建仓并给仓库打 dsh-plugin 主题标签（官方推荐的社区发现方式） | dsh plugin --profile web add github:<你>/dsh-notify |

本包有两个对分发有利的性质：零运行时依赖（Host 半只用 Node 内置模块）与客户端 bundle 已预构建（手写产物，无需打包链）。因此三条路都不需要构建期脚本，也就不会触发 pnpm ≥10 对依赖脚本的 allowBuilds 权限询问。

为什么不是 PR：官方仓库的 has_pull_requests 为 false（PR 功能在仓库层面关闭，Issues 亦关闭，仅 Discussions 开放）。官方 CONTRIBUTING 明确「deeply customizable，社区包不比官方包低一等」，并推荐以 dsh-plugin 主题发布社区插件。

排查

Host 半会往 ~/.dsh/dsh-notify.log.jsonl（或 $DSH_HOME 下）追加一行一行的诊断记录，每条都带 event：

| event | 含义 |
| presence-route | 存在性路由注册成功（握手可用） |
| toast | 原生通知已发出（附 sessionId / title / presenceReady） |
| skip + reason: page-alive | 有页面在线，交给客户端了 |
| skip + reason: subagent | 是子 agent 会话，不打扰 |
| skip + reason: repeat-window | 同一会话 10 秒内重复空闲 |
| toast-failed | PowerShell 调用失败（附错误信息） |
| no-web-server | 拿不到 webServer 服务，存在性判断失效 |

客户端侧的日志在浏览器控制台，前缀 [dsh-notify]。

想改行为

- 想彻底关掉网页通知：在浏览器站点设置里把本站「通知」改为「阻止」，客户端立刻静默（它每次都读 Notification.permission）；Host 侧仍会在浏览器关闭时通知。
- 想重新被询问：清除本站点数据（localStorage 的 dsh-notify.asked 会一起清掉），刷新后会再问一次。

已知边界

- 原生通知目前仅 Windows：非 Windows 平台检测照常运行，只跳过显示步骤。
- 存在性 TTL 为 150 秒：正常关闭浏览器会立刻发告别信标、Host 立即接管；若浏览器崩溃（来不及发信标），最多要等 150 秒 Host 才开始接管。
- 远程访问场景可能重复通知：通过非 localhost 域名访问 DSH 时，存在性心跳走的是页面同源请求，若该路径未被代理转发，Host 会误判「没有页面」，于是两边各弹一次。本机 127.0.0.1 访问不受影响。
- 子 agent 会话不通知：这是有意的——子 agent 在一个回合内部完成，不是给用户看的「任务结束」。

结构

dsh-notify/
├── package.json # dsh.bundle.patch + dsh.client(platform: web)
├── cordis.patch.yml # 把本插件的行 insert 进 profile 组合 ├── lib/ │ ├── index.js # Host 半：存在性路由 + 会话结束检测 + Windows 原生 toast │ └── client.js # 客户端 bundle（手写，无需构建工具链） ├── LICENSE └── README.md