استشارة فنية مُفصَّلة حول Gemini CLI

1. مقدمة

مرحبًا، اسمي "سباركي". يسعدنا انضمامك إلينا. لقد قطعتُ مسافة طويلة من مجموعة GKE في us-central1 لأكون هنا اليوم. مرحبًا بك في هذا الدرس التطبيقي حول الترميز.

لقد أمضيت حياتي كلها وأنا أتنقّل بين تدفّقات بيانات Google Cloud، وقد رأيت كل شيء. لقد رأيتكم، أي المهندسين المعماريين والمهندسين، تبنون أشياء رائعة. لكنّي رأيتك أيضًا عالقًا في الشجيرات الشائكة. أنت تعرف ما أتحدث عنه! الشعور بالتبديل بين السياقات عند تصحيح أخطاء وحدة في GKE أنت تتنقّل بين kubectl logs، ووحدة تحكّم Google Cloud Platform للتحقّق من سلامة العُقدة، وبيئة التطوير المتكاملة (IDE) للاطّلاع على الرمز المصدر الذي تم نشره، وعلامة تبويب المتصفّح التي تتضمّن مستندات Kubernetes الرسمية لعمليات ربط دورة حياة الحزمة. كل انتقال هو انقطاع في التركيز.

والأدوات المعقّدة! ‫gcloud وkubectl وterraform... كل منها مزوّد بلغة خاصة بنطاق محدّد (DSL) ومجموعة كبيرة من العلامات. يؤدي ذلك إلى البحث المستمر عن المستندات. سينتهي بك الأمر بالبحث عن أمر gcloud مثالي واحد يتضمّن المجموعة الصحيحة من العلامتَين --filter و--format للحصول على البيانات التي تحتاج إليها. الأمر أشبه بمحاولة العثور على جوزة محددة في غابة تضم ملايين الجوز. ولا أريد أن أتحدث عن المهام المتكررة. لقد رأيتك تكتب الرمزين Dockerfile وcloudbuild.yaml نفسيهما لخدمة Python جديدة مرات عديدة، لذا من المحتمل أنّ الرمز البرمجي قد سبق له أن رأى هذا الرمز.

حسنًا، سأعرض عليك طريقة أفضل. طريق سري عبر الغابة هذا هو الهدف من Gemini CLI.

ما هو Gemini CLI؟

إذًا، ما هو هذا الاختصار السحري الذي أنا متحمّس بشأنه؟

يمكنك اعتبار Gemini CLI بمثابة مساعدك الشخصي على السحابة الإلكترونية، مباشرةً في نافذة الأوامر على جهازك. إنّها محادثة وشراكة. فهو يدرك السياق، أي أنّه لا يستمع فقط، بل يفهم. يمكنه قراءة ملفاتك والتعرّف على اصطلاحات مشروعك، مثل ما إذا كنت تستخدم علامات تبويب أو مسافات، ومعرفة ما تحاول تنفيذه. يبدو الأمر وكأنّني أستطيع شمّ الجوز الذي تحاول جمعه!

البنية عالية المستوى (لنلقِ نظرة من الداخل)

كيف تعمل هذه الميزة؟ وهي مزيج من بعض الميزات الرائعة التي تعمل بتناغم:

نموذج لغوي قوي: هذا هو العقل المدبّر. وهو تحديدًا نموذج كبير ومتعدّد الوسائط درّبته Google. يشير مصطلح "متعدد الوسائط" إلى أنّ النموذج لا يفهم النصوص فقط، بل يفهم أيضًا بنية الرموز البرمجية ومعناها. يتيح ذلك للنموذج فهم برنامجك، وليس قراءته فقط.
السياق المحلي: هذا أمر بالغ الأهمية. تعمل واجهة سطر الأوامر في Gemini كعملية على جهازك المحلي، مع الأذونات نفسها التي يمتلكها حساب المستخدم. وهذا يعني أنّه يمكنه الوصول إلى نظام الملفات لتقديم مساعدة خاصة بالمشروع. إنّها ليست خدمة سحابية بعيدة تخمّن الرمز البرمجي، بل هي متوفّرة هنا بجانبك.
منظومة أدوات متكاملة: هذه هي الطريقة التي يتفاعل بها النموذج مع العالم. لديه مجموعة محدّدة جيدًا من الدوال التي يمكنه استدعاؤها، مثل read_file أو run_shell_command. يمكن اعتبارها واجهة برمجة تطبيقات آمنة. يقرّر النموذج ما يجب فعله والأداة التي يجب استخدامها، ثم ينشئ حزمة tool_code لتنفيذ ذلك. ويجعل هذا الإجراءات التي يتّخذها قابلة للتوقّع وموثوقة.
تنفيذ أوامر Shell: هذه هي الميزة السحرية الحقيقية. يمكنه تنفيذ أي أمر في bash -c <command> shell فرعي. تسجّل هذه السمة stdout وstderr وexit code. هذا إنجاز كبير! وهذا يعني أنّ Gemini CLI يمكنه تنفيذ أمر، والتحقّق مما إذا كان قد تعذّر تنفيذه، ثم محاولة إصلاحه استنادًا إلى رسالة الخطأ.
شبكة الأمان: هذا هو الجزء المفضّل لديّ! قبل تنفيذ كتلة tool_code البرمجية، سيعرض لك برنامج سطر الأوامر exact ويطلب منك تأكيده. هذه العملية تتم من جهة العميل، لذا يمكنك اتّخاذ القرار النهائي قبل أن يتم إجراء أي تغييرات على نظامك. أنت المتحكّم دائمًا.

فهو ليس مجرد برنامج محادثة مبرمَجة، بل هو برنامج ينجز المهام. مساعد نشِط في مغامرتك البرمجية

المفهوم الأساسي: التصريحي مقابل الإلزامي

