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

1. مقدمة

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

ما ستنشئه

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

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

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

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

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

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

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

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

ملاحظات مهمة:

يتطلّب هذا البرنامج التعليمي مشروعًا على Google Cloud مع حساب فوترة نشط. إذا لم يكن لديك حساب بعد، يُرجى اتّباع الخطوات التالية للحصول على حساب فوترة تجريبي يمكن استخدامه في هذا البرنامج التعليمي:

1. فتح نافذة التصفُّح المتخفي
2. إذا كنت ستنضم إلى جلسة ورشة عمل، سيتم عادةً تقديم عنوان URL لبوابة الاسترداد في الجلسة، وإلا يمكنك الانتقال إلى بوابة استرداد حساب الفوترة التجريبي.
3. سجِّل الدخول باستخدام حسابك الشخصي على Gmail ( لن تعمل حسابات Google Workspace أو عناوين البريد الإلكتروني الأخرى). )
4. اتّبِع تعليمات تحصيل القيمة المفصّلة.

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

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

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

افتح وحدة طرفية في 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

ملاحظة مهمة: تستخدم مهام سير عمل SDD في هذا الدرس التطبيقي فروع git لتنظيم مواصفات الميزات. تضمن إزالة الريموت origin بقاء الفروع وعمليات الدمج محلية. إذا أردت الاحتفاظ بنسخة احتياطية من عملك، أضِف جهاز تحكّم عن بُعد خاصًا بك: git remote add origin <your-repo-url>

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

شغِّل النص البرمجي للمتطلبات الأساسية. يبحث عن git وcurl وgcloud وuv وPython 3.12 وMCP Toolbox (ويثبّتها إذا لم تكن متوفّرة):

bash scripts/setup_prerequisites.sh

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

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

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

gcloud auth login
gcloud auth application-default login

ملاحظات: في أمر OAuth الثاني، عندما يُطلب منك اختيار الإذن. الاطّلاع على جميع الخيارات

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

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

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

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

توفير Cloud SQL

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

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

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

أنشئ مثيل Cloud SQL:

gcloud sql instances create restaurant-db \
  --database-version=POSTGRES_17 \
  --edition=ENTERPRISE \
  --region=${REGION} \
  --availability-type=ZONAL \
  --tier=db-custom-1-3840 \
  --root-password=${DB_PASSWORD} \
  --enable-google-ml-integration \
  --database-flags cloudsql.enable_google_ml_integration=on &

إنّ مستوى db-custom-1-3840 هو الحدّ الأدنى المطلوب لدمج تعلُّم الآلة في Vertex AI. يتيح الخيار --enable-google-ml-integration لخدمة Cloud SQL استدعاء نماذج التضمين في Gemini مباشرةً من SQL، ما يتيح استخدام ميزة البحث الدلالي.

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

تثبيت التبعيات

افتح علامة تبويب جديدة في الوحدة الطرفية. تأكَّد من أنّك لا تزال في دليل مشروع مستودع الرموز البرمجية المستنسخ وأعِد تحميل متغيرات البيئة:

source .env

سنستخدم 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

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

3- استكشاف الرمز الأولي وفهم عملية التطوير المستندة إلى المواصفات

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

بنية المشروع

افتح مشروع مستودع الرموز البرمجية المستنسخ في محرِّر 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)
│   │   ├── adk-agent-development/
│   │   │   ├── SKILL.md     # ADK patterns
│   │   │   └── examples/
│   │   │       ├── basic_agent.py
│   │   │       ├── Dockerfile
│   │   │       ├── server.py
│   │   │       ├── stateful_agent.py
│   │   │       ├── toolbox_agent.py
│   │   │       ├── tools_agent.py
│   │   │       └── tools.yaml
│   │   └── repo-research/
│   │       └── SKILL.md     # Repo analysis 
│   └── 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 Toolbox تم تحديد ثلاث أدوات بحث في القائمة: البحث عن الكلمات الرئيسية (search_menu)، والبحث الدلالي من خلال pgvector (semantic_search_menu)، وفلتر الفئات (get_menu_by_category). لا تتوفّر أدوات الحجز بعد، وسيتمّ إضافتها لاحقًا
• server.py: خادم FastAPI بسيط يعرض كيفية الوصول إلى ADK ككائن FastAPI. توفّر get_fast_api_app() من "حزمة تطوير التطبيقات" نقاط نهاية مدمجة، بما في ذلك /run_sse لبث SSE وواجهات برمجة تطبيقات لإدارة الجلسات.

