مرجع API في NextPDF Connect

نظرة سريعة

توفّر هذه الصفحة مرجعًا للرموز في خادم ⁨NextPDF Connect⁩ (nextpdf/server). وهي تسرد كل أداة باسمها المسجَّل وفئتها المنفِّذة، وتوثِّق خدمة ⁨gRPC⁩ المسماة NextPDFConnect، بما في ذلك طرائق استدعاء الإجراءات البعيدة (⁨RPC⁩) ورسائل الطلب والاستجابة. كما تحدِّد عقود المصادقة والأخطاء وحدود المعدل المشتركة بين جميع وسائط النقل.

يعرض الخادم سجلَّ أدوات واحدًا عبر ثلاث وسائط نقل: بروتوكول سياق النموذج (⁨MCP⁩) عبر الإدخال والإخراج القياسيَّين، وواجهة ⁨API⁩ بنمط ⁨REST⁩، و⁨gRPC.⁩ توثِّق كل وسيلة نقل تفاصيلها على مستوى السلك في صفحة مستقلة: راجع وسيلة نقل ⁨MCP⁩، ووسيلة نقل ⁨REST⁩، ووسيلة نقل ⁨gRPC⁩. وتفهرس هذه الصفحة الرموز التي تحملها تلك الوسائط.

تأتي أسماء الأدوات وفئاتها ومستويات مخاطرتها من تطبيقات الأدوات في src/Tools/. ويعتمد عدد الأدوات التي يعرضها أي نشر على وقت التشغيل؛ راجع فهرس الأدوات. يشرح الإقلاع والاكتشاف آلية تحديد المستوى.

توفُّر وسائط النقل

تتوفر الأدوات عبر كل وسيلة نقل يُشغِّلها النشر. وتعمل وسائط النقل كعمليات مستقلة؛ فبدء إحداها لا يبدأ الوسائط الأخرى.

وسيلة النقل	نقطة الدخول	تنسيق السلك	المصادقة
⁨MCP⁩	`bin/nextpdf-mcp`	استدعاء الإجراءات البعيدة بترميز كائنات ⁨JavaScript⁩ (⁨JSON-RPC⁩) 2.0 عبر ⁨stdio⁩	حد عملية نظام التشغيل (لا مفتاح ⁨API⁩)
⁨REST⁩	`bin/nextpdf-server`	⁨HTTP⁩ و⁨OpenAPI 3.1⁩	مفتاح ⁨API⁩ من نوع ⁨Bearer⁩ في ترويسة `Authorization`
⁨gRPC⁩	`bin/nextpdf-grpc`	⁨Protocol Buffers⁩، الحزمة `nextpdf.connect.v1`	رمز ⁨Bearer⁩ في البيانات الوصفية للاستدعاء `authorization`

عبر ⁨MCP⁩، استدعِ الأداة باستخدام tools/call واسم الأداة المسجَّل. وعبر ⁨REST⁩ و⁨gRPC⁩، تصل إلى قدرات المحرك نفسها من خلال أسطح العرض والعمليات والقدرات؛ راجع جدول المسارات في وسيلة نقل ⁨REST⁩ وجدول ⁨RPC⁩ في وسيلة نقل ⁨gRPC⁩.

المصادقة ومستوى المخاطرة

المصادقة بمفتاح ⁨API⁩

تتطلب وسيلتا نقل ⁨REST⁩ و⁨gRPC⁩ مفتاح ⁨API⁩ من نوع ⁨Bearer⁩ في كل طلب، باستثناء فحوص السلامة غير المُصادَق عليها. تكون صيغة المفتاح npk_live_{kid}_{secret}: يمثّل kid معرِّفًا من ثمانية أحرف للبحث عن السجل، بينما يحمل الجزء السري قيمة عشوائية. يخزِّن الخادم بصمة ⁨SHA-256⁩ للمفتاح فقط، ويقارن الرمز المقدَّم في زمن ثابت، فلا يكشف المفتاح غير الصالح أي معلومات عبر التوقيت. يقرأ ⁨REST⁩ الرمز من ترويسة Authorization: Bearer …، بينما يقرأ ⁨gRPC⁩ الرمز نفسه من البيانات الوصفية للاستدعاء authorization. ولا تستخدم وسيلة نقل ⁨MCP⁩ عبر ⁨stdio⁩ مفتاح ⁨API⁩ لأنها عملية فرعية محلية يثق بها العميل الذي يُطلقها. يوثِّق الأمان والعمليات نموذج المصادقة الكامل.

مستويات المخاطرة الأربعة

تُعلِن كل أداة أحد مستويات المخاطرة الأربعة المرتَّبة، والمُعرَّفة بواسطة تعداد RiskLevel في src/Config/RiskLevel.php.

