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