Skip to content

اكتب مهام متصفحك الخاصة: تطبيق عملي لمكتبة Agent ​

في الدروس الأربعة الأولى كنت تستخدم Ultrafast: تشاهد القرارات في inspector، وتعيد إنتاج التسجيلات عبر flights.py، وتفكك ساعة الإيقاف في درس الأداء. هذا الدرس هو نقطة التحول في Jev Ultrafast تعليمي من التشغيل كما هو إلى الكتابة بنفسك — تحويل Ultrafast من عرض توضيحي إلى مكتبة داخل كودك: from jev_ultrafast import Agent، تعطيه URL وهدفًا واحدًا، فيعيد إليك حالة كل خطوة.

التعريف الرسمي لهذا الاستخدام جملة واحدة: نفس مجموعة السياسات، غيّر URL وهدفًا واحدًا، فتحصل على مهمة جديدة (README: The same policy can run a different task). في هذا الدرس ستكتب my_task.py الخاص بك، وتستخدم run.py المرفق بالمستودع لتشغيل أي صفحة ويب دون كود، وتفهم كل حقل في state، وتضيف تحققًا مستقلًا لمهمتك على نمط flights.py.

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

  • اكتب سكربت مهمة أتمتة متصفح خاصًا بك باستخدام from jev_ultrafast import Agent، وشغّله من جذر المستودع بـ uv run --env-file .env python my_task.py
  • اذكر ما يتحكم به كل معامل في Agent(url, goals, *, record_dir=None, screenshots=False)، والفرق بين تمرير goals كسلسلة نصية أو كقائمة
  • شغّل أي مهمة على أي صفحة ويب دون كتابة سطر كود واحد باستخدام examples/run.py --url … --goal …، مع إمكانية تكرار --goal لتكوين قائمة أهداف مرتبة
  • افهم state الذي يعيده run() خطوة بخطوة: كيفية استخدام كل حقل من history وdecisions وtext_calls وstatus وelapsed_ms
  • اعرف ميزانية 60 إجراءً / 120 استدعاء نموذج، وشروط تفعيل blocked، ولماذا يجب أن تكتب تحققك الخاص حتى بعد DONE

مأزقك الحالي ​

  • inspector لا يشغّل إلا السيناريوهات المسبقة، وتعديل جملتين في مربع المهمة ممكن، لكنك لا تعرف من أين تبدأ إذا أردت ربط الوكيل بسكربتك الخاص — تحقق تلقائي بعد الانتهاء، وحفظ trace، وتنبيه عند الفشل
  • تريد أن يبحث المتصفح لك تلقائيًا كل يوم عن شيء أو يملأ نموذجًا، لكن مجرد التفكير في كتابة المحددات وانتظار التحميل والتعامل مع مختلف عناصر التحكم يجعلك تتراجع
  • تفتح agent.py لتقتبس منه، فتجد حلقات وقرارات وحالة مليئة بالحقول، ولا تفرّق بين ما هو لك وما هو تنفيذ داخلي

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

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

  • ربط Ultrafast بكودك الخاص: الحصول على النتائج بعد الانتهاء، وحفظ trace، والتحقق التلقائي، والتنبيه عند الفشل
  • تشغيل مهام مختلفة على مواقع مختلفة بنفس وكيل المتصفح المخصص، دون كتابة سكربت محددات يدويًا لكل موقع
  • الحصول على بيانات كل خطوة تدريجيًا (الإجراء، والاحتمال، والتأخير، واستدعاءات النص) لأغراض التصحيح أو الإحصاء

ولا تريد:

  • أن تُقيَّد بالسيناريوهات المسبقة في inspector تنقر الأزرار
  • أن تحافظ على محددات DOM لكل موقع، فتفشل جماعيًا بمجرد تغيير تصميم الصفحة
  • أن تعلن نجاح المهمة لمجرد أن النموذج قال DONE

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

  • أكملت تثبيت Ultrafast وتشغيله: تم تثبيت التبعيات عبر uv sync، و.env مُعبأ بـ TYPESAFE_API_KEY بالفعل (المهام التي تتطلب الكتابة تحتاج أيضًا إلى TEXT_MODEL_API_KEY، يُفصَّل في الخطوة 6)
  • (موصى به) شغّلت مرة تطبيق Google Flights العملي ورأيت كيف يبدو verify() التحقق المستقل
  • الشبكة تستطيع الوصول إلى api.typesafe.ai والموقع الهدف الذي ستتعامل معه
  • فكّرت في مهمة ويب يمكن إنجازها ضمن 5 خطوات (ابدأ صغيرًا ثم كبّر؛ ميزانية 60 خطوة تُشرح في الخطوة 4)
  • تعرف كتابة سكربتات Python واستخدمت with — هذا كل ما تحتاجه اليوم

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

نصحّح أولًا وهمًا سهل الوقوع: Ultrafast ليس عرضًا توضيحيًا مع قليل من الكود، بل هو حزمة Python قابلة للاستيراد. للمدخل في الحزمة اسمان فقط (__all__ في __init__.py): Agent وBrowser — وفي الاستخدام اليومي تحتاج فقط إلى Agent.

