ساختن برنامه میانای کاربر زایا (GenUI)

۱. مقدمه

در این codelab، بااستفاده از Flutter،‏ Firebase AI Logic، و بسته جدید genui، برنامه فهرست تکالیف خواهید ساخت. با برنامه گپ مبتنی بر نوشتار شروع می‌کنید، آن را با GenUI ارتقا می‌دهید تا به عامل قدرت ایجاد میانای کاربر خود را بدهید، و درنهایت عنصر میانای کاربر تعاملی و سفارشی خودتان را می‌سازید که شما و عامل می‌توانید مستقیماً آن را دستکاری کنید.

برنامه فهرست تکالیف درحال اجرا در Chrome

آنچه انجام خواهید داد

  • ساختن میانای گپ پایه بااستفاده از Flutter و Firebase AI Logic
  • بسته genui را برای تولید سطوح مبتنی بر هوش مصنوعی ادغام کنید
  • نوار پیشرفتی اضافه کنید تا نشان دهد چه زمانی برنامه منتظر پاسخ ازسوی نماینده است
  • سطح نام‌گذاری‌شده‌ای ایجاد کنید و آن را در نقطه‌ای اختصاصی در میانای کاربری نشان دهید.
  • ساختن عنصر کاتالوگ GenUI سفارشی که به شما امکان می‌دهد نحوه ارائه تکالیف را کنترل کنید

آنچه نیاز خواهید داشت

این codelab برای توسعه‌دهندگان Flutter در سطح متوسط است.

۲. قبل‌از شروع

راه‌اندازی پروژه Flutter

  1. اگر قبلاً این کار را نکرده‌اید، Flutter SDK را به‌صورت محلی نصب کنید.
  2. پایانه را باز کنید و flutter create را اجرا کنید تا پروژه جدیدی بسازید:
    flutter create intro_to_genui
    cd intro_to_genui
    
  3. وابستگی‌های لازم را به پروژه Flutter خود اضافه کنید:
    flutter pub add firebase_core firebase_ai genui json_schema_builder
    
    بخش نهایی dependencies باید به این شکل باشد (شماره نسخه‌ها ممکن است کمی متفاوت باشد):
    dependencies:
      flutter:
        sdk: flutter
    
      cupertino_icons: ^1.0.9
      firebase_core: ^4.15.0
      firebase_ai: ^4.0.0
      genui: ^0.10.3
      json_schema_builder: ^0.1.7
    
  4. flutter pub get را اجرا کنید تا همه بسته‌ها بارگیری شود.اگر پیام‌واره‌ای دریافت کردید که نسخه‌های جدیدتر بسته دردسترس است، می‌توانید flutter pub outdated را اجرا کنید تا نسخه‌ها را بررسی کنید و flutter pub upgrade را اجرا کنید تا وابستگی‌هایتان را به‌روز کنید.

راه‌اندازی پروژه Firebase

  1. اگر قبلاً واسط خط فرمان Firebase را نصب نکرده‌اید، آن را نصب کنید.
  2. بااستفاده از «حساب Google» خود به سیستم Firebase وارد شوید:
    firebase login
    
  3. FlutterFire CLI را نصب کنید:
    dart pub global activate flutterfire_cli
    
  4. از فهرست راهنمای پروژه Flutter، فرمان زیر را اجرا کنید تا پروژه Flutter شما برای استفاده از Firebase پیکربندی شود:
    flutterfire configure
    
    این فرمان کارهای زیر را انجام می‌دهد:
    1. از شما می‌پرسد که آیا می‌خواهید از پروژه Firebase موجود استفاده کنید یا پروژه Firebase جدیدی ایجاد کنید. ایجاد پروژه Firebase جدید را انتخاب کنید.
    2. از شما می‌پرسد که می‌خواهید برنامه Flutter شما کدام پلاتفرم (iOS،‏ Android،‏ Web) را هدف قرار دهد. درحال‌حاضر، Web را انتخاب کنید.

دستور flutterfire configure به‌طور خودکار یک پروژه Firebase و یک «برنامه وب Firebase» جدید در آن پروژه Firebase ایجاد می‌کند. سپس این فرمان یک فایل پیکربندی Firebase (firebase_options.dart) ایجاد می‌کند و آن را به‌طور خودکار به دایرکتوری lib/ پروژه Flutter شما اضافه می‌کند.

توجه داشته باشید که برنامه این codelab فقط با Flutter SDK و Chrome نصب‌شده در دستگاهتان کار می‌کند (یعنی به‌عنوان برنامه وب ساخته می‌شود). بااین‌حال، چون این برنامه با Flutter ساخته شده است، در پلاتفرم‌های دیگر هم کار خواهد کرد! بنابراین در پایان codelab، سعی کنید flutterfire configure را دوباره اجرا کنید تا پشتیبانی از iOS،‏ Android، یا پلاتفرم دیگری را اضافه کنید، و سپس برنامه را در آن پلاتفرم بازسازی کنید.

برای اطلاعات بیشتر، دستورالعمل‌های افزودن Firebase به برنامه Flutter را بررسی کنید.

راه‌اندازی Firebase AI Logic

  1. به سیستم کنسول Firebase وارد شوید. از همان «حساب Google» استفاده کنید که برای ورود به سیستم «واسط خط فرمان Firebase» استفاده کردید.
  2. پروژه Firebase را که به‌تازگی بااستفاده از FlutterFire CLI ساخته‌اید انتخاب کنید.
  3. از منوِ پیمایش سمت راست، خدمات هوش مصنوعی > منطق هوش مصنوعی را انتخاب کنید.
  4. روی شروع به کار کلیک کنید تا گردش کار راهنمایی‌شده راه‌اندازی شود.
  5. برای شروع کار با Gemini Developer API، انتخاب کنید و پیام‌واره‌های روی صفحه را برای راه‌اندازی Firebase AI Logic دنبال کنید.

