pdfx CLI: محلي أولاً، وسحابياً عند الحاجة
يعالج pdfx ملفات PDF على جهازك افتراضياً، ثم تنتقل إلى السحابة بعنوان أساسي ومفتاح API عند حاجتك إلى نقاط نهاية PDF123 المستضافة أو الذاتية.
اسم المنتج هو PDF123، أما pdfx فهو واجهة سطر أوامر قصيرة تخاطب العمليات ذاتها. والمسار الافتراضي محلي: اقرأ ملفاً، وشغّل العملية عبر pdf-core واكتب ناتجاً. بلا حساب، وبلا مفتاح API، وبلا رفع.
المحلي أولاً يعني أن الملف لا يغادر
يبدو الاستدعاء النمطي هكذا: pdfx merge a.pdf b.pdf -o merged.pdf أو pdfx compress input.pdf. وتجري المعالجة حيث يعمل الملف التنفيذي. وهذا يناسب مهام CI على مشغّل خاص، والسكربتات التي تجاور دفعة فواتير، وكل حالة يكون فيها الرفع إلى طرف ثالث جواباً خاطئاً.
والوضع المحلي ليس غلافاً رقيقاً يرسل البايتات إلى مكان آخر سراً، فالأداة تتشارك سجلّ العمليات نفسه مع الخادم (pdf_core::ops::run). وإن أردت مسار الشبكة، انتقل إليه صراحةً بـ --cloud.
وتغطي الأوامر الفرعية المدمجة عمليات شائعة: الدمج، والتقسيم، والضغط، والتدوير، والاستخراج، وOCR، والتحويل، والحماية، وفك القفل، والعلامة المائية، وما يجاورها. والناتج المحلي ملفٌ افتراضياً عبر -o أو --output ويكتب الرمز - إلى المخرج القياسي.
--cloud هو الكتالوج نفسه عبر HTTP
حين تحتاج واجهة API المستضافة، أو خادم pdfx-server الخاص بك، مرّر --cloud مع --api-base و--api-key أو PDFX_API_KEY. ويتطلب وضع السحابة curl في الداخل ويفشل إن لم يُضبط مفتاح API. ومن المثال المنشور في المهارة:
pdfx --cloud --api-base "$PDFX_API_BASE" --api-key "$PDFX_API_KEY" \
merge a.pdf b.pdf -o merged.pdf
ويُضبط --api-base افتراضياً على https://pdf123.xyz، أي واجهة الاستضافة. ولنسخة Docker Compose محلية وجّهه إلى http://127.0.0.1:8080 بدلاً من ذلك. وتصبح الأداة عميلاً لسطح REST الموثّق على المطوّرين، وتتوافق أسماء العمليات مع أدوات البوابة وOpenAPI (/v1/openapi.json).
ولا يغيّر وضع السحابة معنى العملية. فالضغط ما زال ضغط تدفقات qpdf، وOCR ما زال يعيد نص Markdown من مسار Rust لا طبقة PDF قابلة للبحث. والأعلام المتبقية في أداة سطر الأوامر التي تقابل معاملات OCR مهملة من حقبة Java، مثل حقل languages لا تغيّر ذلك العقد.
لماذا يوجد وضعان
يغطي المحلي الثقة دون اتصال وكلفة الذهاب والإياب الصفرية. ويغطي السحابي حدود المعدل المشتركة، وتشغيل العمليات على جهاز لا يملك إلا أداة سطر الأوامر وcurl، والفرق التي تصدر مفاتيح API بالفعل. ويستطيع الوكلاء أيضاً استدعاء القاعدة نفسها عبر MCP عند /mcp أو عبر المهارة المنشورة في dist/skills/pdf-toolbox/SKILL.md إضافة إلى فهارس الاكتشاف مثل /llms.txt التي تساعد وكلاء البرمجة على العثور على نقاط النهاية، وهي ليست إشارة ترتيب في Google.
ولإعادات المحاولة الآمنة لطلبات POST المُعدِّلة على الواجهة، أرسل Idempotency-Key كما في إعادات المحاولة الآمنة لمهام PDF. ويظل مسار السحابة في الأداة طلب HTTP واحداً لكل استدعاء؛ استخدم الترويسة حين يعيد غلافك المحاولة.
اختيار الوضع عملياً
استخدم المحلي حين يجب أن تبقى الملفات على المشغّل، وحين تملك ملف pdfx التنفيذي والاعتماديات الأصلية على ذلك الجهاز، وحين يكون زمن الاستجابة محكوماً بالعملية لا بالرفع. واستخدم السحابي حين تكون الاعتماديات الثقيلة على الخادم وحده، أو حين تريد حدود المعدل والقياس نفسها التي يحصل عليها عملاء API الآخرون، أو حين يملك الوكلاء بالفعل مفتاح API لـ https://pdf123.xyz أو لقاعدتك المستضافة ذاتياً.
ولا تخلط التوقعات: فـ OCR المحلي ما زال يتبع عقد مخرجات Markdown في النقطة misc/ocr-pdf وضغط السحابة ما زال تدفقات qpdf لا تجزئة خطوط. فمفتاح الوضع يغيّر مكان تشغيل العملية، لا دلالة الكتالوج.
ما ليست عليه الأداة
pdfx ليست واجهة رسومية مكتبية ولا مكتبة OCR قابلة للتضمين تربطها في تطبيق آخر. إنها عميل سطر أوامر لعمليات PDF: محلي افتراضياً، وHTTP عند الطلب. أما المهام الفردية في المتصفح فتبقى على البوابة (الضغط وOCR وبقية الكتالوج). والأتمتة التي تفضّل ملفاً تنفيذياً تستطيع البقاء على pdfx.
وتجد مقارنات العملية الواحدة بين المتصفح وcurl وMCP وأداة سطر الأوامر في العملية نفسها، أربعة عملاء. ابدأ من المطوّرين للمفاتيح وOpenAPI، أو من الاستضافة الذاتية إن كان عنوان القاعدة يجب أن يكون نسخة Docker Compose خاصة بك.