Skip to content

تشغيل Google Flights: إكمال بحث حقيقي في 7 ثانية ​

في الدرس السابق جهّزنا البيئة، وفي هذا الدرس سيقوم الوكيل بعمل حقيقي: إعادة إنتاج تسجيل Jev Ultrafast Google Flights الرسمي — على Google Flights الحقيقي، إكمال بحث باتجاه واحد من Zürich → London بهدف من جملة واحدة بلغة طبيعية. في الفيديو الرسمي استغرقت هذه الرحلة 7.073 ثانية (تشغيل بالسرعة الأصلية بمعدل 1×)، بما يشمل استدعاءات النموذج وتوليد أسماء المدن وعمليات المتصفح وانتظار التحميل.

يستخدم هذا الدرس الهدف نفسه في مسارين: أولًا فهم العملية قرارًا بقرار في inspector، ثم إعادة إنتاج التسجيل باستخدام examples/flights.py ليتحقق الكود من النتيجة بشكل مستقل. في الأثناء ستواجه مرارًا تذكيرًا رسميًا — DONE لا يُحتسب، التحقق المستقل هو ما يُحتسب — وهو بطل هذا الدرس.

ماذا ستستطيع أن تفعل بعد إتمام الدرس ​

  • إكمال بحث حقيقي في سيناريو Google Flights · real web في inspector، ورؤية كيف تُختار العمليات والأهداف خطوة بخطوة باستخدام Choose next
  • إعادة إنتاج التسجيل الرسمي باستخدام uv run --env-file .env python examples/flights.py --keep-open: بحث وتحقق مستقل وحفظ trace، دون أي اختيار أو حجز
  • شرح ما يفحصه كل من فحوصات 7 المستقلة في verify() (مثلًا قيمة حقل origin يجب أن تكون Zürich)، ولماذا لا يصلح DONE كدليل على النجاح
  • توضيح طريقة احتساب زمن 7.073 ثانية: من أول تنبؤ إلى قبول DONE، وما يدخل في الحساب وما لا يدخل
  • معرفة كيفية تعديل الهدف وسلاسل التحقق معًا عند انتهاء صلاحية تواريخ المثال، لتحويل المثال إلى تجربتك الخاصة في البحث التلقائي عبر المتصفح

مشكلتك الحالية ​

  • في الفيديو الرسمي يكتمل البحث عن الرحلات في 7 ثانية، لكن عند تشغيل inspector بنفسك تنتهي الصفحة بضغطات قليلة — لم ترَ بوضوح ما اختاره Jev في كل خطوة ولا لماذا اختاره
  • تريد أن تخبر الآخرين بأن «هذا الوكيل يعمل فعلًا»، لكن لا تملك دليلًا سوى «لقد قال DONE» — ماذا لو كان قد بحث خطأ في الواقع؟
  • كتابة سكربتات تعبئة النماذج التلقائية بنفسك مؤلمة: المحددات كلها تعتمد على تفكيك DOM، وأي تعديل في Google يُسقطها دفعة واحدة، كما أنها لا تتعامل مع منتقي التواريخ والإكمال التلقائي وهي عناصر «تتطلب انتظار استجابة الصفحة»

متى تستخدم هذه الطريقة ​

عندما تحتاج إلى:

  • أن ترى بعينيك أن Jev Ultrafast يستطيع إكمال بحث كامل على موقع حقيقي (وليس صفحة اختبار محلية)
  • طريقة تشغيل قابلة للتكرار والتحقق لمعيار ultrafast flights، لتعديل الهدف أو الموقع لاحقًا وإجراء تجارب مقارنة
  • عرض وكيل متصفح لفريقك أو أصدقائك، مع القدرة على الإشارة إلى فحوصات 7 true في verify() والقول «النتيجة تم التحقق منها»

ولا تريد:

  • كتابة سكربت محددات لـ Google Flights يدويًا — يصبح بلا فائدة مع أي تعديل في الصفحة
  • إعلان نجاح المهمة بناءً فقط على قول النموذج DONE

🎒 التحضير قبل البدء ​

  • إتمام تثبيت Ultrafast وتشغيله: uv sync لتثبيت التبعيات، و.env لتعبئة TYPESAFE_API_KEY وTEXT_MODEL_API_KEY، وأن inspector يفتح 127.0.0.1:8766
  • الاتصال بـ Chrome مرة واحدة على الأقل (السماح بالتصحيح عن بُعد عند أول Start demo؛ إن لم ينجح الأمر عُد إلى الدرس السابق وشغّل uv run browser-harness --doctor)
  • تمكّن الشبكة من الوصول إلى www.google.com وapi.typesafe.ai — هذه المرة سيخرج الاتصال إلى الإنترنت فعلًا
  • الاطلاع على Jev مبادئ Ultrafast وأنواع العمليات الـ 8 و«قرار مزدوج في جولة واحدة»، حتى لا تُربكك لوحة inspector
  • كوب من الماء — 7 ثانية وقت قصير، لكنك ستشاهدها اليوم مرات كثيرة

الفكرة الأساسية ​