النموذج الذهني في جملة: أنت تقدم URL والهدف، وAgent يقوم بالحلقة، وأنت تستهلك state.

ما تقدمهما يفعله Agentما تحصل عليه
url: صفحة البدايةيفتح علامة تبويب في الخلفية، والملاحظة الأولىrun() state يُعاد خطوة بخطوة
goals: هدف واحد (أو قائمة)الحلقة: ملاحظة ← طلب TypeSafe واحد بقرارين ← تنفيذhistory / decisions / text_calls لكل خطوة
(اختياري) record_dirمعالجة stale، والتحكم في الميزانية، وتحديد الحالة blockedالحالة النهائية status:‏ done أو blocked

ثلاثة مفاهيم رئيسية:

**1. نفس السياسة، مع تغيير URL والهدف تصبح مهمة جديدة. ** لا توجد في السياسة نصوص برمجية للمواقع ولا سلاسل حقول جاهزة (كما ورد النص الأصلي في الدرس الدرس رقم 3)، لذا فإن «المهمة المخصصة» لا تعني «كتابة سكربت أتمتة» — أنت لا تكتب محددات (selectors)، بل تكتب الهدف فقط.

**2. الـ state هو كل شيء لديك. ** ما يستطيع كودك فعله يعتمد على ما يوجد في الـ state الذي يعيده لك run(). الفاتورة التي فككناها في الدرس السابق (عدد الطلبات 17، وزمن الاستجابة الوسيط 178 ms، وعدد مرات توليد النص 2) كلها تأتي من هذه الحقول — وهذا الدرس يعلّمك قراءتها مباشرة.

**3. الحلقة تأتي مع ضمانات مدمجة. ** إذا تغيّرت الصفحة بعد اتخاذ القرار (stale)، تتخلص الحلقة من القرار وتلاحظ من جديد وتعيد الجولة؛ القرار يُستهلك مرة واحدة فقط، فإعادة المحاولة لا تنقر مرتين؛ وقيم النص المولّدة لا تُعاد إلا إذا بقي الإدخال دون تغيير تمامًا. كل هذا لا تحتاج إلى كتابته بنفسك.

مقارنة بين ثلاث طرق للتشغيل، وهي أيضًا خريطة طريق هذا الدرس:

المفتش inspector (uv run jev)examples/run.pyسكربتك الخاص
كتابة الكودبدونبدونواحد my_task.py
مصدر المهمةسيناريو جاهز + مربع مهمة--url / --goal معاملاتتحددها أنت في الكود
ما تحصل عليهتشاهد اللوحة بعينكتقدم في الطرفية + الـ URL النهائيالـ state كاملًا، عالجه كما تشاء
التحقق التلقائيلالاتكتبه بنفسك (الخطوة 5)
مناسب لـفهم القراراتتجربة مهمة واحدة بسرعةالدمج في نظامك الخاص

💡 هل تريد تغيير سلوك الـ agent؟

الدرس النظري قال: المهام المخصصة تمر عبر الواجهة القياسية لمكتبة Agent، لا عبر حشو المنطق داخل السياسة. كلما كان الهدف مكتوبًا بتفصيل أدق، سار الـ agent بثبات أكبر — هذه الجملة الهدف هي «واجهة البرمجة» الخاصة بك.

اتبع معي ​

الخطوة 1: التعرف على jev_ultrafast Agent — المدخل الوحيد للمهام المخصصة ​

لماذا: قبل كتابة السكربت، اعرف أولًا أي المقابض تركها لك هذه الفئة — أربعة معاملات في المجموع، ستتعرف عليها كلها خلال دقيقتين.

التوقيع (من agent.py):

python
Agent(url, goals, *, record_dir=None, screenshots=False)
المعاملالنوعالوصف
urlstrصفحة البداية. عند الإنشاء يُفتح تلقائيًا تبويب خلفي (منفذ عرض 1120×780) وتُنتظر اكتمال تحميل الصفحة (بحد أقصى 15 ثانية)
goalsstr أو قائمةجملة هدف واحدة؛ إذا مرّرت قائمة تُدمج بالترتيب بفواصل أسطر في نص مهمة واحد. الهدف الفارغ يرمي مباشرة ValueError: Supply a task
record_dirمسار (اختياري)مجلد التسجيل: عند ضبطه تُحفظ تلقائيًا صورة jpg في كل خطوة (الشاشة الأولى هي 000000.jpg، وبعدها التسمية حسب المللي ثانية التراكمية)
screenshotsbool (اختياري)هل تُلتقط لقطات شاشة أثناء الملاحظة، الافتراضي False — الحلقة الافتراضية لا تلتقط لقطات (كما يذكر README صراحةً)؛ عند ضبط record_dir يُفعَّل تلقائيًا معه

