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

تطوير وكيل "حزمة تطوير الوكلاء" المستند إلى المواصفات باستخدام Antigravity وSpec-kit

1. مقدمة

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

ما ستنشئه

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

حجز الطاولات: يمكن للضيوف حجز الطاولات والاطّلاع على الحجوزات، وذلك باستخدام أدوات قاعدة بيانات MCP Toolbox الجديدة وجدول reservations في Cloud SQL.
(تحدّي) – تطوير واجهة مستخدم خاصة بك للوكيل
(تحدّي) – النشر على Google Cloud بمساعدة وكيل Antigravity

يوفّر رمز البداية وكيل ADK يعمل مع البحث في القائمة (الكلمة الرئيسية + الدلالة عبر MCP Toolbox) وتتبُّع التفضيلات الغذائية (عبر ToolContext). يمكنك توسيع نطاقها بدون كتابة الرمز البرمجي للتطبيق يدويًا، إذ تتولّى Antigravity عملية التنفيذ استنادًا إلى مواصفاتك.

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

كيفية إعداد سياق المشروع لكي يفهم Antigravity قاعدة رموز برمجية حالية
كيفية إنشاء مهارات Antigravity وإعداد MCP التي تتضمّن معرفة المجال بالحزمة (مثل مستندات ADK ومهارات الجهات الخارجية) لإعادة استخدامها
كيفية إعداد دستور مشروع تتحقّق منه عمليات سير عمل SDD أثناء التخطيط والتحليل
كيفية استخدام سير عمل Spec-Driven Development (SDD) في Antigravity لإضافة ميزات بشكل منهجي
كيفية توسيع نطاق وكيل ADK باستخدام أدوات جديدة مستندة إلى قاعدة بيانات من خلال MCP Toolbox

المتطلبات الأساسية

تثبيت Google Antigravity وgit على جهازك
حساب على Google Cloud مع تفعيل حساب فوترة نشط
سيكون من المفيد إكمال أربع دورات تدريبية مسبقة حول ADK (أو معرفة مكافئة) لفهم سياق حالة الاستخدام:
إنشاء وكلاء الذكاء الاصطناعي باستخدام حزمة ADK: الأساسيات
إنشاء وكلاء الذكاء الاصطناعي باستخدام حزمة ADK: تزويد الوكلاء بالأدوات
إنشاء وكلاء ذكاء اصطناعي دائمين باستخدام ADK وCloudSQL
نشر وكيل ADK وإدارته ومراقبته على Cloud Run
استخدام قاعدة البيانات كأداة: التوليد المعزّز بالاسترجاع (RAG) المستنِد إلى الذكاء الاصطناعي الوكيل باستخدام ADK وMCP Toolbox وCloud SQL

2. إعداد البيئة

تؤدي هذه الخطوة إلى استنساخ مستودع الرموز البرمجية الأوّلي، والمصادقة باستخدام Google Cloud، وتوفير قاعدة بيانات Cloud SQL، وإعداد بيئة Antigravity المحلية.

تثبيت المتطلبات الأساسية

تأكَّد من أنّ نظامك يتضمّن ملف CLI التنفيذي التالي:

تختلف تعليمات التثبيت حسب نظام التشغيل على جهازك.

إنشاء نسخة طبق الأصل من مستودع التطبيق النموذجي

افتح وحدة طرفية في Antigravity (أو وحدة طرفية في نظامك). أنشئ نسخة طبق الأصل من مستودع الرمز المصدر الخاص بالتطبيق المرافق وأدخِل الدليل:

git clone https://github.com/alphinside/sdd-adk-antigravity-starter.git sdd-adk-agents-agy
cd sdd-adk-agents-agy

افتح المستودع الذي تم استنساخه في Antigravity. ملف->فتح مجلد->اختَر الدليل المستنسخ sdd-adk-agents-agy

أزِل الريموت الأصلي. تنشئ مهام سير عمل SDD فروع git لمواصفات الميزات، وتمنع إزالة وحدة التحكّم عن بُعد إرسال البيانات عن طريق الخطأ إلى مستودع التطبيق الأوّلي:

git remote remove origin

المصادقة باستخدام Google Cloud

نفِّذ أمرَي مصادقة. يفتح كلاهما متصفّحًا لبروتوكول OAuth:

gcloud auth login
gcloud auth application-default login

بما أنّك تعمل على Antigravity بشكل محلي، عليك إثبات ملكية حسابك يدويًا. تتم مصادقة واجهة سطر الأوامر gcloud من خلال auth login. تُصادق application-default login على حِزم تطوير البرامج (SDK) من Google Cloud التي يستخدمها تطبيقك، إذ تعتمد كلّ من طلبات Vertex AI في ADK وCloud SQL Python Connector على "بيانات الاعتماد التلقائية للتطبيقات".

إعداد مشروعك على Google Cloud

اكتب متغيرات الموقع الجغرافي في .env قبل تشغيل نص التهيئة البرمجي للمشروع:

echo "GOOGLE_CLOUD_LOCATION=global" > .env
echo "REGION=us-central1" >> .env

يتم استخدام GOOGLE_CLOUD_LOCATION=global لطلبات البيانات من واجهة Vertex AI / Gemini API.
يُستخدم REGION=us-central1 مع Cloud SQL وبنية Google Cloud Platform الأساسية الأخرى

ملاحظة مهمة: يتم توفير الخطوة أدناه للمساعدة في إعداد مشروع Google Cloud المرتبط بحساب فوترة تجريبي (محدود)، وإذا كنت تفضّل استخدام مشروعك السابق، يمكنك تخطّي الخطوة التالية وتنفيذ الخطوة التالية بدلاً منها:

أضِف اسم مشروعك كمتغيّر GOOGLE_CLOUD_PROJECT في ملف ‎.env

فعِّل مشروعك في الوحدة الطرفية باستخدام الأمر gcloud config set project your-project-id

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

إذا لم تكن متأكدًا من ذلك، يمكنك مواصلة قراءة القسم أدناه

نزِّل نص إعداد المشروع البرمجي وشغِّله. يتم إنشاء مشروع على Google Cloud أو التحقّق من صحته باستخدام فوترة تجريبية، ويتم حفظ رقم تعريف المشروع في .env ثم يتم الحصول على بياناته من المصدر:

curl -sL https://raw.githubusercontent.com/alphinside/cloud-trial-project-setup/main/setup_verify_trial_project.sh -o setup_verify_trial_project.sh

bash setup_verify_trial_project.sh && source .env

تفعيل واجهة برمجة التطبيقات

فعِّل واجهات برمجة التطبيقات المطلوبة:

gcloud services enable \
  aiplatform.googleapis.com \
  sqladmin.googleapis.com \
  compute.googleapis.com \
  cloudresourcemanager.googleapis.com

تثبيت الحِزم التابعة

سنستخدم uv كمدير لمشاريع Python. ‫uv هي حزمة Python سريعة وأداة لإدارة المشاريع مكتوبة بلغة Rust ( المستندات). تستخدم ورشة العمل هذه هذه الحزمة لتحقيق السرعة والبساطة. ثبِّت التبعيات الخاصة بلغة Python:

uv sync

بعد ذلك، عدِّل ملف .env الخاص بأداة ADK باستخدام إعدادات مشروعك:

cat > restaurant_concierge/.env <<EOF
GOOGLE_CLOUD_PROJECT=${GOOGLE_CLOUD_PROJECT}
GOOGLE_CLOUD_LOCATION=global
GOOGLE_GENAI_USE_VERTEXAI=True
EOF

إعداد البنية الأساسية لقاعدة البيانات والبيانات

اضبط كلمة مرور قاعدة البيانات وأضِفها إلى .env:

export DB_PASSWORD=codelabpassword
echo "DB_PASSWORD=${DB_PASSWORD}" >> .env

بعد ذلك، شغِّل النص البرمجي scripts/setup_database.sh لإعداد جميع البنية الأساسية اللازمة. سيؤدي ذلك إلى ما يلي:

إنشاء مثيل Cloud SQL
التحقّق مما إذا كانت الآلة الافتراضية جاهزة
منح أذونات Vertex AI
إنشاء قاعدة بيانات
قاعدة بيانات المحتوى الأساسي
تشغيل خدمة "مجموعة أدوات بروتوكول سياق النموذج" في الخلفية

chmod +x scripts/setup_database.sh
./scripts/setup_database.sh > database_setup.log 2>&1 &

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