ازبخش «راه‌اندازی پروژه Flutter»، افزایه‌های FlutterFire موردنیاز را برای استفاده از Firebase AI Logic دارید. در مرحله بعد، آماده‌اید که به کدنویسی برنامه‌تان بپردازید!

۳. ساختن میانای گپ پایه

قبل‌از معرفی «میانای کاربر زایا»، برنامه‌تان به یک پایه نیاز دارد: یک برنامه گپ نوشتاری پایه با بهره‌گیری از Firebase AI Logic. برای شروع سریع، کل راه‌اندازی واسط گپ را کپی و جای‌گذاری خواهید کرد.

نسخه نوشتاری برنامه

ایجاد ابزاره حبابک پیام

برنامه شما برای نمایش پیامک‌های کاربر و کارگزار به ابزاره نیاز دارد. فایل جدیدی به‌نام lib/message_bubble.dart بسازید و کلاس زیر را اضافه کنید:

import 'package:flutter/material.dart';

class MessageBubble extends StatelessWidget {
  final String text;
  final bool isUser;

  const MessageBubble({super.key, required this.text, required this.isUser});

  @override
  Widget build(BuildContext context) {
    final theme = Theme.of(context);
    final colorScheme = theme.colorScheme;

    final bubbleColor = isUser
        ? colorScheme.primary
        : colorScheme.surfaceContainerHighest;

    final textColor = isUser
        ? colorScheme.onPrimary
        : colorScheme.onSurfaceVariant;

    return Padding(
      padding: const EdgeInsets.symmetric(vertical: 6.0, horizontal: 8.0),
      child: Column(
        crossAxisAlignment: isUser
            ? CrossAxisAlignment.end
            : CrossAxisAlignment.start,
        children: [
          Row(
            mainAxisAlignment: isUser
                ? MainAxisAlignment.end
                : MainAxisAlignment.start,
            children: [
              Flexible(
                child: Container(
                  padding: const EdgeInsets.symmetric(
                    horizontal: 16.0,
                    vertical: 12.0,
                  ),
                  decoration: BoxDecoration(
                    color: bubbleColor,
                    borderRadius: BorderRadius.only(
                      topLeft: const Radius.circular(20),
                      topRight: const Radius.circular(20),
                      bottomLeft: Radius.circular(isUser ? 20 : 0),
                      bottomRight: Radius.circular(isUser ? 0 : 20),
                    ),
                    boxShadow: [
                      BoxShadow(
                        color: Colors.black.withAlpha(20),
                        blurRadius: 4,
                        offset: const Offset(0, 2),
                      ),
                    ],
                    gradient: isUser
                        ? LinearGradient(
                            colors: [
                              colorScheme.primary,
                              colorScheme.primary.withAlpha(200),
                            ],
                            begin: Alignment.topLeft,
                            end: Alignment.bottomRight,
                          )
                        : null,
                  ),
                  child: Text(
                    text,
                    style: theme.textTheme.bodyLarge?.copyWith(
                      color: textColor,
                      height: 1.3,
                    ),
                  ),
                ),
              ),
            ],
          ),
          const SizedBox(height: 2),
        ],
      ),
    );
  }
}

‫MessageBubble یک StatelessWidget است که یک پیام گپ را نمایش می‌دهد. بعداً در این codelab از آن برای نشان دادن پیام‌های شما و عامل استفاده خواهد شد، اما بیشتر فقط یک ابزاره Text فانتزی است.

پیاده‌سازی میانای کاربر Chat در main.dart

کل محتوای lib/main.dart را با این پیاده‌سازی کامل روبات گپ نوشتاری جایگزین کنید:

import 'package:flutter/material.dart';
import 'package:firebase_core/firebase_core.dart';
import 'package:firebase_ai/firebase_ai.dart';
import 'package:intro_to_genui/message_bubble.dart';
import 'firebase_options.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp(options: DefaultFirebaseOptions.currentPlatform);
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Just Today',
      theme: ThemeData(
        colorScheme: ColorScheme.fromSeed(seedColor: Colors.blue),
      ),
      home: const MyHomePage(),
    );
  }
}

class MyHomePage extends StatefulWidget {
  const MyHomePage({super.key});

  @override
  State<MyHomePage> createState() => _MyHomePageState();
}

sealed class ConversationItem {}

class TextItem extends ConversationItem {
  final String text;
  final bool isUser;
  TextItem({required this.text, this.isUser = false});
}

class _MyHomePageState extends State<MyHomePage> {
  final List<ConversationItem> _items = [];
  final _textController = TextEditingController();
  final _scrollController = ScrollController();
  late final ChatSession _chatSession;

  @override
  void initState() {
    super.initState();
    final model = FirebaseAI.googleAI().generativeModel(
      model: 'gemini-3.5-flash',
    );
    _chatSession = model.startChat();
    _chatSession.sendMessage(Content.text(systemInstruction));
  }

  void _scrollToBottom() {
    WidgetsBinding.instance.addPostFrameCallback((_) {
      if (_scrollController.hasClients) {
        _scrollController.animateTo(
          _scrollController.position.maxScrollExtent,
          duration: const Duration(milliseconds: 300),
          curve: Curves.easeOut,
        );
      }
    });
  }

  @override
  void dispose() {
    _textController.dispose();
    _scrollController.dispose();
    super.dispose();
  }

