شروع کار با افزونه‌های Gemini CLI

۱. مقدمه

Gemini CLI یک عامل متن‌باز و مبتنی بر هوش مصنوعی برای ترمینال شماست که قدرت مدل‌های Gemini را مستقیماً به خط فرمان شما می‌آورد. اگرچه به خودی خود قدرتمند است، اما پتانسیل واقعی آن از طریق افزونه‌های Gemini CLI آشکار می‌شود.

افزونه‌ها روش رسمی و استاندارد برای افزایش قابلیت‌های رابط خط فرمان Gemini هستند. قبل از افزونه‌ها، سفارشی‌سازی رابط خط فرمان اغلب شامل ویرایش دستی فایل‌های پیکربندی مانند settings.json بود، فرآیندی که می‌توانست «نامرتب و مستعد خطا» باشد.

یک افزونه را به عنوان یک "ظرف حمل و نقل" برای سفارشی‌سازی‌های Gemini CLI در نظر بگیرید. این یک بسته مستقل، قابل نسخه‌بندی و به راحتی قابل توزیع است که تمام اجزای مورد نیاز برای آموزش مجموعه‌ای جدید از مهارت‌ها به Gemini را در خود جای داده است. این "ظرف حمل و نقل" می‌تواند شامل موارد زیر باشد:

• پیکربندی‌های سرور MCP: این پیکربندی‌ها، جمینی را به ابزارها و APIهای خارجی، مانند APIهای گوگل کلود یا سرویس‌های شخص ثالث، متصل می‌کنند.
• فایل‌های زمینه (GEMINI.md): اینها «کتابچه‌های راهنما» هستند که دستورالعمل‌ها و راهنمایی‌های خاصی را در مورد نحوه استفاده مؤثر از ابزارهای جدید در اختیار مدل قرار می‌دهند.
• دستورات اسلش سفارشی (فایل‌های .toml): این فایل‌ها، دستورات پیچیده و چند مرحله‌ای را در قالب دستورات ساده و آسان برای استفاده، مانند /deploy، کپسوله می‌کنند.
• محدودیت‌های ابزار (excludeTools): این گزینه‌ها می‌توانند ابزارهای داخلی را غیرفعال کنند تا محیطی امن‌تر یا متمرکزتر ایجاد شود.

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

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

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

• Gemini CLI و پیش‌نیازهای Google Cloud آن را نصب و پیکربندی کنید.
• برای یافتن افزونه‌ها، گالری رسمی افزونه‌های Gemini CLI را مرور کنید.
• برای نصب، فهرست کردن و مدیریت افزونه‌ها، از رابط خط فرمان gemini extensions استفاده کنید.
• بررسی چند افزونه‌ی Gemini CLI

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

• افزونه‌های Gemini CLI چیستند و چرا استانداردی برای سفارشی‌سازی CLI هستند؟
• نحوه پیدا کردن و نصب افزونه‌ها از گالری افزونه‌ها یا آدرس اینترنتی گیت‌هاب.
• عملکرد دستورات مدیریت کلید: gemini extensions install ، gemini extensions list و gemini extensions update .
• نصب و استفاده از چند افزونه Gemini CLI

آنچه نیاز دارید

• مرورگر وب کروم
• یک حساب جیمیل
• یک پروژه ابری با قابلیت پرداخت صورتحساب

این آزمایشگاه کد برای کاربران و توسعه‌دهندگان در تمام سطوح (از جمله مبتدیان) طراحی شده است. انتظار می‌رود که با Gemini CLI آشنایی داشته باشید، اگرچه مراحلی برای نصب Gemini CLI از ابتدا ارائه خواهد شد. اگر می‌خواهید با Gemini CLI آشنا شوید، آزمایشگاه کد را امتحان کنید: کار عملی با Gemini CLI.

۲. قبل از شروع

ایجاد یک پروژه

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

برای اعتبارهای Google Cloud: اگر می‌خواهید برای شروع کار از اعتبارهای Google Cloud استفاده کنید، از این لینک برای استفاده از اعتبارهایی که به شما در تکمیل آزمایشگاه کمک می‌کنند، استفاده کنید. می‌توانید دستورالعمل‌های اینجا را برای استفاده از آن دنبال کنید.

3. شما از Cloud Shell ، یک محیط خط فرمان که در Google Cloud اجرا می‌شود و bq از قبل روی آن بارگذاری شده است، استفاده خواهید کرد. روی Activate Cloud Shell در بالای کنسول Google Cloud کلیک کنید.

