DSH 插件(六):什么时候该弹窗,什么时候该闭嘴
桌面通知最常见的失败不是“没弹”,而是“弹太多”。
Agent 调用一次网络工具失败,SDK 内部重试三次。如果每次失败都弹窗,你会收到三条“任务失败”,然后第四条“任务完成”。从此你关掉通知,这个功能等于不存在。
desktop-notice 的大部分代码不是在弹窗,而是在决定不弹。internet-meme 则相反:它只在浏览器里加一层字幕,从不打断你。这篇讲这两个插件怎么划定“打扰的边界”。
一、通知只认终态
DSH 的事件词汇表里,和“出错”有关的有两个:
| 事件 | 模式 | 能不能当通知源 |
|---|---|---|
agent/request-error | waterfall | 不能:带 retryPolicy,瞬时错误会先重试 |
turn/end | emit | 能:一轮的终态,只发一次 |
turn/end 的 reason 是一个可穷举的枚举:
completed | aborted | blocked | error | max-tokens | interrupted映射到通知只有三类:
completed/max-tokens→ 完成;error→ 失败;blocked→ 等你处理。
interrupted 是崩溃后的孤儿回填,不通知;aborted 是用户主动取消,也不值得再弹一次。
“等你处理”不能只靠 blocked。审批请求走的是 approval/asked,Agent 提问走的是 user-questions/request,这两个事件发生时 turn/end 还没到。所以 waiting 是一个组合判断:审批或提问事件先到,blocked 作为补充观察。
踩坑:错误事件会制造通知风暴
第一版把 agent/request-error 当失败源,测试时一次超时重试弹了四条通知。它不只是重复,还会在最终成功之后留下一条“失败”,让人以为任务真的挂了。改成只监听 turn/end 后,通知数量立刻正常。
二、管线的顺序就是优先级
通知管线的处理顺序写死在 pipeline.mjs 顶部:
总开关 → 事件开关 → 前台 → 全屏 → 勿扰时段 → 合并节流 → 渐进提醒/心跳 → 渲染分发这个顺序不是随便排的。越靠前的开关越“硬”:总开关关了,后面全部不执行;事件开关关了,这个类型连合并都不进。
waiting 是唯一的例外:它默认豁免前台、全屏和勿扰。理由很直接——Agent 停在那里等你的输入,每一秒都在烧你的时间。你全屏看电影时,也应该知道它卡住了。
被抑制的通知不会消失,而是进一个上限 100 条的汇总队列。用户离开勿扰或退出全屏后,能看到“刚才有 3 条通知被静音”,而不是以为什么都没发生。
合并与重发
- 同一类型的通知在 10 秒窗口内合并成一条,避免连续工具失败刷屏;
- waiting 如果 N 分钟没处理,重发一次强提醒,只重发一次;
- 长任务在开始 T 分钟后发一次心跳,此后每 N 分钟最多一次。
这三个定时器都按 sessionKey 存,会话结束就清掉。否则一个已经结束的会话还能在半小时后弹“仍在运行”。
三、Windows Toast:子进程是一等风险
Windows 没有可靠的 Node 原生 Toast API,插件走 PowerShell 调 WinRT。这意味着每次通知都要起一个子进程,必须按“不可信外部进程”来防:
| 风险 | 处理 |
|---|---|
| 脚本注入 | 通知内容写临时 JSON 文件,不作为命令行参数拼接 |
| 进程挂死 | 5 秒超时,超时 kill() |
| 频繁失败 | 连续 3 次失败熔断,后续通知直接走 noop |
| 同会话刷屏 | 每个会话 1 秒内只允许一次 Toast |
| 通知来源显示为 PowerShell | 首次使用时注册自有 AUMID,失败回退 |
AUMID 那段是最容易被忽略的:不注册,通知横幅的来源显示“Windows PowerShell”,用户会以为系统在报警。注册需要在开始菜单建快捷方式,属于有副作用的操作,所以只做一次,并且幂等。
前台检测也是 PowerShell:读当前前台窗口进程名,和配置的匹配列表比对。它失败时返回“未知”,通知照常发——这是有意的失败开放。少弹一条的代价,比漏掉一条“任务失败”更大。
四、另一条路:只加氛围,不加打扰
internet-meme 做的是完全相反的事:
- 只加载浏览器端 bundle,不改 Node 侧行为;
- 监听 5 类生命周期事件,在右侧显示向上漂移的短句;
- 不读取回答正文、推理内容、工具参数和工具结果;
- 提示音本地合成,默认关闭,页面失焦或系统“减少动态效果”时不播;
- 设置页的“预览弹幕”走 Host → SSE → 浏览器的真实链路,不是前端假动画。
它的 bridge.ts 只有 382 行,大部分是 DOM 和动画。技术上不难,难的是克制:不碰会话、不上传文本、不阻塞渲染、不因为插件出错影响主界面。
为什么预览要走 SSE
前端直接 setTimeout 造几个假弹幕更简单,但那样预览成功不代表真实链路能用。走一遍 Host 到浏览器的 SSE,能在设置页就暴露“事件没订阅上”“bundle 没加载”这类问题,而不是等用户用了半天才发现没反应。
五、打扰预算
把两个插件放在一起,能得到一张简单的判断表:
| 场景 | 该不该打扰 | 选择 |
|---|---|---|
| 一轮完成 | 该 | 桌面通知,可合并 |
| 一轮失败 | 该,但只一次 | 只认 turn/end(error) |
| 等你审批 / 回答 | 最该 | 豁免勿扰,可重发一次 |
| 长任务仍在跑 | 看情况 | 心跳,低频 |
| 工具单次失败 | 不该 | 不通知 |
| 用户主动取消 | 不该 | 不通知 |
| Agent 正在思考 | 不该 | 只做界面氛围 |
这张表的每一行都对应代码里的一个分支。通知产品的质量,基本等于这张表划得够不够细。
六、边界
desktop-notice 只知道“一轮结束了”,不知道这一轮对你重不重要。它没有优先级、没有按项目静音、没有“只在某个时间段提醒”的复杂规则。
internet-meme 只是氛围层,不提供任何信息增量。它的文案是预设的,不会根据任务内容生成——一旦生成,就会碰会话内容,违背它的隐私边界。
下一篇讲一个更“不务正业”的插件:飞花令。它证明插件不一定都要提升效率,也可以只是让等待模型回复的那几十秒不那么无聊。