diff --git a/docs/zh/agents.md b/docs/zh/agents.md new file mode 100644 index 00000000..8c6d449c --- /dev/null +++ b/docs/zh/agents.md @@ -0,0 +1,54 @@ +# 智能体 (服务端) + +智能体是服务端程序，负责响应用户请求生成 A2UI 消息。 + +实际的组件渲染由 [渲染器](renderers.md) 完成， +在消息传输到客户端之后 [传输](transports.md)。 +智能体仅负责生成 A2UI 消息。 + +## 智能体如何工作 + +``` +用户输入 → 智能体逻辑 → LLM → A2UI JSON → 发送到客户端 +``` + +1. **接收** 用户消息 +2. **处理** 使用 LLM (Gemini, GPT, Claude 等) +3. **生成** A2UI JSON 消息作为结构化输出 +4. **发送** 到客户端通过传输 + +来自客户端的用户交互可以被视为新的用户输入。 + +## 示例智能体 + +A2UI 仓库包含您可以以此学习的示例智能体： + +- [餐厅查找器](https://github.com/google/A2UI/tree/main/samples/agent/adk/restaurant_finder) + - 带有表单的餐桌预订 + - 使用 ADK 编写 +- [联系人查找](https://github.com/google/A2UI/tree/main/samples/agent/adk/contact_lookup) + - 带有结果列表的搜索 + - 使用 ADK 编写 +- [Rizzcharts](https://github.com/google/A2UI/tree/main/samples/agent/adk/rizzcharts) + - A2UI 自定义组件演示 + - 使用 ADK 编写 +- [Orchestrator](https://github.com/google/A2UI/tree/main/samples/agent/adk/orchestrator) + - 从远程子智能体传递 A2UI 消息 + - 使用 ADK 编写 + +## 您将使用 A2A 的不同类型的智能体 + +### 1. 面向用户的智能体 (独立) + +面向用户的智能体是用户直接交互的智能体。 + +### 2. 作为远程智能体宿主的面向用户的智能体 + +这是一种模式，其中面向用户的智能体充当一个或多个远程智能体的宿主。面向用户的智能体将调用远程智能体，远程智能体将生成 A2UI 消息。这是 [A2A](https://a2a-protocol.org) 中的常见模式，客户端智能体调用服务器智能体。 + +- 面向用户的智能体可以“透传” A2UI 消息而不进行更改 +- 面向用户的智能体可以在将 A2UI 消息发送到客户端之前对其进行更改 + +### 3. 远程智能体 + +远程智能体不直接是面向用户 UI 的一部分。相反，它被注册为远程智能体，可以由面向用户的智能体调用。这是 [A2A](https://a2a-protocol.org) 中的常见模式，客户端智能体调用服务器智能体。 diff --git a/docs/zh/community.md b/docs/zh/community.md new file mode 100644 index 00000000..6c27275c --- /dev/null +++ b/docs/zh/community.md @@ -0,0 +1,86 @@ +# 社区 + +欢迎来到 A2UI 社区！我们要共同构建智能体驱动界面的未来。 + +## 参与其中 + +A2UI 是一个基于 Apache 2.0 协议的开源项目。我们欢迎开发者、研究人员以及任何对推动智能体式用户界面感兴趣的人士参与贡献。 + +## 社区展示 + +!!! info "即将推出..." + 我们正在考虑通过何种最佳方式来展示社区项目、示例、主题、渲染器、自定义组件等。在 Github discussions 中链接一个 4 分钟（或更短）的演示视频和代码示例是展示您作品的绝佳方式。 + +## 项目合作伙伴 + +A2UI 是与多个组织合作开发的： + +### Google Opal + +[Opal](http://opal.google) 让用户使用自然语言构建、编辑和分享 AI 小程序。Opal 团队一直是 A2UI 开发的核心贡献者。 + +### Flutter + +[GenUI SDK for Flutter](https://docs.flutter.dev/ai/genui) 使用 A2UI 作为 UI 声明格式，用于在 Flutter 应用程序中生成动态、个性化的 UI。 + +### Gemini Enterprise + +A2UI 正在被集成到 [Gemini Enterprise](https://cloud.google.com/gemini-enterprise?e=48754805) 中，以支持自定义智能体在企业应用程序中渲染丰富、交互式的 UI。 + +### AG UI / CopilotKit + +[AG UI](https://ag-ui.com/) 和 [CopilotKit](https://www.copilotkit.ai/) 提供了对 A2UI 的零日兼容性，使开发人员能够构建富文本、状态同步的应用程序，从智能体中渲染动态 UI。 + +### A2A + +Google 的 [A2A 团队](https://a2a-protocol.org/) 一直是 A2UI 开发的核心贡献者，并得到了 A2A 技术指导委员会 (TSC) 的支持。 + +### ... 还有更多 + +还有许多组织和个人为 A2UI 的开发做出了贡献。 + +如果您对 A2UI 做出了重大贡献，请将您的名字提交到此列表。 + +## 行为准则 + +我们致力于为每个人提供一个受欢迎且包容的环境。所有参与者都应遵循以下原则： + +- 尊重并体贴他人 +- 欢迎不仅仅是新人，并帮助他们入门 +- 关注对社区最有利的事情 +- 对他人表现出同理心 + +我们绝不容忍不可接受的行为。请向项目维护者报告疑虑。 + +## 认可 + +我们感谢所有的贡献！贡献者将在以下地方得到认可： + +- GitHub 的贡献者图表 +- 发布说明 +- 项目致谢 + +重大贡献者可能会被邀请加入项目的维护者团队。 + +## 保持更新 + +- **关注 (Watch) GitHub 仓库** 以获取通知 +- **星标 (Star) 仓库** 以加入书签并表示支持 +- **关注发布 (Follow releases)** 以获取新版本的通知 + +## 贡献方式 + +**[github.com/google/A2UI](https://github.com/google/A2UI)** + +- **报告问题**：发现了 bug？[提交 Issue](https://github.com/google/A2UI/issues) +- **构建渲染器**：查看[路线图](roadmap.md)以了解计划中的框架 +- **分享示例**：在 X/LinkedIn 上使用 `#A2UI` 发布，或者发起一个 [Discussion](https://github.com/google/A2UI/discussions) +- **改进文档**：欢迎向 `docs/` 目录提交 PR + +## 有问题？ + +- 查看 [文档](introduction/what-is-a2ui.md) +- 搜索 [GitHub Discussions](https://github.com/google/A2UI/discussions) +- 在 [GitHub Issues](https://github.com/google/A2UI/issues) 中提问 + +感谢您成为 A2UI 社区的一员！ diff --git a/docs/zh/composer.md b/docs/zh/composer.md new file mode 100644 index 00000000..5fc3e36c --- /dev/null +++ b/docs/zh/composer.md @@ -0,0 +1,16 @@ +# A2UI Composer + +尝试使用 **CopilotKit A2UI Widget Builder** 交互式地构建 A2UI widgets。 + +[![A2UI Composer](../assets/A2UI-widget-builder.png)](https://go.copilotkit.ai/A2UI-widget-builder) + +**[启动 Widget Builder →](https://go.copilotkit.ai/A2UI-widget-builder)** + +## 功能 + +- 可视化地试验 A2UI 组件 +- 通过描述您想要的内容来生成 A2UI JSON +- 查看实时预览 +- 复制 JSON 以在您的智能体中使用 + +由 [CopilotKit](https://www.copilotkit.ai/) 团队构建。 diff --git a/docs/zh/concepts/components.md b/docs/zh/concepts/components.md new file mode 100644 index 00000000..be8ddd74 --- /dev/null +++ b/docs/zh/concepts/components.md @@ -0,0 +1,122 @@ +# 组件与结构 + +A2UI 使用 **邻接表模型** 来表示组件层次结构。组件不是嵌套的 JSON 树，而是带有 ID 引用的扁平列表。 + +## 为什么是扁平列表？ + +**传统的嵌套方法：** + +- LLM 必须一次性生成完美的嵌套 +- 难以更新深层嵌套的组件 +- 难以增量流式传输 + +**A2UI 邻接表：** + +- ✅ 扁平结构，易于 LLM 生成 +- ✅ 增量发送组件 +- ✅ 通过 ID 更新任何组件 +- ✅ 清晰的结构与数据分离 + +## 邻接表模型 + +```json +{ + "surfaceUpdate": { + "components": [ + {"id": "root", "component": {"Column": {"children": {"explicitList": ["greeting", "buttons"]}}}}, + {"id": "greeting", "component": {"Text": {"text": {"literalString": "Hello"}}}}, + {"id": "buttons", "component": {"Row": {"children": {"explicitList": ["cancel-btn", "ok-btn"]}}}}, + {"id": "cancel-btn", "component": {"Button": {"child": "cancel-text", "action": {"name": "cancel"}}}}, + {"id": "cancel-text", "component": {"Text": {"text": {"literalString": "Cancel"}}}}, + {"id": "ok-btn", "component": {"Button": {"child": "ok-text", "action": {"name": "ok"}}}}, + {"id": "ok-text", "component": {"Text": {"text": {"literalString": "OK"}}}} + ] + } +} +``` + +组件通过 ID 引用子级，而不是通过嵌套。 + +## 组件基础 + +每个组件都有： + +1. **ID**: 唯一标识符 (`"welcome"`) +2. **Type**: 组件类型 (`Text`, `Button`, `Card`) +3. **Properties**: 特定于该类型的配置 + +```json +{"id": "welcome", "component": {"Text": {"text": {"literalString": "Hello"}, "usageHint": "h1"}}} +``` + +## 标准目录 + +A2UI 定义了一个按用途组织的标准组件目录： + +- **布局 (Layout)**: Row, Column, List - 排列其他组件 +- **显示 (Display)**: Text, Image, Icon, Video, Divider - 显示信息 +- **交互 (Interactive)**: Button, TextField, CheckBox, DateTimeInput, Slider - 用户输入 +- **容器 (Container)**: Card, Tabs, Modal - 分组和组织内容 + +有关带有示例的完整组件库，请参见 [组件参考](../reference/components.md)。 + +## 静态 vs. 动态子级 + +**静态 (`explicitList`)** - 固定的子级 ID 列表： +```json +{"children": {"explicitList": ["back-btn", "title", "menu-btn"]}} +``` + +**动态 (`template`)** - 从数据数组生成子级： +```json +{"children": {"template": {"dataBinding": "/items", "componentId": "item-template"}}} +``` + +对于 `/items` 中的每个项目，渲染 `item-template`。有关详细信息，请参见 [数据绑定](data-binding.md)。 + +## 填充值 + +组件通过两种方式获取值： + +- **字面量 (Literal)** - 固定值：`{"text": {"literalString": "Welcome"}}` +- **数据绑定 (Data-bound)** - 来自数据模型：`{"text": {"path": "/user/name"}}` + +LLM 可以生成具有字面量值的组件，或者将它们绑定到数据路径以获取动态内容。 + +## 组合 Surfaces + +组件组合成 **Surfaces** (widgets)： + +1. LLM 通过 `surfaceUpdate` 生成组件定义 +2. LLM 通过 `dataModelUpdate` 填充数据 +3. LLM 通过 `beginRendering` 信号通知渲染 +4. 客户端将所有组件渲染为原生 widgets + +一个 Surface 是一个完整、紧凑的 UI（表单、仪表板、聊天等）。 + +## 增量更新 + +- **添加** - 发送带有新组件 ID 的新 `surfaceUpdate` +- **更新** - 发送带有现有 ID 和新属性的 `surfaceUpdate` +- **移除** - 更新父级的 `children` 列表以排除已移除的 ID + +扁平结构使所有更新都是简单的基于 ID 的操作。 + +## 自定义组件 + +除了标准目录之外，客户端还可以定义针对特定领域需求的自定义组件： + +- **如何做**：在您的渲染器中注册自定义组件类型 +- **什么**：图表、地图、自定义可视化、专用 widgets +- **安全性**：自定义组件仍然是客户端受信任目录的一部分 + +自定义组件从客户端的渲染器 _通告 (advertised)_ 给 LLM。然后，LLM 可以在标准目录之外使用它们。 + +有关实现细节，请参见 [自定义组件指南](../guides/custom-components.md)。 + +## 最佳实践 + +1. **描述性 ID**: 使用 `"user-profile-card"` 而不是 `"c1"` +2. **浅层级**: 避免深层嵌套 +3. **分离结构与内容**: 使用数据绑定，而不是字面量 +4. **使用模板复用**: 一个模板，通过动态子级生成许多实例 diff --git a/docs/zh/concepts/data-binding.md b/docs/zh/concepts/data-binding.md new file mode 100644 index 00000000..4e330c06 --- /dev/null +++ b/docs/zh/concepts/data-binding.md @@ -0,0 +1,132 @@ +# 数据绑定 + +数据绑定使用 JSON Pointer 路径 ([RFC 6901](https://tools.ietf.org/html/rfc6901)) 将 UI 组件连接到应用程序状态。这使得 A2UI 能够有效地为大型数据数组定义布局，或显示更新的内容而无需从头重新生成。 + +## 结构 vs. 状态 + +A2UI 分离了： + +1. **UI 结构** (组件): 界面看起来是什么样的 +2. **应用程序状态** (数据模型): 它显示什么数据 + +这使得：响应式更新、数据驱动的 UI、可重用模板和双向绑定成为可能。 + +## 数据模型 + +每个 Surface 都有一个保存状态的 JSON 对象： + +```json +{ + "user": {"name": "Alice", "email": "alice@example.com"}, + "cart": { + "items": [{"name": "Widget", "price": 9.99, "quantity": 2}], + "total": 19.98 + } +} +``` + +## JSON Pointer 路径 + +**语法：** + +- `/user/name` - 对象属性 +- `/cart/items/0` - 数组索引（从零开始） +- `/cart/items/0/price` - 嵌套路径 + +**示例：** + +```json +{"user": {"name": "Alice"}, "items": ["Apple", "Banana"]} +``` + +- `/user/name` → `"Alice"` +- `/items/0` → `"Apple"` + +## 字面量 vs. 路径值 + +**字面量 (固定):** +```json +{"id": "title", "component": {"Text": {"text": {"literalString": "Welcome"}}}} +``` + +**数据绑定 (响应式):** +```json +{"id": "username", "component": {"Text": {"text": {"path": "/user/name"}}}} +``` + +当 `/user/name` 从 "Alice" 更改为 "Bob" 时，文本 **自动更新** 为 "Bob"。 + +## 响应式更新 + +绑定到数据路径的组件会在数据更改时自动更新： + +```json +{"id": "status", "component": {"Text": {"text": {"path": "/order/status"}}}} +``` + +- **初始数据：** `/order/status` = "Processing..." → 显示 "Processing..." +- **更新：** 发送 `dataModelUpdate` 内容为 `status: "Shipped"` → 显示 "Shipped" + +无需更新组件——只需更新数据。 + +## 动态列表 + +使用模板渲染数组： + +```json +{ + "id": "product-list", + "component": { + "Column": { + "children": {"template": {"dataBinding": "/products", "componentId": "product-card"}} + } + } +} +``` + +**数据：** +```json +{"products": [{"name": "Widget", "price": 9.99}, {"name": "Gadget", "price": 19.99}]} +``` + +**结果：** 渲染两张卡片，每个产品一张。 + +### 作用域路径 + +在模板内部，路径的作用域限于数组项： + +```json +{"id": "product-name", "component": {"Text": {"text": {"path": "/name"}}}} +``` + +- 对于 `/products/0`, `/name` 解析为 `/products/0/name` → "Widget" +- 对于 `/products/1`, `/name` 解析为 `/products/1/name` → "Gadget" + +添加/移除项目会自动更新渲染的组件。 + +## 输入绑定 + +交互式组件双向更新数据模型： + +| 组件 | 示例 | 用户操作 | 数据更新 | +|-----------|---------|-------------|-------------| +| **TextField** | `{"text": {"path": "/form/name"}}` | 输入 "Alice" | `/form/name` = "Alice" | +| **CheckBox** | `{"value": {"path": "/form/agreed"}}` | 勾选复选框 | `/form/agreed` = true | +| **MultipleChoice** | `{"selections": {"path": "/form/country"}}` | 选择 "Canada" | `/form/country` = ["ca"] | + +## 最佳实践 + +**1. 使用细粒度更新** - 仅更新更改的路径： +```json +{"dataModelUpdate": {"path": "/user", "contents": [{"key": "name", "valueString": "Alice"}]}} +``` + +**2. 按领域组织** - 对相关数据进行分组： +```json +{"user": {...}, "cart": {...}, "ui": {...}} +``` + +**3. 预计算显示值** - 智能体在发送之前格式化数据（货币、日期）： +```json +{"price": "$19.99"} // 而不是: {"price": 19.99} +``` diff --git a/docs/zh/concepts/data-flow.md b/docs/zh/concepts/data-flow.md new file mode 100644 index 00000000..0ca75af8 --- /dev/null +++ b/docs/zh/concepts/data-flow.md @@ -0,0 +1,92 @@ +# 数据流 + +消息如何从智能体流向 UI。 + +## 架构 + +``` +Agent (LLM) → A2UI Generator → Transport (SSE/WS/A2A) + ↓ +Client (Stream Reader) → Message Parser → Renderer → Native UI +``` + +![end-to-end-data-flow](../assets/end-to-end-data-flow.png) + +## 消息格式 + +A2UI 定义了一系列描述 UI 的 JSON 消息。在流式传输时，这些消息通常格式化为 **JSON Lines (JSONL)**，其中每一行都是一个完整的 JSON 对象。 + +```jsonl +{"surfaceUpdate":{"surfaceId":"main","components":[...]}} +{"dataModelUpdate":{"surfaceId":"main","contents":[{"key":"user","valueMap":[{"key":"name","valueString":"Alice"}]}]}} +{"beginRendering":{"surfaceId":"main","root":"root-component"}} +``` + +**为什么这种格式？** + +一系列独立的 JSON 对象对流式传输友好，易于 LLM 增量生成，并且对错误具有弹性。 + +## 生命周期示例：餐厅预订 + +**用户：** "预订明天晚上 7 点的两人桌" + +**1. 智能体定义 UI 结构：** + +```json +{"surfaceUpdate": {"surfaceId": "booking", "components": [ + {"id": "root", "component": {"Column": {"children": {"explicitList": ["header", "guests-field", "submit-btn"]}}}}, + {"id": "header", "component": {"Text": {"text": {"literalString": "Confirm Reservation"}, "usageHint": "h1"}}}, + {"id": "guests-field", "component": {"TextField": {"label": {"literalString": "Guests"}, "text": {"path": "/reservation/guests"}}}}, + {"id": "submit-btn", "component": {"Button": {"child": "submit-text", "action": {"name": "confirm", "context": [{"key": "details", "value": {"path": "/reservation"}}]}}}} +]}} +``` + +**2. 智能体填充数据：** + +```json +{"dataModelUpdate": {"surfaceId": "booking", "path": "/reservation", "contents": [ + {"key": "datetime", "valueString": "2025-12-16T19:00:00Z"}, + {"key": "guests", "valueString": "2"} +]}} +``` + +**3. 智能体信号通知渲染：** + +```json +{"beginRendering": {"surfaceId": "booking", "root": "root"}} +``` + +**4. 用户将人数编辑为 "3"** → 客户端自动更新 `/reservation/guests`（尚未向智能体发送消息） + +**5. 用户点击 "Confirm"** → 客户端发送带有更新数据的操作： + +```json +{"userAction": {"name": "confirm", "surfaceId": "booking", "context": {"details": {"datetime": "2025-12-16T19:00:00Z", "guests": "3"}}}} +``` + +**6. 智能体响应** → 更新 UI 或发送 `{"deleteSurface": {"surfaceId": "booking"}}` 以进行清理 + +## 传输选项 + +- **A2A 协议**: 多智能体系统，也可用于智能体到 UI 的通信 +- **AG UI**: 双向，实时 +- ... 其他 + +更多细节请参见 [传输](../transports.md)。 + +## 渐进式渲染 + +与其在向用户显示任何内容之前等待生成整个响应，不如将响应块在生成时流式传输到客户端并渐进式渲染。 + +用户可以看到 UI 实时构建，而不是盯着旋转的加载图标。 + +## 错误处理 + +- **格式错误的消息：** 跳过并继续，或向智能体发送错误以进行更正 +- **网络中断：** 显示错误状态，重新连接，智能体重新发送或恢复 + +## 性能 + +- **批处理：** 缓冲更新 16ms，批量渲染 +- **Diffing：** 比较旧/新组件，仅更新更改的属性 +- **细粒度更新：** 更新 `/user/name` 而不是整个 `/` 模型 diff --git a/docs/zh/concepts/overview.md b/docs/zh/concepts/overview.md new file mode 100644 index 00000000..00f7a434 --- /dev/null +++ b/docs/zh/concepts/overview.md @@ -0,0 +1,33 @@ +# 核心概念 + +本节解释了 A2UI 的基本架构。理解这些概念将帮助您构建有效的智能体驱动界面。 + +## 宏观图景 + +A2UI 围绕三个核心思想构建： + +1. **流式消息**: UI 更新作为从智能体到客户端的一系列 JSON 消息流 +2. **声明式组件**: UI 被描述为数据，而不是被编程为代码 +3. **数据绑定**: UI 结构与应用程序状态分离，支持响应式更新 + +## 关键主题 + +### [数据流](data-flow.md) +消息如何从智能体传输到渲染的 UI。包括餐厅预订流程的完整生命周期示例、传输选项（SSE, WebSockets, A2A）、渐进式渲染和错误处理。 + +### [组件结构](components.md) +A2UI 用于表示组件层次结构的 **邻接表模型**。了解为什么扁平列表优于嵌套树，如何使用静态与动态子级，以及增量更新的最佳实践。 + +### [数据绑定](data-binding.md) +组件如何使用 JSON Pointer 路径连接到应用程序状态。涵盖响应式组件、动态列表、输入绑定以及使 A2UI 如此强大的结构与状态分离。 + +## 消息类型 + +A2UI 使用四种消息类型： + +- **`surfaceUpdate`**: 定义或更新 UI 组件 +- **`dataModelUpdate`**: 更新应用程序状态 +- **`beginRendering`**: 发出信号通知客户端进行渲染 +- **`deleteSurface`**: 移除 UI surface + +有关完整的技术细节，请参见 [消息参考](../reference/messages.md)。 diff --git a/docs/zh/guides/agent-development.md b/docs/zh/guides/agent-development.md new file mode 100644 index 00000000..f6790a14 --- /dev/null +++ b/docs/zh/guides/agent-development.md @@ -0,0 +1,182 @@ +# 智能体开发指南 + +构建生成 A2UI 界面的 AI 智能体。本指南涵盖从 LLM 生成和流式传输 UI 消息。 + +## 快速概览 + +构建 A2UI 智能体： + +1. **理解用户意图** → 决定显示什么 UI +2. **生成 A2UI JSON** → 使用 LLM 结构化输出或提示 +3. **验证与流式传输** → 检查 schema，发送到客户端 +4. **处理操作** → 响应用户交互 + +## 从一个简单的智能体开始 + +我们将使用 ADK 构建一个简单的智能体。我们将从文本开始，最终将其升级到 A2UI。 + +请参阅 [ADK 快速入门](https://google.github.io/adk-docs/get-started/python/) 中的分步说明。 + +```bash +pip install google-adk +adk create my_agent +``` + +然后编辑 `my_agent/agent.py` 文件，创建一个非常简单的餐厅推荐智能体。 + +```python +import json +from google.adk.agents.llm_agent import Agent +from google.adk.tools.tool_context import ToolContext + +def get_restaurants(tool_context: ToolContext) -> str: + """Call this tool to get a list of restaurants.""" + return json.dumps([ + { + "name": "Xi'an Famous Foods", + "detail": "Spicy and savory hand-pulled noodles.", + "imageUrl": "http://localhost:10002/static/shrimpchowmein.jpeg", + "rating": "★★★★☆", + "infoLink": "[More Info](https://www.xianfoods.com/)", + "address": "81 St Marks Pl, New York, NY 10003" + }, + { + "name": "Han Dynasty", + "detail": "Authentic Szechuan cuisine.", + "imageUrl": "http://localhost:10002/static/mapotofu.jpeg", + "rating": "★★★★☆", + "infoLink": "[More Info](https://www.handynasty.net/)", + "address": "90 3rd Ave, New York, NY 10003" + }, + { + "name": "RedFarm", + "detail": "Modern Chinese with a farm-to-table approach.", + "imageUrl": "http://localhost:10002/static/beefbroccoli.jpeg", + "rating": "★★★★☆", + "infoLink": "[More Info](https://www.redfarmnyc.com/)", + "address": "529 Hudson St, New York, NY 10014" + }, + ]) + +AGENT_INSTRUCTION=""" +You are a helpful restaurant finding assistant. Your goal is to help users find and book restaurants using a rich UI. + +To achieve this, you MUST follow this logic: + +1. **For finding restaurants:** + a. You MUST call the `get_restaurants` tool. Extract the cuisine, location, and a specific number (`count`) of restaurants from the user's query (e.g., for "top 5 chinese places", count is 5). + b. After receiving the data, you MUST follow the instructions precisely to generate the final a2ui UI JSON, using the appropriate UI example from the `prompt_builder.py` based on the number of restaurants.""" + +root_agent = Agent( + model='gemini-2.5-flash', + name="restaurant_agent", + description="An agent that finds restaurants and helps book tables.", + instruction=AGENT_INSTRUCTION, + tools=[get_restaurants], +) +``` + +不要忘记设置 `GOOGLE_API_KEY` 环境变量来运行此示例。 + +```bash +echo 'GOOGLE_API_KEY="YOUR_API_KEY"' > .env +``` + +您可以使用 ADK Web 界面测试此智能体： + +```bash +adk web +``` + +从列表中选择 `my_agent`，并询问有关纽约餐厅的问题。您应该会看到纯文本的餐厅列表。 + +## 生成 A2UI 消息 + +让 LLM 生成 A2UI 消息需要一些提示工程。 + +!!! warning "注意" + 这是我们仍在设计的领域。这方面的开发者工效学尚未最终确定。 + +目前，让我们从 contact lookup 示例复制 `a2ui_schema.py`。这是获取智能体的 A2UI schema 和示例的最简单方法（可能会更改）。 + +```bash +cp samples/agent/adk/contact_lookup/a2ui_schema.py my_agent/ +``` + +首先，让我们将新的导入添加到 `agent.py` 文件中： + +```python +# The schema for any A2UI message. This never changes. +from .a2ui_schema import A2UI_SCHEMA +``` + +现在我们将修改智能体指令以生成 A2UI 消息而不是纯文本。我们将为未来的 UI 示例保留一个占位符。 + +```python + +# Eventually you can copy & paste some UI examples here, for few-shot in context learning +RESTAURANT_UI_EXAMPLES = """ +""" + +# Construct the full prompt with UI instructions, examples, and schema +A2UI_AND_AGENT_INSTRUCTION = AGENT_INSTRUCTION + f""" + +Your final output MUST be a a2ui UI JSON response. + +To generate the response, you MUST follow these rules: +1. Your response MUST be in two parts, separated by the delimiter: `---a2ui_JSON---`. +2. The first part is your conversational text response. +3. The second part is a single, raw JSON object which is a list of A2UI messages. +4. The JSON part MUST validate against the A2UI JSON SCHEMA provided below. + +--- UI TEMPLATE RULES --- +- If the query is for a list of restaurants, use the restaurant data you have already received from the `get_restaurants` tool to populate the `dataModelUpdate.contents` array (e.g., as a `valueMap` for the "items" key). +- If the number of restaurants is 5 or fewer, you MUST use the `SINGLE_COLUMN_LIST_EXAMPLE` template. +- If the number of restaurants is more than 5, you MUST use the `TWO_COLUMN_LIST_EXAMPLE` template. +- If the query is to book a restaurant (e.g., "USER_WANTS_TO_BOOK..."), you MUST use the `BOOKING_FORM_EXAMPLE` template. +- If the query is a booking submission (e.g., "User submitted a booking..."), you MUST use the `CONFIRMATION_EXAMPLE` template. + +{RESTAURANT_UI_EXAMPLES} + +---BEGIN A2UI JSON SCHEMA--- +{A2UI_SCHEMA} +---END A2UI JSON SCHEMA--- +""" + +root_agent = Agent( + model='gemini-2.5-flash', + name="restaurant_agent", + description="An agent that finds restaurants and helps book tables.", + instruction=A2UI_AND_AGENT_INSTRUCTION, + tools=[get_restaurants], +) +``` + +## 理解输出 + +您的智能体将不再严格输出文本。相反，它将输出文本和 A2UI 消息的 **JSON 列表**。 + +我们导入的 `A2UI_SCHEMA` 是一个标准的 JSON schema，定义了有效的操作，如： + +* `render` (显示 UI) +* `update` (更新现有 UI 中的数据) + +因为输出是结构化 JSON，所以您可以在将其发送到客户端之前解析并验证它。 + +```python +# 1. Parse the JSON +# Warning: Parsing the output as JSON is a fragile implementation useful for documentation. +# LLMs often put Markdown fences around JSON output, and can make other mistakes. +# Rely on frameworks to parse the JSON for you. +parsed_json_data = json.loads(json_string_cleaned) + +# 2. Validate against A2UI_SCHEMA +# This ensures the LLM generated valid A2UI commands +jsonschema.validate( + instance=parsed_json_data, schema=self.a2ui_schema_object +) +``` + +通过针对 `A2UI_SCHEMA` 验证输出，您可以确保您的客户端永远不会收到格式错误的 UI 指令。 + +TODO: 继续本指南，举例说明如何在没有 A2A 扩展的情况下解析、验证并将其发送到客户端渲染器。 diff --git a/docs/zh/guides/client-setup.md b/docs/zh/guides/client-setup.md new file mode 100644 index 00000000..6ab3a2cf --- /dev/null +++ b/docs/zh/guides/client-setup.md @@ -0,0 +1,106 @@ +# 客户端设置指南 + +使用适合您平台的渲染器将 A2UI 集成到您的应用程序中。 + +## 渲染器 + +| 渲染器 | 平台 | 状态 | +| ------------------------ | ------------------ | ----------------- | +| **Lit (Web Components)** | Web | ✅ 稳定 | +| **Angular** | Web | ✅ 稳定 | +| **Flutter (GenUI SDK)** | 移动/桌面/Web | ✅ 稳定 | +| **React** | Web | 🚧 预计 2026 年第一季度 | +| **SwiftUI** | iOS/macOS | 🚧 计划 2026 年第二季度 | +| **Jetpack Compose** | Android | 🚧 计划 2026 年第二季度 | + +## Web Components (Lit) + +!!! warning "注意" + Lit 客户端库尚未发布到 NPM。请在未来几天回来查看。 + +```bash +npm install @a2ui/web-lib lit @lit-labs/signals +``` + +Lit 渲染器使用： + +- **Message Processor**: 管理 A2UI 状态并处理传入消息 +- **`` component**: 在您的应用中渲染 Surfaces +- **Lit Signals**: 提供响应式状态管理以自动更新 UI + +TODO: 添加经过验证的设置示例。 + +**查看工作示例：** [Lit shell sample](https://github.com/google/a2ui/tree/main/samples/client/lit/shell) + +## Angular + +!!! warning "注意" + Angular 客户端库尚未发布到 NPM。请在未来几天回来查看。 + +```bash +npm install @a2ui/angular @a2ui/web-lib +``` + +Angular 渲染器提供： + +- **`provideA2UI()` function**: 在您的应用配置中配置 A2UI +- **`Surface` component**: 渲染 A2UI Surfaces +- **`MessageProcessor` service**: 处理传入的 A2UI 消息 + +TODO: 添加经过验证的设置示例。 + +**查看工作示例：** [Angular restaurant sample](https://github.com/google/a2ui/tree/main/samples/client/angular/projects/restaurant) + +## Flutter (GenUI SDK) + +```bash +flutter pub add flutter_genui +``` + +Flutter 使用提供原生 A2UI 渲染的 GenUI SDK。 + +**文档：** [GenUI SDK](https://docs.flutter.dev/ai/genui) | [GitHub](https://github.com/flutter/genui) | [GenUI Flutter Package 中的 README](https://github.com/flutter/genui/blob/main/packages/genui/README.md#getting-started-with-genui) + +## 连接到智能体 + +您的客户端应用程序需要： +1. 从智能体 **接收 A2UI 消息**（通过传输） +2. 使用 Message Processor **处理消息** +3. 将 **用户操作发送** 回智能体 + +常见的传输选项： +- **Server-Sent Events (SSE)**: 从服务器到客户端的单向流 +- **WebSockets**: 双向实时通信 +- **A2A 协议**: 支持 A2UI 的标准化智能体对智能体通信 + +TODO: 添加传输实现示例。 + +**参见：** [传输指南](../transports.md) + +## 处理用户操作 + +当用户与 A2UI 组件交互（点击按钮、提交表单等）时，客户端： +1. 捕获组件的操作事件 +2. 解析操作所需的所有数据上下文 +3. 将操作发送给智能体 +4. 处理智能体的响应消息 + +TODO: 添加操作处理示例。 + +## 错误处理 + +需要处理的常见错误： +- **无效的 Surface ID**: 在收到 `beginRendering` 之前引用了 Surface +- **无效的组件 ID**: 组件 ID 在 Surface 内必须唯一 +- **无效的数据路径**: 检查数据模型结构和 JSON Pointer 语法 +- **Schema 验证失败**: 验证消息格式是否符合 A2UI 规范 + +TODO: 添加错误处理示例。 + +## 下一步 + +- **[快速入门](../quickstart.md)**: 尝试演示应用程序 +- **[主题与样式](theming.md)**: 自定义外观和感觉 +- **[自定义组件](custom-components.md)**: 扩展组件目录 +- **[智能体开发](agent-development.md)**: 构建生成 A2UI 的智能体 +- **[参考文档](../reference/messages.md)**: 深入了解协议 diff --git a/docs/zh/guides/custom-components.md b/docs/zh/guides/custom-components.md new file mode 100644 index 00000000..e2a2dcc4 --- /dev/null +++ b/docs/zh/guides/custom-components.md @@ -0,0 +1,79 @@ +# 自定义组件目录 + +通过定义 **自定义目录** 来扩展 A2UI，这些目录包含您自己的组件以及标准 A2UI 组件。 + +## 为什么需要自定义目录？ + +A2UI 标准目录提供了通用的 UI 元素（按钮、文本字段等），但您的应用程序可能需要专用组件： + +- **特定领域的 widgets**: 股票行情机、医疗图表、CAD 查看器 +- **第三方集成**: Google 地图、支付表单、聊天 widgets +- **品牌特定组件**: 自定义日期选择器、产品卡片、仪表板 + +**自定义目录** 是组件的集合，可以包括： +- 标准 A2UI 组件 (Text, Button, TextField 等) +- 您的自定义组件 (GoogleMap, StockTicker 等) +- 第三方组件 + +您向客户端应用程序注册整个目录，而不是单个组件。这允许智能体和客户端在保持安全性和类型安全的同时，就一组共享的扩展组件达成一致。 + +## 自定义目录如何工作 + +1. **客户端定义目录**: 您创建一个列出标准组件和自定义组件的目录定义。 +2. **客户端注册目录**: 您向客户端应用程序注册该目录（及其组件实现）。 +3. **客户端宣布支持**: 客户端通知智能体它支持哪些目录。 +4. **智能体选择目录**: 智能体为给定的 UI Surface 选择一个目录。 +5. **智能体生成 UI**: 智能体使用该目录中的组件名称生成 `surfaceUpdate` 消息。 + +## 定义自定义目录 + +TODO: 为每个平台添加定义自定义目录的详细指南。 + +**Web (Lit / Angular):** +- 如何定义包含标准和自定义组件的目录 +- 如何向 A2UI 客户端注册目录 +- 如何实现自定义组件类 + +**Flutter:** +- 如何使用 GenUI 定义自定义目录 +- 如何注册自定义组件渲染器 + +**查看工作示例：** +- [Lit 示例](https://github.com/google/a2ui/tree/main/samples/client/lit) +- [Angular 示例](https://github.com/google/a2ui/tree/main/samples/client/angular) +- [Flutter GenUI 文档](https://docs.flutter.dev/ai/genui) + +## 智能体端：使用自定义目录中的组件 + +一旦目录在客户端注册，智能体就可以在 `surfaceUpdate` 消息中使用其中的组件。 + +智能体通过 `beginRendering` 消息中的 `catalogId` 指定要使用的目录。 + +TODO: 添加以下示例： +- 智能体如何选择目录 +- 智能体如何引用目录中的自定义组件 +- 目录版本控制如何工作 + +## 数据绑定和操作 + +自定义组件支持与标准组件相同的数据绑定和操作机制： + +- **数据绑定**: 自定义组件可以使用 JSON Pointer 语法将属性绑定到数据模型路径 +- **操作**: 自定义组件可以发出智能体接收和处理的操作 + +## 安全注意事项 + +在创建自定义目录和组件时： + +1. **允许列表组件**: 仅在您的目录中注册您信任的组件 +2. **验证属性**: 始终验证来自智能体消息的组件属性 +3. **清理用户输入**: 如果组件接受用户输入，请在处理之前对其进行清理 +4. **限制 API 访问**: 不要向自定义组件暴露敏感 API 或凭据 + +TODO: 添加详细的安全最佳实践和代码示例。 + +## 下一步 + +- **[主题与样式](theming.md)**: 自定义组件的外观和感觉 +- **[组件参考](../reference/components.md)**: 查看所有标准组件 +- **[智能体开发](agent-development.md)**: 构建使用自定义组件的智能体 diff --git a/docs/zh/guides/renderer-development.md b/docs/zh/guides/renderer-development.md new file mode 100644 index 00000000..aba83b02 --- /dev/null +++ b/docs/zh/guides/renderer-development.md @@ -0,0 +1,82 @@ +# A2UI 渲染器实现指南 + +本文档概述了 A2UI 协议（基于 0.8 版本规范）的新渲染器实现所需的功能。它面向构建新渲染器（例如，用于 React, Flutter, iOS 等）的开发人员。 + +## I. 核心协议实现清单 + +本节详细介绍了 A2UI 协议的基本机制。兼容的渲染器必须实现这些系统才能成功解析服务器流、管理状态和处理用户交互。 + +### 消息处理与状态管理 + +- **JSONL 流解析**: 实现一个解析器，可以逐行读取流式响应，将每一行解码为不同的 JSON 对象。 +- **消息分发器**: 创建一个分发器来识别消息类型 (`beginRendering`, `surfaceUpdate`, `dataModelUpdate`, `deleteSurface`) 并将其路由到正确的处理器。 +- **Surface 管理**: + - 实现一个数据结构来管理多个 UI Surfaces，每个 Surface 由其 `surfaceId` 键控。 + - 处理 `surfaceUpdate`：在指定 Surface 的组件缓冲区中添加或更新组件。 + - 处理 `deleteSurface`：移除指定的 Surface 及其所有关联的数据和组件。 +- **组件缓冲 (邻接表)**: + - 对于每个 Surface，维护一个组件缓冲区（例如，`Map`）以按其 `id` 存储所有组件定义。 + - 能够在渲染时通过解析容器组件 (`children.explicitList`, `child`, `contentChild` 等) 中的 `id` 引用来重建 UI 树。 +- **数据模型存储**: + - 对于每个 Surface，维护一个单独的数据模型存储（例如，JSON 对象或 `Map`）。 + - 处理 `dataModelUpdate`：在指定的 `path` 更新数据模型。`contents` 将采用邻接表格式（例如，`[{ "key": "name", "valueString": "Bob" }]`）。 + +### 渲染逻辑 + +- **渐进式渲染控制**: + - 缓冲所有传入的 `surfaceUpdate` 和 `dataModelUpdate` 消息，而不立即渲染。 + - 处理 `beginRendering`：此消息充当执行 Surface 初始渲染并设置根组件 ID 的显式信号。 + - 从指定的 `root` 组件 ID 开始渲染。 + - 如果提供了 `catalogId`，请确保使用相应的组件目录（如果省略，则默认为标准目录）。 + - 应用此消息中提供的任何全局 `styles`（例如 `font`, `primaryColor`）。 +- **数据绑定解析**: + - 为组件属性中的 `BoundValue` 对象实现解析器。 + - 如果仅存在 `literal*` 值 (`literalString`, `literalNumber` 等)，请直接使用它。 + - 如果仅存在 `path`，请针对 Surface 的数据模型进行解析。 + - 如果 `path` 和 `literal*` 都存在，请首先使用字面量值更新 `path` 处的数据模型，然后将组件属性绑定到该 `path`。 +- **动态列表渲染**: + - 对于具有 `children.template` 的容器，迭代在 `template.dataBinding` 处找到的数据列表（该列表解析为数据模型中的列表）。 + - 对于数据列表中的每个项目，渲染由 `template.componentId` 指定的组件，使该项目的数据可用于模板内的相对数据绑定。 + +### 客户端到服务器通信 + +- **事件处理**: + - 当用户与定义了 `action` 的组件交互时，构造一个 `userAction` 有效负载。 + - 针对数据模型解析 `action.context` 中的所有数据绑定。 + - 将完整的 `userAction` 对象发送到服务器的事件处理端点。 +- **客户端能力报告**: + - 在发送到服务器的 **每条** A2A 消息中（作为元数据的一部分），包含一个 `a2uiClientCapabilities` 对象。 + - 此对象应通过 `supportedCatalogIds` 声明您的客户端支持的组件目录（例如，包括标准 0.8 目录的 URI）。 + - （可选）如果服务器支持，则为自定义的即时组件定义提供 `inlineCatalogs`。 +- **错误报告**: 实现一种机制，向服务器发送 `error` 消息以报告任何客户端错误（例如，数据绑定失败、未知组件类型）。 + +## II. 标准组件目录清单 + +为了确保跨平台的一致用户体验，A2UI 定义了一组标准组件。您的客户端应将这些抽象定义映射到其相应的原生 UI widgets。 + +### 基础内容 + +- **Text**: 渲染文本内容。必须支持 `text` 上的数据绑定和 `usageHint`（h1-h5, body, caption）以进行样式设置。 +- **Image**: 从 URL 渲染图像。必须支持 `fit`（cover, contain 等）和 `usageHint`（avatar, hero 等）属性。 +- **Icon**: 渲染标准集中指定的预定义图标。 +- **Video**: 渲染给定 URL 的视频播放器。 +- **AudioPlayer**: 渲染给定 URL 的音频播放器，可选带有描述。 +- **Divider**: 渲染视觉分隔符，支持 `horizontal` 和 `vertical` 轴。 + +### 布局与容器 + +- **Row**: 水平排列子级。必须支持 `distribution` (justify-content) 和 `alignment` (align-items)。子级可以具有 `weight` 属性以控制 flex-grow 行为。 +- **Column**: 垂直排列子级。必须支持 `distribution` 和 `alignment`。子级可以具有 `weight` 属性以控制 flex-grow 行为。 +- **List**: 渲染可滚动的项目列表。必须支持 `direction` (`horizontal`/`vertical`) 和 `alignment`。 +- **Card**: 一个视觉上将子内容分组的容器，通常带有边框、圆角和/或阴影。具有单个 `child`。 +- **Tabs**: 显示一组选项卡的容器。包括 `tabItems`，其中每个项目都有一个 `title` 和 `child`。 +- **Modal**: 出现在主要内容之上的对话框。它由 `entryPointChild`（例如按钮）触发，并在激活时显示 `contentChild`。 + +### 交互与输入组件 + +- **Button**: 触发 `userAction` 的可点击元素。必须能够包含 `child` 组件（通常是 Text 或 Icon），并且样式可能因 `primary` 布尔值而异。 +- **CheckBox**: 可以切换的复选框，反映布尔值。 +- **TextField**: 文本输入字段。必须支持 `label`, `text` (值), `textFieldType` (`shortText`, `longText`, `number`, `obscured`, `date`), 和 `validationRegexp`。 +- **DateTimeInput**: 用于选择日期和/或时间的专用输入。必须支持 `enableDate` 和 `enableTime`。 +- **MultipleChoice**: 用于从列表 (`options`) 中选择一个或多个选项的组件。必须支持 `maxAllowedSelections` 并将 `selections` 绑定到列表或单个值。 +- **Slider**: 用于从定义范围 (`minValue`, `maxValue`) 中选择数值 (`value`) 的滑块。 diff --git a/docs/zh/guides/theming.md b/docs/zh/guides/theming.md new file mode 100644 index 00000000..ce03d0d1 --- /dev/null +++ b/docs/zh/guides/theming.md @@ -0,0 +1,180 @@ +# 主题与样式 + +自定义 A2UI 组件的外观和感觉以匹配您的品牌。 + +## A2UI 样式哲学 + +A2UI 遵循 **客户端控制的样式** 方法： + +- **智能体描述 *显示什么*** (组件和结构) +- **客户端决定 *它看起来如何*** (颜色、字体、间距) + +这确保了： + +- ✅ **品牌一致性**: 所有 UI 都匹配您应用的设计系统 +- ✅ **安全性**: 智能体不能注入任意 CSS 或样式 +- ✅ **无障碍性**: 您控制对比度、焦点状态和 ARIA 属性 +- ✅ **平台原生感**: Web 应用看起来像 Web，移动应用看起来像移动应用 + +## 样式层级 + +A2UI 样式分层工作： + +```mermaid +flowchart TD + A["1. 语义提示
智能体提供提示
(例如: usageHint: 'h1')"] + B["2. 主题配置
您配置
(颜色、字体、间距)"] + C["3. 组件覆盖
您自定义
(特定组件的 CSS/样式)"] + D["4. 渲染输出
原生平台 widgets"] + + A --> B --> C --> D +``` + +## 第 1 层：语义提示 + +智能体提供语义提示（非视觉样式）以指导客户端渲染： + +```json +{ + "id": "title", + "component": { + "Text": { + "text": {"literalString": "Welcome"}, + "usageHint": "h1" + } + } +} +``` + +**常见的 `usageHint` 值：** +- Text: `h1`, `h2`, `h3`, `h4`, `h5`, `body`, `caption` +- 其他组件有自己的提示（参见 [组件参考](../reference/components.md)） + +客户端渲染器根据您的主题和设计系统将这些语义提示映射到实际的视觉样式。 + +## 第 2 层：主题配置 + +每个渲染器提供了一种全局配置设计系统的方法，包括： + +- **颜色**: Primary, secondary, background, surface, error, success 等 +- **排版**: 字体系列、大小、粗细、行高 +- **间距**: 基础单位和比例 (xs, sm, md, lg, xl) +- **形状**: 圆角值 +- **海拔 (Elevation)**: 用于深度的阴影样式 + +TODO: 添加特定平台的主题指南： + +**Web (Lit):** +- 如何通过渲染器初始化配置主题 +- 可用的主题属性 + +**Angular:** +- 与 Angular Material 主题的集成 +- 独立的 A2UI 主题配置 + +**Flutter:** +- A2UI 如何使用 Flutter 的 `ThemeData` +- 自定义主题属性 + +**查看工作示例：** +- [Lit 示例](https://github.com/google/a2ui/tree/main/samples/client/lit) +- [Angular 示例](https://github.com/google/a2ui/tree/main/samples/client/angular) +- [Flutter GenUI 文档](https://docs.flutter.dev/ai/genui) + +## 第 3 层：组件覆盖 + +除了全局主题之外，您还可以覆盖特定组件的样式： + +**Web 渲染器：** +- 用于细粒度控制的 CSS 自定义属性（CSS 变量） +- 用于组件特定覆盖的标准 CSS 选择器 + +**Flutter:** +- 通过 `ThemeData` 进行 widget 特定的主题覆盖 + +TODO: 为每个平台添加详细的组件覆盖示例。 + +## 常见的样式功能 + +### 深色模式 + +A2UI 渲染器通常支持基于系统首选项的自动深色模式： + +- 自动检测系统主题 (`prefers-color-scheme`) +- 手动浅色/深色主题选择 +- 自定义深色主题配置 + +TODO: 添加深色模式配置示例。 + +### 响应式设计 + +A2UI 组件默认是响应式的。您可以进一步自定义响应式行为： + +- 针对不同屏幕尺寸的媒体查询 +- 针对组件级响应性的容器查询 +- 响应式间距和排版比例 + +TODO: 添加响应式设计示例。 + +### 自定义字体 + +在您的 A2UI 应用程序中加载和使用自定义字体： + +- Web 字体 (Google Fonts 等) +- 自托管字体 +- 平台特定的字体加载 + +TODO: 添加自定义字体示例。 + +## 最佳实践 + +### 1. 使用语义提示，而非视觉属性 + +智能体应提供语义提示 (`usageHint`)，绝不提供视觉样式： + +```json +// ✅ Good: 语义提示 +{ + "component": { + "Text": { + "text": {"literalString": "Welcome"}, + "usageHint": "h1" + } + } +} + +// ❌ Bad: 视觉属性（不支持） +{ + "component": { + "Text": { + "text": {"literalString": "Welcome"}, + "fontSize": 24, + "color": "#FF0000" + } + } +} +``` + +### 2. 保持无障碍性 + +- 确保足够的颜色对比度（WCAG AA: 普通文本 4.5:1，大文本 3:1） +- 使用屏幕阅读器进行测试 +- 支持键盘导航 +- 在浅色和深色模式下进行测试 + +### 3. 使用设计令牌 + +定义可重用的设计令牌（颜色、间距等）并在整个样式中引用它们以保持一致性。 + +### 4. 跨平台测试 + +- 在所有目标平台（Web、移动、桌面）上测试您的主题 +- 验证浅色和深色模式 +- 检查不同的屏幕尺寸和方向 +- 确保跨平台的一致品牌体验 + +## 下一步 + +- **[自定义组件](custom-components.md)**: 使用您的样式构建自定义组件 +- **[组件参考](../reference/components.md)**: 查看所有组件的样式选项 +- **[客户端设置](client-setup.md)**: 在您的应用中设置渲染器 diff --git a/docs/zh/index.md b/docs/zh/index.md new file mode 100644 index 00000000..653183e1 --- /dev/null +++ b/docs/zh/index.md @@ -0,0 +1,155 @@ +--- +hide: + - toc +--- + + + +
+ + +A2UI Logo + +A2UI Logo + +# 智能体驱动界面的协议 + +

