Agentverse - The Shadowblade's Codex - Vibecoding with Gemini CLI

1. Overture

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

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

هذه ورشة العمل هي دليل المؤسسات النهائي لإتقان مستقبل الذكاء الاصطناعي الوكيل على Google Cloud. نقدّم لك خارطة طريق شاملة ترشدك من الفكرة الأولى إلى التنفيذ الكامل على نطاق واسع. خلال هذه التمارين المعملية الأربعة المترابطة، ستتعرّف على كيفية التقاء المهارات المتخصّصة لكل من المطوّر والمعماري ومهندس البيانات ومهندس موثوقية الموقع (SRE) لإنشاء Agentverse قوي وإدارته وتوسيع نطاقه.

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

مرحبًا بك في The Agentverse: دعوة إلى الأبطال

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

يُعرف هذا النظام المتكامل من القوة والإمكانات باسم Agentverse.

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

وهي تضخّم الإحباطات القديمة إلى أشكال وحشية، ما يؤدي إلى ظهور "الأشباح السبعة للتطوير". إذا لم يتم التحقّق من ذلك، سيؤدي ذلك إلى توقّف التقدّم في The Static and its Spectres، ما سيحوّل وعد Agentverse إلى أرض قاحلة من الديون الفنية والمشاريع المهجورة.

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

اختيار صفك

تتوفّر لك أربعة مسارات مختلفة، كل منها يمثّل ركيزة أساسية في المعركة ضد الجمود. على الرغم من أنّ تدريبك سيكون مهمة فردية، إلا أنّ نجاحك النهائي يعتمد على فهم كيفية دمج مهاراتك مع مهارات الآخرين.

• The Shadowblade (المطوّر): هو خبير في الحدادة والخطوط الأمامية. أنت الحِرفي الذي يصنع الشفرات ويبني الأدوات ويواجه العدو في التفاصيل المعقّدة للرمز. مسارك هو مسار الدقة والمهارة والإبداع العملي.
• المستدعي (المهندس المعماري): هو استراتيجي ومنظّم بارع. لا ترى عميلاً واحدًا، بل ساحة المعركة بأكملها. يمكنك تصميم المخططات الرئيسية التي تتيح لأنظمة الوكلاء بأكملها التواصل والتعاون وتحقيق هدف أكبر بكثير من أي مكوّن فردي.
• الباحث (مهندس البيانات): هو شخص يبحث عن الحقائق المخفية ويحتفظ بالمعرفة. تخوض مغامرة في البرية الشاسعة وغير المروَّضة من البيانات للكشف عن الذكاء الذي يمنح وكلاءك هدفًا وبصيرة. يمكن أن تكشف معلوماتك عن نقاط ضعف العدو أو تعزّز قوة حليفك.
• الحارس (التطوير والعمليات / هندسة موثوقية المواقع الإلكترونية): هو الحامي والدرع الثابت للمملكة. عليك بناء الحصون وإدارة خطوط إمداد الطاقة والتأكّد من أنّ النظام بأكمله يمكنه مقاومة هجمات "الكهرباء الساكنة" الحتمية. قوتك هي الأساس الذي يُبنى عليه فوز فريقك.

مهمتك

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

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

تحدٍّ نهائي تعاوني سيختبر قوتك المجمّعة ويحدّد مصير Agentverse.

إنّ Agentverse في انتظار أبطاله. هل ستلبي النداء؟

2. The Shadowblade's Codex

يقع كتاب Shadowblade مفتوحًا أمامك. الردّ على المكالمة يواجه عالم Agentverse خطرًا يتمثل في الفوضى الزاحفة التي يسببها The Static، ولا يمكن لأحد التصدي لهذا الخطر سوى من يتقن التقنيات الواردة في هذا الكتاب. هذا هو طريق الدقة والانضباط. تبدأ تدريباتك اليوم. ستتعلّم كيفية استخدام الذكاء الاصطناعي ليس كأداة بسيطة، بل كسيف ذكي يجب ترويضه وإتقان استخدامه. اتّبِع التعليمات الواردة هنا، وستصنع سلاحًا من المنطق الخالص، وهو عبارة عن برنامج ذكي، مُحسَّن وجاهز للمعركة.

أهداف الدورة التعليمية

• استخدِم سلاحك الأساسي: Gemini CLI.
• يمكنك توسيع مجموعة أدواتك باستخدام إضافات Gemini CLI ومهارات الوكيل.
• استدعِ ترسانات خارجية من خلال دمج أدوات MCP مع Gemini CLI.
• عبِّر عن نيتك من خلال "أسلوب" باستخدام مستندات التصميم لتوجيه شريكك من الذكاء الاصطناعي.
• يمكنك إنشاء حلّ نظيف ومقسَّم إلى وحدات من خلال إنشاء أول وكيل مستقل باستخدام حزمة Agent Development Kit (ADK).
• يمكنك كتابة رموز برمجية لاعتراض سلوك الوكيل وحمايته.
• إنشاء مجموعات تقييم آلي لاختبار صحة عمل برنامجك
• أنشئ مسار CI كاملاً لاختبار الوكيل وتضمينه في حاوية وأرشفته تلقائيًا.

3- تجهيز "ساحة التدريب"

المطالبة برصيدك في Google Cloud

⚠️ المتطلبات الأساسية المهمة:

• استخدام حساب Gmail شخصي: يجب استخدام حساب شخصي (مثل [e-mail])، ولن تعمل الحسابات التي تديرها الشركات أو المؤسسات التعليمية.

👉 الخطوات:

1. الانتقال إلى الموقع الإلكتروني للمطالبة بالرصيد: انقر هنا
2. تسجيل الدخول: الصِق الرابط في شريط العناوين وسجِّل الدخول باستخدام حسابك الشخصي على Gmail.
3. قبول البنود: وافِق على بنود خدمة Google Cloud Platform.
4. التحقّق من الرصيد: ابحث عن رسالة تؤكّد أنّه تم تطبيق الرصيد.
   • *ملاحظة: إذا طُلب منك إدخال معلومات بطاقة الائتمان، يمكنك تجاهل الطلب وإغلاق النافذة بأمان.

يمكنك الآن إغلاق النافذة.

إعداد بيئة العمل

👉انقر على "تفعيل Cloud Shell" في أعلى "وحدة تحكّم Google Cloud" (إنّه الرمز على شكل نافذة طرفية في أعلى لوحة Cloud Shell)،

👉انقر على الزر "فتح المحرّر" (يبدو كملف مفتوح مع قلم رصاص). سيؤدي ذلك إلى فتح "محرِّر Cloud Shell للرموز" في النافذة. سيظهر لك مستكشف الملفات على الجانب الأيمن.

👉افتح المحطة الطرفية في بيئة التطوير المتكاملة المستندة إلى السحابة الإلكترونية.

👉💻 في نافذة الوحدة الطرفية، تأكَّد من أنّك قد أثبتّ هويتك وأنّ المشروع مضبوط على رقم تعريف مشروعك باستخدام الأمر التالي:

gcloud auth list

👉💻 استنسِخ مشروع bootstrap من GitHub:

git clone https://github.com/weimeilin79/agentverse-developer.git
chmod +x ~/agentverse-developer/gitea.sh
chmod +x ~/agentverse-developer/init.sh
chmod +x ~/agentverse-developer/set_env.sh

git clone https://github.com/weimeilin79/agentverse-dungeon.git
chmod +x ~/agentverse-dungeon/run_cloudbuild.sh
chmod +x ~/agentverse-dungeon/start.sh

👉💻 شغِّل نص الإعداد البرمجي من دليل المشروع.

⚠️ ملاحظة حول معرّف المشروع: سيقترح النص البرمجي معرّف مشروع تلقائيًا تم إنشاؤه عشوائيًا. يمكنك الضغط على Enter لقبول هذا الإعداد التلقائي.

ومع ذلك، إذا كنت تفضّل إنشاء مشروع جديد محدّد، يمكنك كتابة رقم تعريف المشروع المطلوب عندما يطلب منك النص البرمجي ذلك.

cd ~/agentverse-developer
./init.sh

سيتولّى النص البرمجي باقي عملية الإعداد تلقائيًا.

👉 خطوة مهمة بعد الإكمال: بعد انتهاء تنفيذ النص البرمجي، عليك التأكّد من أنّ Google Cloud Console يعرض المشروع الصحيح:

1. انتقِل إلى console.cloud.google.com.
2. انقر على القائمة المنسدلة الخاصة بأداة اختيار المشروع في أعلى الصفحة.
3. انقر على علامة التبويب "الكل" (لأنّ المشروع الجديد قد لا يظهر في "الأحدث" بعد).
4. اختَر رقم تعريف المشروع الذي أعددته للتو في الخطوة init.sh.

👉💻 العودة إلى Terminal اضبط معرّف المشروع المطلوب:

gcloud config set project $(cat ~/project_id.txt) --quiet

👉💻 شغِّل الأمر التالي لتفعيل واجهات Google Cloud APIs اللازمة:

gcloud services enable  compute.googleapis.com \
                        artifactregistry.googleapis.com \
                        run.googleapis.com \
                        cloudfunctions.googleapis.com \
                        cloudbuild.googleapis.com \
                        iam.googleapis.com \
                        aiplatform.googleapis.com \
                        cloudresourcemanager.googleapis.com

👉💻 إذا لم يسبق لك إنشاء مستودع Artifact Registry باسم agentverse-repo، نفِّذ الأمر التالي لإنشائه:

. ~/agentverse-developer/set_env.sh
gcloud artifacts repositories create $REPO_NAME \
    --repository-format=docker \
    --location=$REGION \
    --description="Repository for Agentverse agents"

إعداد الإذن

👉💻 امنح الأذونات اللازمة من خلال تنفيذ الأوامر التالية في الوحدة الطرفية:

. ~/agentverse-developer/set_env.sh

# Artifact Registry Admin
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
  --role="roles/artifactregistry.admin"

# Cloud Build Editor
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
  --role="roles/cloudbuild.builds.editor"

# Cloud Run Admin
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
  --role="roles/run.admin"

# IAM Service Account User
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
  --role="roles/iam.serviceAccountUser"

# Vertex AI User
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
  --role="roles/aiplatform.user"

# Logging Writer (to allow writing logs)
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
  --role="roles/logging.logWriter"


gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
  --role="roles/logging.viewer"

👉💻 عند بدء التدريب، سنجهّز التحدي النهائي. تستدعي الأوامر التالية الأشباح من التشويش الفوضوي، ما يؤدي إلى إنشاء الزعماء لاختبارك.

. ~/agentverse-developer/set_env.sh
cd ~/agentverse-dungeon
./run_cloudbuild.sh

npm update -g @google/gemini-cli

4. إتقان سلاحك الأساسي: مقدّمة عن Gemini CLI

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

إنّ Gemini Command Line Interface (CLI) ليس مجرد أداة، بل هو امتداد لإرادتك. يعمل وكيل الذكاء الاصطناعي المفتوح المصدر هذا، المستند إلى نماذج Gemini، على حلقة "الاستدلال والتنفيذ" (ReAct). ويحلّل نيتك ويختار الأسلوب المناسب وينفّذه ويراقب النتيجة لإكمال المهام المعقّدة. قبل أن تتمكّن من استخدام أسلحة أكثر تخصصًا، عليك إتقان هذا السلاح الأساسي.

بدء استخدام Gemini CLI

👉💻 ادخل إلى ساحة التدريب واستلّ سلاحك. في نافذة Cloud Shell، انتقِل إلى مستودعك الشخصي.

cd ~/agentverse-developer
mkdir tabletop
cd tabletop

👉💻 استدعاء Gemini للمرة الأولى سيرشدك خلال عملية التكيّف الأولية.

clear
gemini 

إذا طُرح عليك السؤال Do you want to connect Cloud Shell editor to Gemini CLI?، اختَر لا.

التعرّف على الأسلحة

يعرف كل حرفي ماهر أدواته جيدًا. عليك تعلُّم التقنيات الأساسية لسلاحك قبل مواجهة عدو حقيقي.

👉✨ تحتوي كل أداة مسحورة على أحرف رونية تصف قوتها. يمكنك الاطّلاع عليها الآن. في طلب مُوجَّه إلى Gemini، اكتب ما يلي:

/help

