مبنيّ للوكلاء لا للمتصفحات فقط: كيف تعمل الواجهة البرمجية

لا يزال بإمكانك العمل من لسان المتصفح: تختار أداة، وترفع ملفاً، وتنزّل النتيجة. أما الوكلاء والسكربتات فيستدعون العمليات ذاتها من دون فتح أي واجهة. وكلا المسارين يصل إلى الكتالوج نفسه.

كل صفحة أداة هي أيضاً نقطة نهاية

دمج والتقسيم والضغط وOCR والتحويل: لكل أداة في الكتالوج مسار تحت /api/v1/…. افتح صفحة أي أداة وامرر إلى Call this from code لترى مثال curl مبنيّاً من معاملات تلك الأداة الحقيقية، لا قالباً عاماً. ولا تحتاج الاستدعاءات المجهولة إلى حساب ولا إلى مفتاح API على الموقع العام؛ وبادئات المسارات المجهولة هي /api/v1/general/ و/api/v1/misc/ و/api/v1/security/ و/api/v1/convert/ و/api/v1/filter/.

مثال الدمج ملموس:

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 حين يجب ألا تُعاد مهمة مُعدِّلة عند إعادة المحاولة. وتُعلن الردود المستضافة ترويسات X-RateLimit-Limit وX-RateLimit-Remaining وX-RateLimit-Reset وعند استجابة HTTP 429 اقرأ Retry-After (تحديد معدل الطلبات المجهولة).

ويعيد OCR عبر الكتالوج نفسه صيغة Markdown (text/markdown) من /api/v1/misc/ocr-pdf لا ملف PDF بطبقة نصية مخفية. والوكيل الذي يتوقع ملفاً قابلاً للبحث من هذه النقطة سيخطئ في التعامل مع التنزيل؛ فالعقد هنا استخراج نص لخطوط المعالجة، لا إعادة كتابة بأسلوب OCRmyPDF.

MCP للعملاء الذين يتحدثون به

يتيح MCP (بروتوكول سياق النموذج) لعملاء الوكلاء استكشاف الأدوات واستدعاءها كدوال، بدل كشط التوثيق. ويعرض هذا الموقع خادم MCP عند /mcp إلى جانب واجهة REST، فيتصل العميل المتوافق مرة واحدة ويحصل على الكتالوج كاملاً.

ويشترك MCP وREST في توقعات المصادقة نفسها: استدعاء مجهول حيث تسمح بادئات الأدوات، ومفاتيح API للأتمتة المستقرة وللخوادم ذاتية الاستضافة المقيّدة. وتوجيه وكيل إلى /mcp ليس منتجاً مختلفاً عن توجيه curl إلى /api/v1/…. التوثيق: MCP للمطوّرين.

الأخطاء منظّمة لا نصوص حرّة

تعيد الأعطال application/problem+json (بأسلوب RFC 7807)، لا استجابة 500 عارية ولا «حدث خطأ ما». ويحمل كل رد رمزاً مستقراً، مثل rate_limited وbad_request وinvalid_document وmissing_dependency ونظائرها، وتلميحاً مقروءاً، وخطوة تالية في كثير من الحالات. يستطيع الإنسان تصفّحه، ويستطيع الوكيل أن يقرر إعادة المحاولة أو تبديل الملف أو التوقف من دون أن يحلل أحدهم أثر المكدس.

ويتجاوز هذا البناء فائدة صفحة خطأ HTML الودودة حين يكون المستدعي سكربتاً. المرجع: أخطاء المطوّرين.

llms.txt لأدوات البرمجة لا للترتيب

/llms.txt فهرس نصي بسيط لكل أداة (الاسم، والوصف، والرابط)، مولّد من الكتالوج ذاته الذي يقود الموقع. يستطيع وكلاء البرمجة وأدوات التوثيق قراءته كما يقرأون ملف README. وهو ليس رافعة ترتيب في Google: يتجاهل البحث /llms.txt (المصادر: دليل Google لتحسين البحث بالذكاء الاصطناعي). ولأنه مولّد، لا يمكن أن يتقادم صامتاً كما يتقادم ملف يُحرَّر يدوياً.

CLI والمهارة يتشاركان الأشكال نفسها

يستطيع pdfx تشغيل pdf-core محلياً أو --cloud مقابل عنوان أساسي. وتوثّق مهارة وكيل البرمجة تحت dist/skills/pdf-toolbox/SKILL.md أشكال curl للدمج وخطوط المعالجة، كي لا يخترع الوكلاء عقداً ثانياً. أربعة عملاء وكتالوج واحد: العملية نفسها، أربعة عملاء.

مسار المتصفح لم يتغير

ما زال إسقاط ملف في لسان المتصفح يعمل كما هو. والسطح الإضافي هو نقاط النهاية ذاتها لوكيل أو سكربت أو CI: المعالجة نفسها، بلا إنسان في المنتصف. وتحتفظ الاستضافة الذاتية بهذا السطح داخل شبكتك (الاستضافة الذاتية)، وتبقى الاستضافة العامة مسار التجربة المجهولة.

مرجع الواجهة البرمجية: Swagger. ولأساسيات أي من المسارين: المساعدة والمطوّرون.