前言¶
DeepSeek Harness (DSH) 是一个基于插件化的智能体开发框架。DSH 的运行通常依赖 dsh web 服务，这意味着智能体的任务状态、审批请求或定时触发事件主要展示在浏览器页面中。
当智能体在后台执行任务，或需要你进行审批时，如果视线离开页面，这些关键信息容易被遗漏。dsh-desktop-notify 插件的作用是将 DSH 内部的关键事件直接桥接到操作系统的桌面通知中，确保你不会错过任何重要的状态变化。
功能说明¶
该插件随 dsh web 启动自动加载，支持 Windows 和 Linux 系统。核心能力包括：
- 任务状态监控：当 Agent 从运行状态变为空闲时，通知任务完成。
- 等待交互提醒：当智能体调用
ask_user_question等工具发起提问时，提醒返回页面输入。 - 审批与拒绝通知：当审批策略为
never导致操作被静默拒绝时，发出明确通知。 - 后台任务追踪：后台子代理、目标或命令任务结束时逐一提醒。
- 定时任务触发：仅在定时任务真正被投递（触发）时通知，而非仅创建时。
- 启动与挂载播报：每次
dsh web启动后，推送插件挂载状态（正常/降级）。 - 点击跳转支持：支持点击通知跳转回对应的会话、内置页面或外部 URL。
- 双渠道通知：优先使用 Web Notification（点击精确激活标签页），在无权限或不可用时自动降级为原生 Toast（Windows 使用 koffi，Linux 使用 D-Bus）。
- 权限变更即时反馈：当浏览器通知权限被更改时，立即通知当前运行模式。
安装与启用¶
前置条件¶
- DSH 版本：必须满足
>= 0.1.7-rc.2且<= 0.2.0-rc.2。 - Web 启动：必须已经启动过一次
dsh web（需已生成 web profile）。 - 运行环境：Windows 需要安装 koffi（插件会自动处理），Linux 无额外依赖。
安装步骤¶
在 DSH 的插件管理页面选择添加插件，安装目标填入以下任一内容：
- 包名：
@mvyvn/dsh-desktop-notify - 仓库地址：
https://github.com/Mvyvn/dsh-desktop-notify
安装完成后，完全重启 dsh web 进程并刷新 DSH 页面。
首次授权¶
如果需要使用 Web Notification 渠道，浏览器要求用户手势才能触发授权弹窗。插件会在 DSH 页面显示一个居中卡片，点击“设置”按钮即可授权。授权后通知由浏览器直接显示；如果拒绝或未授权，插件会自动降级为原生 Toast 模式。
使用方法¶
插件注册为 Cordis 服务 desktopNotify。其他插件可以通过 ctx.get('desktopNotify') 调用。
基础推送¶
使用 push 方法推送通知，默认遵循“聚焦门控”规则（即当你正在查看该会话时不会打扰你）。
// 在你的插件代码中
const desktopNotify = ctx.get('desktopNotify');
if (!desktopNotify) return;
// 普通推送，受聚焦门控影响
desktopNotify.push({
title: '构建完成',
message: '工作区/会话:全部通过',
urgency: 'normal', // 'low' | 'normal' | 'critical'
sessionId: agent.session
});
强制推送¶
使用 pushAlways 绕过所有门控，强制弹窗。
desktopNotify.pushAlways({
title: '磁盘告急',
message: '剩余 1GB',
urgency: 'critical'
});
结果查询¶
使用 notify 方法获取详细的推送结果（是否入队、是否被静默等）。
const result = desktopNotify.notify({
title: '构建完成',
sessionId: agent.session
});
// 返回: { ok: true, queued: false, silenced: true, reason: 'silenced', ... }
点击跳转配置¶
通过 click 字段配置点击后的行为。不传 click 则通知不可点击。
// 跳转回指定会话
desktopNotify.push({
title: '打开文档',
click: {
type: 'session',
sessionId: agent.session
}
});
// 跳转外部 URL
desktopNotify.push({
title: '查看详情',
click: {
type: 'url',
url: 'https://example.com'
}
});
静默模式配置¶
在插件设置页，可以为不同类型的通知配置静默模式（session / tab / never），决定在何种情况下不发送通知。
注意事项¶
- 版本兼容性：插件依赖 DSH 的
connection、webServer等服务，严格限定版本范围。版本范围外的行为未做兼容性保证。 - 许可证：插件采用 GPL-3.0-or-later 许可证。安装前请确认源码合规性。
- 权限限制：浏览器通知权限需要在页面内通过用户操作触发授权，无法自动弹窗。
- 图标：原生 Toast 使用 DSH Logo（透明底 PNG/ICO），随系统主题自动切换深浅色。
总结¶
dsh-desktop-notify 为 DSH 提供了系统级的监控能力，将复杂的智能体后台状态转化为直观的桌面提醒。通过其提供的 desktopNotify 服务接口，开发者可以轻松集成通知功能，增强用户体验。