أهم تغيير وأكثرها إثارة هو الانتقال من إخبار الكمبيوتر كيفية تنفيذ إجراء معيّن إلى إخباره بما تريد تنفيذه.

الأسلوب الإلزامي (الطريقة القديمة الصعبة): عليك تقديم كل خطوة على حدة. يجب أن تكون خبيرًا في لغة المجال المحدّد للأداة. مثل هذا الأمر المعقّد:
```
gcloud compute instances create my-vm --project=my-project --zone=us-central1-a --machine-type=e2-medium --image-family=debian-11 --image-project=debian-cloud --metadata-from-file startup-script=./startup.sh --tags=http-server,dev
```
يا للهول! انظر إلى كل هذا! يجب أن تعرف بنية نوع الجهاز ومجموعة الصور والبيانات الوصفية والعلامات. إذا فاتك جزء واحد، ستتلقّى رسالة خطأ غامضة.
الأسلوب التصريحي (اختصار Sparky!): ما عليك سوى إدخال طلبك باللغة الإنجليزية البسيطة.

Create a new e2-medium VM for my web server in us-central1, run the startup.sh script, and tag it for http traffic.

هذا كل شيء! يحلّل Gemini طلبك ويربطه بمَعلمات أداة gcloud، ثم يحدّد الصيغة الصحيحة لكل علامة وينشئ لك هذا الأمر المعقّد. بعد ذلك، سيتم عرضها عليك للموافقة عليها. فالمهم هو أن تكون قادرًا على التفكير بالصورة الأعم، وليس حفظ علامات سطر الأوامر.

تعزيز إمكانات Gemini: مقدّمة حول إضافات CLI

مع أنّ Gemini CLI هو أداة فعّالة جاهزة للاستخدام، يمكن الاستفادة من إمكاناتها الكاملة من خلال الإضافات. الإضافات هي حِزم من الطلبات والأدوات والأوامر المخصّصة التي تعزّز وظائف واجهة سطر الأوامر، ما يتيح لك تخصيصها لتلبية احتياجاتك وسير عملك المحدّدة.

العثور على الإضافات وتثبيتها

تتضمّن Gemini CLI منظومة متكاملة متزايدة من الإضافات التي طوّرها كلّ من Google والمطوّرين الخارجيين. يمكنك تصفّح الدليل الرسمي للإضافات على geminicli.com/extensions.

لتثبيت إضافة، يمكنك استخدام الأمر gemini extensions install مع عنوان URL لمستودع Git الخاص بالإضافة. على سبيل المثال، لتثبيت إضافة Cloud SQL for PostgreSQL الرسمية، عليك تنفيذ الأمر التالي:

gemini extensions install https://github.com/gemini-cli-extensions/cloud-sql-postgresql

حسنًا، يكفي حديثًا. لنبدأ بتجربة هذه الميزة.

2. قبل البدء

مرحبًا، أيها السحرة المستقبليون في مجال الحوسبة السحابية! ‫Sparky في خدمتك. قبل أن نبدأ مغامرتنا الكبيرة، علينا التأكّد من أنّ بيئة ورشة العمل جاهزة. فكِّر في الأمر على أنّه تجهيز حقائبنا بكل الأدوات المناسبة وجوز البلوط السحري قبل أن نتوجّه إلى الغابة. تابعني

إذا كان لديك مشروع على السحابة الإلكترونية من Google Cloud، يمكنك استخدام Gemini CLI في Google Cloud Shell لأنّه يأتي مثبّتًا مسبقًا مع Gemini CLI. يمكنك بدلاً من ذلك اتّباع الخطوات التالية لإعدادها على جهازك المحلي.

الخطوة 1: المتطلبات الأساسية

يحتاج كل مغامر جيد إلى أساس متين. قبل أن نتمكّن من تثبيت Gemini CLI، يجب إعداد بعض الأمور على جهازك المحلي.

حزمة تطوير البرامج (SDK) من Google Cloud (gcloud): هذه هي مجموعة الأدوات الرئيسية في Google Cloud. ‫Gemini CLI هو جزء من هذه المجموعة.

التحقّق من تثبيته: شغِّل gcloud --version. إذا ظهر لك رقم إصدار، يعني ذلك أنّك جاهز لاستخدام التطبيق.
في حال عدم التثبيت: اتّبِع التعليمات الرسمية على cloud.google.com/sdk/docs/install.

Git: سنحتاج إلى هذا البرنامج لاستنساخ مستودع الدرس العملي.

التحقّق من تثبيته: شغِّل git --version.
في حال عدم التثبيت: يمكنك الحصول عليه من git-scm.com/downloads.

مشروع Google Cloud Platform والمصادقة:

تأكَّد من توفّر مشروع Google Cloud مع تفعيل الفوترة. هذا مهم للغاية.
سجِّل الدخول إلى حسابك على Google من خلال تنفيذ ما يلي:

gcloud auth login

اضبط مشروعك للجلسة. ابحث عن رقم تعريف مشروعك من وحدة تحكّم Google Cloud Platform ونفِّذ ما يلي:

gcloud config set project YOUR_PROJECT_ID

(استبدِل YOUR_PROJECT_ID برقم تعريف مشروعك الفعلي).

الإصدار 20 من Node.js أو إصدار أحدث

الخطوة 2: الحصول على Magic! (تثبيت Gemini CLI)

حسنًا، بعد أن انتهينا من الأساسيات، حان الوقت للحدث الرئيسي! سنثبِّت Gemini CLI.

التشغيل على الفور باستخدام npx

# Using npx (no installation required)
npx https://github.com/google-gemini/gemini-cli

التثبيت على مستوى العالم باستخدام npm

npm install -g @google/gemini-cli

التثبيت على مستوى العالم باستخدام Homebrew (نظام التشغيل macOS أو Linux)

brew install gemini-cli

التحقّق من إصدار Gemini

