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

1. Overture

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

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

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

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

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

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

agentverse.png

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

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

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

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

اختيار صفك

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

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

مهمتك

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

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

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

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

2. The Shadowblade's Codex

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

02-00-overview.png

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

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

3- الاستعداد لـ "ساحة التدريب"

👉انقر على "تفعيل Cloud Shell" في أعلى "وحدة تحكّم Google Cloud" (رمز شكل الوحدة الطرفية في أعلى لوحة Cloud Shell)، cloud-shell.png

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

👉العثور على رقم تعريف مشروعك على Google Cloud:

  • افتح Google Cloud Console: https://console.cloud.google.com
  • اختَر المشروع الذي تريد استخدامه في ورشة العمل هذه من القائمة المنسدلة للمشروع في أعلى الصفحة.
  • يظهر رقم تعريف مشروعك في بطاقة "معلومات المشروع" على "لوحة البيانات".

03-04-project-id.png

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

03-05-new-terminal.png

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

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

git clone https://github.com/weimeilin79/vertex-ai-creative-studio.git
chmod +x ~/vertex-ai-creative-studio/experiments/mcp-genmedia/mcp-genmedia-go/install.sh

👉💻 شغِّل نص الإعداد الأوّلي، وسيطلب منك إدخال رقم تعريف مشروع Google Cloud. وأدخِل رقم تعريف مشروع Google Cloud الذي عثرت عليه في الخطوة الأخيرة عندما يُطلب منك ذلك من خلال النص البرمجي init.sh.

cd ~/agentverse-developer
./init.sh

👉💻 اضبط رقم تعريف المشروع المطلوب:

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 هي أكثر من مجرد أداة، فهي امتداد لإرادتك. يعمل برنامج وكيل الذكاء الاصطناعي المفتوح المصدر هذا، المستند إلى نماذج Gemini، على حلقة "الاستدلال والتنفيذ" (ReAct). ويحلّل نيتك ويختار الأسلوب المناسب وينفّذه ويراقب النتيجة لإكمال المهام المعقّدة. قبل أن تتمكّن من استخدام أسلحة أكثر تخصصًا، عليك إتقان هذا السلاح الأساسي.

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

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

cd ~/agentverse-developer
mkdir tabletop
cd tabletop

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

clear
gemini --yolo

إذا طُلب منك ذلك Do you want to connect Cloud Shell editor to Gemini CLI?، اختَر لا.

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

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

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

/help

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

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

!ls -l

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

/tools

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

👉✨ لا يكون السلاح فعّالاً إلا إذا تم استخدامه بشكل صحيح. يمكن أن يتضمّن 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. لكن لا يمكن إتقان استخدام السيف إلا بعد اختباره في معركة حقيقية. قبل مواجهة العدو الحقيقي، عليك أولاً استكشاف محيطك المباشر وتشكيله، أي ساحة المعركة الرقمية.

نظرة عامة

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

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

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

قصة

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

clear
cd ~/agentverse-developer/tabletop
gemini --yolo

👉✨ باستخدام أمر واحد وفعّال، يمكنك توجيه 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 place holder spot for profile picture.

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

لا يمكن معرفة القيمة الحقيقية لتقنية معيّنة إلا في سيناريو مباشر. أصدر أمرًا لسيفك لبدء محاكاة محلية.

👉✨ في Gemini CLI، أصدِر أمر المحاكاة:

Use Python's built-in web server to start the Shadowblade Profile website you just created.

سيؤكّد Gemini أنّ المحاكاة نشطة.

👀 سيمتثل Gemini CLI، مؤكّدًا أنّ المحاكاة نشطة وأنّ علامتك الرقمية متاحة:

The website is now being served on port 8000. You can access it at http://localhost:8000.

ملاحظة: قد تحتاج الشفرة إلى بضع محاولات لتنفيذ هذا الإجراء بشكل صحيح. إذا استمرت المشكلة بعد 3 أو 4 محاولات، اخرج من Gemini CLI عن طريق كتابة /quit أو الضغط على Ctrl+C مرتين و👉💻 نفِّذ الأمر التالي في الوحدة الطرفية.

python3 -m http.server

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

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

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

Stop the Shadowblade Profile website

👉💻 ملاحظة: إذا كنت تنفّذ هذا الأمر خارج واجهة سطر الأوامر في Gemini، اضغط على Ctrl+C للخروج من خادم http.

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

لهذا السبب، يمارس الحرفيون الأكثر حكمةً أساليبهم الأقوى أو غير المختبَرة في ساحة تدريب محمية، وهي بُعد محصور يُعرف باسم البيئة التجريبية.

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