الآن، يجب أن يتوفّر لدينا كل مستودع وكيل ADK المطلوب للبدء. سنتحدث الآن أكثر عن Antigravity وSpec-driven development في القسم التالي أثناء انتظار اكتمال كل شيء.

3- استكشاف الرمز البرمجي الأوّلي وفهم نهج Spec-Driven Development

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

بنية المشروع

افتح مشروع مستودع الرموز البرمجية المستنسخ في محرِّر Antigravity وراجِع تخطيط الدليل:

sdd-adk-agents-agy/
├── .agents/
│   ├── workflows/                 # SDD slash commands (/speckit.*) – manual trigger
│   │   ├── speckit.specify.md
│   │   ├── speckit.clarify.md
│   │   ├── speckit.plan.md
│   │   ├── speckit.tasks.md
│   │   ├── speckit.analyze.md
│   │   ├── speckit.implement.md
│   │   ├── speckit.checklist.md
│   │   └── speckit.constitution.md
│   ├── skills/                   # Antigravity skills (loaded on demand, agent determined)
│   │   ├── mcp-toolbox-postgres/
│   │   │   └── SKILL.md     # MCP Toolbox config skill
│   │   └── repo-research/
│   │       └── SKILL.md     # Repo analysis skill
│   └── rules/               # Always-active context
├── .specify/                # spec-kit SDD templates and memory
│   ├── memory/constitution.md
│   ├── templates/
│   └── scripts/
├── restaurant_concierge/    # ADK agent package
│   ├── __init__.py
│   ├── agent.py             # LlmAgent + ToolContext tools + Toolbox integration
│   └── .env                 # Vertex AI configuration
├── server.py                # FastAPI server wrapping the agent
├── tools.yaml               # MCP Toolbox tool definitions
├── scripts/                 # Setup scripts
└── pyproject.toml

الملفات الرئيسية

ملفات طلبات الوكلاء

restaurant_concierge/agent.py: الوكيل الأساسي LlmAgent يجمع بين أدوات قاعدة بيانات MCP Toolbox وتتبُّع التفضيلات الغذائية المستند إلى ToolContext. يحمّل الوكيل جميع الأدوات من خادم "مجموعة الأدوات" ويضيف دالتَي Python (save_dietary_preference وget_dietary_preferences) اللتين تستخدمان ToolContext لإدارة الحالة.
tools.yaml: تعريفات أدوات مجموعة أدوات MCP تم تحديد ثلاث أدوات بحث في القائمة: البحث عن الكلمات الرئيسية (search_menu) والبحث الدلالي من خلال pgvector (semantic_search_menu) وفلتر الفئات (get_menu_by_category). لا تتوفّر أدوات الحجز بعد، وسيتمّ إضافتها لاحقًا
server.py: خادم FastAPI بسيط يعرض كيفية الوصول إلى ADK ككائن FastAPI. توفر get_fast_api_app() من "حزمة تطوير التطبيقات" نقاط نهاية مدمجة، بما في ذلك /run_sse لبث SSE وواجهات برمجة تطبيقات لإدارة الجلسات.

ملفات Antigravity

.agents/skills/mcp-toolbox-postgres/SKILL.md: مهارة ترشد Antigravity إلى كيفية إنشاء إعدادات صحيحة لملف tools.yaml في MCP Toolbox. ستعلّمك هذه المهارة كيفية ضبط إعدادات sources وtools وembeddingModels المطلوبة لإنشاء مسار RAG مناسب. لن يتم تفعيل هذه المهارة إلى أن تضيف بيانات YAML أولية مناسبة لكي يتعرّف عليها Antigravity
.agents/skills/repo-research/SKILL.md: هي مهارة تعلّم Antigravity كيفية تحليل مستودع بشكل تدريجي وإنشاء مستند منظَّم لسياق المشروع. تتّبع هذه الأداة نهجًا من 4 مراحل: المسح السطحي (شجرة الدليل فقط)، وملفات الإعداد والبيانات الوصفية، ونقاط الدخول ونماذج البيانات، ثم عمليات التدقيق المتعمّق المستهدَفة. تتوقف كل مرحلة وتكتب النتائج قبل الانتقال إلى المرحلة التالية. تظل أيضًا غير نشطة إلى أن تضيفوا YAML frontmatter لاحقًا. بعد التفعيل، يمكنك استدعاء هذه الأداة لإنشاء .agents/rules/project-context.md، وهو مستند شامل لإعداد التطبيق يتضمّن البنية والتبعيات في وقت التشغيل وواجهة برمجة التطبيقات ومسرد المصطلحات الخاصة بالمجال.