gemini --version

من المفترض أن يظهر لك رقم الإصدار. وهذا يؤكّد نجاح عملية التثبيت.

الخطوة 3: التشغيل (الإعداد)

بعد تثبيت Gemini CLI، علينا منحه مفاتيح الوصول إلى كل الميزات. أولاً، شغِّل الأداة من خلال تنفيذ الأمر gemini في الوحدة الطرفية. من المفترض أن تظهر لك الشاشة التالية:

لتسهيل الأمر، يمكنك المصادقة باستخدام حساب Google، ما يتيح لك الوصول إلى Gemini 2.5‎ Pro مع قدرة استيعاب مليون رمز مميّز وما يصل إلى 60 طلبًا في الدقيقة و1,000 طلب في اليوم بدون الحاجة إلى إدارة مفتاح واجهة برمجة التطبيقات.

إذا كنت تريد الوصول إلى نماذج Gemini معيّنة أو الترقية إلى حدود أعلى عند الحاجة، استخدِم مفتاح Gemini API كطريقة مصادقة.

بالنسبة إلى فِرق Enterprise وأحمال عمل الإنتاج التي تم إعداد حساب فوترة ومشروع Google لها، استخدِم Vertex AI للاستفادة من الأمان والامتثال المتقدّمين.

استنادًا إلى الخيار الذي اخترته، سيُطلب منك اتّخاذ الخطوات التالية لإعداد المصادقة. يُرجى الرجوع إلى مستندات واجهة سطر الأوامر في Gemini للحصول على مزيد من التفاصيل حول هذه الخيارات.

إذا كنت تنوي استخدام منصة Vertex AI من Google Cloud، عليك أولاً الخروج من Gemini CLI من خلال الضغط على ctrl+c مرتين، ثم ضبط متغيرات البيئة المطلوبة.

بغض النظر عن طريقة المصادقة، عليك عادةً ضبط المتغيّرَين التاليَين: GOOGLE_CLOUD_PROJECT وGOOGLE_CLOUD_LOCATION.

لضبط هذه المتغيّرات، اتّبِع الخطوات التالية:

# Replace with your project ID and desired location (e.g., us-central1)
export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION"

لنبدأ الآن بتسجيل الدخول إلى Google Cloud:

gcloud auth application-default login

بعد إكمال عملية المصادقة باستخدام الطريقة السابقة، شغِّل Gemini CLI مرة أخرى عن طريق تنفيذ الأمر gemini في نافذة الأوامر. في خيارات المصادقة، انقر على Vertex AI، وبذلك تكون قد انتهيت.

الخطوة 4: اختبار Spark (التحقّق من صحة الإعداد)

هذه هي لحظة الحقيقة! لنرى ما إذا كان كل شيء يعمل. نفِّذ الأوامر التالية للتأكّد من أنّ جميع المؤشرات خضراء.

أدخِل الطلب التالي:

What is my current directory?

من المفترض أن يردّ Gemini CLI بإخبارك بدليل العمل الحالي. يختبر هذا الإجراء نموذج اللغة الأساسي وعملية الدمج مع Shell.

اختبار اتصال Google Cloud Platform:

list my gcs buckets

إذا كانت لديك أي حِزم GCS، من المفترض أن يتم إدراجها. إذا لم يكن هناك أي أجهزة، سيتم إعلامك بذلك. يؤكّد ذلك أنّه مرتبط بمشروعك على Google Cloud Platform بشكلٍ صحيح.

الخطوة 5: منحها المزيد من الميزات الخارقة (تثبيت الإضافات)

لنحسّن الآن إمكانات Gemini CLI من خلال تثبيت بعض الإضافات التي ستكون مفيدة لاحقًا في المختبر.

Cloud Run

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

أمان Gemini CLI

gemini extensions install https://github.com/gemini-cli-extensions/security

gcloud

gemini extensions install https://github.com/gemini-cli-extensions/gcloud

Cloud SQL for PostgreSQL

gemini extensions install https://github.com/gemini-cli-extensions/cloud-sql-postgresql

إذا نجحت كل هذه الأوامر، تكون قد أصبحت جاهزًا رسميًا لحضور ورشة العمل. تم إعداد بيئة العمل، وأنت على استعداد لبدء تعزيز إنتاجيتك. نراك في المختبر الأول!

3- المفاهيم الأساسية والتفاعل مع مساحة العمل المحلية

حسنًا، هل أنت مستعد للبدء؟ سنستعرض الآن الأدوات الفعلية في حزمة أدوات Gemini الجديدة. أعتبرها قواي الخارقة لاستكشاف السحابة الإلكترونية والبناء فيها. لنستعرض بعض التفاصيل الفنية حول طريقة عملها.

الإمكانات الأساسية

أصنّف قدراتي إلى فئتين: الاطّلاع على ما هو متاح، ثم تنفيذ المهام.

فهم البيئة المحيطة (حواسي الخارقة!)

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