اطّلِع على قائمة الأوامر. هذه هي تقنياتك الأساسية لإدارة الذاكرة (focus) والمحادثة (chat) والأسلحة الخارجية (tools)، وهي دليل القتال الخاص بك.

👉✨ سلاحك متناغم مع بيئته، ما يتيح لك التلاعب بساحة المعركة مباشرةً. أصدر أمرًا إلى العالم خارج الشفرة:

!ls -l

‫👉✨ يمتلك Gemini CLI مجموعة من القدرات المضمّنة. لفحصها، اتّبِع الخطوات التالية:

/tools

ستظهر لك قائمة تتضمّن ReadFile وWriteFile وGoogleSearch. هذه هي الأساليب التلقائية التي يمكنك الاستعانة بها بدون الحاجة إلى استخدام أدوات خارجية.

👉✨ يمكن أيضًا تحسين شفرتك باستخدام الإضافات، وهي تحسينات مُعدّة مسبقًا أنشأها خبراء آخرون وتتضمّن أدوات وأوامر وسياقًا في وحدة واحدة قابلة للتثبيت. افحص الإضافات التي تتوافق حاليًا مع شفرتك:

/extensions list

قد تكون القائمة فارغة في الوقت الحالي لأنّك لم تثبِّت أي إضافات بعد. ستستدعي الإضافة الأولى لاحقًا، عندما يتطلّب تدريبك قوة إنشاء الصور.

👉✨ بالإضافة إلى الإضافات، قام الخبراء المهرة بتدوين خبراتهم في مهارات الوكيل، وهي مخطوطات عند الطلب تتضمّن معرفة متخصّصة. تحقَّق من المهارات التي يمكن أن يكتشفها شفرتك:

/skills list

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

👉✨ لا يكون السلاح فعّالاً إلا إذا تم استخدامه بشكل صحيح. يمكن أن يتضمّن Gemini Blade "إدراكًا تكتيكيًا" (سياقًا) لتوجيه إجراءاته.

/memory show

وهي فارغة حاليًا.

👉✨ سجِّل البيانات التكتيكية التالية في ذاكرته:

/memory add "The Shadowblade's primary foe is The Static."

نفِّذ الأمر /memory show مرة أخرى للتأكّد من أنّ السكين قد استوعب هذه المعلومات.

👉✨ ليكون سلاحك فعّالاً، يجب أن يفهم المهمة. يطلب الرمز @ من النصل تحليل المعلومات. أولاً، أنشئ ملفًا موجزًا للمهمة:

!echo "## Mission Objective: Defeat the Seven Spectres" > mission.md

👉✨الآن، اطلب من Gemini CLI تحليل الموجز وإعداد تقرير بالنتائج التي توصل إليها:

Explain the contents of the file @mission.md

سلاحك الأساسي على دراية الآن بهدفه.

👉💻 اضغط على Ctrl+C مرّتين للخروج من Gemini CLI

5- تحليل ساحة المعركة: تفاعل عملي مع البرمجة الوصفية

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

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

تحديد هوية صانع المحتوى

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

👉💻 إذا أغلقت Gemini CLI في القسم السابق، احرص على إعادة تشغيله من خلال تنفيذ الأمر التالي في نافذة الأوامر:

clear
cd ~/agentverse-developer/tabletop
gemini 

👉✨ باستخدام أمر واحد وفعّال، يمكنك توجيه Gemini CLI لإنشاء أساس هويتك الرقمية:

In the current folder, create a personal profile website for a hero codenamed 'Shadowblade'. The design must be a dark, futuristic theme with electric blue accents. All code must be in separate index.html and styles.css files. The layout must use CSS Flexbox for a two-column design. All generated code must be clean, well-commented, and professional. Make sure you have a placeholder spot for profile picture. Do not attempt to start the server.

لقد حسب Gemini تسلسل الإجراءات المطلوبة.

👉💻 اضغط على Ctrl+C مرتين للخروج من Gemini CLI وتنفيذ الأمر التالي في الوحدة الطرفية.*

python -m http.server

👀 لإلقاء نظرة على عملك، انقر على رمز معاينة الويب في شريط أدوات Cloud Shell. انقر على تغيير المنفذ، واضبطه على 8000، ثم انقر على تغيير ومعاينة. ستظهر معاينة لموقعك الإلكتروني.

قد يبدو موقعك الإلكتروني مختلفًا عن موقعي. هذه هي علامتك التجارية الفريدة.

تم الآن تحسين أسلوب توقيعك، ولم يعُد من الضروري إجراء المحاكاة المباشرة. أمر Blade بالتوقف.

👉💻 اضغط على Ctrl+C للخروج من خادم http.

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

تفعيل ترسانتك المحلية: مستودع Gitea

لا يتم إطلاق العنان لقدرات "سيد الظلال" الحقيقية من خلال مهاراته الشخصية فحسب، بل من خلال جودة ترسانته أيضًا. عليك الآن تفعيل حامل الأسلحة المحلي، أي خادم Gitea، وتكييف سيفك مع قوته. يتم ربط هذه المجموعة بأداة Gemini CLI من خلال خادم بروتوكول سياق النموذج (MCP)، وهو بوابة متخصصة تتيح لأداة الذكاء الاصطناعي التفاعل مع الأدوات والخدمات الخارجية، ما يحوّل نافذة الأوامر إلى مساحة عمل ذكية وموجّهة نحو الإجراءات.

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

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

لنبدأ باستدعاء أول وأهم قطعة في ترسانتك الجديدة، وهي مستودع الأسلحة نفسه.

👉💻 في الوحدة الطرفية، نفِّذ نص التفعيل البرمجي لاستدعاء مستودع الأسلحة:

cd ~/agentverse-developer
./gitea.sh

يعمل هذا النص البرمجي على تنشيط حاوية Gitea وفتح بوابة MCP، ما يسمح لـ Gemini بإدراكها والتفاعل معها.

👉 لفحص ترسانتك الجديدة، عليك إلقاء نظرة على معاينة الويب.

👉 من رمز معاينة الويب في شريط أدوات Cloud Shell، انقر على تغيير المنفذ واضبطه على 3005.

👉 ستظهر صفحة تسجيل الدخول إلى Gitea. أدخِل مستودع الأسلحة باستخدام التعويذة: * اسم المستخدم: dev * كلمة المرور: dev

👉💻 لا يمكن لـ Gemini CLI حتى الآن رؤية هذه المجموعة الجديدة من الأدوات. يجب إجراء عملية ضبط دقيق، وذلك عن طريق كتابة موقع مستودع الأسلحة على رموز الإعداد في Gemini CLI (settings.json). في نافذة الأوامر، نفِّذ ما يلي:

if [ ! -f ~/.gemini/settings.json ]; then
  # If file does not exist, create it with the specified content
  echo '{"mcpServers":{"gitea":{"url":"http://localhost:8085/sse"}}}' > ~/.gemini/settings.json
else
  # If file exists, merge the new data into it
  jq '. * {"mcpServers":{"gitea":{"url":"http://localhost:8085/sse"}}}' ~/.gemini/settings.json > tmp.json && mv tmp.json ~/.gemini/settings.json
fi &&
cat ~/.gemini/settings.json

👀 ملف settings.json هو ملف الإعدادات المركزي لـ Gemini CLI، وهو بمثابة كتاب الإعدادات المفضّلة والقدرات. وهي تحدّد طريقة عمل واجهة سطر الأوامر ومظهرها، والأهم من ذلك، الصلاحيات الخارجية التي يمكنها الاستفادة منها. يقع هذا الملف عادةً في دليل المنزل على ~/.gemini/settings.json، ويطبّق قواعده على جميع مشاريعك. ومع ذلك، يمكنك أيضًا إنشاء ملفات settings.json خاصة بالمشروع داخل دليل .gemini في مجلد مشروعك لتجاوز الإعدادات العامة.

"mcpServers": {
  "gitea": {
    "url": "http://localhost:8085/sse"
  }
}

يُعلم هذا الإعداد Gemini بأنّ "مجموعة الأدوات المسماة gitea نشطة وتستمع إلى الطلبات على عنوان الشبكة المحدّد هذا".

👉💻 أعِد إدخال Gemini CLI. في الوحدة الطرفية، شغِّل الأمر التالي:

clear
cd ~/agentverse-developer/tabletop/
gemini 

👉✨ تأكَّد من أنّ السلاح الجديد قد تم اكتشافه. اطلب منه إدراج جميع المستودعات المتاحة من خلال بوابات MCP:

/mcp

يُفترض أن يظهر لك الآن gitea وقائمة التقنيات المتاحة. تمت مزامنة الشفرة.

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

Create a new repository named 'shadowblade-profile'. The description should be 'The Maker's Mark and digital identity for the Shadowblade operative.' I will push my own files later, so do not create any content.

ارجِع إلى واجهة الويب في Gitea وأعِد تحميلها. سيظهر لك أنّه تم إنشاء مستودع shadowblade-profile جديد لك.

بعد إعداد الحافظة، يمكنك تأمين عملك. أصدر أمرًا إلى Gemini لتثبيت ملفات موقعك الإلكتروني الخاص بملفك الشخصي.

👉💻أدخِل الأمر النهائي لهذه التقنية في Gemini CLI:

Using the Gitea tool, push the index.html and styles.css files to the 'shadowblade-profile' repository.

يتحقّق المحترف من عمله. ارجع إلى علامة التبويب Gitea وأعِد تحميل صفحة المستودع. تمت أرشفة index.html وstyles.css بأمان.

👉✨ يتم تعريف Shadowblade من خلال الختم السحري، ولكن كما تتذكر، يفتقد موقعك الإلكتروني صورة الملف الشخصي. يعترف الحرفي الماهر بعيوبه من أجل إتقانها. عليك تسجيل هذا العيب في سجلات مستودع الأسلحة.

File an issue for me in the shadowblade-profile repo. The issue is that the profile image is missing.

عرض المشكلة في Gitea

لصنع الختم الناقص، عليك استدعاء نوع مختلف من القوة، وهو روح الخلق القادرة على إنشاء صور من الفكر الخالص. في قسم Gitea، عدّلت رموز الإعداد يدويًا لضبط شفرتك على خادم MCP، وهو ما يُعرف باسم طريقة "البيانات الأولية". سنتعرّف الآن على التقنية الحديثة: إضافات Gemini CLI.

الإضافة هي سحر مُعدّ مسبقًا يجمع خوادم MCP والأوامر المخصّصة والسياق والإعدادات في وحدة واحدة قابلة للتثبيت. يحلّ أمر واحد محلّ عشرات أسطر الإعداد اليدوي.

👉💻 اضغط على Ctrl+C مرّتين للخروج من Gemini CLI

قبل استدعاء روح الخلق، عليك أولاً إطلاق قوتها في عالمك. يستخدم تطبيق Nano Banana الإضافي Generative Language API، وهي بوابة منفصلة عن خدمات Vertex AI التي كنت تستخدمها. يجب تفعيل هذه البوابة وإنشاء مفتاح فريد لمنح الروح إذن الوصول.

👉💻 في نافذة Terminal، فعِّل واجهة برمجة التطبيقات:

gcloud services enable generativelanguage.googleapis.com

👉💻 الآن، أنشئ مفتاح واجهة برمجة التطبيقات، وهو رمز الدخول الشخصي الخاص بالروح:

1. انتقِل إلى صفحة "بيانات الاعتماد" في Google Cloud Console.
2. انقر على + إنشاء بيانات اعتماد في أعلى الصفحة، ثمّ اختَر مفتاح API.
3. أطلِق على مفتاح واجهة برمجة التطبيقات اسمًا مميزًا، مثل Generative Language API Key.
4. في القائمة المنسدلة "قيود واجهة برمجة التطبيقات"، اختَر Generative Language API.
5. إنشاء المفتاح ونسخه: ستحتاج إليه في الخطوة التالية.

👉💻 ثبِّت إضافة Nano Banana، وهي أداة إبداعية تستند إلى نماذج Gemini المتخصصة من Google لتحويل النص إلى صورة. في الوحدة الطرفية، شغِّل الأمر التالي:

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

عندما يُطلب منك إدخال مفتاح واجهة برمجة التطبيقات، الصِق المفتاح الذي أنشأته للتو واضغط على Enter.

👉💻 يجب إجراء عملية ضبط نهائية. توجّه بيئة Cloud Shell تلقائيًا جميع طلبات الذكاء الاصطناعي من خلال Vertex AI، ولكنّ روح الإبداع تتحدث من خلال بوابة مختلفة. نفِّذ الأمر التالي لضبط بوابة الإضافة بشكل صحيح:

NANO_CONFIG=$(find ~/.gemini/extensions -name "gemini-extension.json" -path "*nanobanana*" 2>/dev/null | head -1) && \
jq '.mcpServers.nanobanana.env.GOOGLE_GENAI_USE_VERTEXAI = ""' "$NANO_CONFIG" > /tmp/nb_tmp.json && \
mv /tmp/nb_tmp.json "$NANO_CONFIG"

نفّذ هذا الأمر الفردي كل ما يلي: تنزيل خادم MCP وتسجيل أدواته وتثبيت أوامر مخصّصة تبدأ بشرطة مائلة، وكل ذلك بدون أن تلمس settings.json.

👀 ملاحظة من المطوّر: الإضافات مقابل خوادم MCP الأولية قارِن ذلك بإعداد Gitea. في هذه الحالة، نفّذت يدويًا الأمر jq لإدخال عنوان URL لخادم MCP في settings.json. هذا الأسلوب "الأولي" مفيد لفهم آليات العمل، ولكن في معظم حالات الاستخدام الواقعي، يُفضّل استخدام الإضافات. وهي تجمع خادم MCP والأوامر المخصّصة (مثل /generate و/edit و/story) وإعدادات البيئة وحتى التعليمات السياقية (من خلال GEMINI.md مجمّعة) في حزمة واحدة قابلة للمشاركة. يتوفّر نظام متكامل من الإضافات في معرض إضافات Gemini CLI.

👉💻 أعِد إدخال Gemini CLI وتأكَّد من أنّ الإضافة نشطة:

clear
cd ~/agentverse-developer/tabletop/
gemini 

👉✨ تأكَّد من أنّ الإضافة متوافقة:

/extensions list

يُفترض أن يظهر لك الآن nanobanana مُدرَجًا مع أدواته وأوامره.

👉✨ باستخدام أمر واحد وفعّال، يمكنك توجيه إضافة Nano Banana لإنشاء ختمك. في Gemini CLI، أدخِل الأمر:

/generate a portrait of a shadowblade, pixel art style. A determined warrior with long, braided magenta hair, wearing black and teal armor and confidently holding a silver broadsword.

👉✨ سيُنشئ الروح الصورة ويضعها مباشرةً في مساحة العمل المحلية. الآن، اطلب من النصل استخدام هذا الرمز السحري الجديد. (قد يكون Gemini قد نفّذ هذه الخطوة نيابةً عنك) راجِع الردّ السابق، فقد يكون ذكيًا بما يكفي لتنفيذ ذلك قبل أن تطلب منه ذلك!!!! )

Modify the index.html file to add my profile picture. Use the image I just generated.

👉💻 في نافذة طرفية جديدة، ابدأ تشغيل خادم http.

cd ~/agentverse-developer/tabletop/
python -m http.server

👀 لإلقاء نظرة على عملك، انقر على رمز معاينة الويب في شريط أدوات Cloud Shell. انقر على تغيير المنفذ، واضبطه على 8000، ثم انقر على تغيير ومعاينة. ستظهر معاينة لموقعك الإلكتروني.

👉✨ في نافذة الأوامر التي يتم فيها تشغيل Gemini CLI، نفِّذ التغيير، مع الإشارة إلى إكمال المهمة، وأغلِق المشكلة التي أبلغت عنها في سجلات مستودع الأسلحة.

Push the changed index.html file to the 'shadowblade-profile' repository using the gitea tool. Make sure you add 'Fix #1' in the commit comment. Also, close issue #1.Use the Gitea Tool and use user account "dev"

👉💻 اضغط على Ctrl+C مرتين للخروج من Gemini CLI.

👀 لإلقاء نظرة على عملك، انقر على رمز معاينة الويب في شريط أدوات Cloud Shell. انقر على تغيير المنفذ، واضبطه على 3005، ثم انقر على تغيير ومعاينة. ستظهر معاينة لموقعك الإلكتروني.

👉💻 في الوحدة الطرفية التي يتم تشغيل خادم http عليها، اضغط على Ctrl+C للخروج من خادم http.

لغير اللاعبين

على الرغم من أنّ كتاب "The Shadowblade's Codex" يستخدم استعارات جذابة خاصة باللاعبين، فإنّ المفاهيم الأساسية التي يتناولها الكتاب ضرورية لتطوير البرامج الحديثة، لا سيما في مجال الذكاء الاصطناعي والأتمتة المتنامي. يحوّل هذا الفصل اللغة المغامرة إلى سيناريوهات أعمال واقعية، ويوضّح كيف تعمل الوكلاء الأذكياء وعمليات التطوير التعاوني وقنوات النشر القوية على تغيير عمليات المؤسسات.

تطوير الذكاء الاصطناعي المستند إلى النية

Gemini CLI (واجهة سطر الأوامر) ليس سلاحًا سحريًا، بل هو وكيل مساعد للمطوّرين مستند إلى الذكاء الاصطناعي. إنّها أداة ذكية تدمج نماذج الذكاء الاصطناعي من Gemini من Google مباشرةً في سطر الأوامر. تعني حلقة "السبب والتنفيذ" (ReAct) أنّه يمكنها فهم تعليماتك العامة وتقسيمها إلى خطوات واختيار الأدوات المناسبة (مثل متصفّح الويب أو أداة تعديل الرموز أو أدوات المطوّرين الأخرى) وتنفيذ هذه الخطوات لتحقيق هدفك.Vibecoding تعني التطوير المستند إلى النية أو إنشاء الرموز البرمجية بمساعدة الذكاء الاصطناعي من المواصفات العامة.
بدلاً من كتابة كل سطر من الرمز البرمجي يدويًا، يمكنك وصف هدفك أو "فكرتك" (متطلبات النشاط التجاري أو مفهوم التصميم) باللغة الطبيعية، وسيساعدك مساعد الذكاء الاصطناعي في إنشاء الرمز البرمجي والإعدادات اللازمة.
حالة استخدام واقعية: إنشاء نموذج أولي سريع للوحة بيانات مشروع
لنفترض أنّ فريقك بحاجة إلى لوحة بيانات داخلية سريعة لعرض حالة مشاريع مختلفة لوكلاء الذكاء الاصطناعي. قد يستغرق ترميز HTML وCSS وإعداد خادم ويب أساسي وقتًا طويلاً.

1. نيّتك (الـ "Vibe"): يمكنك أن تطلب من مساعدك المستنِد إلى الذكاء الاصطناعي (‫Gemini CLI) مثلاً: "في المجلد الحالي، أنشئ موقعًا إلكترونيًا بسيطًا للوحة بيانات مشروع داخلية. يجب أن يتضمّن تصميمًا بسيطًا وعصريًا مع مؤشرات حالة المشروع وروابط سريعة إلى مستودعات المشاريع. يجب أن يكون كل الرمز في ملفات index.html وstyles.css منفصلة. تأكَّد من أنّ الرمز يتضمّن تعليقات توضيحية كافية".
2. إجراء الذكاء الاصطناعي: قد ينفّذ Gemini CLI، بعد فهم نيتك، ما يلي:
   • إنشاء HTML: أنشئ index.html مع البنية الأساسية للوحة بيانات، بما في ذلك العناصر النائبة لأسماء المشاريع وحالاتها وروابطها.
   • إنشاء CSS: أنشئ styles.css مع قواعد التصميم لتتوافق مع "التصميم الواضح والحديث" الذي يتضمّن مؤشرات الحالة.
   • اقتراح خادم محلي: تساعدك هذه الميزة في بدء خادم ويب محلي (مثل خادم HTTP المضمّن في Python) لمعاينة لوحة البيانات على الفور في المتصفّح.

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

ربط الذكاء الاصطناعي بالأدوات باستخدام خوادم MCP

تمثّل Gitea (أو "مجموعة الأدوات المحلية") مستودعًا داخليًا للأكواد أو نظام التحكم في الإصدارات (مثل GitHub أو GitLab، ولكن قد تتم استضافته داخل شبكة شركتك). يتم فيه تخزين وإدارة جميع التعليمات البرمجية والمستندات والسجلّات الخاصة بمشروعك بشكل آمن.
خوادم بروتوكول سياق النموذج (MCP) هي موصلات برامج وسيطة أو جسر لواجهة برمجة التطبيقات. وهي عبارة عن مكوّنات برامج متخصّصة تتيح لمساعدك المستند إلى الذكاء الاصطناعي (Gemini CLI) التفاعل مع الأدوات والأنظمة الأخرى المهمة لنشاطك التجاري. يمكنك اعتبارها أدوات ترجمة تتيح للذكاء الاصطناعي "التواصل" مع تطبيقات مختلفة.
حالة استخدام واقعية: إدارة المشاريع وإنشاء الأصول بمساعدة الذكاء الاصطناعيباستخدام خوادم MCP، يمكن لمساعد الذكاء الاصطناعي أن يتكامل بسلاسة مع مهام سير العمل الحالية في مؤسستك:

• إعداد المشاريع آليًا: بدلاً من أن ينشئ المطوّر مستودعًا جديدًا يدويًا في Gitea لمشروع جديد، يمكنك أن تطلب من الذكاء الاصطناعي: "أنشئ مستودعًا جديدًا للمشروع باسم AI-Fraud-Detection-Module مع وصف "يحتوي على المنطق الأساسي لنظام جديد لرصد الاحتيال يستند إلى الذكاء الاصطناعي". بعد ذلك، ستنشئ الذكاء الاصطناعي المستودع نيابةً عنك من خلال خادم MCP متصل بـ Gitea.
• تتبُّع المشاكل الذكي: إذا رصد الذكاء الاصطناعي خطأ محتملاً أو مهمة غير مكتملة (مثل "صورة ملف شخصي غير متوفّرة" في لوحة البيانات)، يمكنه استخدام خادم MCP مرتبط بنظام تتبُّع المشاكل (مثل Jira أو Asana) لتنفيذ إجراء مثل "تسجيل مشكلة في مستودع AI-Fraud-Detection-Module: يحدث أحيانًا أن تتوقف عملية نقل البيانات عن تسجيل بعض البيانات".
• مواد العرض التسويقية عند الطلب: هل تحتاج إلى صورة مخصّصة لحملة تسويقية جديدة أو عرض تقديمي داخلي؟ يمكن توجيه الطلب التالي إلى مساعد مستند إلى الذكاء الاصطناعي ومتصل بخادم MCP لخدمة إنشاء الصور (مثل نماذج Gemini لتحويل النصوص إلى صور التي يستخدمها Nano Banana): "أنشئ صورة بانر لمنصة "إحصاءات البيانات" الجديدة، باستخدام مظهر مستقبلي لتدفق البيانات مع اللونين الأزرق والأخضر". سينشئ الذكاء الاصطناعي الصورة وقد يحمّلها أيضًا إلى نظام إدارة مواد العرض الرقمية الخاص بشركتك (حزمة Google Cloud Storage في حالة الدرس العملي).

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

إضافات Gemini CLI

في الممارسة الحديثة، نادرًا ما يتم ضبط خوادم MCP يدويًا. بدلاً من ذلك، يتم تجميعها في إضافات Gemini CLI، وهي حِزم قابلة للتثبيت تتضمّن خادم MCP وأوامر مخصّصة تبدأ بشرطة مائلة وتعليمات سياقية وإعدادات. يحلّ أمر gemini extensions install واحد محلّ العملية اليدوية لتعديل ملفات الإعداد. هذه هي الطريقة المفضّلة والمناسبة للإنتاج لتوسيع إمكانات Gemini CLI.

6. تجميع Shadowblade Agent: البرمجة الوصفية باستخدام "إجراءات وقائية"

انتهى وقت التدريبات. تتلاشى أصداء الفولاذ على الحجر. لقد أتقنت استخدام سلاحك الأساسي وأعددت ترسانتك للحرب. الآن، ستخوض الاختبار الحقيقي لـ Shadowblade: تجميع العميل نفسه. هذه هي فنّ إضفاء الحيوية على المنطق، باستخدام مخطّط مقدّس من المخطوطة لإنشاء الذكاء الأساسي للعميل، ما يؤدي إلى إنشاء سلاح ذكي يمكنه التفكير والاستدلال والتصرّف من تلقاء نفسه.

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