ثلاث نقاط استخدام رئيسية:

  • استخدم with: الـ Agent هو مدير سياق (context manager)، عند انتهاء كتلة with يُغلق التبويب تلقائيًا؛ وحتى عند فشل الإنشاء (مثلًا تعذر فتح الصفحة) يُغلق المتصفح أولًا ثم يُرمى الخطأ
  • الإنشاء يعني الملاحظة: بمجرد تنفيذ Agent(...) يكون المتصفح قد فُتح وأُنجزت الملاحظة الأولى، ولا ينتظر حتى تستدعي run() لتبدأ
  • للاستخدام مرة واحدة: بعد الوصول إلى done أو blocked ينتهي هذا الـ Agent، ولا يمكن متابعة تشغيله (تنبيه المصيدة رقم 4)

يفترض أن ترى: في المجلد الجذر للمستودع تحقق من نقطة الدخول (uv sync أدرج الحزمة في البيئة بالفعل):

bash
uv run python -c "from jev_ultrafast import Agent; print(Agent)"
text
<class 'jev_ultrafast.agent.Agent'>
  • تستطيع ذكر اثنين من المعاملات الأربعة سنستخدمهما اليوم: url و goals

الخطوة 2: اكتب أول سكربت مهمة متصفح مخصصة لك ​

لماذا: قسم «Use the library» في README يبدأ ببضعة أسطر هيكلية (ما يُملأ في الهيكل الرسمي هو هدف Flights من الدرس 3)، ثم يقول مباشرة The same policy can run a different task، ويعطي مثالًا لسطر أوامر ويكيبيديا — اكتب أولًا المثال الرسمي كسكربت وشغّله بنجاح، ثم استبدل الـ URL والهدف بما تريد.

أنشئ في المجلد الجذر للمستودع my_task.py (بنفس مستوى examples/؛ يوضع في المجلد الجذر لأن uv run يجب تنفيذه من المجلد الجذر للمستودع):

python
from jev_ultrafast import Agent

URL = "https://en.wikipedia.org/wiki/Main_Page"
GOAL = "Find and open the Wikipedia article about Gödel’s incompleteness theorems."

with Agent(URL, GOAL) as agent:
    for state in agent.run():
        print(state["elapsed_ms"], state["status"])
print(state["page"]["url"])

هذا هو مثال ويكيبيديا من README الرسمي معاد كتابته كسكربت (الجملة الهدف نفسها هي التي تعمل في run.py، انظر الخطوة التالية). التشغيل:

bash
uv run --env-file .env python my_task.py

ملاحظة: هذه المهمة تتطلب الكتابة في مربع البحث، لذا يجب أن يحتوي .env أيضًا على قيمة لـ TEXT_MODEL_API_KEY (تُفصَّل الإعدادات في الخطوة 6).

يفترض أن ترى: يفتح Chrome تبويبًا خلفيًا إضافيًا على الصفحة الرئيسية لويكيبيديا، وتطبع الطرفية سطرًا بسطر «المللي ثانية التراكمية + الحالة»، ومعظم الأسطر ready، وآخر سطر حالته done (إذا حصلت blocked، ابحث عن السبب في الخطوة 4 الخاصة بالميزانية وتحديد الأفعال غير المجدية، أو راجع الدرس التالي لاستكشاف الأخطاء)، ثم يُطبع الـ URL النهائي الذي توقف عنده المتصفح — في اختبار الدخان الرسمي، فتحت نفس السياسة هذا المقال في 2.798 ثانية (قسم Other checks في performance.md):

text
<المللي ثانية> ready
<المللي ثانية> ready
……
<المللي ثانية> done
<الـ URL النهائي — صفحة مقال مبرهنة عدم الاكتمال لغودل>

(الأرقام بالمللي ثانية والترميز الدقيق للـ URL تعتمد على تشغيلك هذا)

  • اكتمل تشغيل my_task.py، والـ URL المطبوع في السطر الأخير هو صفحة مقال مبرهنة عدم الاكتمال لغودل

الخطوة 3: تشغيل أي مهمة دون كتابة كود باستخدام examples/run.py ​

لماذا: إذا أردت تجربة مهمة على عجل، لا تحتاج حتى إلى إنشاء ملف — الـ runner العام المرفق بالمستودع يحوّل الـ URL والهدف كليهما إلى معاملات سطر أوامر.

الأمر الأصلي في README (حرفيًا):

bash
uv run --env-file .env python examples/run.py \
  --url https://en.wikipedia.org/wiki/Main_Page \
  --goal 'Find and open the Wikipedia article about Gödel’s incompleteness theorems.'

المعاملان (من شيفرة run.py المصدرية):

المعاملالوصف
--urlإلزامي، صفحة البداية
--goalمطلوب، ويمكن تمريره بشكل متكرر (وهو action="append" الخاص بـ argparse)، وتُشكّل بالترتيب قائمة أهداف مرتبة

حلقة run.py تقتصر على أمرين: في كل خطوة تطبع «المللي ثانية بمحاذاة يمين + عدد الإجراءات المنفذة + الحالة»، وعند الانتهاء تطبع عنوان URL الحالي للمتصفح:

text
<المللي ثانية> ms <عدد الإجراءات> actions <الحالة>
……
<عنوان URL النهائي>

يجب أن ترى: نفس المهمة ونفس النتيجة كما في الخطوة 2 — وهذا هو الحد الأدنى من الإثبات على أن «نفس السياسة، مع تغيير عنوان URL والهدف تصبح مهمة جديدة». يمكنك استخدام أي موقع: استبدل --url بصفحة البحث أو موقع التوثيق الذي تستخدمه عادةً، واكتب في --goal هدفًا محددًا بجملة واحدة (لمعرفة كيفية كتابة هدف جيد، راجع تنبيه المزالق رقم 2).

💡 ماذا يحدث إذا تم تمرير الهدف عدة مرات؟

عند تمرير --goal عدة مرات، سيقوم الـ Agent بدمج الأهداف المتعددة بالترتيب باستخدام فواصل الأسطر في نص مهمة واحد (السطر 14 من agent.py) — يتم تقييمها كمهمة واحدة متكاملة، وليس تنفيذ هدف واحد ثم الانتقال تلقائيًا إلى التالي.

  • شغّل run.py مرة واحدة باستخدام --url و --goal الخاصة بك، ويكون عنوان URL في السطر الأخير مطابقًا للتوقعات

الخطوة 4: افهم الـ state الذي يُخرجه run() — لوحة معلومات المهام المخصصة ​

لماذا: حساب فاتورة الدرس السابق اعتمد على هذه الحقول بالضبط؛ والحكم على مهامك الخاصة بشأن «إلى أين وصل التنفيذ، وكم كلّف، وماذا فعل» يقع هنا أيضًا بالكامل. run() هو مولّد (generator)، وفي كل خطوة تنفيذ يُخرج (yield) لقطة من الـ state — وحتى خطوة done / blocked يتم إخراجها قبل الانتهاء.

الحقول الرئيسية للـ state (من self.state و snapshot() في agent.py):

الحقلالمحتوىما الذي يمكنك فعله به
statusready / predicted / done / blockedتحديد نهاية الحلقة؛ عند blocked ابحث عن السبب في history
elapsed_msالمللي ثانية المتراكمة منذ أول تنبؤالتوقيت وإحصاءات الأداء
historyقائمة الإجراءات المنفذةيحتوي كل عنصر على action (وسم العنصر) و kind و choice و probability و confidence و latency_ms و text و operation و target و page_changed و url و usage و executed_ms وغيرها
decisionsسجل لكل تنبؤ (يشمل fingerprint و elapsed_ms و request و raw_answers)مراجعة ما رآه النموذج وما اختاره في كل جولة
text_callsسجل استدعاءات الـ helper النصية (model و latency_ms و usage و field و value)إحصاء عدد استدعاءات الـ LLM الصغير وزمن الاستجابة والقيم المولّدة
pageآخر ملاحظة للصفحة: url و title و text و actions و fingerprintالتحقق في الخطوة 5 يقرأ منها
goalنص المهمة بعد الدمجالتحقق من الأهداف التي استلمها الـ agent
elementsجدول العناصر المرقّمة الحالي (يُضاف بواسطة snapshot())رؤية الصفحة كما يراها الـ agent

(توجد أيضًا حقول داخلية أخرى مثل plan / plan_index / decision / started_at / record؛ وكائن browser لا يظهر في اللقطة.)

تذكّر ميزانيتين وفرملة تلقائية واحدة (كلها من agent.py، MAX_STEPS = 60):

  • ميزانية الأفعال: 60 فعلًا منفذًا، عند التجاوز تُضبط الحالة إلى blocked ويُرمى ValueError: Stopped at the 60-action demo budget
  • ميزانية استدعاءات النموذج: 120 تنبؤًا (MAX_STEPS * 2)، وعند التجاوز يُرفع ValueError: Reached the demo's model-call budget
  • إجراءات غير صالحة متتالية: آخر 3 إجراءات لم يحدث فيها أي تغيير في الصفحة ولم يكن أي منها من نوع wait، فتُضبط الحالة تلقائيًا على blocked

أضف إلى الحلقة طباعة عملية (نفس نمط flights.py):

python
with Agent(URL, GOAL) as agent:
    for state in agent.run():
        last = state["history"][-1] if state["history"] else {}
        print(state["elapsed_ms"], state["status"], last.get("action", ""))

يجب أن ترى: سطرًا إضافيًا في كل سطر يوضح «وسم العنصر الذي نُفذ للتو» (مثل مربع البحث، أو أحد الاقتراحات، أو رابط معين)، وهو أكثر وضوحًا بكثير من مجرد النظر إلى الحالة — هذه هي نسخة البيانات من Decision trail في الـ inspector.

  • أن تتمكن من ذكر معنى 3 حقول على الأقل من history
  • أن تعرف الحد الأقصى لعدد الخطوات التي يمكن أن تقطعها مهمتك (60 إجراءً / 120 استدعاءً للنموذج)

