التخطيط لإنشاء التطبيقات باستخدام Conductor Plugin

1- مقدمة

في هذا الدرس التطبيقي حول الترميز، ستتعرّفون على كيفية التخطيط لتطبيقات البرامج وإنشائها باستخدام الـ مكوّن الإضافي Conductor. ‫Conductor هو مكوّن إضافي مفتوح المصدر أنشأته Google، ويتيح ميزات التطوير المستند إلى المواصفات، مثل التخطيط وتتبُّع التنفيذ. ستبدأون بإنشاء تطبيق جديد تمامًا. بعد ذلك، ستتعاملون معه على أنّه مشروع حالي، وتكرّرون العمل عليه لإضافة المصادقة والتخزين.

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

• تثبيت المكوّن الإضافي Conductor في Antigravity CLI أو Claude Code
• إنشاء تطبيق ويب "Picker Wheel" من البداية باستخدام إمكانات التخطيط والتنفيذ في Conductor
• إضافة ميزة التخصيص إلى التطبيق من خلال إضافة المصادقة والتخزين باستخدام Firebase

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

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

المتطلبات

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

2. قبل البدء

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

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

بدء Cloud Shell

يتيح لنا استخدام Cloud Shell إكمال هذا القسم بدون الحاجة إلى تثبيت أداتَي سطر الأوامر gcloud وfirebase محليًا.

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

1. انقر على تفعيل Cloud Shell في أعلى Google Cloud Console.
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 نفسه الذي يمنحك إمكانية الوصول إلى مشروع Google Cloud. إذا كنت تعمل محليًا، ثبِّت Firebase CLI باتّباع الـ تعليمات.

firebase login

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

firebase projects:addfirebase

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

الخروج من Cloud Shell

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

3. تثبيت وكلاء الترميز في سطر الأوامر والمصادقة عليهم

في هذه الخطوة، ستعدّون بيئة التطوير المحلية من خلال تثبيت Antigravity CLI أو Claude Code والمصادقة عليهما في محرّر الرموز البرمجية المحلي باستخدام بيانات اعتماد Google Cloud.

تثبيت Antigravity CLI والمصادقة عليه

1. ثبِّتوا أحدث إصدار من Antigravity CLI.

   # MacOS and Linux
   curl -fsSL https://antigravity.google/cli/install.sh | bash
   
   # Windows Powershell
   irm https://antigravity.google/cli/install.ps1 | iex
   
   # Windows CMD
   curl -fsSL https://antigravity.google/cli/install.cmd -o install.cmd && install.cmd && del install.cmd
   

2. أعيدوا تشغيل نافذة الأوامر ليتم إضافة agy إلى PATH.
3. تأكَّدوا من أنّ عملية التثبيت قد ثبّتت أحدث إصدار.

   agy --version
   

4. صادِقوا باستخدام بيانات اعتماد Google Cloud.
   • ابدأوا Antigravity CLI.

     agy
     

   • عندما يُطلب منكم اختيار طريقة تسجيل الدخول ، اختاروا استخدام مشروع على Google Cloud. افتحوا عنوان URL الآمن للتفويض في متصفّح ويب. سجِّلوا الدخول باستخدام بيانات الاعتماد الموافق عليها وأكملوا عملية المصادقة. يعرض المتصفّح رمز تفويض أبجديًا رقميًا فريدًا. انسخوا هذا الرمز، وعودوا إلى نافذة الأوامر، والصقوه في الطلب.

   يمكنكم أيضًا اختيار طرق تسجيل دخول أخرى. يهدف هذا الدرس التطبيقي حول الترميز إلى توضيح كيفية العمل مع مشروع على Google Cloud.

5. اخرجوا من Antigravity CLI.اكتبوا /exit من نافذة الأوامر لإنهاء جلسة Antigravity CLI المباشرة قبل المتابعة.

تثبيت Claude Code والمصادقة عليه

بدلاً من ذلك، يمكنكم استخدام المكوّن الإضافي Conductor مع Claude Code. سنثبّت Claude Code ونصادق عليه هنا باستخدام بيانات اعتماد Google Cloud.

1. ثبِّتوا أحدث إصدار من Claude Code.
2. صادِقوا باستخدام بيانات اعتماد Google Cloud.
   • ابدأوا Claude Code.

     claude
     

   • اكتبوا /login لاختيار طريقة تسجيل الدخول. اختاروا الخيار منصة تابعة لجهة خارجية · Amazon Bedrock أو Microsoft Foundry أو Vertex AI وGoogle Vertex AI. لإعداد Google Vertex AI، اختاروا بيانات الاعتماد التلقائية للتطبيق (google auth)، وأكملوا الإعداد حسب التعليمات.

   يمكنكم أيضًا اختيار طرق تسجيل دخول أخرى. يهدف هذا الدرس التطبيقي حول الترميز إلى توضيح كيفية العمل مع مشروع على Google Cloud.