4. پس از اتصال به Cloud Shell، با استفاده از دستور زیر بررسی می‌کنید که آیا از قبل احراز هویت شده‌اید و پروژه روی شناسه پروژه شما تنظیم شده است یا خیر:

gcloud auth list

5. دستور زیر را در Cloud Shell اجرا کنید تا تأیید شود که دستور gcloud از پروژه شما اطلاع دارد.

gcloud config list project

6. اگر پروژه شما تنظیم نشده است، از دستور زیر برای تنظیم آن استفاده کنید:

gcloud config set project <YOUR_PROJECT_ID>

7. API های مورد نیاز را از طریق دستور زیر فعال کنید. این کار ممکن است چند دقیقه طول بکشد، پس لطفاً صبور باشید.

gcloud services enable cloudresourcemanager.googleapis.com \
                       servicenetworking.googleapis.com \
                       run.googleapis.com \
                       cloudbuild.googleapis.com \

در صورت اجرای موفقیت‌آمیز دستور، باید پیامی مشابه آنچه در زیر نشان داده شده است را مشاهده کنید:

Operation "operations/..." finished successfully.

اگر هر API از قلم افتاده باشد، می‌توانید همیشه آن را در طول پیاده‌سازی فعال کنید.

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

یک پوشه نمونه ( gemini-cli-projects ) ایجاد کنید و از طریق دستورات نشان داده شده در زیر به آن بروید. اگر ترجیح می‌دهید از نام پوشه دیگری استفاده کنید، لطفاً این کار را انجام دهید.

mkdir gemini-cli-projects

بیایید به آن پوشه برویم:

cd gemini-cli-projects

توجه: اگر از Google Cloud Shell استفاده می‌کنید، رابط خط فرمان Gemini از قبل نصب شده است.

شما می‌توانید مستقیماً Gemini CLI را از طریق دستور gemini در یک ترمینال Cloud Shell جدید اجرا کنید یا اینکه از قبل در یک ترمینال Cloud Shell جداگانه اجرا شده است.

اولین تعامل ما با رابط خط فرمان Gemini

ما باید مطمئن شویم که همه چیز در محیط Gemini CLI ما خوب است، بنابراین می‌توانیم اولین اعلان خود را مطابق شکل زیر ارائه دهیم:

Give me a famous quote on Artificial Intelligence and who said that?

متوجه خواهید شد که درخواست ما منجر به فراخوانی ابزار GoogleSearch (ابزاری داخلی در Gemini CLI) شده است. به عبارت دیگر، شما قبلاً یکی از ابزارهای قدرتمند داخلی Gemini CLI به نام GoogleSearch را اجرا کرده‌اید که پاسخ‌های خود را بر اساس اطلاعاتی که از وب دریافت می‌کند، ارائه می‌دهد. شما باید پاسخی برای درخواست خود دریافت کنید.

بیایید در ادامه با افزونه‌ها (Extensions) شروع کنیم.

۳. افزونه چیست؟

یک افزونه، یک بسته‌ی مستقل، قابل نسخه‌بندی و به راحتی قابل توزیع است. آن را به عنوان "ظرف حمل و نقل" برای سفارشی‌سازی‌های Gemini CLI خود در نظر بگیرید که هر آنچه را که برای یک گردش کار خاص نیاز دارید، در یک بسته‌ی واحد و مرتب قرار می‌دهد.

یک افزونه می‌تواند هر ترکیبی از موارد زیر را در خود جای دهد:

• دستورات اسلش سفارشی (فایل‌های .toml شما).
• پیکربندی‌های سرور MCP (که قبلاً در settings.json قرار داشتند).
• فایل‌های زمینه (GEMINI.md) برای ارائه دستورالعمل‌ها و راهنماهای خاص به مدل.
• محدودیت‌های ابزار (excludeTools) برای ایجاد محیطی امن‌تر و متمرکزتر.

چرا از افزونه‌ها استفاده کنیم؟ مزایای اصلی

استفاده از افزونه‌ها برای سفارشی‌سازی‌های شما چندین مزیت قدرتمند را ارائه می‌دهد:

• نصب تک‌فرمانی : این نکته کلیدی است. به جای راه‌اندازی دستی چند مرحله‌ای، کاربر می‌تواند یک مجموعه ابزار کامل و پیچیده را با یک دستور نصب کند: gemini extensions install <URL> یا gemini extensions install --path=some/local/path . <URL> در دستور بالا می‌تواند آدرس گیت‌هاب (Github URL) باشد که افزونه را در آن میزبانی کرده‌اید.
• توزیع ساده‌شده : اشتراک‌گذاری کارتان به آسانی اشتراک‌گذاری یک URL مخزن گیت می‌شود. دیگر نیازی به رد و بدل کردن فایل‌های تکی و قطعه کدهای پیکربندی نیست.
• مدیریت نسخه‌بندی و وابستگی : از آنجا که افزونه‌ها معمولاً در مخازن گیت میزبانی می‌شوند، شما کنترل نسخه را به صورت رایگان دریافت می‌کنید. gemini extensions update command برای به‌روزرسانی یک افزونه به آخرین نسخه وجود دارد.
• قابلیت کشف و اکوسیستم : افزونه‌ها پایه و اساس یک اکوسیستم غنی و باز هستند، دقیقاً مانند بازارهای VS Code یا Chrome. مکانیسم افزونه می‌تواند پایه و اساس یک بازار آینده را تشکیل دهد که در آن این افزونه‌ها برای بررسی، دانلود و موارد دیگر، به سبک یک جامعه واقعی، در دسترس باشند.

معرفی این چارچوب توسعه، نشانه‌ای واضح است که Gemini CLI در حال تکامل از یک ابزار مستقل قدرتمند به یک پلتفرم واقعاً قابل توسعه است.

۴. درک اصول اولیه افزونه‌ها

این بخش بخش‌های مربوط به کاربر در اکوسیستم افزونه‌ها را پوشش می‌دهد: یافتن افزونه‌ها و مدیریت آنها .

گالری افزونه‌ها را کاوش کنید

گالری افزونه‌ها، بازار مرکزی برای کشف تمام افزونه‌های رسمی ساخته‌شده توسط گوگل و شخص ثالث است:

1. آدرس اینترنتی زیر را در مرورگر خود باز کنید: https://geminicli.com/extensions/browse/ .
2. این گالری موتور کشف‌پذیری برای این اکوسیستم است. می‌توانید افزونه‌های شرکت‌هایی مانند GitHub، Redis و DynaTrace را ببینید که وسعت ابزارهای موجود را نشان می‌دهند.
3. به پایین اسکرول کنید و کارت افزونه‌ی Cloud Run را پیدا کنید.
4. توجه داشته باشید که این کارت شامل توضیحات، نام نویسنده (گوگل) و دکمه‌ی دستور Copy install با یک کلیک است. این ساده‌ترین راه برای دریافت دستور نصب یک افزونه است.

افزونه‌های Gemini CLI - دستورات مدیریتی

دستور gemini extensions نقطه شروع شما برای مدیریت افزونه‌های محلی‌تان است.

برای مشاهده لیست دستورات موجود، آن را در ترمینال خود اجرا کنید.

دستورات ساده هستند (نصب/حذف، فهرست کردن، به‌روزرسانی، فعال/غیرفعال کردن و غیره) و ما از برخی از این دستورات در این آزمایشگاه کد استفاده خواهیم کرد.

وضعیت فعلی خود را بررسی کنید

قبل از نصب هر چیزی، بیایید «صفحه سفید» خود را بررسی کنیم.

1. دستور gemini extensions list را اجرا کنید:
2. شما باید خروجی زیر را ببینید که تأیید می‌کند هنوز هیچ افزونه‌ای نصب نشده است.

No extensions installed.

۵. افزونه Cloud Run (استقرار یک برنامه)

افزونه Cloud Run که در گالری افزونه‌های Gemini CLI موجود است، یک سرور MCP است که به ما امکان می‌دهد برنامه‌های خود را در Cloud Run مستقر کنیم.

کارت افزونه Cloud Run از گالری افزونه‌ها در زیر نشان داده شده است:

ابتدا افزونه Cloud Run را با کلیک روی دستور Copy install همانطور که در بالا نشان داده شده است نصب می‌کنیم. سپس آن دستور را در ترمینال Cloud Shell پیست کنید (باید مشابه زیر باشد):

gemini extensions install https://github.com/GoogleCloudPlatform/cloud-run-mcp

با اجرای دستور بالا، یک تأیید از شما خواسته می‌شود. آن را تأیید کنید. سپس افزونه Cloud Run باید با موفقیت نصب شود.

