كيفية استخدام "مهارات وكيل الذكاء الاصطناعي" (مع Antigravity CLI و"مهارات وكيل الذكاء الاصطناعي" في Firebase)

1. مقدمة

في هذا التمرين العملي، ستتعرّف على كيفية إنشاء مهارات الوكيل لمنح وكلاء الذكاء الاصطناعي إمكانية الوصول إلى المعرفة وسير العمل المخصّصَين. ستنشئها كمهارة محلية يمكن الوصول إليها من Antigravity CLI.

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

• يمكنك إنشاء مهارات الوكيل الخاصة بك لتنفيذ مهامك المفضّلة.
• استخدِم Antigravity CLI للاستعلام عن مهارتك.
• ثبِّت "مهارات وكلاء Firebase" الرسمية واستخدِمها لإنشاء تطبيق ونشره.

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

• كيفية تنظيم مهارة
• كيفية كتابة ملف SKILL.md
• كيفية استخدام المهارات المحلية مع Antigravity CLI

2. إعداد المشروع

1. إذا لم يكن لديك حساب على Google، عليك إنشاء حساب Google.
   • استخدام حساب شخصي بدلاً من حساب تديره المؤسسة التعليمية أو حساب تابع للعمل. قد تتضمّن حسابات العمل والمؤسسات التعليمية قيودًا تمنعك من تفعيل واجهات برمجة التطبيقات اللازمة لهذا الدرس التطبيقي.
2. سجِّل الدخول إلى Google Cloud Console.
3. فعِّل الفوترة في Cloud Console.
   • يجب أن تبلغ تكلفة إكمال هذا الدرس التطبيقي أقل من دولار أمريكي واحد في موارد السحابة الإلكترونية.
   • يمكنك اتّباع الخطوات في نهاية هذا المختبر لحذف الموارد وتجنُّب تحصيل المزيد من الرسوم.
   • يمكن للمستخدمين الجدد الاستفادة من الفترة التجريبية المجانية بقيمة 300 دولار أمريكي.
4. أنشِئ مشروعًا جديدًا أو اختَر إعادة استخدام مشروع حالي.
   • إذا ظهر لك خطأ بشأن حصة المشروع، أعِد استخدام مشروع حالي أو احذف مشروعًا حاليًا لإنشاء مشروع جديد.

3- فتح Cloud Shell Editor

1. انقر على هذا الرابط للانتقال مباشرةً إلى محرّر Cloud Shell
2. إذا طُلب منك منح الإذن في أي وقت اليوم، انقر على تفويض للمتابعة.
3. إذا لم تظهر النافذة الطرفية في أسفل الشاشة، افتحها باتّباع الخطوات التالية:
   • انقر على عرض.
   • انقر على Terminal.
4. في الوحدة الطرفية، اضبط مشروعك باستخدام الأمر التالي:
   • التنسيق:

     gcloud config set project [PROJECT_ID]
     

   • مثال:

     gcloud config set project lab-project-id-example
     

   • إذا تعذّر عليك تذكُّر رقم تعريف مشروعك، اتّبِع الخطوات التالية:
     • يمكنك إدراج جميع أرقام تعريف المشاريع باستخدام:

       gcloud projects list | awk '/PROJECT_ID/{print $2}'
       

     
5. من المفترض أن تظهر لك هذه الرسالة:

   Updated property [core/project].
   

   إذا ظهرت لك WARNING وطُلب منك Do you want to continue (Y/n)?، من المحتمل أنّك أدخلت رقم تعريف المشروع بشكل غير صحيح. اضغط على n، ثم على Enter، وحاوِل تنفيذ الأمر gcloud config set project مرة أخرى.

4. إنشاء مهارة مخصّصة

مهارات الوكيل هي أدلة تحتوي على ملف SKILL.md على الأقل يقدّم تعليمات ومعلومات لوكيل الذكاء الاصطناعي. في هذا القسم، ستنشئ مهارة تعلّم Antigravity CLI عن اهتماماتك المفضّلة.

1. أنشئ دليلاً لهذا الدرس التطبيقي وانتقِل إليه:

   mkdir ~/agent-skills-lab && cd ~/agent-skills-lab
   

2. أنشئ دليلاً لمهارة مشروعك:

   mkdir -p ~/agent-skills-lab/.agents/skills/my-favorite-things
   

3. أنشئ ملف SKILL.md جديدًا لمهارتك وافتحه:

   cloudshell edit ~/agent-skills-lab/.agents/skills/my-favorite-things/SKILL.md
   

   سيفتح الأمر cloudshell edit الملف SKILL.md في المحرِّر أعلى الوحدة الطرفية.