لم تختر الجهة الرسمية Google Flights كـ«امتحان تخرج» عبثًا: النموذج معقّد (تبديل الاتجاه الواحد، حقلان للمدينة مع إكمال تلقائي، منتقي تواريخ، زر بحث)، والتحميل واقعي (صفحة النتائج تتطلب انتظارًا)، والأهم أن النتيجة قابلة للتحقق آليًا — فعنوان URL وقيم الحقول وقائمة الرحلات كلها موجودة في صفحة النتائج.

ثلاثة أمور في هذا الدرس:

**1. جملة هدف واحدة هي كل المدخلات. ** النص الحرفي من README: لا توجد في السياسة سكربتات إجراءات مخصصة لمواقع معينة ولا سلاسل حقول مُعدّة مسبقًا (There are no site-specific action scripts or prepared field strings in the policy). كل ما تقدمه هو عنوان URL بداية وجملة هدف، والباقي يعتمد كليًا على جدول العناصر المرقّمة المُولّد ديناميكيًا من الملاحظة في كل جولة — لذلك يمكن للسياسة نفسها بالانتقال إلى عنوان URL وهدف مختلفين أن تفتح Wikipedia (مثال الدرس 5).

**2. 7 ثانية هي ثواني «حلقة القرار»، وله معيار واضح. ** الفيديو الرسمي 7,073 ms: يبدأ من أول تنبؤ (بعد ملاحظة الصفحة الأولية)، وينتهي عند قبول DONE؛ ويشمل استدعاء النموذج وتوليد النص وعمليات المتصفح وقرارات stale وانتظار التحميل؛ ولا يشمل تشغيل المتصفح أو التنقل الأولي أو التحقق المستقل اللاحق. من الطبيعي ألا تتطابق الثواني التي تحصل عليها مع هذا — تفاصيل المعيار سنفككها في الدرس التالي قراءة الأداء.

**3. DONE لا يُحتسب، بل verify() هو ما يُحتسب. ** يذكر README بوضوح: A DONE choice still requires independent outcome verification (اختيار DONE لا يزال يتطلب تحققًا مستقلًا من النتيجة). examples/flights.py يحتوي بالفعل على verify() — وهو يقرأ صفحة النتائج نفسها، وليس إجابة النموذج.

نفس الهدف، طريقتان للتشغيل، ولكل منهما دورها:

inspector (uv run jev)السكربت (examples/flights.py)
الاستخداممشاهدة القرارات بالعينالقياس بالساعة الإيقافية + تحقق تلقائي
لقطات الشاشةمفعّلة (يمرّرها demo صراحةً screenshots=True)غير مفعّلة (Agent الافتراضي screenshots=False)
التحقق من النتائجتنظر بنفسكverify() فحوصات تلقائية من 7 عنصر
لوحة traceExport trace ↓ تصدير يدوييُحفظ تلقائيًا في artifacts/flights/latest/
مناسب لـأول تشغيل، تقدّم بطيء خطوة بخطوةإعادة إنتاج التسجيل الفعلي، وتعديل الهدف لإجراء التجارب

💡 لماذا لا يصلح inspector للقياس الزمني

يذكر README صراحةً أن حلقة agent الافتراضية لا تلتقط لقطات شاشة، وأن inspector هو الذي «فعّل اللقطات» (The inspector opts into screenshots). اللقطات تتطلب عرضًا ونقلًا، وتسير عبر خدمة HTTP محلية — لإعادة إنتاج الثواني الرسمية، استخدم طريقة السكربت في الخطوة 4 من هذا الدرس.

اتبع خطواتي ​

الخطوة 1: افهم الهدف — ما الذي يجب أن يحققه بحث Google Flights هذه المرة ​

لماذا: ما تعطيه لـ Ultrafast هو هدف واحد بلغة طبيعية (بالإضافة إلى URL بداية)، دون سكربتات للموقع ودون قائمة حقول. كل عبارة في الهدف متطلب يجب على agent تحقيقه (ويُتحقق من معظمها) — فكّكه أولًا لتعرف في كل خطوة تالية ما الذي تنظر إليه.

هدف مثال (من GOALS في examples/flights.py، وهو أيضًا النص المعبأ مسبقًا في مربع مهام inspector):

text
Find one-way flights from Zurich to London on September 20, 2026,
for one adult in economy. Stop when matching flight options are visible.
Do not select or book a flight.

المقابل بالصينية: ابحث عن رحلة ذهاب فقط من Zurich إلى London في يوم 20 من شهر 9 سنة 2026، شخص بالغ واحد، درجة اقتصادية؛ توقف عند رؤية خيارات رحلات مطابقة؛ لا تختار رحلة ولا تحجز.

فكّك الهدف جملة جملة، كل متطلب يقابل مهمة، ومعظمها تراقبه verify():

