مرجع مطوّري Sweepy
يعمل Sweepy كمشروع Python صغير بمحرك مسطّح. تربط هذه الصفحة كل مرحلة من خط المعالجة بالوحدة التي تشغّلها، لتعرف أين تجري التغيير.
الجمهور
اقرأ هذه الصفحة إذا كنت تخطط لتغيير شيفرة Sweepy أو إضافة مصدر وظائف. ويستطيع المراجعون استخدامها لتوجيه طلب دمج. وتغطي الداخليات فقط: الوحدات والتبعيات وإصدارات Python.
تلميح
تجاوز هذه الصفحة إذا كنت تريد تشغيل عمليات المسح. ابدأ بـ التثبيت.
مراحل خط المعالجة والوحدات
يشغّل swee.py خمس مراحل بالترتيب. وتطبع الطرفية كل مرحلة بالصيغة [1/5] حتى [5/5].
| المرحلة | الوحدة | ما تفعله |
|---|---|---|
| 1. تحميل الملف التعريفي | engine/config.py | يحمّل ملفك التعريفي بصيغة YAML ويتحقق منه. ويكتب المعالج في الوحدة نفسها ملفًا تعريفيًا. |
| 2. اكتشاف الوظائف | engine/discovery.py | يستعلم من تغذيات المجمّعات عبر python-jobspy ويصنّف كل منصة. |
| 2. اكتشاف الوظائف | engine/sources/ | يجلب منصات Greenhouse وAshby وLever وWorkable وBuilt In NYC من نقاط نهاية عامة. |
| 2. إزالة التكرار | swee.py | يدمج نتائج المجمّعات والمصادر في بطاقة واحدة لكل رابط وظيفة. |
| 3. التحقق من الروابط | engine/validator.py | يفحص كل رابط بطلب HTTP HEAD مع GET كبديل. ويحذف الإعلانات الميتة. |
| 4. احتساب التطابق مقابل السيرة الذاتية | engine/scorer.py | يستخرج مصطلحات الإعلان والسيرة الذاتية، ثم يحتسب التداخل في المتطلبات والكلمات المفتاحية. ويوسم الإعلانات التي تطلب إجابات كتابية. |
| 5. توجيه مسارات السيرة الذاتية | engine/enrich.py | يختار المسار ذا أعلى تداخل مصطلحات ويسند لون الشارة المطابق. |
| 5. إثراء البطاقات | engine/enrich.py | يبني ملخصات البطاقات وسطور الراتب ونص النصيحة المخصص. |
| 5. PDF البطاقات الافتراضي | engine/report.py | يعرض تخطيط البطاقات، ست بطاقات في الصفحة افتراضيًا، ويعيد عدد الصفحات. |
| 5. PDF الجدول القديم | engine/pdf_builder.py | يعرض تخطيط الجدول عندما يضبط ملفك التعريفي report.style: legacy. |
| 5. تصدير البيانات | engine/exporter.py | يكتب ملفات CSV وJSON. ويحوّل صور صفحات PNG عند الطلب. |
| 5. تتبع الوظائف | engine/tracking.py | يضيف أعمدة التتبع ويقرأ التصديرات السابقة لتعود القيم التي تدخلها. |
تحمل engine/session.py مخزن البطاقات للتدفق الحافي الحالة عبر بروتوكول سياق النموذج (MCP). ويحفظ البطاقات في خريطة آمنة للخيوط مفهرسة بتجزئة ثابتة لكل رابط وظيفة.
أين تجري التغيير
| ما تريد تغييره | ابدأ في |
|---|---|
| مصدر وظائف أو نقطة نهايته | engine/sources/، مع قائمة بذور في data/sources/ |
| طريقة احتساب التطابقات | engine/scorer.py |
| ما تعرضه البطاقة | engine/enrich.py، ثم engine/report.py |
| طريقة فحص الروابط | engine/validator.py |
| مفتاح سطر أوامر | swee.py |
| أداة MCP | server.py |
تلميح
تستورد server.py الوحدات نفسها التي تستوردها أداة سطر الأوامر. فاختبر مسار MCP بعد أي تغيير في المحرك، لأن إصلاحًا واحدًا يؤثر في نقطتي الدخول.
مرجع الوحدات
نقاط الدخول
| الوحدة | الغرض |
|---|---|
swee.py | المنسّق الأساسي ونقطة دخول سطر الأوامر عبر argparse لخط المعالجة المكوّن من خمس مراحل. |
server.py | خادم بروتوكول سياق النموذج (stdio) الذي يعرض أدوات المحرك لمساعدي الذكاء الاصطناعي. |
وحدات المحرك
| الوحدة | الغرض |
|---|---|
engine/config.py | المعالج التفاعلي مع تحميل YAML والتحقق منه. |
engine/discovery.py | تنسيق أدوات الاستخراج لـ python-jobspy والمصادر الحتمية، وكشف أنظمة تتبع المتقدمين (ATS)، وإزالة التكرار. |
engine/validator.py | فحوص استمرار الروابط مع كشف soft-404. وتبقى الروابط غير القابلة للتحقق في التشغيل. |
engine/scorer.py | استخراج مصطلحات السيرة الذاتية، ومطابقة النسبة، والوسم، والاحتساب لكل مسار. |
engine/enrich.py | إثراء البطاقات بالملخصات والراتب وتوجيه المسار والنصائح المخصصة. |
engine/session.py | مخزن بطاقات آمن للخيوط بمعرّفات ثابتة للتدفق الحافي الحالة عبر MCP. |
engine/report.py | PDF تخطيط البطاقات الافتراضي. |
engine/pdf_builder.py | PDF تخطيط الجدول القديم لـ report.style: legacy. |
engine/exporter.py | تصديرات CSV وJSON، مع تحويل تقارير PDF إلى صور PNG. |
engine/tracking.py | أعمدة التتبع وقراءة الترحيل من التصديرات السابقة. |
engine/docx.py | تحويل DOCX إلى PDF بـ python-docx وreportlab، مع بديل Microsoft Word. |
engine/documents.py | توجيه المستندات لـ --convert ومحوّل MCP، ويغطي DOCX وDOC والنص وMarkdown وPDF. |
engine/logging.py | سجلات تصحيح اختيارية تحت logs/. |
engine/cache.py | ذاكرة استخراج مؤقتة في SQLite مفهرسة بالاستعلام ومجموعة المحركات، بعمر ساعة واحدة. |
engine/circuit_breaker.py | يعدّ أخطاء المصدر المتتالية ويوقف الطلبات أثناء فترة تهدئة. |
engine/engine_defaults.py | قوائم مواقع افتراضية مشتركة وإعدادات محركات، بلا استيرادات لتجنب الدورات. |
engine/engines.py | سجل المحوّلات ومثبّت المحركات الاختيارية hirehunt وopenroles وapify وjobdrop. |
engine/history.py | سجل دائم للإعلانات التي سبق الإبلاغ عنها. فالمسح اليومي يبلّغ عن الوظائف الجديدة فقط. |
engine/normalize.py | يوحّد صفوف المحركات الخام في أعمدة الإعلان المشتركة. |
engine/salary.py | استخراج الأجر من نص الإعلان عندما تهمل المنصة الأجر المهيكل. |
engine/sweep_config.py | يطبّق القيم الافتراضية المشتركة للمحرك على إعدادات الملف التعريفي. |
engine/updater.py | فحص تحديث قائم على Git وإعادة تثبيت التبعيات للنسخة المستنسخة. |
المصادر الحتمية
| الوحدة | الغرض |
|---|---|
engine/sources/__init__.py | تصديرات أدوات الجلب وتحميل قوائم البذور من data/sources/. |
engine/sources/_common.py | أدوات مساعدة مشتركة لترويسات HTTP والترشيح المسبق للعناوين وتحويل HTML إلى نص. |
engine/sources/greenhouse.py | أداة جلب منصة وظائف Greenhouse. |
engine/sources/ashby.py | أداة جلب منصة وظائف Ashby. |
engine/sources/lever.py | أداة جلب إعلانات Lever. |
engine/sources/workable.py | أداة جلب واجهة برمجة ودجت Workable. |
engine/sources/builtinnyc.py | أداة استخراج فئات Built In NYC. |
محوّلات المحركات
| الوحدة | الغرض |
|---|---|
engine/adapters/__init__.py | سجل يربط كل اسم محرك بمحوّله. |
engine/adapters/base.py | الصنف الأساسي ScraperAdapter، وترويسة User-Agent المشتركة، وأدوات مساعدة لشكل النتائج. |
engine/adapters/jobspy_adapter.py | محوّل مجمّع python-jobspy لـ LinkedIn وIndeed وGlassdoor وZipRecruiter. |
engine/adapters/ats_adapter.py | محوّل فوق أدوات جلب ATS الحتمية في engine/sources/. |
engine/adapters/hirehunt_adapter.py | محوّل محرك hirehunt الاختياري. |
engine/adapters/openroles_adapter.py | محوّل محرك openroles الاختياري. |
engine/adapters/apify_adapter.py | محوّل ممثل Apify الاختياري. |
engine/adapters/jobdrop_adapter.py | محوّل محرك jobdrop الاختياري. |
البيانات والنصوص البرمجية والاختبارات
| المسار | الغرض |
|---|---|
data/sources/*.txt | قوائم بذور للمنصات والشركات والمؤسسات والفئات. |
scripts/make_sample.py | أداة بناء التقرير النموذجي المحفوظ في docs/. |
tests/ | مجموعة اختبارات pytest بملف لكل مجال: المحوّلات والتهيئة والمستندات وdocx والمحركات والإثراء والسجل والتسجيل والتقرير. وتغطي ملفات أخرى الأجر ومحتسب التطابق والخادم والجلسة والمصادر وswee والتتبع والمحدّث والمدقق. |
ملاحظة
أضف ملف اختبار مخصصًا عندما تغيّر discovery.py أو exporter.py أو pdf_builder.py. وضع الملف في tests/.
التبعيات
تأتي حزم التشغيل من requirements.txt. وتطابق الإصدارات أدناه ذلك الملف.
| الحزمة | الإصدار | ما تفعله لـ Sweepy |
|---|---|---|
reportlab | 5.0.1 | يبني تقرير PDF المنسّق مع روابط قابلة للنقر. |
pymupdf | 1.28.2 | يستخرج النص من سير PDF ويحوّل تصديرات PNG إلى صور نقطية. |
python-docx | 1.2.0 | يقرأ السير بصيغة .docx ويعيد بناء نص DOCX كـ PDF دون Word. |
requests | 2.32.5 | يصل إلى نقاط نهاية ATS ويفحص كل رابط وظيفة بحثًا عن استجابة حية. |
beautifulsoup4 | 4.15.0 | يحلل HTML من مصادر Greenhouse وLever وWorkable وBuilt In NYC. |
pyyaml | 6.0.3 | يقرأ الملفات التعريفية بصيغة YAML ويكتبها. |
questionary | 2.1.1 | يدير أسئلة المعالج التفاعلي. |
prompt-toolkit | 3.0.53 | يدير إدخال النص التفاعلي في المعالج. |
python-jobspy | 1.2.0 | يستخرج من LinkedIn وIndeed وGlassdoor وZipRecruiter دون بيانات اعتماد API. |
pandas | 2.2.3 | ينظّم الإعلانات ويبني تصديرات CSV وJSON. |
mcp | 1.30.0 | يشغّل خادم بروتوكول سياق النموذج. |
anyio | 4.12.1 | يشغّل ناقل MCP غير المتزامن. |
يسرد requirements.txt حزمة اختيارية واحدة أيضًا. أزل التعليق عن docx2pdf عندما يجب أن يبني Word ملف PDF.
docx2pdf(0.5.2، اختيارية) تعرض DOCX إلى PDF عبر Microsoft Word على Windows. ويستدعيها Sweepy كلما وُجد Microsoft Word على الجهاز.
ملاحظة
يبقى mcp على الإصدار 1.x بقصد. فحزمة SDK بالإصدار 2.x تخدم عصر بروتوكول 2026-07-28 فقط. وعميل يستكشف server/discover ثم يعود إلى مصافحة initialize يتلقى خطأ -32022. ويتبع VS Code Copilot ذلك البديل.
تلميح
يبقى pandas على الإصدار 2.x بقصد. فـ Pandas 3.x يتطلب Python 3.11 أو أحدث، ولا تزال مصفوفة CI تختبر Python 3.10.
حزم التطوير (requirements-dev.txt)
| الحزمة | الإصدار | ما تفعله |
|---|---|---|
pytest | 9.1.1 | يشغّل مجموعة الاختبارات في tests/. |
pytest-cov | 7.1.0 | يبلّغ عن التغطية في swee.py وserver.py وengine/scorer.py. |
ruff | 0.17.0 | يفحص الشيفرة ويرتب الاستيرادات. |
tomli | 2.2.1 | يوفّر tomllib لتشغيلات اختبار Python 3.10. |
الطرفية
pip install -r requirements.txt
pip install -r requirements-dev.txt
ruff check .
pytest -q
المتطلبات وإصدارات Python المدعومة
| العنصر | التفصيل |
|---|---|
| الحد الأدنى لـ Python | يتطلب Sweepy الإصدار Python 3.10 أو أحدث ويستهدف صياغة 3.10 في كل وحدة. |
| النطاق المختبَر | يشغّل سير عمل CI في .github/workflows/ci.yml الإصدارات Python 3.10 و3.11 و3.12 على Ubuntu. |
| هدف الفحص | يضبط pyproject.toml القيمة target-version = "py310" في ruff. وأي تركيب خاص بإصدار أحدث يفشل مهمة الفحص. |
| طول السطر | يفرض Ruff حدًا بـ 100 حرف ويتجاهل E501. |
| خطوات CI | تثبّت المهمة ملفَي المتطلبات وتنفّذ ruff check . قبل pytest. |
ملاحظة
يعلن pyproject.toml القيمة requires-python = ">=3.10"، فيرفض pip أي مفسّر أقدم عند التثبيت. وتحدد مصفوفة CI وهدف ruff النطاق المختبَر. ويعمل Python 3.13 عمليًا لكنه يبقى خارج ذلك النطاق.
Python 3.13
قد تُجمَّع حزمة pymupdf من المصدر عندما لا تتوفر حزمة جاهزة. ثبّت Microsoft C++ Build Tools واختر حمل العمل "Desktop development with C++" قبل تثبيت التبعيات.
تخطيط المستودع
بنية المستودع
swee.py نقطة دخول سطر الأوامر ومنسّق المسح
server.py خادم MCP عبر stdio
engine/ وحدات خط المعالجة
engine/sources/ أدوات جلب حتمية لأنظمة ATS
engine/adapters/ محوّلات المجمّعات والمحركات الاختيارية
data/sources/ قوائم أولية لكل أداة جلب
profiles/ ملفات تعريف بحث بصيغة YAML
results/ ملفات PDF وCSV وJSON وPNG مُنشأة
logs/ سجلات تصحيح اختيارية
styles/ قواعد أسلوب Vale للتوثيق
tests/ مجموعة اختبارات pytest
عندما تغيّر توقيع أداة في server.py، حدّث مرجع أدوات MCP في الالتزام نفسه.