Linux 桌面提醒 Wlaeg/dsh-notify-linux

dsh-notify-linux

为 Linux + GNOME 上的 DSH（DeepSeek Harness）提供桌面通知与提示音。DSH 完成任务、需要你做出选择、有工具调用等待批准，或者执行出错时，主动提醒你。

通知由 DSH 主进程发出，而不是浏览器页面 —— 因此页面切到后台标签、窗口最小化，甚至页面完全关闭时，提醒一样能送到。

- 无 npm 运行时依赖（Host 半身只用 Node 内置模块）
- 通知走 notify-send，声音走 paplay，并以 canberra-gtk-play 兜底
- 浏览器侧兜底（页内浮层、Web Notification、Web Audio 合成音），用于系统通道不可用的环境
- 所有开关都能在 DSH 设置页调整，也可以直接改一个 JSON 文件

会提醒哪些情况

共四类事件。每一类都有独立开关、独立的紧迫度与图标，以及各自的音效（turnEnd 除外，它用你选择的提示音主题）。

| 类型 | 触发时机 | 通知标题 | 紧迫度 | 图标 | 声音 |
| turnEnd | 整个 agent 回合即将结束，模型不再有待回答的输出 | DSH 已完成任务 | normal | dialog-information | 所选主题 |
| question | 模型请求你作答（单选 / 多选 / 自由文本） | DSH 正在等待你的选择 | normal | dialog-information | message-new-instant |
| approval | 某个工具调用在等待人类放行 | DSH 需要你的批准 | normal | dialog-information | dialog-information |
| error | 某一步或整个回合失败 | DSH 执行出错 | critical | dialog-error | dialog-error |

通知正文会带上会话标识，方便你认出是哪一摊活。格式为 <工作区名> · <会话 id 前 8 位>，后接事件细节，例如：

DSH 已完成任务 default-workspace · 44b6a957 的回合已结束

turnEnd 挂在 agent/turn-stopping 上 —— 那是回合真正结束的时点。工具调用的往返不会触发它，只有整个回合收尾才会。

通知文案目前是中文（由 Host 半身发出）。设置页本身是完整双语的（中文与英文）。

为什么在 Host 侧发通知

纯浏览器通知方案有一个硬限制：只有页面开着、浏览器还活着的时候才有效。切到别的窗口、把浏览器最小化、或者关掉标签页，通知就根本送不到。

而 DSH 主进程的存活时间比页面长得多。notify-send 走 GNOME 通知中心，所以即使页面没聚焦、浏览器不在前台，甚至页面根本没打开，通知与声音一样会到。

因此浏览器半身不做重复投递，而是负责另外三件事：

| 半身 | 文件 | 职责 |
| Host | index.js（500 行） | 监听四类事件、发出真实的系统通知与声音、持久化配置、提供 HTTP API |
| 浏览器 | client.js（682 行） | 设置页、页内浮层，以及在 Host 侧没能送出时用 Web Notification / Web Audio 兜底 |

是否兜底由 Host 随每个事件返回的两个布尔值 desktop 与 sound 决定，它们的含义是「这次真的发出去了没有」。系统通知既然已经送出，浏览器就保持安静，绝不会提醒两遍。

环境要求

| 项目 | 说明 |
| 平台 | Linux + GNOME（已在 Manjaro GNOME、Wayland 下验证） |
| DSH | 任意带 Cordis 插件系统、提供 webServer 与 settings.section 插槽的 DSH 构建 |
| Node | >= 22（DSH 自身的要求） |
| 通知 | libnotify 提供的 notify-send |
| 声音 | pulseaudio-utils 提供的 paplay，或 libcanberra 提供的 canberra-gtk-play |
| 声音文件 | /usr/share/sounds/freedesktop/stereo（freedesktop 声音主题） |
| npm 依赖 | 无 —— package.json 里没有 dependencies |

这些外部工具在某种意义上都是可选的，因为插件会优雅降级：如果 notify-send 不存在，插件会把这个能力标记为不可用，浏览器半身就可以用 Web Notification 接手。事件分发路径上从不 await 任何东西 —— 命令缺失或执行失败都绝不会拖住 agent。