3. أعيدوا تشغيل Claude Code.

4. تثبيت المكوّن الإضافي Conductor

‫Conductor هو مكوّن إضافي مفتوح المصدر أنشأته Google، ويتيح ميزات التطوير المستند إلى المواصفات، مثل التخطيط وتتبُّع التنفيذ.

التثبيت في Antigravity CLI

1. ثبِّتوا المكوّن الإضافي:
   • Antigravity CLI

     agy plugins install https://github.com/gemini-cli-extensions/conductor
     

2. تأكَّدوا من أنّ عملية التثبيت قد ثبّتت أحدث إصدار:
   • ابدأوا Antigravity CLI.

     agy
     

   • اكتبوا /conductor وستظهر لكم قائمة بالأوامر، مثل /conductor:conductor-setup و/conductor:conductor-new-track وconductor:conductor-implement وما إلى ذلك.
3. اخرجوا من سطر الأوامر.اكتبوا /exit من نافذة الأوامر لإنهاء جلسة سطر الأوامر المباشرة قبل المتابعة.

التثبيت في Claude Code

1. سجِّلوا مستودع Marketplace وثبِّتوا المكوّن الإضافي Conductor مباشرةً في جلسة Claude Code.

   /plugin marketplace add gemini-cli-extensions/conductor
   /plugin install conductor
   /reload-plugin
   

2. تأكَّدوا من أنّ عملية التثبيت قد ثبّتت أحدث إصدار.
   • اكتبوا /conductor وستظهر لكم قائمة بالأوامر، مثل /conductor-setup وconductor-new-track وconductor-implement وما إلى ذلك.
3. اخرجوا من سطر الأوامر.اكتبوا /exit من نافذة أوامر Claude Code لإنهاء جلسة سطر الأوامر المباشرة قبل المتابعة.

5. التطوير الجديد: Picker Wheel

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

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

1. أنشئوا دليل مشروع جديدًا وانتقلوا إليه.سنعمل الآن على مشروع في دليل picker-wheel. أنشئوا هذا الدليل وانتقلوا إليه.

   mkdir picker-wheel
   cd picker-wheel
   

2. ابدأوا Antigravity CLI.ابدأوا جلسة سطر أوامر جديدة من دليل مشروعكم باستخدام Antigravity CLI أو Claude Code.

   # Antigravity CLI
   agy
   
   # Claude Code
   claude
   

   • عندما يُطلب منكم "هل تثقون بالملفات في هذا المجلد؟"، اختاروا المجلد الموثوق به (picker-wheel)
3. ابدأوا Conductor.نفِّذوا أمر الإعداد لإنشاء بنية المشروع وإعداد بيئة Conductor.

   # Antigravity CLI
   /conductor:conductor-setup
   
   # Claude Code
   /conductor-setup
   

4. اتّبِعوا التعليمات التفاعلية.لن تتطابق التعليمات التفاعلية التي تظهر لكم مع هذه الأمثلة تمامًا. ركِّزوا على تصميم أبسط للتعرّف على سير عمل Conductor.
   • هدف المنتج: تطبيق ويب يعرض عجلة دوارة قابلة للضبط لاختيار عنصر عشوائي من قائمة.
     • الجمهور المستهدف ← عامة الجمهور
     • التفاعل ← النقر/الضغط للتدوير
     • التخصيص ← أساسي
     • النظام الأساسي ← سطح المكتب أولاً
   • الإرشادات المتعلقة بالمنتجات: يتم إنشاؤها تلقائيًا.
   • حزمة التكنولوجيا:
     • اللغات ← TypeScript/JavaScript - مثالية للويب الكامل
     • الواجهة الأمامية ← Vue.js - واجهات ويب بسيطة
     • الواجهة الخلفية ← Express.js - واجهة خلفية سريعة لـ Node
     • قاعدة البيانات ← لا شيء - لا حاجة إلى قاعدة بيانات
   • سير العمل: عادي.
   • المتطلبات المتعلقة بالمنتجات:
     • قصص المستخدمين ← خيارات قابلة للتخصيص، عرض واضح للفائز
     • الميزات الرئيسية ← قائمة خيارات قابلة للتعديل، ألوان عشوائية
     • القيود ← من جهة العميل فقط، أداء عالٍ
     • غير وظيفية ← تغطية عالية للاختبار، TypeScript وVue.js، تصميم سريع الاستجابة
   سينشئ Conductor ملفات السياق في دليل conductor/.