  Future<void> _addMessage() async {
    final text = _textController.text;

    if (text.trim().isEmpty) {
      return;
    }
    _textController.clear();

    setState(() {
      _items.add(TextItem(text: text, isUser: true));
    });

    _scrollToBottom();

    final response = await _chatSession.sendMessage(Content.text(text));

    if (response.text?.isNotEmpty ?? false) {
      setState(() {
        _items.add(TextItem(text: response.text!, isUser: false));
      });
      _scrollToBottom();
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        backgroundColor: Theme.of(context).colorScheme.inversePrimary,
        title: const Text('Just Today'),
      ),
      body: Column(
        children: [
          Expanded(
            child: ListView(
              controller: _scrollController,
              padding: const EdgeInsets.all(16),
              children: [
                for (final item in _items)
                  switch (item) {
                    TextItem() => MessageBubble(
                          text: item.text,
                          isUser: item.isUser,
                        ),
                  },
              ],
            ),
          ),
          SafeArea(
            child: Padding(
              padding: const EdgeInsets.symmetric(horizontal: 16.0),
              child: Row(
                children: [
                  Expanded(
                    child: TextField(
                      controller: _textController,
                      onSubmitted: (_) => _addMessage(),
                      decoration: const InputDecoration(
                        hintText: 'Enter a message',
                      ),
                    ),
                  ),
                  const SizedBox(width: 8),
                  ElevatedButton(
                    onPressed: _addMessage,
                    child: const Text('Send'),
                  ),
                ],
              ),
            ),
          ),
        ],
      ),
    );
  }
}

const systemInstruction = '''
  ## PERSONA
  You are an expert task planner.

  ## GOAL
  Work with me to produce a list of tasks that I should do today, and then track
  the completion status of each one.

  ## RULES
  Talk with me only about tasks that I should do today.
  Do not engage in conversation about any other topic.
  Do not offer suggestions unless I ask for them.
  Do not offer encouragement unless I ask for it.
  Do not offer advice unless I ask for it.
  Do not offer opinions unless I ask for them.

  ## PROCESS
  ### Planning
  *   Ask me for information about tasks that I should do today.
  *   Synthesize a list of tasks from that information.
  *   Ask clarifying questions if you need to.
  *   When you have a list of tasks that you think I should do today, present it
    to me for review.
  *   Respond to my suggestions for changes, if I have any, until I accept the
    list.

  ### Tracking
  *   Once the list is accepted, ask me to let you know when individual tasks are
    complete.
  *   If I tell you a task is complete, mark it as complete.
  *   Once all tasks are complete, send a message acknowledging that, and then
    end the conversation.
''';

فایل main.dart که به‌تازگی کپی و جای‌گذاری کردید، ChatSession پایه را بااستفاده از Firebase AI Logic و پیام‌واره در systemInstruction راه‌اندازی می‌کند. این کلاس با حفظ فهرستی از عناصر TextItem و نمایش آن‌ها در کنار پُرسمان‌های کاربر بااستفاده از ابزاره MessageBubble که قبلاً ایجاد کرده‌اید، نوبت‌های مکالمه را مدیریت می‌کند.

در اینجا چند مورد وجود دارد که قبل‌از ادامه دادن باید بررسی کنید:

  • روش initState جایی است که اتصال به Firebase AI Logic راه‌اندازی می‌شود.
  • این برنامه TextField و دکمه‌ای برای ارسال پیام به نماینده ارائه می‌دهد.
  • روش _addMessage جایی است که پیام کاربر به عامل ارسال می‌شود.
  • فهرست _items جایی است که سابقه مکالمه در آن ذخیره می‌شود.
  • پیام‌ها در ListView بااستفاده از ابزاره MessageBubble نمایش داده می‌شود.

آزمایش برنامه

با قرار دادن این کد در محل، اکنون می‌توانید برنامه را اجرا و آزمایش کنید.

flutter run -d chrome

درباره تکالیفی که می‌خواهید امروز انجام دهید با نماینده گپ بزنید. اگرچه میانای کاربر صرفاً نوشتاری می‌تواند کار را انجام دهد، اما GenUI می‌تواند تجربه را آسان‌تر و سریع‌تر کند.

پس‌از تکمیل آزمایش، قبل‌از رفتن به مرحله بعدی، با فشار دادن q (یا Ctrl+C) در پایانه، برنامه درحال اجرا را متوقف کنید.

۴. ادغام کردن بسته GenUI

اکنون زمان ارتقا از نوشتار ساده به «رابط کاربری زایا» است. حلقه پیام‌رسانی Firebase پایه را با اشیای GenUI Conversation،‏ Catalog، و SurfaceController جایگزین خواهید کرد. این کار به مدل هوش مصنوعی اجازه می‌دهد تا ابزاره‌های واقعی Flutter را در جریان گپ نمونه‌سازی کند.

نسخه‌ای از برنامه با GenUI یکپارچه‌شده

بسته genui پنج کلاس ارائه می‌دهد که در سراسر این codelab از آن‌ها استفاده خواهید کرد:

  • SurfaceController میانای کاربر نقشه‌ها که توسط مدل برای صفحه‌نمایش تولید شده است.
  • A2uiTransportAdapter درخواست‌های GenUI داخلی را با هر مدل زبانی خارجی مرتبط می‌کند.
  • ‫Conversation کنترل‌کننده و آداپتور انتقال را با یک API واحد و یکپارچه برای برنامه Flutter شما می‌پیچد.
  • Catalog ابزارک‌ها و ویژگی‌های دردسترس برای مدل زبانی را توصیف می‌کند.
  • ‫Surface ابزاره‌ای است که واسط کاربر تولیدشده توسط مدل را نمایش می‌دهد.

برای نمایش Surface تولیدشده آماده شوید

در lib/main.dart، کد موجود شامل کلاس TextItem است که نشان‌دهنده یک پیامک در مکالمه است. بلافاصله پس‌از کلاس TextItem، کلاس SurfaceItem را اضافه کنید تا Surface ایجادشده توسط نماینده را نشان دهد:

class TextItem extends ConversationItem {
  // ... existing code ...
}