الخطوة 5: أضف تحققًا مستقلًا لمهمة المتصفح الخاصة بك — القاعدة الصارمة لدرس Jev Ultrafast ​

لماذا: يقول قسم Evidence and limits في README بوضوح: A DONE choice still requires independent outcome verification. الأمثلة الرسمية لديها verify() للمساعدة، أما مهمتك الخاصة فلا — وهذه الخطوة لا يمكن تخطيها. التحقق يقرأصفحة النتائج، ولا يقرأ إجابة النموذج.

النموذج المرجعي هو verify() الخاص بـ flights.py الذي فككناه في الدرس 3: يستخدم page["url"] وقيم الحقول ونص الصفحة لإجراء 7 فحوصات، وإذا فشل أي منها يخرج بـ SystemExit برمز غير صفري. جهّز لمهمة Wikipedia نسخة مماثلة:

python
def verify(page):
    """独立检查结果页面,不读模型的 DONE 回答。"""
    ok_url = page["url"].startswith("https://en.wikipedia.org/wiki/")
    ok_title = "incompleteness theorems" in page["title"].lower()
    return {"passed": ok_url and ok_title, "url": page["url"], "title": page["title"]}

اربطه بالسكربت (تحقق فوري بعد الانتهاء، وعند الفشل خروج برمز غير صفري — نفس خاتمة flights.py):

python
with Agent(URL, GOAL) as agent:
    for state in agent.run():
        pass  # 想看进度,照第 4 步打印

    result = verify(state["page"])
    print(result)

if not result["passed"]:
    raise SystemExit("Final page did not satisfy the checks")

تعتمد طريقة كتابة التأكيدات (assertions) على مهمتك، وكل الطرق الثلاثة صالحة:

كائن التحققمن الـ stateمثال
الوصول إلى الصفحة الصحيحةpage["url"]تأكيد على بادئة / مسار URL (يستخدم search_page في flights.py للتحقق من hostname والمسار)
صحة محتوى الصفحةpage["title"] و page["text"]احتواء العنوان أو النص الأساسي على المحتوى المتوقع
التحقق من قيمة عنصر تحكمpage["actions"]التحقق بالاعتماد على تسمية العنصر (في flights.py يقرأ origin قيمة Where from?)

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

  • مهمتك الخاصة أصبحت مزودة بـ verify، وهي تقرأ state["page"] وليس إجابة النموذج

الخطوة 6: المهمة تتطلب الكتابة؟ اضبط مساعد النص على DeepSeek أو GLM ​

لماذا: طالما أن المهمة تحتوي على حقل إدخال (البحث في الخطوة 2 هو مثال)، فإن سلسلة عملية TYPE_TEXT يولّدها نموذج LLM صغير متوافق مع OpenAI — التهيئة النموذجية تستخدم Mercury من OpenRouter؛ ويوضح README صراحةً أن Gemini وGLM وDeepSeek يمكنها جميعًا استخدام هذا المساعد. الطريقة الكاملة لكتابة .env مشروحة بالكامل في الأساليب A/B/C ضمن الدرس 2، ونحن هنا نضيف فقط ثلاث حقائق من منظور المهام.

الحقيقة الأولى: غياب المفتاح لا يسبب خطأً عند الإقلاع، بل عند الكتابة. TEXT_MODEL_API_KEY لا يُفحص إلا عندما تكون العملية TYPE_TEXT، ونص الخطأ الأصلي:

text
ValueError: TYPE_TEXT needs TEXT_MODEL_API_KEY; no text is hardcoded or guessed by the executor.

الحقيقة الثانية: القيمة الافتراضية في الكود عند عدم التهيئة هي DeepSeek. إذا لم يُضبط TEXT_MODEL_BASE_URL / TEXT_MODEL، فالقيمة الافتراضية هي https://api.deepseek.com/v1 + deepseek-chat (السطران 164–165 في model.py) — لذا فإن أسهل طريقة «للتحويل إلى DeepSeek» هي تعبئة سطر واحد فقط في .env:

bash
TEXT_MODEL_API_KEY=<你的 DeepSeek Key>

(إذا نسخت من .env.example، فيجب حذف سطري TEXT_MODEL_BASE_URL وTEXT_MODEL — ترك سلسلة فارغة يُحتسب أيضًا على أنه مضبوط ولن يعود إلى القيمة الافتراضية. أما عند التبديل إلى GLM أو غيره من نقاط النهاية المتوافقة مع OpenAI فيجب تهيئة اسم النموذج ونقطة النهاية وإعداد reasoning المناسبة، ونص README الأصلي: configure the appropriate model, endpoint, and reasoning setting.)

الحقيقة الثالثة: مخرجات المساعد تُتحقق منها بصرامة، ولا تُكتب إن لم تكن مطابقة. يجب أن يُعيد كائن JSON بمفتاح واحد فقط {"text": "…"}: سلسلة غير فارغة لا تتجاوز 2000 حرفًا؛ وعند غياب القيمة يُعيد {"text": null} بحسب التعليمات — وnull كذلك لا يُكتب، ويُرمى الاستثناء:

text
ValueError: Text helper returned no valid field value; nothing typed.

يجب أن ترى: بعد ضبط المفتاح أعد تشغيل الخطوة 2، فيظهر في مربع البحث مصطلح استرجاع ولّده النموذج ويُختار الاقتراح — ويمكنك في state["text_calls"] رؤية اسم النموذج المستدعى هذه المرة وزمن الاستجابة والقيمة المولّدة.

  • .env يحتوي TEXT_MODEL_API_KEY على قيمة (اختر واحدًا من DeepSeek / OpenRouter / GLM)

نقاط التحقق ✅ ​

  • my_task.py يعمل في جذر المستودع عبر uv run --env-file .env python my_task.py، وتطبع الطرفية المللي ثانية والحالة سطرًا بسطر
  • تستطيع ذكر الغرض من المعاملات الأربعة لـ Agent(url, goals, *, record_dir=None, screenshots=False)
  • examples/run.py يعمل حتى النهاية بـ --url و--goal خاصين بك، وعنوان URL النهائي مطابق للتوقعات
  • تستطيع ذكر ما هي history / decisions / text_calls / status / elapsed_ms داخل state
  • مهمتك الخاصة مزودة بتحقق مستقل، ولا تُعد ناجحة إلا إذا كان passed يساوي true؛ وتعرف ميزانية 60 عملية / 120 استدعاء نموذج

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

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

الظاهرة: uv run python my_task.py يرمي KeyError: 'TYPESAFE_API_KEY' فور الإقلاع.

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

الطريقة الصحيحة: أدرج --env-file .env حرفيًا في الأمر، ونفّذه من جذر المستودع (يوجد تحليل كامل في تنبيهات المزالق ضمن الدرس 3).

❌ الهدف مكتوب بشكل عام جدًا، فيعلن الوكيل DONE قبل الأوان ​

الظاهرة: الحالة وصلت إلى done، لكن الصفحة ليست ما تريده — مثلًا فتح رابط «يبدو ذا صلة» في الصفحة الرئيسية فقط.

السبب: تعليمات النموذج تشترط لـ DONE «دليلًا مرئيًا على استيفاء جميع المتطلبات» (DONE requires visible evidence that ALL requirements are satisfied)، لكن أساس الحكم هو جملة هدفك فقط. إذا لم يحدد الهدف معايير الإنجاز بوضوح، أنهى الوكيل المهمة بحسب فهمه الخاص.

الطريقة الصحيحة: اكتب معايير الإنجاز داخل الهدف — هدف flights هو النموذج المثالي: Stop when matching flight options are visible. Do not select or book a flight. (توقف عند ظهور نتائج مطابقة؛ لا تختر رحلة ولا تحجزها). الهدف الجيد = المهمة + شرط التوقف + الحدود. ثم عزّز ذلك بالتحقق المستقل في الخطوة 5.

❌ المهمة كبيرة جدًا، فيُرمى خطأ الميزانية أثناء التشغيل ​

