اكتب مهام متصفحك الخاصة: تطبيق عملي لمكتبة 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):
Agent(url, goals, *, record_dir=None, screenshots=False)| المعامل | النوع | الوصف |
|---|---|---|
url | str | صفحة البداية. عند الإنشاء يُفتح تلقائيًا تبويب خلفي (منفذ عرض 1120×780) وتُنتظر اكتمال تحميل الصفحة (بحد أقصى 15 ثانية) |
goals | str أو قائمة | جملة هدف واحدة؛ إذا مرّرت قائمة تُدمج بالترتيب بفواصل أسطر في نص مهمة واحد. الهدف الفارغ يرمي مباشرة ValueError: Supply a task |
record_dir | مسار (اختياري) | مجلد التسجيل: عند ضبطه تُحفظ تلقائيًا صورة jpg في كل خطوة (الشاشة الأولى هي 000000.jpg، وبعدها التسمية حسب المللي ثانية التراكمية) |
screenshots | bool (اختياري) | هل تُلتقط لقطات شاشة أثناء الملاحظة، الافتراضي False — الحلقة الافتراضية لا تلتقط لقطات (كما يذكر README صراحةً)؛ عند ضبط record_dir يُفعَّل تلقائيًا معه |
ثلاث نقاط استخدام رئيسية:
- استخدم
with: الـ Agent هو مدير سياق (context manager)، عند انتهاء كتلةwithيُغلق التبويب تلقائيًا؛ وحتى عند فشل الإنشاء (مثلًا تعذر فتح الصفحة) يُغلق المتصفح أولًا ثم يُرمى الخطأ - الإنشاء يعني الملاحظة: بمجرد تنفيذ
Agent(...)يكون المتصفح قد فُتح وأُنجزت الملاحظة الأولى، ولا ينتظر حتى تستدعيrun()لتبدأ - للاستخدام مرة واحدة: بعد الوصول إلى done أو blocked ينتهي هذا الـ Agent، ولا يمكن متابعة تشغيله (تنبيه المصيدة رقم 4)
يفترض أن ترى: في المجلد الجذر للمستودع تحقق من نقطة الدخول (uv sync أدرج الحزمة في البيئة بالفعل):
uv run python -c "from jev_ultrafast import Agent; print(Agent)"<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 يجب تنفيذه من المجلد الجذر للمستودع):
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، انظر الخطوة التالية). التشغيل:
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):
<المللي ثانية> ready
<المللي ثانية> ready
……
<المللي ثانية> done
<الـ URL النهائي — صفحة مقال مبرهنة عدم الاكتمال لغودل>(الأرقام بالمللي ثانية والترميز الدقيق للـ URL تعتمد على تشغيلك هذا)
- اكتمل تشغيل
my_task.py، والـ URL المطبوع في السطر الأخير هو صفحة مقال مبرهنة عدم الاكتمال لغودل
الخطوة 3: تشغيل أي مهمة دون كتابة كود باستخدام examples/run.py
لماذا: إذا أردت تجربة مهمة على عجل، لا تحتاج حتى إلى إنشاء ملف — الـ runner العام المرفق بالمستودع يحوّل الـ URL والهدف كليهما إلى معاملات سطر أوامر.
الأمر الأصلي في README (حرفيًا):
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 الحالي للمتصفح:
<المللي ثانية> 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):
| الحقل | المحتوى | ما الذي يمكنك فعله به |
|---|---|---|
status | ready / 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):
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 نسخة مماثلة:
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):
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، ونص الخطأ الأصلي:
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:
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 كذلك لا يُكتب، ويُرمى الاستثناء:
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 لحفظ اللقطات على القرص:
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.py | L1–6 __all__ = ["Agent", "Browser"] |
| توقيع Agent وإنشاؤه | jev_ultrafast/agent.py | L12–26 Agent(url, goals, *, record_dir=None, screenshots=False)؛ دمج goals كسلسلة/قائمة بأسطر جديدة؛ هدف فارغ Supply a task؛ الإنشاء يفتح المتصفح ويلاحظ مباشرة، وعند الفشل يغلق أولًا ثم يرمي الاستثناء |
| جميع حقول state | jev_ultrafast/agent.py | L27–41 goal / page / decision / history / status / plan / plan_index / decisions / text_calls / elapsed_ms / started_at / record |
| snapshot() (اللقطة تحذف browser وتضيف elements) | jev_ultrafast/agent.py | L46–50 |
| run() (تُنتج yield حتى done/blocked) | jev_ultrafast/agent.py | L163–165 |
| الميزانية و blocked | jev_ultrafast/agent.py | L75–76 ميزانية استدعاءات النموذج MAX_STEPS * 2؛ L102–104 60 ميزانية الأفعال تضع blocked؛ L153–157 3 محاولات متتالية دون تغيير وليست wait تضع blocked |
| القرار يُستهلك مرة واحدة / إعادة الملاحظة تلقائية عند stale | jev_ultrafast/agent.py | L55–64 تلتقط tick استثناء StalePage وتعيد الملاحظة؛ L90–91 يُفرغ القرار قبل التنفيذ |
| حقول مدخلات history / text_calls | jev_ultrafast/agent.py | L115 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.py | L73–74 This run has stopped. Start a fresh demo. |
| مدير السياق (context manager) | jev_ultrafast/agent.py | L167–174 close() / __enter__ / __exit__ |
| أداة تشغيل (runner) عامة | examples/run.py | L7–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.py | L160–168 TEXT_MODEL_API_KEY إلزامي (نص رسالة الخطأ)، نقطة النهاية والنموذج الافتراضيان لـ DeepSeek، وفروع reasoning الثلاثة؛ L187–193 يجب أن يكون الناتج بمفتاح واحد {"text": …} وغير فارغ و≤2000 حرفًا، وإلا لا يُدخَل في |
| تعليمات مساعد النصوص (helper) | jev_ultrafast/questions.py | TEXT_VALUE: عند غياب القيمة يُرجَع {"text": null}، ولا يُختلَق أي معلومات شخصية؛ MAX_STEPS = 60 |
| نموذج وضع verify | examples/flights.py | L18–38 verify() 7 فحوصات مستقلة؛ L63–64 عند فشل التحقق SystemExit |
| بيانات اختبار الدخان (smoke) لـ Wikipedia | docs/performance.md | Other checks: نفس الاستراتيجية تفتح هذا الإدخال خلال 2.798 s؛ مهمة الفندق المحلية خلال 1.896 s |
| علاقة الخدمة السحابية بالنسخة مفتوحة المصدر | README.md | IMPORTANT في الأعلى: BU Ultrafast (model: "bu-ultrafast") هو النسخة المستضافة على Browser Use Cloud؛ .env المتغيرات الستة موجودة في .env.example |
| حقول ملاحظة الصفحة | jev_ultrafast/browser.py | L115–117 يُحسَب fingerprint من url/text/actions/scroll؛ L188–193 تُرجِع الملاحظة info + fingerprint (+screenshot اختياري)؛ model.py L110 يأخذ url/title/text من page |
| الـ inspector وحده هو من يقرأ .env بنفسه | jev_ultrafast/demo.py | L23–29 load_environment() (ملف .env في cwd)، L132 يُستدعى عند بدء التشغيل |
| الـ trace لا يدخل إلى git | .gitignore | .env و.venv/ وartifacts/ كلها مُتجاهَلة |