插件在运行时探测这些工具，并在设置页里报告结果（notify-send、paplay、 canberra-gtk-play 各显示为可用或不可用）。

安装

这是一个 DSH 的 Cordis 插件 bundle。请通过 DSH 的插件管理（plugin_manager，动作 install_bundle）安装，指向以下任一来源：

- 本地目录 —— /home/wlaeg/文档/deepseek-harness/default-workspace/dsh-notify
- 或 Git 仓库 —— https://github.com/Wlaeg/dsh-notify-linux

bundle 在 package.json 里声明了自己的 patch：

{
"dsh": {
"bundle": { "patch": "./cordis.patch.yml" },
"client": { "platform": "web", "immediately": true, "inject": [] }
}
}

而 patch 只有一行 insert，用来挂载 Host 半身：

- insert:
- id: dsh-notify-linux
name: 'dsh-notify-linux'
config: {}

浏览器半身由 dsh.client 声明，并绑定在 name 为裸包名的那一行上 —— 子路径形式的条目不会携带浏览器半身。

安装完成后插件即生效。刷新一次 DSH Web 界面，浏览器半身就会注册它的设置分区。
没有额外的 CLI 安装步骤。

替换已安装的副本（例如改完源码之后）需要重启 DSH 宿主进程。插件管理会立刻改写依赖与 patch，但正在运行的进程仍持有启动时加载的那一代 JS 模块，旧路由与旧处理器会一直活着直到 DSH 重启 —— 只刷新页面不够。宿主半身的 HTTP 路由让这一点很好判断：旧副本还在时， GET /api/dsh-notify-linux/config 会返回 401，因为旧的 /api/dsh-notify 前缀路由仍在抢这条路径。

设置页

设置分区名为「任务通知」（settings.section 插槽，order 30）。其中包含：

- 总开关
- 四类事件的开关
- 桌面通知 / 提示音的开关，以及完成时的提示音主题
- 子代理、仅前台不打扰、冷却时间等选项
- 浏览器兜底分组，并显示当前浏览器通知权限
- 试一下 一行：每个事件类型一个按钮，走与真实通知完全相同的投递路径
- 能力检测行：显示本机是否找到了 notify-send、paplay、canberra-gtk-play

截图占位 —— 本仓库目前还没有截图，因此这里不引用任何图片。本块是显式的占位，不是坏链。

配置

所有选项都在一个文件里：

<DSH profile 目录>/dsh-notify-linux.json

profile 目录的解析顺序是 $DSH_PROFILE_DIR，否则为 $DSH_HOME/profiles/$DSH_PROFILE（默认 ~/.dsh/profiles/web）。在本机上即 ~/.dsh/profiles/web/dsh-notify-linux.json。

文件以原子方式写入（临时文件 + rename），权限为 0600，所以读侧永远看不到写了一半的 JSON。你可以直接改它 —— 每次推送通知都会重新读取 —— 也可以用设置页，它走的是同一套写入逻辑。

默认值

| 键 | 类型 | 默认值 | 含义 |
| enabled | boolean | true | 总开关。关掉后所有事件都不再提醒。 |
| systemNotify | boolean | true | 经 notify-send 发桌面通知。 |
| systemSound | boolean | true | 播放系统声音主题里的提示音。 |
| browserToast | boolean | true | 显示页内浮层。 |
| browserNotify | boolean | true | 用 Web Notification 兜底。需要浏览器授权。 |
| browserSound | boolean | false | 用 Web Audio 合成音兜底。 |
| soundTheme | string | 'complete' | turnEnd 使用的提示音，取值为 complete、message、bell、none。 |
| events.turnEnd | boolean | true | 回合结束时提醒。 |
| events.question | boolean | true | 模型需要你选择时提醒。 |
| events.approval | boolean | true | 工具调用需要批准时提醒。 |
| events.error | boolean | true | 某一步或整个回合失败时提醒。 |
| includeSubagents | boolean | false | 子代理会话也提醒（默认关闭，避免并行任务刷屏）。 |
| onlyWhenUnfocused | boolean | false | DSH 窗口在前台时，不弹系统通知、不播声音。 |
| cooldownSeconds | number | 3 | 同一类提醒的最小间隔，取值限制在 0–120。0 表示关闭冷却。 |