4. أضِف المحتوى التالي إلى ملف SKILL.md:

   ---
   name: my-favorite-things
   description: Provides personal information about my favorite color, food, and programming language. Use this skill when the user asks questions about my personal preferences or favorite things.
   ---
   
   # Knowledge
   
   - **Favorite Color:** Blue
   - **Favorite Food:** Pizza
   - **Favorite Programming Language:** Python
   
   If asked about one of my favorite things, please respond with the information provided above.
   

باستخدام ملف SKILL.md فقط، تكون قد أنشأت مهارتك الأولى. حان الوقت لاستخدام هذه المهارة في Antigravity CLI.

5- استخدام مهارتك من Antigravity CLI

بعد إنشاء مهارة بنجاح، يمكن العثور عليها من خلال Antigravity CLI لأنّها تقع في الدليل .agents/skills.

1. ابدأ Antigravity CLI:

   agy
   

ملاحظة: تأتي أداة Antigravity CLI مثبَّتة مسبقًا في Cloud Shell.

1. المصادقة باستخدام Antigravity CLI: يجب إجراء المصادقة أثناء بدء التشغيل الأولي. اختَر OAuth (بالضغط على Enter).
2. انقر على الرابط (إذا لم يكن قابلاً للنقر، حدِّد عنوان URL في Cloud Shell لنسخه، ثم الصِقه في المتصفّح).
3. تسجيل الدخول إلى حسابك على Google
4. نسخ الشفرة
5. ألصِق الرمز في وحدة Cloud Shell Editor الطرفية
6. اضغط على Enter.
7. اضغط على Enter لقبول بعض الإعدادات التلقائية.
8. أن تدرج Antigravity CLI المهارات المتاحة لها ضمن سياقها

   /skills
   

   من المفترض أن يظهر my-favorite-things في قائمة المهارات المتاحة.
9. اضغط على ESC للخروج من عرض المهارات
10. اطرح على Antigravity CLI سؤالاً عن لونك المفضّل:

    What is my favorite color?
    

    يجب أن تستخدم أداة Antigravity CLI مهارة my-favorite-things للإجابة عن سؤالك. إذا طُلب منك ذلك، امنح Antigravity CLI الإذن باستخدام المهارة.

يجب أن يوضّح الناتج أنّ Antigravity CLI استخدمت مهارتك وأجابت بشيء مثل "أزرق" أو "لوني المفضّل هو الأزرق".

لقد أنجزت المهمة! لقد أنشأت مهارة بنجاح واختبرتها باستخدام Antigravity CLI.

عندما تكون مستعدًا لإنهاء جلستك، اكتب /exit ثم اضغط على Enter للخروج من Antigravity CLI.

6. (اختياري) إنشاء تطبيق ونشره على "استضافة Firebase"

بالإضافة إلى إنشاء مهاراتك الخاصة، يمكنك تثبيت مهارات أنشأها مستخدمون آخرون. يوضّح ذلك استخدام المهارات القابلة للنقل، وهي وحدات مستقلة من المعرفة والتعليمات وأساليب العمل التي يمكن مشاركتها وإعادة استخدامها بسهولة.

تُعدّ "مهارات الوكيل" في Firebase مثالاً رائعًا على هذه الوحدات القابلة للنقل. وهي مصمَّمة لمساعدة مساعدي الذكاء الاصطناعي في فهم أفضل ممارسات Firebase وتنفيذ المهام المعقّدة بدقة أعلى وبتكلفة أقل.

يمكنك الآن استخدام "مهارات الوكيل" في Firebase لإنشاء تطبيق ويب "قائمة المهام"، مع مصادقة المستخدمين وقاعدة بيانات، ونشره على استضافة Firebase.

إعداد مشروعك

1. إذا كنت لا تزال في Antigravity CLI، اكتب /exit للخروج.
2. أنشئ دليلاً جديدًا لمشروعك وانتقِل إليه:

   mkdir ~/todo-app && cd ~/todo-app
   

