استكشاف أخطاء Ultrafast: ماذا تفعل عند مشاكل الاتصال وعدم الاستجابة والانحراف
إذا واجهتك مشكلة عند تشغيل Jev Ultrafast، فالغالب أنها عالقة في إحدى الطبقات الأربع: الخدمة المحلية لم تبدأ، أو Chrome لم يتصل، أو استدعاء النموذج رُفض، أو تنفيذ القرار اصطدم بعائق. في هذا الدرس نأخذ أخطاء jev-ultrafast الشائعة واحدًا واحدًا حسب «النص الأصلي للخطأ» مع السبب والحل — ابدأ بالفحص السريع في 60 ثانية، ثم طابق خطأك مع القائمة.
جميع النصوص الأصلية للأخطاء مأخوذة من الشيفرة المصدرية للمستودع (jev_ultrafast/model.py وagent.py وbrowser.py وdemo.py وواجهة inspector)، قابلة للبحث حرفيًا وقابلة للنسخ عند طرح الأسئلة. لا مشكلة إن تعطّلت الدروس السابقة، فأيًّا كانت الخطوة التي فشلت في التثبيت والتشغيل يمكنك العودة إلى هنا للتحقق منها.
ماذا ستستطيع أن تفعل بعد إتمام الدرس
- تحديد أي حلقة من المشكلة — الدليل أم المفتاح أم Chrome أم طبقة تنفيذ المتصفح — باستخدام 4 أوامر خلال 60 ثانية
- مطابقة أخطاء jev-ultrafast: النص الأصلي للخطأ ← السبب ← خطوات الإصلاح
- التمييز بين معاملة ثلاث فئات من الأخطاء: فئة stale (تلتئم تلقائيًا في الوضع التلقائي)، وفئة إعادة المحاولة (يتراجع الكود تلقائيًا)، وفئة التدخل اليدوي (تتطلب منك تعديل الإعدادات أو الهدف)
- فهم 6 حالات العرض في شريط حالة inspector، ومعرفة الخطوة التالية لكل من done و blocked
- حفظ قائمة غير المدعوم: shadow DOM وframes وcanvas والرفع وفتح تبويب جديد منبثق والتمرير المتداخل وأي مكوّن لوحة مفاتيح
- استخدام Export trace لتصدير أدلة القرار، وطرح الأسئلة بأقل قدر من المعلومات
مأزقك الحالي
- نقرت Start demo دون أي استجابة، ولا تدري هل الخدمة لم تبدأ أم Chrome لم يتصل أم المفتاح غير مُهيّأ
- خطأ إنجليزي داخل إطار أحمر يومض ويمضي، ولا تدري أي عبارة تأخذها للبحث، وحتى إن وجدت النتيجة لا تفهم أي طبقة هي المسؤولة
- حالة agent تغيّرت إلى done / blocked، لكن الصفحة ليست النتيجة المرجوة — هل الهدف مكتوب خطأ أم أن هذه الصفحة لا يمكن تشغيلها أصلًا؟
متى تستخدم هذه الطريقة
عندما تحتاج إلى:
- إصلاح الأخطاء المتعطّلة في تثبيت Ultrafast وتشغيله وتشغيل Google Flights وكتابة مهام المتصفح الخاصة بك
- تحديد ما إذا كان موقع ما مناسبًا لـ Ultrafast قبل البدء — صفِّ القائمة غير المدعومة أولًا، لا تندفع بعناد
وأنت لا تريد:
- حذف المستودع وإعادة التثبيت عند كل خطأ، وإعادة عملية التثبيت من الصفر
- عدم التمييز بين «الصفحة تغيّرت ويجب إعادة المحاولة» و«الإعدادات معطوبة ويجب إصلاحها»، فتضيع وقتك في تعديلات بلا جدوى
🎒 الاستعداد قبل البدء
- إتمام تثبيت Ultrafast وتشغيله (لا مشكلة إن تعطّلت، فهذا الدرس مخصص لحل التعطّل)
- المستودع مستنسخ محليًا، والطرفية قادرة على تنفيذ الأوامر في الدليل الجذري
jev-ultrafast/ - (اختياري) إتمام كتابة مهام المتصفح الخاصة بك — الأخطاء التي تصادفها عند استخدام مكتبة Agent يمكن مطابقتها هنا أيضًا
الفكرة الأساسية
حدّد الطبقة أولًا، ثم انظر إلى الخطأ. تمرّ مهمة Ultrafast واحدة بأربع طبقات، وأخطاء كل طبقة تبدو مختلفة:
| الطبقة | ماذا تفحص | الخطأ / الظاهرة النموذجية |
|---|---|---|
| 1. الخدمة المحلية | هل بدأت uv run jev، وهل الدليل صحيح، وهل العنوان هو 127.0.0.1 | Cannot reach local demo server / Forbidden |
| 2. اتصال Chrome | Browser Harness، وتفويض التصحيح عن بُعد | اللوحة لا تستجيب إطلاقًا |
| 3. استدعاء النموذج | المفتاحان، الشبكة، الحصة | TYPE_TEXT needs TEXT_MODEL_API_KEY / Model provider returned HTTP 401 |
| 4. القرار والتنفيذ | تغيّر الصفحة، ميزانية الإجراءات، حدود عناصر التحكم في الصفحة | Target changed or is covered / الحالة تصبح blocked |
ثلاث فئات من الأخطاء، ثلاث معاملات. عند رؤية خطأ، صنّفه أولًا ولا تتعجّل بالتدخل:
| النوع | مثال | ما عليك فعله |
|---|---|---|
| ذاتيّة الشفاء (stale، تغيّرت الصفحة) | Page changed since the decision / Target changed or is covered | لا تفعل شيئًا: التشغيل التلقائي سيعيد المراقبة ثم اتخاذ القرار؛ في الوضع اليدوي اضغط Choose next مرة واحدة |
| إعادة المحاولة (رفض مؤقت من الخادم) | 429 / 529 / 503 → يحاول الكود إجمالًا 3 مرات (إعادة محاولة 2 مرات)، وإذا استمر الفشل يظهر Model provider returned HTTP 429/529/503 | انتظر قليلًا ثم أعد التشغيل، وتحقق من الحصة |
| تتطلب تدخلًا (إعداد / ميزانية / حدود) | مفتاح مفقود، HTTP 401، 60 ميزانية الإجراءات، عدم دعم shadow DOM | عدّل الإعدادات أو الهدف أو غيّر الصفحة وفق البنود أدناه |
💡 جدول مقارنة لشريط حالة inspector (النص الأصلي في app.js)
| ما يعرضه شريط الحالة | المعنى | ما عليك فعله |
|---|---|---|
| Ready to explore | لم تضغط Start demo بعد | أدخل الهدف واضغط Start demo |
| Page observed · ready for a decision | تمت ملاحظة الصفحة، بانتظار القرار | اضغط Choose next أو Run automatically |
| Choice ready · inspect or execute | صدر القرار، بانتظار التنفيذ | افحص الاحتمالات ثم اضغط Execute choice |
| Jev reports complete · inspect the page | اختار النموذج DONE | تحقق من الصفحة بنفسك — فـ DONE ليس دليلًا على النجاح |
| Stopped · no supported next action | blocked: إجراءات غير صالحة متتالية أو اختار النموذج BLOCKED | انظر آخر خطوات Decision trail وقارنها بقائمة غير المدعوم |
| Paused · needs attention | توقف مؤقت بسبب خطأ | انظر نص الخطأ في الإطار الأحمر وطابقه مع الحالات |
الفحص الأول: فحص سريع في 60 ثانية
نفّذ الأوامر الأربعة بالترتيب، للتحقق تباعًا من الدليل والمفتاح واتصال Chrome وطبقة تنفيذ المتصفح. الشرط المسبق: الطرفية التي تشغّل uv run jev ما زالت تطبع Jev Ultrafast: http://127.0.0.1:8766، والمتصفح مفتوح عبر 127.0.0.1:8766 (وليس localhost، والسبب في بند استكشاف Forbidden أدناه).
# 1. 当前目录对吗?——.env 从「当前目录」读取,必须在仓库根目录跑
pwd
# 应以 jev-ultrafast 结尾;不在就先 cd jev-ultrafast
# 2. 两个 Key 都配了吗?——应看到两行(值非空才算数)
grep -E "^(TYPESAFE_API_KEY|TEXT_MODEL_API_KEY)=." .env
# 顺手 echo $TYPESAFE_API_KEY 确认 shell 里没有旧值抢先——.env 不会覆盖已 export 的变量
# 3. Chrome 连得上吗?——官方诊断命令
uv run browser-harness --doctor
# 按提示在 Chrome 里允许远程调试
# 4. 浏览器执行层正常吗?——官方开发命令,不调用模型、不花 API 费
uv run python scripts/check_guards.py
# 在本地浏览器里跑执行守卫回归;脚本自己的说明:No model calls or external websitesالمفترض أن ترى: الأمر 1 ينتهي بـ jev-ultrafast؛ الأمر 2 يطبع سطرين؛ الأمر 3 يُكمل تشخيص الاتصال؛ الأمر 4 ينتهي بطباعة PASS: N browser guard checks; no model calls. أي أمر يفشل ابدأ الإصلاح منه؛ وإذا نجحت الأربعة كلها وما زال هناك خطأ، فالمشكلة غالبًا في استدعاء النموذج أو طبقة القرار — طابق مع الحالات أدناه.
استكشاف المشكلات الشائعة
البدء والاتصال بـ Chrome (فشل الاتصال)
"Cannot reach local demo server"
السبب: صفحة inspector لا تستطيع الوصول إلى الخدمة المحلية — uv run jev لا يعمل، أو غُيّر المنفذ، أو أن الصفحة تبويب قديم. تظهر هذه العبارة في شريط الحالة (فرع فشل fetch في app.js).
الحل:
- أعد التشغيل من الدليل الجذري للمستودع، وينبغي أن تطبع الطرفية:
uv run jev
# Jev Ultrafast: http://127.0.0.1:8766- افتح في المتصفح
http://127.0.0.1:8766. إذا غيّرت المنفذ: يجب ضبطTYPESAFE_DEMO_PORTقبل بدء التشغيل (يقرأ demo.py المنفذ عند استيراد الوحدة)، وللتفاصيل انظرمهارات متقدمة في درس التثبيت والتشغيل.
فتح الصفحة يعرض "Forbidden" فقط
السبب: استخدمت localhost:8766 بدلًا من 127.0.0.1:8766. تتحقق خدمة demo من ترويسة Host ولا تعترف إلا بـ 127.0.0.1:8766 — فهذه الخدمة تستمع فقط على عنوان الاسترجاع المحلي (تُسمي demo.py نفسها Loopback-only inspector)، وطلبات POST تحصل أيضًا على {"error": "Local demo requests only"}.
الحل: غيّر العنوان في شريط العناوين إلى http://127.0.0.1:8766 وحدّث الصفحة.
لا يتصل Chrome واللوحة لا تتحرك
السبب: يحتاج Browser Harness إلى السماح بالتصحيح عن بُعد في Chrome، وسيعرض Chrome تنبيهًا عند الاتصال الأول؛ إذا فوّتته أو رفضته يفشل الاتصال. النص الأصلي في README: Allow remote debugging in Chrome when prompted.
الحل:
- نفّذ أمر التشخيص الرسمي، من الدليل الجذري للمستودع:
uv run browser-harness --doctor- عندما يعرض Chrome تنبيه «السماح بالتصحيح عن بُعد» اضغط السماح.
- إذا نجح التشخيص لكنها ما زالت لا تتحرك: نفّذ أولًا
uv run python scripts/check_guards.py— فهو لا يستدعي النموذج ويستطيع التحقق وحده من طبقة تنفيذ المتصفح.
"A browser step is already running"
السبب: الخطوة السابقة ما زالت قيد التنفيذ. تستخدم خدمة demo قفلًا عامًّا واحدًا لضمان تشغيل خطوة متصفح واحدة فقط في اللحظة نفسها، والطلبات التي تصطدم بالقفل تعيد 409 مع هذه العبارة.
الحل: انتظر اكتمال الخطوة الحالية؛ وإذا أردت إيقاف Run automatically أثناء عملها فاضغط Pause.
"Local demo failed; no automatic retry. Reset to recover."
السبب: تلفّ خدمة demo الاستثناءات غير الملتقطة خصيصًا في هذه العبارة 500 كرسالة احتياطية. أكثر الأسباب شيوعًا: TYPESAFE_API_KEY غير مضبوط إطلاقًا — model.py يقرأ os.environ["TYPESAFE_API_KEY"] مباشرة، وغيابه يرمي KeyError ولا يعرض النص الأصلي بل يسقط إلى هذه الرسالة الاحتياطية.
الحل:
- تحقق من المفتاحين في
.env(البند 2 من الفحص السريع في 60 ثانية). - اضغط Reset كما تشير الرسالة: اضغط Start demo لإعادة الفتح مرة أخرى.
- من يستخدم مكتبة Agent سيرى الـ traceback الأصلي مباشرة (مثل
KeyError: 'TYPESAFE_API_KEY')، فيعالج كل مفقود بحسبه.
"Start a demo first"
السبب: في inspector ضُغط Choose next / Execute choice / Run automatically قبل Start demo — ترفض خدمة demo هذه الأوامر قبل إنشاء الـ agent.
الحل: اكتب الهدف أولًا، وانقر Start demo، ثم نفّذ أزرار التحكم.
"Enter 1–2,000 characters"
السبب: الهدف فارغ أو يتجاوز 2000 حرفًا (تحقق reset في demo.py).
الحل: اكتب الهدف ضمن 1–2000 حرفًا. تمرير هدف فارغ عبر مكتبة Agent يرفع Supply a task (agent.py)، وهو المعنى نفسه.
المفتاح واستدعاء النموذج (منطقة الأخطاء الأكثر شيوعًا في TEXT_MODEL)
"TYPE_TEXT needs TEXT_MODEL_API_KEY; no text is hardcoded or guessed by the executor."
السبب: ينقص .env المفتاح TEXT_MODEL_API_KEY. لا يُفعَّل هذا التحقق إلا عندما تكون العملية من نوع TYPE_TEXT (model.py ضمن field_text())، لذلك يمكن للعرض التجريبي أن يبدأ ويمكن ملاحظة الصفحة، لكنه يتوقف فور الوصول إلى «الكتابة في حقل الإدخال» — يحتاج عرض Flights التجريبي إلى توليد أسماء مدن، فلا مفر من ذلك.
الحل:
- أضف مفتاح النموذج النصي في
.env(لمعرفة من أين تحصل عليه، انظرالخطوة 3 من درس التثبيت والتشغيل بالطرق A/B/C). - انتبه لقاعدة القراءة: يقرأ
.envمنالدليل الحالي، ولا يلغي المتغيرات المصدَّرة بالفعل في shell التي تحمل الاسم نفسه — إذا ظهر الخطأ رغم أنك ملأته، فنفّذcd jev-ultrafastثم أعد التشغيل، وتحقق منecho $TEXT_MODEL_API_KEY.
"Model provider returned HTTP 401; no action executed."
السبب: أرجعت نقطة نهاية النموذج رمز حالة خطأ، أُدرج في قالب هذه العبارة (المصدر هو f"Model provider returned HTTP {response.status_code}; no action executed."). 401 = مفتاح غير صالح. هذه العبارة مشتركة بين TypeSafe والنموذج النصي، فحدّد أولًا أي الطرفين:
| متى يظهر الخطأ | أي الطرفين | ما الذي تفحصه |
|---|---|---|
| يظهر الخطأ منذ أول قرار | TypeSafe (القرار يُستدعى في كل دورة) | TYPESAFE_API_KEY |
| يظهر الخطأ عند خطوة الكتابة فقط | النموذج النصي (لا يستخدمه إلا TYPE_TEXT) | ما إذا كان TEXT_MODEL_API_KEY متطابقًا مع TEXT_MODEL_BASE_URL |
الحل:
- على جانب TypeSafe: عُد إلىصفحة Keys في وحدة التحكم وأعد نسخ المفتاح، ويمكنك التحقق باستخدام curl (يوجداستكشاف أخطاء البدء أمر كامل).
- على جانب النموذج النصي: تأكد من أن المفتاح يخص نقطة النهاية التي ضبطتها (مفتاح OpenRouter مع نقطة نهاية DeepSeek يعني 401).
- معاني رموز الحالة الأخرى (400/413/415/422 وما إلى ذلك) تجدها في جدول رموز الحالة ضمنمرجع API السريع — 429/529/503 لا تُبلغ عنها فورًا، انظر أدناه "Model provider returned HTTP 429/529/503".
"Model connection failed; no action executed."
السبب: ألقى عميل HTTP استثناءً على مستوى الشبكة — تعذّر الوصول إلى نقطة النهاية، أو فشل تحليل DNS، وما شابه؛ لم يُرسَل الطلب أصلًا (model.py يلتقط httpx.HTTPError ثم يلقي هذه العبارة).
الحل:
- تحقق من قدرة الشبكة على الوصول إلى
api.typesafe.aiوTEXT_MODEL_BASE_URLالخاص بك. - تحقق من كتابة نقطة النهاية: الخطأ الشائع في
TEXT_MODEL_BASE_URLهو نقص أو زيادة/v1(القيمة النموذجيةhttps://openrouter.ai/api/v1، وافتراضي DeepSeek هوhttps://api.deepseek.com/v1).
"Model provider returned HTTP 429/529/503; no action executed." (تحديد المعدل والحمل الزائد)
السبب: أرجعت نقطة نهاية النموذج 429 (تحديد المعدل) / 529 (حمل زائد) / 503. لا تُبلَّغ رموز الحالة هذه فورًا: يحاول الكود 3 مرات إجمالًا (إعادة محاولة 2 مرات، بفواصل 0.5 ثانية و1 ثانية)، وعند فشل المحاولة رقم 3 يُدرج رمز الحالة في القالب أعلاه ويظهر Model provider returned HTTP 429; no action executed. (529 و503 بالصيغة نفسها).
توجد في المصدر أيضًا عبارة احتياطية "Model unavailable" (model.py السطر L27)، لكنها غير قابلة للوصول وفق تدفق التحكم الحالي — بعد استنفاد محاولات 429/529/503 يُتَّبع قالب رمز الحالة، فلا تظهر هذه العبارة في الواجهة؛ إذا وجدتها في المصدر، فطبّقها على هذا البند.
الحل: انتظر قليلًا ثم أعد المحاولة؛ إذا تكرر ظهورها فافحص الحصة — على جانب TypeSafe انظر فيصفحة rate-limits في وحدة التحكم، وعلى جانب النموذج النصي انظر صفحة الفواتير لدى مزوّدك.
"Invalid TypeSafe response; no action executed."
السبب: استجابة القرار لم تجتز التحقق المحلي (model.py ضمن validate_choice(): يجب أن يكون الخيار المحدد ضمن المرشحين، وأن يكون لكل خيار احتمال، وأن تكون القيم ضمن 0–1، وأن يبلغ مجموع الاحتمالات نحو 1). هذا حارس ضد «الاستجابة غير المطابقة للعقد»، وليس مشكلة في إعداداتك.
الحل: أعد التشغيل كما هو أولًا (خطأ عابر)؛ إذا استمر الظهور فصدّر التتبع (انظر «ما زال لا يعمل؟») وأرفقه بالملاحظات.
"Text helper returned no valid field value; nothing typed."
السبب: مخرجات النموذج النصي لا تطابق العقد — يجب أن تكون JSON بمفتاح text وحده، وقيمته سلسلة نصية غير فارغة لا تتجاوز 2000 حرفًا (قواعد التحليل في model.py). محفّزان شائعان:
| المحفّز | الآلية |
|---|---|
| قيمة إلزامية ناقصة في الهدف | تنص تعليمات النموذج صراحةً: عند نقص القيمة أرجِع {"text": null} ولا تختلق بيانات شخصية أبدًا (TEXT_VALUE في questions.py) — فشل تحليل null، فلا يُكتب شيء |
| نموذج لا يلتزم بالقواعد | أخرج نصًا تعليقيًا بدلًا من JSON — التقرير الرسمي للأداء يذكر أنه رُفض نموذج من هذا النوع أثناء الاختبار |
الحل:
- اكتب في الهدف القيم التي تحتاجها المهمة (مثل التواريخ وأسماء المدن، ولا تدع النموذج يخمّن).
- إذا لم ينجح ذلك فبدّل النموذج النصي، وأبقِ
TEXT_MODEL_REASONING=none(النماذج المعطّلة الاستدلال أقل ارتجالًا). - حتى إذا أدخلت قيمة خاطئة (وليس ترك الإدخال فارغًا) فالمعالجة هي نفسها — الاختبار الرسمي رفض سابقًا نموذجًا كتب نقطة الانطلاق والوجهة بالعكس، لذا جرّب النموذج أولًا بمهمة صغيرة قبل تغييره.
انقطاع التنفيذ والميزانية (لا يتحرك النقر)
"Target changed or is covered. Observe again."
السبب: فحص السلامة قبل التنفيذ اكتشف أن الهدف قد تغيّر: تمت تغطيته أو إخفاؤه أو تعطيله أو نقله خارج نطاق العرض، أو أنه لم يعد نفس العنصر الذي تمت ملاحظته. هذا هو الحارس أثناء عمله، وليس خطأ برمجيًا — مخرجات النموذج تشير دائمًا فقط إلى عناصر حقيقية تمت ملاحظتها، وقبل التنفيذ يُعاد التحقق من الموقع الهندسي مرة أخرى.
الحل: أعد الملاحظة ثم اتخذ القرار من جديد. في التشغيل التلقائي (بدون Slow motion) تسير كل خطوة عبر tick، وهذه الأخطاء من نوع stale تُبتلع تلقائيًا مع إعادة الملاحظة فلا تراها أبدًا؛ في التنفيذ اليدوي خطوة بخطوة أو مع تفعيل الوضع البطيء سيتوقف العرض ويظهر النص الأصلي، فقط انقر Choose next لإعادة اتخاذ القرار.
"Page changed since the decision. Choose again."
السبب: عائلة stale — تغيّرت الصفحة بعد اتخاذ القرار فأصبح القرار القديم لاغيًا. المتغيرات من نفس العائلة: Page changed before text generation. Choose again. (تغيّرت الصفحة قبل توليد النص)، Page changed since this decision. Observe again. (إعادة الفحص قبل التنفيذ)، Document changed during evaluation / Document is navigating (الصفحة تتغير أثناء الملاحظة).
الحل: كما سبق، أعد الملاحظة. تفصيلان:
- القيمة المولّدة للكتابة لا تذهب سدى: فقط عندما يبقى مدخل مساعد النص دون أي تغيير، ستُعيد المحاولة استخدام القيمة المولّدة في المرة السابقة (قسم Reuse an interrupted text request في README).
- تكرار ظهور هذا الخطأ يعني أن الصفحة مليئة بالرسوم المتحركة/التحميل، انتظر قليلًا قبل التشغيل أو اختر صفحة أكثر استقرارًا.
"Page did not settle"
السبب: في 10 ملاحظات متتالية (بفاصل 20ms لكل منها) لم تستقر الصفحة — الرسوم المتحركة لا تتوقف أو التحميل مستمر.
الحل: انتظر حتى تهدأ الصفحة ثم شغّل؛ بعض الصفحات الثقيلة (رسوم متحركة عند التمرير، شاشات هيكلية دائمة) قد لا تكون مناسبة أصلًا.
"Dropdown execution was not confirmed; inspect before retrying."
السبب: لم يتم تأكيد نتيجة تنفيذ <select> الأصلي، أو تمت مقاطعة التنفيذ (النص المتغير: Dropdown execution was interrupted; inspect before retrying.). يختار الكود هنا التوقف بحذر بدلًا من إعادة المحاولة بشكل أعمى — إعادة المحاولة قد تسبب تحديدًا مزدوجًا.
الحل: أعد الملاحظة (Choose next / إعادة التشغيل)، ليتخذ الـ agent قرارًا جديدًا بناءً على الصفحة الجديدة.
"Observe and choose before acting"
السبب: في الوضع اليدوي نُقر Execute choice دون وجود قرار، أو تغيّرت بصمة الصفحة بعد صدور القرار وكان القرار قد استُهلك بالفعل.
الحل: انقر Choose next مرة واحدة للحصول على قرار جديد، ثم Execute choice.
"Stopped at the 60-action demo budget"
السبب: نفدت الميزانية الصارمة للتشغيل الواحد: بحد أقصى 60 إجراء منفَّذًا (MAX_STEPS = 60). أما عدد استدعاءات القرار فله حد أقصى منفصل 120 (MAX_STEPS × 2)، وعند بلوغه يظهر Reached the demo's model-call budget.
الحل: إذا كانت المهمة كبيرة فقسّمها إلى مهام أصغر — معامل المثال الرسمي لـ examples/run.py اسمه 'A narrow goal'، وكتابة هدف ضيق هي التوصية الرسمية. إذا لم ينتهِ التشغيل ضمن الميزانية، فهذا يعني عادةً أن الهدف واسع جدًا أو أن الصفحة غير مناسبة (انظر المجموعة التالية).
"This run has stopped. Start a fresh demo."
السبب: الحالة أصبحت done أو blocked بالفعل، ومع ذلك يُطلب قرار جديد — انتهى هذا التشغيل.
الحل: انقر Start demo لبدء تشغيل جديد.
شريط الحالة يعرض "Stopped · no supported next action" (blocked)
السبب: مصدران محتملان: النموذج اختار BLOCKED طوعًا (تعريف التعليمات: لا يوجد إجراء مدعوم يمكنه دفع المهمة قدمًا)، أو أن 3 إجراءات منفَّذة متتالية (ولا شيء منها WAIT) لم يطرأ بعدها أي تغيير على الصفحة — يحدد الكود أن الأمر عالق ويحوّل تلقائيًا إلى blocked.
الحل:
- انظر آخر 3 خطوات في Decision trail: ما الذي نُقر، ولماذا لم تتغير الصفحة.
- قارن مع مجموعة «قائمة غير المدعوم» أدناه — السبب الجذري الأكثر شيوعًا لـ blocked هو وجود عناصر تحكم لا يمكن تشغيلها في الصفحة.
- اجعل الهدف أضيق وأكثر تحديدًا، ثم أعد فتح الـ demo.
نتائج خاطئة وحدود الصفحة (انحرف المسار)
شريط الحالة يعرض "Jev reports complete · inspect the page"، لكن الصفحة ليست ما تريده
السبب: اختار النموذج DONE، لكن DONE ليس أبدًا دليلًا على النجاح — الرسميون كتبوا ذلك بوضوح في Evidence and limits: حتى مع اختيار DONE يجب التحقق من النتيجة بشكل مستقل. النصف الثاني من جملة شريط الحالة في الواجهة (inspect the page) هو تذكير لك بأن تنظر بنفسك.
الحل:
- للمهام المهمة أضف تحققًا مستقلًا. النموذج الرسمي هو
examples/flights.pyفيverify(): مطابقة بندًا بندًا على صفحة النتائج — اتجاه واحد، نقطة الانطلاق، الوجهة، التاريخ، ظهور النتائج — عدم الثقة في DONE الصادر من النموذج؛ وإذا لم ينجح التحقق فاخرج وأبلغ عنFinal page did not satisfy the route/date checks. - اكتب شرط التوقف بوضوح في الهدف. هدف مثال Flights الرسمي ينتهي بـ
Stop when …، فاكتب بهذه الصياغة. - أهداف من نوع «فتح نتيجة معينة» تحتاج انتباهًا خاصًا: تعليمات النموذج تنص صراحةً على أن «مجرد العثور على الرابط المطابق لا يُعد إنجازًا».
النقر على عنصر تحكم دون استجابة / عدم وجوده أصلًا في قائمة العناصر (shadow DOM، canvas، رفع الملفات……)
السبب: الاصطدام بحدود الـ MVP. قارئ DOM يتعرف فقط على عناصر HTML وARIA الشائعة، ولا يطبق خوارزمية accessible-name الكاملة. وفق قائمة Limits الرسمية، ما يلي غير مدعوم جميعه:
| غير مدعوم | أمثلة |
|---|---|
| shadow roots / frames | عناصر التحكم الداخلية التي تعرضها أطر المكونات |
| canvas | التفاعلات من نوع الخرائط ولوحات الرسم |
| رفع الملفات | <input type="file"> |
| فتح تبويب جديد منبثق | روابط تفتح تبويبًا جديدًا بعد النقر |
| تمرير متداخل | حاويات تمرير داخلية |
| مكونات لوحة المفاتيح التعسفية | الاختصارات، محررات النصوص الغنية |
الحل: قبل بدء المهمة قارنها بالقائمة أولًا، والصفحات التي تتضمن هذه العناصر لا تحاول اقتحامها حاليًا (الخطوة 4 من درس المبادئ تحتوي على نفس الحدود)؛ اختر صفحة أو مهمة تحتوي فقط على عناصر تحكم اعتيادية. وانتبه أيضًا: تبويب الـ agent يستخدم Chrome profile الحالي لديك — حالة تسجيل الدخول تؤثر على محتوى الصفحة، فخذ هذا الجانب في الحسبان عند تشخيص مشكلة «الصفحة مختلفة عن المتوقع».
النص المكتوب غير صحيح، أو النص المطلوب كتابته لم يُكتب
السبب: السلسلة النصية يستنتجها مساعد النص من الهدف، وليست مكتوبة بواسطة Jev. إذا كان الحرف غير صحيح = فهم نموذج المساعد انحرف؛ وإذا لم تُكتب = أعاد القيمة وفق القواعد {"text": null} (يرفض اختلاق قيمة إلزامية مفقودة في الهدف، راجع بند nothing typed أعلاه).
الحل: اكتب القيمة الإلزامية حرفيًا في الهدف («September 20, 2026» بدلًا من «الشهر القادم»)؛ إذا لم ينجح فبدّل نموذج النص، وجرّبه أولًا بمهمة صغيرة — الرسمي نفسه اعتمد على ست نداءات استطلاع لاستبعاد النماذج التي عكست ترتيب المدن وأخرجت تعليقات (راجع قراءة الأداء).
يملأ الحقول لكن لا يرسل، يكتب النص لكن لا يختار الاقتراح
السبب: تعليمات النموذج تثبّت هذه القواعد فعليًا: بعد ملء الحقول الإلزامية يجب الإرسال («الحقول المملوءة لا تعني بحثًا مُطبَّقًا»)، وبعد كتابة الاستعلام يجب اختيار اقتراح الإكمال التلقائي المطابق. عدم الالتزام غالبًا مسألة توقيت — بعد الكتابة ينتظر الكود بحد أقصى 200ms لتظهر الاقتراحات، والمواقع البطيئة في تحميل الاقتراحات قد لا تلحق بالملاحظة التالية.
الحل: إعادة التشغيل نفسها مرة أخرى تجتاز عادةً؛ إذا استمر التعثر في نفس النقطة فاجعل الهدف أوضح (ماذا يُرسل، أين يتوقف)، أو بدّل إلى صفحة تُحمّل اقتراحاتها بسرعة.
ما زال لا يعمل؟
اعزل أولًا، ثم اجمع الأدلة، وأخيرًا اسأل ومعك الأدلة.
أداة العزل هي السكربتان المرفقان بالمستودع (كلاهما في scripts/، من قسم Development في README):
# 只测浏览器执行层:本地页面、不调用模型、不花钱
uv run python scripts/check_guards.py
# 测完整链路:浏览器只开本地 fixture 页面,但会发起真实模型调用(产生付费 API 费用)
uv run python scripts/smoke.pycheck_guards.py نجح، وsmoke.py نجح أيضًا، والموقع الحقيقي ما زال يفشل — المشكلة غالبًا في الموقع نفسه (حدود عناصر التحكم، توقيت التحميل)، قارن بقائمة غير المدعوم.
اجمع الأدلة، ثلاثة أشياء تكفي:
| الدليل | كيف تحصل عليه | ماذا يحتوي |
|---|---|---|
| تتبع القرارات | أسفل inspector زر Export trace ↓ | تنزيل typesafe-browser-trace.json: تاريخ القرارات كاملًا، والاحتمالات، والهدف، وعنوان URL للصفحة والنص المرئي (بدون لقطات شاشة) |
| ما رآه النموذج | قسم الصفحة القابل للطي What the model sees | جسم الطلب الكامل المرسل إلى النموذج، قابل للفحص حقلًا حقلًا |
| نص رسالة الخطأ الأصلي | الجملة داخل الإطار الأحمر | جميع عناوين H4 في هذه الصفحة تطابقها |
⚠️ راجع قبل الإرسال
يحتوي التتبع على عنوان URL للصفحة والنص المرئي، وقد يشمل معلومات حسابك؛ وانتبه أيضًا: مثال live وسكربتات التسجيل كلاهما يُنشئ نداءات API مدفوعة (بنص README)، فكن على دراية قبل إعادة الإنتاج مرارًا.
أين تسأل:
| القناة | متى تلجأ إليها |
|---|---|
| هذا الدرس + التثبيت والتشغيل | راجع نفسك مرتين أولًا، معظم المشكلات لا تصل إلى هذه المرحلة |
| استكشاف أخطاء البدء / مرجع API سريع | TypeSafe مشكلات رموز الحالة من جهة API |
| GitHub Issues | عيوب Ultrafast نفسها: أرفق التتبع + نص الخطأ الأصلي + الهدف وعنوان URL |
| TypeSafe Discord | مشكلات جهة API القرارات (Jev)، يقول المسؤولون أبلغ مباشرة إذا انكسر |
| Browser Use Cloud | مشكلات عند استخدام BU Ultrafast المُدار (model: "bu-ultrafast") |
نقاط تحقق ✅
- 60 فحص سريع في 60 ثانية: الأوامر الأربعة كلها جرت، وأعرف أين علِقت في أي طبقة
- أستطيع التمييز بين ثلاثة أنواع من الأخطاء: stale يلتئم ذاتيًا، و429/529/503 يُعاد تلقائيًا، والتكوين/الميزانية/الحدود تتطلب تدخلًا يدويًا
- عندما تكون الحالة done لا أعتبر العمل منتهيًا مباشرة — أضيف تحققًا مستقلًا للمهام المهمة (verify() في flights.py هو النموذج)
- ألقي نظرة على قائمة غير المدعوم: shadow DOM، وframes، وcanvas، والرفع، وtab جديد، والتمرير المتداخل، ومكونات لوحة المفاتيح
- عند السؤال أرفق typesafe-browser-trace.json ونص الخطأ الأصلي والهدف وعنوان URL
خلاصة هذا الدرس
✅ في استكشاف الأخطاء حدد الطبقة أولًا: الخدمة المحلية ← اتصال Chrome ← نداء النموذج ← تنفيذ القرار، ولكل طبقة مظهر أخطاء مختلف.
✅ نصوص أخطاء jev-ultrafast كلها من مصدر المستودع، قابلة للبحث حرفيًا؛ عناوين H4 هي نص الخطأ نفسه، انسخها للبحث أو للسؤال.
✅ ثلاث فئات معاملة: فئة stale تُترك لإعادة الملاحظة التلقائية، و429/529/503 تُترك لإعادة المحاولة في الكود، وفئات التكوين/الميزانية/الحدود فقط تحتاج تدخلك.
✅ DONE ليس دليل نجاح، وblocked تحقق أولًا من قائمة غير المدعوم، وإجراء 60 ميزانية صارمة — إذا حفظت هذه الثلاثة تتجنب مسبقًا نصف حالات «الانحراف».
مرجع سريع للإشارات الرئيسية:
| الإشارة | في أي طبقة | الخطوة الأولى |
|---|---|---|
| Cannot reach local demo server / Forbidden | الخدمة المحلية | أعد تشغيل uv run jev؛ افتح بـ 127.0.0.1:8766 |
| اللوحة لا تتحرك إطلاقًا | اتصال Chrome | uv run browser-harness --doctor، واسمح بالتصحيح عن بُعد |
| TYPE_TEXT needs TEXT_MODEL_API_KEY | نداء النموذج (جهة النص) | .env أضف المفتاح، وانتبه إلى cwd وsetdefault |
| Model provider returned HTTP 401 | نداء النموذج (مفتاح غير صالح) | ميّز أولًا TypeSafe أم نموذج النص، ثم أعد نسخ المفتاح |
| Model provider returned HTTP 429/529/503 | نداء النموذج (تحديد المعدل/التحميل الزائد) | انتظر قليلًا وأعد التشغيل، وتحقق من الحصة |
| Target changed or is covered | تنفيذ القرار (stale) | أعد الملاحظة؛ الوضع التلقائي يلتئم ذاتيًا |
| Stopped at the 60-action demo budget | تنفيذ القرار (الميزانية) | اجعل الهدف أضيق، وقسّم المهمة إلى أجزاء صغيرة |
| الحالة done لكن النتيجة خاطئة | التحقق من النتائج | تحقّق بنفسك؛ أضف تحققًا مستقلًا على نمط flights.py |
| الحالة blocked | حدود الصفحة | قارن بقائمة العناصر غير المدعومة، وغيّر الصفحة أو عدّل الهدف |
نظرة على الدرس القادم
بهذا نختتم جزء المتصفح. الدرس القادم Jev 1.13 دليل تجنّب المطبات:9 نمط فشل وحلول بديلة يعود إلى Jev النموذج نفسه — خارج Ultrafast، ينطبق على جميع تطبيقات Jev. ستتعلم:
- أنماط الفشل الـ 9 في وثائق jaggedness الرسمية: الفهم الحرفي، العدّ الحسابي، مقارنة التواريخ، الإشارة غير المباشرة…
- الحلول البديلة لكل نمط فشل: ضع الحساب في الكود، استخرج مكونات التاريخ، صفِّ الحالة الكبيرة أولًا
- كيف تصبّ عادات الطرح هذه في مصلحة أهدافك في Ultrafast وتطبيقات Jev الأخرى
دروس ذات صلة
- تثبيت Ultrafast وتشغيله: uv sync مع مفتاحي API
- تشغيل Google Flights بنجاح: 7 ثوانٍ لإتمام بحث حقيقي واحد
- ماذا تفعل إذا فشل التثبيت أو التشغيل: استكشاف أخطاء البداية وإصلاحها
ملحق: مرجع الكود المصدري
اضغط للتوسيع ومعرفة مواضع الكود المصدري
آخر تحديث: 2026-11-04 (المستودع github.com/browser-use/jev-ultrafast، مصدر المعلومات المحلي sources/jev/repo-ultrafast/)
| الوظيفة | مسار الملف | المواضع الرئيسية |
|---|---|---|
| نص الخطأ الأصلي: الاتصال/HTTP/إعادة المحاولة | jev_ultrafast/model.py | L15–27 post_json (L20 فشل الاتصال، L21–23 إعادة محاولة تلقائية لـ 429/529/503 بإجمالي 3 محاولات، L25 قالب رمز حالة HTTP، L27 نص احتياطي Model unavailable · غير قابل للوصول في تدفق التحكم الحالي)؛ L12 مهلة العميل timeout=25 |
| نص الخطأ الأصلي: التحقق من استجابة القرار | jev_ultrafast/model.py | L30–45 validate_choice (L44 Invalid TypeSafe response) |
| نص الخطأ الأصلي: helper النصوص | jev_ultrafast/model.py | L160–198 field_text (L163 نص الخطأ عند نقص مفتاح، L187–193 التحقق من عقد JSON، L193 nothing typed) |
| طلب TypeSafe وقراءة المفتاح | jev_ultrafast/model.py | L119 (api.typesafe.ai/v1/systemone + os.environ["TYPESAFE_API_KEY"]، يرمي KeyError عند غيابه) |
| نص الخطأ الأصلي: الميزانية وآلة الحالة | jev_ultrafast/agent.py | L74 توقّف، L75–76 ميزانية استدعاء النموذج (MAX_STEPS×2=120)، L88–89 الملاحظة قبل التنفيذ، L96/L107–108 نص stale الأصلي، L102–104 ميزانية أفعال 60، L153–158 3 مرات متتالية دون تغيير ← blocked |
| نص الخطأ الأصلي: stale وحارس التنفيذ | jev_ultrafast/browser.py | L86 Page did not settle، L102 تغيّر الصفحة قبل التنفيذ، L130–131/L162–163 القائمة المنسدلة غير مؤكدة/مقاطَعة، L164 الهدف مغطى؛ L16 StalePage(ValueError) |
| نص الخطأ الأصلي: خدمة demo | jev_ultrafast/demo.py | L16 المنفذ (يُضبط قبل التشغيل بـ TYPESAFE_DEMO_PORT)، L23–29 قراءة .env (cwd + setdefault)، L48–52 السيناريوهات وحرف 1–2000، L64–65 Start a demo first، L111–112 قفل الخطوة الواحدة 409، L122–123 الاحتياط 500 |
| شريط حالة inspector وعرض الأخطاء | jev_ultrafast/static/app.js | L63 Paused · needs attention، L82–88 نصوص الحالات الخمس، L173–183 الحلقة التلقائية (الشفاء الذاتي بـ tick مقابل الخطوات البطيئة)، L217–235 تصدير trace (مع إزالة لقطات الشاشة)، L243 Cannot reach local demo server |
| أزرار الواجهة والمناطق القابلة للطي | jev_ultrafast/static/index.html | L56–59 Choose next / Execute choice / Run automatically / Pause، L126 Export trace ↓، L133 What the model sees |
| تعليمات النموذج (DONE/BLOCKED/الإرسال/قواعد الاقتراح) | jev_ultrafast/questions.py | L3–14 NEXT_ACTION، L21–24 TEXT_VALUE (إرجاع null عند نقص القيمة، وعدم اختلاق معلومات شخصية)، L26 MAX_STEPS = 60 |
| التثبيت، --doctor، التصحيح عن بُعد، قائمة الميزات غير المدعومة | README.md | س53–68 Try it (يتضمن uv run browser-harness --doctor)، س118–126 Evidence and limits (تتطلب DONE تحققًا مستقلًا؛ shadow roots/frames/canvas/الرفع/تبويب جديد/التمرير المتداخل/مكونات لوحة المفاتيح غير مدعومة؛ يستخدم التبويب ملف تعريف Chrome الحالي)، س128–138 Development (check_guards، تنبيه الدفع) |
| قائمة الميزات غير المدعومة (نص Limits الأصلي) | docs/performance.md | س53–55؛ س49 اكتشاف النماذج المرفوضة (كتابة مدينة معكوسة/تعليقات في المخرجات) |
| نموذج للتحقق المستقل | examples/flights.py | س18–38 verify() التحقق بندًا بندًا، س63–64 Final page did not satisfy the route/date checks |
| سكربت اختبار الانحدار للحُرّاس المحليين | scripts/check_guards.py | س1 سلسلة التوثيق (No model calls or external websites)، س133 الطباعة في النهاية PASS: N browser guard checks; no model calls |
| سكربت اختبار دخان للـ fixtures المحلية | scripts/smoke.py | س1 سلسلة التوثيق (واجهة API مدفوعة)، س19 --max-actions (الافتراضي 15)، س25 طباعة مسار مجلد trace |