SuperAPI AI 工具集

notify

办公与效率

查看项目

更新于 10-26 18:53

技能介绍

用途:notify 用于让后台 worker、watcher 或 fixer 在任务执行中途主动向活跃会话投递事件,实现“完成后通知我”、邮箱事件以及子进程到父进程的信号传递。该技能本身只负责策略;所有机制由 bro CLI 实现。

主要能力:bro comms notify <text> 会把一个事件原子写入会话邮箱,从而投递到每个会话下一次 postTool 探测中,无需在等待循环中消耗 token。邮箱位置在仓库内为 <git-common-dir>/bro/notify/,通过 common git dir 在 linked worktree 间共享;在仓库外为 XDG 状态目录($XDG_STATE_HOME,默认 ~/.local/state)。若要逐字传递可能被当作选项的文本(如 --help),使用 bro comms notify -- <text>。

投递策略:投递是拉取式的,事件不会唤醒休眠会话,只会在会话下一次工具调用时进入上下文;要触达空闲父会话,需要父会话自身有工具调用节奏。应当“写入而非等待”:worker 提前完成、watcher 观察到状态变化、fixer 需要关注时,直接发出事件并继续工作,不要轮询父会话。每个事件应自包含,因为 drain 会把它逐字渲染进上下文。邮箱采用广播方式,每个事件对每个活跃会话恰好送达一次(按会话 .seen 游标),约 1 小时后过期;自己的会话看到自己写入的事件属于正常回显,可作为投递确认。邮箱没有回复通道,如果需要回答,应在事件中写明所需信息。

面向人员的通知:notify.sinks webhook 可把事件送达人员。配置按事件类型路由,支持 topic 或 topic:kind 以及 * 通配;密钥从环境变量读取(urlEnv/tokenEnv/chatIdEnv 指定变量名,值不进入配置),投递不会阻塞代理,有超时限制,失败会静默记录。Slack 发送 {text},telegram 使用 sendMessage,webhook 发送原始事件 JSON。内置事件包括 convoy HUMAN GATE(convoy:gate)、drive 卡住 PR 与静默审查告警(drive:alert)、act 等待结算(act:block / act:result)、wtf/retro 捕获(wtf:note / retro:result)。可用 bro sinks list 查看解析后的 sink、路由模式与密钥环境变量设置状态(不显示值),用 bro sinks test 投递探测事件并报告每个 sink 的成功或错误。

适用场景:后台任务完成通知、监视状态变化、子到父事件信号、需要把关键事件通过 Slack、telegram 或 webhook 通知人员。限制:拉取式投递不唤醒休眠会话;邮箱无回复通道;事件约 1 小时过期;工作区外依赖 XDG 状态目录。