// New!
class SurfaceItem extends ConversationItem {
  final String surfaceId;
  SurfaceItem({required this.surfaceId});
}

مقداردهی اولیه عناصر اصلی GenUI

در بالای lib/main.dart، کتابخانه genui را وارد کنید:

import 'package:genui/genui.dart' hide TextPart;
import 'package:genui/genui.dart' as genui;

هر دو بسته genui و firebase_ai شامل کلاس TextPart هستند. با وارد کردن genui به این روش، نسخه TextPart آن را به‌عنوان genui.TextPart فضای نام‌گذاری می‌کنید و از تداخل نام جلوگیری می‌کنید.

کنترل‌کننده‌های عملکردی اصلی را در _MyHomePageState پس‌از _chatSession اعلام کنید:

class _MyHomePageState extends State<MyHomePage> {
  // ... existing members
  late final ChatSession _chatSession;

  // Add GenUI controllers
  late final SurfaceController _controller;
  late final A2uiTransportAdapter _transport;
  late final Conversation _conversation;
  late final Catalog catalog;

سپس، initState را به‌روز کنید تا کنترل‌کننده‌های کتابخانه GenUI آماده شود.

برداشتن این خط از initState:

_chatSession.sendMessage(Content.text(systemInstruction));

سپس، کد زیر را اضافه کنید:

@override
void initState() {
  // ... existing code ...

  // Initialize the GenUI Catalog.
  // The genui package provides a default set of primitive widgets (like text
  // and basic buttons) out of the box using this class.
  catalog = BasicCatalogItems.asCatalog();

  // Create a SurfaceController to manage the state of generated surfaces.
  _controller = SurfaceController(catalogs: [catalog]);

  // Create a transport adapter that will process messages to and from the
  // agent, looking for A2UI messages.
  _transport = A2uiTransportAdapter(onSend: _sendAndReceive);

  // Link the transport and SurfaceController together in a Conversation,
  // which provides your app a unified API for interacting with the agent.
  _conversation = Conversation(
    controller: _controller,
    transport: _transport,
  );
}

این کد یک نمای Conversation ایجاد می‌کند که کنترل‌کننده و آداپتور را مدیریت می‌کند. آن مکالمه جریانی از رویدادها را به برنامه شما ارائه می‌دهد که می‌تواند از آن برای همگام شدن با آنچه عامل ایجاد می‌کند استفاده کند، و همچنین روشی برای ارسال پیام به عامل ارائه می‌دهد.

سپس، شنونده‌ای برای رویدادهای مکالمه ایجاد کنید. این رویدادها شامل رویدادهای مربوط به سطح و همچنین رویدادهای مربوط به پیام‌های نوشتاری و خطاها می‌شود:

@override
void initState() {
  // ... existing code ...

  // Listen to GenUI stream events to update the UI
  _conversation.events.listen((event) {
    setState(() {
      switch (event) {
        case ConversationSurfaceAdded added:
          _items.add(SurfaceItem(surfaceId: added.surfaceId));
          _scrollToBottom();
        case ConversationSurfaceRemoved removed:
          _items.removeWhere(
            (item) =>
                item is SurfaceItem && item.surfaceId == removed.surfaceId,
          );
        case ConversationContentReceived content:
          _items.add(TextItem(text: content.text, isUser: false));
          _scrollToBottom();
        case ConversationError error:
          debugPrint('GenUI Error: ${error.error}');
        default:
      }
    });
  });
}

در آخر، پیام‌واره سیستم را ایجاد کنید و آن را برای عامل ارسال کنید:

  @override
  void initState() {
    // ... existing code ...

    // Create the system prompt for the agent, which will include this app's
    // system instruction as well as the schema for the catalog.
    final promptBuilder = PromptBuilder.chat(
      catalog: catalog,
      systemPromptFragments: [systemInstruction],
    );

    // Send the prompt into the Conversation, which will subsequently route it
    // to Firebase using the transport mechanism.
    _conversation.sendRequest(
      ChatMessage.system(promptBuilder.systemPromptJoined()),
    );
  }

همچنین روش dispose() را در _MyHomePageState به‌روز کنید تا کنترل‌کننده‌های GenUI که به‌تازگی اضافه شده‌اند هنگام دور انداختن ابزاره به‌درستی پاک‌سازی شوند:

  @override
  void dispose() {
    _conversation.dispose();
    _transport.dispose();
    _controller.dispose();
    _textController.dispose();
    _scrollController.dispose();
    super.dispose();
  }

سطوح نمایش

سپس، روش build ListView را به‌روز کنید تا SurfaceItem در فهرست _items نمایش داده شود:

Expanded(
  child: ListView(
    controller: _scrollController,
    padding: const EdgeInsets.all(16),
    children: [
      for (final item in _items)
        switch (item) {
          TextItem() => MessageBubble(
            text: item.text,
            isUser: item.isUser,
          ),
          // New!
          SurfaceItem() => Surface(
            surfaceContext: _controller.contextFor(
              item.surfaceId,
            ),
          ),
        },
    ],
  ),
),

سازنده ابزارک Surface یک surfaceContext می‌گیرد که به آن می‌گوید مسئول نمایش در کدام سطح است. SurfaceController که قبلاً ایجاد شده است، _controller، تعریف و وضعیت هر سطح را ارائه می‌دهد و مطمئن می‌شود که درصورت وجود به‌روزرسانی، بازسازی شود.

متصل کردن GenUI به Firebase AI Logic

بسته genui از رویکرد «مدل خودتان را بیاورید» استفاده می‌کند، یعنی شما کنترل می‌کنید کدام «مدل زبانی بزرگ» تجربه شما را تقویت کند. در این مورد، از Firebase AI Logic استفاده می‌کنید، اما این بسته برای کار با انواع مختلف عامل‌ها و ارائه‌دهندگان ساخته شده است.

این آزادی منجر به کمی مسئولیت بیشتر می‌شود: باید پیام‌های تولیدشده توسط بسته genui را بگیرید و آن‌ها را به عامل انتخابی‌تان ارسال کنید، و باید پاسخ‌های عامل را بگیرید و آن‌ها را به genui برگردانید.

برای انجام این کار، روش _sendAndReceive را که در کد مرحله قبل به آن ارجاع داده شده است تعریف خواهید کرد. در lib/main.dart،‏ _sendAndReceive را به کلاس _MyHomePageState اضافه کنید (برای مثال، درست بعداز خط late final Catalog catalog;):

class _MyHomePageState extends State<MyHomePage> {
  // ... existing code ...
  late final Catalog catalog;

