A2UI v0.8 JSON Schema 全解析：消息协议、组件目录与 LLM 友好的解析式 Schema

A2UI v0.8 JSON Schema 全解析消息协议、组件目录与 LLM 友好的解析式 Schema【免费下载链接】a2ui项目地址: https://gitcode.com/GitHub_Trending/a2/a2uiA2UIAgent to UIv0.8 协议的核心资产是一组形式化的 JSON Schema 文件它们共同定义了服务端如何向客户端推送 UI与客户端如何向服务端回传事件的完整契约。本指南以 specification/v0_8/json/README.md 为骨架逐一拆解这六类 Schema 的字段语义、设计动机与解析方式并结合仓库中的渲染器源码与示例消息帮助你掌握如何基于这些 Schema 构建 Agent UI、自定义组件目录或开发全新的渲染器实现。一、Schema 家族总览specification/v0_8/json/目录存放的是 A2UI v0.8 协议的正式 JSON Schema 定义整个目录结构如下specification/v0_8/json/ ├── README.md # 本文关联文档 ├── server_to_client.json # 服务端→客户端消息抽象、与目录无关 ├── client_to_server.json # 客户端→服务端事件 ├── catalog_description_schema.json # 组件目录的元模式meta-schema ├── standard_catalog_definition.json # 标准组件目录具体实现 ├── server_to_client_with_standard_catalog.json# 解析后的 LLM 友好版本 ├── a2ui_client_capabilities_schema.json # 客户端能力声明 └── catalogs/ ├── basic/ # 标准目录的示例消息31 个场景 │ ├── examples/*.json │ └── ... └── minimal/ # 最小目录渲染器测试床 ├── minimal_catalog.json ├── README.md └── examples/*.json六个核心文件的定位可以先用一张表概括Schema 文件角色关键作用server_to_client.json抽象线协议定义beginRendering、surfaceUpdate、dataModelUpdate、deleteSurface四种消息component字段保持通配additionalProperties: trueclient_to_server.json事件协议定义userAction与error两类客户端回传消息catalog_description_schema.json元模式定义组件目录的结构catalogIdcomponentsstyles允许创建任意自定义组件集standard_catalog_definition.json具体目录标准组件集的落地实现Text、Image、Row、Card 等server_to_client_with_standard_catalog.json解析模式将标准目录替换进server_to_client.json把通配的component变为严格的oneOf/属性枚举供 LLM 直接生成合法消息a2ui_client_capabilities_schema.json能力协商客户端声明支持的目录集合供服务端选择catalogId二、server_to_client.json四种服务端消息的线协议server_to_client.json是整组 Schema 中目录无关catalog-agnostic的核心。它位于 specification/v0_8/json/server_to_client.json顶层约束additionalProperties: false即一条消息必须且只能包含beginRendering、surfaceUpdate、dataModelUpdate、deleteSurface四个动作属性之一。这四种消息承载了 A2UI 的核心理念UI 结构组件树与应用数据数据模型严格分离。组件结构通过surfaceUpdate一次性下发之后的数据刷新只需发送轻量的dataModelUpdate无需重传整棵 UI 树。渲染器源码印证了这一点——renderers/web_core/src/v0_8/schema/server-to-client.ts 使用 Zod 对同一结构做了逐字段等价建模并额外实现了组件 ID 去重引用完整性校验等 Schema 本身无法表达的约束。2.1 beginRendering首帧渲染信号beginRendering通知客户端可以开始渲染某个 surface防止出现内容不完整闪烁flash of incomplete content。客户端会先缓冲surfaceUpdate与dataModelUpdate消息直到收到该信号后才执行首次渲染。{ beginRendering: { surfaceId: unique-surface-1, root: root-component-id } }字段说明surfaceId必填string要渲染的 UI surface 唯一标识。root必填string根组件 ID客户端从该组件出发遍历组件树完成渲染。catalogId可选string本次 surface 使用的组件目录标识省略时客户端必须回退到本版本的默认标准目录。每个 surface 可以使用不同的目录这在多 Agent 系统中尤其灵活——不同 Agent 可以支持不同的组件目录。styles可选objectUI 的样式信息。在通配版中additionalProperties: true在解析版中则被约束为目录styles所定义的字段如font、primaryColor。2.2 surfaceUpdate组件树的主要载体surfaceUpdate是定义 UI 结构的主要消息包含surfaceId与components数组。每个数组元素是一个组件实例结构如下{ surfaceUpdate: { surfaceId: main_content_area, components: [ { id: unique-component-id, component: { Text: { text: { literalString: Hello, A2UI }, usageHint: h1 } } } ] } }组件实例的三个字段id必填string组件唯一标识被布局容器Row/Column/List 等通过字符串 ID 引用。weight可选number组件在 Row/Column 内的相对权重对应 CSS 的flex-grow仅当组件是 Row/Column 的直接子节点时才能设置。component必填object包装对象必须且只能包含一个键键名即组件类型名如Heading、Text键值为该组件的属性对象。关键设计整个组件列表是扁平的邻接表而不是嵌套 JSON 树。各组件之间的父子关系通过字符串 ID 互相引用。这样设计的原因在 specification/v0_8/docs/a2ui_protocol.md 中有明确阐述要求 LLM 一次性生成完美嵌套的 JSON 树既困难又易错而先想一个组件、给它一个 ID、之后再用 ID 引用它的方式更符合生成式模型的思维方式。组件可以按任意顺序下发只要在beginRendering之前所有被引用的组件都已到位即可。2.3 dataModelUpdate动态数据与状态管理dataModelUpdate负责更新 surface 的数据模型是状态与结构分离设计的具体实现{ dataModelUpdate: { surfaceId: main_content_area, path: /user/name, contents: [ { key: username, valueString: a2a_fan }, { key: age, valueNumber: 30 }, { key: active, valueBoolean: true } ] } }字段说明surfaceId必填string本次数据更新作用的 surface。path可选string数据模型内的目标路径如/user/name省略或设为/时整个数据模型将被整体替换。contents必填array数据条目数组每条必须包含key并恰好提供一个带类型的value*属性。可用类型有valueString、valueNumber、valueBoolean以及表示邻接表形式映射的valueMap其内部条目同样遵循一个 key 加恰好一个 value*规则。Zod 实现中对恰好一个 value* 属性的校验非常直接renderers/web_core/src/v0_8/schema/server-to-client.ts#L40-L52依次统计valueString、valueNumber、valueBoolean、valueMap的出现次数若总数不等于 1 则校验失败。数据绑定data binding方面协议只支持 1:1 的直接绑定不包含格式化器、条件等转换器——任何数据变换都必须在服务端完成后再通过dataModelUpdate下发。2.4 deleteSurface销毁 surfacedeleteSurface显式移除某个 surface 及其全部内容{ deleteSurface: { surfaceId: surface-to-remove } }仅一个必填字段surfaceId用于标识要删除的 UI surface。三、client_to_server.json客户端事件回传客户端向服务端回传事件使用独立的 client_to_server.json。它通过minProperties: 1、maxProperties: 1与oneOf: [{required: [userAction]}, {required: [error]}]双重约束保证每条消息只能携带一个事件。保持数据流单向SSE 单向推送 UI事件通过独立的 A2A 消息回传是协议健壮且可扩展设计原则的一部分。3.1 userAction用户交互事件用户触发组件上的动作时上报其字段全部来自组件定义中的action{ userAction: { name: login_submitted, surfaceId: gallery-simple-login-form, sourceComponentId: submit_button, timestamp: 2025-09-19T10:30:00Z, context: { user: a2a_fan, pass: s3cret } } }字段说明name必填string动作名称取自组件action.name属性。surfaceId必填string事件来源 surface 的 ID。sourceComponentId必填string触发事件的组件 ID。timestamp必填stringformat: date-timeISO 8601 格式的事件发生时间。context必填object组件action.context中定义的数据绑定解析全部绑定后的键值对。注意context中携带的是解析数据绑定之后的值组件定义里value可以写成{path: /username}客户端解释器会在事件触发时把该路径解析为数据模型中的实际值再回传。3.2 error客户端错误上报{ error: { message: Failed to load font resource, code: FONT_LOAD_ERROR } }error对象内容完全灵活additionalProperties: true用于向服务端报告客户端侧错误。四、catalog_description_schema.json自定义目录的元模式A2UI 的可扩展性根植于目录机制协议本身不固定组件集合组件集由独立的Catalog定义。catalog_description_schema.json 是描述一个目录长什么样的元模式仅要求三个字段catalogId必填string目录唯一标识。文档建议用自己拥有的互联网域名做前缀以避免冲突例如mycompany.com:somecatalog。components必填object键为组件名、值为该组件属性的 JSON Schema引用 draft 2020-12。styles必填object键为样式名、值为该样式属性的 JSON Schema。这意味着任何团队都可以构建自己的组件集——签名面板、报表卡片、专用图表等——而协议本身无需改动。styles对象是beginRendering消息中styles字段的取值约束来源。五、standard_catalog_definition.json标准组件目录standard_catalog_definition.json 是符合上述元模式的标准目录实现定义了 A2UI v0.8 基线所包含的组件与样式它是beginRendering省略catalogId时的默认回退目录。5.1 标准组件清单标准目录共 20 个组件分为展示类、布局类、容器类与输入类类别组件核心属性展示Texttext字面量或数据路径、usageHinth1~h5/caption/body展示Imageurl、altText、fit对应 CSSobject-fit、usageHinticon/avatar/smallFeature/mediumFeature/largeFeature/header展示Iconname约 50 个枚举图标名或数据路径展示Videourl展示AudioPlayerurl、description布局RowchildrenexplicitList或template、distribution对应justify-content、alignment对应align-items布局Column同Row主轴方向为垂直布局Listchildren、directionvertical/horizontal、alignment容器Cardchild容器内渲染的组件 ID容器TabstabItems每个 tab 含title与child容器Divideraxishorizontal/vertical容器ModalentryPointChild触发打开的组件、contentChild弹窗内组件输入Buttonchild、primary、actionnamecontext键值数组输入CheckBoxlabel、value字面量布尔或数据路径输入TextFieldlabel、text、textFieldTypedate/longText/number/shortText/obscured、validationRegexp输入DateTimeInputvalueISO 8601、enableDate、enableTime输入MultipleChoiceselections、options、maxAllowedSelections、variantcheckbox/chips、filterable输入Sliderlabel、value、minValue、maxValue要点动态列表Row/Column/List的children支持两种形态——explicitList显式固定子组件 ID 数组与template由数据模型中的列表动态生成template.componentId指定模板组件template.dataBinding指定数据路径。字面量 vs 数据绑定几乎所有取值属性文本、URL、图标名、标签等都支持字面量literalString/literalNumber/literalBoolean/literalArray或数据路径path如/user/name二选一的结构。客户端解释器负责在渲染前解析这些路径。样式标准目录只定义两个样式——fontstring与primaryColorstring必须匹配^#[0-9a-fA-F]{6}$十六进制格式。5.2 标准目录示例登录表单仓库在 specification/v0_8/json/catalogs/basic/examples/ 提供了 31 个标准目录示例涵盖简单文本、航班状态、邮箱撰写、音乐播放器、商品卡片、聊天消息、咖啡点单、运动详情、健身汇总等真实场景。以00_simple-login-form.json为例它完整演示了数据先行 → 结构后置 → 信号渲染的典型消息序列[ { dataModelUpdate: { surfaceId: gallery-simple-login-form, path: /, contents: [ { key: username, valueString: }, { key: password, valueString: } ] } }, { surfaceUpdate: { surfaceId: gallery-simple-login-form, components: [ { id: root, component: { Column: { children: { explicitList: [form_title, username_field, password_field, submit_button] }, distribution: start, alignment: stretch } } }, { id: submit_button, component: { Button: { child: submit_label, primary: true, action: { name: login_submitted, context: [ { key: user, value: { path: /username } }, { key: pass, value: { path: /password } } ] } } } } ] } }, { beginRendering: { surfaceId: gallery-simple-login-form, root: root } } ]这段示例展示了三个关键手法先发dataModelUpdate初始化空表单数据surfaceUpdate用扁平列表描述整棵组件树Column 根节点通过explicitList引用子组件 IDTextField 的text与 Button 的action.context都通过path绑定数据模型最后发beginRendering指定根组件root客户端才开始渲染。六、server_to_client_with_standard_catalog.jsonLLM 友好的解析模式通配版server_to_client.json中surfaceUpdate.components[].component是开放的additionalProperties: true虽然协议灵活但对 LLM 来说可以放任何东西意味着不知道该放什么。server_to_client_with_standard_catalog.json正是为解决这个问题而生的解析后resolved版本它把standard_catalog_definition.json的组件定义替换进server_to_client.json将通配的component对象变成严格的属性枚举Text、Image、Row、Card……每个键的值都是对应组件的严格属性 Schema同时把beginRendering.styles替换为目录中的styles定义font与primaryColor。这样 LLM 拿到的是一份完整、严格类型、零歧义的 Schema可以直接用于生成合法 A2UI 消息。6.1 自己生成解析模式文档 specification/v0_8/docs/a2ui_protocol.md#L269-L285 给出了基于任意自定义目录生成解析模式的 Python 逻辑核心只有三步替换import copy component_properties custom_catalog_definition[components] style_properties custom_catalog_definition[styles] resolved_schema copy.deepcopy(server_to_client_schema) resolved_schema[properties][surfaceUpdate][properties][components][items][properties][component][properties] component_properties resolved_schema[properties][beginRendering][properties][styles][properties] style_properties换句话说server_to_client.json是抽象的线协议wire protocolserver_to_client_with_standard_catalog.json是具体的生成工具generation tool。构建 Agent 时官方建议使用面向目标目录的解析模式以显著提升 UI 生成的可靠性。6.2 渲染器侧的 Schema 消费在渲染器实现侧解析模式同样被直接使用。例如 renderers/web_core/src/v0_8/index.ts#L25-L32 既导出了基于 Zod 手写的A2uiMessageSchema也直接以 JSON 模块方式引入解析模式文件并对外暴露为Schemas.A2UIClientEventMessage。而verify-schema.test.tsrenderers/web_core/src/v0_8/schema/verify-schema.test.ts则验证手写 Zod 模式与官方 JSON Schema 的一致性——这说明 JSON Schema 文件不仅是文档还是各语言渲染器实现正确性的对照基准。七、minimal_catalog.json渲染器开发的测试床标准目录功能全面但对于从零实现一个渲染器而言负担过重。catalogs/minimal/minimal_catalog.json 将组件面收敛到五个基础组件Text渲染文本字符串Row水平 flex 布局Column垂直 flex 布局Button基础交互与动作派发TextField用户输入。它的catalogId为https://a2ui.org/specification/v0_8/catalogs/minimal/minimal_catalog.json。根据 catalogs/minimal/README.md 的说明最小目录是标准目录的严格子集strict subset任何对该最小目录合法valid的 A2UI 消息对标准目录同样合法。这意味着开发者可以用最小目录的示例catalogs/minimal/examples/下的 5 个场景去测试那些硬编码使用标准目录的既有 v0.8 渲染器也可以先围绕布局算法、组件嵌套、数据绑定、事件处理四个核心能力打好地基再扩展到完整标准目录。八、配套a2ui_client_capabilities_schema.json 与能力协商能力协商机制使平台无关成为可能协议定义的是抽象组件树我需要一个 Card 里面放一个 Row由客户端负责把这些抽象类型映射到原生控件。为此客户端需要告诉服务端我支持哪些目录。a2ui_client_capabilities_schema.json 定义了a2uiClientCapabilities对象supportedCatalogIds必填string[]客户端支持的每个目录的 URIv0.8 标准目录为https://a2ui.org/specification/v0_8/standard_catalog_definition.json。inlineCatalogs可选array内联目录定义数组元素引用catalog_description_schema.json仅当服务端在能力声明中标记了acceptsInlineCatalogs: true时才应提供。服务端收到客户端能力后在beginRendering.catalogId中指定所选目录必须是supportedCatalogIds之一或某个inlineCatalogs的catalogId。省略则客户端回退到标准目录。九、实践要点与使用建议围绕这组 Schema 的典型开发场景与要点总结如下Agent 生成 UI优先使用解析模式如server_to_client_with_standard_catalog.json或按 6.1 节逻辑基于自有目录生成的解析模式作为 LLM 的工具/约束输入而不是通配版线协议。消息序列习惯按dataModelUpdate数据→surfaceUpdate结构→beginRendering渲染信号的顺序发送后续状态变化只需小体积的dataModelUpdate避免重传整个组件树。组件 ID 纪律id在整个 surface 内必须唯一Row/Column/List引用不存在的组件 ID 会导致渲染失败。Zod 实现server-to-client.ts的superRefine会对重复 ID 与悬空引用给出显式错误。数据绑定约定只支持 1:1 直接绑定无转换器格式化、条件等逻辑必须在服务端完成。自定义目录以catalog_description_schema.json为元模式定义组件与样式 Schema用域名前缀的catalogId避免冲突并通过inlineCatalogs或客户端能力声明提供给服务端。渲染器开发入门先以minimal_catalog.json为靶子跑通五个基础组件与catalogs/minimal/examples/示例再逐步逼近标准目录同时可复用 web_core 的 Schema 一致性测试思路验证自己的实现。这组 JSON Schema 既是协议的事实规范也是所有语言 SDK 与渲染器实现的单一事实来源深入理解它们的层次关系抽象线协议 / 具体目录 / 解析模式是使用 A2UI 或为其贡献实现的关键起点。【免费下载链接】a2ui项目地址: https://gitcode.com/GitHub_Trending/a2/a2ui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考