Agent Zero WebUI 通知组件架构解析toast、模态框与通知存储的完整实现指南【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zeroAgent Zero 的 WebUI 前端将通知系统拆分为notification-store.js、notification-toast-stack.html、notification-modal.html与notification-icons.html四个模块分别负责通知状态管理、toast 渲染、详情模态框与图标入口。本文以 webui/components/notifications/AGENTS.md 为骨架结合前端 store 实现、后端NotificationManager与notification_createAPI 源码系统讲解这套通知体系的职责边界、数据结构、双端同步机制与前端调用方式帮助你在 WebUI 开发或插件扩展中正确使用通知能力。通知组件模块的职责划分根据 AGENTS.md 的 Ownership 约定通知系统由四个文件组成职责互不重叠文件职责notification-store.js拥有通知状态与全部公开辅助动作创建、标记已读、toast 栈管理notification-toast-stack.html负责 toast 渲染含样式、动画、交互notification-modal.html负责通知详情模态框 UInotification-icons.html负责共享的通知图标入口铃铛按钮与未读角标这种单一 store 多视图的拆分方式使所有通知逻辑收敛在 store 中视图组件只做声明式渲染。store 通过 Alpine 的createStore(notificationStore, model)注册为全局$store.notificationStore见 notification-store.js三个视图文件在script typemodule中直接导入同一 store 实例保证多视图状态一致。通知数据模型类型、优先级与字段通知类型NotificationType前端与后端helpers/notification.py使用完全一致的枚举定义info普通信息success成功反馈warning警告error错误progress进度图标带旋转动画见 notification-modal.html类型通过getNotificationClass(type)映射为notification-info/success/warning/error/progressCSS 类每条 toast 左侧使用 4px 彩色边框区分notification-toast-stack.htmlinfo 蓝#2196F3、success 绿#4CAF50、warning 橙#FF9800、error 红#F44336、progress 紫#9C27B0。优先级NotificationPriorityexport const NotificationPriority { NORMAL: 10, HIGH: 20, }; export const defaultPriority NotificationPriority.NORMAL;优先级影响两个行为未读角标只统计 HIGH 优先级unreadPrioCount以及 toast 关闭后的已读落库策略见下文toast 生命周期。NotificationItem 字段后端 NotificationItem 数据类定义了完整字段通过output()序列化后经轮询下发给前端字段类型说明idstrUUID用于去重与已读同步typestr五种类型之一priorityint10 或 20title/messagestr标题与正文message 支持 HTMLdetailstr可展开的 HTML 详情内容timestampdatetime本地化时间display_timeint展示时长秒默认 30表示常驻readbool已读标记groupstr分组标识同组新 toast 会顶掉旧 toast前端在addOrUpdateNotification中按id去重已存在则更新否则unshift插入头部并截断到maxNotifications 100条notification-store.js后端NotificationManager._enforce_limit同样维护 100 条上限并重排编号helpers/notification.py。双端同步链路从后端创建到前端渲染通知的完整生命周期是一条后端产生 → 轮询同步 → store 加工 → 视图渲染的闭环后端创建业务方调用NotificationManager.send_notification(type, priority, message, title, detail, display_time, group, id)helpers/notification.py该方法会代理到当前 Agent 上下文的AgentContext.get_notification_manager()并追加到通知列表同时通过mark_dirty_all触发状态监控脏标记。API 暴露api/notification_create.py 提供notification_create端点负责参数校验message必填、display_time负值或非法回退为 3、非法类型返回错误校验通过后调用send_notification并返回notification_id。前端轮询webui/index.js 轮询时携带notifications_from: notificationStore.lastNotificationVersion || 0增量拉取api/poll.py 对应读取notifications_from参数。store 合并updateFromPoll(pollData)首先比对notifications_guid——若 GUID 变化后端重启则清空本地列表与 toast 栈notification-store.js随后遍历新通知判断isNew与shouldRetoast内容或时间戳变化且未读时重新弹 toast再调用addOrUpdateNotification并更新lastNotificationVersion。渲染toast 栈与模态框视图通过 Alpinex-for消费 store 数据。Toast 栈渲染与交互细节栈结构与布局toast 栈使用column-reverse从底部向上堆叠容器z-index: 8900右下角锚定、最大宽度 400pxpointer-events: none而每个toast-item重新开启事件notification-toast-stack.html。该层级保证 toast 栈位于普通与 legacy 模态框之上、确认对话框之下——这正是 AGENTS.md 中 Local Contracts 声明的层级契约。移动端max-width: 768px下容器铺满左右 10px 并取消宽度限制。生命周期与计时器addToToastStack为每条 toast 生成toast-${notification.id}的 toastId记录addedAt并设置自动消失定时器getToastDisplayTime(toast)读取display_time非有限数值回退为 3 秒isPersistentToast(toast)display_time 0视为常驻 toast不启动自动移除clearToastTimer/restartToastTimer配合mouseenter/mouseleave实现悬停暂停计时notification-toast-stack.html栈上限maxToasts 5超出时移除最旧一条shift。分组去重如果通知携带group字段入栈前会先移除同组旧 toast实现同组通知只显示最新一条的语义addFrontendToastOnly中也有同样处理。交互行为点击 toasthandleToastClick先判断点击目标是否落在button, a, input, select, textarea, summary, label, [rolebutton], [data-toast-interactive]等交互元素上若是则仅标记该条已读并返回否则打开详情模态框模态框打开会清空 toast 栈并markAllAsRead手动关闭dismissToast以removedByUser true调用removeFromToastStack关闭后已读落库afterToastRemoved规定用户手动关闭或普通优先级priority NORMAL超时消失都会调用markAsRead同步后端HIGH 优先级超时消失则不标记已读确保重要通知保留在列表中。已读状态与显示策略updateUnreadCount分别统计全部未读数unreadCount与高优先级未读数unreadPrioCountgetDisplayNotifications显示所有未读 最近 5 分钟内的已读避免模态框过空formatTimestamp提供 Just now / Xm ago / Xh ago / Xd ago 的相对时间显示。模态框与图标入口详情模态框notification-modal.html 通过openModal(notifications/notification-modal.html)打开包含头部操作Clear All按钮调用clearAll()清空本地列表与 toast 栈并同步调用后端notifications_clear见 notification-store.js列表为空时自动禁用通知列表每条按getNotificationItemClass呈现 unread/read 状态unread 带主色左边框点击条目即markAsRead可展开详情存在detail字段时显示 ▶ Show Details / ▼ Hide Details 切换按钮详情内容支持 HTML 并带淡入淡出动画空状态无通知时显示铃铛图标与 No notifications to display。图标入口notification-icons.html 渲染铃铛按钮存在高优先级未读时显示notification-badge角标数字为unreadPrioCount并通过has-unread/has-notifications类驱动样式点击调用openModal()。openModal在打开模态框时清空 toast 栈关闭时自动markAllAsReadnotification-store.js。前端开发者 API如何主动弹出通知store 导出两类便捷 API供核心界面与插件使用后端优先的frontend*系列推荐addFrontendToast采用后端优先、前端兜底策略notification-store.js连接正常时先调用notification_create后端 API通知经由轮询回流保证多标签页/刷新后状态一致后端不可用isConnected()为 false 或请求失败时降级为纯前端 toast并打印日志说明降级原因。await store.frontendSuccess(备份已完成, Backup); await store.frontendError(模型连接失败请检查网络, Connection Error, 8); await store.frontendWarning(磁盘空间不足, Warning); await store.frontendInfo(任务已进入队列, Info); await store.frontendProgress(正在生成报告中, Progress);各便捷方法签名统一为(message, title, display_time, group, priority, frontendOnly)默认display_time为 3 秒error 为 8 秒支持传入group与priority。对象参数形式frontendNotification({ type, message, title, displayTime, group, priority, frontendOnly })提供 JSDoc 标注的对象参数形式适合插件代码可读性要求较高的场景。全局兼容导出为兼容旧脚本store 将toastFrontendInfo/Success/Warning/Error/Progress同时挂载到globalThisnotification-store.js可直接在浏览器控制台或旧代码中调用。纯前端直发addFrontendToastOnly(type, message, title, display_time, group, priority)生成frontend-${timestamp}-${random}格式的本地 ID只进入前端 toast 栈、不写后端适合纯 UI 反馈场景。核心使用契约Local ContractsAGENTS.md 明确了以下必须遵守的契约这些约束在源码中均有对应实现面向用户的反馈统一走通知系统成功、警告、信息、错误四类反馈都应通过frontend*/createNotification发出而非自定义临时 UI。webui/index.js 中的 toast 封装即统一将 timeout 从毫秒换算为秒后路由到对应frontend*方法。公开辅助方法名保持稳定核心代码与插件均依赖frontendInfo/Success/Warning/Error/Progress、addFrontendToast、markAsRead、markAllAsRead、openModal等公开方法修改需向后兼容。层级顺序固定toast 栈z-index: 8900必须位于普通/legacy 模态框之上、确认对话框之下。刷新前持久化已读状态dismissToastAndReload先调用notifications_mark_read将对应通知标记已读成功后才window.location.reload()避免刷新后通知复活notification-store.js。禁止泄露敏感信息通知文本中不得包含密钥、原始 auth 载荷等敏感内容这是面向用户展示内容的硬性安全约束。验证方法AGENTS.md 的 Verification 章节要求对以下行为做冒烟测试与源码中的可观察行为一一对应toast 显示未读通知到达时出现在右下角栈中display_time到期自动消失display_time 0的常驻 toast 不消失toast 关闭手动点关闭按钮立即移除并同步已读普通优先级超时消失也标记已读模态框详情点击 toast 打开模态框detail 字段可展开/收起Clear All 清空全部严重程度样式五种类型各自的边框色、图标info/check_circle/warning/error/hourglass_empty与 unread/read 视觉状态正确。小结Agent Zero 的通知组件是一个单一 store 多视图的典型前端模块store 承担全部状态与动作toast、模态框、图标三个视图各司其职后端NotificationManager与notification_createAPI 提供持久化与跨端同步轮询增量拉取保证多标签页一致。理解其数据模型类型、优先级、group、display_time与公开 API 契约后无论是为 WebUI 添加新的反馈入口还是开发插件调用通知能力都能准确接入而不破坏现有层级与已读语义。【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考