GenUI SDK 主要组件与概念

genui package 围绕以下主要组件构建：

Conversation
package 的主要门面与入口。包含 SurfaceController 类，管理对话历史，并编排整个生成式 UI 流程。

Catalog
CatalogItem 对象的集合，定义 AI 允许使用的 widget 集。 SurfaceController 支持多个 catalog，便于将 widget 组织成逻辑分组。每个 CatalogItem 指定 widget 名称（供 AI 引用）、属性数据 schema，以及渲染 Flutter widget 的 builder 函数。

DataModel
所有动态 UI 状态的集中、可观察存储。 widget 绑定 到该模型中的数据；数据变化时，仅依赖该数据的 widget 会重建。

A2uiTransportAdapter
将来自 LLM 的原始文本流解析为供 SurfaceController 使用的 A2uiMessage 命令的桥梁。

A2uiMessage
由 AI 发送（经 A2uiTransportAdapter 解析）给 UI 的消息，指示其执行 createSurface、surfaceUpdate、dataModelUpdate 或 deleteSurface 等操作。

SurfaceController
处理 A2uiMessage，管理 DataModel，并维护 UI surface 的状态。

Conversation 管理交互周期：

1. 用户输入

   用户提供提示词（例如通过文本字段）。应用调用 conversation.sendMessage()。

2. AI 调用

   Conversation 将用户消息发送给 LLM SDK。

3. AI 响应

   LLM 在其系统提示词提供的 widget schema 引导下返回响应。

4. 流式传输处理

   LLM SDK 的文本流输入 A2uiTransportAdapter。

5. UI 状态更新

   适配器解析的 A2uiMessages 传给 SurfaceController.handleMessage()，更新 UI 状态与 DataModel。

6. UI 渲染

   SurfaceController 广播更新，监听该 surface ID 的 Surface widget 会重建。 widget 绑定 DataModel，数据变化时自动更新。

7. 回调

   文本响应与错误在 Conversation 上触发回调，或由你的 LLM 集成流程处理。

8. 用户交互

   用户与新生的 UI 交互（例如在文本字段中输入）。交互直接更新 DataModel。若为操作（如按钮点击），Surface 捕获事件并转发给 SurfaceController，后者自动创建包含数据模型当前状态的 UserMessage 并重启周期。

有关适用于 Flutter 的 GenUI SDK 实现的更多细节，请参阅 设计文档。

下一节将引导你把 genui 加入应用。