المستوى	حالة التعداد	القيمة	الأثر
آمن	`RiskLevel::Safe`	0	للقراءة فقط، دون آثار جانبية. يُنفَّذ تلقائيًا.
احتراز	`RiskLevel::Caution`	1	ينشئ حالةً في الذاكرة أو يعدِّلها. يُنفَّذ تلقائيًا، مع تسجيله في سجل التدقيق.
مراجعة	`RiskLevel::Review`	2	يُنتِج مخرجات قد يُساء استخدامها. يُنفَّذ تلقائيًا، مع تسجيله في سجل التدقيق.
⁨ApprovalRequired⁩	`RiskLevel::ApprovalRequired`	3	مُدمِّر أو قانوني أو حسَّاس للخصوصية. يتطلب تأكيدًا بشريًا.

يُستمد مستوى المخاطرة الفعلي للأداة من موضعين فقط: إعلان الأداة ذاتها riskLevel()، وتجاوز اختياري في إعداد المُشغِّل لا يُسمح له إلا برفع المخاطرة، ولا يجوز له أبدًا خفض أداة ApprovalRequired. راجع مستويات المخاطرة بإشراف بشري (⁨HITL⁩) والإعداد.

كيف تنتقل رموز الموافقة

عند استدعاء أداة ApprovalRequired دون رمز صالح، تُعيد ConfirmationGate (src/Mcp/ConfirmationGate.php) رمز تحدٍّ يُستخدم مرة واحدة بدلًا من تشغيل الأداة. يُمرِّر الوكيل التحدي إلى إنسان، ثم يعيد استدعاء الأداة نفسها مع الرمز الصادر في الوسيط _confirmation_token. يربط الرمز اسم الأداة، وقيمة عشوائية تُستخدم مرة واحدة (⁨nonce⁩)، ومدة بقاء قدرها 300 ثانية (⁨TTL⁩). لا يربط الرمز الوسائط، ولا يُعد بيانات اعتماد للمصادقة. في ⁨REST⁩، يظل مفتاح ⁨API⁩ من نوع ⁨Bearer⁩ مسؤولًا عن مصادقة الطلب، وتعمل البوابة نفسها في مُنفِّذ الأدوات المشترك قبل العملية الخاضعة للبوابة. وفي ⁨gRPC⁩، تعمل البوابة نفسها قبل العملية المُرسَلة. آلية التحدي والرمز متطابقة عبر جميع وسائط النقل.

الأدوات ونقاط النهاية

يوثِّق الجدول كل أداة باسمها المسجَّل (عمود الرمز) وفئتها المنفِّذة. تُجمَّع الأدوات حسب المستوى والفئة. تقع جميع فئات شجرة التركيب المجردة (⁨AST⁩) والتعديل ضمن src/Tools/Ast وsrc/Tools/Ast/Mutation؛ وتقع فئات الاستخراج ضمن src/Tools/Extraction؛ أما الفئات المتبقية فتقع ضمن src/Tools/Core.

أدوات المستندات الأساسية

