تخطيط التطبيقات وإنشاؤها باستخدام Gemini CLI Conductor

1. مقدمة

في هذا الدرس التطبيقي حول الترميز، ستتعلّم كيفية التخطيط لإنشاء تطبيقات برمجية باستخدام إضافة Gemini CLI Conductor. ستبدأ بإنشاء تطبيق "جديد" من البداية تمامًا. بعد ذلك، ستتعامل معه كمشروع "brownfield"، وتكرّر العمل عليه لإضافة المصادقة والتخزين.

الإجراءات التي ستنفذّها

  • ثبِّت Gemini CLI وإضافة Conductor
  • إنشاء تطبيق ويب "عجلة الاختيار" من البداية باستخدام إمكانات التخطيط والتنفيذ في Conductor
  • إضافة ميزة التخصيص إلى التطبيق من خلال إضافة المصادقة والتخزين باستخدام Firebase

أهداف الدورة التعليمية

  • كيفية استخدام إضافة Conductor لتخطيط تطبيق "جديد" وتنفيذه ومراجعته
  • كيفية استخدام إضافة Conductor لإضافة ميزات إلى تطبيق "brownfield"

المتطلبات

  • متصفّح ويب، مثل Chrome
  • مشروع Google Cloud تم تفعيل الفوترة فيه
  • تثبيت Node.js (يُنصح بالإصدار 18 أو إصدار أحدث)
  • أداة تعديل رموز برمجية على الجهاز، مثل Visual Studio Code

2. قبل البدء

إنشاء مشروع على Google Cloud

  1. في Google Cloud Console، في صفحة اختيار المشروع، اختَر مشروعًا على Google Cloud أو أنشِئ مشروعًا.
  2. تأكَّد من تفعيل الفوترة لمشروعك على السحابة الإلكترونية. كيفية التحقّق مما إذا كانت الفوترة مفعَّلة في مشروع

بدء Cloud Shell

Cloud Shell هي بيئة سطر أوامر تعمل في Google Cloud ومحمّلة مسبقًا بالأدوات اللازمة.

  1. انقر على تفعيل Cloud Shell في أعلى "وحدة تحكّم Google Cloud".
  2. بعد الاتصال بـ Cloud Shell، تحقَّق من مصادقتك باتّباع الخطوات التالية:
    gcloud auth list
  3. تأكَّد من إعداد مشروعك باتّباع الخطوات التالية:
    gcloud config get project
  4. إذا لم يتم ضبط مشروعك على النحو المتوقّع، اضبطه باتّباع الخطوات التالية:
    export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

تفعيل واجهات برمجة التطبيقات

فعِّل Firebase Management API في مشروعك على Google Cloud.

gcloud services enable firebase.googleapis.com

إضافة Firebase إلى مشروعك

تتوفّر واجهة Firebase CLI مثبَّتة مسبقًا في Cloud Shell. من Cloud Shell، سجِّل الدخول باستخدام حساب Google نفسه الذي يمنحك إذن الوصول إلى مشروع على السحابة الإلكترونية. إذا كنت تعمل على جهازك، ثبِّت Firebase CLI باتّباع التعليمات.

firebase login

نفِّذ الأمر التالي لإضافة Firebase إلى مشروعك على Google Cloud:

firebase projects:addfirebase

إذا كانت هذه هي المرة الأولى التي تشغّل فيها واجهة سطر الأوامر firebase، أجب عن أي أسئلة تُطرح عليك.

الخروج من Cloud Shell

يمكنك إغلاق نافذة Cloud Shell. في القسم التالي، سنضبط بيئتك المحلية.

3- تثبيت Gemini CLI وConductor على الجهاز

في هذه الخطوة، ستجهّز بيئة التطوير المحلية من خلال تثبيت Gemini CLI وإضافة Conductor باستخدام أداة تعديل الرموز الطرفية المحلية.

تثبيت Gemini CLI

  1. ثبِّت أحدث إصدار من Gemini CLI على مستوى العالم باستخدام npm:
    npm install -g @google/gemini-cli
  2. أعِد تشغيل نافذة Terminal ليتمّ إضافة gemini إلى PATH.
  3. تأكَّد من أنّ عملية التثبيت قد ثبّتت أحدث إصدار:
    gemini --version
  4. إنشاء دليل مشروع جديد والانتقال إليه: في قسم لاحق، سننشئ مشروعًا في الدليل picker-wheel. أنشئ هذا الدليل الآن وانتقِل إليه:
    mkdir picker-wheel
