前言¶
DeepSeek Harness (DSH) 采用插件化架构，允许开发者扩展功能。在运行长会话或后台任务时，可能会错过关键节点。dsh-notify 是一个插件 bundle，用于在会话完成任务、提问或需要审批，且你不在当前会话时，发送桌面通知并播放提示音。
功能¶
该插件主要提供以下能力：
- 触发时机：支持在以下事件触发通知
- 会话一轮对话结束（
turn/end） - 持久化目标完成（
goal/change） - Agent 调用提问接口（
tool/call） - 需要用户审批的动作（
approval/asked）
- 会话一轮对话结束（
- 子代理过滤：只监听顶层会话。插件通过会话头部的
origin: 'subagent'标记过滤掉所有子代理（subagent）的事件，避免干扰中间过程。 - 在场检测：仅在用户离开时通知。
- 当页面为当前标签页且窗口有焦点时，视为“在会话中”，不弹通知。
- 切换标签页、最小化或关闭页面时，视为“离开”，触发通知。
- 标签页崩溃或断连超过 45 秒（TTL），会自动视为离开。
- 系统默认提示音：尝试调用
canberra-gtk-play -i message或pw-play/paplay播放系统提示音，支持通过配置关闭。 - 通知后端：支持 Linux
notify-send（自动检测）、纯控制台输出，或任意自定义命令（支持模板替换）。
安装¶
本包是一个 DSH 规范的 bundle，包含宿主插件和浏览器客户端半部。
从本地目录安装¶
# 1. 构建（如果尚未构建）
npm install
npm run build
# 2. 安装到指定 profile
dsh plugin --profile web add /path/to/DSH_remind
dsh plugin 会自动检测 dsh.bundle.patch 并追加到 profile 的 bundle 列表中，重启 profile 即可生效。
从 GitHub 安装¶
dsh plugin --profile web add github:you/dsh-notify#<commit-sha>
验证配置层¶
在不启动的情况下检查配置是否正确加载：
dsh --profile web --patch /path/to/DSH_remind/cordis.patch.yml --dump-config
配置¶
默认零配置即可运行。在 profile 的 cordis.patch.yml 中按 id 覆盖该行。
默认配置参数¶
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
backend |
auto \| notify-send \| console \| command |
auto |
自动检测 notify-send，否则降级为控制台 |
command |
string | '' |
自定义命令模板，经 /bin/sh -c 执行，支持 {title} 和 {message} 占位符 |
urgency |
low \| normal \| critical |
normal |
notify-send 的紧急度 |
onTurnComplete |
boolean | true |
一轮回答完成时通知 |
onGoalComplete |
boolean | true |
goal 完成时通知 |
onUserQuestion |
boolean | true |
Agent 提问时通知 |
onApproval |
boolean | true |
需要审批时通知 |
onlyWhenAway |
boolean | true |
仅在离开时通知 |
playSound |
boolean | true |
播放系统提示音 |
debounceMs |
number | 0 |
同类通知的最小间隔（毫秒） |
自定义命令示例¶
在 command 后端中自定义通知行为：
# 通知 + 自定义提示音文件
config:
backend: command
command: 'notify-send --app-name "DeepSeek Harness" --urgency critical "{title}" "{message}" && paplay "$HOME/.local/share/sounds/custom.oga"'
# 通知 + 留痕到日志文件
config:
backend: command
command: 'notify-send "{title}" "{message}"; echo "$(date "+%F %T") {title} | {message}" >> "$HOME/.local/share/dsh-notify.log"'
工作原理¶
插件分为浏览器端（客户端半部）和宿主端（bundle 行）：
- 浏览器端：监听页面可见性变化（
visibilitychange）、焦点/失焦（focus/blur）以及心跳（15s）。将当前会话 ID 和在场状态通过 RPC 上报给宿主。 - 宿主端：订阅
session/event流。在处理事件前，先检查会话是否为顶层会话（排除subagent），再检查presence服务中记录的用户是否“在场”。 - 执行：通过防抖处理，最终触发通知和声音播放。通知失败不会影响会话本身的运行。
在 Headless 或 TUI 环境中，由于没有浏览器端上报，presence 恒为“离开”，所有事件均会触发通知。
注意事项¶
- 纯事件观察者：插件不会拦截或修改任何会话行为，通知故障不会影响 DSH 的运行。
- 权限与安全：安装前请检查源码与许可证。插件以当前 DSH 进程的权限运行，自定义命令需注意安全风险。
- Headless 场景：无浏览器环境的场景下，所有事件均会触发通知。
