1- التعرّف على رحلة التحديث
هذا الدرس التطبيقي الشامل حول الترميز هو مختبر عملي مصاحب مستمد مباشرةً من المقالة المتعمّقة حول البنية، كيفية أتمتة التحديث باستخدام Antigravity وتنسيق الوكلاء المتعدّدين. على الرغم من أنّنا نستخدم عملية تبديل إطار عمل Node.js كلاسيكي كأداة ملموسة للعرض التوضيحي، فإنّ أنماط التصميم الأساسية وبُنى الدليل وعمليات التنسيق المستندة إلى الذكاء الاصطناعي الوكيل التي ستستخدمها هنا لا تعتمد على لغة معيّنة ويمكن تطبيقها عالميًا على أي مشروع لتحديث الأنظمة القديمة على نطاق واسع.
على عكس مساعدي الترميز العاديين الذين يكملون سطورًا في ملف واحد فقط، ستتعرّف على كيفية الاستفادة من إمكانات Google Antigravity المستندة إلى الذكاء الاصطناعي الوكيل لتنسيق فِرق مستقلة من الوكلاء الفرعيين المتخصّصين في الذكاء الاصطناعي. يمكن لهؤلاء الوكلاء إجراء هندسة عكسية لقواعد الرموز القديمة بشكل مستقل، وكتابة مجموعات اختبار صارمة، وإنشاء بُنى حديثة، وتصحيح أخطاء المحول البرمجي بأنفسهم باستخدام حلقات Reflexion، مع الحفاظ على تحكّمك المطلق بصفتك مهندسًا رفيع المستوى.
أهداف الدورة التعليمية
- تحديد سير العمل: كيفية تصنيف مهام الإعداد المحدّدة وفصلها بشكل صحيح عن تحديات إعادة التصميم المعقدة المستندة إلى الخبرة.
- بنية المهارات: كيفية تنظيم حزمة مهارات وكيل قابلة للتوسيع باستخدام ميزة "الكشف التدريجي" وبيانات YAML الوصفية للتوجيه.
- تنسيق أنماط التصميم: كيفية إجراء عملية إعادة تصميم على نطاق واسع من خلال ربط أنماط التصميم "جهاز التوجيه" و"التخطيط والتنفيذ" و"التفكير".
- عقود صارمة للإدخال والإخراج: كيفية فرض حدود واضحة للإدخال والمهارة والإخراج في جميع مراحل خطوط أنابيب الهندسة العكسية والإنشاء المستهدفة.
- التحقّق من التكافؤ: كيفية الاستفادة من الوكيل الفرعي للمتصفّح في Antigravity لإجراء اختبار التكافؤ جنبًا إلى جنب في متصفّح الويب Chrome.
ما ستنشئه
ستنسّق خط أنابيب إعادة تصميم تلقائيًا بالكامل من البداية، يأخذ نموذج Express وMongoose CRUD القديم والمميز (العرض التوضيحي "madhums") ويعيد إنشائه بشكل مستقل من البداية في تطبيق Next.js App Router مكتوب بشكل صارم ومستند إلى MongoDB، والتحقّق الصارم من Zod، ومكوّنات ShadCN UI التي يمكن الوصول إليها.
المتطلبات
- تثبيت**بيئة تطوير متكاملة (IDE) من Google Antigravity** محليًا (متاحة على antigravity.google)
- تثبيت Node.js (الإصدار 18 أو أحدث) محليًا
- متصفّح Chrome للتحقّق التلقائي من واجهة المستخدم
- نسخة طبق الأصل من مستودع العرض التوضيحي الأحادي مفتوح المصدر لتحديث Express.js
2- إعداد بيئة التحديث
قبل السماح للوكلاء المستقلين بالعمل على قاعدة رموز قديمة، يجب إنشاء بيئة مستودع أحادي نظيفة ومستقرة للغاية. إنّ تزويد مساعد الذكاء الاصطناعي بخط أساس نظيف يضمن تركيزه بالكامل على إنشاء رموز حديثة عالية الجودة بدلاً من إضاعة الرموز المميزة في محاربة الثغرات الأمنية في الحزم التي مضى عليها عقد من الزمن أو حالات عدم تطابق المحول البرمجي.
مقارنة بنية Express القديمة ببنية Next.js الحديثة
المكوّن | الحزمة القديمة | الاستبدال الحديث | الأسباب |
البنية | Express Monolith | Next.js App Router | فصل المنطق إلى مكوّنات الخادم لتحسين العرض وأداء مكوّنات خادم React (RSC) |
منطق البيانات | Mongoose (إطار عمل إدارة المستندات) | MongoDB + Zod | تبديل خطافات ORM الضمنية بمخططات Zod الصريحة والآمنة من حيث النوع وأداء برنامج التشغيل الأولي |
اللغة | CommonJS / JavaScript | TypeScript (ESM) | فرض الأمان في وقت الترجمة والانتقال إلى معايير الوحدات الحديثة |
الواجهة الأمامية | Pug/EJS (عرض الخادم) | ShadCN UI + Tailwind | الانتقال من النماذج الصارمة إلى نظام تصميم قابل للإنشاء ويمكن الوصول إليه ويستند إلى الأدوات أولاً |
المصادقة | Passport.js | NextAuth | تحديث إدارة الجلسات من خلال الدعم المضمّن لمقدّمي خدمات Edge والمعاصرين |
السلامة | البرمجيات الوسيطة اليدوية | Zod (التحقّق الصارم) | تنفيذ "مصدر وحيد للحقيقة" للتحقّق من صحة البيانات على مستوى الحزمة بالكامل |
إعداد مركز التحديث
أول إجراء محدّد نتخذه هو استنساخ بنية المستودع الأحادي المعزول. يؤدي ذلك إلى فصل الرموز القديمة للقراءة فقط عن مستودعنا الجديد من البداية، ما يضمن عدم حدوث أي تغييرات غير مقصودة في التطبيق الأصلي.
افتح الوحدة الطرفية في Antigravity وشغِّل أوامر الإعداد التالية:
git clone https://github.com/GoogleCloudPlatform/devrel-demos.git cd devrel-demos/other/modernizing-expressjs
بعد الاستنساخ، افتح المجلد modernizing-expressjs مباشرةً في مستكشف بيئة تطوير Antigravity المتكاملة. سيظهر لك التنسيق المعزول التالي:
/modernizing-expressjs/ ├── .agents/ # Skills metadata and checklists │ └── skills/ ├── docs/ # Target directory for reverse-engineered markdown artifacts ├── legacy-app/ # Read-only root of the legacy Express monolith ├── modern-app/ # Greenfield target repository for the Next.js rewrite ├── GEMINI.md # Project-wide agent constitution └── README.md # Companion documentation
شاهِد هذا الفيديو القصير الذي يوضّح كيفية إعداد بيئة المستودع الأحادي وعزلها بشكل محدّد:
3- تصميم حِزم المهارات والأنماط لوكيل الذكاء الاصطناعي
يختلف تأليف مهارة وكيل قوية اختلافًا جوهريًا عن كتابة طلب محادثة عادي. عند تأليف حزمة مهارات، أنت تصمّم جزءًا معيّنًا من البرامج يمكن أن تنفّذه نموذج لغوي كبير أساسي بشكل مستقل. لمنع الوكيل من الهلوسة أو تحمّل "ضريبة قدرة الاستيعاب"، نقدّم حزمة مهارات تنسيق Greenfield مفتوحة المصدر كنموذج تأليف قابل للتوسيع يستند إلى مبدأين غير قابلين للتفاوض: الإيجاز والكشف التدريجي.
الكشف التدريجي باستخدام توجيه البيانات الوصفية بتنسيق YAML
بدلاً من إدراج جميع قواعد الهدف في تعليمات نظام أحادية، نوزّع التعليمات على مستوى الأدلة. يحتوي كل دليل مهارة على نقطة دخول SKILL.md مضمّنة في كتلة بيانات YAML الوصفية للتوجيه.
افتح الملف .agents/skills/orchestrating-greenfield-migration/SKILL.md وافحص البيانات الوصفية لجهاز التوجيه:
---
name: orchestrating-greenfield-migration
description: >
Manages the end-to-end modernization of legacy Express
monoliths into Next.js architectures. Orchestrates subagents
for auditing, scaffolding, and verification. Use when starting
or managing a greenfield rewrite project.
---
تضمين نمط "التخطيط والتنفيذ" بشكل ثابت
لمنع الوكيل المستقل من الانحراف أو التشتت بسبب البرمجيات الوسيطة القديمة المثيرة للاهتمام أو محاولة إجراء عمليات تبديل غير مصرّح بها لقاعدة البيانات، نتجاوز التخطيط العادي المفتوح من خلال تضمين نمط التخطيط والتنفيذ بشكل ثابت في التعليمات مباشرةً.
افحص قائمة التحقق من Markdown الحرفية المضمّنة داخل المنسّق الرئيسي:
### Phase 1: The AI audit (reverse engineering)
Dispatch subagents to produce specifications while identifying project-specific test scenarios.
* [ ] Init `docs/verification/Verification_Plan.md` to create baseline template.
* [ ] Run `auditing-data-models` -> Append Data Integrity Stress-Tests.
* [ ] Run `auditing-api-contracts` -> Append API Parity & Edge Case Probes.
* [ ] Run `auditing-business-logic` -> Append Logic & Authorization Stress-Tests.
* [ ] Run `auditing-ui-archeology` -> Append Interaction & Layout Targets.
من خلال تنسيق سير العمل كقائمة تحقق صريحة تتضمّن مراجع مضمّنة للمهارات، ينسخ الوكيل هذه الخريطة الدقيقة إلى خطة المهام، ما يجعله في وضع "التنفيذ فقط" الذي يتحقق بشكل منهجي من المربّعات ويستدعي الوكلاء الفرعيين المتخصّصين للغاية عند الحاجة فقط.
4- المرحلة 1: إجراء هندسة عكسية للنموذج القديم (التدقيق)
نحن على استعداد لتشغيل تسلسل التنسيق الرئيسي. تستخرج مرحلتنا الرئيسية الأولى قواعد النشاط التجاري ومخططات البيانات وحِملات واجهة برمجة التطبيقات من النموذج القديم، وتخزّنها كعناصر Markdown نظيفة مع ترك عقد من الديون الفنية الضرورية وراءنا.
تشغيل تسلسل إعادة التصميم المستقل
في لوحة محادثة وكيل Antigravity، اكتب أمر يبدأ بشرطة مائلة مخصّص التالي واضغط على مفتاح Enter:
/orchestrating-greenfield-migration
الآن، راقِب وحدة التحكم الطرفية. ستشاهد الوكيل الرئيسي يقرأ تعليمات النظام، ويطابق طلبك مع البيانات الوصفية للمنسّق، ويعرض قائمة التحقق من 5 مراحل، ويبدأ على الفور في إرسال وكلاء فرعيين متخصصين في "التدقيق" بالتوازي.
عقد التعليمات للإدخال والمهارة والإخراج
خلال المرحلة 1، ينفّذ الوكيل خط أنابيب صارمًا للهندسة العكسية ملتزمًا بعقد التعليمات التالي:
المدخلات المستخدَمة: ملفات رموز المصدر القديمة للقراءة فقط الموجودة داخل legacy-app/
المهارات المستدعاة:
المهارة | الوصف |
| يتتبّع المسارات القديمة لتوثيق حِزم استجابة JSON الدقيقة. |
| يحلّل مخططات Mongoose لاستخراج العلاقات والحقول المطلوبة والإعدادات التلقائية. |
| يوثّق الآثار الجانبية الضمنية وتدفقات مصادقة Passport وقواعد البرمجيات الوسيطة. |
| يفحص نماذج Pug القديمة لتحديد "هدف واجهة المستخدم" رفيع المستوى (أشرطة التنقل والنماذج). |
العناصر التي تم إنشاؤها: مواصفات Markdown منظّمة للغاية يتم إنشاؤها مباشرةً في المجلد docs/
العنصر | الوصف |
| توضّح هذه الوثيقة مساحة واجهة برمجة التطبيقات التي تم إجراء هندسة عكسية لها في تطبيق Express القديم. استخدِم هذا الكتالوج لضمان التكافؤ الصارم عند إعادة إنشاء المسارات في تطبيق Next.js الحديث. |
| تسجّل هذه الوثيقة السلوكيات والإعدادات والقواعد الصارمة التي تم التحقّق منها في تطبيق Express القديم بشأن المصادقة (AuthN) والترخيص (AuthZ) والبرمجيات الوسيطة العامة وإدارة الجلسات والآثار الجانبية. |
| تقدّم هذه الوثيقة تحليلاً شاملاً لمخططات Mongoose القديمة من |
| تقدّم هذه الوثيقة تحليلاً تفصيليًا لواجهة المستخدم القديمة المستندة إلى Pug في |
شاهِد هذه اللقطة المباشرة من الوحدة الطرفية التي توضّح عملية التدقيق المستقلة للهندسة العكسية أثناء العمل:
5- المرحلتان 2 و3: إطار عمل TDD والإنشاء من البداية للواجهة الخلفية
بعد تدقيق التطبيق القديم وتوثيقه بالكامل، ينتقل المنسّق الرئيسي إلى إنشاء الواجهة الخلفية الحديثة المستهدفة. تقدّم هذه المرحلة نمط التصميم المستند إلى الذكاء الاصطناعي الوكيل الأكثر فاعلية في مجموعة الأدوات: التفكير (التفكير الذاتي) ذو الحلقة المغلقة الذي يستند إلى تطوير الاختبار أولاً (TDD) الصارم.
إنشاء رموز ذاتية الإصلاح باستخدام حلقات Reflexion
إنّ كتابة الرموز الحديثة أمر بسيط، ولكن ضمان ترجمتها بشكل مثالي واجتيازها قيود التحقّق الصارمة يتطلب تقييمًا بحلقة مغلقة. يتولّى المنسّق ذلك بشكل مستقل من خلال إعادة توجيه نتائج الاختبار مباشرةً إلى قدرة استيعاب الوكيل الفرعي:
- المرحلة 2 (إعداد TDD): يستدعي المنسّق الوكيل الفرعي
generating-api-tests، الذي يقرأdocs/API_Contracts.mdويكتب مجموعات اختبار تكامل شاملة في Vitest تؤكد رموز حالة HTTP وحِملات JSON المطلوبة بدقة. وكما هو متوقّع في TDD، تفشل هذه الاختبارات في البداية. - المرحلة 3 (إنشاء الواجهة الخلفية): تبدأ الوكلاء الفرعيون للإنشاء في كتابة معالِجات مسارات Next.js الحديثة ومخططات التحقّق الصارمة من Zod.
- حلقة التصحيح الذاتي: عندما يقيّم إطار عمل Vitest المحدّد الرموز الجديدة ويعرض نتيجة فاشلة (على سبيل المثال، إذا عرض خطأ التحقّق المتوقّع
422رمز الحالة500)، لا يتعطّل الوكيل. بل يفكر في نتيجة الخطأ الموضوعية، ويعيد فتح معالِج المسار المستهدف، ويصلح بنية حِملة مخطط Zod، ويشغّل الاختبارات مرة أخرى. ويكرّر ذلك بشكل مستقل إلى أن يحقق رمز خروج0.
عقد التعليمات للإدخال والمهارة والإخراج
المدخلات المستخدَمة: عناصر المواصفات التي تم إجراء هندسة عكسية لها (docs/API_Contracts.md، docs/Data_Models.md).
المهارات المستدعاة:
المهارة | الوصف |
| ينشئ مجموعات تكامل فاشلة في Vitest. |
| يهيئ التنسيق الأساسي لـ Next.js App Router. |
| يضبط بيئة برنامج تشغيل اختبار Vitest المحلي. |
| يحوّل نماذج Mongoose القديمة إلى مخططات MongoDB + Zod. |
| يعيد إنشاء مسارات Express في معالِجات مسارات Next.js وحراس المسارات النمطية. |
النتائج التي تم إنشاؤها: حزم اختبار Vitest الأولية الفاشلة، ومخططات Zod المكتوبة بشكل كامل، ومعالِجات مسارات Next.js الوظيفية، وعمليات تنفيذ حزم الاختبار النظيفة والناجحة.
شاهِد عملية الإنشاء التلقائي لإطار عمل اختبار TDD:
شاهِد عملية التنفيذ في الوقت الفعلي لحلقة Reflexion ذاتية التصحيح التي تنشئ الواجهة الخلفية المستهدفة:
6- المرحلة 4: إنشاء الواجهة الأمامية الحديثة (مكوّنات واجهة المستخدم)
بعد أن تصبح مرحلة التحقّق من الواجهة الخلفية قوية بالكامل وتجتاز اختبارات التكامل، يغيّر المنسّق الرئيسي السياق لتحديث العرض المرئي. يتم تجاهل النماذج الضرورية التي يتم عرضها على الخادم لصالح نظام تصميم مكوّنات يسهل الوصول إليه ويستند إلى الأدوات أولاً.
ترجمة هدف واجهة المستخدم إلى طرق عرض قابلة للإنشاء
بدلاً من محاولة ترجمة CSS سطرًا بسطر، يقرأ الوكيل الفرعي للواجهة الأمامية جرد "هدف واجهة المستخدم" الذي تم استخراجه ويطابق العناصر الهيكلية مباشرةً مع النظائر الحديثة عالية الدقة.
عقد التعليمات للإدخال والمهارة والإخراج
المدخلات المستخدَمة: عنصر جرد الواجهة الأمامية الذي تم إجراء هندسة عكسية له (docs/UI_Inventory.md)
المهارات المستدعاة:
المهارة | الوصف |
| يحوّل عنصر |
النتائج التي تم إنشاؤها: صفحات الواجهة الأمامية في Next.js الجاهزة للإنتاج التي تم إنشاؤها باستخدام مكوّنات ShadCN UI التي يسهل الوصول إليها للغاية وتنسيقات الأدوات المساعدة في Tailwind CSS
شاهِد عملية الإنشاء المستقلة لطبقة عرض الواجهة الأمامية الحديثة:
7- المرحلة 5: التحقّق والتدقيق المعاكس
ينتهي خط أنابيب إعادة التصميم بعملية فحص صارمة للجودة. ينتقل المنسّق الرئيسي من تحليل الرموز الثابتة إلى اختبار بيئة وقت التشغيل النشطة، محاولاً بنشاط تعطيل التطبيق الجديد المستهدف لإثبات التكافؤ الوظيفي المطلق مع خط الأساس القديم.
تنفيذ اختبار علامتي التبويب وتفعيل المتصفّح
تستفيد مرحلة التحقّق من إمكانات Antigravity المرئية والمستندة إلى نموذج العناصر في المستند (DOM) لإثبات النجاح بشكل مستقل بدون الحاجة إلى النقر يدويًا على النماذج:
- التكافؤ جنبًا إلى جنب: يوجّه الوكيل الفرعي
auditing-parityبرنامج التشغيل المحلي لبدء كل من نموذج Express القديم وتطبيق Next.js الحديث في الوقت نفسه، ما يؤدي إلى التحقّق من العرض المرئي وعرض البيانات المتطابقين. - التحقق الأمني المعاكس: يستدعي المنسّق الوكيل الفرعي
adversarial-verification، الذي يشغّل الوكيل الفرعي للمتصفّح في Antigravity. يُفعّل هذا الوكيل المتخصّص المتصفّح مباشرةً، ويكتب في حقول الإدخال، ويرسل النماذج، ويبحث عن حالات تراجع الأمان أو ملفات تعريف ارتباط الجلسات المعطّلة أو الحالات الحدّية غير المعالَجة. - إنشاء سجلّ التدقيق: يسجّل الوكيل الفرعي للمتصفّح تلقائيًا لقطات فيديو بتنسيق WebP لعمليات تفعيل الجلسة، ويرفقها مباشرةً بتقرير الترحيل النهائي كـ "إثبات عمل" يمكن التحقّق منه.
عقد التعليمات للإدخال والمهارة والإخراج
المدخلات المستخدَمة: كل من التطبيقين القديم والحديث اللذين يتم تشغيلهما جنبًا إلى جنب في بيئات وقت التشغيل المحلية
المهارات المستدعاة:
المهارة | الوصف |
| ينفّذ عمليات التحقّق من التكافؤ جنبًا إلى جنب في وقت التشغيل. |
| يبحث عن عيوب المنطق وحالات التراجع الوظيفي باستخدام تفعيل المتصفّح التلقائي. |
النتائج التي تم إنشاؤها: سجلّ تدقيق شامل للتكافؤ الوظيفي مقترن بفيديوهات مسجّلة لجلسة المتصفّح تؤكد النجاح الكامل
شاهِد الوكيل الفرعي للمتصفّح التلقائي يتحقّق بنشاط من التطبيق الحديث:
8- الجاهزية لإصدار التطبيق والخطوات التالية بعد الترحيل
تهانينا! لقد نسّقت بنجاح خط أنابيب إعادة تصميم متقدّمًا للغاية ومستقلاً ومستندًا إلى الذكاء الاصطناعي الوكيل لتحديث نموذج قديم من البداية، وتعلّمت مهارات عالمية قابلة للنقل بدرجة كبيرة، مثل الكشف التدريجي وقوائم التحقق من "التخطيط والتنفيذ" وحلقات Reflexion ذاتية الإصلاح.
الاستعداد للنشر في مرحلة الإنتاج
بعد التحقّق من تطبيق Next.js وتدقيقه بالكامل، أنت على استعداد للانتقال إلى التكامل في مرحلة الإنتاج. ننصحك بتنفيذ الخطوات التالية المتوافقة مع معايير الصناعة:
- التوجيه التدريجي: يمكنك نشر وكيل عكسي (مثل نمط Strangler Fig) لتوجيه حركة المرور تدريجيًا من تطبيق Express القديم إلى الهدف الحديث.
- الحفاظ على تحسين محركات البحث: يمكنك ربط مسارات Express القديمة بعمليات إعادة التوجيه الدائمة في Next.js (
_redirects.yaml) للحفاظ على سلطة النطاق الحالية. - بث البيانات: يمكنك الانتقال من إعداد قاعدة البيانات الثابتة إلى بث بيانات الإنتاج المباشرة التي يتم التحقّق منها بشكل آمن في وقت التشغيل باستخدام مخططات Zod الصارمة.
- إمكانية المراقبة: يمكنك استبدال أدوات تسجيل البيانات الضرورية بأطر عمل OpenTelemetry المنظّمة.
تعميق خبرتك في التحديث
لاستكشاف قواعد الرموز البرمجية الأساسية الكاملة وتعليمات المهارات المخصّصة والأسباب النظرية الشاملة التي تحرّك مسار التعلّم هذا، احرِص على قراءة المقالة الرئيسية الكاملة، بالإضافة إلى محتوى تنسيق الوكلاء المتعدّدين الآخر.
- المقالة: كيفية أتمتة التحديث باستخدام Antigravity وتنسيق الوكلاء المتعدّدين
- الدرس التطبيقي حول الترميز: إنشاء أداة تدقيق رموز متعددة اللغات باستخدام وكلاء Antigravity المتوازيين
الانضمام إلى منتدى Agentic Builder
نأمل أن تكون أنماط إعادة التصميم العالمية وخطوط الأنابيب المستندة إلى الذكاء الاصطناعي الوكيل مفيدة لك. للاطّلاع على آخر الأخبار عن حِزم المهارات مفتوحة المصدر المستقبلية والمحتوى الفني المتعمّق والمشاركات القادمة في المؤتمرات، يمكنك متابعتي على القنوات المهنية:
- المتابعة على LinkedIn: linkedin.com/in/jamesor
- المتابعة على X (المعروف سابقًا باسم Twitter): x.com/JamesOR
يهمّنا معرفة رأيك
ما هو أكثر ما يثير اهتمامك في التنسيق المستند إلى الذكاء الاصطناعي الوكيل؟
شكرًا لك على استخدام Google Antigravity.