cd picker-wheel
  5. المصادقة:
    • ابدأ استخدام Gemini CLI.
      gemini
    • عندما يُطرح عليك السؤال "هل تثق في الملفات الموجودة في هذا المجلد؟"، اختَر الوثوق بالمجلد (عجلة الاختيار).
    • عندما يُطلب منك تحديد طريقة المصادقة لهذا المشروع، اختَر Vertex AI. اتّبِع دليل المصادقة للحصول على مفتاح Google Cloud API وضبط متغيّر البيئة GOOGLE_API_KEY. يُرجى تخصيص بعض الوقت لاستكشاف فئات الاستخدام المختلفة وحدود المعدّل المقابلة لها في واجهة برمجة التطبيقات.
  6. الخروج من Gemini CLI: اكتب /quit في نافذة الأوامر على جهازك لإنهاء جلسة Gemini CLI المباشرة قبل المتابعة.

تثبيت إضافة Conductor

Conductor هي إضافة مفتوحة المصدر إلى Gemini CLI من إنشاء Google، وتتيح ميزات التطوير المستند إلى السياق، مثل التخطيط وتتبُّع التنفيذ.

  1. تثبيت الإضافة:
    gemini extensions install https://github.com/gemini-cli-extensions/conductor
  2. التحقّق من عملية التثبيت:
    • ابدأ استخدام Gemini CLI. 
      gemini
    • اكتب /conductor وستظهر لك قائمة بالأوامر مثل setup وnewTrack وimplement وما إلى ذلك.
  3. الخروج من Gemini CLI: اكتب /quit في نافذة الأوامر على جهازك لإنهاء جلسة Gemini CLI المباشرة قبل المتابعة.

4. Greenfield Development: The Picker Wheel

بعد إعداد بيئتك، ستنشئ تطبيقًا جديدًا من البداية. ستنشئ تطبيق ويب بسيطًا باسم "عجلة الاختيار"، وهو تطبيق يدور لاختيار خيار عشوائي.

إعداد سياق المنتج

  1. تأكَّد من أنّك في دليل picker-wheel الذي أنشأته في القسم السابق:
    pwd
  2. بدء Gemini CLI: ابدأ جلسة Gemini CLI جديدة من دليل مشروعك.
    gemini
  3. بدء تهيئة Conductor: نفِّذ أمر الإعداد لإنشاء بنية المشروع وإعداد بيئة Conductor.
    /conductor:setup
  4. اتّباع الطلبات التفاعلية: لن تتطابق الطلبات التفاعلية التي تظهر لك مع هذه الأمثلة تمامًا. ركِّز على تصميم أبسط للتعرّف على سير عمل Conductor.
    • الهدف من المنتج: هو تطبيق ويب يعرض عجلة دوّارة قابلة للضبط لاختيار عنصر عشوائي من قائمة.
      • الجمهور المستهدَف → عامة الجمهور
      • التفاعل → النقر/الضغط للتدوير
      • التخصيص → أساسي
      • النظام الأساسي → سطح المكتب أولاً
    • إرشادات المنتجات: يتم إنشاؤها تلقائيًا.
    • حزمة التكنولوجيا:
      • اللغات → TypeScript/JavaScript: مثالية للويب المتكامل
      • Frontend → Vue.js - Intuitive web interfaces
      • الخادم الخلفي → Express.js - خادم خلفي سريع يعمل على Node
      • قاعدة البيانات → بلا - لا حاجة إلى قاعدة بيانات
    • سير العمل: عادي
    • متطلبات المنتج:
      • قصص المستخدمين → خيارات قابلة للتخصيص، عرض الفائز بوضوح
      • الميزات الرئيسية → قائمة الخيارات القابلة للتعديل، الألوان العشوائية
      • القيود → من جهة العميل فقط، أداء عالٍ
      • غير وظيفي → تغطية عالية للاختبار، وTypeScript وVue.js، وتصميم سريع الاستجابة
    سينشئ Conductor ملفات السياق في الدليل conductor/.

إنشاء مقطع جديد

يمثّل "المسار" في Conductor ميزة أو وحدة عمل.

  1. ابدأ مقطعًا صوتيًا جديدًا باستخدام /conductor:newTrack. قد تقترح أداة Conductor مسارًا أوليًا استنادًا إلى سياق المنتج. بدلاً من ذلك، يمكنك اقتراح أغنية أو طلب من "قائد الأوركسترا" اقتراح أغنية.
  2. مراجعة الخطة التي تم إنشاؤها: ستنشئ أداة Conductor index.md وspec.md وplan.md داخل conductor/tracks/{track-id}/. يُرجى تخصيص بعض الوقت لقراءتها. إذا كان كل شيء يبدو على ما يرام، سيطلب منك Conductor حفظ ملفات الإعداد الأولي وتنفيذها.