الرمز	المُعامِلات	السلوك الافتراضي	يُعيد	يطرح استثناءً أو يفشل بـ	ملاحظات
`create_pdf`	`page_size` (افتراضيًا `A4`)، `orientation` (`portrait`/`landscape`)، `title`، `author`؛ لا شيء مطلوب.	ينشئ مستندًا في الذاكرة من صفحة واحدة، ويضبط البيانات الوصفية عند توفيرها.	⁨JSON⁩ يحتوي على `document_id`، `page_count`، `page_size`، `orientation`.	يُعيد نتيجة خطأ مع رسالة المحرك عند الفشل.	الفئة `CreatePdfTool`. المخاطرة `RiskLevel::Caution`. المستوى الأساسي. يُستخدم `document_id` المُعاد في كل عملية لاحقة.
`add_page`	`document_id` (مطلوب)، وحجم الصفحة واتجاهها اختياريان.	يُلحِق صفحةً بالمستند.	⁨JSON⁩ يحتوي على عدد الصفحات الجديد.	نتيجة خطأ عندما يكون `document_id` غير معروف.	الفئة `AddPageTool`. المخاطرة `RiskLevel::Caution`. المستوى الأساسي.
`add_text`	`document_id` (مطلوب)، `text` (مطلوب)، والموضع والنمط اختياريان.	يضيف نصًا إلى المستند.	⁨JSON⁩ بملخص حالة المستند.	نتيجة خطأ عندما يكون `document_id` غير معروف.	الفئة `AddTextTool`. المخاطرة `RiskLevel::Caution`. المستوى الأساسي.
`add_image`	`document_id` (مطلوب)، `source` (مطلوب: مسار ملف أو ⁨base64⁩)، والموضع اختياري.	يضيف صورةً من مسار أو من بيانات ⁨base64.⁩	⁨JSON⁩ بملخص حالة المستند.	نتيجة خطأ عند تعذُّر قراءة المصدر أو عندما يكون `document_id` غير معروف.	الفئة `AddImageTool`. المخاطرة `RiskLevel::Caution`. المستوى الأساسي.
`add_table`	`document_id` (مطلوب)، `html` (مطلوب).	يعرض جدول ⁨HTML⁩ داخل المستند.	⁨JSON⁩ بملخص حالة المستند.	نتيجة خطأ عند وجود ترميز غير صالح أو عندما يكون `document_id` غير معروف.	الفئة `AddTableTool`. المخاطرة `RiskLevel::Caution`. المستوى الأساسي.
`set_font`	`document_id` (مطلوب)، `family` (مطلوب)، والحجم والنمط اختياريان.	يضبط الخط لعمليات النص اللاحقة.	⁨JSON⁩ بتأكيد الخط النشط.	نتيجة خطأ عند وجود خط غير معروف أو عندما يكون `document_id` غير معروف.	الفئة `SetFontTool`. المخاطرة `RiskLevel::Caution`. المستوى الأساسي.
`output_pdf`	`document_id` (مطلوب)، `file_path` (اختياري)، `destroy` (افتراضيًا `true`).	يُنهي المستند ويكتب إلى `file_path`، أو يُعيد ⁨base64⁩ عند عدم توفيره، ويُتلف المستند افتراضيًا.	⁨JSON⁩ يحتوي على `file_path` و`file_size`، أو `base64` و`file_size`.	نتيجة خطأ عندما يكون `document_id` غير معروف؛ وفشل احتواء المسار عند الكتابة خارج الدليل الأساسي.	الفئة `OutputPdfTool`. المخاطرة `RiskLevel::ApprovalRequired`. المستوى الأساسي. تمر كتابة الملف عبر بوابة التأكيد؛ أما وضع ⁨base64⁩ فلا يمر بها.
`preview_layout`	`document_id` (مطلوب).	يُعيد ملخص التخطيط دون عرض ملف ⁨PDF⁩ النهائي.	⁨JSON⁩ بملخص التخطيط.	نتيجة خطأ عندما يكون `document_id` غير معروف.	الفئة `PreviewLayoutTool`. المخاطرة `RiskLevel::Safe`. المستوى الأساسي.
`parse_pdf`	`document_id` (مطلوب).	يفحص البيانات الوصفية البنيوية: عدد الصفحات، والخطوط، والصور، والتشفير، وقاموس المعلومات (⁨Info Dictionary⁩).	⁨JSON⁩ بالبيانات الوصفية البنيوية.	نتيجة خطأ عند وجود مستند مشوَّه.	الفئة `ParsePdfTool`. المخاطرة `RiskLevel::Safe`. المستوى الأساسي. لا يُسجَّل إلا عندما تكون قيمة `NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED` هي `true` أو `1`.

أدوات التشخيص الأساسية

الرمز	المُعامِلات	السلوك الافتراضي	يُعيد	يطرح استثناءً أو يفشل بـ	ملاحظات
`diagnostic.doctor`	لا شيء.	يُجري فحص سلامة، ويُعيد تشخيصات منظَّمة للبيئة.	⁨JSON⁩ بتقرير البيئة.	نتيجة خطأ عند فشل فحص داخلي.	الفئة `DiagnosticDoctorTool`. المخاطرة `RiskLevel::Safe`. المستوى الأساسي. لا يتطلب مستندًا ولا تأكيدًا.
`diagnostic.capabilities`	لا شيء.	يسرد القدرات مع معلومات المستوى والحالة.	⁨JSON⁩ بقائمة القدرات.	نتيجة خطأ عند فشل داخلي.	الفئة `DiagnosticCapabilitiesTool`. المخاطرة `RiskLevel::Safe`. المستوى الأساسي.
`diagnostic.inspect`	`document_id` (مطلوب).	يفحص ملف ⁨PDF⁩ ويُعيد بيانات وصفية بنيوية.	⁨JSON⁩ بالبيانات الوصفية البنيوية.	نتيجة خطأ عندما يكون `document_id` غير معروف.	الفئة `DiagnosticInspectTool`. المخاطرة `RiskLevel::Safe`. المستوى الأساسي.
`diagnostic.verify`	`document_id` (مطلوب)، وملف تعريف ⁨PDF/A⁩ أو ⁨PDF/UA⁩ اختياري.	يتحقق من السلامة البنيوية؛ ويتحقق اختياريًا من ⁨PDF/A⁩ أو ⁨PDF/UA⁩ عبر إطلاق عملية فرعية من ⁨VeraPDF.⁩	⁨JSON⁩ بتقرير التحقق.	نتيجة خطأ عند فشل العملية الفرعية أو انتهاء المهلة أو تجاوز حجم الإدخال الحد المسموح.	الفئة `DiagnosticVerifyTool`. المخاطرة `RiskLevel::Caution`. المستوى الأساسي. الإدخال محدود بسقف قدره 50 ميبي‑بايت (⁨MiB⁩).