ينشئ وضع الحماية (gemini --sandbox) في Gemini CLI حاوية مؤقتة ومعزولة لجلسة العمل. إنّ أي أمر ينفّذه الذكاء الاصطناعي، وأي ملف يكتبه، وأي عملية يبدأها، لا يكون متاحًا إلا في هذا العالم الوهمي. ولا يمكنه لمس بيئة Cloud Shell الفعلية أو تغييرها أو إتلافها. إنّها المكان المثالي لاختبار أدوات جديدة وفعّالة أو تحليل رموز غير مألوفة أو تقديم تعليمات معقّدة للذكاء الاصطناعي بدون المخاطرة بعواقب غير مقصودة. إنّها تجسيد لحذر Shadowblade.

👉💻 الآن، ستنفّذ طقس احتواء لتفهم قوته.

clear
gemini --sandbox --yolo
  • إذا طُلب منك Do you want to connect Cloud Shell editor to Gemini CLI?، اختَر لا.
  • اتّبِع التعليمات لتسجيل الدخول إذا طُلب منك ذلك، واحرص على تسجيل الدخول باستخدام تسجيل الدخول باستخدام حساب Google

أنت تعمل الآن ضمن السمة المعزولة. بالنسبة إلى Gemini CLI، سيبدو كل شيء طبيعيًا. لنثبت ذلك.

👉💻 اطلب من الأداة تنفيذ الأسلوب نفسه كما في السابق:

Use the Python's built-in web server to start the Shadowblade Profile website, you just created.

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

👉 انتقِل إلى معاينة الويب وحاوِل عرض موقعك الإلكتروني على المنفذ 8000.

في هذه المرة، سيظهر لك خطأ. سيتعذّر الاتصال. لا يمكنك الوصول إلى الموقع الإلكتروني.

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

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

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

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

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

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

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

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

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

cd ~/agentverse-developer
./gitea.sh

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

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

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

👉 ستظهر صفحة تسجيل الدخول إلى 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 --yolo

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

/mcp

خادم Gitea 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 جديد لك. مستودع Gitea

بعد إعداد الحافظة، يمكنك تأمين عملك. أصدر أمرًا إلى 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 بأمان.

مستودع Giteaمستودع Gitea

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

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

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

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

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

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

echo 'export PATH="$PATH:$HOME/go/bin"' >> ~/.bashrc
source ~/.bashrc
cd ~/vertex-ai-creative-studio/experiments/mcp-genmedia/mcp-genmedia-go
./install.sh

👉 عند المطالبة بذلك، اختَر الخيار mcp-imagen-go (عادةً ما يكون 4 ولكن في بعض الأحيان تتغير الأرقام)، لأنّنا نحتاج فقط إلى إنشاء صورة لملفنا الشخصي.

👉💻 تتطلّب روح الإبداع وعاءً مقدّسًا، أي حزمة Google Cloud Storage، لحفظ إبداعاتها. لِننشئ واحدًا الآن. في الوحدة الطرفية، شغِّل الأمر التالي:

. ~/agentverse-developer/set_env.sh
gcloud storage buckets create gs://$BUCKET_NAME --project=$PROJECT_ID

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

. ~/agentverse-developer/set_env.sh
source ~/.bashrc
jq \
--arg bucket "$BUCKET_NAME" \
--arg project "$PROJECT_ID" \
--arg region "$REGION" \
'.mcpServers.imagen = { "command": "mcp-imagen-go", "env": { "MCP_SERVER_REQUEST_TIMEOUT": "55000", "GENMEDIA_BUCKET": $bucket, "PROJECT_ID": $project, "LOCATION": $region } }' \
~/.gemini/settings.json > tmp.json && mv tmp.json ~/.gemini/settings.json
cat ~/.gemini/settings.json

"طقس التناغم" هذا هو نص برمجي shell يضبط Gemini CLI لاستخدام أداة جديدة وفعّالة، وهي Imagen، نموذج إنشاء الصور من Google. والأهم من ذلك، يتم تحقيق ذلك من خلال إعداد خادم بروتوكول Model Context (MCP) لـ Imagen. يعمل خادم MCP هذا كجسر، ما يتيح لواجهة سطر الأوامر في Gemini التواصل مع إمكانات Imagen والاستفادة منها. ويتم ذلك من خلال تعديل ملف الإعداد المركزي لواجهة سطر الأوامر (CLI) مباشرةً، وهو ~/.gemini/settings.json، لتعليمه كيفية تنفيذ الأمر mcp-imagen-go باستخدام بيانات اعتماد السحابة الإلكترونية الصحيحة.

👀 بعد إكمال الطقس، سيحتوي ملف settings.json على كتلة جديدة تعلّم Gemini CLI مهارة جديدة:

"imagen": {
    "command": "mcp-imagen-go",
    "env": {
        "MCP_SERVER_REQUEST_TIMEOUT": "55000",
        "GENMEDIA_BUCKET": "your-bucket-name",
        "PROJECT_ID": "your-project-id",
        "LOCATION": "your-region"
    }
}

يُعلم ذلك واجهة Gemini CLI بما يلي: "عندما تتطلّب إحدى المهام استخدام أداة Imagen، عليك تنفيذ البرنامج الذي يحمل الاسم mcp-imagen-go (وهو خادم Imagen MCP). عند تشغيلها، يجب تزويدها بهذه البيئة المحدّدة (env): حزمة Google Cloud Storage لحفظ الصور فيها، ورقم تعريف المشروع والموقع الجغرافي المطلوب استخدامهما لواجهات برمجة التطبيقات المستندة إلى السحابة الإلكترونية." من خلال إعداد خادم MCP هذا، يمكنك تزويد واجهة سطر الأوامر Gemini بإمكانية الوصول إلى قدرات Imagen في إنشاء الصور."

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

clear
cd ~/agentverse-developer/tabletop/
gemini --yolo

👉✨ باستخدام أمر واحد وفعّال، يمكنك توجيه Gemini CLI لإنشاء الأساس لهويتك الرقمية. في 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.

👉✨ ابدأ الموقع الإلكتروني لآخر مرة لتشاهد عملك المثالي.

start the website with a simple HTTP server via Python

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

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

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"

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

👉✨ تأكَّد في Gitea من تعديل الصورة وإغلاق المشكلة. اكتمل عملك. أوقِف الخادم.

stop website server

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

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

6. تجميع Shadowblade Agent: رمز الاهتزاز مع الإجراءات الوقائية

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

نظرة عامة

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

The Assembly Ritual

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

قصة

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

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

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

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

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

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

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

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

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

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

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

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

download https://raw.githubusercontent.com/weimeilin79/agentverse/main/developer/shadowblade/agent_design.md  and store it to my local folder
and show me the newly downloaded design doc. Do not attempt to create 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 --yolo

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

/memory show

هذه هي اللحظة المحورية. ستقدّم المخطط (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. في الوقت الحالي، لا يتوفّر في مستودع الأسلحة سوى عدد قليل من الأسلحة.

06-02-story.png

👉✨ لنطلب من 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 مرتين لكي يستريح البطل. اكتملت عملية التجميع.

FOR NON GAMER

7. Wards of Purity: Evaluating the agents

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

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

07-01-story.png

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

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

نظرة عامة

مجموعة أدوات تطوير الوكلاء (ADK) من Google هي مجموعة أدوات توفّرها 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 --yolo

👉✨ اطلب من 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 --yolo

👉✨ استخدِم الطلب التالي في 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 at 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 الدقيق وإثبات صحتهما، لن يكون وكيلك مجرد وكيل وظيفي، بل سيكون وكيلًا نقيًا تم اختباره وجاهزًا للنشر.

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

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

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

قصة

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

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

نظرة عامة

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

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

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

cd ~/agentverse-developer/
clear
gemini --yolo

👉✨ الآن، أرسِل الأمر التالي إلى 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 تنفيذ الاختبار بأكمله.

الخروج من Gemini لاختبار النتيجة

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

. ~/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 Build

اجتاز الوكيل اختبار التحدي. أصبحت الآن قطعة أثرية أصلية معتمدة في ترسانتك. القرار النهائي يعود إليك. باستخدام أمر واحد، يمكنك استدعاء هذا العنصر من السجلّ وتفعيله كخدمة عامة على 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. اكتملت طقوس المخطوطة. حان الوقت لإثبات جدارته. في انتظارك "شبح"، وهو مخلوق وُلد من الفوضى التي تعلّمت كيفية السيطرة عليها. استعدّ للتجربة النهائية.

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

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 نسخته) في هذا الحقل.
  • انقر على "ربط" للاستفادة من ميزة التنقّل السريع.

دائرة الانتقال

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

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

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

Dungeon

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

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

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

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

تهانينا، Shadowblade.

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

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

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

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

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

حذف وكيل Shadowblade على Cloud Run وArtifact Registry Repository

يزيل هذا الأمر وكيل 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

حذف حزمة Google Cloud Storage

يزيل هذا الأمر الحزمة التي يستخدمها خادم Imagen MCP لتخزين الصور التي تم إنشاؤها.

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

. ~/agentverse-developer/set_env.sh
gcloud storage rm -r gs://${BUCKET_NAME} --quiet

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

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

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

rm -rf ~/agentverse-developer
rm -rf ~/agentverse-dungeon
rm -rf ~/vertex-ai-creative-studio
rm -f ~/project_id.txt
rm -rf ~/.gemini # This removes all Gemini CLI configurations, including the MCP server settings.

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