Installing extension "cloud-run".
**Extensions may introduce unexpected behavior. Ensure you have investigated the extension source and trust the author.**
This extension will run the following MCP servers:
  * cloud-run (local): npx -y @google-cloud/cloud-run-mcp
This extension will append info to your gemini.md context using gemini-extension/GEMINI.md
Do you want to continue? [Y/n]: Y
Extension "cloud-run" installed successfully and enabled.

اگر اکنون دستور gemini extensions list را اجرا کنید، باید افزونه Cloud Run را مطابق شکل زیر نصب شده ببینید:

✓ cloud-run (1.0.0)
 Path: <HOME_FOLDER>/.gemini/extensions/cloud-run
 Source: https://github.com/GoogleCloudPlatform/cloud-run-mcp (Type: github-release)
 Release tag: v1.5.0
 Enabled (User): true
 Enabled (Workspace): true
 Context files:
  <HOME_FOLDER>/.gemini/extensions/cloud-run/gemini-extension/GEMINI.md
 MCP servers:
  cloud-run

اگر اکنون Gemini CLI را اجرا کنید و دستور /mcp را اجرا کنید، موارد زیر را مشاهده خواهید کرد:

حالا بیایید به Cloud Shell برگردیم و سعی کنیم یک برنامه را مستقر کنیم. برای این کار ابتدا به یک برنامه ساده برای استقرار در Cloud Run نیاز داریم. مراحل زیر را دنبال کنید:

مطمئن شوید که در پوشه‌ای هستید که قبلاً ایجاد کردیم، یعنی gemini-cli-projects . پوشه دیگری درون این پوشه با نام gemini-cloud-run ایجاد کنید و به داخل آن بروید.

mkdir gemini-cloud-run

cd gemini-cloud-run

حالا دو فایل در این پوشه ایجاد کنید (فایل app.py و requirements.txt )، که محتوای آنها در زیر آمده است:

app.py

from flask import Flask
app = Flask(__name__)
@app.route('/')
def hello_world():
  return 'Hello from Gemini and Cloud Run!'
if __name__ == "__main__":
  app.run(debug=True, host='0.0.0.0', port=8080)

requirements.txt

Flask
gunicorn

حالا Gemini CLI را از پوشه gemini-cloud-run اجرا کنید و پس از آماده شدن ترمینال، دستور زیر را اجرا کنید:

/deploy --project="PROJECT_ID" --location="PROJECT_LOCATION" --name="SERVICE_NAME"

شما باید PROJECT_ID (شناسه پروژه گوگل کلود)، PROJECT_LOCATION و SERVICE_NAME را مشخص کنید. اگر این موارد را وارد نکنید، دستور Cloud Run ابزارهای مناسب را برای کمک به شما در انتخاب آنها فراخوانی می‌کند.

به عنوان بخشی از این فرآیند، ابزار مناسب را از افزونه Cloud Run MCP Server که نصب کرده‌ایم انتخاب می‌کند. برای مثال، باید پیامی مانند این را ببینید:

ادامه دهید و اجازه دهید از این ابزار استفاده شود.

همین! رابط خط فرمان Gemini اکنون تمام اطلاعات مورد نیاز خود را به همراه مجوز شما برای اجرای ابزارها در اختیار دارد. اکنون کل مراحل استقرار را اجرا خواهد کرد: ساخت تصویر Docker، ارسال آن به رجیستری Artifact، پیکربندی و استقرار یک سرویس Cloud Run جدید.

بعد از چند لحظه (در واقع ۲-۳ دقیقه)، یک پیام موفقیت‌آمیز به همراه URL سرویس مشاهده خواهید کرد. نمونه‌ای از اجرای آن در زیر نشان داده شده است:

The Cloud Run service SERVICE_NAME has been deployed from the current folder in project PROJECT_ID.
  You can view the service in the Cloud Console: https://console.cloud.google.com/run/detail/PROJECT_LOCATION/SERVICE_NAME?project=PROJECT_ID
  The service is accessible at: https://SERVICE_NAME-SOME-ID.a.run.app

روی آن لینک کلیک کنید. باید ببینید که برنامه Flask صفحه اصلی را نمایش می‌دهد:

این به شما قدرت افزونه‌ی Gemini CLI (در این مورد Cloud Run) را نشان می‌دهد، که در آن پیچیدگی دستورات gcloud CLI به طور کامل محصور شده و به سادگی تمام جزئیات را برای شما انجام می‌دهد.