أداة الباركود الأساسية

الرمز	المُعامِلات	السلوك الافتراضي	يُعيد	يطرح استثناءً أو يفشل بـ	ملاحظات
`generate_barcode`	`payload` (مطلوب)، `format` (على سبيل المثال ⁨QR Code⁩ و⁨DataMatrix⁩).	يُولِّد مصفوفة وحدات باركود ثنائية الأبعاد للحمولة.	⁨JSON⁩ بمصفوفة الوحدات.	نتيجة خطأ عند وجود `format` غير مدعوم أو حمولة غير صالحة.	الفئة `BarcodeTool`. المخاطرة `RiskLevel::Caution`. المستوى الأساسي. لا يُسجَّل `BarcodeTool` إلا عند وجود سجل مُرمِّز `barcode` الأساسي في `nextpdf/core` المثبَّت؛ واسم الأداة المسجَّل هو `generate_barcode`.

أدوات الخصوصية في ⁨Enterprise⁩

تغلِّف هذه الأدوات فئات الخصوصية في ⁨Enterprise⁩، ولا تُسجَّل ضمن مستوى ⁨Enterprise⁩ إلا عندما تكون تلك الفئات قابلة للتحميل التلقائي. تعمل هذه الأدوات على محتوى نصي صِرف.

الرمز	المُعامِلات	السلوك الافتراضي	يُعيد	يطرح استثناءً أو يفشل بـ	ملاحظات
`redact_pdf`	`content` (مطلوب)، وخيارات الكشف اختيارية.	يحجب المعلومات الشخصية المُعرِّفة (⁨PII⁩) في المحتوى النصي الصِّرف حجبًا إتلافيًا باستخدام محرك الحجب في ⁨Enterprise.⁩	⁨JSON⁩ يحتوي على المحتوى المحجوب وبصمة ⁨SHA-256.⁩	نتيجة خطأ عند غياب فئات ⁨Enterprise⁩ أو فشل الكشف.	الفئة `RedactPdfTool`. المخاطرة `RiskLevel::Review`. المستوى ⁨Enterprise.⁩
`deidentify_pdf`	`content` (مطلوب)، `strategy` (حجب أو كبت).	يطبِّق استراتيجية منهجية لإزالة الهوية على المحتوى النصي الصِّرف باستخدام مزيل الهوية في ⁨Enterprise.⁩	⁨JSON⁩ يحتوي على المحتوى بعد إزالة الهوية.	نتيجة خطأ عند غياب فئات ⁨Enterprise.⁩	الفئة `DeIdentifyPdfTool`. المخاطرة `RiskLevel::Review`. المستوى ⁨Enterprise.⁩
`zone_redact_pdf`	`content` (مطلوب)، `zones` (صفحة مع قائمة مستطيلات مُطبَّعة).	يطبِّق حجبًا قائمًا على المناطق والإحداثيات باستخدام محرك الحجب في ⁨Enterprise.⁩	⁨JSON⁩ يحتوي على المحتوى المحجوب.	نتيجة خطأ عند وجود منطقة غير صالحة أو غياب فئات ⁨Enterprise.⁩	الفئة `ZoneRedactionTool`. المخاطرة `RiskLevel::Review`. المستوى ⁨Enterprise.⁩

أدوات قراءة شجرة التركيب المجردة (⁨AST⁩)

تُشحَن هذه الأدوات مع الخادم، وتُسجَّل ضمن مستوى ⁨Pro⁩، وتُحجَب بواسطة NEXTPDF_AST_TOOLS_ENABLED (مُفعَّل افتراضيًا). وهي مخصَّصة للقراءة فقط.