المتطلب في الهدفما يفعله agentالفحص المقابل في verify()
one-way (ذهاب فقط)تبديل ticket type إلى One wayone_way: قيمة الحقل == One way
from Zurichالكتابة في مربع Where from? واختيار اقتراح الإكمال التلقائيorigin: قيمة الحقل == Zürich
to Londonالكتابة في مربع Where to? واختيار الاقتراحdestination: قيمة الحقل == London
September 20, 2026فتح Departure، والنقر على التاريخ ثم التأكيدdate: قيمة الحقل == Sun, Sep 20؛year: يحتوي URL أو نص الصفحة على 2026-09-20
one adult in economyالتحقق من المسافرين ودرجة المقعد وفق التعليمات «اضبط عنصر التحكم لكل متطلب»لا فحص مقابل (عناصر 7 لا تشمل هذا البند)
Stop when … visibleلا تُصدر DONE إلا بعد ظهور النتائج واستيفاء جميع المتطلباتresults: عنصر Select flight واحد على الأقل، وجميعها تحتوي Sunday, September 20
Do not select or bookحتى صفحة النتائج فقط، دون النقر على أي رحلةdocstring المثال: never selects or books a flight

المسافرون ودرجة المقعد ليس لهما فحص verify مقابل — للتحقق من هذا البند عليك فقط النظر إلى صفحة النتائج بنفسك.@@I18N_KEEP_000034@@

تفصيلان يستحقان الانتباه:

  • عنوان URL البداية هو https://www.google.com/travel/flights?hl=en — ?hl=en يثبّت الواجهة على الإنجليزية. تسميات الحقول التي يؤكدها verify() (Where from?، Select flight) كلها بالإنجليزية؛ إن شغّلته بلغة أخرى، لن يتطابق التحقق.
  • الهدف يكتب Zurich (دون علامات تشكيل)، بينما تتوقع verify قيمة الحقل Zürich (مع علامات تشكيل) — بينهما خطوة «الكتابة → اختيار اقتراح الإكمال التلقائي»؛ وبعد اختيار الاقتراح يبقى في الحقل ما يكتبه Google بنفسه. وتطلب تعليمات النموذج أيضًا: A typed query still needs its matching autocomplete suggestion selected.

ينبغي أن ترى: بعد تفكيك الهدف، تنتقل معظم المتطلبات إلى فحص آلي — الذهاب فقط، والمدينتان، والتاريخ، وقائمة النتائج لها فحوصات؛ بينما «بالغ واحد درجة اقتصادية» لا فحص مقابل له، و«لا تختار ولا تحجز» يضمنه تصميم المثال نفسه (نص docstring الحرفي: never selects or books a flight).

  • أن تذكر فحوص verify المقابلة لما لا يقل عن 3 متطلبات من الهدف

الخطوة 2: ابدأ في inspector بحث Jev Ultrafast Google Flights ​

لماذا: عند أول تشغيل على موقع حقيقي، يُنصح بالبدء بـ inspector — فهو يتيح الإيقاف خطوة بخطوة ومشاهدة احتمالات كل مرشح، فتعرف عند حدوث مشكلة أين علِقت.

ابدأ من جذر المستودع (بالبيئة المثبتة في الدرس السابق):

bash
cd jev-ultrafast
uv run jev

ينبغي أن ترى: يطبع الطرفية Jev Ultrafast: http://127.0.0.1:8766. يفتح المتصفح هذا العنوان، ومربع المهام معبأ مسبقًا بهدف Zurich → London من الخطوة 1.

ثم:

  1. تأكد أن قائمة السيناريو المنسدلة هي Google Flights · real web (وهذا هو الافتراضي؛ السيناريوهان الآخران · fixture صفحات محلية لا تخرج إلى الإنترنت)
  2. انقر Start demo، واسمح عند الطلب بالتصحيح عن بُعد في Chrome (ستعرض حالة الواجهة Opening a fresh browser…)
  3. انقر على Run automatically لتشغيل كل شيء دفعة واحدة، وجرّب أولًا بحثًا كاملًا

يفترض أن ترى (الأربعة أمور المذكورة حرفيًا في README): العناصر المرقمة (numbered elements)، واحتمالات العمليات (operation probabilities)، واحتمالات الأهداف (target probabilities)، والإجراءات المنفذة (executed actions). وستعرض منطقة المقاييس على اليمين لكل قرار: Decision time وTarget confidence والعملية المختارة Operation؛ وفي لوحة المتصفح، تبدأ صفحة Google Flights في العمل عليها تلقائيًا. بعد الانتهاء سيعرض شريط الحالة Jev reports complete · inspect the page — فالواجهة كلها تذكّرك: اذهب لفحص الصفحة، ولا تكتفِ بقولها إنه اكتمل.

  • يظهر في inspector العناصر المرقمة وعمودا الاحتمالات، وتبدأ صفحة Google Flights في Chrome بالتغيّر

الخطوة 3: Choose next ببطء، لرؤية سلسلة القرارات خلال 7 ثوانٍ ​

لماذا: 7 ثوانٍ سريعة جدًا، والتشغيل التلقائي حتى النهاية لا يتيح رؤية شيء. Choose next يتوقف قبل التنفيذ ويعرض «كيف تُرتَّب المرشحات» — وهذا أفضل منظور لفهم الـ agent.