تطوير مستند إلى المواصفات: من التخطيط المضمّن في Antigravity إلى التطوير المنظَّم المستند إلى المواصفات

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

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

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

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

خطة التنفيذ: نظرة عامة على النهج الفني المقترَح والتغييرات في الملفات وقرارات البنية
قائمة المهام: هي تقسيم منظَّم لعناصر العمل

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

يستند هذا الدرس التطبيقي حول الترميز إلى هذا الأساس، ويقدّم سير عمل خاضعًا للتحكّم في الإصدارات يستند إلى spec-kit، وهو إطار عمل للتطوير يستند إلى المواصفات من GitHub. تخضع كل ميزة لمسار مدروس، حيث يكون كل عنصر عبارة عن مستند مستقل يمكنك مراجعته وتعديله وتتبُّعه في git. يتضمّن مسار التعلّم مرحلتَين اختياريتَين لبوابة الجودة (التوضيح والتحليل) لرصد المشاكل قبل أن تصبح مشاكل في التنفيذ:

المرحلة	القطع الأثرية	Purpose
`/speckit.specify`	`spec.md`	تحديد ما يجب إنشاؤه (موجّه للمستخدمين، ولا يعتمد على التكنولوجيا)
`/speckit.clarify` (اختياري)	آخر تحديث: `spec.md`	تحديد المجالات غير المحدّدة بشكل كافٍ، وطرح أسئلة توضيحية مستهدفة، وإعادة ترميز الإجابات في المواصفات
`/speckit.plan`	‫`plan.md`، `data-model.md`، `research.md`	تصميم طريقة إنشاء المنتج (الأسلوب الفني ونماذج البيانات والبحث)
`/speckit.tasks`	`tasks.md`	تقسيم الخطة إلى خطوات عملية منظَّمة
`/speckit.analyze` (اختياري)	تقرير التحليل	راجِع المهام بحثًا عن المخاطر أو الثغرات أو حالات الاستخدام غير الشائعة قبل التنفيذ
`/speckit.implement`	تغييرات الرمز	تنفيذ المهام ووضع علامة بجانب كل مهمة

يتم الاحتفاظ بكل عنصر كملف في specs/<feature-branch>/، ويتم التحكّم في الإصدارات باستخدام git، ويمكن إعادة استخدامه. إذا تمت مقاطعة محادثة أو أردت إعادة النظر في القرارات لاحقًا، ستكون مستندات المواصفات متاحة دائمًا، ولن يتم إخفاؤها في سجلّ المحادثات.

يتضمّن مستودع الرموز البرمجية الأوّلي عمليات سير عمل SDD التالية في .agents/workflows/ ونماذج في .specify/templates/. ستستخدمها لاحقًا لإضافة ميزات إلى الوكيل.

4. بدء مشروع باستخدام Antigravity

الآن، لنحاكي الأمور بشرط "أقرب قليلاً" إلى عملنا اليومي:

مستودع غير مُدار بشكل جيد
ملف README قديم
عدم تعديل المستندات بشكل متكرّر

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

ويتم أيضًا إعداد دستور المشروع، أي المبادئ غير القابلة للتفاوض التي تتحقّق منها عمليات سير عمل SDD. توفّر هذه العناصر معًا السياق والقيود التي تحتاج إليها Antigravity لدورات SDD لاحقًا

التسلسل الهرمي لسياق Antigravity

تستخدم Antigravity ثلاثة مستويات من السياق، ولكل منها نطاق مختلف:

القواعد (.agents/rules/): تعليمات نشطة دائمًا يمكن لكل محادثة في مساحة العمل هذه الاطّلاع عليها ( إذا فعّلتها). استخدِم القواعد لتوفير سياق على مستوى المشروع، مثل قرارات التصميم أو معايير الترميز أو معلومات حزمة التكنولوجيا.
المهارات (.agents/skills/): معلومات عند الطلب لا تحمّل Antigravity مهارة إلا عندما تتطابق المهمة الحالية مع حقل description الخاص بالمهارة. استخدام المهارات للحصول على مواد مرجعية خاصة بمجال معيّن
مهام سير العمل (.agents/workflows/): طلبات محفوظة يتم تشغيلها باستخدام أوامر /. استخدِم سير العمل للعمليات المتكررة المتعدّدة الخطوات، مثل مسار SDD.

تفعيل المهارات

يتضمّن مستودع الرموز البرمجية الأولي مهارتَين مكتوبتَين مسبقًا في .agents/skills/. تحتوي هذه الملفات على تعليمات مفصّلة، ولكنها تبدأ بتعليقات TODO(codelab) بدلاً من YAML frontmatter المطلوب. بدون frontmatter، لا يمكن لـ Antigravity اكتشافها.

تتطلّب مهارات Antigravity كتلة بيانات YAML أولية في أعلى الملف تتضمّن حقلَين:

name: معرّف فريد للمهارة
description: ملخّص باللغة الطبيعية يطابقه Antigravity عند تحديد المهارة التي سيتم تحميلها لطلب معيّن

افتح الملف ‎ .agents/skills/mcp-toolbox-postgres/SKILL.md في المحرِّر. استبدِل أسطر التعليقات TODO(codelab) في الأعلى بما يلي:

---
name: mcp-toolbox-postgres
description: Configure MCP Toolbox for PostgreSQL — sources, tools, and embedding models
---

افتح الملف ‎ .agents/skills/repo-research/SKILL.md في المحرّر. استبدِل أسطر التعليقات TODO(codelab) في الأعلى بما يلي:

---
name: repo-research
description: Analyze a repository's structure, technologies, and patterns to create or update a project context document. Use when asked to research, analyze, or understand a codebase.
---

تأكَّد من أنّ كلتا المهارتين تتضمّنان بيانات أولية صالحة:

head -4 .agents/skills/mcp-toolbox-postgres/SKILL.md
head -4 .agents/skills/repo-research/SKILL.md

يجب أن يعرض كلّ منها محدّدات --- تحيط بالحقلَين name: وdescription:. في حال عدم توفّر المحددات أو الحقول، لن يتعرّف Antigravity على المهارة.

يتم تحميل كلتا المهارتين عند الطلب، إذ تطابق Antigravity طلبك مع الحقل description وتجلب التعليمات الكاملة فقط عندما تكون ذات صلة.

إعداد MCP في مستندات ADK

لضمان توفّر المعرفة الصحيحة لدى وكيل الترميز حول كيفية تطوير وكيل ADK، يجب أن يتمكّن من الوصول بشكل صحيح إلى مستندات ADK. يمكننا تفعيل ذلك من خلال إعداد خادم MCP لمستندات ADK .

أولاً، من محرر Antigravity، ابحث عن رمز "علامة الحذف" في أعلى يسار نافذة الوكيل وانقر عليه، وستظهر لك خيارات الإعداد الخاصة بـ MCP والتخصيص على النحو التالي. انقر على MCP.

بعد ذلك، انقر على الزر Manage MCP servers

سيتم فتح علامة التبويب "إعدادات خوادم MCP"، ثم انقر على الزر View Raw Config

سيتم فتح ملف mcp_config.json. الآن، انسخ هذا الإعداد والصقه في الملف

{
    "mcpServers": {
        "adk-docs-mcp": {
            "command": "uvx",
            "args": [
                "--from",
                "mcpdoc",
                "mcpdoc",
                "--urls",
                "AgentDevelopmentKit:https://adk.dev/llms.txt",
                "--transport",
                "stdio"
            ]
        }
    }
}

سيسمح هذا الإعداد لوكيل الترميز بالبحث عن مستندات ADK وقراءتها باستخدام خادم MCP

تثبيت المهارات المتاحة للجميع

لقد فحصنا سابقًا المهارات التي أنشأناها بأنفسنا ( المهارتان repo-research وmcp-toolbox-postgres). ومع ذلك، هناك العديد من المهارات الأخرى المفيدة لدعم تطوير البرامج ويمكن تثبيتها بسهولة على وكيل الترميز.

Caveman Skills

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