3. سجِّل الدخول إلى Firebase باستخدام حسابك على Google. استخدِم العلامة --no-localhost لأنّك في Cloud Shell:

   firebase login --no-localhost
   

   1. التفاعل مع طلبات واجهة سطر الأوامر:
      • عندما يُطلب منك ذلك، اكتب Y (نعم) واضغط على Enter.Enable Gemini in Firebase features?
      • عندما يُطلب منك ذلك Allow Firebase to collect CLI and Emulator Suite usage and error reporting information?، اكتب Y (نعم) واضغط على Enter.
   2. التفويض في المتصفّح:
      • سيظهر لك عنوان URL في نافذة الوحدة الطرفية. انقر على الرابط (إذا لم يكن قابلاً للنقر، حدِّد عنوان URL في Cloud Shell لنسخه، ثم الصقه في المتصفّح) لفتح صفحة تسجيل الدخول في علامة تبويب متصفّح جديدة.
      • الخطوة 1 من 3 (تأكيد الأمر): انقر على نعم، نفّذتُ هذا الأمر للتو.
      • الخطوة 2 من 3 (تأكيد معرّف الجلسة): تأكَّد من أنّ معرّف الجلسة يتطابق مع ما يظهر في جهازك، ثم انقر على نعم، هذا هو معرّف الجلسة.
      • الخطوة 3 من 3 (نسخ الرمز): انقر على نسخ لنسخ رمز التفويض إلى الحافظة.
   3. إكمال عملية تسجيل الدخول:
      • ارجع إلى نافذة Cloud Shell الطرفية والصِق رمز التفويض عند ظهور الطلب ? Enter authorization code:.
      • اضغط على المفتاح Enter.
   من المفترض أن تظهر لك رسالة نجاح: ✔ Success! Logged in as .

ملاحظة: عند لصق رمز التفويض في Cloud Shell، ابحث عن مربّع حوار في Chrome يطلب أذونات الحافظة وتأكَّد من تفعيلها. يمكنك استخدام Ctrl+Shift+V (في Windows) أو CMD+Shift+V (في Mac) للصق الرمز في المحطة الطرفية.

تثبيت "مهارات وكلاء Firebase"

بعد إنشاء دليل المشروع، عليك تثبيت "مهارات الوكيل" في Firebase ضِمنه.

يمكنك تثبيت "مهارات الوكيل" في Firebase باستخدام skills CLI في نافذة الأوامر:

npx skills add firebase/agent-skills

أثناء عملية التثبيت، سيُطلب منك اختيار المهارات التي تريد تثبيتها. استخدِم مفاتيح الأسهم للتنقّل في القائمة ومفتاح المسافة لاختيار هذه المهارات.

• firebase-auth-basics
• firebase-basics
• firebase-firestore
• firebase-hosting-basics
• firebase-security-rules-auditor

بالنسبة إلى الطلبات اللاحقة، يمكنك قبول الإعدادات التلقائية بأمان من خلال الضغط على Enter.

سيؤدي هذا الأمر إلى تنزيل المهارات وتثبيتها، بما في ذلك firebase-basics وfirebase-hosting-basics، ما يتيح استخدامها في Antigravity CLI إلى جانب مهارة my-favorite-things.

لمزيد من المعلومات حول مهارات الوكلاء في Firebase، اطّلِع على المهارات المتاحة.

إنشاء تطبيق ويب أساسي ونشره

1. فعِّل واجهات برمجة التطبيقات المطلوبة لمشروعك:

   gcloud services enable \
     cloudresourcemanager.googleapis.com \
     firebase.googleapis.com
   

2. فعِّل Firebase في مشروع Google Cloud الحالي باتّباع الخطوات التالية:

   firebase projects:addfirebase ${GOOGLE_CLOUD_PROJECT}
   

3. ابدأ Antigravity CLI:

   agy
   

4. اطلب من Antigravity CLI إنشاء index.html أساسي:

   Generate an index.html file with the content "Hello Firebase Hosting" and
   deploy the application to Firebase Hosting using the current Google Cloud
   Project.
   

   سيطلب Antigravity CLI الحصول على أذونات أثناء إنشاء التطبيق ونشره. اضغط على Enter للسماح بذلك. قد تحتاج إلى كتابة "approve" والضغط على Enter.يجب أن تستخدم Antigravity CLI ميزة "مهارات الوكيل" في Firebase لإنشاء موقعك الإلكتروني ونشره. توجيه الوكيل مع الحصول على الموافقات حسب الحاجة

بعد اكتمال عملية النشر، من المفترض أن يوفّر عنوان URL لتطبيق الويب. استخدِم ctrl+click (في نظام التشغيل Windows أو Linux) أو cmd+click (في نظام التشغيل Mac) لفتح الروابط في نافذة Cloud Shell Editor. انتقِل إلى عنوان URL الخاص بتطبيقك الذي تم نشره.

إضافة خدمة "مصادقة Firebase"