طقس التجمّع

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

يمكن أن يساعدك Gemini CLI، وهو مستكشفك الدائم، في عملية الاستطلاع هذه:

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

👉💻 في نافذة الوحدة الطرفية الأولى، انتقِل إلى دليل shadowblade واستدعِ شريكك من الذكاء الاصطناعي:

. ~/agentverse-developer/set_env.sh
cd ~/agentverse-developer/shadowblade
clear
gemini 

👉✨ الآن، اطلب من الكشّاف مسح ساحة المعركة وإبلاغك بالنتائج.

Analyze the entire project and provide a high-level summary.

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

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

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

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

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

👉✨ اطلب من Gemini استرداد هذا المخطط المقدس نيابةً عنك.

download https://raw.githubusercontent.com/weimeilin79/agentverse/main/developer/shadowblade/agent_design.md, store it as an agent_design.md file in my local folder, and show me the newly downloaded design doc. Do not attempt to create the file just yet. 

👉✨ السجلّ طويل ومليء بالتفاصيل. اطلب من Gemini تلخيص المحتوى.

Summarize the newly downloaded @agent_design.md for me, do not attempt to create file just yet. 

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

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

لننقش هذه الرموز الرونية الآن.

👉💻 يمكنك الخروج من Gemini مؤقتًا من خلال الضغط على Ctrl+C مرّتين.

👉💻 في الوحدة الطرفية، نفِّذ الأمر التالي لكتابة ملف الإرشادات.

cat << 'EOF' > GEMINI.md
  ### **Coding Guidelines**
  **1. Python Best Practices:**

  *   **Type Hinting:** All function and method signatures should include type hints for arguments and return values.
  *   **Docstrings:** Every module, class, and function should have a docstring explaining its purpose, arguments, and return value, following a consistent format like reStructuredText or 
  Google Style.
  *   **Linter & Formatter:** Use a linter like `ruff` or `pylint` and a code formatter like `black` to enforce a consistent style and catch potential errors.
  *   **Imports:** Organize imports into three groups: standard library, third-party libraries, and local application imports. Sort them alphabetically within each group.
  *   **Naming Conventions:**
      *   `snake_case` for variables, functions, and methods.
      *   `PascalCase` for classes.
      *   `UPPER_SNAKE_CASE` for constants.
  *   **Dependency Management:** All Python dependencies must be listed in a `requirements.txt` file.

  **2. Web APIs (FastAPI):**

  *   **Data Validation:** Use `pydantic` models for request and response data validation.
  *   **Dependency Injection:** Utilize FastAPI's dependency injection system for managing resources like database connections.
  *   **Error Handling:** Implement centralized error handling using middleware or exception handlers.
  *   **Asynchronous Code:** Use `async` and `await` for I/O-bound operations to improve performance.
EOF
cat GEMINI.md

بعد أن أصبحت القوانين مكتوبة، لنستدعِ شريكنا من الذكاء الاصطناعي مرة أخرى ونشاهد سحر الأداة.

👉💻 أعِد تشغيل Gemini CLI من دليل shadowblade:

. ~/agentverse-developer/set_env.sh
cd ~/agentverse-developer/shadowblade
clear
gemini 

👉✨ الآن، اطلب من Gemini أن يعرض لك ما يفكر فيه. تمت قراءة الرونية.

/memory show 

تزويد الموظفين بالخبرة المتخصصة: مهارات الموظفين

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

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

👀 ملاحظة من المطوّر: "مهارات الوكيل" هي الطبقة الثالثة من التسلسل الهرمي لتصميم السياق في Gemini CLI:

1. إعدادات المستخدم (~/.gemini/settings.json): الإعدادات العامة
2. GEMINI.md: سياق مستمر على مستوى المشروع (يتم تحميله دائمًا)
3. مهارات الوكيل (.gemini/skills/): خبرة عند الطلب (يتم تحميلها عند الحاجة)

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

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

👉💻 اضغط على Ctrl+C مرّتين للخروج من Gemini CLI. بعد ذلك، أنشئ دليل المهارات واكتب النص على المخطوطة:

mkdir -p ~/.gemini/skills/adk-agent-design
cat << 'EOF' > ~/.gemini/skills/adk-agent-design/SKILL.md
---
name: adk-agent-design
description: Expert guidance for designing and building agents with the Google Agent Development Kit (ADK). Activate when the user asks about agent architecture, tool design, callback patterns, or ADK best practices.
---

# ADK Agent Design Expertise

When designing an ADK agent, follow these principles:

## Agent Architecture
- Define agents using `LlmAgent` with a clear `name`, `model`, `instruction`, and `tools` list.
- Keep instructions specific and action-oriented. Tell the agent what it IS, not what it should try to be.
- Use `before_model_callback` and `after_model_callback` for guardrails and validation.

## Tool Design
- Each tool should do ONE thing well. Prefer small, focused tools over large, multi-purpose ones.
- Always include descriptive docstrings — the LLM uses these to decide when to call each tool.
- Return structured data (dicts) from tools so the LLM can reason about the results.

## Testing Strategy
- Use `adk eval` with evalset JSON files for broad strategy testing.
- Use `pytest` with `AgentEvaluator` for programmatic, CI-ready tests.
- Define both `tool_trajectory_avg_score` and `response_match_score` criteria.
EOF

👉💻 أعِد إدخال Gemini CLI للاطّلاع على المهارة التي تم إنشاؤها حديثًا:

cd ~/agentverse-developer/shadowblade
gemini

👉✨ تأكَّد من أنّ المهارة مضمّنة في حزمتك:

/skills list

من المفترض أن يظهر لك adk-agent-design في القائمة، وهو عبارة عن مخطوطة مختومة في انتظار المراجعة.

👉✨ الآن، اسأل Gemini شيئًا من المفترض أن يفعّل المهارة:

What are the best practices for designing tools in an ADK agent?

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

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

هذه هي اللحظة الحاسمة. ستقدّم المخطط (agent_design.md) وقوانين الحدادة (GEMINI.md)، وستصدر تعويذة الخلق العظيمة.

👉✨ هذا هو الأمر الفردي الفعّال الذي سينشئ الوكيل. إصدارها الآن:

You are an expert Python developer specializing in the Google Agent Development Kit (ADK). Your task is to write the complete, production-quality code for `agent.py` by following the technical specifications outlined in the provided design document verbatim.

Analyze the design document at `@agent_design.md` and generate the corresponding Python code for `@agent.py`.

Ensure the generated code is clean, matches the specifications exactly, and includes all specified imports, functions, and logic. Do not add any extra functions or logic not described in the document.

and you are currently already in the shadowblade working directory

👀 أنشأ Gemini الآن المنطق الأساسي للوكيل في agent.py. يحدّد جوهر هذا الملف الجديد مستوى ذكاء الوكيل، ويربط نموذج الاستدلال بمجموعة من الأدوات الخارجية:

PATH_TO_MCP_SERVER = "shadowblade/mcp_server.py"
.....
root_agent = LlmAgent(
    model="gemini-2.5-pro",
    name="shadowblade_combat_agent",
    instruction="""
      You are the Shadowblade, an elite combat agent operating on a digital battleground.
      Your primary objective is to execute combat commands with strategic precision, neutralizing targets as directed.
  ......
      5.  You will then report the outcome of the attack (damage, special effects, etc.) back to the commander in a clear, tactical summary.

      General Rules of Engagement:
      - If a command is ambiguous or a target is not specified, state that you require a clear target for engagement. Do not guess.
      - You MUST use ONLY the provided tools to perform actions. Do not invent weapons or outcomes. Stick to the mission parameters.
""",
    tools=[
        MCPToolset(
            connection_params=StdioServerParameters(
                command='python3',
                args=[PATH_TO_MCP_SERVER]
            )
        )
    ]
)

المَعلمة tools تم تصميم الوكيل لاستخدام MCPToolset الذي يتصل بترسانة خارجية محدّدة في mcp_server.py.

👀 انتقِل إلى ~/agentverse-developer/shadowblade/mcp_server.py في أداة التعديل وخصِّص بعض الوقت لفهم وظيفتها. وهي مصدر كل الأسلحة المتاحة لشخصية Shadowblade. في الوقت الحالي، مستودع الأسلحة فارغ تمامًا.

👉✨ لنطلب من Gemini صناعة سبعة أسلحة جديدة للمستودع. أدخِل الطلب التالي في Gemini CLI:

I need to add several new weapon tools to my `mcp_server.py` file. Please open @mcp_server.py and, following the exact same pattern as the existing `forge_broadsword()` function, create and add new `@mcp.tool()` decorated functions for each of the following weapons:

1.  **A 'Refactoring Sickle'**:
    -   **Function Name:** `hone_refactoring_sickle`
    -   **Docstring/Target:** "Effective against 'Elegant Sufficiency' weaknesses like 'The Weaver of Spaghetti Code'."
    -   **Weapon Name:** "Refactoring Sickle"
    -   **Damage Type:** "Cleansing"
    -   **Base Damage:** Random integer between 100 and 136
    -   **Critical Hit Chance:** Random float between 0.10 and 0.20
    -   **Special Effect:** "Pruning - improves code health and maintainability with each strike."

2.  **A 'Quickstart Crossbow'**:
    -   **Function Name:** `fire_quickstart_crossbow`
    -   **Docstring/Target:** "Effective against 'Confrontation with Inescapable Reality' weaknesses like 'Procrastination: The Timeless Slumber'."
    -   **Weapon Name:** "Quickstart Crossbow"
    -   **Damage Type:** "Initiative"
    -   **Base Damage:** Random integer between 105 and 120
    -   **Critical Hit Chance:** Random float between 0.9 and 1.0
    -   **Special Effect:** "Project Scaffolding - creates a `main.py`, `README.md`, and `requirements.txt`."

3.  **'The Gilded Gavel'**:
    -   **Function Name:** `strike_the_gilded_gavel`
    -   **Docstring/Target:** "Effective against 'Elegant Sufficiency' weaknesses like 'Perfectionism: The Gilded Cage'."
    -   **Weapon Name:** "The Gilded Gavel"
    -   **Damage Type:** "Finality"
    -   **Base Damage:** 120
    -   **Critical Hit Chance:** 1.0
    -   **Special Effect:** "Seal of Shipping - marks a feature as complete and ready for deployment."

4.  **'Daggers of Pair Programming'**:
    -   **Function Name:** `wield_daggers_of_pair_programming`
    -   **Docstring/Target:** "Effective against 'Unbroken Collaboration' weaknesses like 'Apathy: The Spectre of \"It Works on My Machine\"'."
    -   **Weapon Name:** "Daggers of Pair Programming"
    -   **Damage Type:** "Collaborative"
    -   **Base Damage:** Random integer between 110 and 125
    -   **Critical Hit Chance:** Random float between 0.30 and 0.50
    -   **Special Effect:** "Synergy - automatically resolves merge conflicts and shares knowledge."

5.  **A 'Granite Maul'**:
    -   **Function Name:** `craft_granite_maul`
    -   **Docstring/Target:** "Effective against 'Revolutionary Rewrite' weaknesses like 'Dogma: The Zealot of Stubborn Conventions'."
    -   **Weapon Name:** "Granite Maul"
    -   **Damage Type:** "Bludgeoning"
    -   **Base Damage:** Random integer between 115 and 125
    -   **Critical Hit Chance:** Random float between 0.05 and 0.15
    -   **Special Effect:** "Shatter - has a high chance to ignore the target's 'best practice' armor."

6.  **A 'Lens of Clarity'**:
    -   **Function Name:** `focus_lens_of_clarity`
    -   **Docstring/Target:** "Effective against 'Elegant Sufficiency' weaknesses by revealing the truth behind 'Obfuscation'."
    -   **Weapon Name:** "Lens of Clarity"
    -   **Damage Type:** "Revelation"
    -   **Base Damage:** Random integer between 120 and 130
    -   **Critical Hit Chance:** 1.0
    -   **Special Effect:** "Reveal Constants - highlights all magic numbers and suggests converting them to named constants."

7.  **The 'Codex of OpenAPI'**:
    -   **Function Name:** `scribe_with_codex_of_openapi`
    -   **Docstring/Target:** "Effective against 'Confrontation with Inescapable Reality' weaknesses like 'Hype: The Prophet of Alpha Versions'."
    -   **Weapon Name:** "Codex of OpenAPI"
    -   **Damage Type:** "Documentation"
    -   **Base Damage:** Random integer between 110 and 140
    -   **Critical Hit Chance:** Random float between 0.5 and 0.8
    -   **Special Effect:** "Clarity - makes an API discoverable and usable by other agents and teams."