Antigravity Files

• .agents/skills/adk-agent-development/SKILL.md: مهارة تم ضبطها مسبقًا ( تم إنشاؤها باستخدام Antigravity) تحتوي على أنماط مرجعية مكثّفة من جميع دروس ADK البرمجية الأربعة. وهي غير نشطة حاليًا (لا تتضمّن YAML frontmatter)، لذا عليك تعديلها لاحقًا. تحمّل Antigravity هذه المهارة تلقائيًا عندما ترصد عملًا مرتبطًا بميزات وكيل ADK وأمثلتها، وهي المعرفة التي ترشد Antigravity عند التخطيط لميزة الحجز لاحقًا.
• .agents/skills/repo-research/SKILL.md: هي مهارة تعلّم Antigravity كيفية تحليل مستودع بشكل تدريجي وإنشاء مستند منظَّم لسياق المشروع. تستخدم هذه الأداة نهجًا من 4 مراحل: الفحص السطحي (شجرة الدليل فقط)، وملفات الإعداد والبيانات الوصفية، ونقاط الدخول ونماذج البيانات، ثم عمليات التدقيق المستهدفة. تتوقف كل مرحلة وتكتب النتائج قبل الانتقال إلى المرحلة التالية. وكما هو الحال مع مهارة ADK، تظل هذه الميزة غير نشطة إلى أن تضيف YAML frontmatter لاحقًا. بعد التفعيل، يمكنك استدعاء هذه الأداة لإنشاء .agents/rules/project-context.md، وهو مستند شامل لإعداد التطبيق يتضمّن البنية والتبعيات في وقت التشغيل ومساحة واجهة برمجة التطبيقات ومسرد المصطلحات الخاصة بالمجال.

Spec-Driven Development: from Antigravity's built-in planning to structured SDD

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

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

ملاحظات: يتميّز العنصر المضمّن في Antigravity بواجهة مستخدم تتيح للمستخدمين التعليق على العنصر الذي تم إنشاؤه ( حتى على الصور!). ). وبالتالي، في هذا البرنامج التعليمي، سنعدّل طلب spec-kit الأصلي لدمجه مع العنصر المضمّن في implement مرحلة

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

4. إكمال عملية إعداد Cloud SQL والتأكّد من أنّ Base Agent يعمل بشكل سليم

ارجع إلى علامة تبويب الوحدة الطرفية التي يتم فيها تنفيذ أمر إنشاء Cloud SQL. بعد اكتمالها، تحقَّق من أنّ الجهاز الظاهري جاهز:

gcloud sql instances describe restaurant-db --format="value(state)"

إذا كانت المخرجات تعرض RUNNABLE، انتقِل إلى الخطوة التالية. إذا ظهرت PENDING_CREATE، انتظِر لحظة وأعِد تنفيذ الأمر.

امنح حساب خدمة Cloud SQL إذن الوصول إلى Vertex AI (مطلوب لوظيفة التضمين داخل قاعدة البيانات):

SERVICE_ACCOUNT=$(gcloud sql instances describe restaurant-db --format="value(serviceAccountEmailAddress)")

gcloud projects add-iam-policy-binding $GOOGLE_CLOUD_PROJECT \
  --member="serviceAccount:$SERVICE_ACCOUNT" \
  --role="roles/aiplatform.user" \
  --quiet

أنشئ قاعدة البيانات:

gcloud sql databases create restaurant_db --instance=restaurant-db

من المفترض أن تظهر لك النتيجة على النحو التالي

