GenUI SDK 入门

本指南说明如何开始使用 GenUI SDK for Flutter 及其系列 package。 SDK 的关键组件见 主要组件 页面。

按以下说明将 genui 添加到你的 Flutter 应用。代码示例展示如何在运行 flutter create 创建的全新应用上操作，现有 Flutter 应用也可遵循相同步骤。

genui package 可连接多种智能体提供方，包括：

Firebase AI Logic
适用于与 LLM 的交互全部在 Flutter 客户端、无需服务器的生产应用。 Firebase 还便于安全交付 AI 功能，因为它负责管理 Gemini API 密钥。

GenUI A2UI
适用于智能体运行在服务器上的客户端/服务器架构。

自行构建
你也可以构建自己的适配器以连接首选 LLM 提供方。我们与社区很快会有更多方案。

若你为 iOS 或 macOS 构建 Flutter 项目，在 {ios,macos}/Runner/*.entitlements 文件中添加以下键以启用出站网络请求：

<dict>
...
<key>com.apple.security.network.client</key>
<true/>
</dict>

接下来，按以下说明将应用连接到所选智能体提供方。

1. 创建 SurfaceController，提供你希望向智能体开放的 widget catalog，并创建 A2uiTransportAdapter 解析消息并连接。

2. 创建 PromptBuilder，提供系统指令与工具（你希望智能体能调用的函数）。应始终包含 SurfaceController 提供的工具，也可添加其他工具，并写入 LLM 系统提示词。

3. 使用 SurfaceController 与 A2uiTransportAdapter 实例创建 Conversation；应用主要通过该对象完成工作。

   For example:

   dart

   class _MyHomePageState extends State<MyHomePage> {
     late final SurfaceController _surfaceController;
     late final A2uiTransportAdapter _transportAdapter;
     late final Conversation _conversation;
   ​
     @override
     void initState() {
       super.initState();
   ​
       // Create a SurfaceController with a widget catalog.
       // The BasicCatalogItems contain basic widgets for text, markdown, and images.
       _surfaceController = SurfaceController(catalogs: [BasicCatalogItems.asCatalog()]);
   ​
       // The Conversation wires transport -> controller internally.
       _transportAdapter = A2uiTransportAdapter(onSend: (message) async {
         // Implement sending to LLM and pipe chunks back.
       });
   ​
       final catalog = BasicCatalogItems.asCatalog();
       final promptBuilder = PromptBuilder.chat(
         catalog: catalog,
         systemPromptFragments: [
           '''
           You are an expert in creating funny riddles. Every time I give you a word,
           you should generate UI that displays one new riddle related to that word.
           Each riddle should have both a question and an answer.
           '''
         ],
       );
   ​
       // ... initialize your LLM Client of choice using promptBuilder.systemPromptJoined()
   ​
       // Create the Conversation to orchestrate everything.
       _conversation = Conversation(
         controller: _surfaceController,
         transport: _transportAdapter,
       );
   ​
       // Listen for surface lifecycle events:
       _conversation.events.listen((event) {
         if (event is ConversationSurfaceAdded) {
           _onSurfaceAdded(event);
         } else if (event is ConversationSurfaceRemoved) {
           _onSurfaceDeleted(event);
         }
       });
     }
   ​
     @override
     void dispose() {
       _textController.dispose();
       _conversation.dispose();
       _transportAdapter.dispose();
   ​
       super.dispose();
     }
   }
   

   content_copy

使用 Conversation 类的 sendRequest 方法向智能体发送请求，或直接流式传输到 LLM 客户端并用 _transportAdapter.addChunk 将结果流传入适配器。

要接收并显示生成的 UI：

1. 监听 Conversation 中的 events 流，来跟踪 UI 界面的生成和移除。这些事件包含每个界面的 surface ID。

2. 使用上一步收到的 surface ID，为每个界面构建一个 Surface widget。

   For example:

   dart

   class _MyHomePageState extends State<MyHomePage> {
     // ...
   ​
     final _textController = TextEditingController();
     final _surfaceIds = <String>[];
   ​
     // Send a request containing the user's [text] to the agent.
     void _sendMessage(String text) async {
       if (text.trim().isEmpty) return;
       // await _conversation.sendRequest(ChatMessage.user(TextPart(text)));
     }
   ​
     // Invoked by the events stream listener when a new
     // UI surface is generated. Here, the ID is stored so the
     // build method can create a Surface to display it.
     void _onSurfaceAdded(ConversationSurfaceAdded update) {
       setState(() {
         _surfaceIds.add(update.surfaceId);
       });
     }
   ​
     // Invoked by the events stream listener when a UI surface is removed.
     void _onSurfaceDeleted(ConversationSurfaceRemoved update) {
       setState(() {
         _surfaceIds.remove(update.surfaceId);
       });
     }
   ​
     @override
     Widget build(BuildContext context) {
       return Scaffold(
         appBar: AppBar(
           backgroundColor: Theme.of(context).colorScheme.inversePrimary,
           title: Text(widget.title),
         ),
         body: Column(
           children: [
             Expanded(
               child: ListView.builder(
                 itemCount: _surfaceIds.length,
                 itemBuilder: (context, index) {
                   // For each surface, create a Surface to display it.
                   final id = _surfaceIds[index];
                   return Surface(surfaceContext: _surfaceController.contextFor(id));
                 },
               ),
             ),
             SafeArea(
               child: Padding(
                 padding: const EdgeInsets.symmetric(horizontal: 16.0),
                 child: Row(
                   children: [
                     Expanded(
                       child: TextField(
                         controller: _textController,
                         decoration: const InputDecoration(
                           hintText: 'Enter a message',
                         ),
                       ),
                     ),
                     const SizedBox(width: 16),
                     ElevatedButton(
                       onPressed: () {
                         // Send the user's text to the agent.
                         _sendMessage(_textController.text);
                         _textController.clear();
                       },
                       child: const Text('Send'),
                     ),
                   ],
                 ),
               ),
             ),
           ],
         ),
       );
     }
   }
   

   content_copy

为方便起见，可使用提供的核心 widget catalog。但多数生产应用会希望定义自定义 widget catalog。

要添加自定义 widget，请按以下说明操作。

1. 依赖 json_schema_builder package

   使用 dart pub add 在 pubspec.yaml 文件中添加 json_schema_builder 依赖：

   $ dart pub add json_schema_builder
   

   content_copy

2. 创建新 widget 的 schema

   每个 catalog item 都需要一个 schema，用于定义填充它所需的数据。使用 json_schema_builder package 为新 widget 定义一个 schema。

   dart

   import 'package:json_schema_builder/json_schema_builder.dart';
   import 'package:flutter/material.dart';
   import 'package:genui/genui.dart';
   ​
   final _schema = S.object(
     properties: {
       'question': S.string(description: 'The question part of a riddle.'),
       'answer': S.string(description: 'The answer part of a riddle.'),
     },
     required: ['question', 'answer'],
   );
   

   content_copy

3. 创建 CatalogItem

   每个 CatalogItem 表示智能体允许生成的一类 widget。为此，它组合名称、schema，以及生成构成生成式 UI 的 widget 的 builder 函数。

   dart

   final riddleCard = CatalogItem(
     name: 'RiddleCard',
     dataSchema: _schema,
     widgetBuilder:
         ({
           required data,
           required id,
           required buildChild,
           required dispatchEvent,
           required context,
           required dataContext,
         }) {
           final json = data as Map<String, Object?>;
           final question = json['question'] as String;
           final answer = json['answer'] as String;
   ​
           return Container(
             constraints: const BoxConstraints(maxWidth: 400),
             decoration: BoxDecoration(border: Border.all()),
             padding: const EdgeInsets.all(16),
             child: Column(
               crossAxisAlignment: CrossAxisAlignment.start,
               children: [
                 Text(question, style: Theme.of(context).textTheme.headlineMedium),
                 const SizedBox(height: 8.0),
                 Text(answer, style: Theme.of(context).textTheme.headlineSmall),
               ],
             ),
           );
         },
   );
   

   content_copy

4. 将 CatalogItem 添加到 catalog

   实例化 SurfaceController 时包含你的 catalog item。

   dart

   _surfaceController = SurfaceController(
     catalogs: [BasicCatalogItems.asCatalog().copyWith([riddleCard])],
   );
   

   content_copy

5. 更新系统指令以使用新 widget

   为确保智能体知道要使用你的新 widget，请在系统指令中说明如何以及何时使用。说明时提供 CatalogItem 中的名称。

   dart

   final promptBuilder = PromptBuilder.chat(
     catalog: catalog,
     systemPromptFragments: [
       '''
       You are an expert in creating funny riddles. Every time I give you a word,
       generate a RiddleCard that displays one new riddle related to that word.
       Each riddle should have both a question and an answer.
       '''
     ],
   );
   ​
   // Pass promptBuilder.systemPromptJoined() to your LLM Config
   

   content_copy

genui 的核心概念是 DataModel——所有动态 UI 状态的集中、可观察存储。各 widget 不各自管理状态，而是将状态存入 DataModel。

widget 绑定 到该模型中的数据；模型中的数据变化时，仅依赖该数据的 widget 会重建。这通过传给各 widget builder 函数的 DataContext 对象实现。

要将 widget 属性绑定到数据模型，在 AI 发送的数据中指定特殊 JSON 对象。该对象可含标准 JSON 基元（静态值），或含 path 属性的对象（绑定到数据模型中的值）。

例如，要在 Text widget 中显示用户名，AI 会生成：

{
  "component": "Text",
  "text": "Welcome to GenUI",
  "variant": "h1"
}

{
  "component": "Image",
  "url": "https://example.com/image.png",
  "variant": "mediumFeature"
}

输入类 widget（如 TextField）直接更新 DataModel。用户在绑定到 /user/name 的文本字段中输入时，DataModel 更新，绑定同一路径的其他 widget 会自动重建以显示新值。

这种响应式数据流简化状态管理，并在用户、UI 与 AI 之间形成强大的高带宽交互循环。

查看 genui 仓库中的 示例。 旅行应用 展示如何定义智能体可用于生成领域特定 UI 的自定义 widget catalog。

若有不清楚或缺失之处，请 提交 issue。

genui package 为 LLM 提供一组可用于生成 UI 的工具。要让 LLM 使用这些工具，通过 PromptBuilder 提供的系统指令必须明确告知其这样做。

因此 先前的示例 为智能体包含系统指令，其中有「Every time I give you a word, you should generate UI that...」这样的表述：

final promptBuilder = PromptBuilder.chat(
  catalog: catalog,
  instructions: '''
    You are an expert in creating funny riddles.
    Every time I give you a word, you should generate UI that
    displays one new riddle related to that word.
    Each riddle should have both a question and an answer.
    ''',
);

要在 main 方法中观察应用与智能体之间的通信，请启用日志。

import 'package:logging/logging.dart';
import 'package:genui/genui.dart';
​
final logger = configureGenUiLogging(level: Level.ALL);
​
void main() async {
  logger.onRecord.listen((record) {
    debugPrint('${record.loggerName}: ${record.message}');
  });
​
  // Additional initialization of bindings and Firebase.
}

Firebase 对 Apple 平台有 最低版本要求，可能高于 Flutter 默认值。请检查 Podfile (iOS) 和 CMakeLists.txt (macOS)，确保目标版本满足或超过 Firebase 要求。