A2UI 统一 SDK 架构深度解析Core SDK、Inference SDK 与 Framework Adapter 三层体系【免费下载链接】a2ui项目地址: https://gitcode.com/GitHub_Trending/a2/a2ui导读本文以仓库 sdks_spec.md 为核心系统讲解 A2UI 生成式 UI 生态的统一 SDK 架构。A2UI 通过将关注点分离为A2UI Core SDK核心 SDK、Inference SDK推理 SDK与Framework Adapters框架适配器三个模块化层级并在 TypeScript、Dart、Python、Kotlin、Swift 等语言中复刻同一套结构与术语从而在多语言、多框架场景下实现高代码复用、严格一致性与统一行为。读完本文你将掌握每一层 SDK 的职责边界、依赖关系、核心接口以及如何借助规范驱动开发spec-driven development在多个语言代码库之间保持行为对齐。1. 三层 SDK 架构总览A2UI 将整个 SDK 生态拆分为三个职责互斥的层次该结构在所有目标语言中保持一致层级代表包名核心职责A2UI Core SDKa2ui_core/a2ui/core提供官方 A2UI 规范的语言原生表示协议模型、Surface 状态管理、消息处理与校验Inference SDKa2ui_inference/a2ui/inference引导 LLM 基于组件 Catalog 生成合法的 A2UI 消息载荷Framework Adaptersreact_renderer、compose_renderer等将 CoreSurfaceModel的状态绘制为原生 UI 像素其依赖关系是单向的Framework Adapter 与 Inference SDK 都依赖 Core SDK而 Core SDK 不依赖任何上层。原文用如下依赖图描述这种单向依赖设计带来两个关键收益高代码复用协议模型、状态管理与校验逻辑只实现一次所有上层推理侧与渲染侧共享同一份核心语义规范驱动开发跨语言使用一致的代码库结构与术语使各语言 SDK 可以按同一套规范文档同步维护、同步新增功能。仓库中blueprints/modules/下的 a2ui_core.blueprint.md、a2ui_agent.blueprint.md 与 a2ui_framework_adapter.blueprint.md 正是这三层的“规范蓝图”分别规定各层必须实现的能力与非目标。2. A2UI Core SDKa2ui_core/a2ui/core可用范围每种目标语言TS、Dart、Python、Kotlin、Swift、C。职责提供官方 A2UI 规范的、语言原生的基础表示是纯粹的框架无关层不包含任何 UI 渲染逻辑。Core SDK 的五大能力如下协议模型Protocol Models强类型类表示 Catalog 声明Catalog、ComponentApi、FunctionApi与 A2UI 消息类型ClientToServer、ServerToClient等。Surface 状态管理Surface State Management表示活跃 UI 界面的可变模型SurfaceModel、ComponentModel、DataModel。处理层MessageProcessor求值入站的 JSON 消息数组解析相对 JSON Pointer并更新 Surface 状态模型。校验Validation对消息 Schema 结构与引用做严格校验。增量快照Incremental Snapshotting跟踪并把增量更新折叠为扁平快照如ComponentNode树。2.1 仓库中的实际落地在 Python 实现中agent_sdks/python/a2ui_core/src/a2ui/core/目录与蓝图中的包结构一一对应catalog/Catalog 声明、state/响应式状态模型、processing/消息处理引擎、validating/校验层、rendering/DataContext、GenericBinder 等解析层、schema/协议模型、basic_catalog/内置默认组件。其 README 明确指出该库严格面向A2UI v0.9 及以后的规范与客户端a2ui/web_core引擎保持对称对齐以便在评估状态表示与解析动态布局值时获得完全一致的结果。Dart 实现则位于 dart/a2ui_core/lib/src分为core/catalog、data_model、messages、surface_group_model 等、primitives/reactivity、data_path、event_notifier 等、processing/processor、expressions、rendering/binder与validation/validator、component_graph等包。2.2MessageProcessor状态变更的总控制器MessageProcessor接受原始 A2UI 消息流解析后变更状态模型并聚合渲染端状态用于同步。Python 实现message_processor.py展示了其核心形态构造时接收catalogs列表与可选的action_handler维护一个SurfaceGroupModel实例process_messages()依次执行CreateSurface、UpdateComponents、UpdateDataModel、DeleteSurface四类消息且会拒绝同一消息中包含多个冲突更新动作get_client_capabilities()与get_client_data_model()则分别聚合受支持目录与启用了sendDataModel的 surface 数据模型供传输层携带元数据。对于sendDataModel: true的 surface渲染端在每次发送 renderer-to-agent 消息如action时都需要回传该 surface 数据模型的当前状态MessageProcessor负责跟踪该标志位并在传输前聚合数据。2.3 分层校验体系Core 的校验职责由A2uiValidator与配套组件承担按类别细分为协议信封校验单更新类型、合法version标签、Surface 生命周期校验createSurface不可重复、更新/删除必须存在、Catalog 协商与解析校验、组件属性/主题 Schema 校验、图完整性校验重复组件 ID、缺失root、悬空引用、孤儿节点、图拓扑校验自引用、循环引用检测以及递归深度全局深度 50、函数嵌套 5与 JSON Pointer 路径语法校验。各类失败分别抛出A2uiValidationError、A2uiIntegrityError、A2uiCatalogError、A2uiRecursionError等结构化异常。完整的校验矩阵见 a2ui_core.blueprint.md 第 3 节这也是 conformance/core/validator.yaml 测试用例所覆盖的行为基准。3. Inference SDKa2ui_inference/a2ui/inference可用范围所有受支持的 Agent 语言以及部分客户端语言用于本地推理。职责基于已定义的组件 Catalog 与活跃应用上下文引导大语言模型生成合法的 A2UI 消息载荷。Inference SDK 的四大能力推理策略Inference Strategies标准的结构化生成方案。提示词构造Prompt Construction构建提示词缓冲区动态把组件能力 Schema 喂入 LLM 上下文。消息解析Message Parsing安全地从 LLM 完成流中提取并修复原始 JSON 信封。错误修复与重试Error Repair Retries程序化修复格式错误或非法 Schema。3.1 在 Agent SDK 中的落地仓库中的实际载体是agent_sdks/python/a2ui_agent/src/a2ui/其架构分为低层单一职责原语与高层应用门面两层目录转换器Catalog TransformersComponentPruningTransformer、FunctionPruningTransformer基于 allowlist 规则从完整目录中裁剪组件/函数定义推理格式Inference FormatsInferenceFormat/InferenceFormatFactory策略门面成对组合格式专属的PromptGenerator与Parser。已支持DirectJsonFormat标准 A2UI JSON 载荷包裹于a2ui-json哨兵标签内与ExpressFormat紧凑函数式 DSL用于降低输出 token 消耗语法见 a2ui_express.md 与 Express.g4解析器Parsers响应提取引擎负责标签解包unwrap、流式分块处理parse_chunk、语法编译compile与反编译decompile校验层直接复用 Core 的A2uiValidator原生支持v0_8、v0_9、v0_9_1、v1_0多协议版本分支应用门面A2uiGenerator持有 Agent 支持的CatalogConfig列表按渲染端能力签名生成预协商的A2uiRequestProcessorA2uiRequestProcessor统一多目录能力解析resolve_catalogs、系统提示词片段渲染、回合级解析器创建与响应校验。典型 Agent 工作流如下来自 a2ui_agent.blueprint.md 的代码示例# 1. Agent 启动初始化长期存活的 A2uiGenerator 并注册 Agent 目录 generator A2uiGenerator( catalogs[ CatalogConfig(BasicCatalog(v1.0)), CatalogConfig.from_path(./catalogs/custom_catalog.json), ], examplesload_examples(./prompts/examples/**) ) # 2. 在请求处理器中按渲染端能力获取预协商的处理器 processor generator.create_processor(renderer_capabilities) # 3. 调用 LLM 生成输出 llm_output_text myagent.call_llm(processor.prompt_snippet, request_context) # 4. 用处理器解析并校验输出 response_parts processor.parse_response(llm_output_text) # 5. 将 A2UI 载荷交付给渲染端3.2 渲染端与 Agent 端对 Core 的不同使用方式MessageProcessor在两端扮演不同角色渲染端用它处理入站消息并更新布局/数据状态actionHandler负责路由 UI 点击事件Agent 端则把它作为可选辅助用于在发送前校验 LLM 生成的消息、核对数据路径。Agent 端应传入单一已协商目录以强制目录合规一旦 LLM 生成了引用未协商目录的载荷即失败同时 Agent 不必传actionHandler。二者差异可概括为渲染端维护实时视图模型并路由用户动作事件Agent 端则在发送前校验载荷与数据路径引用。4. Framework Adaptersreact_renderer、compose_renderer等可用范围客户端平台上的每个受支持 UI 框架。职责使用原生 UI 层级把 CoreSurfaceModel的状态绘制到物理屏幕像素上。Framework Adapter 的核心组成框架入口视图Surface观察 Core 状态并启动递归布局循环组件渲染器ComponentImplementation实现视觉规范的单个原生视图如 Basic Catalog 中的标准布局、文本或输入组件生命周期绑定Lifecycle Bindings标准化懒挂载、响应式值传播与内存泄漏防护dispose。4.1 数据流与两层拆分从 a2ui_framework_adapter.blueprint.md 可知客户端架构的数据流是服务端 A2UI 消息JSON→MessageProcessorCore SDK解析并更新SurfaceModel→Surface框架入口视图监听SurfaceModel开始渲染 → 实例化各ComponentImplementation节点构建 UI 树。这确立了根本性的拆分框架无关层数据层 / Core SDKJSON 解析、状态管理、JSON Pointer 与 Schema 逻辑在给定语言的所有 UI 框架间完全一致框架专属层视图层 / Framework Adapter把结构化状态变成实际像素React 节点、Flutter Widget、iOS View 等。4.2 组件实现策略与生命周期契约ComponentImplementation在不同范式下有不同形态函数式/响应式框架Flutter、SwiftUI、React通过build(ctx, buildChild)递归构建子节点有状态/命令式框架Vanilla DOM、Android Views则通过createInstance(ctx)返回可mount/update/unmount的ComponentInstance。无论采用哪种策略适配器都必须遵守三条订阅生命周期规则懒订阅组件挂载后才绑定数据路径、路径稳定性updateComponents变更属性时先退订旧路径再订阅新路径、销毁清理组件移除时挂接原生生命周期调用dispose释放所有数据模型订阅。仓库中的 React 渲染器是很好的参考实现A2uiSurface.tsx 承担Surface入口视图职责adapter.tsx 与renderers/react/src/v0_9/catalog/basic/components/下的Button.tsx、Card.tsx、Row.tsx、List.tsx等即为各 Basic Catalog 组件的ComponentImplementation。Catalog的idcatalogId是任意字符串标识符而非可解析的 URI这一点在多目录协商时需注意。5. 依赖方向与规范驱动开发跨语言一致性如何保证三层 SDK 生态的关键在于“规范即契约”specification/目录下的协议 JSON Schema 与文档如 a2ui_protocol.md、basic_catalog_implementation_guide.md定义了所有语言必须实现的语义conformance/core 与 conformance/agent 下的语言无关 YAML 测试套件则把语义固化为可执行的输入/期望对。各语言 SDK 只需实现一个测试载体参考 conformance/README.md 与 Python 侧的agent_sdks/python/a2ui_agent/tests/conformance/test_conformance.py即可验证自身行为与规范一致。例如conformance/core/message_processor.yaml覆盖消息处理器的状态机agent/streaming_parser.yaml覆盖流式解析器的分块缓冲与增量产出。这正是“跨语言保持统一行为”在工程层面的落地方式。同时需要留意各语言对协议版本的支持差异蓝图明确指出 Dart SDK 不实现 v0.8而 Python 与 TypeScript SDK 为向后兼容保留 v0.8Pythona2ui_core严格只支持 v0.9 及以后。因此协议版本覆盖是各实现自身的属性而非整个生态的统一承诺集成时需按目标 SDK 确认其版本范围。6. 总结与选型指引A2UI 统一 SDK 架构的精髓可以概括为一句话Core 定状态、Inference 出消息、Adapter 绘像素规范贯穿三者。在实际接入时构建Agent / 服务端使用 Inference SDKa2ui_agent注册目录、裁剪 allowlist、选择推理格式Direct JSON 或 Express DSL并通过A2uiValidator或MessageProcessor在发送前校验载荷构建客户端渲染器使用 Core SDK Framework Adapter让Surface监听SurfaceModel为每个 Catalog 组件提供ComponentImplementation并严格管理订阅生命周期追求多语言一致性以specification/与conformance/为唯一事实来源在新增语言时复刻相同的目录结构与术语再以语言无关测试套件验证行为对齐。三个蓝本文档a2ui_core.blueprint.md、a2ui_agent.blueprint.md、a2ui_framework_adapter.blueprint.md提供了各层完整的接口规格与实现要求是继续深入每一层细节的最佳入口。【免费下载链接】a2ui项目地址: https://gitcode.com/GitHub_Trending/a2/a2ui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考