1. ابدأ Antigravity CLI إذا لم يكن قد بدأ بعد:

   agy
   

   قد يطرح Antigravity CLI أسئلة مثل "هل تثق بهذا المجلد؟" اضغط على Enter لقبول الإعدادات التلقائية.
2. الآن، اطلب من Antigravity CLI إضافة ميزة "تسجيل الدخول باستخدام حساب Google":

   Generate HTML, CSS, and Javascript for a single page application.
   It should use Google Sign-in with Firebase Authentication.
   A user should be able to sign in with their Google Account.
   Deploy when you are done and give the URL to me.
   

   قد تطلب Antigravity CLI إنشاء ملفات أو تعديلها، مثل index.html وstyle.css وscript.js. يجب السماح بذلك، فقد يطلب منك Antigravity CLI اتّخاذ بعض الإجراءات في وحدة تحكّم Firebase. يمكن لواجهة سطر الأوامر تنفيذ معظم هذه الخطوات إذا طلبت منها ذلك، ولكن قد يكون من الضروري إكمال الخطوات يدويًا (مثل تفعيل Google OAuth) إذا كان إصدار Firebase CLI المثبَّت على مثيل Cloud Shell قديمًا.

بعد اكتمال عملية النشر، من المفترض أن يوفّر عنوان URL لتطبيق الويب. استخدِم ctrl+click (في نظام التشغيل Windows أو Linux) أو cmd+click (في نظام التشغيل Mac) لفتح الروابط في نافذة Cloud Shell Editor. انتقِل إلى عنوان URL الخاص بتطبيقك الذي تم نشره.

لكي تظهر لك آخر التغييرات، قد تحتاج إلى إجراء "إعادة تحميل إجباري" باستخدام ctrl+shift+R (في نظام التشغيل Windows أو Linux) أو cmd+shift+R (في نظام التشغيل Mac).

إضافة Cloud Firestore

1. ابدأ Antigravity CLI إذا لم يكن قد بدأ بعد:

   agy
   

   قد يطرح Antigravity CLI أسئلة مثل "هل تثق بهذا المجلد؟" اضغط على Enter لقبول الإعدادات التلقائية.
2. اطلب من Antigravity CLI إضافة Firestore لحفظ المهام:

   Update the application to save tasks in Cloud Firestore for the signed-in user.
   A user should be able to add new tasks and see a list of their tasks.
   Deploy when you are done and give the URL to to me.
   

   سيعدّل Antigravity CLI الملفات. اسمح له بذلك.

بعد اكتمال عملية النشر، من المفترض أن يوفّر عنوان URL لتطبيق الويب. استخدِم ctrl+click (في نظام التشغيل Windows أو Linux) أو cmd+click (في نظام التشغيل Mac) لفتح الروابط في نافذة Cloud Shell Editor. انتقِل إلى عنوان URL الخاص بتطبيقك الذي تم نشره.

لكي تظهر لك آخر التغييرات، قد تحتاج إلى إجراء "إعادة تحميل إجباري" باستخدام ctrl+shift+R (في نظام التشغيل Windows أو Linux) أو cmd+shift+R (في نظام التشغيل Mac).

إذا لم يعمل تطبيقك على النحو المتوقّع، تواصَل مع فريق Antigravity CLI للحصول على الوظائف التي تتوقّعها. مثلاً: shell Hide the task form when the user is logged out. Update the security rules so the user can see their TODOs.

ننصحك بمواصلة تجربة المختبر لإضافة الميزات التي تريدها في تطبيق Firebase الجديد.

7. الخاتمة

تهانينا! لقد أنشأت مهارة بنجاح وتعلّمت كيفية تثبيت مهارات إضافية في Antigravity CLI.

(اختياري) التنظيف

إذا أردت تنظيف حسابك، يمكنك حذف مشروعك على السحابة الإلكترونية لتجنُّب تحمّل رسوم إضافية.

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

gcloud projects delete $GOOGLE_CLOUD_PROJECT

يمكنك أيضًا حذف الموارد غير الضرورية من قرص Cloud Shell لإخلاء بعض المساحة.

1. احذف دليل المختبر (سيؤدي ذلك إلى إزالة كل من المهارة والتطبيق):

   rm -rf ~/agent-skills-lab
   

2. احذف دليل تطبيق "قائمة المهام" (إذا أنشأته خارج هذا الدليل):

   rm -rf ~/todo-app
   

إذا احتجت في أي وقت إلى إعادة ضبط Cloud Shell إلى حالته التلقائية، يمكنك اتّباع المستندات الرسمية للحصول على تعليمات حول كيفية إجراء ذلك بأمان.