前言¶
在 DeepSeek Harness（DSH）里跑 Agent 时，任务往往在后台跑很久：完成、等你审批或提问、或会话报错，若你一直盯着别的标签页，很容易错过。系统级 Web Push 需要 Service Worker 和额外基础设施；本插件走的是当前页面内的浏览器 Notification API，配合可选的合成提示音，在三种典型状态下提醒你，并尽量与 Harness 官方设置页的视觉与控件保持一致。
下面介绍插件定位、触发逻辑、设置项与安装方式。事实以 GitHub 仓库 README 为准。
这是什么¶
dsh-plugin-agent-notifications 是 DSH 的 Web 客户端插件（分类：客户端），由维护者 genius-alray 发布，npm 包名同为 dsh-plugin-agent-notifications。它在 Agent 任务完成、需要你操作（审批、提问、计划审阅）或出错时，通过浏览器通知 API 提醒，并可分别为三种情况选择不同提示音。
通知由当前 Harness Web 标签页发出，因此需要保持该标签页打开；插件不注册 Service Worker，也不做 Web Push。
触发时机¶
判定依据来自 Session 插件派生的 UI 状态（uiSession.sessionStatus）以及转发的 api-session/error 事件，不依赖审批 UI 与提问 UI 的注册顺序，也不会抢占官方审批面板。
| 类型 | 判定依据 |
|---|---|
| 任务完成 | 会话 Agent 状态由 running 变为空闲；同一时刻若已有待办，只发「需要操作」，不重复响 |
| 需要操作 | 出现等待用户的交互：工具审批（含工具名）、向用户提问（含问题文本）、计划审阅 |
| 出错 | 会话级错误事件，正文为压缩成单行的错误信息（截断 200 字符） |
行为上还有几条值得记住的细节：首次看到某会话状态只做基线，不会在打开页面或重连时连续轰炸；同一会话同一类型 4 秒内只响一次；不同审批/提问请求各自算独立提醒。点击通知会聚焦窗口并打开对应会话（会话已不存在时只聚焦）。
设置与提示音¶
安装并在 Harness 中启用后，打开 设置 → 通知 进行配置。页面沿用官方 Settings 骨架，开关、下拉、按钮等使用 Harness 原语（如 Switch、Menu、Button），配色跟随明暗主题；偏好保存在浏览器 localStorage（键名 dsh.agent-notifications.v1），与通知权限同域，换浏览器不会互相同步。
页面大致三组：
- 总开关「启用通知」。关闭时，三个事件开关、音效行、音量滑杆一并禁用。
- 触发时机：任务完成 / 需要操作 / 出错，各有一个开关；开关打开后才显示该事件的提示音选择（选择器 + 试听）。三个默认音互不相同：叮咚 / 竖琴琶音 / 水滴。某事件选「静音」仅关声音，事件开关仍可保持开启。
- 范围：仅在页面处于后台时提醒、包含子代理、统一音量 0–100。
权限未授予时，内联 Alert 会引导点击「允许通知」；被拒绝或不支持时显示警告。授权后 Alert 消失。末尾有「发送测试通知」。权限未授予时不构造通知，但仍可播放提示音作为降级；不支持 Notification API 或非安全上下文时同样以提示音为主，设置页会说明。
提示音由 Web Audio 合成，不加载音频文件；通知本身带 silent: true，避免与系统提示音叠加。浏览器可能阻止无用户交互的自动播放，插件在首次点击/按键/窗口焦点时解锁音频上下文，并在切回标签页时主动唤醒。音量滑杆作用于全部三种预设音。
安装与启用¶
推荐从 Harness 插件 面板安装：侧边栏底部「插件」→ 添加插件 → 安装第三方插件，在「包名或地址」填入：
dsh-plugin-agent-notifications
安装完成后刷新页面。同一输入框也支持 GitHub 地址或本地目录。
命令行（Web profile）：
dsh plugin --profile web add dsh-plugin-agent-notifications
或使用 Git 仓库地址：
dsh plugin --profile web add https://github.com/genius-alray/dsh-plugin-agent-notifications
本地开发目录示例：
dsh plugin --profile web add /绝对路径/dsh-plugins/agent-notifications
安装会把 bundle 登记到当前 profile 的 package.json 的 dsh.profile.bundles，并按包内 cordis.patch.yml 增加 agent-notifications 条目，不覆盖官方组件。引擎要求 dsh >= 0.2.1-rc.2（见 package.json）。
典型用法¶
- 按上文任一方式安装并刷新 Harness Web 页面。
- 进入 设置 → 通知，打开「启用通知」，按浏览器提示允许通知权限。
- 按需分别开启「任务完成」「需要操作」「出错」，并为每种情况选提示音（可试听）；若只希望后台标签页才弹窗，打开「仅在页面处于后台时提醒」。
- 点击「发送测试通知」确认权限与样式正常。
- 保持 Harness 标签页存在（可切到后台），在另一标签页工作或等待 Agent 跑完；完成、待审批/提问或会话报错时收到通知与对应音效。
适用场景与注意¶
适合长时间让 Agent 在 Harness 里执行、又不想一直盯着同一标签页的开发者。插件在当前浏览器、当前 DSH Web 会话内运行，权限与偏好都绑定本机浏览器；不能替代手机或关闭浏览器后的推送。
安装第三方插件前，建议自行查看 源码与 LICENSE（MIT），确认与你的工作流和安全策略一致。DSH 生态强调「一切皆插件」；社区目录 SkillHub 插件页 为独立站点，与 DeepSeek / 幻方无官方从属关系。
结尾¶
dsh-plugin-agent-notifications 把 Agent 完成、待你操作和出错三类状态，映射成可配置的浏览器通知与区分明显的合成提示音，并尽量贴合 Harness 官方设置体验。需要进一步了解实现与开发测试命令，见 GitHub：genius-alray/dsh-plugin-agent-notifications。