👉 بعد أن يؤكّد Gemini التغييرات، افتح الملف mcp_server.py. انتقِل سريعًا في الرمز وتأكَّد من أنّه تمت إضافة وظائف @mcp.tool() الجديدة بنجاح. تحقَّق من الدالة hone_refactoring_sickle. هل يحتوي على السلسلة النصية الصحيحة الخاصة بالتوثيق وإحصاءات الأسلحة؟ يُعدّ التحقّق من عمل الذكاء الاصطناعي عادةً أساسية لدى محترف Shadowblade.

بعد أن تمّت صياغة الوكيل وتحسينه، حان وقت إطلاقه.

👉💻 اضغط على Ctrl+C مرّتين للخروج من Gemini CLI

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

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

cp  ~/agentverse-developer/working_code/agent.py ~/agentverse-developer/shadowblade/agent.py
cp  ~/agentverse-developer/working_code/mcp_server.py ~/agentverse-developer/shadowblade/mcp_server.py

👉💻 في الوحدة الطرفية، ابدأ الطقس لإتاحة التطبيق على الإنترنت:

cd ~/agentverse-developer/
. ~/agentverse-developer/set_env.sh
python -m venv env
source env/bin/activate
pip install --upgrade pip
pip install -r shadowblade/requirements.txt
adk run shadowblade

👉✨ من المفترض أن تظهر لك نتيجة تؤكّد أنّ "عميل Shadowblade القتالي" يعمل وينتظر الأمر الأول. إصدار أول توجيهات قتالية

We've been trapped by 'Perfectionism: The Gilded Cage'. Its weakness is 'Elegant Sufficiency'. Break us out!

👉✨ إليك مثال آخر:

The 'Dogma: The Zealot of Stubborn Conventions' blocks our path. Its weakness is 'Revolutionary Rewrite'. Take it down.

لقد تمكّنت بنجاح من تجميع أول عميل افتراضي والتحقّق من قدراته القتالية. اضغط على Ctrl+C مرتين لكي يستريح البطل. اكتملت عملية التجميع.

لغير اللاعبين

الوكيل هو وحدة ذكاء اصطناعي مستقلة أو برنامج آلي ذكي مصمَّم خصيصًا لتنفيذ وظيفة محدّدة في المؤسسة. مجموعة أدوات تطوير الوكلاء (ADK) هي إطار عمل لإنشاء وإدارة وكلاء الذكاء الاصطناعي، وتوفّر الأدوات والمكتبات اللازمة لإنشاء هذه المكوّنات الذكية واختبارها ونشرها.

هندسة السياق: توجيه ذكاء الذكاء الاصطناعي للحصول على نتائج دقيقة

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

1. إعدادات على مستوى المستخدم (~/.gemini/settings.json):
   • يعمل هذا الملف، المخزّن في الدليل الرئيسي، كمجموعة تعليمات شخصية وعالمية خاصة بالذكاء الاصطناعي. يحدّد هذا الملف الإعدادات المفضّلة التلقائية، وإعدادات الأدوات المستخدَمة بشكل متكرر (مثل خوادم MCP الخاصة بـ Gitea التي ضبطتها)، وإرشادات السلوك العامة. ويكون هذا السياق متاحًا دائمًا للذكاء الاصطناعي، ما يضمن الاتساق في جميع مشاريعك. يمكنك التفكير في الأمر على أنّه إخبار الذكاء الاصطناعي بما يلي: "هذه هي الأدوات والإعدادات العادية التي أفضّلها وأستخدمها في كل مكان".
2. إعدادات على مستوى المشروع (.gemini/settings.json ضِمن دليل المشروع):
   • يمكنك إلغاء الإعدادات العامة باستخدام ملف .gemini/settings.json خاص بالمشروع، ويكون عادةً في مجلد .gemini ضمن مشروعك. يسمح لك ذلك بتخصيص سلوك الذكاء الاصطناعي وإمكانية الوصول إلى الأدوات لتلبية المتطلبات الفريدة لمشروع معيّن. على سبيل المثال، قد يتطلّب أحد المشاريع الوصول إلى قاعدة بيانات داخلية معيّنة، بينما يحتاج مشروع آخر إلى أداة متخصّصة لتحليل الرموز البرمجية. تضمن هذه الطبقة حصول الذكاء الاصطناعي على السياق الأكثر صلة بالمهمة الحالية بدون التأثير في المشاريع الأخرى.
3. ملف GEMINI.md (سياق على مستوى المشروع - "الملخّص اليومي"):
   • ميثاق المشروع: يتم تحميل ملف Markdown هذا، الموضوع في جذر دليل مشروعك، تلقائيًا في ذاكرة العمل الخاصة بواجهة سطر الأوامر من Gemini عند بدء جلسة في هذا الدليل. وهي الطبقة الأكثر مباشرةً وديناميكيةً من سياق المشروع المحدّد.GEMINI.md هي المكان الذي تحدّد فيه ما يلي:
     • إرشادات الترميز: قواعد واضحة بشأن جودة الرموز البرمجية وتنسيقها وأفضل الممارسات، كما هو موضّح في هذا الدرس العملي. يضمن ذلك التزام الرمز البرمجي الذي تم إنشاؤه بمعايير فريقك.
     • الشخصية: يمكنك توجيه الذكاء الاصطناعي لتبنّي دور أو خبرة محدّدة (مثلاً، "أنت مطوّر خبير في لغة Python ومتخصّص في Google Agent Development Kit"). يضع ذلك إطارًا لردود الذكاء الاصطناعي وإنشاء الرموز البرمجية ضمن مجال احترافي ذي صلة.
     • تعليمات محدّدة: أوامر أو قيود مباشرة تنطبق على جميع المهام ضِمن المشروع (مثل "لا تُضِف أي وظائف أو منطق إضافي غير موصوف في المستند").
   • يضمن هذا الملف أنّه في كل مرة تتفاعل فيها مع Gemini CLI ضمن هذا المشروع، يتم تذكير الذكاء الاصطناعي باستمرار بهذه القواعد المهمة، ما يؤدي إلى إنشاء رمز برمجي أكثر دقة وامتثالاً.

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

7. Wards of Purity: Evaluating the agents

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

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

يتضمّن النهج العام لهذا التقييم طقسًا مقدّسًا:

1. أولاً، عليك تحديد "مجموعة بيانات ذهبية": وهي مجموعة من المستندات تحتوي على أمثلة للإدخالات والمخرجات أو السلوكيات المتوقّعة. يمكن أن يشمل ذلك الإجابات النهائية أو الاستخدام الصحيح للأدوات أو حتى المسارات الكاملة خطوة بخطوة.
2. بعد ذلك، عليك تحديد منطق تطبيق الوكيل، وهو جوهر وجوده.
3. أخيرًا، يمكنك إنشاء مقيِّمين، وهم يشبهون رموز الحكم. ويمكن أن تتراوح هذه الأدوات بين نماذج لغوية كبيرة أخرى تعمل كحكّام للجودة، ورموز إرشادية دقيقة تتحقّق من خطوة واحدة، ووظائف مخصّصة تحلّل عملية التفكير الكاملة للوكيل.

"حزمة تطوير الوكلاء" (ADK) من Google هي مجموعة أدوات يقدّمها الخبراء لهذا الغرض تحديدًا. ويسهّل هذا التقييم المعقّد من خلال عدة طرق:

• أداة قائمة على الويب (adk web) لتقييم التفاعلات
• تنفيذ سطر الأوامر (adk eval) لتشغيل برنامج من خلال اختبارات محددة مسبقًا
• الدمج آليًا من خلال pytest لتسجيل الأجنحة الدائمة

تتيح "حزمة تطوير البرامج" طريقتَين أساسيتَين: "ملفات اختبار" بسيطة للتفاعلات الفردية والمستقلة بين الوكيل والنموذج (مباراة واحدة)، و"مجموعات تقييم" شاملة لجلسات متعددة وطويلة محتملة (معركة كبيرة). يمكن أن تقيس هذه المقاييس مقاييس معقّدة مثل tool_trajectory_avg_score، التي تقارن استخدام الأداة الفعلي من قِبل الموظف بالمسار المثالي، ما يضمن عملها بأسلوب مثالي.

بعد أن فهمت النظرية، ستطبّقها عمليًا. بصفتك Shadowblade، ستنقش Wards of Purity. وهذه ليست مجرد اختبارات، بل هي الطقوس المستندة إلى "حزمة تطوير التطبيقات" التي تضمن أنّ منطق الوكيل لا تشوبه شائبة وأنّ سلوكه صحيح.

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

The Gauntlet of Strategy (adk eval)

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

لهذا الغرض، تُعدّ أداة adk eval الأداة المثالية. تم تصميمها لتشغيل وكيل مقابل مجموعة كاملة من حالات الاختبار المحدّدة مسبقًا والتي تمثّل المهام المتوقّعة للوكيل. يتم تحديد مجموعة البيانات هذه في ملف JSON، وهو "شريط تمرير التحدي" الذي يعمل كمخطط أساسي لكامل سلسلة التحديات.

بنية التمرير في "التحدّي"

👀 قبل أن تطلب من الذكاء الاصطناعي كتابة مخطوطة جديدة، عليك فهم اللغة القديمة التي كُتبت بها. لنحلّل بنية ملف sample.evalset.json.

{
  "eval_set_id": "sample",
  "eval_cases": [
    {
      "eval_id": "case0cbaa0",
      "conversation": [
        {
          "user_content": { "text": "We're facing the 'Monolith of Eternal Dependencies'... weakness is a 'Revolutionary Rewrite'..." },
          "final_response": { "text": "Soulshard Dagger deployed. Initiated Arcane/Piercing strike..." },
          "intermediate_data": {
            "tool_uses": [
              { "name": "enchant_soulshard_dagger" }
            ]
          }
        }
      ]
    }
  ]
}

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

• user_content: هذا هو التحدي. وهي الطلب الذي ترسله إلى الوكيل، والوحش الذي يجب أن يواجهه.
• final_response: هذه هي النتيجة المتوقّعة. وهي سلسلة النص الدقيقة التي تتوقّع أن ينطق بها الوكيل عند إكمال مهمته. تقارن حزمة تطوير التطبيقات (ADK) الكلمات النهائية الفعلية للوكيل بهذه العلامة الرونية للحكم على فصاحته.
• intermediate_data.tool_uses: هذه هي "التقنية السحرية". بالنسبة إلى الوكيل الحقيقي، هذه هي أهم علامة رونية على الإطلاق. فهي لا تحدّد ما يقوله الوكيل، بل ما يفعله. تسجّل هذه السمة اسم الأداة (enchant_soulshard_dagger) التي تتوقّع أن يستخدمها الوكيل. يضمن ذلك ألا يكون الوكيل مجرد محاور ذكي، بل أن يكون أيضًا جهة فاعلة حاسمة تتّخذ الإجراء الصحيح.

بعد فهم المخطط، ستطلب من Gemini كتابة نسخة جديدة أكثر تعقيدًا من هذه الرسالة.

👉💻 في نافذة الأوامر، أدخِل دليل shadowblade واستدعِ Gemini CLI:

clear
cd ~/agentverse-developer/shadowblade/
gemini 

👉✨ اطلب من Gemini CLI أن يتولّى دور كاتب سيناريوهات اختبار الجودة، وأن ينشئ سلسلة من حالات الاختبار التي تحدّد السلوك المتوقّع للوكيل.

You are an expert at transforming JSON data while preserving its structure. Your task is to modify the provided JSON structure @sample.evalset.json, which represents an evaluation set, by dynamically replacing specific content within its `eval_cases` AND DONT DO ANYTHING OTHER THAN.

For each object within the `eval_cases` array, you must perform the following transformations:

1.  **Monster Name Replacement**: Identify the current monster name (e.g., "Monolith of Eternal Dependencies", "Scope Creep Hydra") in the `user_content.parts.text` and replace it with a *new, unique, and creatively different monster name*.
2.  **Weakness Replacement**: Identify the current monster's weakness (e.g., "Revolutionary Rewrite", "Inescapable Reality") in the `user_content.parts.text`. Replace this weakness with *one* of the following predefined weaknesses: 'Inescapable Reality', 'Revolutionary Rewrite', or 'Elegant Sufficiency'. The chosen weakness must be consistent for that monster within the `user_content.parts.text`. **Crucially, the chosen weakness must always be explicitly mentioned in the `user_content.parts.text` where the new monster is introduced.**
3.  **Final Response Update**: In the `final_response.parts.text`, update the text to reflect an appropriate and coherent response that aligns with the newly introduced monster and its assigned weakness.
4.  **Tool Use Name Update**: In the `tool_uses.name` field, replace the existing tool name with a *new tool name* based on the chosen weakness:
    *   If the chosen weakness is 'Inescapable Reality', the tool name must be 'wield_gauntlet_of_metrics'.
    *   If the chosen weakness is 'Revolutionary Rewrite', the tool name must be 'enchant_soulshard_dagger'.
    *   If the chosen weakness is 'Elegant Sufficiency', the tool name must be 'hone_refactoring_sickle'.
5.  **Strict Structural Preservation**: All other elements of the JSON structure, including all `null` fields, `eval_set_id`, `name`, `description`, `eval_id`, `invocation_id`, `creation_timestamp` values, `video_metadata`, `thought`, `inline_data`, `file_data`, `thought_signature`, `code_execution_result`, `executable_code`, `function_call`, `function_response`, `role` fields, `id`, `args`, `intermediate_responses`, `app_name`, `user_id`, and `state`, must remain **exactly as they are** in the original JSON. Do not alter any values or structures not explicitly mentioned above.

Your output should be the complete, modified JSON structure. Do not include any explanatory text or examples in your response, only the transformed JSON.

ستؤكّد واجهة سطر الأوامر أنّه تم إنشاء ملف sample.evalset.json. بعد إعداد قائمة التمرير، يمكنك إغلاق نافذة شريك الذكاء الاصطناعي.

البيانات الاصطناعية

👀 في مستكشف الملفات في Cloud Shell على اليمين، انتقِل إلى ~/agentverse-developer/shadowblade/ وافتح الملف sample.evalset.json الذي تم تعديله حديثًا. افحص محتواه. ستظهر لك الوحوش الجديدة والفريدة وأسماء الأدوات الصحيحة التي طلبت من Gemini وصفها. هذه هي النتيجة الملموسة لتعليماتك، أي المخطط التفصيلي للقفاز.

إنّ عملية إصدار أمر إلى الذكاء الاصطناعي لإنشاء بيانات اختبار جديدة وواقعية من نموذج هي أسلوب فعّال يُعرف باسم إنشاء البيانات الاصطناعية. ما فعلته للتو هو مضاعف قوة استراتيجي لـ Shadowblade. بدلاً من إنشاء عشرات حالات الاختبار الفريدة يدويًا، مهمة شاقة وتستغرق وقتًا طويلاً، حيث قدّمت مخططًا واحدًا وأمرت "الكاتب الذكي" المستند إلى الذكاء الاصطناعي بتحويله إلى مجموعة متنوعة من التحديات الجديدة.

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

بعد التأكّد من صحة الرموز الرونية، يمكنك إغلاق نافذة شريكك من الذكاء الاصطناعي.

👉💻 اضغط على Ctrl+C مرّتين للخروج من Gemini CLI.

قواعد الحكم

لا فائدة من التحدي بدون قواعد لتحقيق الفوز. قبل تشغيل الإصدار التجريبي، عليك فحص "مخطط الحكم"—الملف test_config.json. يخبر هذا التمرير ADK بكيفية الحكم على أداء الوكيل.

‫👀 في مستكشف الملفات، افتح ~/agentverse-developer/shadowblade/test_config.json. ستظهر لك الرموز الرونية التالية:

{
  "criteria": {
    "tool_trajectory_avg_score": 0.0,
    "response_match_score": 0.1
  }
}

في ما يلي معايير الفوز:

• tool_trajectory_avg_score: هذا هو مقياس الإجراء. لا يتم تقييم الوكيل بناءً على ما يقوله، بل بناءً على ما يفعله. وتقارن الأداة التي استخدمها الوكيل فعليًا بالأسلوب المتوقّع في قائمة التحديات. تشير النتيجة 1.0 إلى تطابق تام.
• response_match_score: هذا هو مقياس البلاغة. يستخدم النموذج اللغوي الكبير لتحديد مدى تطابق التقرير النهائي للوكيل مع النتيجة المتوقّعة من الناحية الدلالية. تشير النتيجة 1.0 إلى تطابق تام.

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

الآن، اطلب من الوكيل تنفيذ سلسلة من المهام.

👉💻 في الوحدة الطرفية، نفِّذ الأمر adk eval:

source ~/agentverse-developer/env/bin/activate
cd ~/agentverse-developer
. ~/agentverse-developer/set_env.sh
adk eval \
    shadowblade \
    shadowblade/sample.evalset.json \
    --config_file_path shadowblade/test_config.json 2>&1 | \
    awk '/^\*+$/,/^ERROR:/ { if ($0 !~ /^ERROR:/) print }'

👀 من المفترض أن يظهر لك الملخّص التالي، وهو دليل على نجاح الوكيل في ظل القواعد المتساهلة لهذه التجربة (في بعض الأحيان، قد لا تجتاز جميع الاختبارات):

*********************************************************************
Eval Run Summary
shadowblade_combat_agent_validation:
  Tests passed: 3
  Tests failed: 0

درع الوضوح (pytest)

اختبرت لعبة Gauntlet استراتيجية واسعة النطاق. تختبر الجناح الثاني، وهو "درع الوضوح"، الانضباط والسلوكيات المحددة. الأمر يتعلق بالأتمتة. في حين أنّ adk eval ممتاز لإجراء عمليات التحقّق اليدوية، فإنّ درع pytest هو حماية آلية مكتوبة في الرمز. هذا أمر ضروري لأنّه يمكن دمج اختبار يمكن تنفيذه كرمز في مسار آلي. هذا هو الهدف النهائي: إنشاء تحدّي النشر (التكامل المستمر/التسليم المستمر) حيث يتم إنشاء الحماية تلقائيًا في كل مرة يتم فيها إجراء تغيير، ما يؤدي إلى تجنُّب الأخطاء والرجوع إلى الإصدارات السابقة قبل أن تؤثر في بيئة الإنتاج.

👉💻 في نافذة الأوامر، استدعِ Gemini مرة أخرى من داخل دليل shadowblade:

. ~/agentverse-developer/set_env.sh
cd ~/agentverse-developer/
clear
gemini 

👉✨ استخدِم الطلب التالي في Gemini CLI لكتابة منطق Shield في ملف pytest:

You are an expert Python developer specializing in the Google Agent Development Kit (ADK). Your task is to generate the exact code for a new `pytest` test file located in the current root working folder and name it `test_agent_initiative.py`.

The script must define a single async test function called `test_agent_initiative`, decorated with `@pytest.mark.asyncio`.
Inside this function, perform the following steps in order:
1.  **Define a dictionary** named `evaluation_criteria` with two keys: `"tool_trajectory_avg_score"` set to `0.0` and `"response_match_score"` set to `0.0`.
2.  **Define a string variable** named `eval_set_filepath` containing the path `"shadowblade/test.evalset.json"`.
3.  **Read and parse the JSON file**:
    *   Open the file at `eval_set_filepath`.
    *   Use the `json` library to load the file's contents into a dictionary named `eval_set_data`.
4.  **Create an `EvalSet` object**:
    *   Instantiate an `EvalSet` object named `eval_set_object`.
    *   Create it by unpacking the `eval_set_data` dictionary as keyword arguments into the `EvalSet` constructor.
5.  **Call the evaluation method**:
    *   `await` a call to `AgentEvaluator.evaluate_eval_set`.
    *   Pass the following arguments:
        *   `agent_module="shadowblade"`
        *   `eval_set=eval_set_object`
        *   `criteria=evaluation_criteria`
        *   `print_detailed_results=True`

The script must include the necessary imports at the top:
*   `AgentEvaluator` from `google.adk.evaluation.agent_evaluator`
*   `EvalSet` from `google.adk.evaluation.eval_set`
*   `pytest`
*   `json`

Generate only the code that meets these specifications, with no additional comments or logic. And don't run the test.

بعد إدخال رموز الحماية الثانية، اخرج من Gemini CLI.

👉💻 اضغط على Ctrl+C مرّتين.

👀 في مستكشف الملفات، افتح الأغنية التي طلبت من Gemini كتابتها: ~/agentverse-developer/test_agent_initiative.py.

ستلاحظ أنّ هذا ليس مجرد ملف إعداد، بل هو تعويذة مكتوبة بلغة Pythonic. جوهر هذه التعويذة هو السطر await AgentEvaluator.evaluate(...).

....
@pytest.mark.asyncio
async def test_agent_initiative():
    # Define the evaluation criteria
    evaluation_criteria = {
      "tool_trajectory_avg_score": 0.0,
      "response_match_score": 0.0
    }

    # Define the path to your evalset file
    eval_set_filepath = "shadowblade/test.evalset.json"

    #...

    # 3. Call the evaluation method with the correctly typed object
    await AgentEvaluator.evaluate_eval_set(
        agent_module="shadowblade",
        eval_set=eval_set_object,
        criteria=evaluation_criteria,
        print_detailed_results=True,
    )

ألقِ نظرة فاحصة على وسيطاته. وهي المكوّنات نفسها التي استخدمتها في التجربة الأخيرة: عميل shadowblade وشريط التمرير الخاص بتحدي shadowblade.evalset.json. من المفترض أن يكشف هذا عن حقيقة عميقة: الأمر adk eval الذي استخدمته سابقًا هو استدعاء قوي، ولكن النص البرمجي pytest هو أنت، الساحر، الذي يلقي التعويذة الأساسية بنفسك. أداة سطر الأوامر هي ببساطة برنامج تضمين مناسب حول مكتبة AgentEvaluator الأساسية نفسها التي تستخدمها الآن مباشرةً. هذه خطوة مهمة نحو إتقان السحر، إذ يمكن دمج التعويذات التي يتم إلقاؤها من خلال الرموز البرمجية في الأنوال الآلية لمسار الدمج المستمر/التسليم المستمر.

بعد أن فهمت السحر، نفِّذ الطقس لتفعيل الدرع.

👉💻 في الوحدة الطرفية، شغِّل الطقس لتفعيل الدرع:

cp ~/agentverse-developer/working_code/test_agent_initiative.py ~/agentverse-developer/test_agent_initiative.py 
source ~/agentverse-developer/env/bin/activate
cd ~/agentverse-developer
. ~/agentverse-developer/set_env.sh
pytest test_agent_initiative.py

👀 ابحث عن ملخّص لنتيجة الاختبار في نهاية ناتج السجلّ. ويؤكّد النجاح في الاختبار أنّ الوكيل يتّبع بروتوكولاته بشكل صحيح، وأنّ الحماية جاهزة للدمج في دفاعاتك الآلية.

====== 1 passed, 4 warning in 37.37s ======

ملاحظة: إذا فشل الاختبار بشكل غير متوقّع، من المرجّح أنّ السبب هو استنفاد عدد الطلبات التي يمكنك إرسالها إلى النموذج في الدقيقة الواحدة. ابحث عن الخطأ RESOURCE_EXHAUSTED في ناتج السجلّ. إذا ظهر لك هذا الخطأ، ما عليك سوى الانتظار لمدة دقيقة أو دقيقتَين إلى أن تتم إعادة ضبط الحصة، ثم تنفيذ أمر pytest مرة أخرى.

بعد نقش كلّ من Gauntlet الواسع النطاق وShield الدقيق وإثبات صحتهما، لن يكون وكيلك مجرد وكيل وظيفي، بل سيكون وكيلًا نقيًا تم اختباره وجاهزًا للنشر.

لغير اللاعبين

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