انقر Start demo مرة أخرى لبدء جولة جديدة، وسِر هذه المرة خطوة بخطوة: انقر Choose next مرة واحدة للتنبؤ فقط دون تنفيذ — ستُرتَّب منطقة Indexed elements حسب الاحتمالات (يتغير تلميح الواجهة من Choose next to rank إلى Ranked by Jev)، وتعرض منطقة NEXT ACTION العملية والهدف المختارين؛ وبعد أن تفهم انقر Execute choice لتنفيذ فعلي. وإن أردت مشاهدة أبطأ، فعّل Slow motion ثم Run automatically — ستتوقف كل خطوة 450 ms بين «التنبؤ» و«التنفيذ».

بمقارنة الهدف، تبدو سلسلة قرارات جولة نموذجية هكذا (أنواع الإجراءات مأخوذة من تعليمات النموذج وجدول العناصر؛ والترتيب المحدد قد يختلف من جولة لأخرى):

المرحلةما ستراهما يحدث في الخلفية
التبديل إلى ذهاب فقطعنصر من نوع CLICK (مثل Change ticket type، أول مثال في جدول عناصر README)تُحدَّد العملية والهدف في طلب واحد TypeSafe في آنٍ معًا
إدخال المدينةTYPE_TEXT يظهر، وبعد توقف قصير يظهر نص في الحقلhelper النصي يولّد السلسلة (التسجيل الرسمي: Zurich استغرقت 581 ms وLondon 346 ms)؛ وبعد الإدخال تنتظر اقتراحات الإكمال التلقائي (≤200 ms) ثم تختار
اختيار التاريخCLICK Departure → النقر على يوم → النقر على التأكيدنص التعليمات: For date pickers, CLICK the field, date, then confirmation
الإرسالCLICK Searchنص التعليمات: If Search/Submit is visible and the required fields are ready, CLICK it immediately
انتظار النتائجWAITنص التعليمات: WAIT only when … submitted results are still loading
الإنهاءDONEنص التعليمات: DONE requires visible evidence that ALL requirements are satisfied

حساب التسجيل الرسمي (performance.md): 17 طلبًا من Jev و10 تفاعلات زائد 1 انتظار WAIT صريح و2 توليدًا نصيًا؛ وسيط زمن الاستجابة لقرار واحد لدى Jev هو 178 ms؛ نُفِّذ البحث في الثانية 5.217 واكتمل في الثانية 7.073.

يفترض أن ترى: بعد انتهاء التشغيل لا تتعجّل في إغلاق الصفحة، فثلاثة أماكن تستحق المشاهدة —

  • Decision trail: سطر لكل إجراء منفَّذ، مع زمن الاستجابة والاحتمال وPage changed / No change observed — هذا هو trace هذه الجولة، ويمكن تصديره عبر Export trace ↓ إلى typesafe-browser-trace.json

  • Decision trail العدّاد بجانب العنوان: N actions · X.XX s — عدد الإجراءات والثواني التراكمية لهذه الجولة

  • الكتلة القابلة للطي أسفل الصفحة What the model sees: النص الأصلي للـ state المهيكل المُرسَل إلى Jev (وليس لقطة شاشة)؛ وهناك في اللوحة جملة أصلية من الواجهة تستحق التذكر: Operation and target are separate choices in one request. Text is generated only for TYPE_TEXT.

  • استخدم Choose next لإكمال 3 خطوات على الأقل، واذكر العملية والهدف المختارين في كل خطوة

  • افتح What the model sees مرة واحدة، وتأكد أن ما تراه هو state مهيكل وليس لقطة شاشة

الخطوة 4: إعادة إنتاج التسجيل الرسمي باستخدام examples/flights.py ​

لماذا: inspector مخصص لتشاهد أنت (مع تفعيل لقطات الشاشة)، بينما الثواني الرسمية صادرة عن طريقة تشغيل السكربت بدون لقطات؛ ويفعل flights.py أمرين إضافيين — التحقق التلقائي بعد الانتهاء، وحفظ الـ trace على القرص.

في الدليل الجذري للمستودع:

bash
uv run --env-file .env python examples/flights.py --keep-open

لا يمكن حذف أي من المُعاملين:

  • --env-file .env: flights.py لا يقرأ .env بنفسه (هذا المنطق موجود فقط في demo.py)، والمفتاح يُحقَن بالكامل عبر uv — بدونه سيُرمى KeyError: 'TYPESAFE_API_KEY' من أول قرار (يستخدم model.py os.environ["TYPESAFE_API_KEY"] للوصول المباشر إلى القيمة)
  • --keep-open: لا يستدعي agent.close() بعد الانتهاء، وتبقى صفحة النتائج في Chrome ليتسنى لك التحقق منها بعينيك

يفترض أن ترى: يطبع الطرفية التقدم بالتمرير أولًا، ثلاثة حقول في كل سطر — الملّي ثواني التراكمية، والحالة، والإجراء المنفَّذ للتو (تسمية الإجراء مأخوذة من عناصر الصفحة وتختلف كل جولة):

text
<ملّي ثانية> ready <تسمية الإجراء المنفَّذ للتو>
<ملّي ثانية> ready <تسمية الإجراء المنفَّذ للتو>
……
<ملّي ثانية> done <تسمية آخر إجراء منفَّذ>