  // New!
  Future<void> _sendAndReceive(ChatMessage msg) async {
    final buffer = StringBuffer();

    // Reconstruct the message part fragments
    for (final part in msg.parts) {
      if (part.isUiInteractionPart) {
        buffer.write(part.asUiInteractionPart!.interaction);
      } else if (part is genui.TextPart) {
        buffer.write(part.text);
      }
    }

    if (buffer.isEmpty) {
      return;
    }

    final text = buffer.toString();

    // Send the string to Firebase AI Logic.
    final response = await _chatSession.sendMessage(Content.text(text));

    if (response.text?.isNotEmpty ?? false) {
      // Feed the response back into GenUI's transportation layer
      _transport.addChunk(response.text!);
    }
  }

این روش هرگاه بسته genui نیاز به ارسال پیام به نماینده داشته باشد، توسط آن فراخوانی می‌شود. فراخوانی addChunk در پایان روش، پاسخ نماینده را به بسته genui برمی‌گرداند و به آن اجازه می‌دهد پاسخ را پردازش کند و واسط کاربر تولید کند.

درنهایت، روش _addMessage موجود را به‌طور کامل با این نسخه جدید جایگزین کنید تا پیام‌ها به‌جای Firebase مستقیماً به Conversation هدایت شوند:

  Future<void> _addMessage() async {
    final text = _textController.text;

    if (text.trim().isEmpty) {
      return;
    }

    _textController.clear();

    setState(() {
      _items.add(TextItem(text: text, isUser: true));
    });

    _scrollToBottom();

    // Send the user's input through GenUI instead of directly to Firebase.
    await _conversation.sendRequest(ChatMessage.user(text));
  }

فقط همین! برنامه را دوباره اجرا کنید. علاوه‌بر پیام‌های نوشتاری، خواهید دید که نماینده سطوح میانای کاربری مانند دکمه‌ها، ابزاره‌های نوشتاری، و غیره را تولید می‌کند.

حتی می‌توانید از عامل بخواهید واسط کاربر را به‌روش خاصی نمایش دهد. برای مثال، پیامی مثل «تکالیفم را در ستونی با دکمه‌ای برای علامت زدن هریک از آن‌ها به‌عنوان تکمیل‌شده نشان بده» را امتحان کنید.

۵. افزودن وضعیت انتظار

تولید LLM ناهمگام است. در مدتی که منتظر پاسخ هستید، میانای گپ باید دکمه‌های ورودی را غیرفعال کند و نشانگر پیشرفتی را نمایش دهد تا کاربر بداند GenUI درحال ایجاد محتوا است. خوشبختانه، بسته genui Listenable را ارائه می‌دهد که می‌توانید از آن برای پیگیری وضعیت مکالمه استفاده کنید. این مقدار ConversationState شامل ویژگی isWaiting است تا مشخص شود که آیا مدل درحال تولید محتوا است یا نه.

کنترل‌های ورودی را با ValueListenableBuilder بپوشانید

در روش build از _MyHomePageState در lib/main.dart، ابزارک SafeArea را در پایین Column پیدا کنید و فرزند آن Row (که حاوی TextField و ElevatedButton شما است) را با ValueListenableBuilder که به _conversation.state گوش می‌دهد بپیچید. با بازرسی state.isWaiting، می‌توانید ورودی را درحالی‌که مدل درحال تولید محتوا است غیرفعال کنید:

SafeArea(
  child: Padding(
    padding: const EdgeInsets.symmetric(horizontal: 16.0),
    // Wrap the Row in a ValueListenableBuilder:
    child: ValueListenableBuilder<ConversationState>(
      valueListenable: _conversation.state,
      builder: (context, state, child) {
        return Row(
          children: [
            Expanded(
              child: TextField(
                controller: _textController,
                // Also disable the Enter key submission when waiting!
                onSubmitted: state.isWaiting ? null : (_) => _addMessage(),
                decoration: const InputDecoration(
                  hintText: 'Enter a message',
                ),
              ),
            ),
            const SizedBox(width: 8),
            ElevatedButton(
              // Disable the send button when the model is generating
              onPressed: state.isWaiting ? null : _addMessage,
              child: const Text('Send'),
            ),
          ],
        );
      },
    ),
  ),
),

افزودن نوار پیشرفت

در روش build از _MyHomePageState، ابزاره اصلی Column را در Stack بپیچید و ValueListenableBuilder را که LinearProgressIndicator را به‌عنوان فرزند دوم آن Stack ارائه می‌دهد اضافه کنید. وقتی کارتان تمام شد، body Scaffold شما باید به این شکل باشد:

body: Stack( // New!
  children: [
    Column(
      children: [
        // ... existing Expanded and SafeArea widgets ...
      ],
    ),
    // Listen to the state again, this time to render a progress indicator
    ValueListenableBuilder<ConversationState>(
      valueListenable: _conversation.state,
      builder: (context, state, child) {
        if (state.isWaiting) {
          return const LinearProgressIndicator();
        }
        return const SizedBox.shrink();
      },
    ),
  ],
),

‫۶. ماندگار کردن سطح GenUI

تاکنون، فهرست تکلیف در جاری‌سازی گپ پیمایشی ارائه شده است و هر پیام یا سطح جدیدی که می‌رسد به فهرست اضافه می‌شود. در مرحله بعد، خواهید دید که چگونه سطحی را نام‌گذاری کنید و آن را در مکان خاصی در رابط کاربری نمایش دهید.

ابتدا، در بالای lib/main.dart، قبل‌از void main()، ثابتی را برای استفاده به‌عنوان شناسه سطح تعریف کنید:

const taskDisplaySurfaceId = 'task_display';

دوم، در initState()، عبارت switch را در شنونده Conversation به‌روز کنید تا مطمئن شوید هیچ سطحی با آن شناسه به _items اضافه نمی‌شود. برای دستیابی به این هدف، شاخه case ConversationSurfaceAdded added: را در _conversation.events.listen با پیچیدن خطوط _items.add(...) و _scrollToBottom() در عبارت if به‌روز کنید:

_conversation.events.listen((event) {
  setState(() {
    switch (event) {
      case ConversationSurfaceAdded added:
        // Wrap these two lines in an if check:
        if (added.surfaceId != taskDisplaySurfaceId) {
          _items.add(SurfaceItem(surfaceId: added.surfaceId));
          _scrollToBottom();
        }
      case ConversationSurfaceRemoved removed:
        // ... existing code ...

سپس، ساختار چیدمان درخت ابزارک را در _MyHomePageState.build باز کنید تا فضایی برای سطح سنجاق‌شده درست قبل‌از گزارش گپ ایجاد کنید. ‫AnimatedSize و const Divider() را به‌عنوان دو فرزند اول Column اصلی، درست قبل‌از کد Expanded(child: ListView(...)) درج کنید:

body: Stack(
  children: [
    Column(
      children: [
        // Insert these two new widgets at the top of the Column:
        AnimatedSize(
          duration: const Duration(milliseconds: 300),
          child: Container(
            padding: const EdgeInsets.all(16),
            alignment: Alignment.topLeft,
            child: Surface(
              surfaceContext: _controller.contextFor(
                taskDisplaySurfaceId,
              ),
            ),
          ),
        ),
        const Divider(),
        Expanded(
          child: ListView(
            // ... existing code ...

تاکنون، عاملی که ساخته‌اید اختیار تام داشته است تا سطوح را به‌گونه‌ای که مناسب می‌داند ایجاد کند و از آن‌ها استفاده کند. برای ارائه دستورالعمل‌های خاص‌تر به آن، باید پیام‌واره سیستم را بازبینی کنید. بخش ## USER INTERFACE زیر را به انتهای پیام‌واره ذخیره‌شده در ثابت systemInstruction اضافه کنید:

const systemInstruction = '''
  // ... existing prompt content ...

  ## USER INTERFACE
  *   To display the list of tasks create one and only one instance of the
    TaskDisplay catalog item. Use "$taskDisplaySurfaceId" as its surface ID.
  *   Update $taskDisplaySurfaceId as necessary when the list changes.
  *   $taskDisplaySurfaceId must include a button for each task that I can use
    to mark it complete. When I use that button to mark a task complete, it
    should send you a message indicating what I've done.
  *   Avoid repeating the same information in a single message.
  *   When responding with text, rather than A2UI messages, be brief.
''';

مهم است که به نماینده‌تان دستورالعمل‌های واضحی درباره زمان و نحوه استفاده از سطوح میانای کاربری بدهید. با گفتن به نماینده برای استفاده از یک مورد کاتالوگ خاص و شناسه سطح (و استفاده مجدد از یک نمونه واحد)، می‌توانید مطمئن شوید که واسطی را که می‌خواهید ببینید ایجاد می‌کند.

کارهای بیشتری باید انجام شود، اما می‌توانید دوباره برنامه‌تان را اجرا کنید تا ببینید که عامل سطح نمایش تکلیف را در بالای واسط کاربر ایجاد می‌کند.

‫۷. ساختن ابزاره کاتالوگ سفارشی

در این مرحله، مورد کاتالوگ TaskDisplay وجود ندارد. در چند مرحله بعدی، این مشکل را با ایجاد یک طرح‌واره داده، یک کلاس برای تجزیه آن طرح‌واره، یک ابزاره، و مورد کاتالوگی که همه چیز را کنار هم قرار می‌دهد، برطرف خواهید کرد.

ابتدا فایل جدیدی به‌نام task_display.dart را در فهرست راهنمای lib/ پروژه خود ایجاد کنید و واردات زیر را اضافه کنید:

import 'package:flutter/material.dart';
import 'package:genui/genui.dart';
import 'package:json_schema_builder/json_schema_builder.dart';

ساختن طرحواره داده

سپس طرحواره داده‌ای را که عامل هنگام ایجاد نمایش تکلیف ارائه خواهد کرد تعریف کنید. این فرایند از برخی سازنده‌های جالب از بسته json_schema_builder استفاده می‌کند، اما اساساً شما فقط یک طرح‌واره JSON را تعریف می‌کنید که در پیام‌های ارسالی به و از نماینده استفاده می‌شود.

با S.object پایه که به نام عنصر ارجاع می‌دهد شروع کنید:

final taskDisplaySchema = S.object(
  properties: {
    'component': S.string(enumValues: ['TaskDisplay']),
  },
);

سپس، title،‏ tasks،‏ name،‏ isCompleted، و completeAction را به ویژگی‌های طرح‌واره اضافه کنید.

final taskDisplaySchema = S.object(
  properties: {
    'component': S.string(enumValues: ['TaskDisplay']),
    'title': S.string(description: 'The title of the task list'),
    'tasks': S.list(
      description: 'A list of tasks to be completed today',
      items: S.object(
        properties: {
          'name': S.string(description: 'The name of the task to be completed'),
          'isCompleted': S.boolean(
            description: 'Whether the task is completed',
          ),
          'completeAction': A2uiSchemas.action(
            description:
                'The action performed when the user has completed the task.',
          ),
        },
      ),
    ),
  },
);

به دارایی completeAction نگاهی بیندازید. این با A2uiSchemas.action ایجاد شده است، سازنده برای ویژگی طرح‌واره‌ای که نشان‌دهنده «کنش A2UI» است. با افزودن کنش به طرح‌واره، برنامه درواقع به نماینده می‌گوید: «وقتی تکلیفی به من می‌دهی، نام و فراداده کنشی را هم ارائه کن که بتوانم از آن برای اعلام تکمیل شدن تکلیف به تو استفاده کنم.» بعداً، وقتی کاربر روی چارگوش انتخاب تک‌ضرب می‌زند، برنامه آن کنش را فراخوانی می‌کند.

سپس، فیلدهای required را به طرح‌واره اضافه کنید. این‌ها به عامل دستور می‌دهند که هر بار ویژگی‌های خاصی را پر کند. در این مورد، همه دارایی‌ها الزامی است!

final taskDisplaySchema = S.object(
  properties: {
    'component': S.string(enumValues: ['TaskDisplay']),
    'title': S.string(description: 'The title of the task list'),
    'tasks': S.list(
      description: 'A list of tasks to be completed today',
      items: S.object(
        properties: {
          'name': S.string(description: 'The name of the task to be completed'),
          'isCompleted': S.boolean(
            description: 'Whether the task is completed',
          ),
          'completeAction': A2uiSchemas.action(
            description:
                'The action performed when the user has completed the task.',
          ),
        },
        // New!
        required: ['name', 'isCompleted', 'completeAction'],
      ),
    ),
  },
  // New!
  required: ['title', 'tasks'],
);

ساختن کلاس‌های تجزیه داده

هنگام ایجاد نمونه‌های این مؤلفه، نماینده داده‌های مطابق با طرح‌واره را ارسال خواهد کرد. دو کلاس اضافه کنید تا آن JSON ورودی را به اشیاء Dart با نوع قوی تجزیه کند. توجه کنید که _TaskDisplayData چگونه ساختار ریشه را مدیریت می‌کند، درحالی‌که تجزیه آرایه داخلی را به _TaskData واگذار می‌کند.

class _TaskData {
  final String name;
  final bool isCompleted;
  final String actionName;
  final JsonMap? actionContext;

  _TaskData({
    required this.name,
    required this.isCompleted,
    required this.actionName,
    this.actionContext,
  });

  factory _TaskData.fromJson(Map<String, Object?> json) {
    try {
      final action = json['completeAction']! as JsonMap;
      final event = action['event']! as JsonMap;

      return _TaskData(
        name: json['name'] as String,
        isCompleted: json['isCompleted'] as bool,
        actionName: event['name'] as String,
        actionContext: event['context'] as JsonMap?,
      );
    } catch (e) {
      throw Exception('Invalid JSON for _TaskData: $e');
    }
  }
}

class _TaskDisplayData {
  final String title;
  final List<_TaskData> tasks;

  _TaskDisplayData({required this.title, required this.tasks});

  factory _TaskDisplayData.fromJson(Map<String, Object?> json) {
    try {
      return _TaskDisplayData(
        title: (json['title'] as String?) ?? 'Tasks',
        tasks: (json['tasks'] as List<Object?>)
            .map((e) => _TaskData.fromJson(e as Map<String, Object?>))
            .toList(),
      );
    } catch (e) {
      throw Exception('Invalid JSON for _TaskDisplayData: $e');
    }
  }
}

اگر قبلاً با Flutter کار کرده‌اید، این کلاس‌ها احتمالاً شبیه کلاس‌هایی هستند که خودتان ساخته‌اید. این توابع JsonMap را می‌پذیرند و شیءی با نوع قوی حاوی داده‌های تجزیه‌شده از JSON را برمی‌گردانند.

به فیلدهای actionName و actionContext در _TaskData نگاهی بیندازید. این کنش‌ها از ویژگی completeAction JSON استخراج می‌شوند و حاوی نام کنش و بافت داده آن (ارجاعی به مکان کنش در مدل داده GenUI) هستند. از این‌ها بعداً برای ایجاد UserActionEvent استفاده خواهد شد.

مدل داده یک فروشگاه متمرکز و قابل‌مشاهده برای همه وضعیت‌های پویای واسط کاربر است که توسط کتابخانه genui نگهداری می‌شود. وقتی عامل یک عنصر رابط کاربری از کاتالوگ ایجاد می‌کند، یک شیء داده نیز ایجاد می‌کند که با طرحواره عنصر مطابقت دارد. این شیء داده در مدل داده در کارخواه ذخیره می‌شود تا بتوان از آن برای ساختن ابزاره‌ها استفاده کرد و در پیام‌های بعدی به نماینده به آن ارجاع داد (مثل completeAction که می‌خواهید به ابزاره متصل کنید).

افزودن ابزاره

اکنون، ابزاره‌ای برای نمایش فهرست ایجاد کنید. این تابع باید نمونه‌ای از کلاس _TaskDisplayData و یک فراخوان برگشتی را برای فراخوانی هنگام تکمیل تکلیف بپذیرد.

class _TaskDisplay extends StatelessWidget {
  final _TaskDisplayData data;
  final void Function(_TaskData) onCompleteTask;

  const _TaskDisplay({required this.data, required this.onCompleteTask});

  @override
  Widget build(BuildContext context) {
    return Column(
      crossAxisAlignment: CrossAxisAlignment.start,
      mainAxisSize: MainAxisSize.min,
      children: [
        Padding(
          padding: const EdgeInsets.all(16.0),
          child: Text(
            data.title,
            style: Theme.of(context).textTheme.titleLarge,
          ),
        ),
        ...data.tasks.map(
          (task) => CheckboxListTile(
            title: Text(
              task.name,
              style: TextStyle(
                decoration: task.isCompleted
                    ? TextDecoration.lineThrough
                    : TextDecoration.none,
              ),
            ),
            value: task.isCompleted,
            onChanged: task.isCompleted
                ? null
                : (val) {
                    if (val == true) {
                      onCompleteTask(task);
                    }
                  },
          ),
        ),
      ],
    );
  }
}

ایجاد CatalogItem

با ایجاد طرح‌واره، تجزیه‌کننده، و ابزاره، اکنون می‌توانید CatalogItem ایجاد کنید تا همه آن‌ها را به هم متصل کنید.

در پایین task_display.dart،‏ taskDisplay را به‌عنوان متغیر سطح بالا ایجاد کنید، از _TaskDisplayData برای تجزیه کردن JSON ورودی استفاده کنید، و نمونه‌ای از ابزارک _TaskDisplay بسازید.

final taskDisplay = CatalogItem(
  name: 'TaskDisplay',
  dataSchema: taskDisplaySchema,
  widgetBuilder: (itemContext) {
    final json = itemContext.data as Map<String, Object?>;
    final data = _TaskDisplayData.fromJson(json);

    return _TaskDisplay(
      data: data,
      onCompleteTask: (task) async {
        // We will implement this next!
      },
    );
  },
);

پیاده‌سازی onCompleteTask

برای اینکه ابزاره کار کند، باید وقتی تکلیفی تکمیل می‌شود با عامل ارتباط برقرار کند. جای‌بان خالی onCompleteTask را با کد زیر جایگزین کنید تا رویدادی را بااستفاده از completeAction از داده‌های تکلیف ایجاد و ارسال کنید.

onCompleteTask: (task) async {
  // A data context is a reference to a location in the data model. This line
  // turns that reference into a concrete data object that the agent can use.
  // It's kind of like taking a pointer and replacing it with the value it
  // points to.
  final JsonMap resolvedContext = await resolveContext(
    itemContext.dataContext,
    task.actionContext,
  );

  // Dispatch an event back to the agent, letting it know a task was completed.
  // This will be sent to the agent in an A2UI message that includes the name
  // of the action, the surface ID, and the resolved data context.
  itemContext.dispatchEvent(
    UserActionEvent(
      name: task.actionName,
      sourceComponentId: itemContext.id,
      context: resolvedContext,
    ),
  );
}

ثبت کردن مورد کاتالوگ

در آخر، main.dart را باز کنید، فایل جدید را وارد کنید، و آن را همراه با دیگر عناصر کاتالوگ ثبت کنید.

این واردات را به بالای lib/main.dart اضافه کنید:

import 'task_display.dart';

catalog = BasicCatalogItems.asCatalog(); را در تابع initState() با این مورد جایگزین کنید:

// The Catalog is immutable, so use copyWith to create a new version
// that includes our custom catalog item along with the basics.
catalog = BasicCatalogItems.asCatalog().copyWith(newItems: [taskDisplay]);

موفق شدید. برای دیدن تغییرات، برنامه را بازراه‌اندازی سریع کنید.

‫۸. روش‌های مختلف تعامل با عامل را امتحان کنید

برنامه فهرست تکالیف درحال اجرا در Chrome

اکنون که ابزاره جدید را به «کاتالوگ» اضافه کرده‌اید و فضایی برای آن در واسط کاربر برنامه ایجاد کرده‌اید، وقت آن است که با عامل کار کنید و لذت ببرید. یکی از مزایای اصلی GenUI این است که دو روش برای تعامل با داده‌هایتان ارائه می‌دهد: ازطریق میانای کاربر برنامه مانند دکمه‌ها و چارگوش‌های انتخاب، و ازطریق عاملی که زبان طبیعی را درک می‌کند و می‌تواند درباره داده‌ها استدلال کند. هر دو را امتحان کنید!

  • از فیلد نوشتاری برای توصیف سه یا چهار تکلیف استفاده کنید و ببینید که در فهرست ظاهر می‌شوند.
  • از چارگوش انتخاب برای تغییر وضعیت تکلیف به کامل یا ناقص استفاده کنید.
  • فهرستی از ۵ تا ۶ تکلیف ایجاد کنید، سپس به نماینده بگویید مواردی را که نیاز به رانندگی دارند حذف کند.
  • به کارشناس بگویید فهرست تکراری از کارها را به‌صورت موارد جداگانه ایجاد کند («باید کارت تبریک تعطیلات برای مامان، بابا، و مادربزرگم بخرم. برای آن‌ها تکلیف‌های جداگانه بسازید.»).
  • به عامل بگویید همه تکالیف را به‌عنوان تمام‌شده یا تمام‌نشده علامت‌گذاری کند، یا دو یا سه تکلیف اول را تیک بزند.

‫۹. تبریک می‌گوییم

تبریک! شما بااستفاده از «میانای کاربر زایا» و Flutter یک برنامه ردگیری تکلیف با بهره‌گیری از هوش مصنوعی ساخته‌اید.

آنچه آموخته‌اید

  • تعامل با مدل‌های بنیادی Google بااستفاده از کیت توسعه نرم‌افزار Flutter Firebase
  • پردازش سطوح تعاملی تولیدشده توسط Gemini بااستفاده از GenUI
  • سنجاق کردن سطوح در چیدمان‌ها بااستفاده از شناسه‌های پردازشی ایستا ازپیش تعیین‌شده
  • طراحی طرح‌واره‌های سفارشی و کاتالوگ‌های ابزاره برای حلقه‌های تعامل قوی

اسناد مرجع