npx skills add JuliusBrussee/caveman

كما فعلنا سابقًا، لنحدّد مهارة caveman هنا في الوقت الحالي

بعد ذلك، ما عليك سوى النقر على Enter للانتقال إلى الخيار الآخر لتفعيل التثبيت التلقائي وتثبيت المهارة في مشروعك الحالي.

الآن، من المفترض أن يكون لدينا 4 مهارات تم إعدادها وجاهزة لبدء رحلة SDD

.agents/skills/
├── caveman
├── mcp-toolbox-postgres
└── repo-research

إنشاء سياق المشروع

تأكَّد من توفّر دليل القواعد:

mkdir -p .agents/rules

في مربّع "إدارة الوكلاء"/"المحادثة" في Antigravity (في وضع التعديل، اضغط على ctrl + L)، ابدأ محادثة جديدة. النوع:

Research this repository and create a project context document, and communicate efficiently

تطابق Antigravity طلبك مع مهارة repo-research وcaveman ( أمر للتواصل بكفاءة)، وتبدأ في تحليل قاعدة الرموز البرمجية بشكل منهجي. يقرأ ملفات الإعدادات ورمز المصدر والمستندات، ثم يملأ نموذج سياق المشروع بالنتائج التي يتوصّل إليها.

بعد اكتمال العملية، افتح .agents/rules/project-context.md في المحرِّر. يتضمّن معلومات ملموسة حول المشروع: مجموعة التكنولوجيات (Python 3.12 وADK وMCP Toolbox وCloud SQL) وبنية المشروع ونموذج البيانات (جدول menu_items مع pgvector) وعمليات التكامل الخارجية.

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

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

تحديد دستور المشروع

تشير إجراءات سير عمل SDD إلى دستور المشروع في .specify/memory/constitution.md أثناء التخطيط والتحليل. ينفّذ سير عمل /speckit.plan "عملية التحقّق من الدستور"، ويضع /speckit.analyze علامة على الانتهاكات باعتبارها "خطيرة". إذا تم ترك الدستور كنموذج فارغ مع رموز مميّزة للقيم النائبة، لن يكون هناك أي شيء يمكن التحقّق منه، وستعمل الخطط والتحليلات بدون ضوابط وقائية.

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

في "إدارة الوكلاء" (Agent Manager) من Antigravity، ابدأ محادثة جديدة. نفِّذ سير عمل الدستور:

/speckit.constitution This is a small restaurant concierge ADK agent maintained by one developer. Set 3 principles: (1) All database operations go through MCP Toolbox tool definitions in tools.yaml — no raw SQL in Python code, no ORM. (2) Session state uses ADK ToolContext — no custom state management, no external state stores. (3) Keep it simple — follow existing file and naming conventions exactly.

تعبئ Antigravity نموذج الدستور بمبادئ ملموسة، وتعيّن إصدارًا (1.0.0)، وتجري عملية تحقّق من الاتساق في جميع نماذج SDD.

راجِع الدستور الذي تم إنشاؤه على .specify/memory/constitution.md. تأكَّد من توفّر المبادئ الثلاثة وذكرها بوضوح.

5- SDD Cycle — Add Reservation Feature

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

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

تحديد الميزة

في "إدارة الوكلاء" (Agent Manager) من Antigravity، ابدأ محادثة جديدة. اكتب أمر سير العمل /speckit.specify مع وصف الميزة:

/speckit.specify Add reservation booking capability to the restaurant concierge agent. Guests should be able to make a table reservation by providing their name, party size, date, and time. They should also be able to check existing reservations. The agent should confirm reservation details before booking and handle special requests (e.g., "window seat", "birthday celebration").

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

تركّز المواصفات على الهدف والسبب، وليس على طريقة التنفيذ. تصف هذه السمة تجربة المستخدم ("يمكن للضيوف حجز طاولة من خلال تقديم الاسم وعدد الأشخاص والتاريخ والوقت") بدون ذكر جداول SQL أو tools.yaml أو واجهات برمجة التطبيقات الخاصة بحزمة تطوير التطبيقات. تأتي تفاصيل التنفيذ في مرحلة التخطيط.

راجِع المواصفات التي تم إنشاؤها في specs/<branch-name>/spec.md. تأكَّد من أنّها تتضمّن المتطلبات الوظيفية ومعايير النجاح.