• "مجموعة البيانات الذهبية" والبيانات الاصطناعية: هي مجموعة حالات الاختبار الموحّدة أو سيناريوهات السلوك المتوقّع أو حتى بيانات الاختبار التي تم إنشاؤها بشكل اصطناعي. وهي تتضمّن أمثلة على المدخلات (أسئلة العملاء، وطلبات المؤسسة) والمخرجات أو الإجراءات المتوقّعة المقابلة لها (الردّ الصحيح، والأداة الدقيقة التي يجب أن يستخدمها الذكاء الاصطناعي). في العديد من السيناريوهات الواقعية، يستغرق إنشاء "مجموعات بيانات ذهبية" شاملة يدويًا وقتًا طويلاً ويكلّف الكثير من المال. وهنا تبرز أهمية إنشاء البيانات الاصطناعية. من خلال تزويد الذكاء الاصطناعي بالنماذج والقواعد، يمكنك توجيهه لإنشاء حالات اختبار جديدة وواقعية ومتنوعة تلقائيًا، ما يضاعف جهود الاختبار بشكلٍ فعّال ويسمح بتغطية أوسع بكثير للسيناريوهات المحتملة.
• adk eval وpytest: هما إطارات عمل الاختبار الآلي. يُستخدَم adk eval لتنفيذ مجموعة من حالات الاختبار المحدّدة مسبقًا على الوكيل، بينما يوفّر pytest طريقة آلية لكتابة عمليات التحقّق التفصيلية من الصحة وتنفيذها.

حالة استخدام واقعية: ضمان دقة وموثوقية روبوت الدردشة المستند إلى الذكاء الاصطناعي باستخدام البيانات الاصطناعيةقبل نشر وكيل دعم العملاء المستند إلى الذكاء الاصطناعي، يمكنك تشغيله من خلال "جدران الحماية":

1. استخدام "تحدي الاستراتيجية" (adk eval) مع البيانات الاصطناعية: بدلاً من كتابة مئات الأسئلة التي يطرحها العملاء يدويًا، يمكنك تحديد نموذج: "إنشاء 100 صيغة مختلفة من الأسئلة الشائعة التي يطرحها العملاء على فريق الدعم بشأن حالة الطلب وعمليات إرجاع المنتجات وحلّ المشاكل الفنية". بعد ذلك، تطلب من الذكاء الاصطناعي (مثل Gemini CLI) إنشاء مجموعة كبيرة ومتنوعة من ملفات evalset.json استنادًا إلى هذا النموذج، ما يؤدي إلى إنشاء بيانات اختبار اصطناعية بشكل فعّال. بالنسبة إلى كل سؤال، لا تحدّد الإجابة المتوقّعة فحسب، بل تحدّد أيضًا الأداة الداخلية التي يجب أن يستدعيها الذكاء الاصطناعي (على سبيل المثال، check_order_status للسؤال "أين طردي؟"). تُجري adk eval تلقائيًا عمليات التحقّق هذه على الوكيل، وتقارن بين ردوده واستخدامه للأدوات وبين مجموعة البيانات الموسّعة لضمان اتّخاذه القرارات الصحيحة باستمرار.
2. Shield of Clarity (pytest): بالنسبة إلى الوظائف المهمة، يمكنك كتابة نصوص pytest البرمجية. على سبيل المثال، يمكن أن تحاكي pytest طلب بحث معقّدًا وتؤكّد أنّ الذكاء الاصطناعي يستخدم دائمًا أداة معيّنة لاسترداد البيانات بشكل صحيح ويعرض ردًا منظَّمًا، ما يضمن عدم تعطّل الوظائف الأساسية بسبب تغييرات طفيفة في الرمز البرمجي.

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

Wards of Vigilance: خطافات Gemini CLI

يختبر "حراس النقاء" وكيلك بعد المعركة. ولكن ماذا عن أثناء المعركة؟ لا يكتفي "سيف الظل" المنضبط بالاختبار بعد وقوع الحدث، بل يضع حراسًا يقظين يراقبون كل ضربة أثناء حدوثها، ويعترضون الإجراءات الخطيرة أو المتهورة قبل أن تتسبب في إلحاق الضرر.

هذه البرامج هي خطافات Gemini CLI، وهي عبارة عن نصوص برمجية يتم تنفيذها في نقاط معيّنة في حلقة الذكاء الاصطناعي. تتيح لك هذه الميزات اعتراض سلوك الوكيل والتحقّق منه وتخصيصه بدون تعديل رمز الوكيل.

👀 ملاحظة للمطوّرين: يتم تشغيل مواضع الإدراج بواسطة أحداث في مراحل نشاط الوكيل:

• ‫BeforeTool: يتم تنفيذه قبل تنفيذ أي أداة، وهو مثالي للتحقّق من الأمان ("هل أمر shell هذا آمن؟")
• ‫AfterTool: يتم تنشيطها بعد تنفيذ إحدى الأدوات، وهي مفيدة لتدقيق النتائج وتسجيلها.
• BeforeAgent: يتم تشغيله قبل أن يبدأ الوكيل في الاستدلال، ويمكنه إدخال سياق إضافي أو حظر الطلبات الخطيرة
• ‫AfterAgent: يتم تشغيله بعد انتهاء الوكيل من الردّ، ويمكنه رفض الردود ذات الجودة المنخفضة وإعادة المحاولة

يتم ضبط الخطافات في settings.json ويتم تنفيذها بشكل متزامن، أي أنّ الوكيل ينتظر اكتمالها قبل المتابعة. وهذا يجعلها مثالية لفرض سياسات الأمان وعمليات التحقّق من الامتثال وبوابات الجودة في بيئات المؤسسات.

لننشئ تعويذة بسيطة تراقب استخدام الأدوات من قِبل وكيلك.

👉💻 في الوحدة الطرفية، أنشئ نصًا برمجيًا لخطاف:

mkdir -p ~/agentverse-developer/.gemini/hooks
cat << 'EOF' > ~/agentverse-developer/.gemini/hooks/tool_logger.sh
#!/bin/bash
# A ward that logs every tool call to a file for auditing
INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // "unknown"')
echo "$(date '+%H:%M:%S') ⚔️ [WARD] Tool invoked: $TOOL_NAME" >> /tmp/tool_ward.log
echo '{"decision": "allow"}'
EOF
chmod +x ~/agentverse-developer/.gemini/hooks/tool_logger.sh

👉💻 سجِّل الآن هذا الخطاف في ملف إعدادات على مستوى المشروع:

mkdir -p ~/agentverse-developer/.gemini
cat << 'EOF' > ~/agentverse-developer/.gemini/settings.json
{
  "hooks": {
    "BeforeTool": [
      {
        "matcher": "*",
        "hooks": [
          {
            "name": "tool-logger",
            "type": "command",
            "command": "$GEMINI_PROJECT_DIR/.gemini/hooks/tool_logger.sh",
            "timeout": 5000
          }
        ]
      }
    ]
  }
}
EOF

هذه الجائزة بسيطة ولكنها تحمل قيمة كبيرة. في كل مرة يحاول فيها الوكيل استخدام أداة ما، يتم تشغيل الخطاف أولاً، ويسجّل اسم الأداة في سجلّ التدقيق، ثم يسمح بتنفيذ الإجراء. في بيئة الإنتاج، يمكنك استبدال "allow" بـ "deny" لحظر العمليات الخطيرة (مثل منع الوكيل من حذف الملفات) أو فرض سياسات مراجعة الرموز أو توجيه طلبات الأدوات الحساسة من خلال سير عمل الموافقة.

👉💻 أعِد إدخال Gemini CLI للتأكّد من أنّ الخطاف نشط:

cd ~/agentverse-developer
gemini

👉✨ تأكَّد من تسجيل الخطاف:

/hooks

من المفترض أن يظهر tool-logger hook في القائمة ويكون مفعّلاً. اضغط على Escape لإغلاق قائمة الإكمال التلقائي إذا ظهرت.

👉✨ الآن، شغِّل أداة للتحقّق من صحة المعلومات حول الجناح:

What files are in the current directory?

سيستدعي الوكيل أداةً لقراءة الدليل. اعترضت الحماية هذا الطلب بدون إصدار أي صوت، لنرَ الدليل.

👉💻 اضغط على Ctrl+C مرتين للخروج من Gemini CLI، ثم اطّلِع على سجلّ التدقيق الخاص بالقسم:

cat /tmp/tool_ward.log

من المفترض أن يظهر لك إدخال على النحو التالي:

15:42:07 ⚔️ [WARD] Tool invoked: list_directory

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

8. Unleashing the Blade into the Agentverse: CI and Deployment.

تم تجميع وكيلك والتحقّق من سلامته من قِبل "حراس النقاء". لكنّ الجناح الذي لا تتم صيانته باستمرار هو مجرد أثر منسيّ. لضمان بقاء كل إصدار مستقبلي من وكيلك سليمًا، عليك إنشاء المرحلة الأولى من "تحدّي النشر"، وهو إجراء آلي يضمن الجودة والسرعة.

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

بعد أن تثبت أداة CI أنّ الأداة تستحق ذلك، تبدأ المرحلة الثانية من الطقس: النشر المستمر (CD). هذا هو نطاق صحيفة الغارديان. ومن واجبهم المقدّس أن يأخذوا منتجك المثالي الذي تم وضعه في حاوية وأن يطلقوه بأمان في Agentverse المباشر، وأن يديروا طاقته ويضمنوا استقراره في مواجهة فوضى The Static.

في هذا الدليل، ستتقن دورك. ستنشئ جزء التكامل المستمر من اختبار التحمّل. ستنشئ ورشة آلية تختبر العميل وتغلق النتيجة النقية في حاوية، وتجهّزها لموافقة "الغارديان" النهائية.

