前言¶
用 DeepSeek Harness（DSH）跑长回合时，客户端一最小化，或被浏览器、ComfyUI 等窗口盖住，界面里的审批卡片和「回合已结束」往往看不见。官方桌面客户端在通知能力上并不完整，社区里也有若干只做「完成提醒」或「前台不打扰」的同类插件。下面介绍 LeeRolling 维护的 dsh-plugin-desktop-notify：在 desktop profile 下订阅客户端事件，在需要授权、需要回答或回合结束时弹出系统 Toast，正文带任务摘要；窗口在前台时一律不弹，避免重复打扰。
这是什么¶
dsh-plugin-desktop-notify 是 DSH 的桌面通知插件，仓库 LeeRolling/dsh-plugin-desktop-notify，许可证 MIT，当前 package 版本 0.1.0。它通过 dsh.bundle.patch 与 dsh.client（platform 为 web）注入宿主半与浏览器半，在 dsh-app://app/ 安全上下文中调用 new Notification()，在已验证环境 DSH Desktop 0.2.0-rc.2（Electron 44）、Windows 11、desktop profile 下，通知显示名为 DeepSeek Harness，使用 Windows 通知中心 Toast 与系统默认提示音。
插件以「一切皆插件」的方式扩展 DSH，与 SkillHub 插件目录 上的条目对应；该目录为社区站点，与 DeepSeek / 幻方无官方从属关系。
核心功能¶
会弹通知的情况¶
浏览器半监听三类客户端事件（只观察、不消费，原样 return next()）：
| 事件 | 用途 |
|---|---|
approval/request |
审批瀑布 |
user-questions/request |
模型提问 |
api-session/status |
会话 running 状态，检测 true → false 边沿表示回合结束 |
按场景分类后，通知标题与正文如下（资料中的表格）：
| 情况 | 通知标题 | 正文 |
|---|---|---|
需要授权执行命令（pwsh / bash 等） |
有任务需要授权 |
工具名 + 操作用途（审批理由；会剥掉 escalate sandbox to <mode>: 前缀） |
需要授权改文件（write / edit 等） |
有文件需要修改 |
工具名 + 操作用途 |
| 其它工具需要确认 | 有任务需要你确认 |
工具名 + 审批理由 |
| 模型提问等你回答 | 有问题需要你回答 |
问题原文 |
| 回合结束 | 任务已完成 |
会话名 + 提示回客户端看结果 |
什么时候不打扰¶
- 客户端在前台（窗口有焦点、页面可见）：不弹，只在 UI 里显示；
- 子代理（subagent）会话回合结束：不弹，仅主会话完成才提醒；
- 冷启动时本就 idle 的会话：不弹，只有观测到
running: true → false才提醒； - 同一事件 1.5 秒内重复：去重，只弹一次。
用法上：先在客户端发消息，再立刻切走。回合从按下发送开始；若先切走再回来打字，窗口回到前台，按设计不会弹通知。
诊断与自检（长期保留）¶
浏览器侧行为外部不可见，插件提供常驻诊断通道，便于排查「装着但不响」：
| 端点 | 方向 | 作用 |
|---|---|---|
POST /api/desktop-notify/report |
浏览器 → 宿主 | 上报决策：事件是否到达、被哪道闸拦下、new Notification() 是否异常、环境快照 |
GET /api/desktop-notify/selftest |
浏览器 → 宿主 | 返回自检开关状态、trace 与开关路径 |
默认 trace 写在 <DSH_HOME|~/.dsh>/desktop-notify/trace.jsonl；环境变量 DSH_DESKTOP_NOTIFY_TRACE 可改路径，设为 off / 0 / false / none / no 则关闭写入（端点与自检仍可用）。trace 超过 512 KB 会按行边界轮转，保留最近约 256 KB。
在同目录放置 selftest.flag，下次页面加载约 2 秒后会无视前后台强制弹出标题「通知自检」的 Toast，用于区分「代码未跑」与「系统不显示」；自检后应删除该文件。
读 trace 摘要：
node tools/trace.mjs # 统计 + 最近 15 条
node tools/trace.mjs --all # 全量
安装与启用¶
在 desktop profile 下安装（命令来自仓库 README）：
dsh plugin --profile desktop add link:<本目录>
# 或从仓库装：
dsh plugin --profile desktop add github:LeeRolling/dsh-plugin-desktop-notify
安装后重启 DSH 客户端生效。若用 link: 本地链入，改 lib/client.js 后重启即可，无需重装。
卸载：
dsh plugin --profile desktop remove dsh-plugin-desktop-notify
典型用法与验收思路¶
- 安装并重启客户端后，发一条会触发长回合的消息，立即切换到其他窗口。
- 等待需要授权、模型提问或回合结束，应在 Windows 通知中心看到对应标题与摘要。
- 若始终无通知：在 trace 目录放
selftest.flag做强制弹窗；或运行node tools/trace.mjs查看suppressed（如window-in-front）、threw、apply-failed等 kind。
仓库提供不依赖启动 DSH 的冒烟测试：
npm test
（假 DOM + 假 Notification，覆盖三事件、分类、前台抑制、去重、子代理静默、冷启动边沿等。）
适用场景与注意¶
适合谁：主要在 Windows 上使用 DSH Desktop、且经常把客户端最小化或盖在其它窗口后面的开发者；需要「授权 / 改文件 / 提问 / 完成」四类情境下带摘要的系统提醒，而不是只有单一「任务完成」铃。
权限与安全：插件随当前 DSH 桌面进程运行，安装前请阅读源码与 MIT 许可证，确认事件订阅与 HTTP 诊断端点符合你的环境策略。
已知限制（README 原文）：
- 点击通知切回客户端依赖
window.focus()，Electron 不保证窗口置顶；preload 未暴露 focus/flash，要完全保证需改主进程，易被客户端更新覆盖。 - 客户端进程完全退出后无法收到通知。
同类思路在社区已有多个插件（如回合结束 + 前台抑制、审批 + 提问等）；本插件侧重按情境分类摘要、常驻 trace/自检与可离线跑的浏览器半测试。文件类授权（write / edit）在 README 验收表中标记为待真实事件触发，逻辑与命令类共用同一段分类代码。
结尾¶
dsh-plugin-desktop-notify 为 DSH 官方桌面客户端补上上下文感知的系统通知：后台时才提醒，正文说明「要授权什么、要问什么、哪条会话跑完了」，并自带 trace 与自检便于排错。安装使用 desktop profile 与 README 中的 dsh plugin 命令即可。