توضيح المواصفات (اختياري)

نفِّذ سير عمل التوضيح لتحديد المناطق غير المحدّدة بشكلٍ كافٍ في المواصفات وحلّها:

/speckit.clarify

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

التخطيط للتنفيذ

اتّبِع سير عمل التخطيط:

/speckit.plan Update the restaurant concierge agent to multi agent architecture which separate responsibilities for handling menu and reservations. Utilize your access to ADK Docs tools and MCP toolbox skill to implement it properly

تُنشئ Antigravity خطة فنية من خلال مرحلتَين:

مرحلة البحث: يتم فيها حلّ المشاكل غير المعروفة في قاعدة الرموز البرمجية الحالية، وإنشاء research.md
مرحلة التصميم: يتم فيها إنشاء data-model.md (تعريف عنصر الحجوزات) وتعديل project-context.md

يجب أن تستخدم Antigravity أدوات MCP في مستندات ADK ومهارة مستندات MCP Toolbox أثناء التخطيط. راجِع البيانات الرئيسية:

specs/<branch-name>/plan.md — النهج الفني: الملفات التي يجب تعديلها، والأنماط التي يجب اتّباعها
specs/<branch-name>/data-model.md: تعريف عنصر الحجوزات (الأعمدة والأنواع والعلاقات)
specs/<branch-name>/research.md: القرارات المتخذة وأسبابها

إنشاء مهام

تنفيذ سير عمل المهام

/speckit.tasks

تقسّم Antigravity الخطة إلى قائمة مهام منظَّمة في specs/<branch-name>/tasks.md. تتّبع المهام تنسيق قائمة التحقّق الصارم مع المعرّفات وعلامات الأولوية ومسارات الملفات، على سبيل المثال:

- [ ] [T001] [P] Create reservations table schema in scripts/seed_db.py
- [ ] [T002] [P] Add create_reservation tool to tools.yaml
- [ ] [T003] [P] Add list_reservations tool to tools.yaml
- [ ] [T004] [P] Update agent instruction in restaurant_concierge/agent.py

يتم تنظيم المهام في مراحل: الإعداد → الأساسية → قصص المستخدمين → التحسين. افحص قائمة المهام لمعرفة ما سيتم إنشاؤه وتعديله.

تحليل المهام (اختياري)

نفِّذ سير عمل التحليل لمراجعة المهام بحثًا عن المخاطر والثغرات:

/speckit.analyze

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

6. التنفيذ

نفِّذ سير عمل التنفيذ:

/speckit.implement

تعرض Antigravity خطة تنفيذ نهائية وأداة مهمة. يجب مراجعتها والموافقة عليها للمتابعة.

تنفّذ Antigravity المهام، وتضع علامة بجانب كل مهمة عند إكمالها. عند الانتهاء، سيتم عرض الجولة الإرشادية الكاملة.

اختبار تغييرات الرمز

بعد اكتمال عملية التنفيذ، تحقَّق من إجراء التغييرات الرئيسية. قد تختلف أسماء الملفات ومحتواها الدقيق، ولكن يجب أن تكون هذه الأنماط متوفرة كما في tools.yaml وagent.py:

# Verify reservation tools were added to tools.yaml
grep -i "reservation" tools.yaml

ستظهر لك بعض النتائج على النحو التالي

...
get_reservations_by_name:
      Retrieve all reservations for a guest by their name. Uses case-insensitive
      SELECT id, guest_name, party_size, reservation_datetime, special_requests, created_at
      FROM reservations
      ORDER BY reservation_datetime DESC
...

بالنسبة إلى agent.py

# Verify agent instruction was updated
grep -i "reservation" restaurant_concierge/agent.py

# Check what files changed
git diff --name-only

ربما ستجد تغييرات مثل هذه

...
- **Table Reservations**: Help guests book a table or check their existing reservations.
## Reservation Booking Rules
When a guest wants to make a reservation, collect ALL of the following before confirming:
**IMPORTANT**: Before calling `book_reservation`, you MUST:
- Only call `book_reservation` after the guest says "yes" or "confirm"
## Checking Reservations
When a guest asks to check their reservations:
- Use `get_reservations_by_name` to find their bookings
        book_reservation,
