前言¶
在 DeepSeek Harness（DSH）里跑 Agent 时，Session 可能在后台等待你批准工具、回答问题，或跑完一轮任务。若窗口不在前台，很容易错过交互或结束时机。浏览器标签页本身也不具备 Windows 应用身份，难以弹出与 DSH Desktop 一致的系统 toast。
dsh-desktop-notify 是社区维护者 guanhaisen 提供的 DSH 插件：在 DSH Desktop 中，当某个 Session 需要你介入，或一次运行结束且时长达到阈值时，弹出 Windows 通知；点击通知可将对应 Session 带回前台。插件不轮询、不另建状态源，只读取 @deepseek-ai/dsh-client-ui-session 已发布的 ctx.uiSession.sessionStatus。
这是什么¶
- 名称：
dsh-desktop-notify（npm 包名，仓库guanhaisen/dsh-desktop-notify） - 维护者：guanhaisen
- 定位：面向 DeepSeek Harness 的桌面通知插件；依赖 Desktop 应用（Windows toast 路径依赖 Electron 渲染进程，纯浏览器标签没有可用的 AppUserModelID）
- 版本（package.json）：0.1.0；许可证 MIT；要求 Node
>=20，DSH^0.2.0-rc.1
核心功能¶
两种触发条件¶
| 触发 | 何时弹出 |
|---|---|
| Needs attention | Agent 被阻塞，等待你的批准或回答 |
| Run finished | 原本在运行的 Session 已停止，且本次运行时长至少达到 minRunMs |
「需要你注意」时，通知文案与 pendingInteraction.kind 对应：approval（特权工具待批准）、question（Agent 提问）、plan-review（计划待审）。同一交互用其 key 去重，状态重复推送不会二次弹窗。
为何做成插件而不是改 Shell¶
DSH Desktop Host 是独立 Node 子进程，其中 require('electron') 拿不到可用的 Notification，也没有 AppUserModelID；Shell 主进程里的通知逻辑仅用于强制更新提示。渲染进程侧：dsh-app: 为特权协议且为安全上下文，配合会话对非媒体权限一律放行，因此在窗口内调用 Web Notification API 即可在 electron.app.DeepSeek Harness 身份下出现真实 Windows toast，无需改 Shell、无需辅助进程。
不会弹窗的常见情况¶
| 情况 | 原因 |
|---|---|
| 你正在看该 Session | 提示已在屏幕上 |
运行时长短于 minRunMs（默认 20 秒） |
快速结束不当作「新闻」 |
| 打开窗口时 Session 已在运行 | 首次快照作基线，避免启动时连发 |
| Windows 勿扰模式 | 系统抑制横幅，通知仍可能进入通知中心 |
排查可查决策日志（见下文「验证是否生效」）。
安装与启用¶
前提：使用 DSH Desktop 应用，而非仅浏览器页。
在插件页安装（无需终端）¶
打开 Settings → Plugins → Add plugin，在 Package name or address 中粘贴其一后点 Install：
| 填写内容 | 用途 |
|---|---|
github:guanhaisen/dsh-desktop-notify |
直接从 GitHub 仓库安装（未发布到 npm） |
https://github.com/guanhaisen/dsh-desktop-notify |
同上，URL 形式 |
D:\path\to\dsh-desktop-notify |
本地目录，必须为绝对路径 |
插件管理器会在 profile 中执行 pnpm add 并写入 bundle 列表；多数情况下无需重启即可生效，若首条 toast 未出现可 Ctrl+R 刷新页面。
社区插件页说明：已安装插件不会自动更新；升级需卸载后重新安装。github: 安装跟踪仓库默认分支，重装可拉取新提交。Fork 后若默认分支不同，可使用 github:you/dsh-desktop-notify#main 等形式指定 ref。
命令行安装¶
在 DSH Desktop profile 目录下执行（Windows 示例路径：%USERPROFILE%\.dsh\profiles\desktop）：
pnpm add github:guanhaisen/dsh-desktop-notify
本地开发可链接工作副本，保存即生效：
pnpm add link:/path/to/dsh-desktop-notify
手动安装后，还须在该目录的 package.json 中把包名加入 profile bundles（插件页安装会自动完成）：
{
"dsh": {
"profile": {
"bundles": ["...existing bundles...", "dsh-desktop-notify"]
}
}
}
README 要求：该包运行时勿带 dependencies；pnpm 不会为 link 包安装其依赖，Cordis 树初始化失败会导致 DSH 无法启动。
配置项¶
在 profile patch 中该插件行，或通过 Plugins 页面设置：
| 键 | 默认值 | 含义 |
|---|---|---|
notifyOnAttention |
true |
Session 阻塞等待你时是否通知 |
notifyOnComplete |
true |
运行结束时是否通知 |
minRunMs |
20000 |
低于该毫秒数的运行忽略完成通知 |
sound |
true |
是否播放系统通知音 |
典型用法与验证¶
日常无需额外 API：安装并启用后，切到其他窗口或应用，在 Session 出现待批准、待回答或长运行结束时应收到 toast；点击通知应聚焦对应 Session。
调试时，浏览器半部通过 Cordis Inspect 提供 DesktopNotify，可从页面外查询：
| 方法 | 作用 |
|---|---|
status |
半部是否挂载、Notification.permission、是否安全上下文、跟踪的 Session |
testToast |
立即发一条真实 toast 并报告构造结果 |
decisions |
内存决策日志：已发送与故意抑制的记录及原因 |
decisions 可回答「为什么没弹」：例如 suppressed: 'watched'（正在看该 Session）、suppressed: 'too-short'（未满 minRunMs）。日志仅内存保留最近 100 条，不写磁盘。
testToast 返回 delivered: true 只表示已构造 Notification；是否与操作系统侧一致，需对照 Windows 通知中心等行为确认。
行为逻辑有 test/watcher.test.mjs，可用 node test/watcher.test.mjs 或包内 pnpm test 运行。
适用场景与注意¶
- 适合：在 Windows 上使用 DSH Desktop、长时间后台跑 Agent、需要系统级提醒再切回 Session 的开发者。
- 不适合：仅浏览器使用 DSH、或非 Windows 且未在资料中声明支持的环境（README 明确围绕 Windows toast 与 Desktop）。
- 权限与安全：插件以当前 DSH 进程权限运行，安装前请阅读 仓库源码 与 MIT 许可证，自行判断是否纳入 profile。
- 生态：DSH 社区插件目录为独立站点（如 SkillHub 插件页），与 DeepSeek / 幻方无官方从属关系；安装来源以 README 给出的
github:guanhaisen/dsh-desktop-notify或插件页指引为准。
结尾¶
dsh-desktop-notify 把 Session 的「等你介入」与「长跑结束」接到 Windows 桌面通知上，状态来自既有 sessionStatus，点击即可回到对应 Session。目录与文档：
- 插件目录页：https://www.skillhub.cn/plugins/guanhaisen/dsh-desktop-notify
- GitHub：https://github.com/guanhaisen/dsh-desktop-notify
