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

1. Overture

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

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

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

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

مرحبًا بك في The Agentverse: A Call to Champions

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

agentverse.png

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

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

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

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

اختيار صفك

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

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

مهمتك

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

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

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

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

2. The Shadowblade's Codex

يقع كتاب Shadowblade مفتوحًا أمامك. الردّ على المكالمة يواجه عالم 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

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

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

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

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

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

cd ~/agentverse-developer
./init.sh

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

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

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

03-05-project-all.png

👉💻 العودة إلى 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 هي أكثر من مجرد أداة، فهي امتداد لإرادتك. يعمل وكيل الذكاء الاصطناعي المفتوح المصدر هذا، المستند إلى نماذج 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. هذه هي الأساليب التلقائية التي يمكنك الاستعانة بها بدون الحاجة إلى استخدام أدوات خارجية.

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

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

لا يُعرف محارب الظل الحقيقي بسلاحه فحسب، بل بأسلوبه المميز، أي علامة الصانع. ستكون هذه العلامة هي حضورك الرقمي، وهي عبارة عن ملف شخصي يعرّف هويتك على 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 place holder spot for profile picture. Do not attempt to start the server.

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

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

python -m http.server

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

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

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

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

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

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

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

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

سنركّز اليوم على قوتَين أساسيتَين لا غنى عنهما لأي "مبتكر أجواء": القدرة على التحكّم في المصنع والقدرة على الابتكار من الخيال. عليك أولاً ربط أداة Blade بخادم 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

👉✨ تأكَّد من أنّ السلاح الجديد قد تم اكتشافه. اطلب منه إدراج جميع المستودعات المتاحة من خلال بوابات 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 Protocol (MCP) لـ Imagen. يعمل خادم MCP هذا كجسر، ما يتيح لواجهة سطر الأوامر Gemini التواصل مع إمكانات Imagen والاستفادة منها. ويتم ذلك من خلال تعديل ملف الإعداد المركزي الخاص بواجهة سطر الأوامر، ~/.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

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

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

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

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

👉✨ في نافذة الوحدة الطرفية التي يتم فيها تشغيل 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، ثم انقر على تغيير ومعاينة. ستظهر معاينة لموقعك الإلكتروني. Fixed

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

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

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

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

نظرة عامة

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

The Assembly Ritual

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

قصة

يمكن أن يساعدك 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  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

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

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

ستلاحظ أنّ هذا ليس مجرد ملف إعداد، بل هو تعويذة مكتوبة بلغة بايثون. جوهر هذه التعويذة هو السطر 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

👉✨ الآن، أرسِل الأمر التالي إلى 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 الخاص بدائرة الانتقال المكاني في المتصفّح للوقوف أمام البوابة المتلألئة المؤدية إلى "قلعة القرمزي".

لاختراق الحصن، يجب أن تتوافق جوهر "سيف الظلال" مع البوابة.

  • في الصفحة، ابحث عن حقل إدخال الأحرف الرونية الذي يحمل التصنيف عنوان 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. مشروعك نظيف، وأنت مستعد لمغامرتك التالية.