العملية نفسها بأربعة عملاء: المتصفح وcurl وMCP وpdfx
العملية نفسها عبر أربعة عملاء: نموذج المتصفح، وcurl إلى /api/v1/general/merge-pdfs وMCP عند /mcp وpdfx محلياً أو سحابياً مقابل قاعدة API.
أربعة عملاء يبدون كأربعة منتجات، لكنهم يتشاركون كتالوجاً واحداً. خُذ الدمج كمهمة ملموسة: اجمع ملفات PDF بترتيب الرفع من دون تحويل الصفحات إلى صور. والنمط نفسه يصحّ على كل أداة أخرى في الكتالوج، من الضغط وOCR والتحويل إلى بقيتها: معرّف عملية واحد بأربع طرق للاستدعاء.
المتصفح
افتح المسار /merge ثم أضف الملفات بالترتيب الذي تريده، وشغّل العملية، ونزّل الناتج. ولا حساب لأدوات الكتالوج. وتبني كتلة Call this from code في الصفحة أمر curl من الحقول نفسها التي يرسلها النموذج، فيبقى سطح الواجهة والعقد عبر HTTP متوافقين.
وتلك الكتلة ليست نصاً تسويقياً، بل مولّدة من تعريف الأداة الذي تستخدمه البوابة للنموذج أصلاً، ولهذا يظهر تغيير اسم أي معامل في المكانين معاً. وإن قبل النموذج الحقل الاختياري sortType=byFileName فمثال curl يحمل الحقل نفسه.
curl وREST
curl -fsS -X POST "$API_BASE/api/v1/general/merge-pdfs" \
-F "[email protected]" \
-F "[email protected]" \
-o merged.pdf
لا تحتاج استدعاءات الكتالوج المجهولة مفتاحاً. أما المفاتيح من المطوّرين فتمنح الأتمتة هوية مستقرة، وتمنح الخوادم ذاتية الاستضافة بوابة. وOpenAPI عند /v1/openapi.json.
وللمهام متعددة الخطوات يقبل POST /api/v1/pipeline عمليات مرتّبة في حقل steps مثل الدمج ثم العلامة المائية ثم الضغط. أرسل Idempotency-Key حين يجب ألا تكرّر إعادات المحاولة العمل؛ وقد تعود إعادة تشغيل ناجحة مع Idempotency-Replayed. وتستخدم الأعطال application/problem+json برموز مستقرة مثل rate_limited وbad_request (أخطاء المطوّرين).
وتُعلن الردود المستضافة أيضاً ترويسات X-RateLimit-Limit وX-RateLimit-Remaining وX-RateLimit-Reset وتضمّ استجابات HTTP 429 ترويسة Retry-After. وتعامل مع تلك الترويسات كميزانية حيّة، لا كرقم محفوظ من مقال (تحديد معدل الطلبات المجهولة).
MCP
يتصل الوكلاء الذين يتحدثون بروتوكول سياق النموذج بـ /mcp فيكتشفون الدمج كأداة، ويستدعونها بقصة مفتاح API نفسها التي في REST. والتوثيق: MCP للمطوّرين.
وMCP ليس كتالوجاً ثانياً، بل بروتوكول اكتشاف واستدعاء فوق العمليات نفسها التي تسردها OpenAPI. فإن غابت عملية عن MCP فذلك خلل في الخادم لا خريطة طريق لمنتج منفصل. واقرن MCP بـ /llms.txt حين تريد فهرساً نثرياً بالأدوات قبل أن يتصل العميل.
أداة pdfx
نواة pdf-core محلياً:
pdfx merge a.pdf b.pdf -o merged.pdf
أو الخادم نفسه الذي تستخدمه البوابة:
pdfx --cloud --api-base "$API_BASE" --api-key "$KEY" merge a.pdf b.pdf -o merged.pdf
ولا يرفع الوضع المحلي شيئاً؛ أما وضع السحابة فيصل إلى عنوانك الأساسي بشكل الأجزاء المتعددة نفسه الذي يستعمله curl. وتوثّق مهارة وكيل البرمجة تحت dist/skills/pdf-toolbox/SKILL.md أشكال الدمج وخطوط المعالجة نفسها، كي لا يخترع الوكلاء OpenAPI ثانياً.
ويعيد OCR عبر أي من هؤلاء العملاء صيغة Markdown من /api/v1/misc/ocr-pdf لا طبقة نصية مخفية. وهذه الحقيقة جزء من العقد المشترك: فتغيير نوع الإرجاع في عميل واحد دون البقية يكسر وعد «العملية نفسها». ويبقى الضغط على /api/v1/misc/compress-pdf لإعادة ضغط التدفقات، وهو عملية مختلفة عن الدمج يمكن الوصول إليها بالطرق الأربع نفسها.
لماذا يهم هذا التماثل
لو تباعد دمج المتصفح عن دمج API يوماً، لتراجعت الأتمتة صامتةً بينما تبدو صفحة العرض سليمة. فعملية واحدة بأربعة مقابض هي المقصد. والبوابة عميل مريح، لا تنفيذ ثانٍ للدمج أو الضغط أو OCR.
ولهذا أيضاً لا توجد نسخة مكتبية متفرّعة: فشجرة واجهة خامسة تعيد إنتاج مشكلة الانحراف باسم ملف تنفيذي آخر. ولإطار أوسع، راجع مبنيّ للوكلاء لا للمتصفحات فقط. ولقرار سطح المكتب، راجع لماذا تخطّينا تطبيق سطح المكتب. ولإقامة API على شبكتك، راجع الاستضافة الذاتية.