در صورت تمایل می‌توانید ابزارهای دیگر موجود در Cloud Run MCP Server را بررسی کنید.

۶. افزونه BigQuery (تحلیل مجموعه داده‌های بزرگ)

برای دنبال کردن موارد زیر به شما نیاز دارید:

• پروژه Google Cloud با API فعال BigQuery.
• مجوزهای IAM:
• کاربر BigQuery (roles/bigquery.user)

1. این دستور را اجرا کنید تا متغیر محیطی BIGQUERY_PROJECT خود را تنظیم کنید. این پروژه‌ای است که وظایف BigQuery را اجرا می‌کند، نه لزوماً پروژه‌ای که داده‌های شما در آن قرار دارد (اگرچه می‌توانند در واقع یکی باشند)

export BIGQUERY_PROJECT=<YOUR_GCP_PROJECT_ID>

2. افزونه BigQuery Data Analytics را از طریق دستور زیر نصب کنید. حتماً به آن اجازه نصب بدهید. پس از نصب موفقیت‌آمیز، اکنون ۲ افزونه در تنظیمات شما نصب شده است: cloud-run و bigquery-data-analytics .

gemini extensions install https://github.com/gemini-cli-extensions/bigquery-data-analytics

3. بیایید دوباره Gemini CLI را از طریق دستور زیر اجرا کنیم:

gemini

رابط خط فرمان Gemini باید در ترمینال شما اجرا شود:

دستورات زیر باید در ترمینال Gemini CLI وارد شوند.

4. با وارد کردن دستور اسلش زیر، تأیید کنید که افزونه‌ی BigQuery نصب شده و آماده‌ی استفاده است:

/extensions list

شما باید افزونه‌ی bigquery-data-analytics را نیز در لیست ببینید.

5. برای بررسی ابزارهای موجود، دستور زیر را اجرا کنید

/mcp list

6. بیایید یک سوال تحلیلی اساسی در مورد مجموعه داده‌های عمومی BigQuery بپرسیم: look ecommerce. این مجموعه داده شامل داده‌هایی در مورد مشتریان، محصولات و سفارشات یک سایت تجارت الکترونیک لباس خیالی است. این دستور را در Gemini CLI وارد کنید:

Look at BigQuery's the look ecommerce public dataset. Identify the top 5 products that had the most orders.

• رابط خط فرمان Gemini از شما می‌پرسد که آیا مایل به اجرای ابزارهای BigQuery هستید یا خیر. برای ادامه، گزینه سوم را انتخاب کنید: Yes, always allow all tools from server "bigquery_data_analytics" .
• در پشت صحنه، Gemini کوئری SQL مناسب را تولید می‌کند، ابزار execute_sql را فراخوانی می‌کند و یک پاسخ به زبان طبیعی را در کنار داده‌های شما برمی‌گرداند:

7. حالا، از Gemini می‌خواهیم که نرخ بازگشت محصولات را بر اساس داده‌های تاریخی پیش‌بینی کند. برای این دستور، Gemini CLI نباید سعی در تولید SQL طولانی برای ایجاد این پیش‌بینی داشته باشد، بلکه باید ابزار forecast را از سرور MCP فراخوانی کند که از AI.Forecast بیگ‌کوئری در زیر کاپوت استفاده خواهد کرد:

Forecast what the return rate will be next month.

• شما باید پاسخی شبیه به این ببینید:

۷. کاوش بیشتر

این پایان کدنویسی ما است که در آن به بررسی افزونه‌های Gemini CLI، دستورات اولیه برای کار با آنها و بررسی چند افزونه دیگر: افزونه‌های cloud-run و bigquery-data-analytics پرداختیم.

برای بررسی افزونه‌های موجود (بیش از ۱۰۰ افزونه در زمان نگارش این مطلب) که امروزه برای استفاده شما در دسترس هستند، از گالری افزونه‌های Gemini در آدرس https://geminicli.com/extensions/ دیدن کنید. هر کارت افزونه حاوی اطلاعاتی از جمله نوع افزونه (MCP، Context و غیره) به همراه لینک مخزن GitHub آن و دستوری برای نصب افزونه در محیط شما است.

۸. تبریک

تبریک می‌گویم، شما با موفقیت افزونه‌های Gemini CLI و نحوه نصب و استفاده از افزونه‌های مختلف Gemini CLI را درک کردید.

اسناد مرجع

• افزونه‌های خط فرمان Gemini
• گالری افزونه‌های Gemini CLI