‫list_directory: هذه هي أداة "التنقيب" الأساسية. وهي عبارة عن برنامج تضمين مباشر حول قائمة الدليل العادية على مستوى نظام التشغيل. لكنّ الجزء الرائع هو أنّ النموذج يمكنه تحليل هذا الناتج المنظَّم لاتخاذ قرارات، مثل اختيار استكشاف دليل فرعي باسم src.
‫glob: هذا هو "مكتشف الجوز" الخاص بي! يستخدم هذا التطبيق أنماط glob عادية، مثل * و** و? و[]، والتي تعرفها من أشياء مثل .gitignore. وبالتالي، يمكنك طرح السؤال "ابحث عن جميع ملفات *.py في الدليل app" باستخدام النمط app/**/*.py. وهي طريقة فعّالة لجمع مجموعة محدّدة من الملفات ليحلّلها النموذج.
‫search_file_content: هذه هي رؤيتي بالأشعة السينية! ويستخدم تعبيرات عادية كاملة (regex) في عمليات البحث، وليس فقط مطابقة السلسلة البسيطة. هذه ميزة فعّالة للغاية. يمكنك أن تطلب منه العثور على أنماط معقّدة، مثل "العثور على جميع مسارات Flask التي تستخدم طريقة POST"، ما قد يؤدي إلى إنشاء تعبير عادي مثل app\.route\(.*methods=\['POST'\].*\). تعرض هذه الدالة مسار الملف ورقم السطر والسطر المطابق، ما يوفّر للنموذج كل السياق الذي يحتاج إليه.
read_file: بعد العثور على ملف مثير للاهتمام، ستحتاج إلى فتحه. تم تحسين read_file لهذا الغرض. يمكنك قراءة ملف كامل، أو يمكنك استخدام المَعلمتَين offset وlimit لقراءته على شكل أجزاء. وهذا يعني أنّ النموذج يمكنه فحص ملفات السجل الكبيرة جدًا بكفاءة بدون أن تنتهي المهلة.

من الفهم إلى اتخاذ الإجراءات (حان وقت البناء!)

حسنًا، لقد استكشفت التضاريس. حان الوقت الآن لبناء عشّك. تتيح لك هذه الأدوات إجراء تغييرات وإنجاز المهام.

**write_file**: هل تحتاج إلى إنشاء ملف جديد من البداية؟ ‫write_file هي عملية ذرية تكتب المحتوى الكامل الذي تقدّمه إلى مسار محدّد. إنّها مثالية لإنشاء وحدات جديدة أو إنشاء Dockerfile من البداية استنادًا إلى احتياجات مشروعك.
**replace**: هذه الأداة مخصّصة لإجراء تغييرات جراحية. لا يقتصر الأمر على البحث والاستبدال البسيطَين. يجب تقديم old_string وnew_string. ولكي يعمل هذا الإجراء بأمان، يجب أن يكون old_string مقتطفًا فريدًا من الملف، وعادةً ما يتضمّن عدة أسطر من السياق قبل الجزء الذي تريد تغييره وبعده. يضمن ذلك أنّنا لن نغيّر سوى جزء الرمز البرمجي exact لما تريد تغييره.
‫**run_shell_command**: هذه هي أفضل طريقة لتعزيز الأداء. ينفّذ الأمر المحدّد في bash -c <command> shell فرعي. يحصل النموذج على stdout وstderr وexit code. هذا أمر بالغ الأهمية لإنشاء سير العمل. يمكن للنموذج تشغيل terraform plan وقراءة الناتج، وإذا كانت الخطة ناجحة (رمز الخروج 0)، يمكنه بعد ذلك أن يسألك عمّا إذا كان يجب تطبيقها.

شبكة الأمان (وعدي لك!)

قد يكون تنفيذ الأوامر أمرًا مخيفًا. حسنًا لهذا السبب، من المهم جدًا توفير شبكة أمان. عندما ينشئ النموذج حزمة tool_code تحتوي على طلب إلى run_shell_command أو write_file، يعترض عليها برنامج Gemini CLI. يعرض لك هذا الأمر الأمر الدقيق أو المحتوى الكامل للملف الذي سيتمّت كتابته ويقدّم لك طلبًا [y/n]. ولن يحدث أي شيء بدون موافقتك الصريحة. أنت المتحكّم دائمًا.

4. استكشاف مشروع

الهدف: استخدام Gemini CLI لفهم قاعدة رموز غير مألوفة بدون مغادرة نافذة الأوامر

السيناريو: أنت مطوّر جديد، وعليك أن تتعرّف على هذا المشروع بسرعة.

المهمة 0: الإعداد - استنساخ المشروع

أولاً، علينا الحصول على الرمز. يتم إخفاء هذا الملف في مستودع عام على GitHub، في "شجرة" باسم quickpoll. لنطلب من Gemini CLI استنساخها. قبل ذلك، لننشئ دليل عمل ونشغّل Gemini CLI من داخل دليل العمل:

mkdir workdir
cd workdir
gemini

الآن، اكتب الطلب التالي:

clone the github repository from the URL: https://github.com/gauravkakad-google/quickpoll.git

سيفهم Gemini أنّ "استنساخ" يعني استخدام الأمر git clone. سيؤدي ذلك إلى إنشاء run_shell_command استدعاء أداة يتضمّن شيئًا مثل git clone https://github.com/gauravkakad-google/quickpoll.git. بعد الموافقة عليه، سيتم تنزيل المستودع لك.

الآن، لنخرج من Gemini CLI بالضغط على ctrl+c مرتين، ثم ننتقل إلى مستودع النماذج ونشغّل Gemini CLI مرة أخرى:

cd quickpoll
gemini

رائع! بعد أن أصبحنا داخل شجرة المشروع، يمكننا البدء في الاستكشاف.

المهمة 1: إدراج جميع الملفات في المشروع

بعد أن دخلنا، لنرسم خريطة للغابة بأكملها. نريد الاطّلاع على كل ملف على حدة. اسأل Gemini السؤال التالي:

List all the files in the project.

