dsh-session-notifier：为 DSH Web 会话添加桌面通知

前言¶

在使用 DeepSeek Harness（DSH）进行智能体开发时，Web 会话通常在后台运行，执行结果、错误、审批请求或问题往往需要开发者主动去检查。这就容易漏掉重要事件，尤其是在多会话并行或长时间运行的场景下。dsh-session-notifier 专门解决这一问题，通过浏览器通知和 Windows Toast 两种方式，在关键事件发生时主动提醒开发者。

这是什么¶

dsh-session-notifier 是一个 DSH 插件，给 DSH Web 会话提供桌面通知能力：会话完成、执行失败、需要审批、需要回答时弹出通知。插件由 CoCoCoDeDeDe 维护，通过 SSE 通道向客户端推送事件，支持 Chrome/Edge 浏览器的原生通知，以及 Windows/WSL 下的 Windows Toast。

核心功能¶

两种通知渠道¶

• 浏览器通知：页面打开时由浏览器客户端弹出；点击通知后，如果已有标签页打开该会话则聚焦该标签页（不刷新），没有则新开一个标签页并定位到对应会话。
• Windows Toast：在 WSL/Windows 下由 Host 调用 PowerShell 弹出；页面关闭也能收到；点击会新开一个浏览器标签页并定位到会话（平台限制：无法聚焦已打开的标签页）。

触发事件¶

插件监听以下事件并生成通知：

通知标题使用会话标题（sessionTitle），无标题时回退到工作目录名或会话 ID 前 8 位。子代理会话默认不通知。

关注会话与抑制规则¶

插件通过 SSE 接收事件，并上报当前正在浏览的会话。Host 的 windowsToast.enabled 决定是否同时弹 Windows Toast：

• auto（默认）：有页面已授予通知权限时只发浏览器通知，避免重复；没有可用页面时回退到 Windows Toast。关闭浏览器通道时视同 always，只弹 Toast。
• always：每条未被关注会话抑制的通知同时弹 Windows Toast。
• never：从不弹 Toast。

被关注会话：同时只看一个页面、一个会话。聚焦且可见的页面上报的当前会话即被关注会话。

• 被关注会话的完成通知会被抑制（页面本身已经能看到结果）。
• 其他会话的完成都会通知。
• 失败、审批、提问即使发生在被关注会话也会通知。
• 页面失焦、最小化或关闭时，所有完成都会通知；没有页面连接时由 Windows Toast 接管。

安装与启用¶

使用官方安装命令：

dsh plugin --profile web add dsh-session-notifier

安装后需要执行以下步骤：

1. 重启 dsh web（profile 的 bundle 列表只在启动时读取）；
2. 浏览器硬刷新（Ctrl+Shift+R）；
3. 首次点击 DSH 页面任意位置，允许浏览器通知权限。

也可以在 设置 → 通用 → 桌面通知 中查看权限状态、启用通知或发送测试通知。

从源码安装（本地开发）：

cd /path/to/dsh-session-notifier
dsh plugin --profile web add "link:$PWD"

配置¶

默认配置在包内的 cordis.patch.yml。要覆盖，在本 profile 的用户 patch 层（~/.dsh/profiles/web/cordis.patch.yml）加一条同 id 的配置；匹配的覆盖会替换整个 config：

- id: dsh-notifier
  name: dsh-session-notifier
  config:
    events:
      completed: true
      error: true
      approval: true
      question: true
    windowsToast:
      enabled: auto          # auto | always | never（也接受 true/false）
      sound: true
      appId: DSH.Web
      launchUrl: http://127.0.0.1:3080/
    browser:
      enabled: true
    allowedHosts: []
    debounceMs: 4000
    includeSubagents: false   # true 时子代理/子会话也通知

改完后由 HMR 重载配置；如果没生效，刷新页面或重启 DSH。

验证与测试¶

插件提供以下端点用于验证和调试：

# 通道状态（客户端数、浏览器通道是否可用、Toast 模式、被关注会话）
curl -s http://127.0.0.1:3080/dsh-notifier/state

# 发送一条测试通知：浏览器通知 + Windows Toast
curl -s -X POST http://127.0.0.1:3080/dsh-notifier/test -H 'content-type: application/json' -d '{}'

# 模拟某个会话的事件（用于验证关注会话抑制）
curl -s -X POST http://127.0.0.1:3080/dsh-notifier/test \
  -H 'content-type: application/json' \
  -d '{"kind":"completed","sessionId":"session-other"}'

# 观察 SSE 广播
curl -sN 'http://127.0.0.1:3080/dsh-notifier/events?client=probe'

kind 可为 completed / error / approval / question / test。

点击通知的行为¶

新标签页定位完成后会把 dsh-session 参数从地址栏移除，之后刷新不会重复跳转。Toast 的打开地址可以用配置里的 windowsToast.launchUrl 覆盖。

适用场景与注意¶

适用场景¶

• 需要同时运行多个 DSH 会话，不希望错过关键事件；
• 在后台长时间运行智能体任务，需要实时反馈；
• 在远程开发环境（如 SSH/WSL）中使用 DSH，无法频繁检查页面；
• 使用反向代理部署 DSH，需要通过域名访问。

注意事项¶

• 环境要求：DSH 版本需满足 >=0.2.1-rc.2 <0.3.0-0，Node.js 版本需 >=20；
• 浏览器要求：支持 Chrome/Edge，通知授权依赖用户手势；
• Windows Toast 限制：仅 Windows 或 WSL 可用，需要 PATH 中有 powershell.exe；
• 权限与安全：通知路由只接受本机地址、dsh web 绑定地址以及 allowedHosts 里显式列出的主机；经 --public-url 反向代理访问时，要把代理域名加入 allowedHosts；路由没有额外鉴权，不要把端点暴露到不受信任的网络；
• 子代理会话：默认被过滤，主会话完成时会统一通知；如需为子代理也启用通知，将 includeSubagents 设为 true；
• 需要浏览器进程在运行才能收到浏览器通知；页面全部关掉后由 Windows Toast 接管。

结语¶

dsh-session-notifier 通过浏览器通知和 Windows Toast 两种方式，让 DSH Web 会话的关键事件不再被遗漏。开发者可以根据实际场景选择合适的通知渠道和配置策略，在多会话并行、后台运行或远程开发时保持对任务状态的掌控。插件代码开源，遵循 MIT 许可证，适合在本地开发或生产环境中使用。

• 插件目录：https://www.skillhub.cn/plugins/CoCoCoCoDeDeDe/dsh-session-notifier
• GitHub：https://github.com/CoCoCoDeDeDe/dsh-session-notifier