دليل Jev GUI Delegate: خلّي Codex يفوّض عمليات الواجهة الرسومية فـ Windows وChrome

نظرة عامة على المشروع

Jev GUI Delegate هو نموذج أولي لتفويض واجهات Windows وChrome موجّه لـCodex. النموذج الرئيسي كيحدّد أهداف المهمة وشروط القبول، بينما المتحكّم المحلي كيراقب الواجهة، كيطابق العناصر، كينفّذ الإجراءات، وكيعاين النتيجة الفعلية من بعد كل خطوة. المتحكّم ما كيستعملش TypeSafe Jev إلا ملي كيكون الاختيار الدلالي ما كيتعالجش بقواعد حتمية.

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

هاد المشروع نموذج أولي تصمّم شخصياً، وتنفّذ بمساعدة الذكاء الاصطناعي، وكيتدار ليه التحقق باستمرار. عقد المهمة، وتنظيم الأدوات، وآليات الاسترجاع، وفحص الصلاحيات، والاختبارات، والتكرار بناءً على الملاحظات، كلها مساهمات فالمشروع؛ أما نموذج Jev وTypeSafe SDK وCodex وإضافة المتصفح فهي منتجات من جهات أخرى.

طريقة العمل

1. النموذج الرئيسي ديال Codex كيرسل الهدف وشروط القبول.

2. كتتنظّم المهمة فعقد محلي يمكن التحقق منو.

3. المتحكّم كيراقب الواجهة الحالية وكيحاول يطابق العناصر بطريقة حتمية.

4. إلا ما قدرش يحدّد الاختيار مباشرة، كينادي Jev باش يدير الاختيار الدلالي.

5. إجراءات Chrome كتتنفّذ عبر جلسة المتصفح الرسمية المتوافقة اللي كيوفّرها المضيف، وإجراءات Windows كتتنفّذ عبر UI Automation.

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

هاد المسار ما كينسخش إعدادات المتصفح الشخصية وما كيستخرجش ملفات Cookie. مسار Chrome كيعتمد على API ديال جلسة المتصفح الرسمية المتوافقة اللي كيوفّرها مضيف Codex، والمستودع بوحدو ما يقدرش ينشئ هاد الجلسة ولا يعوّضها.

الوظائف الرئيسية

جوج مسارات لتنفيذ GUI

• Chrome: كيعاود يستعمل جلسة المتصفح الرسمية اللي كيوفّرها المضيف.

• Windows: كيستعمل Windows UI Automation للتعامل مع عناصر سطح المكتب القابلة للوصول.

عقد مهمة واضح

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

استعمال Jev عند الحاجة

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

التنفيذ المتواصل والاسترجاع

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

النتائج وفحوصات السلامة

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

بيئة التشغيل والشروط المسبقة

المشروع موجّه للبيئات التالية:

• Windows x64

• Python 3.12

• Node.js

• سطح مكتب تفاعلي لتنفيذ عمليات GUI الأصلية

• إلا بغيتي تستعمل مسار Chrome، خاص كذلك API متوافقة لجلسة المتصفح الرسمية كيقدمها مضيف Codex

من الأفضل تثبيت المشروع فـ C:\jev\jev-bridge. بعض الأوامر القديمة وأمثلة Codex skill كتعتمد افتراضياً على هاد المسار. إلا اخترتي مجلداً آخر، خاصك تبدّل الأمثلة والإعدادات المرتبطة به كذلك.

تثبيت المشروع

الخطوة الأولى: استنساخ المستودع وإنشاء البيئة الافتراضية

git clone https://github.com/YUTA-fywoo/jev-gui-delegate.git C:\jev\jev-bridge
cd C:\jev\jev-bridge
py -3.12 -m venv .venv

الخطوة الثانية: تثبيت الاعتماديات المثبتة

.\.venv\Scripts\python.exe -m pip install --require-hashes -r requirements.lock

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

الخطوة الثالثة: تجهيز وقت التشغيل

.\.venv\Scripts\python.exe scripts/setup-runtime.py

الخطوة الرابعة: تشغيل الاختبارات غير المتصلة

.\.venv\Scripts\python.exe -m unittest discover -s gui_delegate/tests -p "test_*.py"

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

إعداد مفتاح Jev

يمكن توفير المفتاح عبر متغير البيئة المحلي TYPESAFE_API_KEY أو عبر Windows Credential Manager. المشروع كينصح باستعمال نافذة الإدخال المحلية اللي كتحلها set-key.cmd للإعداد.

set-key.cmd

ما تكتبش المفتاح فمستودع Git، ولا فعقد المهمة، ولا فمحتوى المحادثة. ملف chrome-runtime.json اللي كينشئه المثبّت محلياً متجاهَل، والمستودع ما فيهش مسارات البيئة ديال جهاز المؤلف الأصلي.

التسجيل فـCodex

إلا بغيتي تربط المشروع بـCodex، شغّل سكريبتات التثبيت التالية من مجلد المشروع:

install.cmd
gui-install.cmd

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

