تشغيل 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 عنصر |
| لوحة trace | Export 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):
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 way | one_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 — فهو يتيح الإيقاف خطوة بخطوة ومشاهدة احتمالات كل مرشح، فتعرف عند حدوث مشكلة أين علِقت.
ابدأ من جذر المستودع (بالبيئة المثبتة في الدرس السابق):
cd jev-ultrafast
uv run jevينبغي أن ترى: يطبع الطرفية Jev Ultrafast: http://127.0.0.1:8766. يفتح المتصفح هذا العنوان، ومربع المهام معبأ مسبقًا بهدف Zurich → London من الخطوة 1.
ثم:
- تأكد أن قائمة السيناريو المنسدلة هي
Google Flights · real web(وهذا هو الافتراضي؛ السيناريوهان الآخران· fixtureصفحات محلية لا تخرج إلى الإنترنت) - انقر Start demo، واسمح عند الطلب بالتصحيح عن بُعد في Chrome (ستعرض حالة الواجهة Opening a fresh browser…)
- انقر على 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.jsonDecision 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 على القرص.
في الدليل الجذري للمستودع:
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.pyos.environ["TYPESAFE_API_KEY"]للوصول المباشر إلى القيمة)--keep-open: لا يستدعيagent.close()بعد الانتهاء، وتبقى صفحة النتائج في Chrome ليتسنى لك التحقق منها بعينيك
يفترض أن ترى: يطبع الطرفية التقدم بالتمرير أولًا، ثلاثة حقول في كل سطر — الملّي ثواني التراكمية، والحالة، والإجراء المنفَّذ للتو (تسمية الإجراء مأخوذة من عناصر الصفحة وتختلف كل جولة):
<ملّي ثانية> ready <تسمية الإجراء المنفَّذ للتو>
<ملّي ثانية> ready <تسمية الإجراء المنفَّذ للتو>
……
<ملّي ثانية> done <تسمية آخر إجراء منفَّذ>(توضيحي؛ أرقام الملّي ثانية والإجراءات تعتمد على جولتك الحالية، وحالة السطر الأخير هي done)
ثم تُطبع نتيجة التحقق بصيغة JSON (البنية من flights.py، ومحتوى visible_flights يعتمد على الرحلات المتاحة في ذلك اليوم):
{
"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، يخرج السكربت برمز غير صفري، وآخر سطر هو:
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_way | Change ticket type. One way قيمة الحقل == One way | تم تطبيق إعداد الاتجاه الواحد |
origin | Where from? قيمة الحقل == Zürich | تم اختيار الاقتراح الصحيح لمدينة الانطلاق |
destination | Where to? قيمة الحقل == London | تم اختيار الاقتراح الصحيح لمدينة الوصول |
date | Departure قيمة الحقل == 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 | يُنصح بإحضاره | بدونه يُغلق المتصفح تلقائيًا بعد انتهاء التشغيل |
--output | artifacts/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.py | L11–15 URL (google.com/travel/flights?hl=en)، GOALS (مطابق للهدف المعبأ مسبقًا في static/index.html) |
| التحقق المستقل بـ 7 فحوصات | examples/flights.py | L18–38 verify(): search_page / one_way / origin / destination / date / year (عبر فك ترميز tfs أو نص الصفحة، مساران) / results؛ L63–64 عند فشل التحقق SystemExit("Final page did not satisfy the route/date checks") |
| وسيطات سطر الأوامر وحفظ trace | examples/flights.py | L43 --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 معيار القياس الزمني وتحذير DONE | README.md، docs/performance.md | README «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.py | L44–62 command(): scenario flights → Google Flights URL؛ goal 1–2000 حرفًا؛ screenshots=True؛ L88–91 /demo.mp4 مسار |
| عناصر اللوحة ونصوص الحالة | jev_ultrafast/static/index.html + app.js | index.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.py | L163–165 run()؛ status ∈ ready/predicted/done/blocked؛ L102–104 MAX_STEPS=60 ميزانية الإجراءات؛ L153–157 3 إجراءات غير صالحة متتالية تؤدي إلى blocked |
| نص تعليمات النموذج الأصلي | jev_ultrafast/questions.py | NEXT_ACTION (حقل CLICK لمنتقي التاريخ/التاريخ/التأكيد، اقتراحات الإكمال التلقائي، يتطلب DONE دليلًا مرئيًا، شرط WAIT، النقر على Search فورًا)؛ MAX_STEPS = 60 |
| طريقة قراءة المفتاح | jev_ultrafast/model.py | L119 os.environ["TYPESAFE_API_KEY"] (يؤدي غيابه إلى رفع KeyError)؛ L160–168 فحص field_text() لـ TEXT_MODEL_API_KEY |
| قيود مخرجات helper النصي | jev_ultrafast/model.py | L187–193 يجب أن يكون الناتج مفتاحًا واحدًا {"text": …} وغير فارغ و≤2000 حرفًا، وإلا لا يتم الكتابة |
| trace لا يدخل إلى git | .gitignore | .env و.venv/ وartifacts/ كلها مُتجاهَلة |
| سكربت التسجيل | scripts/record_flights.py | README «Development»: captures original browser timestamps؛ مثال live وسكربت التسجيل يُنتجان استدعاءات API مدفوعة |