未知字段会被丢弃，类型不对就退回默认值，文件缺失或损坏则静默恢复默认 ——通知配置永远不该让插件挂掉。

示例：

{
"enabled": true,
"systemNotify": true,
"systemSound": true,
"browserToast": true,
"browserNotify": true,
"browserSound": false,
"soundTheme": "message",
"events": { "turnEnd": true, "question": true, "approval": true, "error": true },
"includeSubagents": false,
"onlyWhenUnfocused": true,
"cooldownSeconds": 5
}

提示音主题

turnEnd 用你选择的主题，其余三类事件音效固定。

| 主题 | /usr/share/sounds/freedesktop/stereo 下的文件 | 界面文案 |
| complete | complete.oga | 轻快完成音 |
| message | message.oga | 消息提示音 |
| bell | bell.oga | 铃声 |
| none | — | 静音 |

设置页只会列出本机确实存在对应 .oga 文件的主题。若播放时文件不在，则跳过 paplay，回退到 canberra-gtk-play -i <sound>。

架构

Host 半身（index.js）

| 行号 | 作用 |
| :187 | sendDesktop(title, body, kind) —— 拉起 notify-send，带 -a DSH、图标、紧迫度、-t 8000 |
| :200 | playSound(sound) —— 先 paplay 播放主题文件，否则 canberra-gtk-play |
| :254 | fire(kind, title, body) —— 依次应用总开关、单事件开关、冷却，然后分发 |
| :289 | agent/turn-stopping 处理器 → turnEnd |
| :299 | user-questions/request waterfall 处理器 → question |
| :317 | approval/request waterfall 处理器 → approval |
| :334 | agent/error 处理器 → error |
| :489 | ctx.inject(['webServer']) —— 等 webServer 就绪后注册 HTTP 路由 |

有三个值得了解的设计决定：

1. 即发即忘（fire-and-forget）。 通知以 detached 子进程方式拉起并 unref()。
事件分发路径绝不 await 外部进程，通知失败也绝不影响 agent。插件刻意不使用 DSH 的 subprocess 服务，因为那个服务的契约是「调用方持有句柄并对生命周期负责」，与这里想要的恰好相反。
2. waterfall 里必须 return next()。 user-questions/request 与 approval/request 都是串行责任链。本插件是纯观察者：监听器只做副作用，然后把
next() 原样委托下去。一旦忘记委托，Host 侧的问询与批准流程会全部卡死。
3. 会话总线环境修复。 如果 DSH 是从 systemd 用户单元或 SSH 里拉起的， DBUS_SESSION_BUS_ADDRESS / XDG_RUNTIME_DIR 可能缺失，notify-send 会静默失败。
插件在拉起子进程前补上 unix:path=/run/user/<uid>/bus 与 /run/user/<uid>。

通知使用了 -h string:x-canonical-private-synchronous:dsh-notify-linux-<kind>，所以同类的新通知会顶替上一条，连续回合不会把通知中心刷满。

浏览器半身（client.js）

| 行号 | 作用 |
| :238 | requestPermission() —— 在用户手势里请求 Web Notification 权限 |
| :254 | beep(kind) —— 用振荡器现场合成提示音，每类事件一段音符序列 |
| :279 | webNotify(title, body, kind) —— Web Notification，带按类型的 tag 与 silent: true |
| :308 | showToast(title, body, tone, onClick) —— 原生 DOM 页内浮层，7 秒后自动消失 |
| :631 | new EventSource('/api/dsh-notify-linux/events') —— 订阅实时事件流 |
| :671 | ctx.slots.register({ name: 'settings.section', id: 'dsh-notify-linux', order: 30 }) |

浏览器半身是手写的 ModuleLoader 包：无构建步骤，除 shell 已提供的 react 外无依赖，颜色全部走主题变量，因此跟随明暗模式切换。

