نحوه استفاده از مهارت‌های عامل هوش مصنوعی (با رابط خط فرمان Antigravity و مهارت‌های عامل برای Firebase)

۱. مقدمه

در این آزمایشگاه، شما یاد خواهید گرفت که چگونه مهارت‌های عامل (Agent Skills) را ایجاد کنید تا به عامل‌های هوش مصنوعی (AI) دسترسی به دانش و گردش‌های کاری سفارشی را ارائه دهید. شما آن را به عنوان یک مهارت محلی ایجاد خواهید کرد که از طریق Antigravity CLI قابل دسترسی است.

کاری که انجام خواهید داد

• مهارت‌های عامل خودتان را برای چیزهای مورد علاقه‌تان ایجاد کنید.
• برای بررسی مهارت خود از Antigravity CLI استفاده کنید.
• مهارت‌های رسمی Agent را برای Firebase نصب کنید و از آنها برای ساخت و استقرار یک برنامه استفاده کنید.

آنچه یاد خواهید گرفت

• چگونه یک مهارت را ساختارمند کنیم.
• نحوه نوشتن فایل SKILL.md .
• نحوه استفاده از مهارت‌های محلی با Antigravity CLI.

۲. راه‌اندازی پروژه

1. اگر از قبل حساب گوگل ندارید، باید یک حساب گوگل ایجاد کنید .
   • به جای حساب کاری یا تحصیلی از یک حساب شخصی استفاده کنید. حساب‌های کاری و تحصیلی ممکن است محدودیت‌هایی داشته باشند که مانع از فعال کردن APIهای مورد نیاز برای این آزمایشگاه توسط شما شود.
2. وارد کنسول ابری گوگل شوید.
3. فعال کردن پرداخت در کنسول ابری
   • تکمیل این آزمایشگاه باید کمتر از ۱ دلار آمریکا از طریق منابع ابری هزینه داشته باشد.
   • شما می‌توانید مراحل انتهای این آزمایش را برای حذف منابع دنبال کنید تا از هزینه‌های بیشتر جلوگیری شود.
   • کاربران جدید واجد شرایط استفاده از دوره آزمایشی رایگان ۳۰۰ دلاری هستند.
4. یک پروژه جدید ایجاد کنید یا از یک پروژه موجود دوباره استفاده کنید.
   • اگر در مورد سهمیه پروژه خطایی مشاهده کردید، از یک پروژه موجود دوباره استفاده کنید یا یک پروژه موجود را حذف کنید تا یک پروژه جدید ایجاد شود.

۳. ویرایشگر Cloud Shell را باز کنید

1. برای دسترسی مستقیم به ویرایشگر Cloud Shell ، روی این لینک کلیک کنید.
2. اگر امروز در هر مرحله‌ای از شما خواسته شد که مجوز دهید، برای ادامه روی تأیید کلیک کنید.
3. اگر ترمینال در پایین صفحه نمایش داده نشد، آن را باز کنید:
   • روی مشاهده کلیک کنید
   • روی ترمینال کلیک کنید
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 اجرا کنید.

۴. مهارت سفارشی خود را ایجاد کنید

مهارت‌های عامل، دایرکتوری‌هایی هستند که حداقل حاوی یک فایل 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 استفاده کنید.

۵. از مهارت خود در Antigravity CLI استفاده کنید

اکنون که با موفقیت یک مهارت ایجاد کرده‌اید، توسط Antigravity CLI قابل شناسایی است زیرا در دایرکتوری .agents/skills قرار دارد.

1. شروع رابط خط فرمان آنتی‌گراویتی:

   agy
   

توجه: رابط خط فرمان Antigravity به صورت پیش‌فرض در Cloud Shell نصب شده است.

1. احراز هویت با Antigravity CLI: در هنگام راه‌اندازی اولیه، احراز هویت لازم است. OAuth را انتخاب کنید (با فشار دادن Enter ).
2. روی لینک کلیک کنید (اگر قابل کلیک نیست، URL را در Cloud Shell هایلایت کنید تا کپی شود، سپس آن را در مرورگر خود جایگذاری کنید)
3. وارد حساب گوگل خود شوید
4. کد را کپی کنید
5. کد را در ترمینال ویرایشگر Cloud Shell قرار دهید
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 CLI خارج شوید.