تنفيذ المسار

  1. بدء التنفيذ:
    /conductor:implement
    سيعمل Conductor الآن من خلال الخطة، ويكتب الرمز البرمجي للمشروع.
  2. التحقّق من التطبيق: خلال مرحلة التنفيذ، سيطلب منك Conductor اختبار التطبيق يدويًا. على سبيل المثال، سيُطلب منك فتح خادم الويب المحلي، ومعاينة التطبيق في المتصفّح، والتحقّق من التغييرات. عند اكتمال عملية التنفيذ، من المفترض أن ترى عجلة اختيار تعمل بشكل سليم.تطبيق Picker Wheel
  3. مراجعة التنفيذ: كخطوة أخيرة، يمكنك أن تطلب من Conductor مراجعة عملية التنفيذ. يجب أن يراجع الرمز المصدر، ويُزامن وثائق المشروع، ويؤرشف المقطع الصوتي.
    /conductor:review

5- التكرار في Brownfield: إضافة التخصيص

الآن، ستنتقل إلى تطوير "brownfield". ستعمل على تحسين تطبيق الويب "عجلة الاختيار" من القسم السابق ليتمكّن المستخدمون الذين سجّلوا الدخول من حفظ إعدادات "عجلة الاختيار" واستعادتها.

إنشاء مسار تخصيص

  1. في مثال "brownfield" التالي، سنستخدم Firebase للمصادقة والتخزين. ثبِّت إضافة Firebase في Gemini CLI لكي يتمكّن Conductor من استخدامها.
    gemini extensions install https://github.com/gemini-cli-extensions/firebase
  2. بدء Gemini CLI: ابدأ جلسة Gemini CLI جديدة من دليل مشروعك.
    gemini
  3. بدء مقطع جديد: لبدء مقطع جديد
    /conductor:newTrack "I want users to be able to log in to their accounts and
save their picker wheel configurations."
  4. اتّباع الطلبات التفاعلية: لن تتطابق الطلبات التفاعلية التي تظهر لك مع هذه الأمثلة تمامًا. ركِّز على تصميم أبسط للتعرّف على سير عمل Conductor.
    • تتبُّع الهدف:
      • موفّر المصادقة → Firebase Auth
      • الإعدادات المحفوظة → خيارات العجلة
      • تخزين البيانات → Firestore
      • واجهة مستخدم تسجيل الدخول في Firestore → عنصر مركّب على شكل نافذة مشروطة
    ستنشئ Conductor ملفات سياق لمسار جديد داخل conductor/tracks/{track-id}.
  5. مراجعة الخطة التي تم إنشاؤها: خصِّصوا بعض الوقت لقراءة index.md وspec.md وplan.md داخل conductor/tracks/{track-id}/.
  6. التنفيذ: إذا كان كل شيء يبدو على ما يُرام، يمكنك بدء التنفيذ.
    /conductor:implement
  7. التحقّق: أعِد تحميل تطبيقك. من المفترض أن يظهر لك تطبيق محدَّث. &quot;عجلة الاختيار&quot; مع تسجيل الدخول

في ما يلي الرمز الذهبي لتنفيذ مرجعي. يجب تقديم مشروع Firebase الخاص بك في .firebaserc وإعدادات Firebase في firebase.ts لبدء تطبيقك بشكلٍ صحيح.

6. تَنظيم

لتجنُّب الرسوم المستمرة على حسابك على Google Cloud، احذف الموارد التي تم إنشاؤها أثناء هذا الدرس العملي.

حذف مشروع Firebase (ومشروع Google Cloud)

أسهل طريقة لتنظيف المشروع هي حذفه بالكامل.

  1. في Google Cloud Console، اختَر المشروع الذي أنشأته.
  2. انقر على حذف.

بدلاً من ذلك، إذا كنت تريد الاحتفاظ بالمشروع ولكن حذف المراجع، اتّبِع الخطوات التالية:

  1. حذف قاعدة بيانات Firestore: انتقِل إلى وحدة تحكّم Firebase > Firestore واحذف قاعدة البيانات.
  2. حذف المصادقة: انتقِل إلى وحدة تحكّم Firebase > المصادقةطريقة تسجيل الدخول، ثم أوقِف Google.

7. تهانينا

تهانينا! لقد استخدمت إضافة Gemini CLI Conductor بنجاح لإنشاء تطبيق ويب من البداية ثم تكراره باستخدام ميزات معقّدة، مثل المصادقة ودمج قاعدة البيانات.

الخطوات التالية