用途:在构建 agent UI 时决定状态应存放在哪一层。核心原则是每个值只属于一个层级,多数 agent UI 的 bug 源于值被放错层。
三层归属 1)权威业务数据:由服务端或外部服务持有,长期存活,例如任务、工单、订单、文档。视图只渲染快照,不拥有数据。写回流程:视图调用 MCP 工具,服务端校验、授权并更新数据,返回更新后的权威快照,视图渲染该快照并保留兼容的展示状态。返回值需带足够 structuredContent,让模型和视图都能理解新状态。乐观更新可用于降低延迟,但须保留更新前快照以便回滚,且在服务端确认前不得把乐观值送入 updateModelContext。 2)临时 UI 状态:由渲染出来的视图实例持有,仅该实例有效,例如选中行、展开面板、排序、草稿筛选。使用框架状态如 useState、store 或普通变量。两种外推机制:ui/update-model-context(app.updateModelContext,传入有界的结构化事实,如 ID、计数、模式,不要传原始第三方文本);setWidgetState(用于 ChatGPT / Copilot 的 remount 存活,每次有意义变更后同步调用,它不是持久存储也不是真相来源)。需要图片进入模型时可用 modelContent、privateContent、imageIds 的结构化形式。 3)跨会话持久状态:存放在自己控制的存储中,绑定已认证用户,跨会话与设备存活,例如保存的筛选、视图模式、工作区偏好。需注意:渲染路径上的低延迟、服务端强制授权(视图不是信任边界)、数据驻留与合规、限流(重试与并发视图实例会放大流量)、存储对象版本化以便迁移。避免用 localStorage 存核心状态;唯一合理用途是按服务端提供的 viewUUID 做机会性恢复,属于缓存而非真相。
Remount 存续:视图可能因显示模式切换、滚动回收、会话重载、携带同一资源的新工具调用而重挂载。防御优先级为:解耦数据工具与渲染工具以从根源减少重挂载;每次有意义变更调用 setWidgetState 并在初始化时恢复;用 onteardown 冲刷(但在 M365 Copilot 不受支持,不能作为唯一路径);viewUUID 加 localStorage 作为昂贵重建的机会性恢复。
AG-UI 共享状态:引入第四类状态——agent 与前端共享的状态。StateSnapshot 为完整状态,连接时及失同步后应用;StateDelta 为 RFC 6902 JSON Patch,按顺序应用;MessagesSnapshot 为完整会话历史。快照与增量都要处理:仅增量会在重连时失效,仅快照会浪费带宽。补丁应用失败时应请求快照,而非猜测。共享状态要与本地 UI 状态分开存储,合并会导致 agent 更新覆盖用户滚动位置。
A2UI 数据模型:数据放在由 JSON Pointer 寻址的显式 surface 数据模型中,与组件结构严格分离。输入组件双向绑定,用户编辑立即更新本地模型,仅在动作派发时到达 agent。updateDataModel 为 upsert,缺失路径会创建,null 表示删除。sendDataModel: true 会把整个模型附加到每条渲染器到 agent 的消息上,代价高,但能消除“agent 不知道用户输入了什么”的失败模式。
常见失败模式与修复:选中状态不断重置,因数据工具携带 resourceUri,应解耦数据与渲染工具;模型不知道用户选中项,因未调用 updateModelContext,应在变更时推送有界事实;切换全屏后状态丢失,因只放在 useState,应加 setWidgetState;偏好不跟随用户,因存在 widget state 或 localStorage,应迁到服务端存储;变更后 UI 陈旧,因渲染了请求而非响应,应渲染返回的快照;模型被告知后来失败的事,因把乐观值送入模型上下文,应先经服务端确认;AG-UI 前端与 agent 漂移,因增量乱序或补丁静默失败,应在失败时请求 StateSnapshot。
相关:openai-apps-sdk(解耦的数据/渲染模式)、ag-ui-protocol(快照与增量语义)、a2ui-protocol(surface 数据模型)、ui-security-sandbox(可安全进入模型上下文的内容)。