+A2UI 使 AI 智能体能够生成丰富、交互式的用户界面，这些界面可以在 Web、移动设备和桌面上原生渲染——无需执行任意代码。 +

+ +
+ +!!! warning "️状态：早期公开预览" + A2UI 目前处于 **v0.8 (公开预览版)**。规范和实现功能正常，但仍在不断发展。我们要开放该项目以促进协作、收集反馈并征集贡献（例如，在客户端渲染器上）。 + 预计会有变更。 + +## 概览 + +A2UI 目前为 [v0.8](specification/v0.8-a2ui.md)， +采用 Apache 2.0 许可， +由 Google 创建，并得到了 CopilotKit 和开源社区的贡献， +正在 [GitHub 上](https://github.com/google/A2UI) 积极开发。 + +A2UI 解决的问题是：**AI 智能体如何安全地跨越信任边界发送富 UI？** + +A2UI 允许智能体发送 **声明式组件描述**，客户端使用自己的原生控件进行渲染，而不是纯文本响应或有风险的代码执行。这就像让智能体说一种通用的 UI 语言。 + +在这个仓库中，您会找到 +[A2UI 规范](specification/v0.8-a2ui.md) +以及针对客户端的 +[渲染器](renderers.md)（例如：Angular, Flutter 等）的实现， +以及在智能体和客户端之间传递 A2UI 消息的 [传输](/transports.md)（例如：A2A 等）。 + +
+ +- :material-shield-check: **设计上安全** + + --- + + 声明式数据格式，非可执行代码。智能体只能使用目录中预先批准的组件——没有 UI 注入攻击。 + +- :material-rocket-launch: **LLM 友好** + + --- + + 扁平的流式 JSON 结构，专为易于生成而设计。LLM 可以增量构建 UI，而无需一次性生成完美的 JSON。 + +- :material-devices: **框架无关** + + --- + + 一个智能体响应随处可用。在 Angular、Flutter、React 或使用您自己的样式组件的原生移动设备上渲染相同的 UI。 + +- :material-chart-timeline: **渐进式渲染** + + --- + + 在生成 UI 更新时流式传输它们。用户可以实时看到界面构建，而无需等待完整的响应。 + +
+ +## 5 分钟上手 + +
+ +- :material-clock-fast:{ .lg .middle } **[快速入门指南](quickstart.md)** + + --- + + 运行餐厅查找演示，查看由 Gemini 驱动的智能体的 A2UI 实际应用。 + + [:octicons-arrow-right-24: 开始使用](quickstart.md) + +- :material-book-open-variant:{ .lg .middle } **[核心概念](concepts/overview.md)** + + --- + + 了解 Surfaces、组件、数据绑定和邻接表模型。 + + [:octicons-arrow-right-24: 学习概念](concepts/overview.md) + +- :material-code-braces:{ .lg .middle } **[开发者指南](guides/client-setup.md)** + + --- + + 将 A2UI 渲染器集成到您的应用程序中或构建生成 UI 的智能体。 + + [:octicons-arrow-right-24: 开始构建](guides/client-setup.md) + +- :material-file-document:{ .lg .middle } **[协议参考](specification/v0.8-a2ui.md)** + + --- + + 深入了解完整的技术规范和消息类型。 + + [:octicons-arrow-right-24: 阅读规范](specification/v0.8-a2ui.md) + +
+ +## 工作原理 + +1. **用户发送消息** 给 AI 智能体 +2. **智能体生成 A2UI 消息** 描述 UI（结构 + 数据） +3. **消息流式传输** 到客户端应用程序 +4. **客户端渲染** 使用原生组件（Angular, Flutter, React 等） +5. **用户交互** 与 UI，将操作发送回智能体 +6. **智能体响应** 更新后的 A2UI 消息 + +![端到端数据流](../assets/end-to-end-data-flow.png) + +## A2UI 实战 + +### 景观设计师演示 + +
+
+ +
+

