SuperAPI AI 工具集

a2ui-protocol

通用与其它

查看项目

更新于 10-16 06:16

技能介绍

用途:在构建 A2UI(Agent to UI)界面时使用,代理以流式 JSON 描述 UI,客户端用自身原生组件渲染,UI 是数据而非代码。与 MCP Apps 的取舍:客户端拥有设计系统、需在非 Web 界面渲染、或不接受执行模型生成标记时选 A2UI;需要聊天宿主内任意 Web 能力时选 MCP Apps。

六种消息(每条约一个 JSON 对象,含 "version":"v1.0" 与唯一 envelope 键,通常以 JSONL 流式传输):createSurface 打开 surface,可带初始组件与 dataModel;updateComponents 增改组件;updateDataModel 用 JSON Pointer 路径写入,upsert 语义;deleteSurface 销毁 surface;callRendererFunction 调用渲染器注册的函数;agentFunctionResponse 返回渲染器到代理调用的结果。surfaceId 在渲染器生命周期内必须唯一,已删除的不能复用。

三套模式:common_types.json 定义 DynamicString、DynamicNumber、ComponentId、ChildList、AccessibilityAttributes、CheckRule;agent_to_renderer.json 为消息信封;catalogs/basic/catalog.json 是基线组件与函数。

组件模型:扁平邻接表而非嵌套树,每项有 id,父组件按 ID 引用子组件。每个 surface 隐式含规范 Surface 容器,其 child 为 root;Surface 保留,目录不可重定义。扁平化支持流式与增量补丁。

目录:catalogId 为唯一字符串(惯例是 URI,不需可解析);每个组件 schema 须固定 "component":{"const":"<Name>"};标识符遵循 UAX #31,@ 前缀保留给系统上下文;allowedParents/allowedChildren 运行时强制执行,违规报 UNALLOWED_PARENT/UNALLOWED_CHILD;目录解析顺序为组件显式 catalogId → createSurface 的 surface 默认 → 报错,无渲染器默认回退;instructions 是给 LLM 的说明文字,用于编码 schema 无法表达的设计意图。

数据模型与绑定:UI 结构与数据严格分离,组件用 JSON Pointer 引用数据;根作用域为绝对路径,模板集合作用域内相对路径解析到当前项。TextField、CheckBox、ChoicePicker 双向绑定:显示绑定路径的值,输入立即更新本地模型,动作派发时才送达代理。updateDataModel 为 upsert,缺失路径创建,null 删除键。createSurface 上设 sendDataModel:true 后,渲染器会把整个数据模型附加到每条回传消息的元数据(昂贵,但可消除代理不知用户输入的问题)。

动作分代理动作(往返代理)与本地动作(渲染器处理,无往返),后者用于导航、展开折叠、复制、格式化等。函数携带 returnType 与 callableFrom 固定可调用方向;basic 目录含 formatString(${...} 插值,${ 转义)、@index(模板渲染中 0 基索引,子作用域专用,不能内部使用绝对路径)、required 与 email 校验谓词。CheckRule 返回 valid/code/message/severity,校验在渲染器运行,无效表单不消耗代理轮次。

流式与渐进渲染:渲染器缓冲组件定义,直到出现 id 为 root 的组件才开始增量渲染,未到达的引用显示占位符,故可先流式输出骨架再填充。传输支持请求/响应(HTTP,callRendererFunction 在响应中发出,渲染器随后 POST functionResponse)与双向(WebSocket/gRPC,用 functionCallId 关联)。

无障碍:AccessibilityAttributes(label、description、live、hidden)须接入框架原生无障碍 API;主题方面 v1.0 移除固定主题属性,样式交由渲染器原生主题系统,目录只用 instructions 引导 LLM,不应在载荷中发送品牌色。

限制:资料未提供具体安装命令、收费或价格、支持平台清单与性能数据,暂未提供。