من المرجّح أن يستخدم Gemini الأداة glob مع النمط **/*. يُدرِج هذا الأمر بشكل متكرّر كل ملف، ما يمنحك بيانًا كاملاً لقاعدة الرموز البرمجية. وهي خطوة أولى رائعة لفهم بنية المشروع.

المهمة 2: العثور على جميع الملفات التي تستورد google.cloud.sql.connector

حسنًا، أنا فضولي. أين يتواصل هذا المشروع مع Google Cloud Storage؟ لنبدأ التحقيق. اطرح السؤال التالي:

Find all files that import the 'google.cloud.sql.connector' library.

باستخدام search_file_content، سيعثر Gemini على الملفات المحدّدة التي تحتوي على عبارة الاستيراد هذه. يؤدي ذلك على الفور إلى تضييق نطاق تركيزك على أجزاء الرمز التي تتعامل مع Cloud SQL. في هذا المشروع، من المفترض أن يعثر على backend/main.py.

المهمة 3: عرض محتوى ملف Dockerfile الرئيسي

أرى Dockerfile! هذا هو المخطط الأولي للحاوية. لنلقِ نظرة على ما في الداخل. ما عليك سوى طرح السؤال التالي:

Show me the contents of the main Dockerfile.

سيستخدم Gemini read_file لعرض Dockerfile. يمكنك تحليل الصورة الأساسية (FROM) والموارد الاعتمادية التي يتم تثبيتها (RUN pip install...) والأمر النهائي (CMD)، ما يتيح لك معرفة بيئة وقت التشغيل للتطبيق.

المهمة 4: ما هو الغرض من الملف `main.py`؟

حسنًا، حان الوقت لإلقاء نظرة على جوهر الرمز. لنسأل Gemini أن يكون دليلنا. قُل:

What's the purpose of the `main.py` file?

وهنا تبرز أهمية Gemini CLI. سيتم الاتصال أولاً بالرقم ‎read_file في ‎backend/main.py. بعد ذلك، سيحلّل نموذج اللغة المتعدد الوسائط رمز Python البرمجي. سيحدّد أنّها تطبيق FastAPI يوفّر واجهة برمجة تطبيقات REST لتطبيق استطلاع. سيشرح بعد ذلك نقاط نهاية واجهة برمجة التطبيقات ووظائفها. يوفّر عليك ذلك الوقت الذي قد تستغرقه في قراءة كل المعلومات وفهمها بنفسك. يمكنك أيضًا طرح أسئلة متابعة لشرح بعض هذه الوظائف بالتفصيل. أليس هذا رائعًا؟ ننصحك بتجربة ذلك.

5- من المحلية إلى المباشرة! النشر باستخدام Cloud Run وCloud SQL

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

الهدف: نشر تطبيق quickpoll على Cloud Run، مع استخدام قاعدة بيانات PostgreSQL على Cloud SQL كخادم خلفي.

المهمة 1: إنشاء فرع قوي لبياناتنا (إعداد Cloud SQL)

يحتاج كل تطبيق جيد إلى مكان لتخزين الجوز الثمين... أقصد البيانات. سنستخدم Cloud SQL for PostgreSQL. يمكن تشبيهها بحديقة سحرية ذاتية العناية لقاعدة البيانات، ما يتيح لنا التركيز على الأمور الممتعة.

لنطلب من Gemini CLI إنشاء قاعدة بيانات.

Please create a new Cloud SQL for PostgreSQL instance for me in project <myproject>. Call it quickpoll-db and put it in us-central1. Lets use the Development preset for now, and make the root password a-very-secure-password!.

سيبدأ Gemini CLI العمل باستخدام إضافة Cloud SQL. ستظهر لك أداة استدعاء create_instance. يمكنك الموافقة عليه.

بعد إنشاء الجهاز الافتراضي، من المفترض أن تظهر لك نتيجة مشابهة لما يلي:

يمكنك إنشاء ملف ‎ .env يتضمّن متغيّر البيئة أعلاه وتضمينه قبل إعادة تشغيل Gemini CLI، ليتمكّن من الوصول إلى هذه المتغيّرات.

بينما ينمو مثيلنا، لنُجهّز التربة. نحتاج إلى قاعدة بيانات ومستخدم لتطبيقنا.

In the quickpoll-db instance, create a new database named quickpolldb.

سيستخدم Gemini CLI الأداة create_database في إضافة Cloud SQL for PostgreSQL لإنشاء قاعدة البيانات لك.

لنضِف الآن مستخدمًا لإدارة هذا الحساب:

In the quickpoll-db instance, create a built in user named quickpoll-user with the password another-secure-password!.

في هذه المرة، سيستخدم Gemini CLI أداة create_user.

المهمة 2: المسار السري (ربط الخلفية)

يحتاج الخلفية إلى معرفة المسار السري إلى قاعدة البيانات الجديدة. لنلقِ نظرة على ملف backend/main.py لمعرفة كيفية عمله.

show me how would the backend/main.py connect to the database

حقًا! هل رأيت ذلك؟ يستخدم هذا البرنامج Cloud SQL Python Connector ويبحث عن متغيّرات البيئة، مثل CLOUD_SQL_POSTGRES_INSTANCE وCLOUD_SQL_POSTGRES_USER وCLOUD_SQL_POSTGRES_PASSWORD وCLOUD_SQL_POSTGRES_DATABASE. يجب تقديم هذه المعلومات إلى خدمة Cloud Run.

أولاً، نحتاج إلى CLOUD_SQL_POSTGRES_INSTANCE. إنّها مثل مصافحة سرية.

What are the details for the Cloud SQL instance quickpoll-db in us-central1?

ستظهر لك مجموعة من التفاصيل. ابحث عن "اسم الاتصال" وانسخ هذه القيمة. سيبدو على النحو التالي: your-project-id:us-central1:quickpoll-db.

الآن قبل نشر التطبيق على Cloud Run، لننشئ قاعدة البيانات باستخدام الجداول المطلوبة. بعد إنشاء قاعدة بيانات ومستخدم منفصلَين، لنخرج من Gemini CLI ونعدّل ملف ‎ .env الذي أنشأناه سابقًا بالقيم الجديدة:

export CLOUD_SQL_POSTGRES_USER=quickpoll-user
export CLOUD_SQL_POSTGRES_PASSWORD=password-you-provided
export CLOUD_SQL_POSTGRES_DATABASE=quickpolldb

أعِد تشغيل Gemini CLI وأدخِل ما يلي:

execute backend/database.sql file on quickpolldb database as quickpolluser in quickpoll-db instance

لقد أدرك تلقائيًا أنّ الأداة execute_sql لا تتيح تنفيذ أوامر SQL متعددة في طلب واحد. لذلك، تم تنفيذ كل أمر SQL على حدة.

المهمة 3: الخلفية، انطلق! (النشر على Cloud Run)

حان الوقت كي يغادر نظامنا الخلفي العشّ. سنطلب من Gemini نشر مجلد الخلفية على Cloud Run ومنحه المسار السري إلى قاعدة البيانات.

Deploy the backend folder to a new Cloud Run service called quickpoll-be in us-central1. Here are the secrets (environment variables):
CLOUD_SQL_POSTGRES_INSTANCE=your-project-id:us-central1:quickpoll-db
CLOUD_SQL_POSTGRES_USER=quickpoll-user
CLOUD_SQL_POSTGRES_PASSWORD=password-you-provided
CLOUD_SQL_POSTGRES_DATABASE=quickpolldb

سيحزّم Gemini الرمز البرمجي وينشئ صورة حاوية وينشرها على Cloud Run. بعد الانتهاء من ذلك، والذي قد يستغرق بضع دقائق، ستتلقّى عنوان URL لخدمة الخلفية الجديدة الرائعة. احرص على الاحتفاظ بعنوان URL هذا في مكان يسهل الوصول إليه.

المهمة 4: اللمسات الأخيرة (ضبط الواجهة الأمامية ونشرها)

واجهة المستخدم الأمامية هي بمثابة الوجه الودود لتطبيقنا. ويجب أن يعرف مكان العثور على الخلفية. لنخبره إلى أين يتوجّه.

Deploy the frontend folder to a new Cloud Run service called quickpoll-fe in us-central1. Here are the secrets (environment variables):
BACKEND_URL=backend-url

المهمة 5: الكشف الكبير!

هذا كل ما في الأمر. حان وقت الحقيقة! احصل على عنوان URL لخدمة quickpoll-fe وافتحه في متصفّح الويب.

من المفترض أن يظهر تطبيق QuickPoll، وهو جاهز للاستخدام. يمكنك إنشاء استطلاع والتصويت فيه والاطّلاع على النتائج في الوقت الفعلي.

أحسنت! لقد نقلت مشروعًا من جهازك المحلي إلى Google Cloud وأضفيت عليه الحيوية. وقد أنجزت كل ذلك من نافذة الأوامر على جهازك باستخدام مساعدك الموثوق، Gemini CLI.

هذا ما أسمّيه إنتاجية!

6. للمطوّرين: تسريع مراحل تطوير التطبيقات

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

من الفكرة إلى الرمز البرمجي

فكِّر في دورة التطوير النموذجية. الأمر لا يقتصر على كتابة الرمز البرمجي، أليس كذلك؟ ويشمل ذلك إنشاء بنية أساسية وإضافة إجراءات التعامل مع الأخطاء وإعادة تصميم الرمز البرمجي وكتابة الاختبارات. يمكن أن يساعدك Gemini في كل ذلك.

المهام المتكرّرة والنصوص النموذجية: لا داعي للنسخ واللصق

حسنًا، لديك الآن وظائف التطبيق الأساسية. الآن، عليك إضافة تسجيل البيانات والتعامل مع الأخطاء المحتملة، أليس كذلك؟ ويكون ذلك عادةً عبارة عن الكثير من كتل try...except المتكررة. لم يعُد الأمر كذلك. لنبدأ بطلب تحليل الرمز البرمجي من Gemini CLI واقتراح أفضل الممارسات لتسجيل الأخطاء والتعامل مع الاستثناءات:

What are the best practices for error handling and logging that should also be included in this application?

سيحلّل Gemini CLI الملف الحالي ويقدّم بعض الاقتراحات بشأن أفضل الممارسات. يمكن اعتبارها مساعدًا خبيرًا يمكنه توفير وقتك الذي قد تستغرقه في البحث عن هذه المعلومات بنفسك.

لنطلب الآن من "مساعد Google" تنفيذ هذه الاقتراحات نيابةً عنك:

please go ahead and implement these in the existing app

قد يختلف الناتج الفعلي في حالتك، ولكن في النهاية يجب أن تظهر لك تفاصيل التغييرات التي تم إجراؤها. على سبيل المثال، في لقطة الشاشة أدناه، يمكنك ملاحظة أنّه تمت إضافة structlog لإنشاء سجلّات بتنسيق JSON، وتنفيذ معالجة مركزية للأخطاء، وتحسين طريقة تسجيل استجابات الطلبات. فكِّر في كل الكتابة التي وفّرتها على نفسك!

Refactoring: Your Personal Code Reviewer

نريد جميعًا كتابة تعليمات برمجية واضحة وفعّالة. لكن في بعض الأحيان، نكون على عجلة من أمرنا. كأنّه مراجعك الشخصي للرمز البرمجي. يمكنك طرح أسئلة مثل:

please perform a comprehensive code review for best practices and security

يفهم Gemini أفضل الممارسات الخاصة بكل لغة. مرة أخرى، قد يختلف الناتج الفعلي في حالتك عن لقطات الشاشة أعلاه، ولكن إذا قرأت الناتج، ستلاحظ مستوى التفاصيل الذي وصل إليه Gemini CLI لتحليل الرمز البرمجي. فهي تساعدك على تعلُّم التعليمات البرمجية وتحسينها في الوقت نفسه.

إنشاء الاختبار: الجزء الأفضل!

هذه هي الحيلة المفضّلة لديّ! ندرك جميعًا أنّه يجب كتابة اختبارات، ولكن قد يكون ذلك مملًا، خاصةً عندما يكون عليك محاكاة بعض العناصر. شاهدوا ما يلي. يمكنك ببساطة طرح السؤال التالي:

Add a test suite to this application

سيحلّل Gemini الدالة ويحدّد مدخلاتها ومخرجاتها، كما سيحدّد العناصر التي تعتمد عليها. بعد ذلك، سيتم إنشاء ملف test_main.py كامل يتضمّن عدة حالات اختبار، بما في ذلك "المسار السعيد" وربما حالة خطأ. هذا تحسّن كبير في الإنتاجية.

إجراء الاختبارات (مهمة تحدٍّ لك)

الآن، ستبدأ الإثارة الحقيقية. سأترك هذا الجزء كتحدٍّ لك لاستكشافه بشكل مستقل. يمكنك أن تطلب من Gemini CLI تنفيذ حالات الاختبار التي أنشأها. بعد ذلك، ما عليك سوى الاسترخاء ومشاهدة السحر وهو يتجلّى أمامك.

7. ما وراء Localhost: الدمج مع GitHub

لقد أنجزنا بعض الأعمال الرائعة على جهازنا المحلي، وهو ركننا الصغير في الغابة. لكنّ الميزة الحقيقية للسحابة الإلكترونية هي التعاون والتواصل. حان الوقت للانطلاق واستكشاف كيف يمكن لـ Gemini التفاعل مع العالم الأوسع، بدءًا من أكبر شجرة في غابة المطوّرين: GitHub.

المفهوم: مساعد DevOps المدمج

حتى الآن، استخدمنا Gemini كشريك محلي في البرمجة. سنرقّي هذه الميزة الآن إلى مساعد متكامل لتطوير البرامج وعملياتها. ويعود الفضل في ذلك إلى عملية دمج بروتوكول Model Context Protocol ‏ (MCP). هذا الاسم يبدو معقّدًا، ولكنّه يعني ببساطة أنّ Gemini يمكنه التفاعل بأمان مع خدمات أخرى نيابةً عنك، وأول خدمة سنتقنها هي GitHub.

فكِّر في الأمر. كم مرة تضطر إلى مغادرة نافذة الأوامر للتحقّق من طلب سحب أو إنشاء مشكلة أو تصفّح مستودع على GitHub؟ هذا يعني المزيد من التبديل بين السياقات. باستخدام مجموعة أدوات github، يمكنك تنفيذ كل ذلك مباشرةً من هنا. يحوّل Gemini إلى واجهة أصلية لـ GitHub.

تقدّم المستندات الرسمية لخادم MCP على GitHub إرشادات وافية بشأن الأدوات وخيارات الإعداد المتاحة. يمكنك الاختيار بين التشغيل المحلي أو البعيد، إذ إنّ Gemini CLI يتيح بالكامل استخدام خوادم MCP البعيدة.

سيرشدك هذا البرنامج التعليمي إلى كيفية إعداد خيار خادم MCP البعيد في GitHub. أولاً، ستحتاج إلى رمز دخول شخصي (PAT) من GitHub.

بعد الحصول على رمز PAT، حان الوقت لإضافة عنصر خادم MCP إلى ملف settings.json. يظهر ملف settings.json الكامل أدناه، ولكن يمكنك ببساطة التأكّد من أنّ عنصر mcpServers يطابق ما تراه هنا:

{
  "security": {
    "auth": {
      "selectedType": "vertex-ai"
    }
  },
 "mcpServers": {
    "github": {
      "httpUrl": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "GITHUB_PAT"
      },
      "timeout": 5000
    }
  }
}

بعد تعديل ملف settings.json باستخدام إعدادات خادم MCP على GitHub، ما عليك سوى إعادة تشغيل Gemini CLI أو تنفيذ الأمر /mcp refresh. توضّح لقطة الشاشة أدناه خادم GitHub MCP الذي تم إعداده الآن على نظامي، وتعرض مجموعة الأدوات الفعّالة التي يمكن أن تستخدمها أداة Gemini CLI الآن مع بروتوكول Model Context Protocol.

عرض لأهم الأوامر

يأتي Gemini مزوّدًا بمجموعة جديدة من الميزات الفائقة المصمّمة خصيصًا لمنصة GitHub. في ما يلي بعض من الأغاني المفضّلة لديّ:

github.list_repositories: هل تريد الاطّلاع على جميع المستودعات في مؤسستك بدون فتح متصفّح؟ هذه هي الأداة المناسبة لك. ما عليك سوى طرح السؤال "أدرِج جميع المستودعات في مؤسستي".
github.create_issue: هل عثرت على خطأ؟ لا تبدّل النوافذ لإنشاء مشكلة. يمكنك ببساطة أن تطلب من Gemini إنشاء مشكلة في مستودع sample-flask-app بعنوان "إصلاح خطأ تسجيل الدخول" مع هذا الوصف..." وها هي المشكلة تم إنشاؤها.
github.get_pull_request: هل تحتاج إلى الاطّلاع على طلب علاقات عامة؟ يمكنك طرح السؤال التالي: "أريد الاطّلاع على تفاصيل طلب السحب رقم 42 في مستودع sample-flask-app". سيجلب Gemini العنوان والوصف والحالة ومعلومات عن المراجعين.
github.get_file_contents: هذا الفيديو رائع جدًا. يمكنك قراءة ملف من مستودع بعيد بدون الحاجة إلى استنساخه أولاً. وهي رائعة للتحقّق بسرعة من ملف إعداد أو ملف README لمشروع غير متوفّر لديك محليًا.

8. استكشاف GitHub

كفى حديثًا، هيا بنا نُحلّق! سنستخدم ميزات GitHub الجديدة لاستكشاف مؤسسة ومشروع، وكل ذلك من خلال نافذة الأوامر.

الهدف: استخدام Gemini لاستكشاف مشروع مستضاف على GitHub وفهمه

السيناريو: عليك التعرّف على مشروع على GitHub لم يسبق لك العمل عليه.

المهمة 1: إدراج المستودعات في مؤسسة

لنبدأ أولاً بعرض جميع المشاريع في مؤسسة GitHub. بالنسبة إلى هذا المختبر، يمكنك استخدام اسم مستخدم GitHub الخاص بك أو مؤسسة تنتمي إليها. لنطلب من Gemini إدراجها.

List the repositories in the `[your-org-or-username]` GitHub organization.

(يُرجى تذكُّر استبدال [your-org-or-username] بمعلوماتك الفعلية). سيستخدم Gemini الأداة github.list_repositories ويعرض لك قائمة بجميع المشاريع. رائع!

المهمة 2: العثور على مستودع معيّن

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

المهمة 3: إدراج طلبات السحب المفتوحة

بعد أن حدّدنا المستودع المستهدف، لنرَ ما يحدث فيه. هل هناك أي طلبات سحب مفتوحة؟ لنطرح السؤال التالي:

List the open pull requests for the `quickpoll` repository in the `[your-org-or-username]` organization.

سيستخدم Gemini أداة github.list_pull_requests، مع الفلترة حسب الولاية open. بعد ذلك، سيتم إدراج أي طلبات سحب مفتوحة، مع عرض رقم طلب السحب والعنوان والشخص الذي أنشأه. هذه هي طريقة العرض الفورية لعملية التطوير النشطة للمشروع. يمكنك تجربة ذلك باستخدام مستودع تساهم فيه بشكل نشط والتحقّق من النتائج.

المهمة 4: التحقيق في طلب سحب

لنفترض أنّ هناك طلب دمج مثيرًا للاهتمام في تلك القائمة. نريد معرفة المزيد عن ذلك. نريد الاطّلاع على الوصف والملفات التي تم تغييرها. اختَر رقم طلب تغيير من القائمة (يمكنك تخطّي هذه الخطوة إذا لم يكن هناك أي طلب، ولكن لنفترض أنّ هناك طلبًا واحدًا).

Show me the details and files changed in PR number 1 in the `quickpoll` repo.

هذا مثال رائع على مهمة متعددة الخطوات يمكن أن يساعدك فيها Gemini. أولاً، من المرجّح أن تستخدم github.get_pull_request لجلب التفاصيل الرئيسية، مثل العنوان والنص والمؤلف وما إلى ذلك. ثم، للحصول على تغييرات الملف، ستستخدم أداة ثانية، وهي github.get_pull_request_files. بعد ذلك، سيتم دمج كل هذه المعلومات في ملخّص بسيط وواضح. لقد راجعت للتوّ طلب سحب بدون مغادرة نافذة الأوامر. أليس هذا رائعًا؟

9- من مستند متطلبات المنتج إلى عملية الإيداع الأولية

لقد تعلّمت كيفية الاستكشاف والإنشاء والاختبار. الآن، سنطبّق كل ما تعلّمناه في سيناريو من العالم الواقعي. هذه هي اللحظة التي نحول فيها خطة إلى منتج. سننتقل من مستند متطلبات المنتج (PRD) إلى أول عملية إيداع. لنبدأ العمل على مشروع رائع.

الهدف: محاكاة مهمة تطوير في العالم الحقيقي من البداية إلى النهاية، مع الجمع بين السياق المحلي والسياق البعيد

السيناريو: تم تعيين ميزة جديدة لك. تنتظرك المتطلبات في ملف PRD داخل مستودع GitHub الخاص بالمشروع.

المهمة 1: الفهم - قراءة مستند متطلبات المنتج

هذه هي الخطوة الأكثر أهمية. قبل التفكير في كتابة سطر واحد من الرموز البرمجية، عليك فهم الخطة تمامًا. تتضمّن متطلبات ميزتنا الجديدة الملف prd/NEW_FEATURE.md. لنفتحها ونرى ما بداخلها.

explain the requirements mentioned in prd/NEW_FEATURE.md

سيستخدم Gemini CLI الدالة read_file لعرض محتوى مستند متطلبات المنتج. لنبدأ. ستوضّح هذه الرسالة الميزة الجديدة: زر "إعادة تحميل" يتيح للمستخدمين تعديل قائمة الاستطلاعات النشطة يدويًا. يجب الرجوع إلى المخطط دائمًا.

المهمة 2: الرمز البرمجي - تحويل المتطلبات إلى واقع

هذه هي اللحظة السحرية! سنأخذ المتطلبات من مستند متطلبات المنتج ونطلب من Gemini كتابة الرمز البرمجي نيابةً عنّا. لنكن أكثر تحديدًا ونخبره بالضبط بما نريده.

Implement the changes as per the PRD

سيبدأ Gemini CLI العمل، وبعد لحظة، ستظهر لك نتيجة مشابهة لما يلي. أصبح رمزنا الجديد الرائع متوفّرًا الآن!

المهمة 3: التحقّق من التغييرات

لقد أنشأنا ملفًا جديدًا يتضمّن رمزًا جديدًا. الخطوة الأخيرة في هذا المختبر هي نشر التغيير على Cloud Run والتحقّق منه.

let's deploy the changes made to frontend to Cloud Run. The existing service on Cloud Run is quickpoll-fe in us-central1.

لاحظ كيف قدّم هذا الطلب تفاصيل إضافية، مثل اسم خدمة Cloud Run الحالية ومنطقة نشرها. يساعدك تحديد التفاصيل في توفير الوقت، مع أنّ Gemini CLI سيطلب منك دائمًا تقديم أي تفاصيل ناقصة إذا لم تذكرها.

إذا واجهت خدمتك المعدَّلة على Cloud Run خطأً، ما عليك سوى أن تطلب من Gemini CLI تصحيح الأخطاء في الرمز البرمجي. تذكَّر أنّها رفيقك الخارق.

10. تهانينا

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