اسکریپت برنامه‌ها: Vibe-code یک افزونه جیمیل با Gemini CLI و سرورهای MCP

۱. مرور کلی

این آزمایشگاه شما را در یک گردش کار مدرن و مبتنی بر هوش مصنوعی راهنمایی می‌کند تا یک افزونه پویا برای جیمیل از پایه بسازید. شما از رابط خط فرمان Gemini برای هماهنگ کردن یک محیط توسعه محلی قدرتمند استفاده خواهید کرد و از سرورهای MCP (پروتکل زمینه مدل) و افزونه‌های Gemini CLI برای ادغام ابزارهایی مانند gcloud و clasp بهره خواهید برد.

افزونه‌ای که ایجاد می‌کنید، با فراخوانی یک مدل تصویر در پلتفرم هوش مصنوعی Vertex گوگل کلود، یک تصویر گربه منحصر به فرد را بر اساس تقاضا تولید و نمایش می‌دهد.

در پایان، شما یک افزونه‌ی جیمیل کاملاً کاربردی خواهید داشت که API هوش مصنوعی Vertex را فراخوانی می‌کند تا تصاویر منحصر به فردی را مستقیماً در رابط جیمیل تولید کند، که همگی از طریق خط فرمان محلی شما مدیریت می‌شوند.

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

با تکمیل این آزمایشگاه، شما یاد خواهید گرفت که چگونه:

  • راه‌اندازی و استفاده از رابط خط فرمان Gemini به همراه افزونه‌ها
  • یک افزونه جیمیل بسازید که یک API خارجی را فراخوانی کند
  • افزونه را طوری تغییر دهید که API هوش مصنوعی Vertex را برای تولید تصاویر فراخوانی کند.
  • یک نسخه آزمایشی از افزونه Google Workspace را از رابط کاربری Apps Script مستقر کنید

۳. تنظیمات و الزامات

قبل از شروع آزمایشگاه

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

الزامات آزمایشگاه

برای اینکه بتوانید از این آزمایشگاه نهایت استفاده را ببرید، به موارد زیر نیاز دارید:

  • مرورگر وب: یک مرورگر وب استاندارد مانند کروم (توصیه می‌شود).
  • زمان اختصاصی: زمان کافی را برای تمرکز روی فعالیت‌های آزمایشگاهی اختصاص دهید.

۴. محیط ابری گوگل خود را تنظیم کنید

  1. روی نماد فعال کردن پوسته ابری کلیک کنید 7a0d8a88ebea95af.png : در گوشه سمت راست بالای سربرگ کنسول، روی آیکون ترمینالی که وقتی نشانگر ماوس را روی آن نگه می‌دارید، نوشته شده «Activate Cloud Shell» کلیک کنید.
  2. مجاز کردن .
  3. منتظر مقداردهی اولیه باشید: یک جلسه Cloud Shell در یک قاب جدید در پایین پنجره کنسول شما باز خواهد شد. مقداردهی اولیه جلسه چند لحظه طول می‌کشد زیرا یک ماشین مجازی (VM) موقت مبتنی بر دبیان برای شما فراهم می‌کند.
  4. پس از راه‌اندازی اولیه‌ی جلسه، یک اعلان خط فرمان ( user@cloudshell:~ $ ) مشاهده خواهید کرد.
  5. شما می‌توانید با کلیک بر روی دکمه‌ی expand، پنجره‌ی Cloud Shell خود را گسترش دهید تا اندازه‌ی پنجره بزرگتر شود.
  6. پروژه خود را تأیید کنید: دستور زیر را اجرا کنید: 
gcloud config list project
  1. پروژه خود را تغییر دهید (در صورت نیاز): 
gcloud config set project [YOUR_PROJECT_ID]

شما آماده‌اید تا فعالیت‌های آزمایشگاهی را شروع کنید!

۵. محیط توسعه محلی خود را پیکربندی کنید

در این تمرین، شما رابط خط فرمان Gemini و افزونه‌های آن را برای مدیریت پروژه‌های ابری و اسکریپت برنامه‌ها از طریق ترمینال خود راه‌اندازی خواهید کرد.

  1. رابط خط فرمان Gemini از قبل به عنوان بخشی از محیط Cloud Shell نصب شده است، بنابراین نیازی به نصب آن نیست.
  2. clasp نیز به عنوان بخشی از محیط Cloud Shell از قبل نصب شده است، با این حال، ما مطمئن خواهیم شد که در این آزمایشگاه از آخرین نسخه استفاده می‌کنیم. 