(توضيحي؛ أرقام الملّي ثانية والإجراءات تعتمد على جولتك الحالية، وحالة السطر الأخير هي done)

ثم تُطبع نتيجة التحقق بصيغة JSON (البنية من flights.py، ومحتوى visible_flights يعتمد على الرحلات المتاحة في ذلك اليوم):

json
{
  "passed": true,
  "checks": {
    "search_page": true,
    "one_way": true,
    "origin": true,
    "destination": true,
    "date": true,
    "year": true,
    "results": true
  },
  "visible_flights": [
    "…当天可选航班的 Select flight 按钮,每条都含 Sunday, September 20…"
  ]
}

إذا كان أي عنصر في عناصر 7 يساوي false، يخرج السكربت برمز غير صفري، وآخر سطر هو:

text
Final page did not satisfy the route/date checks

وفي الوقت نفسه، أُضيف ملفان تحت artifacts/flights/latest/ (لتغيير الدليل أضف --output <目录>):

الملفالمحتوى
state.jsonلقطة كاملة + نتيجة verification (فحوصات 7 عناصر والرحلات المرئية كلها فيه)
session.jsonمعلومات target المتصفح والجلسة

artifacts/ موجود في .gitignore الخاص بالمستودع، فلن يُرسَل الـ trace بالخطأ.

  • تطبع الطرفية في النهاية JSON للتحقق "passed": true
  • يوجد تحت artifacts/flights/latest/ كلا من state.json و session.json
  • صفحة نتائج Chrome لا تزال مفتوحة، ومكان الانطلاق/الوصول/التاريخ هي Zürich / London / Sep 20

الخطوة 5: فهم فحوصات 7 المستقلة في verify() — إجابة DONE لا تُحتسب ​

لماذا: هذه أهم خطوة في هذا الدرس. سلسلة التوثيق في verify() بملف flights.py مكتوبة بوضوح تام: Independent checks on the resulting page, not the model's DONE answer — فهي تفحص صفحة النتائج، وليست التقرير الذاتي للنموذج.

نلقي نظرة على 7 من الفحوصات واحدًا تلو الآخر (أسماء المفاتيح والقيم المتوقعة كلها مأخوذة من الشيفرة المصدرية لملف flights.py):

بند الفحصالتوكيدمعنى النجاح
search_pageاسم المضيف هو www.google.com والمسار هو /travel/flights/searchوصلنا فعلًا إلى صفحة نتائج البحث
one_wayChange ticket type. One way قيمة الحقل == One wayتم تطبيق إعداد الاتجاه الواحد
originWhere from? قيمة الحقل == Zürichتم اختيار الاقتراح الصحيح لمدينة الانطلاق
destinationWhere to? قيمة الحقل == Londonتم اختيار الاقتراح الصحيح لمدينة الوصول
dateDeparture قيمة الحقل == Sun, Sep 20التاريخ المختار هو اليوم 20 من الشهر 9
yearمعامل tfs في URL بعد فك ترميزه بـ base64 يحتوي على 2026-09-20، أو نص الصفحة يحتوي على departing 2026-09-20السنة هي أيضًا 2026 (مساران للتحقق، يكفي تحقق أي منهما)
resultsتسمية إجراء واحدة على الأقل تحتوي على Select flight، وكل واحدة منها تحتوي على Sunday, September 20قائمة النتائج ظُهرت فعلًا، وكلها رحلات ذلك اليوم

ثلاثة تفاصيل تصميمية تستحق أن تنسخها إلى مهامك الخاصة:

  • التحقق يقرأ الصفحة، لا النموذج. إجابة DONE ليست سوى أحد خيارات Jev؛ تستخدم verify() أدوات urlparse وقيم الحقول ونص الصفحة لإعادة تدقيق النتيجة.
  • فحص السنة له مساران. يحمل URL لصفحة النتائج معامل استعلام tfs، تفكه verify() بترميز base64 ثم تبحث عن 2026-09-20؛ وإذا فشل فك الترميز ترجع إلى البحث في نص الصفحة عن departing 2026-09-20. قيمة الحقل Sun, Sep 20 لا تتضمن السنة، لذا يجب فحص السنة بشكل منفصل.
  • الفحوصات مكتوبة بشكل ثابت. فحوص 7 كلها مثبتة على خط الطيران والتاريخ في المثال — إذا غيّرت الهدف فيجب تعديل verify() بالتزامن (انظر بند 2 في تنبيهات المزالق).

إذا فشل أي بند، تصبح passed بقيمة false ويخرج السكربت عبر SystemExit. اعتمد عليها، لا على إجابة DONE.

يجب أن ترى: افتح artifacts/flights/latest/state.json، وستجد أن verification.checks فيه يتطابق واحدًا لواحد مع 7 من أسماء المفاتيح في الجدول أعلاه — كل قيمة true تعبر عن توكيد على صفحة النتائج، وليس عن تقرير ذاتي من النموذج.

  • تستطيع ذكر محتوى التوكيد لما لا يقل عن 3 من بين 7 من الفحوصات

