前言¶
DeepSeek Harness 运行在 Node.js 环境中。在 macOS 上，命令行输出与桌面交互有限。dsh-macos-notify 插件通过原生通知中心将 Harness 的运行状态反馈到系统桌面，并提供了一套完整的过滤与音效配置机制。
插件介绍¶
这个插件提供原生 macOS 通知，支持按事件类型播放不同音效、通知过滤、多任务合并以及 DSH Web UI 内的一级设置页面。由 CrombastiC 维护，许可证为 MIT。
安装与启用¶
安装只需执行以下命令：
npx -y @deepseek-ai/dsh plugin --profile web add dsh-macos-notify
安装后，在 DSH 的 Web 界面设置导航中打开 Settings → macOS notifications。
若要移除插件，执行：
npx -y @deepseek-ai/dsh plugin --profile web remove dsh-macos-notify
核心功能¶
事件通知与音效¶
插件会在以下情况触发通知中心弹窗：
* 任务回合完成
* 任务失败或被阻塞
* 任务等待批准
* 任务被中止
针对不同事件，支持设置不同的系统音效。任何事件都可以被静音。在设置页面的音效选择器中，可以使用系统自带音效，并通过 afplay 命令在页面内预览。支持导入自定义音效，文件会被转换为 AIFF 格式，限制为 5MB 大小和 10 秒时长，最多管理 20 个文件，总容量限制 50MB，存储在 ~/Library/Sounds。
过滤与合并策略¶
为了避免并行任务淹没通知中心，插件内置了合并机制：
* 合并窗口：默认 1.5 秒的合并窗口，在此期间的结果会合并为一条通知。
* 摘要模式：可选的定期摘要功能。
* 重复错误抑制：可配置冷却窗口，抑制同一会话内的重复错误通知。
项目规则与过滤¶
通过项目路径规则，可以精细化控制通知行为：
* 静音：完全屏蔽指定路径下的所有通知。
* 仅错误：仅允许错误、阻塞事件和批准请求的通知。
* 重要项目： bypass 最小持续时间、焦点、空闲时间、安静时段和临时暂停等过滤器。
此外，还支持：
* 最小回合时长过滤：避免回复时间过短（默认 30 秒）触发通知。
* Web 标签页焦点抑制：当 DSH Web 界面有标签页处于聚焦状态时，抑制完成通知。
* HID 空闲时间 gating：要求键盘或鼠标空闲一定时间（默认 0 秒）后才发送完成通知。
安静时段与诊断¶
- 安静时段：支持每日的本地时间安静时段，并可选择在安静时段内继续发送错误和批准通知。
- 临时暂停：支持自定义时长的临时暂停，并显示剩余时间。
- 通知诊断：设置页面会记录最近 50 条决策（发送、排队、抑制、失败）及原因，数据持久化至
~/Library/Application Support/dsh-macos-notify/state.json，并在重启后保持。
终端支持¶
插件支持 OSC 9 通知协议，兼容 iTerm2、WezTerm、Kitty、Ghostty、Warp 等终端，以及通过 DCS passthrough 支持的 tmux 会话。
注意事项¶
- 系统限制：插件仅支持 macOS。原生通知依赖
osascript，自定义音效导入依赖 macOS 音频工具。 - 音效行为差异：在 OSC 9 渠道下，终端控制音效的播放与否及方式，此时忽略插件内的单事件音效选择。
- Web 设置通道：Web 设置页面使用受信任的
/macos-notifyRPC 通道，这是由于当前 DSH Web 设置代理对内置设置有命名空间白名单限制。 - 音效管理：仅 v0.2.0 及之后导入的音效会被标记为“管理音效”。手动复制到
~/Library/Sounds的旧文件在删除插件后仍会保留，需手动清理。
结语¶
该插件解决了 DSH 在 macOS 上缺乏原生反馈的问题，通过丰富的过滤和音效配置，让任务状态通知更加可控。源码与目录可访问：[GitHub 链接]。
