عن المشروع

web-core هي حزمة بنية تحتية ويب مشتركة لـ Python، توصف بأنها المحرك لخادم wet-mcp MCP والتطبيقات الأخرى التابعة له. تقوم الحزمة بتجميع عدة قدرات مواجهة الويب خلف واجهة برمجة تطبيقات (API) عامة ومحددة الأنواع، ويشير ملف README إلى أن المحددات (selectors) الخاصة بالمواقع تُترك عمدًا للتطبيقات المستهلكة — حيث توفر الحزمة بنية تحتية عامة فقط، مع توفير ملفات تعريف الارتباط (cookies) والمحددات لكل نطاق عبر متغيرات البيئة. القدرات المدرجة في README: - بحث SearXNG: مشغل singleton عبر العمليات (يعتمد على قفل الملف، مما يضمن وجود نسخة واحدة عبر جميع عمليات Python) بالإضافة إلى عميل يقوم بإعادة المحاولات، وإزالة تكرار النتائج، وتصفية النطاقات. - كشط متعدد الاستراتيجيات: وكيل LangGraph state-machine يقوم بالتصعيد عبر الاستراتيجيات. تشمل وحدات الاستراتيجية المتاحة: الجلب المباشر عبر API، وHTTP الأساسي، وتزييف بصمة TLS عبر curl-cffi، والرندرة بدون رأس (headless) عبر Crawl4AI، ورندرة متصفح Patchright المتخفي، والرندرة عن بعد من خلال RenderClient، واستراتيجية CAPTCHA مدعومة بـ CapSolver. يتم تجربة الاستراتيجيات بترتيب موصى به في التخزين المؤقت، ويتم التحقق من الاستجابات، وتتصاعد الإخفاقات تلقائيًا — بما في ذلك الانتقال من أغلفة JavaScript غير المرندرة بالكامل إلى خلفية رندرة. يتتبع StrategyCache الأداء لكل نطاق. - عميل HTTP آمن ضد SSRF: عميل httpx مثبت الـ DNS، وتطبيع الـ URL، وتجريد معاملات التتبع، ومساعدات التحقق من النطاق. من المفترض أن تمر جميع طلبات HTTP الصادرة عبر safe_httpx_client للحماية من إعادة ربط DNS. - المتصفحات والرندرة عن بعد: بروتوكول BrowserProvider بالإضافة إلى مزود Patchright (Playwright غير مكتشف)، وBrowserlessClient لنقاط نهاية /content المستضافة ذاتيًا، وعميل Cloudflare Browser Rendering، والموجهة للحاويات النحيفة التي تنقل رندرة JavaScript إلى الخارج. - الامتثال لـ robots.txt: فحص مخزن مؤقتًا لكل نطاق قبل الجلب. - استنتاج المحددات عبر LLM (اختياري): عند فشل المحددات المدمجة، يمكن اكتشاف المزود تلقائيًا من أي مفتاح API متاح (Google Gemini, OpenAI, Anthropic, xAI)؛ وإذا لم يتم تعيين مفتاح، يتم تخطي الاستنتاج بصمت. يمكن أيضًا حقن llm_caller مخصص. يمكن توجيه Gemini عبر Vertex AI من خلال متغيرات المشروع والموقع. - مهايئات API خارجية: عملاء محددة الأنواع وآمنة ضد SSRF لجلب المجلدات والملفات من Google Drive و MangaDex (المانجا، الفصول، الصور). يتم التثبيت من PyPI باسم n24q02m-web-core (عبر uv add)، مع خط مستقر v2.x. التكوين يعتمد بالكامل على متغيرات البيئة وكل متغير اختياري — حيث يؤدي حذف أحدها إلى تعطيل الميزة التي يتحكم فيها، ولا يلزم وجود أي متغير لاستيراد الحزمة أو استخدامها. تغطي المتغيرات الموثقة URL الخاص بـ SearXNG ومستخدم التشغيل، وملفات تعريف الارتباط لكل نطاق (JSON) للكشط، ومفاتيح مزود LLM بالإضافة إلى تجاوز النموذج لاستنتاج المحددات. يتم تمرير بيانات اعتماد الرندرة عن بعد كوسطاء في المنشئ (constructor arguments) بدلاً من ذلك. تُنظم البنية تحت src/web_core مع وحدات طبقية: http (بدائيات آمنة ضد SSRF، أدوات URL)، search (العميل، النماذج، المشغل)، scraper (الوكيل، الاستراتيجية الأساسية، التخزين المؤقت، robots، استنتاج المحددات، الحالة، الأدوات، والحزمة الفرعية للاستراتيجيات)، browsers (البروتوكول، patchright، browserless، cf_rendering) و adapters (google_drive, mangadex). تشحن الحزمة علامة py.typed لـ PEP 561 typing. تشمل قرارات التصميم البارزة تثبيت DNS للحماية من SSRF، والتصعيد التلقائي للاستراتيجيات، وsingleton الخاص بـ SearXNG عبر العمليات، واستخدام التنميط الهيكلي القائم على Protocol بحيث لا تحتاج تطبيقات المتصفح والرندرة إلى الوراثة من فئة أساسية. يستهدف التطوير Python 3.13 مع uv، واختصارات مهام mise اختيارية، وpre-commit hooks، وruff للتنسيق والتدقيق، وty لفحص الأنواع وpytest مع التغطية — تفرض مجموعة الاختبارات حد تغطية بنسبة 95% وتستخدم asyncio_mode auto. تعكس ملفات الاختبار هيكل وحدات المصدر. المشروع مرخص تحت Apache-2.0.