智能体提醒 kjx-talesofai/dsh-plugin-agent-alerts

dsh-plugin-agent-alerts

智能体跑完一轮、向你提问、或需要你批准的那一刻，弹出桌面通知并播放提示音 —— 这样你就能去干别的，不用一直盯着窗口。

= 0.2.0-rc.1">

dsh-plugin-agent-alerts — agent 回复完、向你提问、或需要你批准工具时，弹出桌面通知并播放提示音

中文说明（点开） —— 你不用一直盯着窗口，它响了再回来

它是什么：给 DSH 加上提示音 + macOS 桌面通知。三种时刻会响：agent 把一轮做完了、agent 向你提问、工具在等你批准。

为什么做：agent 跑一个 turn 可能要几分钟，这期间正确的做法是去干别的 —— 但"去干别的"需要一个信号把你叫回来，DSH 本身没有。

自带两段哆啦A梦音效，也可以换成你自己的文件（设置里填绝对路径，页面上会显示它有没有读到）。

通知有两种通道，因为可靠性不一样：

| 方式 | 说明 |
| 应用横幅（默认） | Harness 自己的名字和图标，点一下会跳到那个会话 |
| 系统兜底 | 让 macOS 代为通知，署名是「脚本编辑器」，点了没反应 —— 横幅一直不出来时用它 |

三件它故意不做的事：

- 子 agent 的 turn 结束不响。 一次 workflow 一分钟能结束几十个子运行，每个都响就是在训练你忽略它。但子 agent 提问或要审批照常响 —— 那仍然是你的决定。
- 页面刚加载不补报历史。 app 在会话列表加载时会把所有历史空闲会话标成"未读"，把它们当新闻就会每次开 app 响几十下。
- 刚结束又立刻继续的 turn 不响。 goal 的下一轮紧接着上一轮，先说"做完了"是在骗人，所以会等 1.5 秒复查。

注意事项：

- app 必须开着。 两半都跑在 Harness 进程里，退出就没有任何东西能提醒你 —— 这不是常驻后台服务。
- 通知需要 macOS 允许。 如果横幅不出现，先去 系统设置 → 通知 → DeepSeek Harness 看两处：最上面的开关，和下面的提醒样式（不能是「无」）。
- 专注模式会压掉横幅，压不掉声音（声音是插件自己播的）。
- 只在 macOS 上端到端跑过。 Windows / Linux 未测。

怎么装（DSH「添加插件」里填，不需要 npm 账号）：

github:kjx-talesofai/dsh-plugin-agent-alerts#v0.3.4

装完重启桌面端（host 半边只在启动时加载）。

卸载：DSH「插件」列表里卸载 → 重启。它只在自己的 config 块里留了一份设置，没有别的痕迹。

为什么做

智能体跑一轮要几分钟。理性的做法是离开 —— 而离开的全部意义在于，你需要一个信号把你叫回来。DSH 没有这个信号。

两种提示而不是一种，因为它们的失效方式不同：窗口被三个别的窗口挡住时，声音能传到你耳朵里；横幅则告诉你哪个会话，点一下就能打开。

什么时候提醒

| 时刻 | 声音 | 通知 |
| 一轮跑完 | duo_finish.mp3 | 会话标题 |
| 智能体向你提问 | duo_question.mp3 | 提问内容 |
| 工具需要你批准 | duo_question.mp3 | 正在请求的工具 |
| 计划等待审核 | duo_question.mp3 | 计划提示词 |

点击横幅，把窗口带到前台，并打开它对应的会话。设置页会说明这次点击是否已接通，这样静默失败就能看见，而不是悄无声息。系统回退不可点击 —— display notification 不带任何动作 —— 这也是它默认关闭的原因之一。

有三件事它刻意不做：

- 它不播报子代理的回合。 一个工作流一分钟内可能跑完几十次子代理运行；每次都播报，只会让你学会忽略提醒。子代理提出的问题和审批仍然会响，因为这些仍然要你决定。
- 页面加载时它不重放历史。 应用在加载列表时，会把所有历史上空闲的会话标记为未读；把这些当成新消息，每次启动都会为每个旧会话触发一次提醒。
- 它不播报立刻接着开始的回合。 目标轮次会结束当前回合，片刻后开启下一个回合，所以已结束的回合会先挂起 1.5 秒，如果会话又跑起来就丢弃 —— 或者如果回合结束的原因是智能体在等你，也丢弃。

安装

用 DSH 自带的 Add plugin 对话框。不需要 npm 账号，也不需要发布。

| 字段 | 值 |
| GitHub | github:kjx-talesofai/dsh-plugin-agent-alerts#v0.3.4 |
| 本地目录 | 绝对路径，例如 /path/to/dsh-plugin-agent-alerts |

之后重启桌面应用：Host 部分只在启动时加载。浏览器部分随页面重新加载。