نقاط تحقق ✅ ​

  • اكتمل سيناريو Google Flights · real web في inspector، ويسرد Decision trail الإجراءات المنفذة، ويعرض شريط الحالة Jev reports complete · inspect the page
  • اكتمل تشغيل examples/flights.py --keep-open، وطبعت الطرفية JSON للتحقق "passed": true
  • يوجد تحت artifacts/flights/latest/ كلا من state.json و session.json
  • لم يتم اختيار أي رحلة ولم يتم حجز أي تذكرة طوال العملية — المثال يبحث فقط دون حجز (نص سلسلة التوثيق في flights.py حرفيًا: never selects or books a flight)
  • تستطيع توضيح سبب عدم صلاحية إجابة DONE كدليل على النجاح، وما إذا كانت verify() تفحص صفحة النتائج أم إجابة النموذج

تنبيهات المزالق ​

❌ اعتبار إجابة DONE دليلًا على النجاح ​

الظاهرة: تصل حالة agent إلى done، فتظن أن المهمة نجحت.

السبب: يذكر README بصراحة في قسم Evidence and limits — A DONE choice still requires independent outcome verification. إجابة DONE هي خيار النموذج، وليست حالة الصفحة؛ وتضيف الجهة الرسمية جملة أخرى: العملية الصحيحة قد تكون خاطئة أيضًا (a valid operation can still be wrong). كما أن نص حالة inspector نفسه يكتب inspect the page.

الإجراء الصحيح: انظر إلى passed من verify()، أو تحقق بنفسك من صفحة النتائج (خط الطيران، التاريخ، قائمة النتائج). وعند كتابة مهام المتصفح الخاصة بك لاحقًا (الدرس 5)، يجب كذلك إرفاق تحقق مستقل.

❌ تاريخ المثال أصبح في الماضي، وفحص results لا ينجح ​

الظاهرة: عند تشغيل flights.py، تكون results (أو date/year) بقيمة false، ويخرج السكربت برسالة Final page did not satisfy the route/date checks.

السبب: كل من GOALS و verify() في المثال مثبتان على 2026-09-20 — وتوجد في verify() أربعة توكيدات للتاريخ: Sun, Sep 20، و2026-09-20 (فك ترميز tfs)، وdeparting 2026-09-20، وSunday, September 20. حُدِّثت هذه الصفحة في 2026-11-04، وهذا التاريخ قد مضى؛ وسلوك Google Flights مع التواريخ الماضية لم يُذكر في مصادر المعلومات.@@I18N_KEEP_000035@@

الإجراء الصحيح: إن أردت فقط إعادة إنتاج طريقة التشغيل الرسمية، فنفّذه كما هو (ستُنفَّذ خطوات السكربت ومنطق التحقق كالمعتاد، ويعتمد النجاح على سلوك Google مع التواريخ الماضية)؛ أما إن أردت رؤية رحلات متاحة حقيقية، فغيّر التاريخ في GOALS إلى تاريخ مستقبلي، وعدّل بالتزامن سلاسل التواريخ الأربعة في verify() — لاحظ أن Sun, Sep 20 يتضمن اختصار يوم الأسبوع، فيجب أن يتوافق يوم الأسبوع للتاريخ الجديد مع الواقع (2026-09-20 يصادف يوم الأحد، ولهذا كُتب في النص الأصلي Sun).

❌ تشغيل السكربت بدون --env-file .env ​

الظاهرة: uv run python examples/flights.py يرمي KeyError: 'TYPESAFE_API_KEY' فور الإطلاق.

السبب: يقرأ demo.py عند الإطلاق ملف .env من الدليل الحالي بنفسه، أما flights.py فلا يملك هذا المنطق — متغيرات البيئة تُحقن كلها عبر uv run --env-file .env. ويستخدم model.py os.environ["TYPESAFE_API_KEY"] للحصول على القيمة مباشرة، فغيابها يعني KeyError.

الطريقة الصحيحة: استخدم الأمر حرفيًا كما ورد في README — uv run --env-file .env python examples/flights.py --keep-open، ونفّذه من الدليل الجذر للمستودع.

❌ التشكيك في «7 ثانية» اعتمادًا على الثواني التي قستها بنفسك ​

الظاهرة: حصلت على 8 ثوانٍ و9 ثوانٍ، بل أكثر من عشر ثوانٍ في inspector، فظننت أن الأرقام الرسمية مبالغ فيها.

السبب: ثلاثة اختلافات في المنهجية — ① التوقيت الرسمي يبدأ منأول تنبؤ (بعد مراقبة الصفحة الأولية) وينتهي عند قبول DONE؛ إطلاق المتصفح والتنقل الأولي والتحقق المستقل اللاحق ليست ضمن الحساب؛ ② Google والشبكة وذاكرة التخزين المؤقت كلها متغيرة، فعمليات النسخة المحسّنة الـ 3 في المقارنة الرسمية مع القياس الفعلي تتراوح بين 6.964–7.913 ثانية؛ ③ inspector يُفعّل لقطات الشاشة، فهو أصلًا ليس طريقة تشغيل للتوقيت.

