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

1. مقدمة

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

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

• يمكنك إنشاء "مهارات الوكيل" الخاصة بك لتنفيذ المهام المفضّلة لديك.
• استخدِم 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: يجب إجراء المصادقة أثناء بدء التشغيل الأوّلي. اختَر 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 مهارة my-favorite-things للإجابة عن سؤالك. إذا طُلب منك ذلك، اسمح لأداة Antigravity CLI باستخدام المهارة.

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

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

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

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?
      • عندما يُطلب منك ذلك، اكتب Y (نعم) واضغط على Enter.Allow Firebase to collect CLI and Emulator Suite usage and error reporting information?
   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 ميزة "مهارات الوكيل" في 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 على حالته التلقائية، يمكنك اتّباع المستندات الرسمية للحصول على تعليمات حول كيفية إجراء ذلك بأمان.