macOS 通知插件：dsh-plugin-mac-notify

前言¶

DSH 的会话经常在后台长时间运行。当任务完成、需要人工输入或发生错误时，直接在终端里翻日志不够直观，容易错过关键信息。这个插件通过 macOS 通知中心提醒你，点击通知即可回到 DSH 页面，适合在无人值守或远程服务器上运行 DSH。

这是什么¶

这是一个非官方的 DSH 客户端插件，由 AK-blank 维护。它是一个 Host 侧的 bundle，专注于监听 Host 事件并通过 terminal-notifier 或系统自带的 osascript 将警报推送到 macOS 通知中心。它不包含浏览器端的渲染代码。

核心功能¶

插件监听以下 4 种 Host 事件并发送通知：

任务完成：当 agent/status 状态从 running 变为 idle 时。
需要回答：当代理调用 ask_user_question 被阻塞时。
需要批准：当代理等待审批决策时。
执行出错：当某一步骤或回合发生错误时。

默认情况下，子代理静默，且非紧急通知在 5 秒内会合并显示，避免通知刷屏。

安装与启用¶

使用官方 CLI 安装，安装后必须重启 dsh web 或 dsh tui 进程才能生效。

dsh plugin --profile web add github:AK-blank/dsh-plugin-mac-notify

安装完成后，插件会在 DSH 的 Plugins 页面出现，可以手动开关。

配置¶

插件本身不携带配置项，所有设置需在 cordis.patch.yml 中覆盖（在 bundle 层之后应用）：

- id: mac-notify
  name: 'dsh-plugin-mac-notify'
  config:
    enabled: true
    sound: Ping
    notifyOnApproval: false
    url: 'http://127.0.0.1:3080'

主要配置项包括：
* enabled：总开关。
* sound：音效名称（如 Ping、Glass）或 off。
* onClick：点击行为，focus（聚焦现有标签页）、open（打开新标签页）、none。
* notifier：选择 auto（推荐）或强制使用 osascript。
* minIntervalMs：非紧急通知的最小间隔（默认 1500ms）。

典型用法¶

安装后，可以通过以下命令进行自检，确保 57 项断言全部通过：

node selftest.mjs

如果需要调试而不实际发送通知，可以使用环境变量：

DSH_MAC_NOTIFY_DRY_RUN=1 dsh web

注意事项¶

平台限制：仅支持 macOS。其他平台插件会激活并记录日志，但不会发送通知。
依赖项：点击跳转功能依赖 terminal-notifier。如果没有安装，插件会回退到 osascript，但无法执行点击动作。
- 安装命令：brew install terminal-notifier
系统权限：需要授予插件通知权限和 macOS Automation 权限（首次点击时系统会弹窗）。
重启生效：插件更新后，必须重启 dsh web 或 dsh tui 进程才能加载新代码。

结尾¶

该插件通过原生通知解决了 DSH 后台运行时的状态同步问题。通过查看 GitHub 仓库，你可以获取源码和更多调试信息。