A2UI 开源项目解读
项目信息
项目名称：A2UI
项目描述: 是 Google 开源的一个协议和库集合，让 AI Agent 能够生成丰富的交互式用户界面。Agent 发送声明式 JSON，客户端用原生组件渲染，安全且跨平台。
官方文档：https://a2ui.org/
解决的核心痛点：
文本交互效率低下：传统 Agent 只能以纯文本与用户交互，表单填写、时间选择等场景需要多轮对话。A2UI 让 Agent 能直接生成交互式 UI，将多轮文本对话压缩为一轮 UI 交互。
远程 Agent 无法安全操控 UI：在多 Agent 系统中，Agent 通常运行在远程服务器上，无法直接操作客户端 UI。传统方案（iframe 嵌入 HTML/JS）存在严重的安全风险和样式隔离问题。A2UI 以声明式数据格式替代可执行代码，实现"像数据一样安全，像代码一样表达力强"。
跨平台 UI 生成缺乏统一标准：不同平台（Web、iOS、Android、Flutter）需要不同的 UI 实现。A2UI 将 UI 结构与实现分离，同一份 JSON 可在多种框架上渲染。
1. 项目概览
1.1 项目定位与核心价值
一句话定位：A2UI 是一个开源的 Agent-to-User Interface 协议和库集合，让 AI Agent 能够"说 UI 语言"——通过声明式 JSON 格式生成和传递丰富的交互式用户界面。
解决的核心痛点：
文本交互效率低下：传统 Agent 只能以纯文本与用户交互，表单填写、时间选择等场景需要多轮对话。A2UI 让 Agent 能直接生成交互式 UI，将多轮文本对话压缩为一轮 UI 交互。
远程 Agent 无法安全操控 UI：在多 Agent 系统中，Agent 通常运行在远程服务器上，无法直接操作客户端 UI。传统方案（iframe 嵌入 HTML/JS）存在严重的安全风险和样式隔离问题。A2UI 以声明式数据格式替代可执行代码，实现"像数据一样安全，像代码一样表达力强"。
跨平台 UI 生成缺乏统一标准：不同平台（Web、iOS、Android、Flutter）需要不同的 UI 实现。A2UI 将 UI 结构与实现分离，同一份 JSON 可在多种框架上渲染。
目标用户画像：
| 角色 | 描述 |
|---|---|
| Agent 开发者 | 使用 Python/Kotlin SDK 让 Agent 生成 A2UI JSON 的服务端开发者 |
| 客户端开发者 | 使用 Lit/React/Angular/Flutter 渲染 A2UI 的前端/移动端开发者 |
| 平台构建者 | 构建 Agent 平台的团队，需要统一 Agent UI 生成能力 |
| 最终用户 | 通过 Agent 驱动的应用获得更丰富交互体验的普通用户 |
1.2 目标用户与使用场景
核心业务场景：
- 场景一：动态数据收集 — Agent 根据对话上下文动态生成定制化表单（日期选择器、滑块、输入框等），例如预订特色餐厅时的偏好收集。
- 场景二：远程子 Agent 编排 — 编排器 Agent 将任务委托给远程专业 Agent，远程 Agent 返回 UI 负载，在主聊天窗口中渲染。
- 场景三：自适应工作流 — 企业级 Agent 根据用户查询即时生成审批仪表盘或数据可视化界面。
典型使用 Case（端到端流程）：
- 用户在聊天界面中提出请求，如"帮我找附近的意大利餐厅"
- Agent（运行在服务端，如 Google ADK）处理请求，生成包含餐厅列表、评分筛选、预订按钮等组件的 A2UI JSON
- JSON 通过 A2A 或 AG UI 传输协议发送到客户端
- 客户端 A2UI 渲染器（如 Lit/Angular/React）接收到 JSON，使用本地组件目录映射渲染为原生 UI
- 用户与 UI 交互（点击按钮、填入表单等），交互事件通过协议回传 Agent
- Agent 接收用户操作，动态更新 UI（增量补丁），形成闭环交互
1.3 核心技术亮点
- 安全优先：Agent 只能请求渲染客户端预批准目录中的组件，无法执行任意代码
- LLM 友好的增量更新：扁平组件列表 + ID 引用，LLM 易于逐组件生成和修正
- 框架无关：同一份 A2UI JSON 可在 Lit、React、Angular、Flutter、SwiftUI 上渲染
- 渐进式渲染：流式解析引擎支持逐组件产出，用户看到"逐步构建"的 UI
- 响应式数据绑定：基于 Preact Signals 的细粒度响应式系统，数据变更时只更新相关组件
- Schema 驱动的通用绑定：GenericBinder 通过分析 Zod Schema 自动适配组件属性，无需手写绑定逻辑
1.4 技术栈与选型对比
| 层级 | 技术选择 | 关键依赖 |
|---|---|---|
| Agent SDK (Python) | Python 3.10+ | google-adk, google-genai, jsonschema, a2a-sdk |
| Agent SDK (Kotlin) | Kotlin / JVM | Gradle |
| 渲染核心 (Web) | TypeScript | Zod, Preact Signals |
| 主力渲染器 | Lit (Web Components) v3 | @lit/context, @lit-labs/signals |
| React 渲染器 | React + TypeScript | - |
| Angular 渲染器 | Angular Standalone | - |
| Flutter 渲染器 | Dart (GenUI SDK) | - |
| 可视化工具 | Next.js 14 (App Router) | React |
| 文档站点 | MkDocs Material | - |
| 传输协议 | A2A, AG UI, MCP | - |
关键选型决策：
- 声明式 JSON 而非可执行代码：安全性 > 灵活性。Agent 不可信任，声明式数据确保 Agent 只能请求预批准组件。
- 独立协议层而非直接使用 HTML：跨平台 > 简单性。引入新抽象层的学习成本换来真正的"一次生成，多端渲染"。
- Lit (Web Components) 作为主力渲染器：Web 标准保证了跨框架兼容性，轻量化适合渲染简单 UI。
- GenericBinder (Schema 驱动) 而非手写绑定：可扩展性 > 直观性。新增组件只需定义 Zod Schema，无需编写新的数据绑定代码。
2. 整体架构设计
2.1 架构概述
A2UI 采用协议驱动的分层架构模式。系统共分为五层：规范定义层（Specification）、Agent 生成层（Agent SDKs）、传输适配层（Transport）、渲染核心层（Web Core）和客户端渲染层（Renderers）。各层通过标准化的 JSON 协议消息松耦合连接，上层生成 A2UI JSON 消息，下层解析并渲染为原生 UI。核心设计哲学是"声明式数据替代可执行代码"，Agent 只能请求客户端预批准组件目录中的组件。
整体架构图 (plainText)：
text
+=======================================================================+
| A2UI 整体架构 (Protocol-Driven Architecture) |
+=======================================================================+
+---------------------------------------------+
| Specification Layer (规范层) |
| v0.8 (Stable) | v0.9 (Current) | v0.10 (Draft) |
| JSON Schema 协议定义 + 组件目录规范 |
+------------------+--------------------------+
| (定义协议格式)
v
+---------------------------------------------+
| Agent SDK Layer (Agent 生成层) |
| +------------------+ +------------------+ |
| | Python SDK | | Kotlin SDK | |
| | - Schema Manager | | - StreamingParser| |
| | - Stream Parser | | - ... | |
| | - Catalog System | | | |
| | - ADK Integration| | | |
| +------------------+ +------------------+ |
+------------------+--------------------------+
| (生成 A2UI JSON 消息)
v
+---------------------------------------------+
| Transport Layer (传输适配层) |
| +---------+ +--------+ +-----------+ |
| | A2A | | AG UI | | MCP | |
| | Protocol| |(Copilot)| | Protocol | |
| +---------+ +--------+ +-----------+ |
+------------------+--------------------------+
| (传输 JSON 消息到客户端)
v
+---------------------------------------------+
| Web Core Layer (渲染核心层) |
| +---------------------------------------+ |
| | MessageProcessor (消息处理器) | |
| | - 消息验证与分发 | |
| | - Surface 生命周期管理 | |
| +---------------------------------------+ |
| | State Management (状态管理) | |
| | - DataModel (响应式数据模型) | |
| | - SurfaceModel (Surface 模型) | |
| | - ComponentModel (组件模型) | |
| +---------------------------------------+ |
| | Rendering Engine (渲染引擎) | |
| | - GenericBinder (通用数据绑定) | |
| | - ComponentContext (组件上下文) | |
| | - DataContext (数据上下文) | |
| +---------------------------------------+ |
+------------------+--------------------------+
| (提供数据绑定和状态)
v
+---------------------------------------------+
| Renderers Layer (客户端渲染层) |
| +---------+ +-------+ +---------+ +------+ |
| | Lit | | React | | Angular | |Flutter| |
| | (主力) | | | | | | | |
| +---------+ +-------+ +---------+ +------+ |
| +------------------+ |
| | Markdown | |
| +------------------+ |
+---------------------------------------------+
|
v
+------------------+
| End User (最终用户) |
| - Browser |
| - Mobile App |
| - Desktop App |
+------------------+2.2 目录结构
shell
A2UI/
├── specification/ # 【核心基建】A2UI 协议规范定义 (所有版本的协议 JSON Schema)
│ ├── v0_8/ # 【核心基建】v0.8 稳定版协议规范 (已锁定, 不再接受修改)
│ │ └── README.md # 【核心基建】v0.8 协议文档入口
│ ├── v0_9/ # 【核心基建】v0.9 版协议规范 (已发布, 不再活跃开发)
│ │ └── README.md # 【核心基建】v0.9 协议文档入口 + Evolution Guide
│ ├── v0_9_1/ # 【核心基建】v0.9.1 版协议规范 (小版本修正)
│ │ └── README.md # 【核心基建】v0.9.1 协议文档入口
│ ├── v0_10/ # 【核心基建】v0.10 版协议规范 (当前开发中的版本)
│ │ └── README.md # 【核心基建】v0.10 协议文档入口
│ └── scripts/ # 【工具集】规范验证与处理脚本
│ └── validate.py # 【工具集】JSON Schema 规范验证工具
│
├── agent_sdks/ # 【核心基建】Agent 端 SDK (服务端, 用于生成 A2UI JSON)
│ ├── python/ # 【核心基建】Python Agent SDK (主力实现)
│ │ ├── src/a2ui/ # 【核心基建】Python SDK 源码
│ │ │ ├── __init__.py # 【核心基建】SDK 入口 (导出 __version__)
│ │ │ ├── version.py # 【配置】版本号常量
│ │ │ ├── inference_strategy.py # 【核心基建】LLM 推理策略基类 (Adapter Pattern)
│ │ │ ├── parser/ # 【核心基建】流式 JSON 解析引擎 (Factory Pattern)
│ │ │ │ ├── parser.py # 【核心基建】基础解析器
│ │ │ │ ├── streaming.py # 【核心基建】A2uiStreamParser 工厂类 (版本路由)
│ │ │ │ ├── streaming_v08.py # 【核心基建】v0.8 流式解析器实现
│ │ │ │ ├── streaming_v09.py # 【核心基建】v0.9 流式解析器实现 (状态机)
│ │ │ │ ├── payload_fixer.py # 【工具集】LLM 输出 payload 修复/纠错
│ │ │ │ ├── response_part.py # 【核心基建】流式解析产出事件类型 (ResponsePart)
│ │ │ │ └── constants.py # 【配置】解析器常量 (CUTTABLE_KEYS 等)
│ │ │ ├── schema/ # 【核心基建】Schema 与 Catalog 管理 (协议安全核心)
│ │ │ │ ├── manager.py # 【核心基建】A2uiSchemaManager - LLM 提示词生成 + Catalog 协商
│ │ │ │ ├── catalog.py # 【核心基建】A2uiCatalog - 组件目录定义与 Schema 验证
│ │ │ │ ├── catalog_provider.py # 【核心基建】CatalogProvider 接口 (Plugin/Extension Point)
│ │ │ │ ├── validator.py # 【核心基建】拓扑分析 + 组件引用/必填字段提取
│ │ │ │ ├── common_modifiers.py # 【核心基建】Schema Modifier 管道 (支持自定义修饰符)
│ │ │ │ ├── utils.py # 【工具集】bundled resource 加载工具
│ │ │ │ └── constants.py # 【配置】协议版本与 Schema 文件映射
│ │ │ ├── adk/ # 【核心基建】Google ADK (Agent Development Kit) 集成
│ │ │ │ ├── send_a2ui_to_client_toolset.py # 【核心基建】ADK Toolset - 暴露 A2UI 工具给 LLM
│ │ │ │ ├── __init__.py # 【核心基建】ADK 模块入口
│ │ │ │ └── a2a/ # 【核心基建】A2A 协议桥接
│ │ │ │ ├── event_converter.py # 【核心基建】A2A Event → A2UI 事件转换器
│ │ │ │ └── part_converter.py # 【核心基建】A2A Part → A2UI 消息转换器
│ │ │ ├── a2a/ # 【核心基建】A2A 协议扩展 (Agent-to-Agent)
│ │ │ │ ├── extension.py # 【核心基建】A2A AgentExtension 注册
│ │ │ │ └── parts.py # 【核心基建】A2UI 专用 A2A Part 类型定义
│ │ │ ├── basic_catalog/ # 【核心基建】基础组件目录 (Button, Text, Card 等标准组件)
│ │ │ │ ├── provider.py # 【核心基建】BasicCatalogProvider - 加载 bundled catalog.json
│ │ │ │ ├── constants.py # 【配置】基础组件目录 ID 常量
│ │ │ │ └── __init__.py # 【核心基建】模块入口
│ │ │ └── template/ # 【核心基建】模板管理系统 (预定义 UI 模板)
│ │ │ ├── manager.py # 【核心基建】TemplateManager - 模板生命周期管理
│ │ │ └── __init__.py # 【核心基建】模块入口
│ │ ├── tests/ # 【质量保证】Python SDK 测试
│ │ └── pyproject.toml # 【配置】Python 项目配置 (hatchling + uv)
│ ├── kotlin/ # 【核心基建】Kotlin Agent SDK (JVM/Android)
│ │ ├── src/main/kotlin/com/google/a2ui/ # 【核心基建】Kotlin SDK 源码
│ │ │ └── parser/StreamingParser.kt # 【核心基建】Kotlin 流式解析器 (1114行, 与 Python 版功能对等)
│ │ └── gradle/ # 【配置】Gradle 构建系统配置
│ └── conformance/ # 【质量保证】跨 SDK 一致性测试 (确保 Python/Kotlin 行为一致)
│ ├── suites/ # 【质量保证】测试套件定义
│ ├── test_data/ # 【质量保证】共享测试数据 (JSON fixtures)
│ └── tests/ # 【质量保证】一致性测试用例
│
├── renderers/ # 【核心基建】客户端渲染器集合 (多框架实现)
│ ├── web_core/ # 【核心基建】Web 渲染核心库 (所有 Web 渲染器的共享基础设施)
│ │ └── src/
│ │ ├── v0_8/ # 【核心基建】v0.8 协议核心实现
│ │ │ ├── types/colors.ts # 【核心基建】颜色系统类型定义 (Material Design 风格)
│ │ │ ├── errors.ts # 【核心基建】v0.8 错误类型定义
│ │ │ └── index.ts # 【核心基建】v0.8 模块入口
│ │ └── v0_9/ # 【核心基建】v0.9 协议核心实现 (当前主力版本)
│ │ ├── schema/ # 【核心基建】协议消息 Schema (Zod → JSON Schema)
│ │ │ ├── server-to-client.ts # 【核心基建】服务端→客户端消息定义 (4种消息类型)
│ │ │ ├── client-to-server.ts # 【核心基建】客户端→服务端消息定义 (Action + DataModel)
│ │ │ ├── common-types.ts # 【核心基建】公共类型 (Component, DataBinding, Action, ChildList)
│ │ │ ├── client-capabilities.ts # 【核心基建】客户端能力声明 (Catalog 协商)
│ │ │ ├── verify-schema.test.ts # 【质量保证】Schema 验证测试
│ │ │ └── index.ts # 【核心基建】Schema 模块入口
│ │ ├── state/ # 【核心基建】响应式状态管理 (Preact Signals 驱动)
│ │ │ ├── data-model.ts # 【核心基建】DataModel - JSON Pointer 响应式数据树
│ │ │ ├── surface-model.ts # 【核心基建】SurfaceModel - UI Surface 状态
│ │ │ ├── component-model.ts # 【核心基建】ComponentModel - 组件实例状态
│ │ │ ├── surface-components-model.ts # 【核心基建】Surface 级组件注册表
│ │ │ └── surface-group-model.ts # 【核心基建】全局 Surface 组管理
│ │ ├── processing/ # 【核心基建】消息处理引擎
│ │ │ └── message-processor.ts # 【核心基建】MessageProcessor - 消息验证与分发中枢
│ │ ├── catalog/ # 【核心基建】组件目录与函数调用
│ │ │ ├── types.ts # 【核心基建】Catalog/ComponentApi 类型定义
│ │ │ └── function_invoker.ts # 【核心基建】自定义函数调用器 (支持客户端注册函数)
│ │ ├── reactivity/ # 【核心基建】响应式系统封装
│ │ │ └── signals.ts # 【核心基建】Preact Signals 适配封装
│ │ ├── rendering/ # 【核心基建】渲染抽象层
│ │ │ ├── generic-binder.ts # 【核心基建】GenericBinder - Schema 驱动的数据绑定引擎
│ │ │ ├── component-context.ts # 【核心基建】ComponentContext - 组件上下文 (绑定到 Surface)
│ │ │ └── data-context.ts # 【核心基建】DataContext - 数据上下文 (路径解析 + 动态值订阅)
│ │ ├── common/ # 【工具集】公共基础设施
│ │ │ └── events.ts # 【工具集】Event Emitter (Pub/Sub 订阅管理)
│ │ ├── basic_catalog/ # 【核心基建】基础组件目录 Web 实现
│ │ │ └── index.ts # 【核心基建】基础目录注册 (包含所有标准 UI 组件的 Zod Schema)
│ │ ├── errors.ts # 【核心基建】v0.9 错误类型定义
│ │ └── index.ts # 【核心基建】v0.9 模块统一入口
│ ├── lit/ # 【业务模块】Lit (Web Components) 渲染器 - Google 主力实现
│ │ ├── src/
│ │ │ ├── index.ts # 【核心基建】@a2ui/lit 包入口 (多版本导出)
│ │ │ ├── 0.8/ # 【业务模块】v0.8 版渲染实现 (稳定版)
│ │ │ │ ├── core.ts # 【核心基建】核心函数 (create, processMessages, etc.)
│ │ │ │ ├── model.test.ts # 【质量保证】模型单元测试 (1323行, 覆盖全面)
│ │ │ │ ├── index.ts # 【核心基建】v0.8 公开 API
│ │ │ │ └── ui/ # 【UI 视图】v0.8 UI 组件 (LitElement Web Components)
│ │ │ │ ├── ui.ts # 【UI 视图】UI 组件聚合导出
│ │ │ │ ├── root.ts # 【UI 视图】A2UIRoot - 应用根节点
│ │ │ │ ├── surface.ts # 【UI 视图】A2UISurface - Surface 容器
│ │ │ │ ├── button.ts # 【UI 视图】A2UIButton - 按钮 (支持 Action 绑定)
│ │ │ │ ├── text.ts # 【UI 视图】A2UIText - 文本 (h1-h5, body, caption)
│ │ │ │ ├── card.ts # 【UI 视图】A2UICard - 卡片容器
│ │ │ │ ├── image.ts # 【UI 视图】A2UIImage - 图片
│ │ │ │ ├── video.ts # 【UI 视图】A2UIVideo - 视频播放器
│ │ │ │ ├── audio.ts # 【UI 视图】A2UIAudio - 音频播放器
│ │ │ │ ├── checkbox.ts # 【UI 视图】A2UICheckbox - 复选框
│ │ │ │ ├── slider.ts # 【UI 视图】A2UISlider - 滑块
│ │ │ │ ├── column.ts # 【UI 视图】A2UIColumn - 垂直布局
│ │ │ │ ├── row.ts # 【UI 视图】A2UIRow - 水平布局
│ │ │ │ ├── tabs.ts # 【UI 视图】A2UITabs - 标签页
│ │ │ │ ├── modal.ts # 【UI 视图】A2UIModal - 模态框
│ │ │ │ ├── divider.ts # 【UI 视图】A2UIDivider - 分割线
│ │ │ │ ├── styles.ts # 【UI 视图】Material Design 3 样式系统
│ │ │ │ └── component-registry.ts # 【核心基建】组件注册表 (Map<componentType, LitElement>)
│ │ │ └── v0_9/ # 【业务模块】v0.9 版渲染实现 (新架构)
│ │ │ ├── index.ts # 【核心基建】v0.9 公开 API
│ │ │ ├── a2ui-controller.ts # 【核心基建】A2uiController - Lit ReactiveController (绑定 GenericBinder)
│ │ │ ├── a2ui-lit-element.ts # 【核心基建】A2uiLitElement - 组件基类 (注入 ComponentContext)
│ │ │ ├── types.ts # 【核心基建】v0.9 类型定义
│ │ │ ├── surface/ # 【UI 视图】Surface 渲染
│ │ │ │ ├── a2ui-surface.ts # 【UI 视图】A2uiSurface - v0.9 Surface 容器
│ │ │ │ └── render-a2ui-node.ts # 【UI 视图】递归组件节点渲染 (遍历组件树)
│ │ │ ├── context/ # 【核心基建】依赖注入 Context (Lit Context Protocol)
│ │ │ │ ├── context.ts # 【核心基建】主 Context (ComponentContext, 组件注册表)
│ │ │ │ └── markdown.ts # 【核心基建】Markdown 渲染 Context
│ │ │ ├── directives/ # 【UI 视图】Lit 自定义指令
│ │ │ │ ├── directives.ts # 【UI 视图】通用渲染指令
│ │ │ │ └── markdown.ts # 【UI 视图】Markdown 渲染指令 (AsyncDirective)
│ │ │ └── tests/ # 【质量保证】v0.9 测试
│ │ │ ├── a2ui-surface.test.ts # 【质量保证】Surface 组件的集成测试
│ │ │ ├── a2ui-lit-element.test.ts # 【质量保证】基础元素测试
│ │ │ ├── a2ui-controller.test.ts # 【质量保证】Controller 单元测试
│ │ │ ├── basic-catalog-examples.test.ts # 【质量保证】基础目录集成测试
│ │ │ ├── custom-catalogs.test.ts # 【质量保证】自定义目录测试
│ │ │ ├── markdown.test.ts # 【质量保证】Markdown 渲染测试
│ │ │ └── dom-setup.ts # 【质量保证】JSDOM 测试环境配置
│ │ └── package.json # 【配置】@a2ui/lit 包配置 (v0.10.0)
│ ├── react/ # 【业务模块】React 渲染器
│ │ └── src/
│ │ ├── index.ts # 【核心基建】@a2ui/react 包入口
│ │ ├── types.ts # 【核心基建】React 渲染器类型定义
│ │ ├── v0_8/ # 【业务模块】v0.8 React 实现
│ │ │ ├── core/ # 【核心基建】核心 React 组件
│ │ │ │ ├── A2UIProvider.tsx # 【核心基建】A2UIProvider - 全局状态提供者 (React Context)
│ │ │ │ ├── A2UIViewer.tsx # 【核心基建】A2UIViewer - 消息接收 + 渲染编排
│ │ │ │ ├── A2UIRenderer.tsx # 【核心基建】A2UIRenderer - 组件递归渲染器
│ │ │ │ ├── ComponentNode.tsx # 【核心基建】ComponentNode - 单节点渲染
│ │ │ │ └── store.ts # 【核心基建】响应式 Store (Valtio 状态管理)
│ │ │ ├── hooks/ # 【UI 视图】React 自定义 Hooks
│ │ │ │ ├── useA2UI.ts # 【UI 视图】useA2UI - 获取 A2UI 应用状态
│ │ │ │ └── useA2UIComponent.ts # 【UI 视图】useA2UIComponent - 获取单个组件状态
│ │ │ ├── registry/ # 【核心基建】组件注册表
│ │ │ │ ├── ComponentRegistry.ts # 【核心基建】组件注册表 (支持动态注册)
│ │ │ │ └── defaultCatalog.ts # 【核心基建】默认 React 组件目录
│ │ │ ├── theme/ # 【UI 视图】主题系统
│ │ │ │ ├── ThemeContext.tsx # 【UI 视图】主题上下文 (支持自适应)
│ │ │ │ ├── litTheme.ts # 【UI 视图】Lit 主题兼容层 (与 Lit 渲染器共享主题)
│ │ │ │ └── utils.ts # 【工具集】主题工具函数
│ │ │ ├── styles/ # 【UI 视图】CSS-in-JS 样式
│ │ │ │ ├── index.ts # 【UI 视图】样式聚合导出
│ │ │ │ └── reset.ts # 【UI 视图】浏览器样式重置
│ │ │ └── lib/ # 【工具集】工具库
│ │ │ └── utils.ts # 【工具集】通用工具函数
│ │ └── v0_9/ # 【业务模块】v0.9 React 实现 (新架构)
│ │ ├── A2uiSurface.tsx # 【UI 视图】A2uiSurface - v0.9 React Surface 组件
│ │ ├── adapter.tsx # 【核心基建】React → GenericBinder 适配器 (createReactComponent)
│ │ └── index.ts # 【核心基建】v0.9 React 公开 API
│ ├── angular/ # 【业务模块】Angular 渲染器 (基于 Angular Standalone Components)
│ ├── flutter/ # 【业务模块】Flutter 渲染器 (Dart) - GenUI SDK 底层
│ │ └── pubspec.yaml # 【配置】Flutter 包配置
│ ├── markdown/ # 【业务模块】Markdown 渲染器 (生成纯 Markdown 输出)
│ ├── docs/ # 【配置】渲染器内部文档
│ └── scripts/ # 【工具集】渲染器构建与发布脚本
│
├── tools/ # 【工具集】A2UI 开发辅助工具链
│ ├── composer/ # 【业务模块】A2UI Composer - 可视化 JSON 编辑器 (Next.js 14 App Router)
│ │ ├── src/
│ │ │ ├── app/ # 【UI 视图】Next.js App Router
│ │ │ │ ├── page.tsx # 【UI 视图】主编辑器页面 (拖拽式组件构建)
│ │ │ │ └── layout.tsx # 【UI 视图】应用布局
│ │ │ ├── lib/ # 【核心基建】编辑器核心逻辑
│ │ │ │ ├── components-data.ts # 【核心基建】v0.8 组件定义与元数据 (1115行)
│ │ │ │ ├── components-data-v09.ts # 【核心基建】v0.9 组件定义与元数据 (1052行)
│ │ │ │ ├── transcoder.ts # 【核心基建】v0.8 <-> v0.9 版本双向转码器
│ │ │ │ ├── a2ui.tsx # 【核心基建】A2UI JSON 生成逻辑
│ │ │ │ ├── json-parser.ts # 【工具集】JSON 解析与验证
│ │ │ │ ├── storage.ts # 【核心基建】localStorage 持久化
│ │ │ │ ├── utils.ts # 【工具集】通用工具函数
│ │ │ │ ├── v09Viewer.tsx # 【UI 视图】v0.9 JSON 预览组件
│ │ │ │ └── viewerTheme.ts # 【UI 视图】预览区主题配置
│ │ │ ├── contexts/ # 【核心基建】React Context (SpecVersion, Widgets)
│ │ │ │ ├── spec-version-context.tsx # 【核心基建】协议版本切换上下文
│ │ │ │ └── widgets-context.tsx # 【核心基建】Widget 状态管理上下文
│ │ │ ├── data/theater/ # 【配置】Theater 预构建场景 JSON (demo 数据)
│ │ │ │ ├── restaurant-finder.json # 【配置】餐厅查找场景
│ │ │ │ ├── booking-form.json # 【配置】预订表单场景
│ │ │ │ ├── weather-widget.json # 【配置】天气组件场景
│ │ │ │ ├── flight-status.json # 【配置】航班状态场景
│ │ │ │ ├── contact-card.json # 【配置】联系人卡片场景
│ │ │ │ ├── kitchen-sink.json # 【配置】全组件展示场景
│ │ │ │ ├── component-gallery-stream.json # 【配置】组件流式渲染场景
│ │ │ │ └── floor-plan.json # 【配置】楼层平面图场景
│ │ │ ├── types/ # 【核心基建】TypeScript 类型定义
│ │ │ │ └── widget.ts # 【核心基建】Widget 节点类型 (树形 + 属性)
│ │ │ └── test/ # 【质量保证】测试
│ │ └── package.json # 【配置】Composer 包配置
│ ├── inspector/ # 【业务模块】A2UI Inspector - 运行时调试工具
│ │ └── package.json # 【配置】Inspector 包配置
│ ├── editor/ # 【业务模块】A2UI Editor - Web 代码编辑器
│ │ └── package.json # 【配置】Editor 包配置
│ └── build_catalog/ # 【工具集】Catalog 构建工具
│
├── samples/ # 【业务模块】示例项目集合
│ ├── agent/adk/ # 【业务模块】ADK Agent 示例 (Python)
│ │ ├── restaurant_finder/ # 【业务模块】餐厅查找 - 主力 Demo (Gemini API 驱动)
│ │ ├── personalized_learning/ # 【业务模块】个性化学习 - 教育场景 Demo
│ │ ├── orchestrator/ # 【业务模块】多 Agent 编排 - 远程子 Agent 场景
│ │ ├── rizzcharts/ # 【业务模块】图表生成 Demo
│ │ ├── custom-components-example/ # 【业务模块】自定义组件目录示例
│ │ ├── mcp-apps-in-a2ui-sample/ # 【业务模块】MCP Apps 集成示例
│ │ ├── mcp_app_proxy/ # 【业务模块】MCP 代理示例
│ │ └── gemini_enterprise/ # 【业务模块】Gemini Enterprise 示例
│ ├── client/ # 【业务模块】客户端示例
│ │ ├── lit/ # 【UI 视图】Lit 客户端 (主力)
│ │ │ ├── shell/ # 【UI 视图】Shell 应用 (app.ts 932行)
│ │ │ ├── custom-components-example/ # 【业务模块】自定义组件客户端
│ │ │ ├── personalized_learning/ # 【业务模块】个性化学习客户端 (含 api-server)
│ │ │ └── mcp-apps-in-a2ui-sample/ # 【业务模块】MCP Apps 客户端
│ │ ├── react/shell/ # 【UI 视图】React Shell 应用
│ │ ├── angular/ # 【UI 视图】Angular 示例
│ │ ├── flutter/restaurant_finder/ # 【UI 视图】Flutter 餐厅查找 (GenUI 集成)
│ │ └── shared/ # 【工具集】共享资源 (MCP inner iframe)
│ └── mcp/ # 【业务模块】MCP 协议集成示例
│ ├── a2ui-over-mcp-recipe/ # 【业务模块】A2UI over MCP - 完整双向集成
│ ├── a2ui-in-mcpapps/ # 【业务模块】MCP Apps 中的 A2UI - 应用内嵌入
│ └── mcp-apps-calculator/ # 【业务模块】MCP 计算器 - 简单示例
│
├── eval/ # 【质量保证】评估框架 (Agent 生成质量评估)
│ ├── a2ui_eval/ # 【核心基建】评估核心库 (Python)
│ ├── datasets/ # 【质量保证】标准测试数据集
│ ├── tests/ # 【质量保证】评估框架测试
│ └── bin/ # 【工具集】评估执行脚本
│
├── docs/ # 【配置】MkDocs Material 文档站点 (a2ui.org)
│ ├── introduction/ # 【配置】介绍文档 (What/Who/How/Compare)
│ ├── concepts/ # 【配置】核心概念 (Data Flow/Components/Data Binding/Catalogs/Transports)
│ ├── guides/ # 【配置】开发者指南 (Client Setup/Agent Dev/Renderer Dev/MCP 集成)
│ ├── reference/ # 【配置】API 参考 (Component Gallery/Message Reference/Renderers)
│ ├── specification/ # 【配置】规范文档副本
│ ├── ecosystem/ # 【配置】生态介绍 (Community/Community Renderers)
│ ├── assets/ # 【配置】文档静态资源 (SVG/PNG)
│ ├── stylesheets/ # 【配置】自定义 CSS
│ └── scripts/ # 【工具集】文档生成脚本
│
├── scripts/ # 【工具集】项目级脚本
│ └── fix_format.sh # 【工具集】全仓库格式化 (Prettier + Pyink + dart format)
│
├── .github/ # 【配置】GitHub CI/CD
│ ├── workflows/ # 【配置】GitHub Actions 工作流
│ └── ISSUE_TEMPLATE/ # 【配置】Issue 模板
│
├── .gemini/ # 【配置】Gemini CLI 配置
│
├── README.md # 【配置】项目主页 (英文)
├── CONTRIBUTING.md # 【配置】贡献指南 (CLA + 编码规范)
├── LICENSE # 【配置】Apache 2.0 许可证
├── mkdocs.yaml # 【配置】MkDocs 文档站点配置
├── pubspec.yaml # 【配置】Flutter (Dart) 项目配置
├── hooks.py # 【配置】MkDocs 自定义钩子 (文档预处理)
├── analysis_options.yaml # 【配置】Dart 代码分析规则
└── requirements-docs.txt # 【配置】Python 文档构建依赖3. 模块依赖与调用关系
3.1 全局入口与核心路由
逻辑说明：A2UI 的数据流从 Agent（如 Google ADK）开始，Agent 通过 Python/Kotlin SDK 的 SchemaManager 构建 LLM 系统提示词，LLM 生成 A2UI JSON 消息流，经过 StreamParser 解析验证后，通过 A2A/AG UI/MCP 传输协议发送到客户端。客户端 MessageProcessor 接收消息，根据消息类型（createSurface / updateComponents / updateDataModel / deleteSurface）分发到对应的 Surface 状态模型，状态变更通过 Signal 响应式系统自动传播到 UI 组件。
调用拓扑 (plainText)：
text
Agent Application (e.g., ADK Agent)
+---> A2uiSchemaManager.generate_system_prompt()
+---> LLM (Gemini/Other) generates A2UI JSON stream
+---> A2uiStreamParser.process_chunk()
+---> (版本判断) A2uiStreamParserV08 | A2uiStreamParserV09
+---> (验证) JsonSchemaValidator
+---> (产出) ResponsePart events
|
Transport (A2A / AG UI / MCP) <----+
|
+---> Client: MessageProcessor.processMessages()
|
+---> [createSurface] --> SurfaceGroupModel.addSurface()
| +---> Catalog lookup
| +---> SurfaceModel 创建
|
+---> [updateComponents] --> SurfaceModel.componentsModel
| +---> ComponentModel 创建/更新
| +---> 触发 onUpdated 事件
|
+---> [updateDataModel] --> SurfaceModel.dataModel.set()
| +---> Signal 更新
| +---> 通知订阅者 (ancestors/descendants)
|
+---> [deleteSurface] --> SurfaceGroupModel.deleteSurface()
Renderer-Specific Adapter (Lit/React/Angular/Flutter)
+---> GenericBinder.subscribe()
+---> resolveAndBind() (遍历 BehaviorNode 树)
+---> 订阅 DataContext 动态路径
+---> 产出 ResolvedProps --> UI Component re-render3.2 核心业务实体与关联
实体定义：
- Surface：UI 画布。代表一个独立的 UI 渲染区域（如对话框、侧边栏、主视图）。一个应用可以同时存在多个 Surface。
- Component：UI 元素。包括 Button、Text、Card、TextField 等。每个 Component 有唯一的 id、类型（如 "Text"）、属性集合，通过 id 引用形成组件树。
- DataModel：应用状态。采用 JSON Pointer (RFC 6901) 路径寻址的响应式树形数据结构。组件通过 path 绑定到数据模型的特定位置，数据更新自动触发 UI 更新。
- Catalog：组件目录。定义客户端支持的组件类型集合、每个组件的 Schema（使用 Zod/JSON Schema 描述属性）、可用函数和主题定义。
- Message：A2UI 协议消息。有四种核心消息类型：
createSurface、updateComponents、updateDataModel、deleteSurface。
实体引用拓扑 (plainText)：
text
[Catalog] 1 <----> N [ComponentApi]
| |
| (defines) | (describes schema for)
| v
| [Component] (generic)
|
+-------> [Surface] 1 -----> N [Component] (instance)
| |
| (has) | (binds to)
v v
[DataModel] 1 <-----> N [Data Binding (path)]
|
| (notifies via)
v
[Signal (Preact Signals)]
|
| (updates)
v
[UI Component (Lit/React/etc.)]
|
| (triggers)
v
[Action] ----> [Agent] (event callback)4. 核心模块详解
模块一：MessageProcessor (消息处理器)
模块名称：MessageProcessor - A2UI 消息处理核心
设计说明：MessageProcessor 是客户端的消息分发中枢，采用观察者模式。它接收 A2UI JSON 消息数组，根据消息类型字段（createSurface/updateComponents/updateDataModel/deleteSurface）分发到不同的处理流程。它维护 SurfaceGroupModel 作为全局状态管理器，并管理 Catalog 注册表和 Action 回调。核心设计特点是消息可以增量到达（支持流式传输），每个消息只修改状态的一部分，通过 Preact Signals 实现的响应式系统自动传播变更到订阅的 UI 组件。
内部结构图 (plainText)：
text
+----------------------------------------+
| MessageProcessor<T> |
| (消息分发中枢 / Observer Pattern) |
+-----+--------+--------+---------+-----+
| | | |
v v v v
+--------+ +--------+ +--------+ +--------+
|Create | |Update | |Update | |Delete |
|Surface | |Comps | |Data | |Surface |
+--------+ +--------+ +--------+ +--------+
| | | |
v v v v
+========================================+
| SurfaceGroupModel<T> |
| +----------------------------------+ |
| | surfacesMap: Map<string, Surface> | |
| +----------------------------------+ |
| | onSurfaceCreated / onSurfaceDeleted| |
| | onAction (Event Emitter) | |
| +----------------------------------+ |
+========================================+
|
| (每个 Surface 包含)
v
+----------------------------------------+
| SurfaceModel<T> |
| +----------------+ +---------------+ |
| |ComponentsModel | | DataModel | |
| |(组件注册表) | | (JSON Pointer) | |
| +----------------+ +---------------+ |
| | Catalog<T> | | sendDataModel | |
| +----------------+ +---------------+ |
+----------------------------------------+模块二：DataModel (响应式数据模型)
模块名称：DataModel - 响应式状态管理
设计说明：DataModel 是 A2UI 客户端的核心状态管理模块，基于 JSON Pointer (RFC 6901) 路径寻址，使用 Preact Signals 实现细粒度响应式更新。支持路径的 CRUD 操作、父子路径的级联通知（修改子路径时通知所有祖先路径的订阅者）、Signal 缓存和惰性初始化。设计模式上采用了发布-订阅模式，外部通过
subscribe(path, callback)订阅特定路径的变更，内部通过signal(path)管理响应式原语。内部结构图 (plainText)：
text
+--------------------------------------------+
| DataModel |
| (基于 JSON Pointer + Preact Signals) |
+--------------------------------------------+
| data: Record<string, unknown> |
| signals: Map<string, Signal<any>> |
| subscriptions: Set<() => void> |
+------------------+-------------------------+
|
+--------------+--------------+
| | |
v v v
+--------+ +----------+ +-----------+
| set() | | get() | |subscribe()|
| path: | | path: | | path: |
| string | | string | | string |
| value: | | returns | | callback |
| any | | any|undef| | returns |
+--------+ +----------+ | DataSub |
| +-----------+
| |
v v
+--------------------------------------------+
| notifySignals(path) |
| (级联通知机制) |
| 1. updateSignal(targetPath) |
| 2. Notify all ancestor paths (向上冒泡) |
| 3. Notify all descendant paths (向下广播) |
+--------------------------------------------+
|
v
+--------------------------------------------+
| Preact Signals (signal / batch / effect) |
| - signal(): 创建响应式原语 |
| - batch(): 批量更新优化 |
| - effect(): 副作用订阅 |
+--------------------------------------------+模块三：GenericBinder (通用数据绑定引擎)
模块名称：GenericBinder - Schema 驱动的响应式数据绑定
设计说明：GenericBinder 是 A2UI v0.9 的核心创新模块，采用 策略模式 + 行为树遍历 的设计。它通过
scrapeSchemaBehavior()分析 Zod Schema，自动识别属性类型（DYNAMIC/ACTION/STRUCTURAL/CHECKABLE/STATIC），无需为每个组件硬编码属性处理逻辑。DYNAMIC 类型自动订阅 DataModel 更新，ACTION 类型生成可执行闭包函数，STRUCTURAL 类型管理子组件列表。这是一种元编程方法——Schema 即是行为配置。内部结构图 (plainText)：
text
+--------------------------------------------+
| GenericBinder<T> |
| (Schema-Driven Reactive Binding Engine) |
+--------------------------------------------+
| context: ComponentContext |
| behaviorTree: BehaviorNode |
| currentProps: Partial<T> |
+------------------+-------------------------+
|
v
+--------------------------------------------+
| scrapeSchemaBehavior(schema) |
| (Zod Schema --> BehaviorNode Tree) |
+--------------------------------------------+
| 识别规则: |
| - ZodUnion + { event: ... } --> ACTION |
| - ZodUnion + { path: ... } --> DYNAMIC |
| - ZodUnion + { componentId, path } --> STRUCTURAL |
| - propertyName === 'checks' --> CHECKABLE |
| - ZodObject --> OBJECT (递归) |
| - ZodArray --> ARRAY (递归) |
| - Fallback --> STATIC |
+------------------+-------------------------+
|
v
+--------------------------------------------+
| resolveAndBind(value, behavior) |
| (行为驱动的属性解析) |
+--------------------------------------------+
| |
| DYNAMIC ----> subscribeDynamicValue() |
| 返回当前值 + 自动重订阅 |
| |
| ACTION ----> () => dispatchAction() |
| 生成可执行闭包 |
| |
| STRUCTURAL --> subscribeDynamicValue() |
| 生成子组件列表 [{id, basePath}] |
| |
| CHECKABLE --> 验证规则数组 |
| 注入 isValid / validationErrors |
| |
| OBJECT/ARRAY --> 递归遍历子节点 |
| |
| STATIC ----> 原值返回 |
+--------------------------------------------+
|
v
+--------------------------------------------+
| subscribe(listener) / notify() |
| (Observer Pattern 通知视图更新) |
+--------------------------------------------+模块四：A2uiStreamParser (流式解析器)
模块名称：A2uiStreamParser - 流式 JSON 解析
设计说明：A2uiStreamParser 是 Agent 端的核心流式解析引擎，采用工厂模式根据 Catalog 版本创建对应的解析器实例（V08/V09）。主要挑战是处理 LLM 流式输出时 JSON 可能不完整的情况——解析器需要缓存不完整的 chunk，支持自动修复截断的字符串值（CUTTABLE_KEYS 机制），以及容错处理。解析结果以 ResponsePart 事件形式产出，支持逐组件的渐进式渲染。
内部结构图 (plainText)：
text
+--------------------------------------------+
| A2uiStreamParser (Factory) |
| catalog.version === 'v0.9' ? V09 : V08 |
+------------------+-------------------------+
|
+---------+---------+
| |
v v
+------------------+ +------------------+
| StreamParserV08 | | StreamParserV09 |
+------------------+ +------------------+
| _buffer: str | | _buffer: str |
| _component_state | | _state: Enum |
| _depth: int | | (INIT/IN_MESSAGE|
| | | /IN_COMPONENTS/ |
| | | IN_ARRAY) |
+--------+---------+ +--------+---------+
| |
v v
+--------------------------------------------+
| process_chunk(chunk: str) |
| 1. 追加 chunk 到 buffer |
| 2. 尝试提取完整的 JSON 行/块 |
| 3. 对不完整部分尝试 auto-heal (CUTTABLE) |
| 4. 逐行解析为 dict |
| 5. 通过 JsonSchemaValidator 验证 |
| 6. 产出 ResponsePart(createSurface | |
| updateComponents | updateDataModel | |
| deleteSurface) |
+--------------------------------------------+
|
v
+--------------------------------------------+
| ResponsePart (事件对象) |
| - type: MessageType |
| - data: dict (完整消息体) |
| - component_id?: str (单组件事件) |
| - is_partial?: bool (流式中间状态) |
+--------------------------------------------+模块五：Catalog System (组件目录系统)
模块名称：Catalog System - 组件目录注册与协商
设计说明：Catalog System 是 A2UI 安全模型的基石，采用策略模式 + 适配器模式。Agent 端维护支持的 Catalog 列表，客户端声明其能力（
A2uiClientCapabilities），双方通过supportedCatalogIds协商选择共同支持的组件集。支持内联目录（Inline Catalog）——客户端可以将自定义组件的 JSON Schema 内联发送给 Agent，Agent 端的 LLM 即可理解并使用这些自定义组件。目录选择遵循三级优先级：内联目录 > 客户端支持的目录 ID > Agent 默认目录。内部结构图 (plainText)：
text
+--------------------------------------------+
| A2uiSchemaManager |
| (Agent 端 Schema 管理器) |
+--------------------------------------------+
| _version: str |
| _supported_catalogs: list[A2uiCatalog] |
| _accepts_inline_catalogs: bool |
+------------------+-------------------------+
|
v
+--------------------------------------------+
| _select_catalog(capabilities) |
| 目录选择优先级: |
| 1. Inline Catalogs (客户端内联) |
| --> merge with base catalog |
| 2. supportedCatalogIds (客户端声明) |
| --> first mutual match |
| 3. Agent default catalog (服务端默认) |
+------------------+-------------------------+
|
v
+--------------------------------------------+
| A2uiCatalog |
| +--------------------------------------+ |
| | catalog_id: str | |
| | components: dict (组件定义) | |
| | functions: list (可用函数) | |
| | theme_schema: dict (主题定义) | |
| +--------------------------------------+ |
| | render_as_llm_instructions() -> str | |
| | load_examples() -> str | |
| | with_pruning() -> A2uiCatalog | |
| +--------------------------------------+ |
+--------------------------------------------+
^
| (客户端侧)
+--------------------------------------------+
| MessageProcessor.getClientCapabilities() |
| - supportedCatalogIds: string[] |
| - inlineCatalogs?: InlineCatalog[] |
| (包含完整 JSON Schema 定义) |
+--------------------------------------------+5. 关键数据流程
场景说明：这是一个完整的 A2UI 交互生命周期——用户提出"帮我找附近的意大利餐厅"，Agent 生成餐厅搜索 UI，用户填写偏好后提交，Agent 更新搜索结果 UI。此流程覆盖了 A2UI 的所有核心消息类型（createSurface, updateComponents, updateDataModel, 用户 Action 回调）以及响应式数据绑定的完整链路。
- 流转时序图 (Mermaid)：
6. 接口与契约规范
6.1 核心内部模块契约 (TypeScript)
typescript
/**
* A2UI v0.9 消息联合类型
* Agent 可以发送以下四种消息之一
*/
export type A2uiMessage =
| CreateSurfaceMessage // 创建渲染 Surface
| UpdateComponentsMessage // 更新组件列表
| UpdateDataModelMessage // 更新数据模型
| DeleteSurfaceMessage; // 删除 Surface
/**
* 消息处理器核心接口
* 负责接收、验证并分发 A2UI 消息到对应的状态模型
*/
export interface IMessageProcessor<T extends ComponentApi> {
/** 处理一批 A2UI 消息 */
processMessages(messages: A2uiMessage[] | A2uiMessageListWrapper): void;
/** 获取客户端能力声明（用于与 Agent 协商目录） */
getClientCapabilities(options?: CapabilitiesOptions): A2uiClientCapabilities;
/** 获取启用了 sendDataModel 的 Surface 的聚合数据模型 */
getClientDataModel(): A2uiClientDataModel | undefined;
/** 订阅 Surface 创建事件 */
onSurfaceCreated(handler: (surface: SurfaceModel<T>) => void): Subscription;
/** 订阅 Surface 删除事件 */
onSurfaceDeleted(handler: (id: string) => void): Subscription;
}
/**
* 响应式数据模型接口
* 基于 JSON Pointer (RFC 6901) 路径寻址
*/
export interface IDataModel {
/** 写入数据到指定路径，自动通知订阅者 */
set(path: string, value: any): this;
/** 读取指定路径的数据 */
get<T = any>(path: string): T | undefined;
/** 订阅路径变更，返回包含当前值和取消订阅方法的对象 */
subscribe<T>(path: string, onChange: (value: T | undefined) => void): DataSubscription<T>;
/** 获取路径对应的 Signal（惰性创建） */
getSignal<T>(path: string): Signal<T | undefined>;
/** 清理所有订阅 */
dispose(): void;
}
/**
* Surface 模型接口
* 代表一个独立的 UI 渲染区域
*/
export interface ISurfaceModel<T extends ComponentApi> {
readonly id: string;
readonly catalog: Catalog<T>;
readonly componentsModel: ComponentsModel<T>;
readonly dataModel: DataModel;
readonly sendDataModel: boolean;
/** 设置主题参数 */
setTheme(theme: Record<string, unknown>): void;
/** 销毁 Surface */
dispose(): void;
}
/**
* 通用数据绑定引擎接口
* 将 A2UI JSON 属性转换为响应式 props
*/
export interface IGenericBinder<T> {
/** 当前已解析的 props 快照 */
readonly currentProps: Partial<T>;
/** 获取同步快照 */
readonly snapshot: T;
/** 订阅 props 变更 */
subscribe(listener: (props: T) => void): { unsubscribe: () => void };
/** 销毁所有监听 */
dispose(): void;
}
/**
* Actions 监听器
* 处理用户在 A2UI Surface 上的交互事件
*/
export type ActionListener = (
surfaceId: string,
actionName: string,
payload: Record<string, unknown>
) => void;6.2 对外 API 契约 (A2UI v0.9 核心消息 Schema)
yaml
# A2UI v0.9 核心消息类型 — OpenSpec/YAML 格式
components:
schemas:
CreateSurface:
type: object
required: [version, createSurface]
properties:
version:
type: string
enum: ["v0.9"]
createSurface:
type: object
required: [surfaceId, catalogId]
properties:
surfaceId:
type: string
description: UI Surface 的唯一标识符
catalogId:
type: string
description: 组件目录的唯一标识符
theme:
type: object
description: 可选的 Surface 级主题参数
sendDataModel:
type: boolean
description: 若为 true，客户端将在每次数据更新时发送完整数据模型
UpdateComponents:
type: object
required: [version, updateComponents]
properties:
version:
type: string
enum: ["v0.9"]
updateComponents:
type: object
required: [surfaceId, components]
properties:
surfaceId:
type: string
description: 目标 Surface 的唯一标识符
components:
type: array
minItems: 1
items:
$ref: '#/components/schemas/Component'
description: 该 Surface 的所有 UI 组件列表
UpdateDataModel:
type: object
required: [version, updateDataModel]
properties:
version:
type: string
enum: ["v0.9"]
updateDataModel:
type: object
required: [surfaceId]
properties:
surfaceId:
type: string
description: 目标 Surface 的唯一标识符
path:
type: string
description: JSON Pointer 路径，默认为根路径 "/"
value:
description: 要更新的数据值
DeleteSurface:
type: object
required: [version, deleteSurface]
properties:
version:
type: string
enum: ["v0.9"]
deleteSurface:
type: object
required: [surfaceId]
properties:
surfaceId:
type: string
description: 要删除的 Surface 唯一标识符
ClientCapabilities:
type: object
required: [v0.9]
properties:
v0.9:
type: object
required: [supportedCatalogIds]
properties:
supportedCatalogIds:
type: array
items:
type: string
description: 客户端支持的目录 ID 列表
inlineCatalogs:
type: array
items:
$ref: '#/components/schemas/InlineCatalog'
description: 客户端内联提供的完整目录定义7. 快速开始
7.1 环境配置
- Node.js 18+
- Python 3.10+ (推荐使用 uv)
- Gemini API Key (用于 Restaurant Finder Demo)
7.2 安装与运行
bash
git clone https://github.com/google/A2UI.git
cd A2UI
export GEMINI_API_KEY="your_gemini_api_key"
cd samples/client/lit
npm run demo:restaurant启动后访问 http://localhost:5173 即可体验完整的 A2UI 餐厅查找应用。
7.3 典型用例
| 路径 | 说明 | 时间 |
|---|---|---|
| Quickstart Demo | 完整 A2UI 本地运行 (Gemini + ADK + Lit) | ~5 分钟 |
| A2UI + AG-UI (CopilotKit) | 将 A2UI 集成到现有 Agent 框架 | ~5 分钟 |
| A2UI Composer | 可视化构建 A2UI JSON | ~1 分钟 |
| A2UI Theater | 预构建的流式渲染场景浏览 | ~1 分钟 |