+ 观看智能体为景观设计师应用程序生成所有界面。用户上传照片；智能体使用 Gemini 理解照片并生成针对绿化需求的自定义表单。 +

+
+ +### 自定义组件：交互式图表与地图 + +
+
+ +
+

+ 观看智能体选择响应图表组件来回答数值摘要问题。然后智能体选择 Google 地图组件来回答位置问题。两者都是客户端提供的自定义组件。 +

+
+ +### A2UI Composer + +CopilotKit 也有一个公开的 [A2UI Widget Builder](https://go.copilotkit.ai/A2UI-widget-builder) 可供试用。 + +[![A2UI Composer](../assets/A2UI-widget-builder.png)](https://go.copilotkit.ai/A2UI-widget-builder) diff --git a/docs/zh/introduction/agent-ui-ecosystem.md b/docs/zh/introduction/agent-ui-ecosystem.md new file mode 100644 index 00000000..cb4fe206 --- /dev/null +++ b/docs/zh/introduction/agent-ui-ecosystem.md @@ -0,0 +1,36 @@ +# 智能体生态系统中的 A2UI + +智能体式 UI 领域正在迅速发展，出现了解决堆栈不同部分的出色工具。A2UI 不是这些框架的替代品——它是一个专门的协议，解决了 **互操作、跨平台、生成式或基于模板的 UI 响应** 的特定问题。 + +## 概览 + +A2UI 的方法是将 JSON 作为消息发送到客户端，然后客户端使用渲染器将其转换为原生 UI 组件。 LLMs 可以即时生成组件布局，或者您可以使用模板。 + +!!! tip "" + **这使其像数据一样安全，像代码一样具有表现力。** + +本页面的其余部分将帮助您了解 A2UI 与其他选项的关系。 + +## 导航智能体式 UI 生态系统 + +### 1. 构建“宿主”应用程序 UI + +如果您正在构建全栈应用程序（用户交互的“宿主” UI），除了构建实际的 UI 之外，您还可以利用框架 **(AG UI / CopilotKit, Vercel AI SDK, GenUI SDK for Flutter，它们在底层已经使用了 A2UI)** 来处理“管道”：状态同步、聊天记录和输入处理。 + +**A2UI 的位置：** A2UI 是互补的。如果您使用 AG UI 连接您的宿主应用程序，则可以使用 A2UI 作为数据格式来渲染来自宿主智能体以及第三方或远程智能体的响应。这为您提供了两全其美的方案：一个丰富的、有状态的宿主应用程序，可以安全地渲染来自其无法控制的外部智能体的内容。 + +- **A2UI with A2A:** 您可以直接通过 A2A 发送到客户端前端。 +- **A2UI with AG UI:** 您可以直接通过 AG UI 发送到客户端前端。 +- 具有 REST, SSE, WebSockets 和其他传输的 A2UI 是可行的，但尚未可用。 + +### 2. UI 作为“资源” (MCP Apps) + +**模型上下文协议 (MCP)** [最近引入了 **MCP Apps**](https://blog.modelcontextprotocol.io/posts/2025-11-21-mcp-apps/)，这是一个整合了 MCP-UI 和 OpenAI 的出色工作的新标准，使服务器能够提供交互式界面。这种方法将 UI 视为资源（通过 `ui://` URI 访问），工具可以返回该资源，通常在沙盒 `iframe` 中渲染预构建的 HTML 内容，以确保隔离和安全性。 + +**A2UI 有何不同：** A2UI 采用了“原生优先”的方法，这与 MCP Apps 的资源获取模型不同。A2UI 智能体发送原生组件的蓝图，而不是检索要在沙盒中显示的不透明有效负载。这允许 UI 完美地继承宿主应用程序的样式和无障碍功能。在多智能体系统中，编排器智能体可以轻松理解来自子智能体的轻量级 A2UI 消息内容，从而实现智能体之间更流畅的协作。 + +### 3. 特定于平台的生态系统 (OpenAI ChatKit) + +像 **ChatKit** 这样的工具提供了一种高度集成、优化的体验，专门用于在 OpenAI 生态系统中部署智能体。 + +**A2UI 有何不同：** A2UI 专为在 Web, Flutter 和原生移动设备上构建自己的智能体式 Surface 的开发人员设计，或者为智能体需要跨越信任边界进行通信的企业网格（如 **A2A**）设计。A2UI 赋予客户端更多样式控制权，但这由智能体付出代价，以允许与宿主客户端应用程序实现更大的视觉一致性。 diff --git a/docs/zh/introduction/how-to-use.md b/docs/zh/introduction/how-to-use.md new file mode 100644 index 00000000..01a53780 --- /dev/null +++ b/docs/zh/introduction/how-to-use.md @@ -0,0 +1,53 @@ +# 我该如何使用 A2UI？ + +选择与您的角色和用例相匹配的集成路径。 + +## 三条路径 + +### 路径 1：构建宿主应用程序 (前端) + +将 A2UI 渲染集成到您现有的应用程序中，或者构建一个新的智能体驱动的前端。 + +**选择渲染器：** + +- **Web:** Lit, Angular +- **移动/桌面:** Flutter GenUI SDK +- **React:** 预计 2026 年第一季度 + +**快速设置：** + +如果我们使用 Angular 应用程序，我们可以添加 Angular 渲染器： + +```bash +npm install @a2ui/angular +``` + +连接到智能体消息（SSE, WebSockets 或 A2A）并自定义样式以匹配您的品牌。 + +**下一步：** [客户端设置指南](../guides/client-setup.md) | [主题](../guides/theming.md) + +--- + +### 路径 2：构建智能体 (后端) + +创建一个为任何兼容客户端生成 A2UI 响应的智能体。 + +**选择您的框架：** + +- **Python:** Google ADK, LangChain, 自定义 +- **Node.js:** A2A SDK, Vercel AI SDK, 自定义 + +将 A2UI schema 包含在您的 LLM prompts 中，生成 JSONL 消息，并通过 SSE, WebSockets 或 A2A 流式传输到客户端。 + +**下一步：** [智能体开发指南](../guides/agent-development.md) + +--- + +### 路径 3：使用现有框架 + +通过具有内置支持的框架使用 A2UI： + +- **[AG UI / CopilotKit](https://ag-ui.com/)** - 带有 A2UI 渲染的全栈 React 框架 +- **[Flutter GenUI SDK](https://docs.flutter.dev/ai/genui)** - 跨平台生成式 UI（内部使用 A2UI） + +**下一步：** [智能体 UI 生态系统](agent-ui-ecosystem.md) | [A2UI 在哪里使用？](where-is-it-used.md) diff --git a/docs/zh/introduction/what-is-a2ui.md b/docs/zh/introduction/what-is-a2ui.md new file mode 100644 index 00000000..93da6a57 --- /dev/null +++ b/docs/zh/introduction/what-is-a2ui.md @@ -0,0 +1,95 @@ +# 什么是 A2UI？ + +**A2UI (Agent to UI) 是一个用于智能体驱动界面的声明式 UI 协议。** AI 智能体生成丰富、交互式的 UI，这些 UI 可以在跨平台（Web、移动、桌面）上原生渲染，而无需执行任意代码。 + +## 问题 + +**这纯文本智能体交互效率低下：** + +``` +User: "预订明天晚上 7 点的两人桌" +Agent: "好的，哪一天？" +User: "明天" +Agent: "几点？" +... +``` + +**更好：** 智能体生成一个带有日期选择器、时间选择器和提交按钮的表单。用户与 UI 交互，而不是文本。 + +## 挑战 + +在多智能体系统中，智能体通常在远程运行（不同的服务器、组织）。它们不能直接操作您的 UI——它们必须发送消息。 + +**传统方法：** 在 iframe 中发送 HTML/JavaScript + +- 沉重，视觉上脱节 +- 安全复杂性 +- 不匹配应用样式 + +**需求：** 传输像数据一样安全，像代码一样具有表现力的 UI。 + +## 解决方案 + +A2UI：描述 UI 的 JSON 消息： + +- LLM 作为结构化输出生成 +- 通过任何传输（A2A, AG UI, SSE, WebSockets）传输 +- 客户端使用其自己的原生组件进行渲染 + +**结果：** 客户端控制安全性和样式，智能体生成的 UI 感觉是原生的。 + +### 示例 + +```json +{"surfaceUpdate": {"surfaceId": "booking", "components": [ + {"id": "title", "component": {"Text": {"text": {"literalString": "Book Your Table"}, "usageHint": "h1"}}}, + {"id": "datetime", "component": {"DateTimeInput": {"value": {"path": "/booking/date"}, "enableDate": true}}}, + {"id": "submit-text", "component": {"Text": {"text": {"literalString": "Confirm"}}}}, + {"id": "submit-btn", "component": {"Button": {"child": "submit-text", "action": {"name": "confirm_booking"}}}} +]}} +``` + +```json +{"dataModelUpdate": {"surfaceId": "booking", "contents": [ + {"key": "booking", "valueMap": [{"key": "date", "valueString": "2025-12-16T19:00:00Z"}]} +]}} +``` + +```json +{"beginRendering": {"surfaceId": "booking", "root": "title"}} +``` + +客户端将这些消息渲染为原生组件（Angular, Flutter, React 等）。 + +## 核心价值 + +**1. 安全性：** 声明式数据，而非代码。智能体从客户端受信任的目录中请求组件。没有代码执行风险。 + +**2. 原生感觉：** 没有 iframe。客户端使用其自己的 UI 框架进行渲染。继承应用样式、无障碍性、性能。 + +**3. 可移植性：** 一个智能体响应随处可用。相同的 JSON 在 Web (Lit/Angular/React)、移动 (Flutter/SwiftUI/Jetpack Compose)、桌面上渲染。 + +## 设计原则 + +**1. LLM 友好：** 带有 ID 引用的扁平组件列表。易于增量生成、纠正错误、流式传输。 + +**2. 框架无关：** 智能体发送抽象组件树。客户端映射到原生 widgets（Web/移动/桌面）。 + +**3. 关注点分离：** 三层——UI 结构、应用程序状态、客户端渲染。启用数据绑定、响应式更新、清洁架构。 + +## A2UI 不是什么 + +- 不是一个框架（它是一个协议） +- 不是 HTML 的替代品（用于智能体生成的 UI，而不是静态网站） +- 不是一个强大的样式系统（客户端控制样式，服务端样式支持有限） +- 不限于 Web（适用于移动和桌面） + +## 关键概念 + +- **Surface**：组件的画布（对话框、侧边栏、主视图） +- **Component**：UI 元素（按钮、文本框、卡片等） +- **Data Model**：应用程序状态，组件绑定到它 +- **Catalog**：可用的组件类型 +- **Message**：JSON 对象 (`surfaceUpdate`, `dataModelUpdate`, `beginRendering` 等) + +要比较类似项目，请参见 [智能体 UI 生态系统](agent-ui-ecosystem.md)。 diff --git a/docs/zh/introduction/where-is-it-used.md b/docs/zh/introduction/where-is-it-used.md new file mode 100644 index 00000000..771143ec --- /dev/null +++ b/docs/zh/introduction/where-is-it-used.md @@ -0,0 +1,150 @@ +# A2UI 在哪里使用？ + +A2UI 正在被 Google 和合作伙伴组织的团队采用，以构建下一代智能体驱动的应用程序。以下是 A2UI 产生影响的真实示例。 + +## 生产部署 + +### Google Opal: 适于所有人的 AI 小程序 + +[Opal](http://opal.google) 使数十万人能够使用自然语言构建、编辑和共享 AI 小程序——无需编码。 + +**Opal 如何使用 A2UI：** + +Google 的 Opal 团队从一开始就是 **A2UI 的核心贡献者**。他们使用 A2UI 来驱动动态的、生成式的 UI 系统，从而使 Opal 的 AI 小程序成为可能。 + +- **快速原型设计**：快速构建和测试新的 UI 模式 +- **用户生成的应用**：任何人都可以创建具有自定义 UI 的应用 +- **动态界面**：UI 自动适应每个用例 + +> "A2UI 是我们工作的基础。它给了我们灵活性，让我们能够以新颖的方式让 AI 驱动用户体验，而不受固定前端的限制。其声明式的性质和对安全性的关注使我们能够快速安全地进行实验。" +> +> **— Dimitri Glazkov**, Principal Engineer, Opal Team + +**了解更多：** [opal.google](http://opal.google) + +--- + +### Gemini Enterprise: 商业自定义智能体 + +Gemini Enterprise 使企业能够构建强大的、自定义的 AI 智能体，以适应其特定的工作流程和数据。 + +**Gemini Enterprise 如何使用 A2UI：** + +A2UI 正在被集成以允许企业智能体在业务应用程序中渲染 **丰富的、交互式的 UI**——超越简单的文本响应，引导员工完成复杂的工作流程。 + +- **数据录入表单**：用于结构化数据收集的 AI 生成的表单 +- **审批仪表板**：用于审查和审批流程的动态 UI +- **工作流自动化**：针对复杂任务的分步界面 +- **自定义企业 UI**：针对特定行业需求的定制界面 + +> "我们的客户需要他们的智能体不仅仅是回答问题；他们需要智能体引导员工完成复杂的工作流程。A2UI 将允许在 Gemini Enterprise 上构建的开发人员让他们的智能体生成任何任务所需的动态、自定义 UI，从数据录入表单到审批仪表板，从而显著加速工作流自动化。" +> +> **— Fred Jabbour**, Product Manager, Gemini Enterprise + +**了解更多：** [Gemini Enterprise](https://cloud.google.com/gemini) + +--- + +### Flutter GenUI SDK: 移动端的生成式 UI + +[Flutter GenUI SDK](https://docs.flutter.dev/ai/genui) 为跨移动、桌面和 Web 的 Flutter 应用程序带来了动态的、AI 生成的 UI。 + +**GenUI 如何使用 A2UI：** + +GenUI SDK 使用 **A2UI 作为服务端智能体和 Flutter 应用程序之间通信的底层协议**。当您使用 GenUI 时，您在底层使用的就是 A2UI。 + +- **跨平台支持**：同一个智能体适用于 iOS, Android, web, desktop +- **原生性能**：Flutter widgets 在每个平台上原生渲染 +- **品牌一致性**：UI 匹配您的应用设计系统 +- **服务端驱动 UI**：智能体控制显示内容，无需应用更新 + +> "我们的开发人员选择 Flutter 是因为它允许他们快速创建富有表现力、品牌丰富、自定义的设计系统，在每个平台上都感觉很棒。A2UI 非常适合 Flutter 的 GenUI SDK，因为它确保每个平台上的每个用户都能获得高质量的原生体验。" +> +> **— Vijay Menon**, Engineering Director, Dart & Flutter + +**试用：** +- [GenUI 文档](https://docs.flutter.dev/ai/genui) +- [入门视频](https://www.youtube.com/watch?v=nWr6eZKM6no) +- [Verdure 示例](https://github.com/flutter/genui/tree/main/examples/verdure) (client-server A2UI sample) + +--- + +## 合作伙伴集成 + +### AG UI / CopilotKit: 全栈智能体框架 + +[AG UI](https://ag-ui.com/) 和 [CopilotKit](https://www.copilotkit.ai/) 提供了一个构建智能体式应用程序的综合框架，具有 **零日 A2UI 兼容性**。 + +**它们如何协同工作：** + +AG UI 擅长在自定义前端与其专用智能体之间创建高带宽连接。通过添加 A2UI 支持，开发人员可以两全其美： + +- **状态同步**：AG UI 处理应用状态和聊天记录 +- **A2UI 渲染**：渲染来自第三方智能体的动态 UI +- **多智能体支持**：协调来自多个智能体的 UI +- **React 集成**：与 React 应用程序无缝集成 + +> "AG UI 擅长在自定义构建的前端与其专用智能体之间创建高带宽连接。通过添加对 A2UI 的支持，我们为开发人员提供了两全其美的方案。他们现在可以构建富文本、状态同步的应用程序，还可以通过 A2UI 渲染来自第三方智能体的动态 UI。这对于多智能体世界来说是完美的匹配。" +> +> **— Atai Barkai**, Founder of CopilotKit and AG UI + +**了解更多：** +- [AG UI](https://ag-ui.com/) +- [CopilotKit](https://www.copilotkit.ai/) + +--- + +### Google 的 AI 驱动产品 + +随着 Google 在全公司范围内采用 AI，A2UI 提供了一种 **AI 智能体交换用户界面的标准化方式**，而不仅仅是文本。 + +**内部智能体采用：** + +- **多智能体工作流**：多个智能体贡献同一个 surface +- **远程智能体支持**：在不同服务上运行的智能体可以提供 UI +- **标准化**：跨团队的通用协议减少了集成开销 +- **外部暴露**：内部智能体可以轻松地暴露给外部（例如，Gemini Enterprise） + +> "就像 A2A 让任何智能体都可以与另一个智能体对话一样，无论平台如何，A2UI 标准化了用户界面层，并通过编排器支持远程智能体用例。这对内部团队来说非常强大，使他们能够快速开发智能体，其中丰富的用户界面是常态，而不是例外。随着 Google 进一步推进生成式 UI，A2UI 为在任何客户端上渲染的服务端驱动 UI 提供了一个完美的平台。" +> +> **— James Wren**, Senior Staff Engineer, AI Powered Google + +--- + +## 社区项目 + +A2UI 社区正在构建令人兴奋的项目： + +### 开源示例 + +- **餐厅查找器** ([samples/agent/adk/restaurant_finder](https://github.com/google/A2UI/tree/main/samples/agent/adk/restaurant_finder)) + - 带有动态表单的餐桌预订 + - 由 Gemini 驱动的智能体 + - 提供完整源代码 + +- **联系人查找** ([samples/agent/adk/contact_lookup](https://github.com/google/A2UI/tree/main/samples/agent/adk/contact_lookup)) + - 带有结果列表的搜索界面 + - A2A 智能体示例 + - 演示数据绑定 + +- **组件库** ([samples/client/angular - gallery mode](https://github.com/google/A2UI/tree/main/samples/client/angular)) + - 所有组件的交互式展示 + - 带有代码的实时示例 + - 非常适合学习 + +### 社区贡献 + +您是否用 A2UI 构建了一些东西？[与社区分享！](../community.md) + +--- + +## 下一步 + +- [快速入门指南](../quickstart.md) - 尝试演示 +- [智能体开发](../guides/agent-development.md) - 构建智能体 +- [客户端设置](../guides/client-setup.md) - 集成渲染器 +- [社区](../community.md) - 加入社区 + +--- + +**在生产中使用 A2UI？** 在 [GitHub Discussions](https://github.com/google/A2UI/discussions) 上分享您的故事。 diff --git a/docs/zh/introduction/who-is-it-for.md b/docs/zh/introduction/who-is-it-for.md new file mode 100644 index 00000000..ddb8e239 --- /dev/null +++ b/docs/zh/introduction/who-is-it-for.md @@ -0,0 +1,65 @@ +# A2UI 是为谁准备的？ + +构建具有丰富、交互式 UI 的 AI 智能体的开发人员。 + +## 三类受众 + +### 1. 宿主应用开发人员 (前端) + +构建多智能体平台、企业助手或智能体生成 UI 的跨平台应用程序。 + +**为什么选择 A2UI：** + +- 品牌控制：客户端拥有样式和设计系统 +- 多智能体：支持本地、远程和第三方智能体 +- 安全：声明式数据，无代码执行 +- 跨平台：Web、移动、桌面 +- 互操作性：开源，具有多个渲染器的相同规范 + +**开始使用：** [客户端设置](../guides/client-setup.md) | [主题](../guides/theming.md) | [自定义组件](../guides/custom-components.md) + +### 2. 智能体开发人员 (后端/AI) + +构建生成表单、仪表板和交互式工作流的智能体。 + +**为什么选择 A2UI：** + +- LLM 友好：扁平结构，易于增量生成 +- 丰富的交互：超越文本（表单、表格、可视化） +- 生成而非工具：UI 作为智能体生成的输出的一部分 +- 可移植：一个智能体响应适用于所有 A2UI 客户端 +- 可流式传输：在生成时渐进式渲染 + +**开始使用：** [智能体开发](../guides/agent-development.md) + +### 3. 平台构建者 (SDK 创建者) + +构建智能体编排平台、框架或 UI 集成。 + +您是否将远程智能体带入您的应用程序？ + +您是否将您的智能体发布到您不一定控制的其他应用程序中？ + +**为什么选择 A2UI：** + +- 标准协议：与 A2A 和其他传输互操作 +- 可扩展：自定义组件目录 +- 开源 (Apache 2.0) + +**开始使用：** [社区](../community.md) | [路线图](../roadmap.md) + +--- + +## 何时使用 A2UI + +- ✅ **智能体生成的 UI** - 核心目的 +- ✅ **多智能体系统** - 跨越信任边界的标准协议 +- ✅ **跨平台应用程序** - 一个智能体，多个渲染器（Web/移动/桌面） +- ✅ **安全关键** - 声明式数据，无代码执行 +- ✅ **品牌一致性** - 客户端控制样式 + +- ❌ **静态网站** - 使用 HTML/CSS +- ❌ **简单的纯文本聊天** - 使用 Markdown +- ❌ **未与客户端集成的远程 widgets** - 使用 iframe，如 MCP Apps +- ❌ **快速的一起构建 UI + 智能体应用程序** - 使用 AG UI / CopilotKit + diff --git a/docs/zh/quickstart.md b/docs/zh/quickstart.md new file mode 100644 index 00000000..e1862e40 --- /dev/null +++ b/docs/zh/quickstart.md @@ -0,0 +1,276 @@ +# 快速开始：5 分钟运行 A2UI + +通过运行餐厅查找演示来亲身体验 A2UI。本指南将让您在不到 5 分钟的时间内体验智能体生成的 UI。 + +## 您将构建什么 + +在本快速入门结束时，您将拥有： + +- ✅ 一个运行 A2UI Lit 渲染器的 Web 应用程序 +- ✅ 一个由 Gemini 驱动的智能体，可生成动态 UI +- ✅ 一个交互式餐厅查找器，具有表单生成、时间选择和确认流程 +- ✅ 了解 A2UI 消息如何从智能体流向 UI + +## 前提条件 + +在其开始之前，请确保您已有： + +- **Node.js** (v18 或更高版本) - [在此下载](https://nodejs.org/) +- **Gemini API 密钥** - [从 Google AI Studio 免费获取](https://aistudio.google.com/apikey) + +!!! warning "安全提示" + 此演示运行一个使用 Gemini 生成 A2UI 响应的 A2A 智能体。该智能体有权访问您的 API 密钥，并将向 Google 的 Gemini API 发出请求。在生产环境中运行智能体代码之前，请务必对其进行审查。 + +## 第 1 步：克隆仓库 + +```bash +git clone https://github.com/google/a2ui.git +cd a2ui +``` + +## 第 2 步：设置您的 API 密钥 + +将您的 Gemini API 密钥导出为环境变量： + +```bash +export GEMINI_API_KEY="your_gemini_api_key_here" +``` + +## 第 3 步：导航到 Lit 客户端 + +```bash +cd samples/client/lit +``` + +## 第 4 步：安装并运行 + +运行一键演示启动器： + +```bash +npm install +npm run demo:all +``` + +此命令将： + +1. 安装所有依赖项 +2. 构建 A2UI 渲染器 +3. 启动 A2A 餐厅查找智能体（Python 后端） +4. 启动开发服务器 +5. 在浏览器中打开 `http://localhost:5173` + +!!! success "演示正在运行" + 如果一切正常，您应该会在浏览器中看到该 Web 应用程序。智能体现在已准备好生成 UI！ + +## 第 5 步：试一试 + +在 Web 应用程序中，尝试以下提示： + +1. **"Book a table for 2"** - 观看智能体生成预订表单 +2. **"Find Italian restaurants near me"** - 查看动态搜索结果 +3. **"What are your hours?"** - 体验针对不同意图的不同 UI 布局 + +### 幕后发生了什么 + +``` +┌─────────────┐ ┌──────────────┐ ┌────────────────┐ +│ You Type │────────>│ A2A Agent │────────>│ Gemini API │ +│ a Message │ │ (Python) │ │ (LLM) │ +│ (您输入消息) │ │ │ │ │ +└─────────────┘ └──────────────┘ └────────────────┘ + │ │ + │ Generates A2UI JSON │ + │ (生成 A2UI JSON) │ + │<────────────────────────┘ + │ + │ Streams JSONL messages + │ (流式传输 JSONL 消息) + v + ┌──────────────┐ + │ Web App │ + │ (A2UI Lit │ + │ Renderer) │ + │ (渲染器) │ + └──────────────┘ + │ + │ Renders native components + │ (渲染原生组件) + v + ┌──────────────┐ + │ Your UI │ + │ (您的界面) │ + └──────────────┘ +``` + +1. **您通过 Web UI 发送消息** +2. **A2A 智能体**接收消息并将对话发送给 Gemini +3. **Gemini 生成**描述 UI 的 A2UI JSON 消息 +4. **A2A 智能体**将这些消息流式传回 Web 应用程序 +5. **A2UI 渲染器**将它们转换为原生 Web 组件 +6. **您在浏览器中看到 UI** 渲染出来 + +## A2UI 消息解剖 + +让我们看看智能体发送了什么。这是 JSON 消息的简化示例： + +### 定义 UI + +```json +{ + "surfaceUpdate": { + "surfaceId": "main", + "components": [ + { + "id": "header", + "component": { + "Text": { + "text": {"literalString": "Book Your Table"}, + "usageHint": "h1" + } + } + }, + { + "id": "date-picker", + "component": { + "DateTimeInput": { + "label": {"literalString": "Select Date"}, + "value": {"path": "/reservation/date"}, + "enableDate": true + } + } + }, + { + "id": "submit-btn", + "component": { + "Button": { + "child": "submit-text", + "action": {"name": "confirm_booking"} + } + } + }, + { + "id": "submit-text", + "component": { + "Text": {"text": {"literalString": "Confirm Reservation"}} + } + } + ] + } +} +``` + +这定义了界面的 UI 组件：一个文本标题、一个日期选择器和一个按钮。 + +### 填充数据 + +```json +{ + "dataModelUpdate": { + "surfaceId": "main", + "contents": [ + { + "key": "reservation", + "valueMap": [ + {"key": "date", "valueString": "2025-12-15"}, + {"key": "time", "valueString": "19:00"}, + {"key": "guests", "valueInt": 2} + ] + } + ] + } +} +``` + +这填充了组件可以绑定的数据模型。 + +### 信号渲染 + +```json +{"beginRendering": {"surfaceId": "main", "root": "header"}} +``` + +这告诉客户端它有足够的信息来渲染 UI。 + +!!! tip "这只是 JSON" + 注意这是多么可读和结构化？LLM 可以轻松生成此内容，并且它是安全传输和渲染的——不需要执行代码。 + +## 探索其他演示 + +该仓库包括其他几个演示： + +### 组件库（无需智能体） + +查看所有可用的 A2UI 组件： + +```bash +npm start -- gallery +``` + +这将运行一个仅限客户端的演示，展示每个标准组件（Card, Button, TextField, Timeline 等），并带有实时示例和代码示例。 + +### 联系人查找演示 + +尝试不同的智能体用例： + +```bash +npm run demo:contact +``` + +这演示了一个生成搜索表单和结果列表的联系人查找智能体。 + +## 下一步是什么？ + +既然您已经看到了 A2UI 的实际应用，您可以准备： + +- **[学习核心概念](concepts/overview.md)**：了解 Surfaces、组件和数据绑定 +- **[设置您自己的客户端](guides/client-setup.md)**：将 A2UI 集成到您自己的应用程序中 +- **[构建智能体](guides/agent-development.md)**：创建生成 A2UI 响应的智能体 +- **[探索协议](reference/messages.md)**：深入了解技术规范 + +## 故障排除 + +### 端口已被占用 + +如果端口 5173 已被占用，开发服务器将自动尝试下一个可用端口。检查终端输出以获取实际 URL。 + +### API 密钥问题 + +如果您看到有关缺少 API 密钥的错误： + +1. 验证密钥是否已导出：`echo $GEMINI_API_KEY` +2. 确保它是来自 [Google AI Studio](https://aistudio.google.com/apikey) 的有效 Gemini API 密钥 +3. 尝试重新导出：`export GEMINI_API_KEY="your_key"` + +### Python 依赖项 + +该演示使用 Python 作为 A2A 智能体。如果您遇到 Python 错误： + +```bash +# 确保已安装 Python 3.10+ +python3 --version + +# 演示应通过 npm 脚本自动安装依赖项 +# 如果没有，请手动安装它们： +cd ../../agent/adk/restaurant_finder +pip install -r requirements.txt +``` + +### 仍有类似问题？ + +- 检查 [GitHub Issues](https://github.com/google/a2ui/issues) +- 查看 [samples/client/lit/README.md](https://github.com/google/a2ui/tree/main/samples/client/lit) +- 加入社区讨论 + +## 了解演示代码 + +想看看它是如何工作的？查看： + +- **智能体代码**：`samples/agent/adk/restaurant_finder/` - Python A2A 智能体 +- **客户端代码**：`samples/client/lit/` - 带有 A2UI 渲染器的 Lit Web 客户端 +- **A2UI 渲染器**：`web-lib/` - Web 渲染器实现 + +每个目录都有自己详细的 README 文档。 + +--- + +**恭喜！** 您已成功运行了第一个 A2UI 应用程序。您已经看到了 AI 智能体如何生成丰富的、交互式的 UI，并在 Web 应用程序中原生渲染——所有这些都通过安全的、声明式的 JSON 消息实现。 diff --git a/docs/zh/reference/components.md b/docs/zh/reference/components.md new file mode 100644 index 00000000..5fe50b92 --- /dev/null +++ b/docs/zh/reference/components.md @@ -0,0 +1,276 @@ +# 组件库 (Component Gallery) + +本页面展示了所有标准 A2UI 组件的示例和使用模式。有关完整的技术规范，请参阅 [标准目录定义](https://github.com/google/A2UI/blob/main/specification/v0_8/json/standard_catalog_definition.json)。 + +## 布局组件 (Layout Components) + +### Row (行) + +水平布局容器。子组件从左到右排列。 + +```json +{ + "id": "toolbar", + "component": { + "Row": { + "children": {"explicitList": ["btn1", "btn2", "btn3"]}, + "alignment": "center" + } + } +} +``` + +**属性:** + +- `children`: 静态数组 (`explicitList`) 或动态 `template` +- `distribution`: 子组件的水平分布 (`start`, `center`, `end`, `spaceBetween`, `spaceAround`, `spaceEvenly`) +- `alignment`: 垂直对齐 (`start`, `center`, `end`, `stretch`) + +### Column (列) + +垂直布局容器。子组件从上到下排列。 + +```json +{ + "id": "content", + "component": { + "Column": { + "children": {"explicitList": ["header", "body", "footer"]} + } + } +} +``` + +**属性:** + +- `children`: 静态数组 (`explicitList`) 或动态 `template` +- `distribution`: 子组件的垂直分布 (`start`, `center`, `end`, `spaceBetween`, `spaceAround`, `spaceEvenly`) +- `alignment`: 水平对齐 (`start`, `center`, `end`, `stretch`) + +## 显示组件 (Display Components) + +### Text (文本) + +显示带有可选样式的文本内容。 + +```json +{ + "id": "title", + "component": { + "Text": { + "text": {"literalString": "Welcome to A2UI"}, + "usageHint": "h1" + } + } +} +``` + +**`usageHint` 值:** `h1`, `h2`, `h3`, `h4`, `h5`, `caption`, `body` + +### Image (图片) + +显示来自 URL 的图片。 + +```json +{ + "id": "logo", + "component": { + "Image": { + "url": {"literalString": "https://example.com/logo.png"} + } + } +} +``` + +### Icon (图标) + +使用 Material Icons 或自定义图标集显示图标。 + +```json +{ + "id": "check-icon", + "component": { + "Icon": { + "name": {"literalString": "check_circle"} + } + } +} +``` + +### Divider (分隔线) + +视觉分隔线。 + +```json +{ + "id": "separator", + "component": { + "Divider": { + "axis": "horizontal" + } + } +} +``` + +## 交互组件 (Interactive Components) + +### Button (按钮) + +支持操作的可点击按钮。 + +```json +{ + "id": "submit-btn-text", + "component": { + "Text": { + "text": { "literalString": "Submit" } + } + } +} +{ + "id": "submit-btn", + "component": { + "Button": { + "child": "submit-btn-text", + "primary": true, + "action": {"name": "submit_form"} + } + } +} +``` + +**属性:** +- `child`: 要在按钮中显示的组件的 ID（例如，Text 或 Icon）。 +- `primary`: 指示这是否为主要操作的布尔值。 +- `action`: 点击时执行的操作。 + +### TextField (文本字段) + +文本输入字段。 + +```json +{ + "id": "email-input", + "component": { + "TextField": { + "label": {"literalString": "Email Address"}, + "text": {"path": "/user/email"}, + "textFieldType": "shortText" + } + } +} +``` + +**`textFieldType` 值:** `date`, `longText`, `number`, `shortText`, `obscured` + +### Checkbox (复选框) + +布尔切换。 + +```json +{ + "id": "terms-checkbox", + "component": { + "Checkbox": { + "label": {"literalString": "I agree to the terms"}, + "value": {"path": "/form/agreedToTerms"} + } + } +} +``` + +## 容器组件 (Container Components) + +### Card (卡片) + +带有高度/边框和内边距的容器。 + +```json +{ + "id": "info-card", + "component": { + "Card": { + "child": "card-content" + } + } +} +``` + +### Modal (模态框) + +覆盖层对话框。 + +```json +{ + "id": "confirmation-modal", + "component": { + "Modal": { + "entryPointChild": "open-modal-btn", + "contentChild": "modal-content" + } + } +} +``` + +### Tabs (选项卡) + +选项卡式界面。 + +```json +{ + "id": "settings-tabs", + "component": { + "Tabs": { + "tabItems": [ + {"title": {"literalString": "General"}, "child": "general-settings"}, + {"title": {"literalString": "Privacy"}, "child": "privacy-settings"}, + {"title": {"literalString": "Advanced"}, "child": "advanced-settings"} + ] + } + } +} +``` + +### List (列表) + +可滚动的项目列表。 + +```json +{ + "id": "message-list", + "component": { + "List": { + "children": { + "template": { + "dataBinding": "/messages", + "componentId": "message-item" + } + } + } + } +} +``` + +## 通用属性 (Common Properties) + +大多数组件支持这些通用属性： + +- `id` (必需): 组件实例的唯一标识符。 +- `weight`: 当组件是 Row 或 Column 的直接子组件时的 flex-grow 值。此属性与 `id` 和 `component` 一起指定。 + +## 实时示例 (Live Examples) + +要查看所有组件的运行情况，请运行组件库演示： + +```bash +cd samples/client/angular +npm start -- gallery +``` + +这将启动一个实时画廊，包含所有组件、它们的变体和交互式示例。 + +## 延伸阅读 (Further Reading) + +- **[标准目录定义](../../specification/v0_9/json/standard_catalog_definition.json)**: 完整的技术规范 +- **[自定义组件指南](../guides/custom-components.md)**: 构建您自己的组件 +- **[主题指南](../guides/theming.md)**: 设置组件样式以匹配您的品牌 diff --git a/docs/zh/reference/messages.md b/docs/zh/reference/messages.md new file mode 100644 index 00000000..bdac27ee --- /dev/null +++ b/docs/zh/reference/messages.md @@ -0,0 +1,404 @@ +# 消息类型 (Message Types) + +本参考文档提供了所有 A2UI 消息类型的详细文档。 + +## 消息格式 (Message Format) + +所有 A2UI 消息都是作为 JSON Lines (JSONL) 发送的 JSON 对象。每一行包含恰好一条消息，每条消息包含以下四个键之一： + +- `beginRendering` +- `surfaceUpdate` +- `dataModelUpdate` +- `deleteSurface` + +## beginRendering + +通知客户端它有足够的信息来执行 Surface 的初始渲染。 + +### Schema + +```typescript +{ + beginRendering: { + surfaceId: string; // 必需: 唯一的 Surface 标识符 + root: string; // 必需: 要渲染的根组件的 ID + catalogId?: string; // 可选: 组件目录的 URL + styles?: object; // 可选: 样式信息 + } +} +``` + +### 属性 (Properties) + +| 属性 | 类型 | 必需 | 描述 | +| :--- | :--- | :--- | :--- | +| `surfaceId` | string | ✅ | 此 Surface 的唯一标识符。 | +| `root` | string | ✅ | 应该是此 Surface 的 UI 树根的组件的 `id`。 | +| `catalogId` | string | ❌ | 组件目录的标识符。如果省略，默认使用 v0.8 标准目录。 | +| `styles` | object | ❌ | UI 的样式信息，由目录定义。 | + +### 示例 (Examples) + +**基本渲染信号:** + +```json +{ + "beginRendering": { + "surfaceId": "main", + "root": "root-component" + } +} +``` + +**使用自定义目录:** + +```json +{ + "beginRendering": { + "surfaceId": "custom-ui", + "root": "root-custom", + "catalogId": "https://my-company.com/a2ui/v0.8/my_custom_catalog.json" + } +} +``` + +### 使用说明 (Usage Notes) + +- 必须在客户端收到根组件及其初始子组件的组件定义后发送。 +- 客户端应缓冲 `surfaceUpdate` 和 `dataModelUpdate` 消息，并且仅在收到相应的 `beginRendering` 消息后才渲染 Surface 的 UI。 + +--- + +## surfaceUpdate + +在 Surface 内添加或更新组件。 + +### Schema + +```typescript +{ + surfaceUpdate: { + surfaceId: string; // 必需: 目标 Surface + components: Array<{ // 必需: 组件列表 + id: string; // 必需: 组件 ID + component: { // 必需: 组件数据的包装器 + [ComponentType]: { // 必需: 恰好一种组件类型 + ...properties // 组件特定属性 + } + } + }> + } +} +``` + +### 属性 (Properties) + +| 属性 | 类型 | 必需 | 描述 | +| :--- | :--- | :--- | :--- | +| `surfaceId` | string | ✅ | 要更新的 Surface 的 ID | +| `components` | array | ✅ | 组件定义数组 | + +### 组件对象 (Component Object) + +`components` 数组中的每个对象必须具有： + +- `id` (string, required): Surface 内的唯一标识符 +- `component` (object, required): 一个包装器对象，包含恰好一个键，即组件类型（例如，`Text`, `Button`）。 + +### 示例 (Examples) + +**单个组件:** + +```json +{ + "surfaceUpdate": { + "surfaceId": "main", + "components": [ + { + "id": "greeting", + "component": { + "Text": { + "text": {"literalString": "Hello, World!"}, + "usageHint": "h1" + } + } + } + ] + } +} +``` + +**多个组件 (邻接表):** + +```json +{ + "surfaceUpdate": { + "surfaceId": "main", + "components": [ + { + "id": "root", + "component": { + "Column": { + "children": {"explicitList": ["header", "body"]} + } + } + }, + { + "id": "header", + "component": { + "Text": { + "text": {"literalString": "Welcome"} + } + } + }, + { + "id": "body", + "component": { + "Card": { + "child": "content" + } + } + }, + { + "id": "content", + "component": { + "Text": { + "text": {"path": "/message"} + } + } + } + ] + } +} +``` + +**更新现有组件:** + +```json +{ + "surfaceUpdate": { + "surfaceId": "main", + "components": [ + { + "id": "greeting", + "component": { + "Text": { + "text": {"literalString": "Hello, Alice!"}, + "usageHint": "h1" + } + } + } + ] + } +} +``` + +具有 `id: "greeting"` 的组件被更新（不是重复）。 + +### 使用说明 (Usage Notes) + +- 必须在 `beginRendering` 消息中指定一个组件作为 `root`，作为树的根。 +- 组件形成邻接表（带有 ID 引用的平面结构）。 +- 发送具有现有 ID 的组件会更新该组件。 +- 子组件通过 ID 引用。 +- 组件可以增量添加（流式传输）。 + +### 错误 (Errors) + +| 错误 | 原因 | 解决方案 | +| :--- | :--- | :--- | +| Surface not found | `surfaceId` 不存在 | 确保对给定的 Surface 一致地使用唯一的 `surfaceId`。Surface 在第一次更新时隐式创建。 | +| Invalid component type | 未知的组件类型 | 检查组件类型是否存在于协商的目录中。 | +| Invalid property | 该类型不存在此属性 | 针对目录 schema 进行验证。 | +| Circular reference | 组件引用自己作为子组件 | 修复组件层级结构。 | + +--- + +## dataModelUpdate + +更新组件绑定的数据模型。 + +### Schema + +```typescript +{ + dataModelUpdate: { + surfaceId: string; // 必需: 目标 Surface + path?: string; // 可选: 模型中位置的路径 + contents: Array<{ // 必需: 数据条目 + key: string; + valueString?: string; + valueNumber?: number; + valueBoolean?: boolean; + valueMap?: Array<{...}>; + }> + } +} +``` + +### 属性 (Properties) + +| 属性 | 类型 | 必需 | 描述 | +| :--- | :--- | :--- | :--- | +| `surfaceId` | string | ✅ | 要更新的 Surface 的 ID。 | +| `path` | string | ❌ | 数据模型内位置的路径（例如 'user'）。如果省略，则更新适用于根。 | +| `contents` | array | ✅ | 作为邻接表的数据条目数组。每个条目都有一个 `key` 和一个类型化的 `value*` 属性。 | + +### `contents` 邻接表 + +`contents` 数组是键值对列表。数组中的每个对象必须有一个 `key` 和恰好一个 `value*` 属性（`valueString`, `valueNumber`, `valueBoolean`, 或 `valueMap`）。这种结构对 LLM 友好，避免了从通用 `value` 字段推断类型的问题。 + +### 示例 (Examples) + +**初始化整个模型:** + +如果省略 `path`，`contents` 将替换 Surface 的整个数据模型。 + +```json +{ + "dataModelUpdate": { + "surfaceId": "main", + "contents": [ + { + "key": "user", + "valueMap": [ + { "key": "name", "valueString": "Alice" }, + { "key": "email", "valueString": "alice@example.com" } + ] + }, + { "key": "items", "valueMap": [] } + ] + } +} +``` + +**更新嵌套属性:** + +如果提供了 `path`，`contents` 将更新该位置的数据。 + +```json +{ + "dataModelUpdate": { + "surfaceId": "main", + "path": "user", + "contents": [ + { "key": "email", "valueString": "alice@newdomain.com" } + ] + } +} +``` + +这将在不影响 `/user/name` 的情况下更改 `/user/email`。 + +### 使用说明 (Usage Notes) + +- 数据模型是每个 Surface 独立的。 +- 当组件绑定的数据发生更改时，组件会自动重新渲染。 +- 优先选择特定路径的细粒度更新，而不是替换整个模型。 +- 数据模型是一个普通的 JSON 对象。 +- 任何数据转换（例如，格式化日期）必须由服务器在发送 `dataModelUpdate` 消息之前完成。 + +--- + +## deleteSurface + +移除 Surface 及其所有组件和数据。 + +### Schema + +```typescript +{ + deleteSurface: { + surfaceId: string; // 必需: 要删除的 Surface + } +} +``` + +### 属性 (Properties) + +| 属性 | 类型 | 必需 | 描述 | +| :--- | :--- | :--- | :--- | +| `surfaceId` | string | ✅ | 要删除的 Surface 的 ID | + +### 示例 (Examples) + +**删除一个 Surface:** + +```json +{ + "deleteSurface": { + "surfaceId": "modal" + } +} +``` + +**删除多个 Surface:** + +```json +{ + "deleteSurface": { + "surfaceId": "sidebar" + } +} +{ + "deleteSurface": { + "surfaceId": "content" + } +} +``` + +### 使用说明 (Usage Notes) + +- 移除与 Surface 关联的所有组件 +- 清除 Surface 的数据模型 +- 客户端应从 UI 中移除该 Surface +- 删除不存在的 Surface 是安全的（无操作） +- 用于关闭模态框、对话框或离开页面时 + +### 错误 (Errors) + +| 错误 | 原因 | 解决方案 | +| :--- | :--- | :--- | +| (无 - 删除是幂等的) | | | + +--- + +## 消息顺序 (Message Ordering) + +### 要求 (Requirements) + +1. `beginRendering` 必须在该 Surface 的初始 `surfaceUpdate` 消息之后。 +2. `surfaceUpdate` 可以在 `dataModelUpdate` 之前或之后。 +3. 不同 Surface 的消息是独立的。 +4. 多个消息可以增量更新同一个 Surface。 + +### 推荐顺序 (Recommended Order) + +```jsonl +{"surfaceUpdate": {"surfaceId": "main", "components": [...]}} +{"dataModelUpdate": {"surfaceId": "main", "contents": {...}}} +{"beginRendering": {"surfaceId": "main", "root": "root-id"}} +``` + +### 渐进式构建 (Progressive Building) + +```jsonl +{"surfaceUpdate": {"surfaceId": "main", "components": [...]}} // Header +{"surfaceUpdate": {"surfaceId": "main", "components": [...]}} // Body +{"beginRendering": {"surfaceId": "main", "root": "root-id"}} // Initial render +{"surfaceUpdate": {"surfaceId": "main", "components": [...]}} // Footer (after initial render) +{"dataModelUpdate": {"surfaceId": "main", "contents": {...}}} // Populate data +``` + +## 验证 (Validation) + +所有消息应针对以下内容进行验证： + +- **[server_to_client.json](https://github.com/google/A2UI/blob/main/specification/v0_8/json/server_to_client.json)**: 消息信封 Schema +- **[standard_catalog_definition.json](https://github.com/google/A2UI/blob/main/specification/v0_8/json/standard_catalog_definition.json)**: 组件 Schemas + +## 延伸阅读 (Further Reading) + +- **[组件库](components.md)**: 所有可用的组件类型 +- **[数据绑定指南](../concepts/data-binding.md)**: 数据绑定如何工作 +- **[智能体开发指南](../guides/agent-development.md)**: 生成有效消息 diff --git a/docs/zh/renderers.md b/docs/zh/renderers.md new file mode 100644 index 00000000..cbd4c158 --- /dev/null +++ b/docs/zh/renderers.md @@ -0,0 +1,62 @@ +# 渲染器 (客户端库) + +渲染器将 A2UI JSON 消息转换为不同平台的原生 UI 组件。 + +[智能体](agents.md) 负责生成 A2UI 消息， +而 [传输](transports.md) 负责将消息传递给客户端。 +客户端渲染器库必须缓冲和处理 A2UI 消息，实现 A2UI 生命周期，并渲染 Surfaces (widgets)。 + +您拥有很大的灵活性，可以将自定义组件带入渲染器，或者构建自己的渲染器以支持您的 UI 组件框架。 + +## 可用渲染器 + +| 渲染器 | 平台 | 状态 | 链接 | +|----------|----------|--------|-------| +| **Lit (Web Components)** | Web | ✅ 稳定 | [代码](https://github.com/google/A2UI/tree/main/renderers/lit) | +| **Angular** | Web | ✅ 稳定 | [代码](https://github.com/google/A2UI/tree/main/renderers/angular) | +| **Flutter (GenUI SDK)** | 移动端/桌面端/Web | ✅ 稳定 | [文档](https://docs.flutter.dev/ai/genui) · [代码](https://github.com/flutter/genui) | +| **React** | Web | 🚧 进行中 | 预计 2026 年第一季度 | + +查看 [路线图](roadmap.md) 获取更多信息。 + +## 渲染器如何工作 + +``` +A2UI JSON → 渲染器 → 原生组件 → 您的应用 +``` + +1. 从传输 **接收** A2UI 消息 +2. **解析** JSON 并根据 Schema 进行验证 +3. 使用平台原生组件 **渲染** +4. 根据您的应用主题进行 **样式设计** + +## 使用渲染器 + +通过遵循您选择的渲染器的设置指南，开始将 A2UI 集成到您的应用程序中： + +- **[Lit (Web Components)](guides/client-setup.md#web-components-lit)** +- **[Angular](guides/client-setup.md#angular)** +- **[Flutter (GenUI SDK)](guides/client-setup.md#flutter-genui-sdk)** + +## 构建渲染器 + +想为您的平台构建渲染器？ + +- 查看 [路线图](roadmap.md) 以了解计划中的框架。 +- 查看现有渲染器以获取模式。 +- 查看我们的 [渲染器开发指南](guides/renderer-development.md) 了解实现渲染器的详细信息。 + +### 关键要求： + +- 解析 A2UI JSON 消息，特别是邻接表格式 +- 将 A2UI 组件映射到原生 widgets +- 处理数据绑定、生命周期事件 +- 处理增量 A2UI 消息序列以构建和更新 UI +- 支持服务器发起的更新 +- 支持用户操作 + +### 下一步 + +- **[客户端设置指南](guides/client-setup.md)**：集成说明 +- **[快速开始](quickstart.md)**：尝试 Lit 渲染器 +- **[组件参考](reference/components.md)**：支持哪些组件 diff --git a/docs/zh/roadmap.md b/docs/zh/roadmap.md new file mode 100644 index 00000000..c1e493e5 --- /dev/null +++ b/docs/zh/roadmap.md @@ -0,0 +1,230 @@ +# 路线图 + +本路线图概述了 A2UI 项目的现状和未来计划。该项目正处于积极开发中，优先级可能会根据社区反馈和新兴用例而变化。 + +## 当前状态 + +### 协议 + +| 版本 | 状态 | 说明 | +|---------|--------|-------| +| **v0.8** | ✅ 稳定 | 首次公开发布 | +| **v0.9** | 🚧 进行中 | 规范草案改进 | + +主要特性： + +- ✅ 流式 JSONL 消息格式 +- ✅ 四种核心消息类型 (`surfaceUpdate`, `dataModelUpdate`, `beginRendering`, `deleteSurface`) +- ✅ 邻接表组件模型 +- ✅ 基于 JSON Pointer 的数据绑定 +- ✅ 结构与状态分离 + +### 渲染器 + +| 客户端库 | 状态 | 平台 | 说明 | +|-----------------|--------|----------|-------| +| **Web Components (Lit)** | ✅ 稳定 | Web | 框架无关，随处可用 | +| **Angular** | ✅ 稳定 | Web | 完整的 Angular 集成 | +| **Flutter (GenUI SDK)** | ✅ 稳定 | 多平台 | 适用于移动端、Web、桌面端 | +| **React** | 🚧 进行中 | Web | 预计 2026 年第一季度 | +| **SwiftUI** | 📋 计划中 | iOS/macOS | 预计 2026 年第二季度 | +| **Jetpack Compose** | 📋 计划中 | Android | 预计 2026 年第二季度 | +| **Vue** | 💡 提议中 | Web | 社区兴趣 | +| [**Svelte/Kit**](https://svelte.dev/docs/kit/introduction) | 💡 提议中 | Web | [社区兴趣](https://news.ycombinator.com/item?id=46287728) | +| **ShadCN (React)** | 💡 提议中 | Web | 社区兴趣 | + +### 传输 + +| 传输 | 状态 | 说明 | +|-------------|--------|-------| +| **A2A 协议** | ✅ 完成 | 原生 A2A 传输 | +| **AG UI** | ✅ 完成 | 零日兼容性 | +| **REST API** | 📋 计划中 | 双向通信 | +| **WebSockets** | 💡 提议中 | 双向通信 | +| **SSE (Server-Sent Events)** | 💡 提议中 | Web 流式传输 | +| **MCP (Model Context Protocol)** | 💡 提议中 | 社区兴趣 | + +### 智能体 UI 工具包 + +| 智能体 UI 工具包 | 状态 | 说明 | +|-------------|--------|-------| +| **CopilotKit** | ✅ 完成 | 由于 AG UI 而具备零日兼容性 | +| **Open AI ChatKit** | 💡 提议中 | 社区兴趣 | +| **Vecel AI SDK UI** | 💡 提议中 | 社区兴趣 | + +### 智能体框架 + +| 集成 | 状态 | 说明 | +|-------------|--------|-------| +| **任何支持 A2A 的智能体** | ✅ 完成 | 由于 A2A 协议而具备零日兼容性 | +| **ADK** | 📋 计划中 | 仍在设计开发者工效学，参见 [示例](https://github.com/google/A2UI/tree/main/samples/agent/adk) | +| **Genkit** | 💡 提议中 | 社区兴趣 | +| **LangGraph** | 💡 提议中 | 社区兴趣 | +| **CrewAI** | 💡 提议中 | 社区兴趣 | +| **AG2** | 💡 提议中 | 社区兴趣 | +| **Claude Agent SDK** | 💡 提议中 | 社区兴趣 | +| **OpenAI Agent SDK** | 💡 提议中 | 社区兴趣 | +| **Microsoft Agent Framework** | 💡 提议中 | 社区兴趣 | +| **AWS Strands Agent SDK** | 💡 提议中 | 社区兴趣 | + +## 近期里程碑 + +### 2025 年第二季度 + +多个 Google 团队的众多研究项目，包括集成到内部产品和智能体中。 + +### 2025 年第四季度 + +- v0.8.0 规范发布 +- A2A 扩展（感谢 Google A2A 团队！在 [a2asummit.ai](https://a2asummit.ai) 上预告） +- Flutter 渲染器（感谢 Flutter 团队！） +- Angular 渲染器（感谢 Angular 团队！） +- Web Components (Lit) 渲染器（感谢 Opal 团队及朋友们！） +- AG UI / CopilotKit 集成（感谢 CopilotKit 团队！） +- Github 公开发布 (Apache 2.0) + +## 即将到来的里程碑 + +### 2026 年第一季度 + +#### A2UI v0.9 + +- 规范 0.9 候选发布版 +- 改进渲染器的多主题支持（完成） +- 改进智能体的服务器端主题支持（最小化） +- 改进开发者工效学 + +#### React 渲染器 + +基于 Hooks API 和完整 TypeScript 支持的原生 React 渲染器。 + +- 常用组件的 React 支持 +- 自定义组件的 React 支持 +- 用于消息处理的 `useA2UI` hook +- React 主题支持 + +### 2026 年第二季度 + +#### 原生移动端渲染器 + +iOS 和 Android 平台的原生渲染器。 + +**SwiftUI 渲染器 (iOS/macOS):** + +- 原生 SwiftUI 组件 +- iOS 设计语言支持 +- macOS 兼容性 + +**Jetpack Compose 渲染器 (Android):** + +- 原生 Compose UI 组件 +- Material Design 3 支持 +- Android 平台集成 + +#### 性能优化 + +- 渲染器性能基准测试 +- 大型组件树的懒加载 +- 列表的虚拟滚动 +- 组件记忆化策略 + +### 2026 年第四季度 + +#### 协议 v1.0 + +最终确定协议 v1.0，包括： + +- 稳定性保证 +- v0.9 的迁移路径 +- 全面的测试套件 +- 渲染器认证计划 + +## 长期愿景 + +### 多智能体协作 + +增强对多个智能体贡献同一 UI 的支持： + +- 推荐的智能体组合模式 +- 冲突解决策略 +- 共享 Surface 管理 + +### 无障碍功能 + +一流的无障碍支持： + +- ARIA 属性生成 +- 屏幕阅读器优化 +- 键盘导航标准 +- 对比度和颜色指南 + +### 高级 UI 模式 + +支持更复杂的 UI 交互： + +- 拖放 +- 手势和动画 +- 3D 渲染 +- AR/VR 界面（探索性） + +### 生态系统增长 + +- 更多框架集成 +- 第三方组件库 +- 智能体市场集成 +- 企业功能和支持 + +## 社区请求 + +社区请求的功能（排名不分先后）： + +- **更多渲染器集成**：从您的客户端库映射到 A2UI +- **更多智能体框架**：从您的智能体框架映射到 A2UI +- **更多传输**：从您的传输映射到 A2UI +- **社区组件库**：与社区共享自定义组件 +- **社区示例**：与社区共享自定义示例 +- **社区评估**：生成式 UI 评估场景和标记数据集 +- **开发者工效学**：如果您能构建更好的 A2UI 体验，请与社区分享 + +## 如何影响路线图 + +我们需要社区对优先级的输入： + +1. **投票 Issues**：给您关心的 GitHub issues 点赞 👍 +2. **提议功能**：在 GitHub 上发起讨论（请先搜索现有讨论） +3. **提交 PR**：构建您需要的功能（请先搜索现有 PR） +4. **加入讨论**：分享您的用例和需求（请先搜索现有讨论） + +## 发布周期 + +- **主版本 (Major)** (1.0, 2.0)：每年或当需要重大破坏性更改时 +- **次版本 (Minor)** (1.1, 1.2)：每季度，包含新功能 +- **补丁版本 (Patch)** (1.1.1, 1.1.2)：按需进行 bug 修复 + +## 版本控制策略 + +A2UI 遵循 [语义化版本控制 (Semantic Versioning)](https://semver.org/)： + +- **MAJOR**：不兼容的协议更改 +- **MINOR**：向后兼容的功能添加 +- **PATCH**：向后兼容的错误修复 + +## 参与其中 + +想为路线图做出贡献？ + +- 在 [GitHub Discussions](https://github.com/google/A2UI/discussions) 中 **提议功能** +- **构建原型** 并与社区分享 +- 在 GitHub Issues 上 **加入对话** + +## 保持更新 + +- 关注 [GitHub 仓库](https://github.com/google/A2UI) 以获取更新 +- 星标仓库以示支持 +- 关注发布以获取新版本通知 + +--- + +**最后更新：** 2025 年 12 月 + +对路线图有疑问？[在 GitHub 上发起讨论](https://github.com/google/A2UI/discussions)。 diff --git a/docs/zh/specification/v0.8-a2a-extension.md b/docs/zh/specification/v0.8-a2a-extension.md new file mode 100644 index 00000000..f90ab84a --- /dev/null +++ b/docs/zh/specification/v0.8-a2a-extension.md @@ -0,0 +1,15 @@ +# A2UI A2A 协议扩展 (v0.8) + +!!! info "实时同步文档" + 本规范内容直接引用自英文原版文件 `specification/v0_8/docs/a2ui_extension_specification.md`。 + +!!! note "版本兼容性" + 此扩展规范适用于 A2UI v0.8 和 A2A 协议。对于基础 A2UI 协议，请参阅 [v0.8 协议规范](v0.8-a2ui.md)。 + +**相关文档：** +- [A2UI 协议 v0.8](v0.8-a2ui.md) (稳定版) +- [A2A 协议文档](https://a2a-protocol.org) + +--- + +--8<-- "specification/v0_8/docs/a2ui_extension_specification.md" diff --git a/docs/zh/specification/v0.8-a2ui.md b/docs/zh/specification/v0.8-a2ui.md new file mode 100644 index 00000000..e78bf3af --- /dev/null +++ b/docs/zh/specification/v0.8-a2ui.md @@ -0,0 +1,16 @@ +# A2UI 协议 v0.8 (稳定版) + +!!! success "稳定版本" + 版本 0.8 是当前的稳定版本，推荐用于生产。 + +!!! info "实时同步文档" + 本规范内容直接引用自英文原版文件 `specification/v0_8/docs/a2ui_protocol.md`。 + +**另请参阅：** +- [v0.9 协议规范](v0.9-a2ui.md) (草案) +- [演进指南：v0.8 → v0.9](v0.9-evolution-guide.md) +- [A2A 扩展规范](v0.8-a2a-extension.md) (用于 v0.8) + +--- + +--8<-- "specification/v0_8/docs/a2ui_protocol.md" diff --git a/docs/zh/specification/v0.9-a2ui.md b/docs/zh/specification/v0.9-a2ui.md new file mode 100644 index 00000000..bc5e9ba4 --- /dev/null +++ b/docs/zh/specification/v0.9-a2ui.md @@ -0,0 +1,15 @@ +# A2UI 协议 v0.9 (草案) + +!!! info "实时同步文档" + 本规范内容直接引用自英文原版文件 `specification/v0_9/docs/a2ui_protocol.md`。 + +!!! warning "草案状态" + 版本 0.9 目前处于草案状态。对于生产使用，请考虑 [v0.8 (稳定版)](v0.8-a2ui.md)。 + +**另请参阅：** +- [v0.8 协议规范](v0.8-a2ui.md) (稳定版) +- [演进指南：v0.8 → v0.9](v0.9-evolution-guide.md) + +--- + +--8<-- "specification/v0_9/docs/a2ui_protocol.md" diff --git a/docs/zh/specification/v0.9-evolution-guide.md b/docs/zh/specification/v0.9-evolution-guide.md new file mode 100644 index 00000000..c2022a7d --- /dev/null +++ b/docs/zh/specification/v0.9-evolution-guide.md @@ -0,0 +1,12 @@ +# 演进指南：v0.8 → v0.9 + +!!! info "实时同步文档" + 本指南内容直接引用自英文原版文件 `specification/v0_9/docs/evolution_guide.md`。 + +**相关文档：** +- [A2UI 协议 v0.8](v0.8-a2ui.md) (稳定版 - 您正在迁移的版本) +- [A2UI 协议 v0.9](v0.9-a2ui.md) (草案 - 您正在迁移到的版本) + +--- + +--8<-- "specification/v0_9/docs/evolution_guide.md" diff --git a/docs/zh/transports.md b/docs/zh/transports.md new file mode 100644 index 00000000..e1730a9f --- /dev/null +++ b/docs/zh/transports.md @@ -0,0 +1,76 @@ +# 传输 (消息传递) + +传输负责将 A2UI 消息从智能体传递到客户端。A2UI 与传输无关——可以使用任何能发送 JSON 的方法。 + +实际的组件渲染由 [渲染器 (renderer)](renderers.md) 完成， +而 [智能体 (agents)](agents.md) 负责生成 A2UI 消息。 +将消息从智能体传递到客户端是传输层的工作。 + +## 工作原理 + +``` +智能体 (Agent) → 传输 (Transport) → 客户端渲染器 (Client Renderer) +``` + +A2UI 定义了一系列 JSON 消息。传输层负责将此序列从智能体传递到客户端。常见的传输机制是使用像 JSON Lines (JSONL) 这样的流格式，其中每一行都是一条单独的 A2UI 消息。 + +## 可用传输 + +| 传输 | 状态 | 用例 | +|-----------|--------|----------| +| **A2A 协议** | ✅ 稳定 | 多智能体系统，企业网格 | +| **AG UI** | ✅ 稳定 | 全栈 React 应用程序 | +| **REST API** | 📋 计划中 | 简单的 HTTP 端点 | +| **WebSockets** | 💡 提议中 | 实时双向通信 | +| **SSE (Server-Sent Events)** | 💡 提议中 | Web 流式传输 | + +## A2A 协议 + +[Agent2Agent (A2A) 协议](https://a2a-protocol.org) 提供安全的、标准化的智能体通信。A2A 扩展提供了与 A2UI 的轻松集成。 + +**优势：** + +- 内置安全和身份验证 +- 支持多种消息格式、身份验证和传输协议的绑定 +- 清晰的关注点分离 + +如果您正在使用 A2A，这几乎应该是自动的。 + +TODO: 添加详细指南。 + +**参见：** [A2A 扩展规范](specification/v0.8-a2a-extension.md) + +## AG UI + +[AG UI](https://ag-ui.com/) 将 A2UI 消息转换为 AG UI 消息，并自动处理传输和状态同步。 + +如果您正在使用 AG UI，这应该是自动的。 + +TODO: 添加详细指南。 + +## 自定义传输 + +您可以使用任何发送 JSON 的传输方式： + +**HTTP/REST:** + +```javascript +// TODO: Add an example +``` + +**WebSockets:** + +```javascript +// TODO: Add an example +``` + +**Server-Sent Events:** + +```javascript +// TODO: Add an example +``` + +## 下一步 + +- **[A2A 协议文档](https://a2a-protocol.org)**：了解 A2A +- **[A2A 扩展规范](specification/v0.8-a2a-extension.md)**：A2UI + A2A 详情 diff --git a/mkdocs.yaml b/mkdocs.yaml index 96f22d65..7e47db02 100644 --- a/mkdocs.yaml +++ b/mkdocs.yaml @@ -19,6 +19,13 @@ site_author: Google site_dir: site extra: + alternate: + - name: English + link: / + lang: en + - name: 简体中文 + link: "/zh/" + lang: zh analytics: provider: google property: G-YX9TPV8DCC @@ -171,6 +178,48 @@ markdown_extensions: # Plugins plugins: + - i18n: + docs_structure: folder + languages: + - locale: en + default: true + name: English + - locale: zh + name: 简体中文 + nav_translations: + Home: 首页 + Introduction & FAQ: 简介与常见问题 + What is A2UI?: 什么是 A2UI？ + Who is it For?: 适用人群 + How Can I Use It?: 如何使用？ + Where is it Used?: 应用场景 + Agent UI Ecosystem: 智能体 UI 生态系统 + Quickstart: 快速开始 + A2UI Composer ⭐: A2UI 编辑器 ⭐ + Developer Guides: 开发者指南 + Client Setup: 客户端设置 + Agent Development: 智能体开发 + Custom Components: 自定义组件 + Theming & Styling: 主题与样式 + Core Concepts: 核心概念 + Overview: 概览 + Data Flow: 数据流 + Components & Structure: 组件与结构 + Data Binding: 数据绑定 + Specifications: 规范 + v0.8 (Stable): v0.8 (稳定版) + A2UI Specification: A2UI 规范 + A2A Extension: A2A 扩展 + v0.9 (Draft): v0.9 (草案) + Evolution Guide: 演进指南 + Renderers (Clients): 渲染器 (客户端) + Transports (Message Passing): 传输 (消息传递) + Agents (Server-side): 智能体 (服务端) + Community: 社区 + Roadmap: 路线图 + Reference: 参考 + Component Reference: 组件参考 + Message Reference: 消息参考 - search - macros # - include-markdown diff --git a/requirements-docs.txt b/requirements-docs.txt index 573152f2..43d63378 100644 --- a/requirements-docs.txt +++ b/requirements-docs.txt @@ -7,3 +7,4 @@ mkdocs-mermaid2-plugin sphinx furo myst-parser +mkdocs-static-i18n