الظاهرة: الطرفية ترمي ValueError: Stopped at the 60-action demo budget (أو Reached the demo's model-call budget)، وتصبح الحالة blocked.

السبب: للوكيل ميزانيتان صارمتان: 60 عملية منفّذة و120 استدعاء نموذج (MAX_STEPS * 2)؛ كما أن عدم تغيّر الصفحة خلال آخر 3 عمليات يجعل الحالة blocked تلقائيًا. إذا كانت خطوات المهمة كثيرة، أو تأخرت الصفحة في إعطاء تغذية راجعة، فستصطدم بالحد.

الطريقة الصحيحة: جزّئ المهام الكبيرة — هدف واحد لكل تشغيل Agent «يُنجز ضمن 5 خطوات». وإذا احتجت فعلًا إلى خطوات أكثر، فسلسل عدة Agent (واحد لكل كتلة with، حيث يأخذ url للتابع من state["page"]["url"] للسابق)، أو وجّه عنوان URL الابتدائي مباشرة إلى صفحة وسيطة.

❌ الاستمرار في استخدام وكيل أنهى تشغيله ​

الظاهرة: بعد انتهاء الحلقة تحاول استدعاء agent.run() مرة أخرى، أو تكليف الوكيل نفسه بهدف آخر، فيُرمى ValueError: This run has stopped. Start a fresh demo..

السبب: بعد أن تصبح الحالة done أو blocked، يُغلق مدخل التنبؤ للوكيل (السطران 73–74 في agent.py) — كل إنشاء يعني مهمة واحدة.

الطريقة الصحيحة: افتح with Agent(...) جديدًا لكل مهمة جديدة؛ وللمهام المتتالية اكتبها كحلقة، وكيل واحد في كل دورة. تُغلق علامة التبويب تلقائيًا مع نهاية كتلة with، فلا تتراكم.

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

سجّل مرة وشاهدها. Agent(URL, GOAL, record_dir="artifacts/mytask") يحفظ كل خطوة كصورة jpg (الشاشة الأولى 000000.jpg، ثم التسمية بأرقام ستة من المللي الثانية التراكمي) — بعد التشغيل تصفّح الصور بسرعة في عارض الصور، فهذا أوضح من قراءة trace. إذا ضبطت record_dir فتُفعّل اللقطات تلقائيًا دون حاجة لتمرير screenshots=True.

احفظ trace للتحليل. اتبع نمط الختام في flights.py لحفظ اللقطات على القرص:

python
import json
from pathlib import Path

# with 块内、run() 结束后:
state = agent.snapshot()
folder = Path("artifacts/mytask")
folder.mkdir(parents=True, exist_ok=True)
(folder / "state.json").write_text(json.dumps(state, indent=2))

يحتوي state.json على history / decisions / text_calls كاملة — فاتورة الدرس السابق حُسبت من هذا النوع من البيانات. artifacts/ موجود في المستودع .gitignore ولن يُرفع بالخطأ.

** يلتقط لقطات شاشة فقط دون حفظها على القرص. ** إذا أردت الحصول على لقطات base64 في state (page["screenshot"]) ومعالجتها بنفسك، يكفي تمرير screenshots=True دون تعيين record_dir.

** لا ترغب في إدارة متصفح محليًا؟ ** في أعلى README يوجد تنبيه مهم: خدمة BU Ultrafast المستضافة على Browser Use Cloud أصبحت متاحة (تُعيّن في الخدمة السحابية model: "bu-ultrafast")، أما النسخة مفتوحة المصدر فهي تنفيذ مرجعي يعمل محليًا — الاثنان ليسا الشيء نفسه، فلا تطبّق استخدام jev_ultrafast.Agent في هذه الصفحة مباشرة على الخدمة السحابية. راجع درس المبادئ.

خلاصة هذا الدرس ​

✅ jev_ultrafast هي مكتبة: نقطة الدخول الوحيدة هي Agent (و Browser)، و Agent(url, goals, *, record_dir=None, screenshots=False) كل استدعاء للإنشاء هو مهمة واحدة، وتُغلق بـ with.

✅ نفس مجموعة الاستراتيجيات مع تغيير الرابط والهدف تصبح مهمة جديدة: أنت لا تكتب محددات (selectors)، بل تكتب الهدف فقط — هدف جيد واحد = مهمة + شرط توقف + حدود.

✅ run() تُنتج (yield) state خطوة بخطوة: history (الأفعال)، decisions (التنبؤات)، text_calls (توليد النصوص)، status، elapsed_ms — فاتورة الدرس السابق جاءت من هذه الحقول.

✅ الميزانية وشبكة الأمان: 60 فعلًا / 120 استدعاء نموذج، و 3 محاولات متتالية دون تغيير تؤدي تلقائيًا إلى blocked؛ إعادة الملاحظة تلقائية عند stale، والقرار يُستهلك مرة واحدة فقط — كل ذلك دون أن تكتبه.

✅ القاعدة الصارمة لدروس Jev Ultrafast: DONE لا يُعتد به — اتبع نمط verify() في flights.py وجهّز لمهمتك تحققًا مستقلًا، واقرأ صفحة النتائج لا إجابة النموذج.

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

المعامل / الحقلالقيمة الموصى بهاالشرح
Agent(url, goals)إلزاميurl هي صفحة البداية؛ goals هدف واحد أو قائمة (تُدمج القائمة بأسطر جديدة بالترتيب)
record_dirيُعيَّن عند الحاجة إلى إعادة تشغيل التسجيليحفظ jpg لكل خطوة، ويفعّل لقطات الشاشة تلقائيًا
screenshotsالافتراضي Falseالحلقة الافتراضية لا تلتقط لقطات شاشة
أمر التشغيلuv run --env-file .env python my_task.pyيُنفَّذ من الدليل الجذري للمستودع، و --env-file لا يمكن حذفه
--url / --goalإلزامي في run.py--goal يمكن تمريره بشكل متكرر لتكوين قائمة أهداف مرتبة
TEXT_MODEL_API_KEYيجب تعيينه عند وجود كتابة نصإذا نُقص يظهر الخطأ عند خطوة TYPE_TEXT فقط؛ وعند عدم تعيين نقطة النهاية/اسم النموذج يتحول الكود افتراضيًا إلى DeepSeek
التحققيجب أن يتوفر لكل مهمةاقرأ state["page"]، ولا يُعد نجاحًا إلا عندما تكون passed بقيمة true

استعراض الدرس القادم ​

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

  • كيفية استخدام uv run browser-harness --doctor عندما يفشل الاتصال بـ Chrome
  • مقارنة نصوص الأخطاء الشائعة: خطأ TEXT_MODEL، وماذا يعني كل من Model provider returned HTTP …
  • قدرات الصفحات التي لا يدعمها هذا MVP (shadow DOM، canvas، الرفع، فتح تبويب جديد……) — عند الانحراف راجع أولًا قائمة الدعم
  • كيفية تشخيص سيناريوهات blocked المختلفة: أفعال غير صالحة متتالية، تجاوز الميزانية

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

انقر للعرض لمعرفة موضع الكود المصدري

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

الوظيفةمسار الملفالمواضع الرئيسية
نقطة دخول المكتبة (تصدّر Agent و Browser فقط)jev_ultrafast/init.pyL1–6 __all__ = ["Agent", "Browser"]
توقيع Agent وإنشاؤهjev_ultrafast/agent.pyL12–26 Agent(url, goals, *, record_dir=None, screenshots=False)؛ دمج goals كسلسلة/قائمة بأسطر جديدة؛ هدف فارغ Supply a task؛ الإنشاء يفتح المتصفح ويلاحظ مباشرة، وعند الفشل يغلق أولًا ثم يرمي الاستثناء
جميع حقول statejev_ultrafast/agent.pyL27–41 goal / page / decision / history / status / plan / plan_index / decisions / text_calls / elapsed_ms / started_at / record
snapshot() (اللقطة تحذف browser وتضيف elements)jev_ultrafast/agent.pyL46–50
run() (تُنتج yield حتى done/blocked)jev_ultrafast/agent.pyL163–165
الميزانية و blockedjev_ultrafast/agent.pyL75–76 ميزانية استدعاءات النموذج MAX_STEPS * 2؛ L102–104 60 ميزانية الأفعال تضع blocked؛ L153–157 3 محاولات متتالية دون تغيير وليست wait تضع blocked
القرار يُستهلك مرة واحدة / إعادة الملاحظة تلقائية عند stalejev_ultrafast/agent.pyL55–64 تلتقط tick استثناء StalePage وتعيد الملاحظة؛ L90–91 يُفرغ القرار قبل التنفيذ
حقول مدخلات history / text_callsjev_ultrafast/agent.pyL115 text_calls (model / latency_ms / usage / field / value)؛ L121–141 history (step / action / kind / choice / probability / confidence / latency_ms / text / text_helper / text_latency_ms / operation / target / page_changed / url / usage / executed_ms / elapsed_ms)
لا يمكن إعادة استخدام وكيل (Agent) منتهٍjev_ultrafast/agent.pyL73–74 This run has stopped. Start a fresh demo.
مدير السياق (context manager)jev_ultrafast/agent.pyL167–174 close() / __enter__ / __exit__
أداة تشغيل (runner) عامةexamples/run.pyL7–10 --url إلزامي، --goal قابل للتكرار (action="append"، help: Repeat for an ordered list of goals)؛ L12–15 تنسيق الطباعة وعنوان URL النهائي
هيكل استخدام المكتبة وأمر التشغيلREADME.md«Use the library»: uv run --env-file .env python your_script.py؛ مثال Wikipedia لسطر الأوامر؛ The same policy can run a different task
إعداد مساعد النصوص (helper) والتحقق منهjev_ultrafast/model.pyL160–168 TEXT_MODEL_API_KEY إلزامي (نص رسالة الخطأ)، نقطة النهاية والنموذج الافتراضيان لـ DeepSeek، وفروع reasoning الثلاثة؛ L187–193 يجب أن يكون الناتج بمفتاح واحد {"text": …} وغير فارغ و≤2000 حرفًا، وإلا لا يُدخَل في
تعليمات مساعد النصوص (helper)jev_ultrafast/questions.pyTEXT_VALUE: عند غياب القيمة يُرجَع {"text": null}، ولا يُختلَق أي معلومات شخصية؛ MAX_STEPS = 60
نموذج وضع verifyexamples/flights.pyL18–38 verify() 7 فحوصات مستقلة؛ L63–64 عند فشل التحقق SystemExit
بيانات اختبار الدخان (smoke) لـ Wikipediadocs/performance.mdOther checks: نفس الاستراتيجية تفتح هذا الإدخال خلال 2.798 s؛ مهمة الفندق المحلية خلال 1.896 s
علاقة الخدمة السحابية بالنسخة مفتوحة المصدرREADME.mdIMPORTANT في الأعلى: BU Ultrafast (model: "bu-ultrafast") هو النسخة المستضافة على Browser Use Cloud؛ .env المتغيرات الستة موجودة في .env.example
حقول ملاحظة الصفحةjev_ultrafast/browser.pyL115–117 يُحسَب fingerprint من url/text/actions/scroll؛ L188–193 تُرجِع الملاحظة info + fingerprint (+screenshot اختياري)؛ model.py L110 يأخذ url/title/text من page
الـ inspector وحده هو من يقرأ .env بنفسهjev_ultrafast/demo.pyL23–29 load_environment() (ملف .env في cwd)، L132 يُستدعى عند بدء التشغيل
الـ trace لا يدخل إلى git.gitignore.env و.venv/ وartifacts/ كلها مُتجاهَلة
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.