إنشاء مسار جديد

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

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

تنفيذ المسار

1. ابدأوا التنفيذ.

   # Antigravity CLI
   /conductor:conductor-implement
   
   # Claude Code
   /conductor-implement
   

   سيعمل Conductor الآن على الخطة، ويكتب الرموز البرمجية للمشروع.

   ملاحظة: لتجنُّب مواجهة مشاكل في واجهات الأوامر التفاعلية أو العمليات الطويلة (مثل خوادم التطوير أو أدوات مراقبة الاختبار)، علينا التأكّد من أنّ Conductor يعرف كيفية التعامل مع هذه الأوامر المحدّدة. غالبًا ما تعمل أدوات مثل Vite (npm run dev) وVitest (npm run test) في "وضع المراقبة" تلقائيًا، ما يحافظ على بقاء العملية مفتوحة إلى أجل غير مسمّى. يمكنكم توجيه Conductor لإيقاف وضع المراقبة أو استخدام is_background: true عند تنفيذ الأوامر من خلال تعديل workflow.md.

2. تحقَّقوا من التطبيق.خلال مرحلة التنفيذ، سيطلب منكم Conductor اختبار التطبيق يدويًا. على سبيل المثال، سيطلب منكم فتح خادم الويب المحلي ومعاينة التطبيق في المتصفّح والتحقّق من التغييرات. عند اكتمال التنفيذ، من المفترض أن تظهر لكم عجلة دوارة عملية.

   تحديد المشاكل وحلّها: إذا كانت الرموز البرمجية التي تم إنشاؤها تتصرف بشكل غير متوقّع، تحقَّقوا من conductor/tracks/.../plan.md بحثًا عن أي خطوات تم تخطّيها أو أخطاء.

3. راجِعوا التنفيذ.كخطوة أخيرة، يمكنكم الطلب من Conductor مراجعة التنفيذ. من المفترض أن يراجع Conductor الرموز البرمجية المصدر، ويُزامِن مستندات المشروع، ويؤرشف المسار.

   # Antigravity CLI
   /conductor:conductor-review
   
   # Claude Code
   /conductor-review
   

6. التكرار في مشروع حالي: إضافة ميزة التخصيص

ستنتقلون الآن إلى تطوير مشروع حالي. ستحسّنون تطبيق الويب Picker Wheel من القسم السابق ليتمكّن المستخدمون الذين سجّلوا الدخول من حفظ إعدادات Picker Wheel واستعادتها.

إذا كنتم تريدون الانتقال مباشرةً إلى تطبيق حالي، يمكنكم تنزيل الرمز الذهبي من القسم الأخير للحصول على نموذج تنفيذ ومواصلة الإنشاء استنادًا إليه.

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

1. في مثال "المشروع الحالي" التالي، سنستخدم Firebase للمصادقة والتخزين. ثبِّتوا مهارات Firebase ليتمكّن Conductor من استخدامها.
2. ابدأوا وكيل سطر الأوامر.ابدأوا جلسة سطر أوامر جديدة.

   # Antigravity CLI
   /new
   
   # Claude Code
   /new
   

3. ابدأوا مسارًا جديدًا.ابدأوا مسارًا جديدًا.

   # Antigravity CLI
   /conductor:conductor-new-track "I want users to be able to log in to their
   accounts and save their picker wheel configurations."
   
   # Claude Code
   /conductor-new-track "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. نفِّذوا.إذا كان كل شيء يبدو على ما يُرام، يمكنكم بدء التنفيذ.

   # Antigravity CLI
   /conductor:conductor-implement
   
   # Claude Code
   /conductor-implement
   

7. تحقَّقوا.أعيدوا تحميل تطبيقكم. من المفترض أن يظهر لكم تطبيق محدّث.

   في حال واجه الذكاء الاصطناعي مشكلة في اختبار تنفيذ المصادقة، تذكّروا تفعيل تسجيل الدخول باستخدام حساب Google في وحدة تحكُّم Firebase ضمن المصادقة > طريقة تسجيل الدخول.

   

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

7. تَنظيم

لتجنُّب فرض رسوم مستمرة على حسابكم على Google Cloud، احذفوا الموارد التي تم إنشاؤها خلال هذا الدرس التطبيقي حول الترميز.

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

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

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

بدلاً من ذلك، إذا كنتم تريدون الاحتفاظ بالمشروع ولكن حذف الموارد:

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

8. تهانينا

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

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

• استكشاف مستندات المكوّنات الإضافية في Antigravity CLI
• استكشاف مستندات المكوّنات الإضافية في Claude Code