Skip to content

Commit 5912c76

Browse files
author
quzhichao.qzc
committed
docs: add Simplified Chinese (zh-CN) translation for A2UI documentation
- Translated all documentation files in `docs/` to `docs/zh/`. - Configured `mkdocs.yaml` for i18n support with `zh` locale and localized navigation. - Updated `specification` files to reference original English sources using `!--8<--` syntax to maintain single source of truth.
1 parent 46a1324 commit 5912c76

30 files changed

Lines changed: 3150 additions & 0 deletions

‎docs/zh/agents.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# 智能体 (服务端)
2+
3+
智能体是服务端程序，负责响应用户请求生成 A2UI 消息。
4+
5+
实际的组件渲染由 [渲染器](renderers.md) 完成，
6+
在消息传输到客户端之后 [传输](transports.md)。
7+
智能体仅负责生成 A2UI 消息。
8+
9+
## 智能体如何工作
10+
11+
```
12+
用户输入 → 智能体逻辑 → LLM → A2UI JSON → 发送到客户端
13+
```
14+
15+
1. **接收** 用户消息
16+
2. **处理** 使用 LLM (Gemini, GPT, Claude 等)
17+
3. **生成** A2UI JSON 消息作为结构化输出
18+
4. **发送** 到客户端通过传输
19+
20+
来自客户端的用户交互可以被视为新的用户输入。
21+
22+
## 示例智能体
23+
24+
A2UI 仓库包含您可以以此学习的示例智能体：
25+
26+
- [餐厅查找器](https://github.com/google/A2UI/tree/main/samples/agent/adk/restaurant_finder)
27+
- 带有表单的餐桌预订
28+
- 使用 ADK 编写
29+
- [联系人查找](https://github.com/google/A2UI/tree/main/samples/agent/adk/contact_lookup)
30+
- 带有结果列表的搜索
31+
- 使用 ADK 编写
32+
- [Rizzcharts](https://github.com/google/A2UI/tree/main/samples/agent/adk/rizzcharts)
33+
- A2UI 自定义组件演示
34+
- 使用 ADK 编写
35+
- [Orchestrator](https://github.com/google/A2UI/tree/main/samples/agent/adk/orchestrator)
36+
- 从远程子智能体传递 A2UI 消息
37+
- 使用 ADK 编写
38+
39+
## 您将使用 A2A 的不同类型的智能体
40+
41+
### 1. 面向用户的智能体 (独立)
42+
43+
面向用户的智能体是用户直接交互的智能体。
44+
45+
### 2. 作为远程智能体宿主的面向用户的智能体
46+
47+
这是一种模式，其中面向用户的智能体充当一个或多个远程智能体的宿主。面向用户的智能体将调用远程智能体，远程智能体将生成 A2UI 消息。这是 [A2A](https://a2a-protocol.org) 中的常见模式，客户端智能体调用服务器智能体。
48+
49+
- 面向用户的智能体可以“透传” A2UI 消息而不进行更改
50+
- 面向用户的智能体可以在将 A2UI 消息发送到客户端之前对其进行更改
51+
52+
### 3. 远程智能体
53+
54+
远程智能体不直接是面向用户 UI 的一部分。相反，它被注册为远程智能体，可以由面向用户的智能体调用。这是 [A2A](https://a2a-protocol.org) 中的常见模式，客户端智能体调用服务器智能体。

‎docs/zh/community.md‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
# 社区
2+
3+
欢迎来到 A2UI 社区！我们要共同构建智能体驱动界面的未来。
4+
5+
## 参与其中
6+
7+
A2UI 是一个基于 Apache 2.0 协议的开源项目。我们欢迎开发者、研究人员以及任何对推动智能体式用户界面感兴趣的人士参与贡献。
8+
9+
## 社区展示
10+
11+
!!! info "即将推出..."
12+
我们要正在考虑通过何种最佳方式来展示社区项目、示例、主题、渲染器、自定义组件等。在 Github discussions 中链接一个 4 分钟（或更短）的演示视频和代码示例是展示您作品的绝佳方式。
13+
14+
## 项目合作伙伴
15+
16+
A2UI 是与多个组织合作开发的：
17+
18+
### Google Opal
19+
20+
[Opal](http://opal.google) 让用户使用自然语言构建、编辑和分享 AI 小程序。Opal 团队一直是 A2UI 开发的核心贡献者。
21+
22+
### Flutter
23+
24+
[GenUI SDK for Flutter](https://docs.flutter.dev/ai/genui) 使用 A2UI 作为 UI 声明格式，用于在 Flutter 应用程序中生成动态、个性化的 UI。
25+
26+
### Gemini Enterprise
27+
28+
A2UI 正在被集成到 [Gemini Enterprise](https://cloud.google.com/gemini-enterprise?e=48754805) 中，以支持自定义智能体在企业应用程序中渲染丰富、交互式的 UI。
29+
30+
### AG UI / CopilotKit
31+
32+
[AG UI](https://ag-ui.com/) 和 [CopilotKit](https://www.copilotkit.ai/) 提供了对 A2UI 的零日兼容性，使开发人员能够构建富文本、状态同步的应用程序，从智能体中渲染动态 UI。
33+
34+
### A2A
35+
36+
Google 的 [A2A 团队](https://a2a-protocol.org/) 一直是 A2UI 开发的核心贡献者，并得到了 A2A 技术指导委员会 (TSC) 的支持。
37+
38+
### ... 还有更多
39+
40+
还有许多组织和个人为 A2UI 的开发做出了贡献。
41+
42+
如果您对 A2UI 做出了重大贡献，请将您的名字提交到此列表。
43+
44+
## 行为准则
45+
46+
我们致力于为每个人提供一个受欢迎且包容的环境。所有参与者都应遵循以下原则：
47+
48+
- 尊重并体贴他人
49+
- 欢迎不仅仅是新人，并帮助他们入门
50+
- 关注对社区最有利的事情
51+
- 对他人表现出同理心
52+
53+
我们绝不容忍不可接受的行为。请向项目维护者报告疑虑。
54+
55+
## 认可
56+
57+
我们感谢所有的贡献！贡献者将在以下地方得到认可：
58+
59+
- GitHub 的贡献者图表
60+
- 发布说明
61+
- 项目致谢
62+
63+
重大贡献者可能会被邀请加入项目的维护者团队。
64+
65+
## 保持更新
66+
67+
- **关注 (Watch) GitHub 仓库** 以获取通知
68+
- **星标 (Star) 仓库** 以加入书签并表示支持
69+
- **关注发布 (Follow releases)** 以获取新版本的通知
70+
71+
## 贡献方式
72+
73+
**[github.com/google/A2UI](https://github.com/google/A2UI)**
74+
75+
- **报告问题**：发现了 bug？[提交 Issue](https://github.com/google/A2UI/issues)
76+
- **构建渲染器**：查看[路线图](roadmap.md)以了解计划中的框架
77+
- **分享示例**：在 X/LinkedIn 上使用 `#A2UI` 发布，或者发起一个 [Discussion](https://github.com/google/A2UI/discussions)
78+
- **改进文档**：欢迎向 `docs/` 目录提交 PR
79+
80+
## 有问题？
81+
82+
- 查看 [文档](introduction/what-is-a2ui.md)
83+
- 搜索 [GitHub Discussions](https://github.com/google/A2UI/discussions)
84+
- 在 [GitHub Issues](https://github.com/google/A2UI/issues) 中提问
85+
86+
感谢您成为 A2UI 社区的一员！

‎docs/zh/composer.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# A2UI Composer
2+
3+
尝试使用 **CopilotKit A2UI Widget Builder** 交互式地构建 A2UI widgets。
4+
5+
[![A2UI Composer](../assets/A2UI-widget-builder.png)](https://go.copilotkit.ai/A2UI-widget-builder)
6+
7+
**[启动 Widget Builder →](https://go.copilotkit.ai/A2UI-widget-builder)**
8+
9+
## 功能
10+
11+
- 可视化地试验 A2UI 组件
12+
- 通过描述您想要的内荣来生成 A2UI JSON
13+
- 查看实时预览
14+
- 复制 JSON 以在您的智能体中使用
15+
16+
由 [CopilotKit](https://www.copilotkit.ai/) 团队构建。

‎docs/zh/concepts/components.md‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
# 组件与结构
2+
3+
A2UI 使用 **邻接表模型** 来表示组件层次结构。组件不是嵌套的 JSON 树，而是带有 ID 引用的扁平列表。
4+
5+
## 为什么是扁平列表？
6+
7+
**传统的嵌套方法：**
8+
9+
- LLM 必须一次性生成完美的嵌套
10+
- 难以更新深层嵌套的组件
11+
- 难以增量流式传输
12+
13+
**A2UI 邻接表：**
14+
15+
- ✅ 扁平结构，易于 LLM 生成
16+
- ✅ 增量发送组件
17+
- ✅ 通过 ID 更新任何组件
18+
- ✅ 清晰的结构与数据分离
19+
20+
## 邻接表模型
21+
22+
```json
23+
{
24+
"surfaceUpdate": {
25+
"components": [
26+
{"id": "root", "component": {"Column": {"children": {"explicitList": ["greeting", "buttons"]}}}},
27+
{"id": "greeting", "component": {"Text": {"text": {"literalString": "Hello"}}}},
28+
{"id": "buttons", "component": {"Row": {"children": {"explicitList": ["cancel-btn", "ok-btn"]}}}},
29+
{"id": "cancel-btn", "component": {"Button": {"child": "cancel-text", "action": {"name": "cancel"}}}},
30+
{"id": "cancel-text", "component": {"Text": {"text": {"literalString": "Cancel"}}}},
31+
{"id": "ok-btn", "component": {"Button": {"child": "ok-text", "action": {"name": "ok"}}}},
32+
{"id": "ok-text", "component": {"Text": {"text": {"literalString": "OK"}}}}
33+
]
34+
}
35+
}
36+
```
37+
38+
组件通过 ID 引用子级，而不是通过嵌套。
39+
40+
## 组件基础
41+
42+
每个组件都有：
43+
44+
1. **ID**: 唯一标识符 (`"welcome"`)
45+
2. **Type**: 组件类型 (`Text`, `Button`, `Card`)
46+
3. **Properties**: 特定于该类型的配置
47+
48+
```json
49+
{"id": "welcome", "component": {"Text": {"text": {"literalString": "Hello"}, "usageHint": "h1"}}}
50+
```
51+
52+
## 标准目录
53+
54+
A2UI 定义了一个按用途组织的标准组件目录：
55+
56+
- **布局 (Layout)**: Row, Column, List - 排列其他组件
57+
- **显示 (Display)**: Text, Image, Icon, Video, Divider - 显示信息
58+
- **交互 (Interactive)**: Button, TextField, CheckBox, DateTimeInput, Slider - 用户输入
59+
- **容器 (Container)**: Card, Tabs, Modal - 分组和组织内容
60+
61+
有关带有示例的完整组件库，请参见 [组件参考](../reference/components.md)。
62+
63+
## 静态 vs. 动态子级
64+
65+
**静态 (`explicitList`)** - 固定的子级 ID 列表：
66+
```json
67+
{"children": {"explicitList": ["back-btn", "title", "menu-btn"]}}
68+
```
69+
70+
**动态 (`template`)** - 从数据数组生成子级：
71+
```json
72+
{"children": {"template": {"dataBinding": "/items", "componentId": "item-template"}}}
73+
```
74+
75+
对于 `/items` 中的每个项目，渲染 `item-template`。有关详细信息，请参见 [数据绑定](data-binding.md)。
76+
77+
## 填充值
78+
79+
组件通过两种方式获取值：
80+
81+
- **字面量 (Literal)** - 固定值：`{"text": {"literalString": "Welcome"}}`
82+
- **数据绑定 (Data-bound)** - 来自数据模型：`{"text": {"path": "/user/name"}}`
83+
84+
LLM 可以生成具有字面量值的组件，或者将它们绑定到数据路径以获取动态内容。
85+
86+
## 组合 Surfaces
87+
88+
组件组合成 **Surfaces** (widgets)：
89+
90+
1. LLM 通过 `surfaceUpdate` 生成组件定义
91+
2. LLM 通过 `dataModelUpdate` 填充数据
92+
3. LLM 通过 `beginRendering` 信号通知渲染
93+
4. 客户端将所有组件渲染为原生 widgets
94+
95+
一个 Surface 是一个完整、紧凑的 UI（表单、仪表板、聊天等）。
96+
97+
## 增量更新
98+
99+
- **添加** - 发送带有新组件 ID 的新 `surfaceUpdate`
100+
- **更新** - 发送带有现有 ID 和新属性的 `surfaceUpdate`
101+
- **移除** - 更新父级的 `children` 列表以排除已移除的 ID
102+
103+
扁平结构使所有更新都是简单的基于 ID 的操作。
104+
105+
## 自定义组件
106+
107+
除了标准目录之外，客户端还可以定义针对特定领域需求的自定义组件：
108+
109+
- **如何做**：在您的渲染器中注册自定义组件类型
110+
- **什么**：图表、地图、自定义可视化、专用 widgets
111+
- **安全性**：自定义组件仍然是客户端受信任目录的一部分
112+
113+
自定义组件从客户端的渲染器 _通告 (advertised)_ 给 LLM。然后，LLM 可以在标准目录之外使用它们。
114+
115+
有关实现细节，请参见 [自定义组件指南](../guides/custom-components.md)。
116+
117+
## 最佳实践
118+
119+
1. **描述性 ID**: 使用 `"user-profile-card"` 而不是 `"c1"`
120+
2. **浅层级**: 避免深层嵌套
121+
3. **分离结构与内容**: 使用数据绑定，而不是字面量
122+
4. **使用模板复用**: 一个模板，通过动态子级生成许多实例

0 commit comments

Comments
 (0)