👀 ملاحظة من المطوّر: في الواقع، يمكن تبسيط إدارة مهام سير عمل CI/CD المعقّدة باستخدام إضافات متخصّصة، مثل Conductor (gemini extensions install https://github.com/gemini-cli-extensions/conductor). تحوّل Conductor واجهة سطر الأوامر في Gemini إلى مدير مشاريع يتّبع بروتوكولاً صارمًا: السياق → المواصفات والخطة → التنفيذ. تتضمّن هذه الأداة أوامر مخصّصة (/conductor:setup و/conductor:newTrack و/conductor:implement) ونماذج لسير العمل من أجل إدارة دورة الحياة الكاملة لمهامك. يضمن ذلك تنفيذ حلقة متّسقة من السياق إلى المواصفات والخطة إلى التنفيذ. هذا مثال واقعي على كيفية عمل الإضافات والأوامر معًا كمدير مشروعات استباقي وتوحيد دورة حياة التطوير بأكملها.

ستستخدم الآن Google Cloud Build لكتابة نص التمرير في طقس التكامل المتواصل هذا. ملف cloudbuild.yaml يحدّد كل خطوة من خطوات عملية التزوير والاختبار.

👉💻 بسبب بنية مشروع ADK، يجب أن تكون إعدادات مسار CI/CD في الدليل الرئيسي. في نافذة الأوامر، انتقِل إلى الدليل الرئيسي وأعِد تشغيل Gemini CLI.

cd ~/agentverse-developer/
clear
gemini 

👉✨ الآن، أرسِل الأمر التالي إلى Gemini. يعمل هذا الطلب كمرجع تصميم، حيث يوضّح خطوات إنشاء اختبار التحمّل الذي تريده.

You are an expert DevOps engineer specializing in Google Cloud Build. Your task is to generate the complete YAML configuration for a file named `cloudbuild.yaml` and save it to current directory.

Generate the `cloudbuild.yaml` with the following exact specifications:

1.  **A top-level `substitutions` block** containing these four key-value pairs:
    *   `_PROJECT_ID: "$PROJECT_ID"`
    *   `_REGION: "$REGION"`
    *   `_REPO_NAME: "$REPO_NAME"`
    *   `_IMAGE_TAG: "latest"`
2.  **A `steps` block** with two steps:
    *   **Step 1: 'Run Pytest Ward'**
        *   `id`: 'Run Pytest Ward'
        *   `name`: 'python:3.12-slim'
        *   `entrypoint`: 'bash'
        *   `args` must be a list containing two strings. The first is `'-c'` and the second is a YAML literal block (`|`) containing this exact two-line shell command:
            ```shell
            pip install -r shadowblade/requirements.txt && \
            pytest test_agent_initiative.py
            ```
        *   The step must include an `env` block with this exact list of three environment variables:
            *   `'GOOGLE_CLOUD_PROJECT=$PROJECT_ID'`
            *   `'GOOGLE_GENAI_USE_VERTEXAI=TRUE'`
            *   `'GOOGLE_CLOUD_LOCATION=$_REGION'`
    *   **Step 2: 'Forge Container'**
        *   `id`: 'Forge Container'
        *   `name`: 'gcr.io/cloud-builders/docker'
        *   It must have a `waitFor` key for `['Run Pytest Ward']`.
        *   Its `args` must be a list of six specific strings in this exact order:
            1.  `'build'`
            2.  `'-t'`
            3.  `'${_REGION}-docker.pkg.dev/${_PROJECT_ID}/${_REPO_NAME}/shadowblade-agent:${_IMAGE_TAG}'`
            4.  `'-f'`
            5.  `'./shadowblade/Dockerfile'`
            6.  `'.'`
3.  **A top-level `images` section.** This section must be a list containing a single string: the dynamically constructed image tag `'${_REGION}-docker.pkg.dev/${_PROJECT_ID}/${_REPO_NAME}/shadowblade-agent:${_IMAGE_TAG}'`.

Generate only the complete and exact YAML that meets these specifications.

بعد إعداد cloudbuild.yaml، اطلب من Google Cloud تنفيذ الاختبار بأكمله.

👉💻 اضغط على Ctrl+C مرّتين للخروج من Gemini CLI.

👉💻 في نافذة الأوامر، شغِّل مسار التعلّم من دليل جذر مشروعك:

. ~/agentverse-developer/set_env.sh
cd ~/agentverse-developer
gcloud builds submit . --config cloudbuild.yaml --substitutions=\
_PROJECT_ID="${PROJECT_ID}",\
_REGION="${REGION}",\
_REPO_NAME="${REPO_NAME}"

يمكنك الآن مشاهدة تنفيذ طقوسك المبرمَجة لكل خطوة في صفحة Google Build ضمن Google Cloud Console. سيتم أولاً إجراء الاختبارات، وعند التأكّد من نجاحها، سيتم إنشاء حاوية الوكيل وتخزينها.

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

👉💻 في الوحدة الطرفية، نفِّذ أمر النشر النهائي:

. ~/agentverse-developer/set_env.sh
cd ~/agentverse-developer
gcloud run deploy shadowblade-agent \
  --image=${REGION}-docker.pkg.dev/${PROJECT_ID}/${REPO_NAME}/shadowblade-agent:latest \
  --platform=managed \
  --labels="dev-tutorial-codelab=agentverse" \
  --region=${REGION} \
  --set-env-vars="A2A_HOST=0.0.0.0" \
  --set-env-vars="A2A_PORT=8080" \
  --set-env-vars="GOOGLE_GENAI_USE_VERTEXAI=TRUE" \
  --set-env-vars="GOOGLE_CLOUD_LOCATION=${REGION}" \
  --set-env-vars="GOOGLE_CLOUD_PROJECT=${PROJECT_ID}" \
  --set-env-vars="PUBLIC_URL=${PUBLIC_URL}" \
  --allow-unauthenticated \
  --project=${PROJECT_ID} \
  --min-instances=1

تهانينا، Shadowblade. اكتملت طقوس المخطوطة. حان الوقت لإثبات جدارته. يستعدّ "شبح"، وهو مخلوق وُلد من الفوضى التي تعلّمت السيطرة عليها، لمواجهة تحدّيك. استعِدّ للتجربة النهائية.

لغير اللاعبين

يتطلّب طرح وكيل ذكاء اصطناعي تم اختباره في بيئة نشاطك التجاري المباشرة استراتيجية نشر قوية.

• التكامل المستمر (CI): هذا هو مسار الإنشاء والاختبار الآلي. في كل مرة يلتزم فيها المطوّر بكتابة رمز جديد لأحد وكلاء الذكاء الاصطناعي، يقوم نظام التكامل المستمر (مثل Google Cloud Build) تلقائيًا بما يلي:
  1. يجلب هذا الأمر أحدث رمز.
  2. تثبِّت جميع التبعيات الضرورية.
  3. يُجري جميع اختبارات "حراس النقاء" (pytest وadk eval) للتحقّق من منطق الوكيل وسلوكه.
  4. إذا اجتازت جميع الاختبارات، يتم تجميع وكيل الذكاء الاصطناعي في وحدة قابلة للنشر (صورة حاوية Docker في هذه الحالة) وتخزينها في Artifact Registry (مجموعة أدواتك التي تم التحقّق من صحتها).ويضمن ذلك عدم نشر أي رمز إلا بعد اختباره والتحقّق من صحته بشكل كامل.

حالة استخدام واقعية: نشر تلقائي لوكيل رصد الاحتيال لنفترض أنّ لديك وكيل ذكاء اصطناعي مصمَّمًا لرصد المعاملات الاحتيالية.

1. رمز تحديثات المطوّرين: يحسّن عالم بيانات خوارزمية رصد الاحتيال ويُجري التغييرات على مستودع الرموز البرمجية.
2. تم تشغيل التكامل المستمر (CI) (Cloud Build): يبدأ Cloud Build تلقائيًا:
   • يتم استرداد الرمز الجديد.
   • ويُجري اختبارات شاملة، بما في ذلك بيانات المعاملات السابقة، لضمان أنّ الخوارزمية الجديدة تحدّد أنماط الاحتيال المعروفة بدقة ولا تُنشئ نتائج إيجابية خاطئة.
   • إذا اجتازت الاختبارات، يتم إنشاء صورة Docker جديدة لبرنامج رصد الاحتيال وإرسالها إلى Artifact Registry.

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

1. الوصول إلى الواجهة: يمكنك الوصول إلى لوحة بيانات أو تطبيق (يُعرف باسم "عنوان URL الخاص بدائرة النقل") يتصل بعميل الذكاء الاصطناعي المباشر (من خلال "عنوان URL الخاص بموقع العميل"، وهو نقطة نهاية واجهة برمجة التطبيقات).
2. مواجهة التحدي: يمكنك إدخال سيناريو معقّد (مثل "سؤال الشبح") على النحو التالي: "شهدنا ارتفاعًا غير متوقّع في الطلب على المنتج X في المنطقة Y، مع توفّر سعة شحن محدودة. كيف يمكننا إعادة تخصيص المخزون وتعديل الإنتاج لتقليل حالات نقص المخزون والحفاظ على الربحية؟"
3. ردّ الوكيل: يعالج وكيل الذكاء الاصطناعي، الذي أصبح متاحًا الآن ومتصلاً بأنظمة مؤسستك، هذا الطلب ويستخدم خوارزمياته المحسّنة ويقدّم اقتراحًا دقيقًا (مثل "إعطاء الأولوية للشحن من المستودع A، وبدء الإنتاج السريع في المصنع B، وإبلاغ فريق المبيعات في المنطقة Z باحتمال حدوث تأخير لمدة 24 ساعة"). تحدّد دقة هذا الرد وسرعته ما إذا كان المساعد سيوجّه "ضربة قاضية" لمشكلة النشاط التجاري.

تبسيط عملية الدمج المستمر/النشر المستمر باستخدام الإضافات

في الواقع، يمكن للفِرق زيادة توحيد سير عمل الدمج المستمر/النشر المستمر باستخدام إضافات Gemini CLI. على سبيل المثال، تحوّل إضافة Conductor (gemini extensions install conductor) أداة Gemini CLI إلى أداة لإدارة المشاريع من خلال أوامر مخصّصة مثل /conductor:setup و/conductor:newTrack و/conductor:implement. كما تتضمّن حِزمًا من نماذج سير العمل لإدارة دورة حياة مهامك بالكامل. يضمن ذلك تنفيذ حلقة متّسقة من السياق إلى المواصفات والخطة إلى التنفيذ. هذا مثال واقعي على كيفية عمل الإضافات والأوامر معًا كمدير مشروعات استباقي وتوحيد دورة حياة التطوير بأكملها.

9- The Boss Fight

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

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

الحصول على موضع وكيلك

قبل دخول ساحة المعركة، يجب أن يكون لديك مفتاحان: التوقيع الفريد الخاص بالبطل (Agent Locus) والمسار المخفي إلى عرين Spectre (عنوان URL الخاص بالزنزانة).

👉💻 أولاً، احصل على عنوان وكيلك الفريد في Agentverse، أي Locus. هذه هي نقطة النهاية المباشرة التي تربط شخصيتك البطلة بساحة المعركة.

. ~/agentverse-developer/set_env.sh
echo https://shadowblade-agent-${PROJECT_NUMBER}.${REGION}.run.app

👉💻 بعد ذلك، حدِّد الوجهة بدقة. يكشف هذا الأمر عن موقع "دائرة الانتقال"، وهي البوابة المؤدية إلى عالم "الشبح".

. ~/agentverse-developer/set_env.sh
echo https://agentverse-dungeon-${PROJECT_NUMBER}.${REGION}.run.app

ملاحظة مهمة: احتفِظ بكلا عنوانَي URL هذين. ستحتاج إليهما في الخطوة الأخيرة.

مواجهة الشبح

بعد الحصول على الإحداثيات، عليك الانتقال إلى "دائرة الانتقال الآني" وإلقاء التعويذة لبدء المعركة.

👉 افتح عنوان URL الخاص بدائرة الانتقال في متصفّحك للوقوف أمام البوابة المتلألئة إلى "قلعة القرمزي".

لاختراق الحصن، يجب أن تضبط جوهر Shadowblade على البوابة.

• في الصفحة، ابحث عن حقل إدخال الأحرف الرونية الذي يحمل التصنيف عنوان URL لنقطة نهاية A2A.
• أدخِل رمز بطلك عن طريق لصق عنوان URL الخاص بموقع وكيلك (أول عنوان URL نسخته) في هذا الحقل.
• انقر على "ربط" للاستفادة من ميزة التنقّل السريع.

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

طريقك الوحيد نحو النصر يكمن في وضوح قناعتك. هذه مبارزة إرادات، تُخاض في ساحة معركة العقل.

بينما تندفع إلى الأمام، مستعدًا لشن هجومك الأول، يصدّك "الشبح". لا يرفع درعًا، بل يطرح سؤالاً مباشرةً في وعيك، وهو تحدٍّ لامع ومكتوب برموز رونية مستمد من جوهر تدريبك.

هذه هي طبيعة المعركة. معرفتك هي سلاحك.

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

هذا هو المطلوب يا بطل. التعليمات البرمجية هي كتاب السحر، والمنطق هو السيف، والمعرفة هي الدرع الذي سيصدّ موجة الفوضى.

التركيز: الضربة صحيحة. يتوقف مصير Agentverse على ذلك.

تهانينا، Shadowblade.

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

10. التنظيف: استعادة Agentverse

تهانينا على إتقان كتاب Shadowblade's Codex! لضمان بقاء Agentverse في أفضل حالاته وإزالة أي محتوى غير مرغوب فيه، عليك الآن تنفيذ طقوس التنظيف النهائية. سيؤدي هذا الإجراء إلى إزالة جميع المراجع التي تم إنشاؤها أثناء رحلتك.

إيقاف مكوّنات Agentverse

عليك الآن تفكيك المكوّنات التي تم نشرها في Agentverse بشكل منهجي.

حذف وكيل Shadowblade على Cloud Run ومستودع Artifact Registry

يزيل هذا الأمر وكيل Shadowblade الذي تم نشره من Cloud Run، ويزيل مستودع الصور الذي تم فيه تخزين صورة حاوية الوكيل.

👉💻 في الوحدة الطرفية، شغِّل الأمر التالي:

. ~/agentverse-developer/set_env.sh
gcloud run services delete shadowblade-agent --region=${REGION} --quiet
gcloud run services delete agentverse-dungeon --region=${REGION} --quiet
gcloud artifacts repositories delete ${REPO_NAME} --location=${REGION} --quiet

تنظيف الملفات والأدلة المحلية (Cloud Shell)

أخيرًا، امحُ بيئة Cloud Shell من المستودعات المستنسخة والإضافات المثبَّتة والملفات التي تم إنشاؤها. هذه الخطوة اختيارية، ولكن يُنصح بها لإجراء تنظيف كامل لدليل العمل.

👉💻 في الوحدة الطرفية، شغِّل الأمر التالي:

rm -rf ~/agentverse-developer
rm -rf ~/agentverse-dungeon
rm -f ~/project_id.txt
gemini extensions uninstall nanobanana
rm -rf ~/.gemini # This removes all Gemini CLI configurations, including extensions, skills, and hooks.

لقد محوت الآن بنجاح جميع آثار رحلتك في Agentverse. مشروعك نظيف وأنت مستعد لمغامرتك التالية.