تكامل NextPDF Connect

نظرة سريعة

ادمج ⁨NextPDF Connect⁩ عبر تشغيله كخادم. لا توصّل مكتبة داخل تطبيق مضيف. اختر وسيلة النقل، ثم اضبط المصادقة لكل وسيلة نقل شبكية. تبقى أدوات المحرك خلف بوابة التأكيد.

التثبيت

composer require nextpdf/server

قيد ⁨Composer⁩ هو nextpdf/core: ^3.0 مع php: >=8.4 <9.0. لإعداد ext-redis وnextpdf/premium الاختياريين، راجع /⁨connect/install/.⁩

نظرة مفاهيمية عامة

تعمل الحزمة كخدمة مستقلة. لا تسجّل مزوّد خدمة أو حزمة (⁨bundle⁩) أو وحدة حاوية في إطار عمل مضيف. نقطة التكامل هي العملية التي تشغّلها. لكل وسيلة نقل نقطة دخول خاصة بها، وتبدأ بشكل مستقل. راجع /⁨connect/boot-and-discovery/.⁩

سطح ⁨API⁩

نقطة الدخول	وسيلة النقل	الملف التعريفي
bin/nextpdf-mcp	⁨MCP⁩ عبر ⁨stdio⁩	(لا شيء — عملية فرعية مباشرة)
bin/nextpdf-server	⁨REST⁩ عبر ⁨RoadRunner HTTP⁩	.rr.yaml
bin/nextpdf-grpc	⁨gRPC⁩ عبر ⁨RoadRunner gRPC⁩	.rr.grpc.yaml
كلتا وسيلتي النقل الشبكيتين	⁨REST⁩ + ⁨gRPC⁩	.rr.full.yaml

الإقلاع والاكتشاف التلقائي

يكتشف السجل الطبقة الأساسية دائمًا. ثم يضيف مزوّدي ⁨Pro⁩ و⁨Enterprise⁩ عندما يمكن حلّ أصنافهم، ثم مزوّدَي شجرة الصياغة المجردة (⁨AST⁩) والطفرات المُضمَّنَين خلف بوابات بيئية. تُرشِّح قائمة السماح الأمنية enabled_tools كل ذلك، لذلك يكون الفهرس المكشوف خاصًا بهذا النشر. راجع /⁨connect/tool-catalog/⁩ و/⁨connect/boot-and-discovery/.⁩

ارتباطات الحاوية

لا شيء. يبني كل مصنع خادم رسمه الكائني الخاص به صراحةً. تدعم المنافذ القابلة للحقن الاختبارات، وليس توصيل التطبيق.

نشر الإعدادات

يقبل خادم ⁨MCP⁩ ملف ⁨YAML⁩ اختياريًا (--config=PATH، القسم nextpdf_mcp) وتجاوزات البيئة NEXTPDF_MCP_*. يقرأ خادما ⁨REST⁩ و⁨gRPC⁩ متغيرات البيئة NEXTPDF_*. لمزيد من التفاصيل، راجع /⁨connect/configuration/.⁩

توفّر وسائل النقل (⁨MCP⁩ / ⁨REST⁩ / ⁨gRPC⁩)

تخدم وسائل النقل الثلاث كلها السجل نفسه:

• ⁨MCP⁩ — عملية فرعية محلية، ⁨JSON-RPC 2.0⁩ عبر ⁨stdio⁩، بدون مفتاح ⁨API⁩، مراجعة ⁨MCP⁩ 2025-06-18. راجع /⁨transports/mcp/.⁩
• ⁨REST⁩ — تجمّع عمّال ⁨RoadRunner HTTP⁩، عقد ⁨OpenAPI 3.1⁩، مفتاح ⁨API⁩ حامل، مسارات محجوبة حسب الطبقة. راجع /⁨transports/rest/.⁩
• ⁨gRPC⁩ — تجمّع عمّال ⁨RoadRunner gRPC⁩، خدمة ⁨Protobuf⁩ nextpdf.connect.v1، استدعاءات ⁨RPC⁩ بتدفّق من الخادم، مصادقة بحامل في البيانات الوصفية، ⁨TLS⁩ متبادل في الملف التعريفي المُجمَّع. راجع /⁨transports/grpc/.⁩

تُعد وسيلة النقل “متوفرة” عندما تكون نقطة دخولها أو ملف ⁨RoadRunner⁩ التعريفي قيد التشغيل. لا تشغّل وسائل النقل بعضها بعضًا تلقائيًا.

طبقة مخاطر ⁨HITL⁩

