SuperAPI AI 工具集

notifications

智能体与模型

查看项目

更新于 10-16 08:33

技能介绍

用途:notify() 是框架中“告知用户”的原语。每次调用都会向收件箱写入一行记录(驱动铃铛 UI),并扇出到所有已注册的服务端通道。适合智能体进度里程碑、自动化触发、后台任务完成、严重错误;聊天回复不走此通道,应走会话。

主要能力:内置 notify 工具(severity + title + 可选 body/metadata/channels)和 list-notifications 工具(查看当前用户近期通知)。severity 分 info(通知/进度/确认)、warning(需尽快查看)、critical(需立即处理)。可选参数 --metadataJson 传元数据,--channels 指定通道。

投递机制:notify() 始终写入 notifications 表(除非 channels 明确排除 inbox),再并行扇出到每个注册通道,尽力而为,单个通道失败不影响其他;最后在事件总线上发出 notification.sent,便于自动化链式触发。

内置通道:inbox 通过 INSERT 驱动铃铛 UI,始终启用;webhook 向 NOTIFICATIONS_WEBHOOK_URL 发送 JSON POST,可选 NOTIFICATIONS_WEBHOOK_AUTH,均支持 ${keys.NAME} 与 URL 白名单,密钥在服务端解析,不进入智能体上下文。

自定义通道:用 registerNotificationChannel 注册,提供 name 与 deliver(input, meta);名称唯一,重复注册即替换;deliver() 须尽力而为,抛错仅记录并忽略;禁止在通道内调用 notify() 以防递归。

用法:命令行示例为 notify --severity info --title "Booking confirmed" --body "Jane at 3pm"。HTTP API 挂载在 /_agent-native/notifications/*,均为会话范围:GET /notifications?unread=true&limit=50&before=<iso>、GET /notifications/count、POST /notifications/:id/read、POST /notifications/read-all、DELETE /notifications/:id。UI 可引入 NotificationsBell,传 browserNotifications 可为挂载后到达的通知触发系统弹窗。

限制:webhook 通道需设置环境变量;browserNotifications 需浏览器权限,被拒绝或不支持时静默忽略;通道内不得调用 notify()。其他收费或平台支持情况暂未提供。