الرمز	المُعامِلات	السلوك الافتراضي	يُعيد	يطرح استثناءً أو يفشل بـ	ملاحظات
`get_document_ast`	`pdf_data` (مطلوب).	يبني شجرة ⁨AST⁩ دلالية: شجرة عُقد كاملة مع مراسي استشهاد لكل عنصر بنيوي.	⁨JSON⁩ بشجرة عُقد إضافةً إلى ⁨ETag⁩ للتحكم في التزامن.	نتيجة خطأ عند وجود مستند مشوَّه.	الفئة `GetDocumentAstTool`. المخاطرة `RiskLevel::Safe`. المستوى ⁨Pro.⁩
`get_ast_node`	`pdf_data` (مطلوب)، `node_id` (مطلوب).	يجلب عقدة ⁨AST⁩ واحدة وجميع أبنائها.	⁨JSON⁩ بعقدة مع أبنائها.	نتيجة خطأ عندما يكون `node_id` غير معروف.	الفئة `GetAstNodeTool`. المخاطرة `RiskLevel::Safe`. المستوى ⁨Pro.⁩
`get_ast_diff`	`original_pdf_data` (مطلوب)، `modified_pdf_data` (مطلوب).	يقارن مستندين بنيويًا بمقارنة شجرتَي ⁨AST⁩ الدلاليتين لهما.	⁨JSON⁩ بالعُقد المُضافة والمحذوفة والمتغيِّرة.	نتيجة خطأ عند وجود مستند إدخال مشوَّه.	الفئة `GetAstDiffTool`. المخاطرة `RiskLevel::Safe`. المستوى ⁨Pro.⁩
`search_ast_nodes`	`pdf_data` (مطلوب)، ومُرشِّحات النوع وفهرس الصفحة والنص اختيارية.	يبحث في عُقد ⁨AST⁩ حسب النوع أو فهرس الصفحة أو محتوى النص.	⁨JSON⁩ بقائمة مسطَّحة من العُقد المطابقة مع أبناء سطحيِّين.	نتيجة خطأ عند وجود مستند مشوَّه.	الفئة `SearchAstNodesTool`. المخاطرة `RiskLevel::Safe`. المستوى ⁨Pro.⁩
`extract_cited_text`	`pdf_data` (مطلوب)، اختياري `headings_only`.	يستخرج كتل النص مع مراسي الاستشهاد (الصفحة، والمربع المحيط، ودرجة الثقة).	⁨JSON⁩ بكتل نص مُستشهَد بها.	نتيجة خطأ عند وجود مستند مشوَّه.	الفئة `ExtractCitedTextTool`. المخاطرة `RiskLevel::Safe`. المستوى ⁨Pro.⁩ الفئة `ast`.
`extract_cited_tables`	`pdf_data` (مطلوب).	يستخرج كتل الجداول مع مراسي الاستشهاد؛ ويُعيد مصفوفة خلايا مرتَّبة حسب الصفوف لكل عقدة ⁨Table.⁩	⁨JSON⁩ بمصفوفات جداول مع مراسيها.	نتيجة خطأ عند وجود مستند مشوَّه.	الفئة `ExtractCitedTablesTool`. المخاطرة `RiskLevel::Safe`. المستوى ⁨Pro.⁩ الفئة `extraction`.

أدوات تعديل ⁨AST⁩

تُشحَن هذه الأدوات مع الخادم، وتُسجَّل ضمن مستوى ⁨Pro⁩، وتُحجَب بواسطة NEXTPDF_MUTATION_TOOLS_ENABLED (مُفعَّل افتراضيًا). الأدوات الأربع كلها ApprovalRequired وتستخدم التحكم المتفائل في التزامن (⁨OCC⁩) عبر ⁨ETag.⁩