۶. (اختیاری) ساخت و استقرار یک برنامه در Firebase Hosting

علاوه بر ایجاد مهارت‌های خودتان، می‌توانید مهارت‌های ایجاد شده توسط دیگران را نصب کنید. این نشان دهنده استفاده از مهارت‌های قابل حمل است - ماژول‌های مستقلی از دانش، دستورالعمل‌ها و گردش‌های کاری که می‌توانند به راحتی به اشتراک گذاشته شوند و دوباره استفاده شوند.

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

حالا با استفاده از Agent Skills for Firebase یک برنامه وب "To Do" با احراز هویت کاربر و یک پایگاه داده ایجاد کنید و آن را در Firebase Hosting مستقر کنید.

پروژه خود را تنظیم کنید

1. اگر هنوز در محیط خط فرمان Antigravity هستید، برای خروج عبارت /exit را تایپ کنید.
2. یک دایرکتوری جدید برای پروژه خود ایجاد کنید و به داخل آن بروید:

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

3. با استفاده از حساب گوگل خود وارد فایربیس شوید. از آنجایی که در Cloud Shell هستید، از پرچم --no-localhost استفاده کنید:

   firebase login --no-localhost
   

   1. تعامل با دستورات CLI :
      • وقتی از شما پرسیده شد که Enable Gemini in Firebase features? )، Y (به معنای بله) را تایپ کنید و Enter فشار دهید.
      • وقتی از شما پرسیده شد Allow Firebase to collect CLI and Emulator Suite usage and error reporting information? Y (به معنای بله) را تایپ کنید و Enter را فشار دهید.
   2. در مرورگر مجوز دهید :
      • یک URL در ترمینال مشاهده خواهید کرد. روی لینک کلیک کنید (اگر قابل کلیک نیست، URL را در Cloud Shell هایلایت کنید تا کپی شود، سپس آن را در مرورگر خود جایگذاری کنید) تا صفحه ورود در یک برگه جدید مرورگر باز شود.
      • مرحله ۱ از ۳ (تأیید دستور) : روی بله، من همین الان این دستور را اجرا کردم کلیک کنید.
      • مرحله ۲ از ۳ (تأیید شناسه جلسه) : اطمینان حاصل کنید که شناسه جلسه با آنچه در ترمینال شما نشان داده شده است مطابقت دارد، سپس روی بله، این شناسه جلسه من است کلیک کنید.
      • مرحله ۳ از ۳ (کپی کردن کد) : برای کپی کردن کد مجوز در کلیپ‌بورد خود، روی کپی کلیک کنید.
   3. ورود را تکمیل کنید :
      • به ترمینال Cloud Shell برگردید و کد مجوز را در قسمت ? Enter authorization code: prompt وارد کنید.
      • Enter فشار دهید.
   شما باید یک پیام موفقیت‌آمیز ببینید: ✔ Success! Logged in as .

نکته: هنگام وارد کردن کد مجوز در Cloud Shell، به کادر محاوره‌ای Chrome که از شما مجوزهای کلیپ‌بورد را درخواست می‌کند، توجه کنید و مطمئن شوید که فعال است. می‌توانید از Ctrl+Shift+V (ویندوز) یا CMD+Shift+V (مک) برای وارد کردن کد در ترمینال استفاده کنید.

نصب مهارت‌های عامل برای فایربیس

اکنون که دایرکتوری پروژه خود را ایجاد کرده‌اید، باید Agent Skills for Firebase را درون آن نصب کنید.