Creating Cloud SQL database...done.
Created database [restaurant_db].
instance: restaurant-db
name: restaurant_db
project: <your-project-id>

نقطة التحقّق: يحتوي ملف .env على GOOGLE_CLOUD_PROJECT وGOOGLE_CLOUD_LOCATION وREGION وDB_PASSWORD. مثيل Cloud SQL restaurant-db قيد التشغيل. يتوفّر toolbox في PATH (تم تثبيته بواسطة setup_prerequisites.sh)، وتم تثبيت تبعيات Python.

تعبئة قاعدة البيانات

حمِّل متغيرات البيئة وشغِّل نص برمجي لإنشاء قاعدة البيانات من أجل إنشاء المخطط وإدراج 16 عنصرًا من عناصر القائمة:

source .env
uv run python scripts/seed_db.py

الناتج المتوقّع:

Creating extensions...
Creating menu_items table...
Inserting 16 menu items...
Seeded 16 menu items.
Done.

إنشاء تضمينات متجهة للبحث الدلالي:

uv run python scripts/generate_embeddings.py

الناتج المتوقّع:

Generating embeddings for 16 menu items...
Generated embeddings for 16 menu items.

يستخدم هذا الإجراء الدالة embedding() المضمّنة في Cloud SQL (من خلال الإضافة google_ml_integration) لاستدعاء gemini-embedding-001 مباشرةً من SQL. يتم تخزين المتّجهات ذات 3072 بُعدًا في العمود embedding من menu_items، بدون الحاجة إلى رمز التضمين من جهة التطبيق.

اختبار الوكيل الأساسي

ابدأ تشغيل "مجموعة أدوات إدارة العملاء المتعددين" كعملية في الخلفية:

set -a; source .env; set +a # Export env variables to child process
toolbox --tools-file tools.yaml --address 127.0.0.1 --port 5000 &

تعرض "أدوات قاعدة البيانات" أدوات قاعدة البيانات عبر HTTP. يتواصل موظّف الدعم مع الجهاز عند الساعة http://127.0.0.1:5000.

ابدأ واجهة مستخدم مطوّر ADK:

uv run adk web .

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

What appetizers do you have?

الفحص: يطلب الوكيل من قاعدة البيانات عرض عناصر القائمة ويعرضها.

I'm vegetarian

فحص: يحفظ الوكيل خيار النظام الغذائي المفضّل في حالة الوكيل

Can I make a reservation for tomorrow?

الفحص: لا يمكن للوكيل التعامل مع هذا الطلب (لا تتوفّر أدوات حجز بعد)

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

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

5- بدء سياق المشروع باستخدام Antigravity

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

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

ملاحظة: إذا لم تكن هذه الأعراض تنطبق عليك، يعني ذلك أنّك محظوظ جدًا.

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

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

التدرّج الهرمي لسياق Antigravity

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

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

ملاحظة: يتضمّن المشروع حاليًا سير عمل (SDD pipeline) ومهارة (ADK agent development) ولكن ليس فيه قواعد. تمنح قاعدة project-context.md Antigravity فهمًا مستمرًا لقاعدة الرموز البرمجية، أي التكنولوجيات المستخدَمة وطريقة تنظيم الملفات وما تم إنشاؤه حتى الآن.

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

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

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

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

افتح

.agents/skills/adk-agent-development/SKILL.md

في المحرِّر استبدِل سطري التعليقات TODO(codelab) في الأعلى بما يلي:

---
name: adk-agent-development
description: Comprehensive guide for building, developing, and deploying AI agents using Google's Agent Development Kit (ADK) with Gemini models, covering agent creation, tools, state management, persistence, deployment, and database integration via MCP Toolbox.
---

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

افتح

.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.
---