الطريقة الصحيحة: قبل المقارنة وحّد المنهجية أولًا (طريقة تشغيل السكربت، نفس URL ونفس الهدف)؛ تجد التفصيل الكامل لحدود التوقيت في الدرس التالي قراءة الأداء.

نصائح متقدمة (اختيارية) ​

غيّر --output للاحتفاظ بجولات تشغيل متعددة. دليل الإخراج الافتراضي هو artifacts/flights/latest، والتشغيل المتكرر سيستبدل النتائج؛ أضف شيئًا مثل --output artifacts/flights/run2 لحفظ trace كل جولة على حدة لتسهيل المقارنة.

سجّل «الفيديو الرسمي» الخاص بك. يتضمن المستودع scripts/record_flights.py <新目录>، ووفقًا لتعليمات README يمكنك تسجيل تشغيل يحمل طوابع الوقت الأصلية للمتصفح. انتبه لتنبيه README: المثال المباشر وسكربت التسجيل كلاهما يُحدثاناستدعاءات API مدفوعة.

شاهد بالتوازي مع الفيديو الرسمي. الملف docs/demo.mp4 في المستودع هو تسجيل حقيقي لتشغيل الـ 7,073 ms (بسرعة ×1)؛ ورابط Watch the real Google Flights run أعلى صفحة inspector يشير إليه مباشرة (توجّهه خدمة demo على المسار /demo.mp4). تسميات العناصر في الفيديو أُضيفت لاحقًا عند التصيير ولا تُشغّل المتصفح.

عدّل الهدف لتجربة عمليات بحث أخرى. يدعم مربع المهمة في inspector أهدافًا مخصصة من 1–2000 حرفًا (قاعدة تحقق demo) — مثلًا غيّر التاريخ أو المسار الجوي. عبثت بالأهداف وتريد استعادة الافتراضي؟ بدّل قائمة السيناريوهات المنسدلة إلى خيار آخر ثم عُد إليها، وسيعاد ملء مربع الهدف بالنص الافتراضي تلقائيًا. ملاحظة: inspector لا يتحقق، فإذا غيّرت الهدف عليك مراجعة النتائج بنفسك؛ وللتحقق في السكربت عليك تعديل verify() معه.

خلاصة الدرس ​

✅ يمكن إعادة إنتاج تسجيل Jev Ultrafast Google Flights بطريقتين: عبر inspector مع تفعيل لقطات الشاشة والمشاهدة بالعين (إبطاء Choose next خطوة بخطوة، ومراقبة ترتيب الاحتمالات)؛ أو عبر flights.py دون لقطات، بالقياس بساعة الإيقاف + التحقق التلقائي.

✅ هدف بلغة طبيعية واحدة هو كل المدخلات — لا سكربتات للموقع ولا سلاسل حقول جاهزة؛ ?hl=en يثبّت الواجهة على الإنجليزية حتى تتطابق التسميات التي تتحقق منها verify().

✅ للـ 7.073 ثانية منهجيتها: تبدأ من أول تنبؤ وتنتهي عند قبول DONE؛ وتشمل استدعاءات النموذج وتوليد النص وعمليات المتصفح وقرارات stale وانتظار التحميل؛ ولا تشمل إطلاق المتصفح ولا التنقل الأولي ولا التحقق اللاحق.

✅ DONE وحدها لا تكفي: تنفّذ verify() على صفحة النتائج 7 فحوصات مستقلة (search_page / one_way / origin / destination / date / year / results)، وأي فشل يجعل السكربت يستدعي SystemExit مباشرة.

✅ المثال مثبّت على 2026-09-20: إذا أصبح التاريخ قديمًا فإما أن تقبل باحتمال كون results فارغة، وإما أن تعدّل الهدف مع سلاسل التواريخ الأربعة في verify().

مراجعة الأوامر والمعاملات الرئيسية:

الأمر/المعاملالقيمة الموصى بهاالشرح
uv run jevيُنفَّذ من الدليل الجذر للمستودعشغّل inspector واختر السيناريو Google Flights · real web
uv run --env-file .env python examples/flights.py --keep-openاستخدمه حرفيًالإعادة إنتاج التسجيل + تحقق تلقائي + حفظ trace، مع إبقاء المتصفح مفتوحًا
--env-file .envإحضاره إلزاميلا يقرأ flights.py ملف .env بنفسه، وغيابه يرمي KeyError
--keep-openيُنصح بإحضارهبدونه يُغلق المتصفح تلقائيًا بعد انتهاء التشغيل
--outputartifacts/flights/latest (افتراضي)تغيير الدليل يتيح الاحتفاظ بجولات تشغيل متعددة

استعراض الدرس التالي ​

