Agent Zero 通知系统完全指南后端 Python 与前端 Alpine.js 的 Toast 通知与持久化实战【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zeroAgent Zero 内置了一套前后端一体化的通知系统后端 Python 代码可随时推送 info / success / warning / error / progress 五类通知前端通过 Alpine.js 的notificationStore以 toast 形式展示在屏幕右下角并通过铃铛图标进入完整历史弹窗。本指南基于仓库文档 docs/developer/notifications.md 并对照底层源码系统讲解从后端调用、前端接入、分组替换到前后端自动同步的完整用法读完后你可以在插件、调度任务、Web UI 组件中自由接入通知能力。一、通知系统的整体架构通知模块由三部分组成它们协作完成产生 → 传输 → 展示 → 持久化的完整链路后端管理器helpers/notification.py 中的NotificationManager持有所有通知的内存状态列表、增量更新游标、GUID并以线程安全threading.RLock方式提供增删改查每次变更还会调用mark_dirty_all通知状态监控state monitor同步持久化状态。REST API如 api/notification_create.py、api/notifications_mark_read.py、api/notifications_clear.py供前端创建、标记已读、清空通知前端通过轮询polling增量拉取新通知。前端 Storewebui/components/notifications/notification-store.js 中的notificationStore负责 toast 栈管理、未读计数、历史弹窗以及先试后端、失败回退前端本地的双通道同步逻辑。后端的数据模型定义在 helpers/notification.pyclass NotificationType(Enum): INFO info SUCCESS success WARNING warning ERROR error PROGRESS progress class NotificationPriority(Enum): NORMAL 10 HIGH 20NotificationItemhelpers/notification.py是单个通知的数据结构包含no序号、idUUID、type、priority、title、message、detail可展开的 HTML、timestamp、display_time默认 3 秒、read、group等字段。二、后端用法Python 中的 AgentNotification在任何 Python 代码中包括插件、工具、调度任务、API 处理器都可以直接使用AgentNotification便捷方法参考 docs/developer/notifications.mdfrom helpers.notification import AgentNotification # 基础通知 AgentNotification.info(Operation completed) AgentNotification.success(File saved successfully, File Manager) AgentNotification.warning(High CPU usage detected, System Monitor) AgentNotification.error(Connection failed, Network Error) AgentNotification.progress(Processing files..., Task Progress) # 带详情与自定义展示时长 AgentNotification.info( messageSystem backup completed, titleBackup Manager, detailpBackup size: strong2.4 GB/strong/p, display_time8 # 秒 ) # 分组通知同组新通知会替换旧通知 AgentNotification.progress(Download: 25%, File Download, groupdownload-status) AgentNotification.progress(Download: 75%, File Download, groupdownload-status) # 替换上一条 AgentNotification.progress(Download: Complete!, File Download, groupdownload-status) # 再次替换底层调用链AgentNotification便捷方法最终走的是NotificationManager.send_notification→AgentContext.get_notification_manager().add_notification这条链路见 helpers/notification.py。add_notificationhelpers/notification.py的核心逻辑是若传入id且该 ID 已存在则原地更新既有通知类型、优先级、标题、消息、详情、时间戳、展示时长、分组一并刷新并重置为未读同时把序号追加到updates增量游标若不存在则创建新的NotificationItem并追加然后通过_enforce_limit裁剪超限的旧通知默认上限 100 条见 helpers/notification.py每次变更都会调用mark_dirty_all触发状态监控持久化保证 Web UI 快照不丢通知。仓库内部使用该 API 的实例可参考 helpers/settings.py设置变更提示与 helpers/plugins.py插件事件通知可作为在框架代码中接入通知的真实范本。后端 REST API后端同时暴露了notification_create接口api/notification_create.py字段与AgentNotification参数一一对应并带有输入校验type可选默认info非法的类型字符串会返回Invalid notification type错误message必填为空时返回Message is requiredpriority默认NORMAL10可传HIGH20title、detail可选detail支持 HTML 用于可展开详情display_time默认 3负数或非数字会被重置为 3group可选分组标识id可选传入后用于更新既有通知而非新建。前端正是通过POST /notification_create走这条路径创建通知见下文。三、前端用法notificationStore前端在 Alpine.js 组件中通过$store.notificationStore访问通知 Store参考 docs/developer/notifications.md// 基础通知 $store.notificationStore.info(User logged in) $store.notificationStore.success(Settings saved, Configuration) $store.notificationStore.warning(Session expiring soon) $store.notificationStore.error(Failed to load data) // 带分组 $store.notificationStore.info(Connecting..., Status, , 3, connection) $store.notificationStore.success(Connected!, Status, , 3, connection) // 替换上一条各便捷方法的完整签名在 webui/components/notifications/notification-store.jsasync info(message, title , detail , display_time 3, group , priority defaultPriority) async success(message, title , detail , display_time 3, group , priority defaultPriority) async warning(message, title , detail , display_time 3, group , priority defaultPriority) async error(message, title , detail , display_time 3, group , priority defaultPriority) async progress(message, title , detail , display_time 3, group , priority defaultPriority)这些方法统一委托给createNotificationwebui/components/notifications/notification-store.js向notification_create接口发送 JSON 请求并返回notification_id前端侧同样定义了NotificationType与NotificationPriorityNORMAL10、HIGH20两套常量与后端保持一致webui/components/notifications/notification-store.js。HTML 中直接使用在模板中绑定点击事件即可参考 docs/developer/notifications.mdbutton click$store.notificationStore.success(Task completed!) Complete Task /button button click$store.notificationStore.warning(Progress: 50%, Upload, , 5, upload-progress) Update Progress /button四、前端通知与后端同步新特性核心机制见 docs/developer/notifications.md后端已连接通知先发到后端随后通过轮询回到前端进入持久化历史跨会话可查后端断开自动降级为纯前端 toast临时展示不进历史自动回退后端不可用时无缝降级用户无感知。实现上由addFrontendToast承担webui/components/notifications/notification-store.js先调用isConnected()判断轮询连接状态webui/components/notifications/notification-store.js连接正常则尝试createNotification走后端失败或断开则落到addFrontendToastOnlywebui/components/notifications/notification-store.js后者生成frontend-时间戳-随机串形式的本地 ID直接加入 toast 栈。前端便捷方法默认标题与展示时长各不同$store.notificationStore.frontendError(Database timeout, Connection Error) $store.notificationStore.frontendWarning(High memory usage, Performance) $store.notificationStore.frontendInfo(Cache cleared, System) $store.notificationStore.frontendSuccess(Saved, Success) $store.notificationStore.frontendProgress(Uploading..., Progress)签名与默认值webui/components/notifications/notification-store.js方法默认 title默认 display_timefrontendErrorConnection Error8frontendWarningWarning5frontendInfo/frontendSuccess/frontendProgress对应类型名3此外还提供了frontendNotification({ type, message, title, displayTime, group, priority, frontendOnly })对象参数形式webui/components/notifications/notification-store.js适合参数较多或需要动态拼装场景。全局函数为了方便非 Alpine 环境普通脚本、控制台调用Store 在导出时把便捷方法绑定为全局函数并兼容挂到globalThiswebui/components/notifications/notification-store.jstoastFrontendError(Server unreachable, Connection Error) toastFrontendWarning(Slow connection detected) toastFrontendInfo(Reconnected successfully) toastFrontendSuccess(Task finished) toastFrontendProgress(Working...)这类函数同样遵循先试后端、失败回退前端的策略。五、通知分组与替换分组group确保 toast 栈中同一组只保留最新一条参考 docs/developer/notifications.md# 进度更新——每条新通知替换上一条 AgentNotification.info(Starting backup..., groupbackup-status) AgentNotification.progress(Backup: 30%, groupbackup-status) # 替换 AgentNotification.progress(Backup: 80%, groupbackup-status) # 替换 AgentNotification.success(Backup complete!, groupbackup-status) # 替换 # 连接状态——只展示当前状态 AgentNotification.warning(Disconnected, groupnetwork) AgentNotification.info(Reconnecting..., groupnetwork) # 替换 AgentNotification.success(Connected, groupnetwork) # 替换分组的替换行为在前端由addToToastStack实现webui/components/notifications/notification-store.js当新 toast 携带非空group时先移除 toast 栈中同组的旧 toast 再加入新 toast纯前端路径addFrontendToastOnly也有同样的同组清理逻辑。典型使用场景是长任务进度条与连接状态指示避免连续进度更新刷爆 toast 区域。六、参数与通知类型速查所有通知方法统一支持以下参数docs/developer/notifications.md参数必填说明message是通知主体文本title否通知标题detail否可展开详情的 HTML 内容display_time否toast 展示时长秒默认 3group否分组标识同组通知触发替换五种类型及语义docs/developer/notifications.md类型语义前端配色左侧边框info一般信息蓝#2196F3success操作成功绿#4CAF50warning重要告警橙#FF9800error错误条件红#F44336progress进行中的操作紫#9C27B0类型对应的图标与 CSS 类映射见 webui/components/notifications/notification-store.jstoast 样式含每种类型的边框色、动画、移动端适配与prefers-reduced-motion无障碍处理在 webui/components/notifications/notification-toast-stack.html 中定义。七、行为细节与边界综合文档与源码通知系统的完整行为契约如下参考 docs/developer/notifications.mdToast 展示位置右下角 toast 栈容器position: absolute锚定在零高度容器底部flex-direction: column-reverse向上堆叠最大宽度 400pxwebui/components/notifications/notification-toast-stack.html。持久化历史所有通知含同步到后端的前端通知都会进入通知历史点击铃铛图标打开历史弹窗webui/components/notifications/notification-modal.html弹窗打开时通过openModal清空 toast 栈并标记全部已读webui/components/notifications/notification-store.js。自动消失toast 在display_time秒后自动移除鼠标悬停会暂停计时mouseenter清除定时器、mouseleave重启见 webui/components/notifications/notification-store.js 与 webui/components/notifications/notification-toast-stack.html。持久 toastdisplay_time 0的通知不会被自动移除isPersistentToast需用户手动关闭。栈容量上限toast 栈最多同时展示 5 条maxToasts 5超出时移除最旧的前端历史列表最多保留 100 条maxNotifications 100webui/components/notifications/notification-store.js与后端NotificationManager的max_notifications 100默认值一致。已读同步toast 被用户关闭或普通优先级 toast 超时消失后会调用notifications_mark_read同步已读状态高优先级priority NORMALtoast 超时不会自动标记已读确保重要告警保留在未读区webui/components/notifications/notification-store.js。对应后端 API 支持按 ID 列表标记或一键全标mark_all见 api/notifications_mark_read.py。系统重启处理后端通知管理器持有 GUID每次clear_all或进程重启会更换helpers/notification.py前端轮询时若发现 GUID 变化会重置通知列表与 toast 栈避免展示过期状态webui/components/notifications/notification-store.js。增量拉取后端维护updates增量游标output_with_state一次返回(本次新增/变更的通知列表, guid, 游标长度)配合锁机制保证轮询不丢通知helpers/notification.py。历史展示策略getDisplayNotifications默认展示全部未读通知 最近 5 分钟内的已读通知兼顾信息量与界面整洁webui/components/notifications/notification-store.js。八、与定时任务的组合实践通知与调度任务Scheduled Tasks是官方推荐的组合用法——任务在后台周期性运行结果通过通知推送到 UI无需人盯着任务列表。文档提示可参考 Usage 指南的 Tasks And Scheduling 章节 获取完整的任务创建与调度模式。典型做法在任务的执行代码中用AgentNotification.success(...)输出任务完成摘要、用AgentNotification.warning(...)标记需要人工关注的异常配合group保证同一任务的多次运行只保留最新结果任务还可以绑定 Project从而继承项目指令、变量、密钥与记忆见 docs/guides/usage.md使通知内容更贴合上下文。九、最佳实践小结短文本、可读标题message是正文、title是摘要二者分工detail可承载结构化 HTML 详情如备份体积、错误堆栈避免 toast 过长。善用分组防刷屏凡是会高频更新的状态下载进度、连接状态、批处理步骤一律传group让 toast 栈只保留最新状态。重要告警用高优先级priorityNotificationPriority.HIGH数值 20的通知不会随超时自动标记已读适合宕机、失败、安全事件等必须人工处理的场景。前端通知默认走后端优先使用frontendError/frontendWarning/frontendInfo等自动同步方法只有明确纯临时提示、无需历史时才用frontendOnlytrue强制本地。校验与容错后端对message必填、display_time数值、type合法性均有校验api/notification_create.py接入时注意传参规范前端createNotification失败时会打印错误并返回null调用方应做好空值处理。相关源码与测试可进一步阅读helpers/notification.py、helpers/notification.py.dox.md模块职责契约、webui/components/notifications/notification-store.js、api/notification_create.py以及测试目录下的通知相关回归用例如 tests/test_download_toast_regressions.py、tests/test_multi_tab_isolation.py。【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考