ملاحظات: يُرجى قراءة ملف repo-research SKILL.md بالتفصيل. هذا مثال على طلب تحليل المستودع، ويُرجى العِلم أنّ قواعد التحديث التزايدي محافظة عمدًا. إذا انتهى سياق Antigravity في منتصف البحث أو تمت مقاطعة المحادثة، سيتم حفظ كل ما تم اكتشافه حتى الآن في الملف. يتم استئناف المهارة من حيث توقفت بدون فقدان التقدم.

تحذير يمكن أن يؤدي تحليل مستودع كبير إلى استنفاد حصتك بسرعة.

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

head -4 .agents/skills/adk-agent-development/SKILL.md
head -4 .agents/skills/repo-research/SKILL.md

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

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

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

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

mkdir -p .agents/rules

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

Research this repository and create a project context document

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

بعد اكتمال العملية، افتح .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. تأكَّد من توفّر المبادئ الثلاثة وذكرها بوضوح.

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

نقطة التحقّق: .agents/rules/project-context.md موجودة وتتضمّن معلومات ملموسة حول المستودع. تعرض الصورة .agents/skills/repo-research/SKILL.md عملية إنشاء مهارة باستخدام YAML frontmatter والتعليمات وحلّ التعارض. يحتوي .specify/memory/constitution.md على ثلاثة مبادئ للمشروع يتم التحقّق من صحتها في إجراءات ومهام سير عمل التخطيط والتحليل. أنّك تفهم التسلسل الهرمي للسياق المكوّن من ثلاثة مستويات: القواعد (نشطة دائمًا)، والمهارات (عند الطلب)، وسير العمل (أوامر الشرطة المائلة).

6. دورة تطوير البرامج الآمنة (SDD) — إضافة ميزة الحجز

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

ملاحظة: بعد إكمال المواصفات، قد تقدّم Antigravity عمليات تسليم مثل "إنشاء خطة فنية" أو "توضيح متطلبات المواصفات". هذه هي الإشارة إلى مرحلة سير العمل التالية (/speckit.plan أو /speckit.clarify)

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

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

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

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

/speckit.clarify

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

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

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

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

/speckit.plan

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

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

يجب أن تستخدم Antigravity مهارة adk-agent-development أثناء التخطيط. راجِع البيانات الرئيسية:

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

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

7. التنفيذ

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

/speckit.implement

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

ملاحظة: يمكنك التعليق عليه مباشرةً. لا يمكن إجراء ذلك إلا باستخدام Artifact المضمّن في 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,
...

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

يجب أن تؤثّر التغييرات في نص قاعدة البيانات الأولية، فلنحاول تنفيذه

source .env
uv run python scripts/seed_db.py

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

ملاحظة: قد تكون Antigravity قد أنشأت نصًا برمجيًا منفصلاً لعملية النقل (مثل scripts/create_reservations.py) بدلاً من تعديل seed_db.py. ابحث في git diff --name-only عن أي نصوص برمجية جديدة في scripts/ ونفِّذها بدلاً من النصوص القديمة.

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

pkill -f toolbox 2>/dev/null
toolbox --tools-file tools.yaml --address 127.0.0.1 --port 5000 &

ابدأ واجهة مستخدم مطوّر 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) مرتين باستخدام Ctrl+C.

نقطة التحقّق: يتعامل الوكيل مع حجز المواعيد والبحث عنها. لقد أكمَلْت دورة كاملة من عملية تطوير البرامج المستندة إلى النماذج (SDD): تحديد → توضيح → تخطيط → مهام → تحليل → تنفيذ → اختبار. أنتجت كل مرحلة عنصرًا ذا إصدار في specs/<branch-name>/.

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

أصبحت الآن على دراية بسير عمل 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.

9- تهانينا!

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

ما أنشأته

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

ما تعلّمته

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

تَنظيم

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

pkill -f toolbox 2>/dev/null

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

gcloud sql instances delete restaurant-db --quiet

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

gcloud projects delete $GOOGLE_CLOUD_PROJECT

ملاحظة مهمة: يمكنك التراجع عن عملية الحذف هذه لفترة محدودة من الوقت باستخدام الأمر gcloud projects undelete ${GOOGLE_CLOUD_PROJECT}