DeepSeek Harness Windows 原生通知插件：dsh-win-notify

前言¶

DeepSeek Harness (DSH) 的通知插件通常运行在渲染层（浏览器页面内的 JS）。当你把标签页切走、关闭浏览器窗口，或者最小化 DSH 时，这类通知就会失效。这恰好是你最需要被叫回来处理任务的时候。

dsh-win-notify 插件运行在宿主层（Cordis host 半身），即 DSH 的主进程。事件在进程内直接产生，不经过浏览器。因此，前台窗口是否打开、标签页是否在浏览器中，都不影响通知送达。它利用 Windows 原生 Toast API，提供对话完成、子代理状态、后台任务等事件的通知。

核心功能¶

插件通过监听 DSH 的宿主事件触发通知，覆盖以下场景：

对话事件：对话回合完成、出错或中断。
子代理事件：子任务完成或异常结束。
后台任务：任务完成、失败或取消。
用户交互：模型提问、工具审批请求。
通知特性：
- 前台探测：默认 auto 模式下，通过 Win32 API 探测前台窗口，正在看 DSH 时不弹窗。可设为 always 或 never。
- 合并与去重：同一工作区短时间内的多会话完成会合并为一条通知；后台任务与回合完成也会合并。
- 速率控制：支持全局速率配额（minIntervalMs / ratePerMinute）和免打扰时段（quietHours）。
- 音效：使用 Windows 系统具名音效（Notification.*），按事件区分（完成、提问、审批、出错）。
- 点击行为：Desktop 配置下点击通知抬回窗口；其他场景打开带鉴权 token 的 Web UI。

安装与启用¶

插件包名为 @zhang-tod/dsh-win-notify。

CLI 安装¶

适用于 web、headless、sdk、acp 及自建配置档：

dsh plugin --profile <profile> add @zhang-tod/dsh-win-notify

安装完成后，必须重启 DSH 才能加载宿主层插件。

Desktop 安装¶

DSH Desktop 的配置档由 Electron 应用独占管理，CLI 命令会被拒绝。请通过应用内入口操作：

侧栏点击插件。
点击 Add plugin，输入 @zhang-tod/dsh-win-notify。
安装后启用该 bundle，随后重启 DSH。

配置方法¶

配置文件位于配置档的 cordis.patch.yml 中。按以下格式编写：

id: dsh-win-notify
config:
  # 前台探测模式：auto (默认), always, never
  mode: 'auto'
  # 是否开启对话回合通知
  turns: true
  # 是否开启子代理通知
  subagents: true
  # 是否开启后台任务通知
  jobs: true
  # 是否开启提问通知
  questions: true
  # 是否开启审批通知
  approvals: true
  # 是否播放音效
  sound: true
  # 端口：0 表示自动获取 DSH 实际端口，不要写死
  port: 0
  # 免打扰时段，如 "23:00-07:30"，支持跨午夜
  quietHours: ""
  # 免打扰时段内是否放行紧急事件（提问/审批）
  quietUrgent: true
  # 全局速率限制：相邻通知最小间隔毫秒数
  minIntervalMs: 3000
  # 合并窗口：同工作区多会话完成合并的时间窗口
  mergeWindowMs: 3000

限制与不做¶

插件有明确的能力边界，使用前需了解：

平台限制：仅支持 Windows，不支持 macOS 或 Linux。
音效限制：音效不可自定义，必须使用 Windows 系统具名音（Notification.* 前缀）。sound 仅是开关，不能更改音色。
审批限制：不支持 toast 按钮一键审批；不支持常驻通知（scenario="reminder"）。
点击限制：点击通知不会跳转到具体会话，仅打开 DSH 主界面（Desktop 下抬回窗口）。
权限依赖：若 DSH 处于全权限模式（approval: never），系统层面不会发出审批请求，插件自然收不到通知。
安装限制：Desktop 配置档不能通过 CLI 的 --profile desktop 安装，必须走应用内设置。
技术细节：
- 不声明 @deepseek-ai/dsh-* peerDependencies。
- 不提供图形设置页，配置直接写 cordis.patch.yml。
- 通知归属可能显示为通用值（取决于系统注册的应用标识）。
- 前台探测可能因窗口标题被修改而失效。

总结¶

dsh-win-notify 为 Windows 上的 DSH 提供了可靠的宿主层通知能力，解决了浏览器关闭后消息丢失的问题。它通过合并、去重和速率控制，保持了通知系统的整洁。由于依赖 Windows 原生 API，其配置较为底层，需要直接编辑 cordis.patch.yml。