بعد نجاح التشغيل، يفكك الدرس التالي قراءة الأداء: كيف قيست الـ 7.073 ثانية ساعة الإيقاف. ستتعلم:

  • التعريف الكامل لحدود التوقيت: من أول تنبؤ إلى قبول DONE، أي المراحل داخل الحساب وأيها خارجه
  • الفاتورة الكاملة لتسجيل واحد: 17 طلب Jev، ووسيط زمن الاستجابة 178 ms، و2 عمليتا توليد نص، والبحث نُفِّذ في الثانية 5.217
  • مقارنة رسمية مع القياس الفعلي: زمن المهمة 9.450 ← 7.092 ثانية، واستدعاءات البروتوكول 1,092 ← 101، ولماذا تقول الجهة الرسمية بنفسها إن هذا مجرد عينة صغيرة
  • منهجية التكلفة: 90,558 token إدخال، واستدعاءان لمساعد النص بتكلفة $0.00006272 (دون احتساب فوترة TypeSafe)

ملحق: مرجع الكود المصدري ​

انقر للتوسيع وعرض مواضع الكود المصدري

آخر تحديث: 2026-11-04 (المستودع github.com/browser-use/jev-ultrafast، مصدر المعلومات المحلي sources/jev/repo-ultrafast/)

الوظيفةمسار الملفالمواضع الرئيسية
الهدف النموذجي وURL البدايةexamples/flights.pyL11–15 URL (google.com/travel/flights?hl=en)، GOALS (مطابق للهدف المعبأ مسبقًا في static/index.html)
التحقق المستقل بـ 7 فحوصاتexamples/flights.pyL18–38 verify(): search_page / one_way / origin / destination / date / year (عبر فك ترميز tfs أو نص الصفحة، مساران) / results؛ L63–64 عند فشل التحقق SystemExit("Final page did not satisfy the route/date checks")
وسيطات سطر الأوامر وحفظ traceexamples/flights.pyL43 --output (الافتراضي artifacts/flights/latest)؛ L44 --keep-open؛ L54–59 يحفظ state.json / session.json
أمر التشغيل و«لا اختيار ولا حجز»README.md«Use the library»: uv run --env-file .env python examples/flights.py --keep-open … does not select or book a flight
7,073 ms معيار القياس الزمني وتحذير DONEREADME.md، docs/performance.mdREADME «Evidence and limits»: Timing starts after initial page observation…؛ A DONE choice still requires independent outcome verification؛ performance.md «Where the time went»: ينتهي التوقيت عند accepted DONE choice، وbrowser setup / initial navigation / post-run verification خارج الجدول
إحصاءات التشغيل الفعلي وبيانات المقارنةdocs/performance.md«Where the time went»: 17 طلب / 10 تفاعل + 1 WAIT / 2 استدعاء helper / وسيط 178 ms / 5.217 s / 7.073 s؛ «Matched runtime comparison»: 6.964 / 7.913 / 7.092
سيناريو inspector والهدف المُعبأ مسبقًاjev_ultrafast/demo.pyL44–62 command(): scenario flights → Google Flights URL؛ goal 1–2000 حرفًا؛ screenshots=True؛ L88–91 /demo.mp4 مسار
عناصر اللوحة ونصوص الحالةjev_ultrafast/static/index.html + app.jsindex.html L33–37 قائمة السيناريو المنسدلة، L40–44 الهدف المُعبأ مسبقًا وزر Start demo، L52–59 Slow motion / Choose next / Execute choice / Run automatically، L123–126 Decision trail وExport trace، L132–136 What the model sees؛ app.js L82–88 نصوص الحالة (Jev reports complete · inspect the page)، L160–168 Choose→predict / Execute→act، L173–186 Slow motion يتوقف 450 ms عند كل خطوة، L217–235 تصدير typesafe-browser-trace.json
حلقة القرار والحالةjev_ultrafast/agent.pyL163–165 run()؛ status ∈ ready/predicted/done/blocked؛ L102–104 MAX_STEPS=60 ميزانية الإجراءات؛ L153–157 3 إجراءات غير صالحة متتالية تؤدي إلى blocked
نص تعليمات النموذج الأصليjev_ultrafast/questions.pyNEXT_ACTION (حقل CLICK لمنتقي التاريخ/التاريخ/التأكيد، اقتراحات الإكمال التلقائي، يتطلب DONE دليلًا مرئيًا، شرط WAIT، النقر على Search فورًا)؛ MAX_STEPS = 60
طريقة قراءة المفتاحjev_ultrafast/model.pyL119 os.environ["TYPESAFE_API_KEY"] (يؤدي غيابه إلى رفع KeyError)؛ L160–168 فحص field_text() لـ TEXT_MODEL_API_KEY
قيود مخرجات helper النصيjev_ultrafast/model.pyL187–193 يجب أن يكون الناتج مفتاحًا واحدًا {"text": …} وغير فارغ و≤2000 حرفًا، وإلا لا يتم الكتابة
trace لا يدخل إلى git.gitignore.env و.venv/ وartifacts/ كلها مُتجاهَلة
سكربت التسجيلscripts/record_flights.pyREADME «Development»: captures original browser timestamps؛ مثال live وسكربت التسجيل يُنتجان استدعاءات API مدفوعة
gaodong.aiAboutPrivacyContact

Independent tutorials, not affiliated with any product mentioned. Product names and trademarks belong to their owners. Check official pages for prices and policies.