أتمتة تحديث الأنظمة القديمة على نطاق واسع باستخدام مسارات قائمة على الوكلاء وAntigravity

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/

المهارات المستدعاة:

المهارة

الوصف

auditing-api-contracts

يتتبّع المسارات القديمة لتوثيق حِزم استجابة JSON الدقيقة.

auditing-data-models

يحلّل مخططات Mongoose لاستخراج العلاقات والحقول المطلوبة والإعدادات التلقائية.

auditing-business-logic

يوثّق الآثار الجانبية الضمنية وتدفقات مصادقة Passport وقواعد البرمجيات الوسيطة.

auditing-ui-archeology

يفحص نماذج Pug القديمة لتحديد "هدف واجهة المستخدم" رفيع المستوى (أشرطة التنقل والنماذج).

العناصر التي تم إنشاؤها: مواصفات Markdown منظّمة للغاية يتم إنشاؤها مباشرةً في المجلد docs/

العنصر

الوصف

docs/API_Contracts.md

توضّح هذه الوثيقة مساحة واجهة برمجة التطبيقات التي تم إجراء هندسة عكسية لها في تطبيق Express القديم. استخدِم هذا الكتالوج لضمان التكافؤ الصارم عند إعادة إنشاء المسارات في تطبيق Next.js الحديث.

docs/Business_Logic_Rules.md

تسجّل هذه الوثيقة السلوكيات والإعدادات والقواعد الصارمة التي تم التحقّق منها في تطبيق Express القديم بشأن المصادقة (AuthN) والترخيص (AuthZ) والبرمجيات الوسيطة العامة وإدارة الجلسات والآثار الجانبية.

docs/Data_Models.md

تقدّم هذه الوثيقة تحليلاً شاملاً لمخططات Mongoose القديمة من legacy-app/app/models/ وتقدّم مخططًا لطبقة وصول إلى البيانات حديثة وآمنة من حيث النوع باستخدام MongoDB وZod الأصليين.

docs/UI_Inventory.md

تقدّم هذه الوثيقة تحليلاً تفصيليًا لواجهة المستخدم القديمة المستندة إلى Pug في legacy-app وتوضّح مخططًا لبنية واجهة أمامية حديثة مستندة إلى المكوّنات في Next.js في modern-app.

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

5- المرحلتان 2 و3: إطار عمل TDD والإنشاء من البداية للواجهة الخلفية

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

إنشاء رموز ذاتية الإصلاح باستخدام حلقات Reflexion

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

  1. المرحلة 2 (إعداد TDD): يستدعي المنسّق الوكيل الفرعي generating-api-tests، الذي يقرأ docs/API_Contracts.md ويكتب مجموعات اختبار تكامل شاملة في Vitest تؤكد رموز حالة HTTP وحِملات JSON المطلوبة بدقة. وكما هو متوقّع في TDD، تفشل هذه الاختبارات في البداية.
  2. المرحلة 3 (إنشاء الواجهة الخلفية): تبدأ الوكلاء الفرعيون للإنشاء في كتابة معالِجات مسارات Next.js الحديثة ومخططات التحقّق الصارمة من Zod.
  3. حلقة التصحيح الذاتي: عندما يقيّم إطار عمل Vitest المحدّد الرموز الجديدة ويعرض نتيجة فاشلة (على سبيل المثال، إذا عرض خطأ التحقّق المتوقّع 422 رمز الحالة 500)، لا يتعطّل الوكيل. بل يفكر في نتيجة الخطأ الموضوعية، ويعيد فتح معالِج المسار المستهدف، ويصلح بنية حِملة مخطط Zod، ويشغّل الاختبارات مرة أخرى. ويكرّر ذلك بشكل مستقل إلى أن يحقق رمز خروج 0.

عقد التعليمات للإدخال والمهارة والإخراج

المدخلات المستخدَمة: عناصر المواصفات التي تم إجراء هندسة عكسية لها (docs/API_Contracts.md، docs/Data_Models.md).

المهارات المستدعاة:

المهارة

الوصف

generating-api-tests

ينشئ مجموعات تكامل فاشلة في Vitest.

scaffolding-nextjs-foundation

يهيئ التنسيق الأساسي لـ Next.js App Router.

scaffolding-test-foundation

يضبط بيئة برنامج تشغيل اختبار Vitest المحلي.

scaffolding-data-layer

يحوّل نماذج Mongoose القديمة إلى مخططات MongoDB + Zod.

scaffolding-api-routes

يعيد إنشاء مسارات Express في معالِجات مسارات Next.js وحراس المسارات النمطية.

النتائج التي تم إنشاؤها: حزم اختبار Vitest الأولية الفاشلة، ومخططات Zod المكتوبة بشكل كامل، ومعالِجات مسارات Next.js الوظيفية، وعمليات تنفيذ حزم الاختبار النظيفة والناجحة.

شاهِد عملية الإنشاء التلقائي لإطار عمل اختبار TDD:

شاهِد عملية التنفيذ في الوقت الفعلي لحلقة Reflexion ذاتية التصحيح التي تنشئ الواجهة الخلفية المستهدفة:

6- المرحلة 4: إنشاء الواجهة الأمامية الحديثة (مكوّنات واجهة المستخدم)

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

ترجمة هدف واجهة المستخدم إلى طرق عرض قابلة للإنشاء

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

عقد التعليمات للإدخال والمهارة والإخراج

المدخلات المستخدَمة: عنصر جرد الواجهة الأمامية الذي تم إجراء هندسة عكسية له (docs/UI_Inventory.md)

المهارات المستدعاة:

المهارة

الوصف

scaffolding-ui-components

يحوّل عنصر UI_Component_Inventory.md إلى مكوّنات ShadCN + Tailwind الحديثة و صفحات Next.js التي تم إنشاؤها بالكامل.

النتائج التي تم إنشاؤها: صفحات الواجهة الأمامية في Next.js الجاهزة للإنتاج التي تم إنشاؤها باستخدام مكوّنات ShadCN UI التي يسهل الوصول إليها للغاية وتنسيقات الأدوات المساعدة في Tailwind CSS

شاهِد عملية الإنشاء المستقلة لطبقة عرض الواجهة الأمامية الحديثة:

7- المرحلة 5: التحقّق والتدقيق المعاكس

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

تنفيذ اختبار علامتي التبويب وتفعيل المتصفّح

تستفيد مرحلة التحقّق من إمكانات Antigravity المرئية والمستندة إلى نموذج العناصر في المستند (DOM) لإثبات النجاح بشكل مستقل بدون الحاجة إلى النقر يدويًا على النماذج:

  1. التكافؤ جنبًا إلى جنب: يوجّه الوكيل الفرعي auditing-parity برنامج التشغيل المحلي لبدء كل من نموذج Express القديم وتطبيق Next.js الحديث في الوقت نفسه، ما يؤدي إلى التحقّق من العرض المرئي وعرض البيانات المتطابقين.
  2. التحقق الأمني المعاكس: يستدعي المنسّق الوكيل الفرعي adversarial-verification، الذي يشغّل الوكيل الفرعي للمتصفّح في Antigravity. يُفعّل هذا الوكيل المتخصّص المتصفّح مباشرةً، ويكتب في حقول الإدخال، ويرسل النماذج، ويبحث عن حالات تراجع الأمان أو ملفات تعريف ارتباط الجلسات المعطّلة أو الحالات الحدّية غير المعالَجة.
  3. إنشاء سجلّ التدقيق: يسجّل الوكيل الفرعي للمتصفّح تلقائيًا لقطات فيديو بتنسيق WebP لعمليات تفعيل الجلسة، ويرفقها مباشرةً بتقرير الترحيل النهائي كـ "إثبات عمل" يمكن التحقّق منه.

عقد التعليمات للإدخال والمهارة والإخراج

المدخلات المستخدَمة: كل من التطبيقين القديم والحديث اللذين يتم تشغيلهما جنبًا إلى جنب في بيئات وقت التشغيل المحلية

المهارات المستدعاة:

المهارة

الوصف

auditing-parity

ينفّذ عمليات التحقّق من التكافؤ جنبًا إلى جنب في وقت التشغيل.

adversarial-verification

يبحث عن عيوب المنطق وحالات التراجع الوظيفي باستخدام تفعيل المتصفّح التلقائي.

النتائج التي تم إنشاؤها: سجلّ تدقيق شامل للتكافؤ الوظيفي مقترن بفيديوهات مسجّلة لجلسة المتصفّح تؤكد النجاح الكامل

شاهِد الوكيل الفرعي للمتصفّح التلقائي يتحقّق بنشاط من التطبيق الحديث:

8- الجاهزية لإصدار التطبيق والخطوات التالية بعد الترحيل

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

الاستعداد للنشر في مرحلة الإنتاج

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

  • التوجيه التدريجي: يمكنك نشر وكيل عكسي (مثل نمط Strangler Fig) لتوجيه حركة المرور تدريجيًا من تطبيق Express القديم إلى الهدف الحديث.
  • الحفاظ على تحسين محركات البحث: يمكنك ربط مسارات Express القديمة بعمليات إعادة التوجيه الدائمة في Next.js (_redirects.yaml) للحفاظ على سلطة النطاق الحالية.
  • بث البيانات: يمكنك الانتقال من إعداد قاعدة البيانات الثابتة إلى بث بيانات الإنتاج المباشرة التي يتم التحقّق منها بشكل آمن في وقت التشغيل باستخدام مخططات Zod الصارمة.
  • إمكانية المراقبة: يمكنك استبدال أدوات تسجيل البيانات الضرورية بأطر عمل OpenTelemetry المنظّمة.

تعميق خبرتك في التحديث

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

الانضمام إلى منتدى Agentic Builder

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

يهمّنا معرفة رأيك

ما هو أكثر ما يثير اهتمامك في التنسيق المستند إلى الذكاء الاصطناعي الوكيل؟

التحقّق المعاكس من المتصفّح حلقات إعادة التصميم المستقلة بنية المهارات القابلة للتوسيع تنسيق الوكلاء المتعدّدين عدم الاعتماد على لغة معيّنة عالميًا

شكرًا لك على استخدام Google Antigravity.