...

من المفترض أن تؤثّر التغييرات في نص قاعدة البيانات الأولية. يجب أن ينشئ النص البرمجي المعدَّل الجدول reservations إذا لم يكن موجودًا من قبل. من المفترض أن يظهر لك ناتج يؤكّد أنّه تم إنشاء الجدول الجديد (مع الاحتفاظ ببيانات menu_items الحالية).

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

lsof -ti:5000 | xargs kill -9 2>/dev/null; echo "Done"
./scripts/setup_database.sh > database_setup.log 2>&1 &

يمكنك الاطّلاع على سجلّ الإخراج في database_setup.log لمعرفة ما إذا كان Antigravity ينشئ الرمز والإعدادات الصحيحة أم لا. في حال حدوث خطأ، حاوِل التفاعل مع الوكيل لحلّه

إذا سارت الأمور على ما يرام، يمكننا بدء واجهة مستخدم مطوّر ADK:

uv run adk web .

افتح http://localhost:8000 في المتصفّح وجرِّب هذه الطلبات:

I'd like to book a table for 4 people on Friday at 7pm under the name Timmy

Do I have any upcoming reservations?

الآن، أوقِف واجهة مستخدم ADK Dev UI بالضغط على Ctrl+C مرتين.

7. التحديات (اختياري)

أصبحت الآن على دراية بسير عمل SDD الكامل. اختبار الميزة:

نفِّذ دورة ثانية من عملية التصميم المستند إلى البيانات (SDD) لإنشاء واجهة محادثة على الويب لخدمة الكونسيرج في المطعم، ولكن بدون إرشادات تفصيلية هذه المرة.
نشر الوكيل على Cloud Run لسيناريو الإنتاج

تلميحات

لا يتضمّن المشروع أي إطار عمل للواجهة الأمامية. يجب أن تقترح Antigravity استخدام HTML/CSS/JS العادي. وإذا اقترحت استخدام React أو ما شابه، يجب توجيهها نحو البساطة (يجب أن يرصد مبدأ "البساطة" في دستورك هذا الاقتراح).
يعرض خادم ADK /run_sse للبث و/apps/{app_name}/users/{user_id}/sessions لإدارة الجلسات. تكتشف Antigravity هذه المعلومات من سياق المشروع.
بعد التنفيذ، ابدأ الخادم باستخدام uv run uvicorn server:app --host 0.0.0.0 --port 8080 (وليس adk web) حتى يعمل تركيب الملف الثابت.
يمكنك إجراء الاختبار على http://localhost:8080/static/index.html.
توضّح دروس الترميز المرجعية كيفية نشر وكيل ADK والحفاظ عليه، لذا يمكنك الرجوع إلى هذه الدروس في Antigravity.

8. تهانينا!

لقد وسّعت نطاق وكيل ADK الخاص بموظف الاستقبال في المطعم ليشمل حجز المواعيد، وذلك من خلال مهام سير عمل SDD في Antigravity بالكامل، بدون كتابة الرمز البرمجي للتطبيق يدويًا.

ما أنشأته

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

ما تعلّمته

كيفية استخدام سير عمل Spec-Driven Development في Antigravity لإضافة ميزات بشكل منهجي إلى قاعدة رموز برمجية حالية
كيفية إنشاء مهارات Antigravity وإعداد MCP التي تحزم معرفة المجال لإعادة استخدامها في المحادثات
كيفية إعداد سياق المشروع الأوّلي لكي يتخذ Antigravity قرارات مدروسة بشأن البنية والأنماط وخيارات التكنولوجيا
كيفية ضبط دستور مشروع تتحقّق منه مهام سير عمل SDD
كيفية توسيع نطاق وكيل ADK باستخدام أدوات جديدة مستندة إلى قاعدة بيانات من خلال MCP Toolbox

تَنظيم

أوقِف أي عمليات محلية قيد التشغيل (Toolbox):

lsof -ti:5000 | xargs kill -9 2>/dev/null

احذف مثيل Cloud SQL لتجنُّب الرسوم المستمرة:

gcloud sql instances delete restaurant-db --quiet

يمكنك اختياريًا حذف المشروع بأكمله:

gcloud projects delete $GOOGLE_CLOUD_PROJECT