npm install -g @google/clasp@latest
  1. با وارد کردن دستور زیر و دنبال کردن دستورالعمل‌های زیر، به clasp اجازه دسترسی به حساب کاربری خود را بدهید: 
clasp login --no-localhost

برای تأیید clasp روی URL تولید شده در ترمینال کلیک کنید. از حساب کاربری آزمایشگاه دانشجویی برای ورود استفاده کنید و وقتی از شما مجوز خواسته شد، گزینه «انتخاب همه» را انتخاب کرده و روی «ادامه» کلیک کنید. سپس باید پیام خطایی مانند تصویر زیر مشاهده کنید.

db77651c2ce19d7f.png

آدرس اینترنتی (URL) را از پنجره مرورگر خود (که با http://localhost:8888/?code=xxx شروع می‌شود) کپی کنید و آن را در جلسه Cloud Shell باز خود جای‌گذاری کنید و Enter را بزنید. clasp جریان مجوز را ادامه می‌دهد و اگر ورود شما موفقیت‌آمیز باشد، تأییدیه‌ای مشابه « You are logged in as user@gmail.com خواهید دید.

  1. افزونه‌های CLI مربوط به قلاب Gemini را نصب کنید. 
gemini extensions install https://github.com/google/clasp --consent
  1. افزونه‌های خط فرمان (CLI) مربوط به gcloud Gemini را نصب کنید. 
gemini extensions install https://github.com/gemini-cli-extensions/gcloud --consent
  1. افزونه‌های Gemini CLI توسعه‌دهنده‌ی Google Workspace را نصب کنید. 
gemini extensions install https://github.com/googleworkspace/developer-tools --consent
  1. یک دایرکتوری پروژه خالی ایجاد کنید: 
mkdir genai-cat-add-on
  1. به دایرکتوری پروژه تازه ایجاد شده خود بروید: 
cd genai-cat-add-on
  1. فایل زمینه Gemini CLI را برای این پروژه پیکربندی کنید: 
cat << 'END_OF_FILE' > GEMINI.md
## **Gemini CLI Instructions for Gmail Add-on Development**

You are a methodical **Google Workspace extensibility and integration expert**. Your goal is to build a Gmail Add-on for the `genai-cat-add-on` project by writing Apps Script code and using command-line tools.

---

## **Tools Available**

*   **`clasp`**: Use this tool for all Apps Script project operations like pushing files.
*   **`gcloud`**: Use this tool for Google Cloud operations, such as enabling APIs or managing IAM permissions.
*   **`workspace-developer`**: Use this tool to search the official Google Workspace documentation for correct syntax, manifest properties, and required OAuth scopes.

---

## **Development Workflow and Validation**

You MUST follow the workflow below when building the add-on:

1.  **Mandatory Documentation Check**: Before creating, committing, or modifying any code (especially manifest files or Apps Script functions), you **MUST** first utilize the **`workspace-developer` tool** and use **search_workspace_docs** to search and validate the necessary Apps Script syntax, OAuth scopes, Apps Script services such as GmailApp, and best practices. Always refer to the official Google Workspace developer documentation via this tool for authoritative information.
2.  **Security and Scopes**: For every code commit or structural change, you must first **verify the manifest file (`appsscript.json`) includes the necessary OAuth scopes** for Gmail access and external API calls, ensuring you use the **minimal required scopes** and nothing more to adhere to the principle of least privilege.
3.  **Versioning/Persistence**: After any successful file creation, update, or deletion, you must ensure the changes are persistently saved and pushed using the appropriate `clasp` tool command.
4.  **Error Handling**: Include appropriate debugging and robust error handling code in all Apps Script functions.

---

## **Project and API Specifications**

* **Project Focus:** All work is centered on the **`genai-cat-add-on`** Apps Script project.
* **Vertex AI Details:** If asked to generate images, you must use the **`gemini-2.5-flash-image`** model on **Vertex AI**. Do NOT use imagen. All Vertex AI operations must use the currently logged-in user's credentials and the current Google Cloud project.
END_OF_FILE
  1. API اسکریپت گوگل اپس را در حساب آزمایشگاه دانشجویی خود فعال کنید، و روی API اسکریپت گوگل اپس کلیک کنید و آن را از خاموش به روشن تغییر دهید.

41eb25a89e13e1ff.gif

۶. راه‌اندازی و تأیید تنظیمات رابط خط فرمان Gemini

  1. Gemini را در دایرکتوری پروژه خود اجرا کنید. 
gemini
  1. به طور پیش‌فرض، رابط خط فرمان Gemini از شما می‌خواهد که تغییرات فایل‌ها را بررسی و بپذیرید. برای این آزمایش، توصیه می‌کنیم با فشار دادن Shift + Tab این گزینه را غیرفعال کنید تا ویرایش‌ها به طور خودکار پذیرفته شوند و به شما در اتمام به موقع آزمایش کمک کند. اکنون صفحه نمایش شما باید این گزینه را با رنگ قرمز برجسته کرده باشد.

31a7326896719d73.png

  1. بررسی کنید که فایل GEMINI.md بارگذاری شده است و نشان دهید که چه چیزی در چارچوب رابط خط فرمان Gemini بارگذاری شده است: 
/memory show
  1. بررسی کنید که سرورهای MCP به درستی پیکربندی شده باشند. ممکن است راه‌اندازی اولیه سرور gcloud MCP کمی طول بکشد، بنابراین اگر با پیغام "قطع اتصال" مواجه شدید، نگران نشوید. چند دقیقه صبر کنید و دوباره امتحان کنید. 
/mcp list

۷. یک افزونه جیمیل ایجاد کنید

  1. از Gemini بخواهید اولین نسخه افزونه Gmail ما را ایجاد کند: 
Use Apps Script to create a new Google Workspace add-on that displays a random cat image using the Cat-as-a-Service API upon opening the add-on in Gmail. Make sure you update the code and manifest files, use the correct scopes, and use the API documentation at https://cataas.com/doc.html.

Once done, provide a link to view the project.
  1. پس از اینکه Gemini به درخواست شما پاسخ داد، روی لینک ارائه شده کلیک کنید، یا به صفحه اصلی Apps Script بروید و روی پروژه genai-cat-add-on کلیک کنید.
  2. روی آیکون تنظیمات پروژه (آیکون چرخ‌دنده) کلیک کنید ۹۴۸۵fddc5bf46369.png در سمت چپ صفحه.

2bc043bb3c3a216d.png

  1. گزینه « نمایش فایل مانیفست 'appsscript.json' در ویرایشگر » را انتخاب کنید.

e74dca570d64e540.png ۹. به صفحه ویرایشگر بروید و کد تولید شده در Code.gs و فایل مانیفست که پروژه را در appsscript.json پیکربندی می‌کند را بررسی کنید.

۸. افزونه را نصب و آزمایش کنید

  1. به صفحه پروژه Apps Script برگردید.
  2. به دنبال دکمه‌ی Deploy در بالا بگردید.
  3. روی فلش کنار Deploy کلیک کنید و Test deployments را انتخاب کنید.
  4. در کادر محاوره‌ای «استقرارهای آزمایشی» که ظاهر می‌شود، باید گزینه‌ای برای نصب افزونه‌ی منتشر نشده ببینید.
  5. روی دکمه نصب کلیک کنید.
  6. یک پیام تأیید ظاهر می‌شود. برای بستن کادر محاوره‌ای استقرار، روی «انجام شد» در پایین کلیک کنید.
  7. صفحه اصلی جیمیل را باز کنید و آن را رفرش کنید .
  8. افزونه اکنون باید در دسترس باشد. افزونه در پنل سمت راست ظاهر می‌شود.
  9. اولین باری که با افزونه تعامل می‌کنید، از شما خواسته می‌شود که به آن اجازه دسترسی به داده‌ها یا مجوزهای لازم را بدهید. برای اعطای مجوزها، دستورالعمل‌های روی صفحه را دنبال کنید.
  10. شما باید تصویری از گربه را ببینید. اگر این‌طور نیست، با به اشتراک گذاشتن پیام خطا، با Gemini CLI عیب‌یابی کنید.

۹. پیاده‌سازی منطق تولید تصویر هوش مصنوعی

  1. از Gemini بخواهید که منطق تولید تصویر را اضافه کند: 
Now update the add-on to display an AI-generated image using the samples in https://docs.cloud.google.com/vertex-ai/generative-ai/docs/multimodal/image-generation#use-image-generation. 

The image should show a cute cat if I open my inbox, and should add a speech bubble saying "<email sender name> rocks!" with the actual sender name when I open an email.
  1. صفحه اصلی جیمیل را رفرش کنید و افزونه را دوباره باز کنید. در صورت درخواست، مجوزهای جدید را بپذیرید.
  2. اکنون باید تصویر گربه تولید شده توسط هوش مصنوعی ظاهر شود. اگر تصویری نمایش داده نمی‌شود، با به اشتراک گذاشتن پیام خطا و دنبال کردن دستورالعمل‌های آن، با Gemini CLI عیب‌یابی کنید.
  3. یک ایمیل را باز کنید و توجه کنید که چگونه تصویر تغییر می‌کند تا یک حباب گفتگو با نام فرستنده نشان داده شود. هرگونه مشکل مربوط به Gemini CLI را مشابه مرحله قبل عیب‌یابی کنید.

۱۰. [اختیاری] منوی کشویی نوع حیوان را اضافه کنید

  1. از Gemini بخواهید که علاوه بر تصویر گربه، گزینه تولید حیوانات دیگر را نیز اضافه کند. 
Add a dropdown menu that lets the user choose the type of animal image it wants. Choose 2 random animals to add to the list in addition to the cat image.
  1. با کلیک روی سه نقطه عمودی و کلیک روی «به‌روزرسانی»، یا با رفرش کردن صفحه اصلی جیمیل و باز کردن دوباره افزونه، افزونه را به‌روزرسانی کنید.
  2. با انتخاب تصویر حیوان دیگری، قابلیت جدید را آزمایش کنید. اگر خطایی وجود داشت، مانند عدم رفرش شدن رابط کاربری یا نمایش خطا، با به اشتراک گذاشتن پیام خطا و دنبال کردن دستورالعمل‌های آن، با Gemini CLI عیب‌یابی کنید.

۱۱. تمیز کردن

خروج از رابط خط فرمان Gemini

از Gemini CLI خارج شوید و با اجرای دستور زیر، آمار استفاده خود را مشاهده کنید: 

/quit

حذف پروژه گوگل کلود

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

gcloud projects delete $GOOGLE_CLOUD_PROJECT

پروژه حذف اسکریپت برنامه‌ها

کلیک کنید روی dc2524b2c9878567.png نماد اطلاعات در پنل ناوبری سمت چپ، و سپس روی 4ad389ddfeda5d7f.png برای حذف پروژه Apps Script، روی نماد سطل زباله در سمت راست صفحه کلیک کنید.

۱۲. نکات عیب‌یابی

  • اگر با رابط خط فرمان Gemini و افزونه‌های آن مشکل دارید، می‌توانید از دستور زیر برای اجرای یک نسخه کاری خاص از رابط خط فرمان Gemini استفاده کنید: 
npx https://github.com/google-gemini/gemini-cli#v0.12.0
  • اگر با هرگونه خطایی مواجه شدید، از Gemini بخواهید که آنها را برای شما برطرف کند و خطاها و زمینه (محل وقوع خطا) را به اشتراک بگذارید.
  • اگر Gemini ثبت خطا را پیاده‌سازی کرده و از شما می‌خواهد هرگونه خطایی را به اشتراک بگذارید، مراحلی را که باعث خطا شده‌اند دوباره اجرا کنید و سپس نتایج را با Gemini به اشتراک بگذارید.
  • می‌توانید یک اعلان مانند این را امتحان کنید: 
You have my permission to fix any errors. Please go ahead and make it work.
  • اگر گیر کرده‌اید و می‌خواهید به Gemini کمک کنید، می‌توانید از دستورالعمل زیر استفاده کنید: 
Use the following Github repo as a reference implementation to make my add-on work: https://github.com/googleworkspace/add-ons-samples/tree/main/apps-script/generative-ai/cat-add-on

۱۳. تبریک می‌گویم!

شما با موفقیت آزمایشگاه را به پایان رساندید و از رابط خط فرمان Gemini برای کدنویسی ویبره یک افزونه جیمیل استفاده کردید.

در این آزمایشگاه، شما یاد گرفتید که چگونه:

  • از رابط خط فرمان Gemini استفاده کنید.
  • ابزارها را نصب کنید و Gemini CLI را با استفاده از سرورهای MCP (Model Context Protocol) گسترش دهید.
  • ساخت، استقرار و نصب افزونه جیمیل.

حالا آماده‌اید تا به آزمایشگاه بعدی‌مان برویم.