الرمز	المُعامِلات	السلوك الافتراضي	يُعيد	يطرح استثناءً أو يفشل بـ	ملاحظات
`apply_ast_mutations`	`pdf_data`، `etag`، `idempotency_key`، `mutations` (كلها مطلوبة).	يطبِّق دفعةً من التعديلات بصورة ذرّية؛ ويعيد تشغيل النتيجة المخزَّنة مؤقتًا عند تكرار `idempotency_key`.	⁨JSON⁩ يحتوي على ملف ⁨PDF⁩ المعدَّل و⁨ETag⁩ جديد.	تعارض ⁨OCC⁩ عندما يكون ⁨ETag⁩ قديمًا؛ وخطأ تحقق عند وجود تعديل مشوَّه.	الفئة `ApplyAstMutationsTool`. المخاطرة `RiskLevel::ApprovalRequired`. المستوى ⁨Pro.⁩
`delete_ast_node`	`pdf_data`، `node_id`، `etag` (كلها مطلوبة).	يزيل عقدة في وضع التراكب (يُغطَّى المحتوى الأصلي ولا يُحذف فعليًا).	⁨JSON⁩ يحتوي على ملف ⁨PDF⁩ المعدَّل و⁨ETag⁩ جديد.	تعارض ⁨OCC⁩ عندما يكون ⁨ETag⁩ قديمًا؛ وخطأ عندما يكون `node_id` غير معروف.	الفئة `DeleteAstNodeTool`. المخاطرة `RiskLevel::ApprovalRequired`. المستوى ⁨Pro.⁩
`insert_ast_node`	`pdf_data`، `parent_node_id`، `position`، `etag`، `node` (كلها مطلوبة).	يُدرِج عقدةً جديدة ابنًا للعقدة الأم في الموضع المحدَّد.	⁨JSON⁩ يحتوي على ملف ⁨PDF⁩ المعدَّل و⁨ETag⁩ جديد.	تعارض ⁨OCC⁩ عندما يكون ⁨ETag⁩ قديمًا؛ وخطأ تحقق عند وجود عقدة مشوَّهة.	الفئة `InsertAstNodeTool`. المخاطرة `RiskLevel::ApprovalRequired`. المستوى ⁨Pro.⁩
`update_ast_node`	`pdf_data`، `node_id`، `etag`، `updates` (كلها مطلوبة).	يحدِّث المحتوى النصي لعقدة.	⁨JSON⁩ يحتوي على ملف ⁨PDF⁩ المعدَّل و⁨ETag⁩ جديد.	تعارض ⁨OCC⁩ عندما يكون ⁨ETag⁩ قديمًا؛ وخطأ عندما يكون `node_id` غير معروف.	الفئة `UpdateAstNodeTool`. المخاطرة `RiskLevel::ApprovalRequired`. المستوى ⁨Pro.⁩

مخطط الطلب والاستجابة