合成提示音的音符序列（[频率 Hz, 偏移 秒]）：

turnEnd 880 → 1318
question 740 → 740
approval 988 → 988
error 300 → 220

播放结束后 800 ms 会关闭 AudioContext，避免它一直占着一条音频通道。

HTTP 接口

Host 半身在 DSH 的 webServer 上注册了同源路由前缀：

| 方法 | 路径 | 用途 |
| GET | /api/dsh-notify-linux/config | 当前配置、工具能力、可用提示音主题、窗口聚焦状态 |
| POST | /api/dsh-notify-linux/config | 局部更新配置（深合并，含 events），并落盘 |
| POST | /api/dsh-notify-linux/test | 用正常链路真实触发一次指定 kind 的通知 |
| POST | /api/dsh-notify-linux/presence | 上报窗口是否聚焦（供 onlyWhenUnfocused 使用） |
| GET | /api/dsh-notify-linux/events | SSE 事件流：hello（能力）、notify（真实的一次投递）、config（配置变更） |

SSE 流每 25 秒发一条 : ping 注释，避免空闲连接被中间的代理掐断。浏览器半身在连续 6 次连接失败后会主动退避（等 30 秒再试），而不是无限紧循环重连。

安全边界

DSH 的 webServer 常绑 0.0.0.0，但这些路由能改插件配置、能触发真实通知，不该对公网开口。每个请求都要过 allowed(req)，只放行：

- 127.0.0.1、::1、localhost 或空地址
- 10.0.0.0/8、127.0.0.0/8
- 192.168.0.0/16
- 172.16.0.0/12
- IPv6 唯一本地地址 fc00::/7 与链路本地地址 fe80::/10

其余一律返回 403 {"error":"forbidden"}。请求体上限 64 KiB。

已验证行为

以下均为在真机（Manjaro GNOME、Wayland）上装好插件、跑着真实 DSH 会话时观测到的：

- 抓到了真实的 D-Bus 通知调用。 触发事件时监控会话总线，看到了插件发出的真实 org.freedesktop.Notifications.Notify 方法调用，也就是说通知确实经由 GNOME 通知中心，而不是任何模拟层。
- 真实回合结束触发了真实通知。 在活动会话中，通知正文为：

default-workspace · 44b6a957 的回合已结束

—— 工作区名取自会话的 cwd，后接会话 id 的前 8 个字符。
- 真实播放了声音。 通知触发时 pactl list sink-inputs 抓到了 paplay 的 sink-input，说明音频链路（而不只是文件查找）是通的。

设置页的「试一下」按钮调用 /test，走的是与真实事件完全相同的 fire() 路径，所见即所得。

故障排查

| 现象 | 排查方向 |
| 没有桌面通知 | notify-send 是否已安装且在 PATH 里？设置页的能力行会显示。 |
| 没有声音 | paplay（或 canberra-gtk-play）是否存在，.oga 文件是否在 /usr/share/sounds/freedesktop/stereo 下？ |
| 只是偶尔没提醒 | cooldownSeconds 会压制同类重复提醒 —— 调小或设为 0。 |
| 完全没有提醒 | enabled 必须为 true，且对应 events.<kind> 开关要打开。 |
| 盯着 DSH 时不提醒 | onlyWhenUnfocused 开着 —— 窗口在前台时按设计不弹系统通知、不播声音。 |
| 设置页打不开 | Host 半身需要 webServer 服务；后端不可达时页面会显示重试按钮。 |
| 子代理任务没有提醒 | includeSubagents 默认就是 false。打开后才会包含。 |

卸载

通过 DSH 的插件管理（plugin_manager，动作 remove_bundle）移除 dsh-notify-linux，然后删掉遗留的配置文件：

rm -f ~/.dsh/profiles/web/dsh-notify-linux.json

系统上没有安装任何其它东西 —— 没有 systemd 单元，也没有 DSH profile 与插件目录之外的文件。插件播放的声音文件属于 freedesktop 声音主题，保持不动。

许可

MIT © Wlaeg (wlaeg@users.noreply.github.com)