如果 Add plugin 报 connection to github.com timed out after 5000ms，那是管理器自己的连通性预检（一次 5 秒的 git 检查），不是下载 —— 同一个 tarball 不到一秒就能拉下来，直接 https://codeload.github.com/... 的 GET 请求能成功，而走 HTTPS 的 git ls-remote 会卡住。重试一次，或者在你的配置档目录里用 pnpm add 安装同一个 spec。

这个插件没有发布到 npm，npm install 不是安装方式。

设置

Settings → Plugins → Agent Alerts → 该行的 configure 控件。 每个开关都立即生效，不需要重启。

| 设置 | 默认值 | 说明 |
| 回合结束 | 开 | |
| 智能体提问 | 开 | 也覆盖等待审核的计划。 |
| 工具需要审批 | 开 | |
| 播放声音 | 开 | |
| 通知方式 | 应用横幅 | Off、App banner 或 System fallback |
| 窗口聚焦时跳过横幅 | 关 | 声音照常播放。 |
| 音量 | 80% | |
| 回合结束的声音 | 空 | 绝对路径。留空则用内置声音。 |
| 提问或审批的声音 | 空 | 绝对路径。留空则用内置声音。 |

通知设置旁边有 Send a test 按钮，点一下立刻触发一次提醒，这样找到你机器上能用的通知方式只需十秒实验，而不是靠猜。
设置放在配置档的 cordis.patch.yml 里，和其他 Harness 偏好放在一起，也可以直接在那里改：

- id: agent-alerts
name: dsh-plugin-agent-alerts
config:
turnEndSound: /Users/you/Sounds/done.mp3
quietWhenFocused: false

覆盖不到的地方

- 没有音效包，也没有文件选择器。 自定义音效要你手填绝对路径。
- 应用退出后什么都不保留。 没有守护进程，没有后台进程。
- 没有按会话或按工作区的规则。 开关是全局的。
- 系统兜底只支持 macOS。 在其他平台上，这条路由返回 501，而不是静默。

兼容性

在 macOS（Apple Silicon）上，用真实配置档对照 DSH 0.2.1-rc.2 重新验证过：浏览器端能挂载，设置页落在本插件那一行，下面每一条契约仍然成立。手工端到端验证（声音、通知、测试按钮）是在 0.2.0-rc.2 上做的 —— docs/plan.md 记录了那次测量错在哪。

| 契约 | 来源 |
| ctx.uiSession.sessionStatus —— 一张可观察的映射，含 { running, pendingInteraction, completionUnread } | dsh-client-ui-session |
| ctx.configForms，以及 plugins.row.config 中键为 <package>#<rowId> 的座位 | dsh-client-ui-settings、dsh-client-ui-plugin-manager |
| 一条 webServer 路由，可从 dsh-app://app 页面访问，位于 connection.admit 之后 | dsh-host-webserver、dsh-api-remotes |
| ctx.remote.$on('user-questions/request')，作为瀑布流 | dsh-api-gateway |

通知这条路径最脆弱，因为页面无法观察操作系统到底显示了什么：Notification.permission 报的 granted 来自 Electron 自己的闸门，不是 macOS 的。所以这里有两套传输通道，外加一个测试按钮。

开发

npm test # 34 tests, no install step required

这里刻意没有构建步骤：client.js 就是发布出去的浏览器包，Host 端只有一个 index.js。

测试套件在 node:vm 里把浏览器端当脚本执行，用一个小型钩子运行时驱动真实组件，并运行 Host 端自己的主体、把它的导入打桩 —— 所以它从不解析包声明的那唯一一个依赖，裸检出就够跑。

| 路径 | 是否随包发布 | 用途 |
| client.js | ✓ | 浏览器端 —— 触发器、声音、通知、设置页 |
| index.js | ✓ | Host 端 —— Config schema、声音路由、系统通知兜底 |
| cordis.patch.yml | ✓ | 挂载本包的 bundle 行 |
| locale/*.json | ✓ | 插件管理器的展示元数据（en / zh） |
| assets/ | ✓ | 两个内置音效和图标 |
| tests/plugin.test.mjs | ✗ | 行为测试套件 |
| docs/plan.md | ✗ | 设计记录：验证了什么，又错在哪 |
| probe/ | ✗ | 阶段 0 诊断，确立了上面这些机制 |
用 link: 安装比从 registry 安装多一步：包留在配置档之外，所以 Host 那一半的依赖必须通过插件目录能访问到，否则入口导入会失败，报 Cannot find package '@deepseek-ai/schemastery'。把它软链到 node_modules/；具体是哪两个，docs/plan.md 里写得很清楚。

卸载

从 DSH 的插件列表里移除 dsh-plugin-agent-alerts，然后重启。它不写浏览器存储，除了自己可选的 config 块之外也不写任何配置档状态。

许可证

MIT © 2026 Jiaxin Kou

Built by hypersampling · GitHub