شما می‌توانید مهارت‌های عامل (Agent Skills) برای فایربیس (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. API های مورد نیاز پروژه خود را فعال کنید:

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

2. فعال کردن فایربیس در پروژه فعلی گوگل کلود شما:

   firebase projects:addfirebase ${GOOGLE_CLOUD_PROJECT}
   

3. شروع رابط خط فرمان آنتی‌گراویتی:

   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 را فشار دهید. رابط خط فرمان آنتی‌گراویتی باید از مهارت‌های عامل (Agent Skills) برای فایربیس (Firebase) برای ایجاد و استقرار وب‌سایت شما استفاده کند. در صورت نیاز، عامل را در صدور مجوزها راهنمایی کنید.

وقتی کار استقرار تمام شد، باید یک URL برای برنامه وب شما ارائه دهد. برای باز کردن لینک‌ها در ترمینال Cloud Shell Editor از ctrl+click (ویندوز/لینوکس) یا cmd+click (مک) استفاده کنید. به URL برنامه مستقر شده خود مراجعه کنید!

اضافه کردن احراز هویت فایربیس

1. اگر Antigravity CLI از قبل شروع نشده است، آن را اجرا کنید:

   agy
   

   ممکن است Antigravity CLI سوالاتی مانند «آیا به این پوشه اعتماد دارید؟» بپرسد. برای پذیرش پیش‌فرض‌ها، Enter فشار دهید.
2. حالا، از Antigravity CLI بخواهید که ورود به سیستم با گوگل را اضافه کند:

   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 انجام دهید. اگر از CLI بخواهید، می‌تواند اکثر این کارها را انجام دهد، اما اگر نسخه قدیمی‌تری از Firebase CLI روی نمونه Cloud Shell شما نصب شده باشد، ممکن است انجام دستی مراحل (مانند فعال کردن Google OAuth) لازم باشد.

وقتی کار استقرار تمام شد، باید یک URL برای برنامه وب شما ارائه دهد. برای باز کردن لینک‌ها در ترمینال Cloud Shell Editor از ctrl+click (ویندوز/لینوکس) یا cmd+click (مک) استفاده کنید. به URL برنامه مستقر شده خود مراجعه کنید!

برای مشاهده‌ی آخرین تغییرات، ممکن است لازم باشد با استفاده از ctrl+shift+R (ویندوز/لینوکس) یا cmd+shift+R (مک) یک «Refresh سخت» (Hard Refresh) انجام دهید.

اضافه کردن کلود فایر استور

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 فایل‌ها را به‌روزرسانی خواهد کرد. به آن اجازه دهید این کار را انجام دهد.

وقتی کار استقرار تمام شد، باید یک URL برای برنامه وب شما ارائه دهد. برای باز کردن لینک‌ها در ترمینال Cloud Shell Editor از ctrl+click (ویندوز/لینوکس) یا cmd+click (مک) استفاده کنید. به URL برنامه مستقر شده خود مراجعه کنید!

برای مشاهده‌ی آخرین تغییرات، ممکن است لازم باشد با استفاده از ctrl+shift+R (ویندوز/لینوکس) یا cmd+shift+R (مک) یک «Refresh سخت» (Hard Refresh) انجام دهید.

اگر برنامه شما مطابق انتظار عمل نمی‌کند، برای رسیدن به عملکرد مورد انتظار، به کار با 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 خود ببینید، به آزمایش با آزمایشگاه ادامه دهید.

۷. نتیجه‌گیری

تبریک! شما با موفقیت یک مهارت ایجاد کردید و یاد گرفتید که چگونه مهارت‌های اضافی را برای Antigravity CLI نصب کنید.

(اختیاری) تمیز کردن

اگر می‌خواهید فضای ابری خود را پاک کنید، می‌توانید پروژه ابری خود را حذف کنید تا از هزینه‌های اضافی جلوگیری شود.

اگر مایلید، پروژه را حذف کنید:

gcloud projects delete $GOOGLE_CLOUD_PROJECT

همچنین می‌توانید منابع غیرضروری را از دیسک Cloud Shell خود حذف کنید تا فضای بیشتری آزاد شود.

1. پوشه‌ی lab را حذف کنید (این کار هم مهارت و هم برنامه را حذف می‌کند):

   rm -rf ~/agent-skills-lab
   

2. پوشه برنامه "To Do" را حذف کنید (اگر آن را در خارج از آن ایجاد کرده‌اید):

   rm -rf ~/todo-app
   

اگر زمانی نیاز به تنظیم مجدد Cloud Shell خود به حالت پیش‌فرض داشتید، می‌توانید برای دستورالعمل‌های مربوط به نحوه انجام ایمن این کار، مستندات رسمی را دنبال کنید.