Codex skill الشخصي القابل للتثبيت كاين فـ gui_delegate/skill/SKILL.md. إلا ما تثبّتش المشروع فالمسار الافتراضي، خاصك تراجع حتى الأمثلة اللي فيها مسارات.

الاستعمال الأساسي والتحقق

فحص الجاهزية المحلية

من بعد التثبيت تقدر تشغّل:

health.cmd

health.cmd كيفحص غير واش المكونات واجدة، وما كيعنيش أنه تدار تحقق مباشر من Jev، وما كيعنيش حتى أن الجهاز الحالي داز قبول سيناريو GUI حقيقي.

تنفيذ التحقق المباشر

مسارات التحقق المباشر بحال verify.cmd كتنادي خدمة Jev:

verify.cmd

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

تصميم مهمة مناسبة للتفويض

هاد النموذج الأولي مناسب لعمليات GUI اللي عندها حدود واضحة، ومراحل قابلة للتحديد، ونتائج يمكن التحقق منها. ملي كتسلّم مهمة للمتحكّم، خاصك توضّح على الأقل هاد العناصر:

• الهدف: الحالة النهائية اللي خاص الوصول ليها.

• النطاق: الصفحات أو النوافذ أو العناصر اللي مسموح التعامل معها.

• الإجراءات المسموح بها: أنواع التفاعلات اللي يقدر المتحكّم ينفّذها.

• المدخلات: البيانات الضرورية لتنفيذ المهمة والمسموح باستعمالها.

• المراحل: مراحل الإجراءات اللي يمكن تنفيذها بشكل متواصل.

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

مثلاً، يمكن لمهمة تطلب من المتحكّم يلقى العنصر المستهدف داخل نطاق صفحات محدد، ويعمّر المدخلات المصرّح بها، ويتأكد من النتيجة عبر حالة الصفحة. حقول العقد المحددة ونموذج النتيجة خاصهما يتحددو حسب التنفيذ الموجود فـ gui_delegate/schema.py، وما خاصش تفترض صيغة ما معرّفهاش README.

مسار قراءة المصدر

إلا بغيتي تفهم آلية التنفيذ أو تدير تطويراً إضافياً، تقدر تقرا الملفات بهاد الترتيب:

1. gui_delegate/schema.py: فهم عقد المهمة، والحالة، ونموذج النتيجة.

2. gui_delegate/controller.py: معرفة كيفاش كينظّم المتحكّم دورة التنفيذ.

3. gui_delegate/drivers.py: فهم السواقات ومراقبة الواجهات المهيكلة.

4. gui_delegate/security.py: مراجعة فحوصات النطاق، والتفويض، والمدخلات.

5. gui_delegate/chrome_gateway.mjs: فهم مدخل جلسة المتصفح الرسمية.

6. jev_client.py: مراجعة تغليف Jev SDK، وفحص الإصدار، وتسجيل الاستعمال.

7. gui_delegate/tests: فهم منطق الاسترجاع والسلوك فالحالات الحدّية عبر الاختبارات.

نصائح للاستعمال المتقدم

عطي الأولوية للمطابقة الحتمية

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

حدّد نتيجة قابلة للملاحظة لكل خطوة

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

تعامل بحذر مع إجراءات الإرسال

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

فرّق بين نقص المدخلات وخطأ الاختيار

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

عاود التحقق من بعد ترقية إصدار Jev

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

الفهم الصحيح للاختبارات المعيارية

README كيسجّل جوج جولات من اختبارات المهام الاصطناعية بتاريخ 2026年 9月 23日. كل جولة فيها نفس 4 مهام و24 إجراء، والمجموعتان بجوج كملو 4/4.

• فالجولة الأولى، هبط Astra token من 2,266,693 لـ236,295، بانخفاض 89.6%، وولات سرعة المهام من البداية للنهاية 3.05 مرات سرعة خط الأساس.

• فالجولة الثانية، هبط Astra token من 2,256,091 لـ192,752، بانخفاض 91.5%، وولات سرعة المهام من البداية للنهاية 3.53 مرات سرعة خط الأساس.

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

القيود المعروفة

• النموذج الأولي كيعتمد على إمكانية قراءة DOM أو معلومات تقنيات المساعدة.

• Canvas، وفهم الصور، وسطح المكتب الآمن، وبعض العناصر اللي كتخدم عبر أطر مختلفة، ممكن ما يتعالجوش مباشرة.

• الوظائف اللي ما كيتيحهاش المضيف ممكن تحتاج معالجة إضافية من النموذج الرئيسي.

• مسار Chrome ما يقدرش يخدم بوحدو بلا جلسة المضيف الرسمية المتوافقة.

• سجل التحقق على جهاز قديم ما كيعنيش أن بيئة تثبيت جديدة دازت القبول.

• سجلات التشغيل، وإعدادات المتصفح، والمفاتيح، ومواد المهام الشخصية، وحالة التثبيت على الجهاز، وحزم التراجع ما منشوراش.

الخلاصة

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

إلى بغيتي تعرف كتر على المكوّنات الأصلية، تقدر تزور وثائق TypeSafe وMCP Python SDK وpywinauto.