前言¶
用 DSH 跑长任务时，注意力通常不在那一个窗口上。你切去编辑器写代码、切去浏览器查资料，任务可能已经结束，也可能卡在权限审批或 agent 的提问上——等你切回来，才发现早就该处理了。
Codex 和 Claude Code 的用户对这个问题有熟悉的解法：Hook 通知，事件发生时在系统层面弹提醒，切到任何窗口都能看到。dsh-notifier 做的就是把这套体验搬进 DSH。DSH 的理念是「一切皆插件」，提醒这件事正好适合由插件来补。
这是什么¶
dsh-notifier 是一个 DSH 任务提醒插件，由 nanami-0713 维护，开源在 GitHub（仓库 nanami-0713/dsh-notifier），npm 包名为 @hsinsekai-nanami/dsh-notifier——两个名字不一致，搜索时需要留意。当前版本 0.5.0，MIT 许可证。
它监听四类事件，走「事件 → Hook → 系统提醒」的链路，与 Claude Code 的 Notification Hook 同构：
- 任务结束：
agent/status从running变为idle - 权限审批：
approval/requested - 用户提问：
ask_user_question - 任务出错：
agent/error
提醒分三层：DSH 网页内的 toast、系统通知中心横幅、跨窗口悬浮面板。决策类事件（审批、提问）通过钉住的弹窗等你处理，其余事件提醒后自动消失。
核心功能¶
三层提醒渠道¶
网页内 toast：DSH 网页右下角的深色通知卡片，带提示音，用 React portal 挂在 document.body 上，保证浮在页面其他元素之上。
系统通知中心横幅：macOS 走 osascript，Linux 走 notify-send，Windows 走系统气泡，可在设置中关闭。
跨窗口悬浮面板（默认开启）：macOS 上使用内置 Swift notifier，基于 NSPanel 的 .floating 层，加上 canJoinAllSpaces 和 fullScreenAuxiliary，面板浮在所有应用窗口、所有 Space、全屏应用之上，带「去处理 / 查看会话」按钮。
决策型弹窗钉住¶
审批和提问属于需要你做决策的事件，对应弹窗会钉住不放，直到你在网页端回答或拒绝后才自动关闭。任务结束和出错的弹窗则在 10 秒后自动消失，不会堆积。
手机同步提醒¶
电脑同时运行 dsh-remote bridge、手机 App 已连接时，插件可以把任务完成、需要你回答两类 PC 弹窗推送到手机（v0.4 引入）。v0.5 补上了开关：总开关 bridgePush 加按类型开关 bridgePushKinds.done、bridgePushKinds.question，手机 App 侧也有独立的接收开关，两端互不干扰。
这条链路有明确边界：只转发 done（任务完成）与 question（需要你回答）两类，审批和错误暂不转发；bridge 走局域网，没有公网系统级推送通道，手机 App 未打开或进程被杀时无法送达。
设置页可视化配置¶
v0.3 起，DSH 左下角「设置 → 提醒通知」提供可视化配置：内置 4 套预设（default / top-light / focus / native-only），可调 toast 位置、主题、宽度、圆角、停留时长、提示音、同屏数量与系统级开关。修改实时生效，并保存到 ~/.dsh/plugins/dsh-notifier/config.json。
配置也支持同源 API 读写：
GET/PUT /api/dsh-notifier/config
安装与启用¶
三种方式任选其一，装完执行 dsh web 启动或重启后生效。
方式一：npm 安装（推荐）¶
dsh plugin --profile web add @hsinsekai-nanami/dsh-notifier@0.5.0
dsh web # 启动或重启后生效
方式二：GitHub Release 安装¶
先到仓库 Releases 页下载 hsinsekai-nanami-dsh-notifier-<版本>.tgz，然后直接装 tgz，无需解压：
dsh plugin --profile web add ./hsinsekai-nanami-dsh-notifier-<版本>.tgz
方式三：源码构建安装¶
git clone https://github.com/nanami-0713/dsh-notifier.git
cd dsh-notifier
npm install
npm run build:all
dsh plugin --profile web add .
典型用法¶
装好后先做一遍验证，再做日常使用。
确认提醒出现¶
打开 DSH 网页，左下角进入「设置 → 提醒通知」，切换预设或修改字段，改动实时生效。之后跑一次任务，观察 toast 与系统提醒是否按预期出现。
跑一遍 E2E 验收¶
仓库自带事件级 E2E 脚本：
node scripts/e2e-done.mjs # 任务结束
node scripts/e2e-approval.mjs # 权限审批：面板钉住，处理完自动关闭
node scripts/e2e-question.mjs # 用户提问
node scripts/ui-test.mjs # Headless Chrome 全链路截图
经过上面的步骤，任务结束、审批、提问三类事件的提醒链路和网页 UI 都能确认到位。
验证悬浮面板在最上层（macOS）¶
macOS 上可以用 CoreGraphics 窗口枚举确认面板确实浮在屏幕上，kCGWindowLayer == 3 即 .floating 层：
swiftc scripts/winlist.swift -o /tmp/winlist && /tmp/winlist
关闭系统级弹窗¶
如果只想要网页内的 toast 和通知中心横幅，可以在设置里关闭系统级弹窗，或把插件配置中的 floating 设为 false。
平台差异与限制¶
网页内 toast 不依赖平台能力；跨窗口系统弹窗按平台选择不同实现：
- macOS：内置 Swift notifier 悬浮卡片。首次使用需要 Xcode Command Line Tools（
swiftc），首次触发时自动编译并缓存到~/.dsh/plugins/dsh-notifier/DSHNotifier；没有swiftc时自动回退到osascript display dialog / notification。 - Windows：使用系统自带的 PowerShell 加
WScript.Shell.Popup，无额外依赖；弹窗为系统对话框样式，不可自定义。 - Linux：需要安装
zenity；没有 zenity 时退化为notify-send横幅；弹窗同样为系统对话框样式。
需要说明：README 自述 Windows 与 Linux 的跨窗口弹窗未在真机验证，macOS 是经过真机验收的平台。在其他平台使用遇到问题，可向仓库提 issue。
适用场景与注意事项¶
dsh-notifier 适合这些场景：长时间挂任务、会在多个窗口或桌面间切换的人；离开工位后想用手机跟进任务进度、需要配合 dsh-remote 的人；不满足于只盯着 DSH 网页等结果的人。
安装和使用前注意三点：
1、插件以当前 dsh 进程权限运行，安装前建议先检查插件源码与许可证（本项目为 MIT）。
2、npm 包名 @hsinsekai-nanami/dsh-notifier 与 GitHub 仓库名 nanami-0713/dsh-notifier 不一致，别当成两个项目。
3、macOS 的跨窗口悬浮面板是主体验证过的实现，Windows / Linux 的对应弹窗未经真机验证，生产环境使用前先自行测试。
小结¶
回顾一下：dsh-notifier 监听任务结束、审批、提问、出错四类事件，用网页 toast、系统通知中心横幅、跨窗口悬浮面板三层渠道提醒你；决策型弹窗钉住直到你处理，任务结束 10 秒自动消失；配合 dsh-remote 还能推送到手机；配置全部可视化，实时生效。
- 插件目录页：https://www.skillhub.cn/plugins/nanami-0713/dsh-notifier
- GitHub 仓库：https://github.com/nanami-0713/dsh-notifier
其中目录页是社区维护的独立站点，与 DeepSeek、幻方没有官方从属关系，仅作插件检索用。