تُعرِّف وسيلة نقل ⁨gRPC⁩ مخطط الخادم المُنمَّط في حزمة ⁨Protocol Buffers⁩ المسماة nextpdf.connect.v1، في proto/nextpdf/connect/v1/*.proto. وتمثل الخدمة ورسائلها رموز المخطط المرجعية.

الخدمة `NextPDFConnect`

تكشف الخدمة NextPDFConnect استدعاءات ⁨RPC⁩ أحادية وبثًّا من الخادم. وتتمثل رموز المخطط في أسماء طرائق ⁨RPC⁩ ورسائل الطلب والاستجابة التي تحملها.

⁨RPC⁩	رسالة الطلب	رسالة الاستجابة	الشكل
`Render`	`RenderRequest`	`RenderResponse`	أحادي. عرض متزامن عديم الحالة.
`RenderStream`	`RenderRequest`	`RenderChunk` (بث)	بث من الخادم. عرض يُسلَّم على شكل أجزاء مرتَّبة.
`SubmitJob`	`SubmitJobRequest`	`JobResponse`	أحادي. إرسال مهمة عرض غير متزامنة.
`GetJobStatus`	`GetJobStatusRequest`	`JobResponse`	أحادي. استطلاع حالة المهمة.
`GetJobResult`	`GetJobResultRequest`	`RenderResponse`	أحادي. تنزيل نتيجة مكتملة.
`GetJobResultStream`	`GetJobResultRequest`	`RenderChunk` (بث)	بث من الخادم. تنزيل نتيجة مكتملة على شكل أجزاء.
`CancelJob`	`CancelJobRequest`	`JobResponse`	أحادي. إلغاء مهمة أو حذفها.
`CreateSession`	`CreateSessionRequest`	`SessionResponse`	أحادي. إنشاء جلسة لبناء مستند.
`GetSession`	`GetSessionRequest`	`SessionResponse`	أحادي. جلب البيانات الوصفية للجلسة.
`DestroySession`	`DestroySessionRequest`	`DestroySessionResponse`	أحادي. إتلاف جلسة ومستندها.
`SessionOperation`	`SessionOperationRequest`	`SessionResponse`	أحادي. تنفيذ عملية على مستند جلسة.
`SessionRender`	`SessionRenderRequest`	`RenderResponse`	أحادي. عرض مستند جلسة إلى ⁨PDF.⁩
`SessionRenderStream`	`SessionRenderRequest`	`RenderChunk` (بث)	بث من الخادم. عرض مستند جلسة على شكل أجزاء.
`ExecuteCapability`	`CapabilityRequest`	`CapabilityResponse`	أحادي. تنفيذ عملية قدرة محجوبة بالمستوى.
`GetCapabilities`	`GetCapabilitiesRequest`	`GetCapabilitiesResponse`	أحادي. سرد القدرات للعميل المُصادَق عليه.
`HealthCheck`	`HealthCheckRequest`	`HealthCheckResponse`	أحادي. فحص الحيوية.
`ReadinessCheck`	`ReadinessCheckRequest`	`ReadinessCheckResponse`	أحادي. فحص الجاهزية.

رموز الرسائل

رسائل الطلب والاستجابة هي الرموز البنيوية للمخطط. رسائل العرض، أي RenderRequest، وRenderResponse، ورسالة البث RenderChunk، تحمل حجم الصفحة واتجاهها والعمليات المرتَّبة وبايتات ⁨PDF⁩ الناتجة. رسائل المهام، أي SubmitJobRequest، وGetJobStatusRequest، وGetJobResultRequest، وCancelJobRequest، وJobResponse، تنمذج دورة حياة المهمة غير المتزامنة، مع حفظ البيانات الوصفية للمهمة في رسالة JobData. رسائل الجلسات، أي CreateSessionRequest، وSessionResponse، وGetSessionRequest، وDestroySessionRequest، وDestroySessionResponse، وSessionOperationRequest، وSessionRenderRequest، تنمذج دورة حياة الجلسة ذات الحالة، مع حفظ البيانات الوصفية للجلسة في رسالة SessionData. رسائل القدرات، أي CapabilityRequest، وCapabilityResponse، وGetCapabilitiesRequest، وGetCapabilitiesResponse، تحمل إرسال العمليات المحجوبة بالمستوى والاستبطان. رسائل النظام، أي HealthCheckRequest، وHealthCheckResponse، وReadinessCheckRequest، وReadinessCheckResponse، تحمل حالة الحيوية والجاهزية.

ملفات .proto المشحونة هي عقد السلك المرجعي؛ راجع مرجع وسيلة نقل ⁨gRPC⁩ في وسيلة نقل ⁨gRPC⁩.

نموذج الأخطاء

يُبلِّغ الخادم عن حالات الفشل بآلية الأخطاء الأصلية لكل وسيلة نقل. وتحافظ كل وسيلة نقل على الحالة المنطقية نفسها؛ ولا يختلف إلا الترميز.

⁨MCP⁩

أخطاء ⁨MCP⁩ هي كائنات خطأ ⁨JSON-RPC 2.0.⁩ تُعيد الطريقة المجهولة الخطأ ⁨method-not-found⁩ (-32601)؛ وتُعيد الرسالة غير الصالحة وفق معيار ⁨JSON-RPC⁩ الخطأ ⁨invalid-request⁩ (-32600)؛ ويُعيد الإدخال غير القابل للتحليل الخطأ ⁨parse-error⁩ (-32700). تُعيد الأداة الفاشلة استجابة ⁨JSON-RPC⁩ ناجحة يُشير محتواها إلى الخطأ، بدلًا من خطأ على مستوى وسيلة النقل، حتى يتمكن الوكيل من قراءة الرسالة. كما أن تحدي التأكيد لأداة ApprovalRequired استجابة ناجحة أيضًا، لا خطأ.

⁨REST⁩

يستخدم ⁨REST⁩ رموز حالة بروتوكول نقل النص التشعبي (⁨HTTP⁩) بالدلالات المُحدَّدة في ⁨RFC 9110.⁩ يحمل 200 النتيجة؛ ويُعاد 400 عندما يفشل أحد حقول الطلب في التحقق من التنسيق؛ ويُعاد 401 عند عدم تقديم مفتاح ⁨API⁩ صالح، ويحمل ترويسة تحدٍّ WWW-Authenticate: Bearer؛ ويُعاد 403 عندما لا يكون مستوى مفتاح صالح مُخوَّلًا للعملية؛ ويُعاد 404 عندما لا يكون مسار محجوب بالمستوى مُسجَّلًا لغياب حزمته. نصوص الأخطاء القابلة للقراءة الآلية هي مستندات ⁨Problem Details⁩ وفق ⁨RFC 9457⁩، تُقدَّم بنوع وسائط application/problem+json وبـtype مُعرِّف موارد موحَّد (⁨URI⁩) ثابت لكل حالة. تُسرَد إخفاقات التحقق على مستوى الحقول في النص. كإجراء تحصين ضد اجتياز المسارات، يُرفض document_id الذي لا يطابق النمط doc_[a-f0-9]{24} بالرمز 400 قبل تشغيل الأداة. توثِّق وسيلة نقل ⁨REST⁩ خط الوسائط البرمجية في ⁨REST⁩ وجدول المسارات.

⁨gRPC⁩

يستخدم ⁨gRPC⁩ رموز حالة ⁨gRPC⁩ القياسية. يفشل الاستدعاء بالرمز UNAUTHENTICATED بدلًا من حالة ⁨HTTP⁩ عند وجود رمز مفقود أو مشوَّه أو مجهول أو مُعطَّل أو منتهي الصلاحية. تطابق تفاصيل الأخطاء الغنية شكل ⁨Problem Details⁩ في ⁨REST⁩، وتُحمَل في تفاصيل حالة ⁨gRPC⁩، بحيث يظل مُعرِّف الموارد الموحَّد للخطأ type متَّسقًا عبر وسائط النقل.

راجع أيضًا ⁨RFC 9110⁩ (دلالات ⁨HTTP⁩) لدلالات رموز الحالة و⁨RFC 9457⁩ (⁨Problem Details⁩ لواجهات ⁨HTTP⁩) لتنسيق نص الخطأ.

RFC 9110: https://www.rfc-editor.org/rfc/rfc9110
RFC 9457: https://www.rfc-editor.org/rfc/rfc9457

حدود المعدل والحصص

تطبِّق وسيلة نقل ⁨REST⁩ تحديد معدل لكل عنوان بروتوكول إنترنت (⁨per-IP⁩) ولكل عميل في خط وسائطها البرمجية، إضافةً إلى حدود حجم النص وحمولة المستوى ومهلة لكل طلب. هذه السقوف قيم إعداد، وليست ثوابت مُرمَّزة في الشيفرة:

سقوف الحمولة لكل مستوى (corePayloadLimit، proPayloadLimit، enterprisePayloadLimit) والمهل المطابقة لها تُطبَّق في ⁨REST⁩ وفق مستوى المفتاح المُصادَق عليه. راجع الإعداد.
مخزن المستندات في الذاكرة محدود بـmax_documents (افتراضيًا 50) وdocument_ttl (افتراضيًا 1800 ثانية).
تكون حالة تحديد المعدل والعمليات المتكافئة خاصة بكل عامل ما لم يُضبَط NEXTPDF_REDIS_HOST لمخزن مشترك. راجع النشر.

عندما تكون مخازن تحديد المعدل والعمليات المتكافئة مشتركة، تُزال ازدواجية عمليات إرسال المهام غير المتزامنة المتطابقة والمتكررة بحسب idempotency_key. تُعالِج وسيلة نقل ⁨MCP⁩ طلبًا واحدًا في كل مرة عبر الأنابيب، وتُزيل ازدواجية id طلبٍ متكرر من مخزن مؤقت سعته 64 مدخلًا بدلًا من تطبيق تحديد معدل شبكي.

ملاحظات التطوير

اقرأ أسماء الأدوات وفئاتها ومستويات مخاطرتها من المصدر ضمن src/Tools/؛ ولا تفترض مجموعة ثابتة. استعلم من الخادم العامل عن العدد المرجعي، كما هو موضَّح في فهرس الأدوات.
أعِد توليد كعوب عميل ⁨gRPC⁩ من ملفات proto/nextpdf/connect/v1/*.proto المشحونة؛ والحزمة ومساحة الأسماء هما nextpdf.connect.v1. لا تحرِّر فئات الرسائل المولَّدة يدويًا.
تُجيب أداة ApprovalRequired بتحدي تأكيد عند الاستدعاء الأول. ابنِ مسار إعادة المحاولة — مرِّر التحدي، ثم أعِد الاستدعاء مع _confirmation_token — قبل أن تشحن تكاملًا يُشغِّل output_pdf أو أي أداة تعديل.
المسار أو القدرة المحجوبة بالمستوى وغير المثبَّتة ليست فشل مصادقة: يُعيد ⁨REST⁩ الرمز 404 للمسار الغائب، ويُبلِّغ ExecuteCapability في ⁨gRPC⁩ عن عدم توفُّر العملية. عامِل غياب مستوى ⁨Pro⁩ أو ⁨Enterprise⁩ باعتباره حالة تشغيل متوقَّعة، لا عطلًا.
أبقِ مفاتيح ⁨API⁩ خارج التحكم بالمصدر؛ وحمِّلها من ملف سري، وفضِّل مخزن مفاتيح ملفي يعيد التحميل أثناء التشغيل حتى لا يحتاج التدوير إلى إعادة تشغيل. راجع الأمان والعمليات.

راجع أيضًا

دليل المطوِّر — البنية، ودورة الحياة، ونقاط التوسيع، وقائمة فحص الاختبار
فهرس الأدوات — مجموعة الأدوات الأساسية المُتحقَّق منها وعدد وقت التشغيل
مستويات المخاطرة بإشراف بشري (⁨HITL⁩) — نموذج المخاطرة وتحدي التأكيد
وسيلة نقل ⁨MCP⁩ · وسيلة نقل ⁨REST⁩ · وسيلة نقل ⁨gRPC⁩ — تفاصيل السلك لكل وسيلة نقل
الأمان والعمليات — المصادقة، وأمن النقل، ونموذج التهديد