تعلن كل أداة عن أحد أربعة مستويات للمخاطر: ⁨safe⁩ و⁨caution⁩ و⁨review⁩ و⁨approval_required.⁩ الأدوات المصنفة approval_required لا تعمل عند الاستدعاء الأول. تُصدر بوابة التأكيد رمز تحدٍّ للاستخدام مرة واحدة يجب أن يصرّح به إنسان. لا يجوز لتجاوزات الإعدادات إلا أن ترفع مستوى مخاطر الأداة، ولا تخفّض أبدًا أداة approval_required. يُطبَّق النموذج بالطريقة نفسها على كل وسيلة نقل تشغّل الأدوات. راجع /⁨connect/hitl-risk-tiers/.⁩

غلاف ⁨JSON⁩ لبوابة التأكيد

يُرجِع فحص البوابة أحد شكلَي ⁨JSON.⁩ مسموح:

{ "allowed": true }

تحدٍّ:

{
  "allowed": false,
  "challenge": "<human-readable text naming the operation, its description, an overwrite warning when applicable, and the re-invocation instruction>",
  "token": "confirm_<nonce>"
}

يربط الرمز اسم الأداة، وقيمة عشوائية لمرة واحدة (⁨nonce⁩)، ومدة بقاء (⁨TTL⁩) قدرها 300 ثانية، وليس الوسائط. للمتابعة، يستدعي المُستدعي الأداة نفسها مرة أخرى مع وسيط _confirmation_token مضبوط على الرمز الصادر. التحدي نص إرشادي بسيط يتضمن الرمز؛ وليس غلافًا موقّعًا تشفيريًا. راجع /⁨connect/hitl-risk-tiers/.⁩

اختبار تدخين للخدمة

./vendor/bin/generate-skills --dry-run --list-tools

يشغّل هذا الأمر السجل واكتشاف الطبقات، ثم يطبع الأدوات المكشوفة دون خدمة أي حركة مرور. استخدمه للتأكد من أن التكامل موصول وللتحقق من الفهرس الذي ينتجه هذا التثبيت.

الحالات الحدّية والمزالق

• لا توجد خطافات لإطار العمل. لا تبحث عن مزوّد خدمة أو حزمة (⁨bundle⁩). العملية قيد التشغيل هي التكامل.
• الطبقة المفقودة ليست خطأً. يبدأ التثبيت الأساسي وحده ويخدم فهرسه الأساسي.
• تتطلب وسائل النقل الشبكية مفتاحًا. فقط /healthz و/readyz (⁨REST⁩) واستدعاءات ⁨RPC⁩ الصحية (⁨gRPC⁩) تكون مجهولة.

الأداء

تكلفة الإقلاع هي فحص السجل واكتشاف الطبقات مرة واحدة لكل عملية. أما تكلفة كل طلب فهي عملية المحرك. حدّد حجم تجمّعات عمّال ⁨RoadRunner⁩ بناءً على زمن التصيير المُلاحَظ. راجع /⁨connect/production-usage/.⁩

ملاحظات أمنية

تعتمد وسائل النقل الشبكية المصادقة بمفتاح حامل npk_live_ يُتحقَّق منه في زمن ثابت؛ وتفرض البوابة تأكيدًا بشريًا للعمليات المدمِّرة بصرف النظر عن وسيلة النقل. أنهِ ⁨TLS⁩ أمام ⁨REST⁩، واستخدم ⁨TLS⁩ متبادلًا لـ ⁨gRPC⁩ على الشبكات غير الموثوقة. راجع /⁨connect/security-and-operations/.⁩

المطابقة

استشهادات البروتوكول والأمن مثبّتة في /⁨transports/mcp/⁩ و/⁨transports/rest/⁩ و/⁨transports/grpc/⁩ و/⁨connect/security-and-operations/.⁩

السياق التجاري

ثبّت nextpdf/premium إلى جانب الخادم لتسجيل أدوات ⁨Pro⁩ و⁨Enterprise⁩ الإضافية في الخادم قيد التشغيل نفسه. لا تشارك أي عملية منفصلة في ذلك.

انظر أيضًا

• /⁨connect/overview/⁩ — البنية المعمارية
• /⁨connect/quickstart/⁩ — أول تبادل قابل للتشغيل
• /⁨transports/mcp/⁩ · /⁨transports/rest/⁩ · /⁨transports/grpc/⁩ — مرجع لكل وسيلة نقل
• /⁨connect/hitl-risk-tiers/⁩ — بوابة التأكيد بالتفصيل
• /⁨connect/tool-catalog/⁩ — الفهرس المعتمِد على زمن التشغيل
• /⁨connect/security-and-operations/⁩ — المصادقة ونموذج التهديد