إخراج الملفات بموافقة بشرية عبر NextPDF Connect

لمحة سريعة

تساعد بوابة التأكيد ذات التدخّل البشري (⁨HITL⁩) على منع عمليات الكتابة غير المقصودة في نظام الملفات. عند استدعاء output_pdf مع file_path، توقف البوابة الاستدعاء مؤقتًا وتُرجع تحدّيًا صالحًا لمرة واحدة بدلًا من كتابة الملف. يوافق عليه إنسان، ثم يعيد الوكيل الاستدعاء باستخدام الرمز المميز، وعندها فقط يُكتب الملف. إخراج ⁨Base64⁩ (بدون file_path) غير خاضع للبوابة.

التثبيت

composer require nextpdf/server

اربط ناقلًا. يستخدم output_pdf مستوى المخاطر “موافقة مطلوبة” افتراضيًا.

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

تقيّم البوابة مستوى المخاطر الفعلي: أي المستوى المتبقي بعد أي تجاوز من التهيئة أو من هوية المستدعي. وبالنسبة إلى أداة من نوع “موافقة مطلوبة”:

• وضع ⁨base64⁩ — يُخفَّض output_pdf دون file_path إلى مستوى “مراجعة”، ويُسمح به دون تأكيد. لا يخلّف أي أثر جانبي في نظام الملفات.
• وضع الملف — يبقى output_pdf مع file_path عند مستوى “موافقة مطلوبة”. تخزّن البوابة رمزًا مميزًا صالحًا لمرة واحدة مرتبطًا باسم الأداة، ثم تُرجع تحدّيًا. إذا كان الملف الهدف موجودًا بالفعل، يتضمن نص التحدّي تحذيرًا من الاستبدال. وتنتهي صلاحية الرمز المميز بعد نافذة زمنية ثابتة.

في كل ناقل، تكون نتيجة البوابة استجابة عادية. الموافقة المعلّقة إيقاف مؤقت لسير العمل، وليست فشلًا في الناقل (⁨PHP Standard Recommendation 18⁩ (⁨PSR-18⁩) §3؛ ⁨PSR-18⁩ §⁨p2⁩).

سطح ⁨API⁩

الأداة	الدور	فئة المخاطر
create_pdf	فتح الجلسة	آمن
set_font، add_text	إنشاء المحتوى	حذر
output_pdf (⁨base64⁩)	إرجاع مضمّن؛ دون بوابة	مراجعة
output_pdf (⁨file⁩)	الكتابة إلى القرص؛ خاضع للبوابة	موافقة مطلوبة

كتالوج الأدوات هو المصدر المرجعي، وتعتمد الأدوات المتاحة على الفئة المثبَّتة. ويحدّد مرجع فئات مخاطر ⁨HITL⁩ سلّم المخاطر والبوابة.

عيّنة برمجية — بداية سريعة

1. create_pdf ← أنشئ المحتوى باستخدام set_font/add_text.
2. output_pdf مع file_path ← تُرجع البوابة مغلّف تحدٍّ (الملف غير مكتوب).
3. انقل التحدّي إلى الإنسان.
4. عند الموافقة، استدعِ output_pdf مجددًا بالوسائط نفسها مع تعيين _confirmation_token إلى الرمز المميز الوارد في التحدّي ← يُكتب الملف وتُدمَّر الجلسة.

عيّنة برمجية — الإنتاج

• عامِل التحدّي دائمًا على أنه إيقاف مؤقت. لا تُعِد المحاولة في حلقة، ولا تختلق رمزًا مميزًا.
• الرمز المميز صالح لمرة واحدة ومرتبط باسم الأداة. الرمز المميز الصادر لأجل output_pdf لا يمكنه أن يأذن لأداة أخرى.
• إذا رفض الإنسان، فلا تعاود الاستدعاء. ولاسترداد البايتات دون كتابة ملف، استدعِ output_pdf في وضع ⁨base64⁩ بدلًا من ذلك. يتطلب ذلك أن تظل الجلسة موجودة، لذا استخدم destroy: false في المحاولة الخاضعة للبوابة إذا توقّعت الحاجة إليه.
• إذا انتهت صلاحية الرمز المميز قبل الموافقة، تُصدر البوابة تحدّيًا جديدًا. انقل التحدّي الجديد.

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

• عدم تقديم الرمز المميز إطلاقًا. تبقى العملية معلّقة. يجب أن يوافق الإنسان، ثم انقل التحدّي وأعِد الاستدعاء.
• رمز مميز منتهي الصلاحية. يُصدَر تحدٍّ جديد. أعِد نقله.
• أداة خاطئة. الرموز المميزة مرتبطة بالأداة. تفشل إعادة استخدامها مع أداة مختلفة، ويُصدَر تحدٍّ جديد.
• مسار غير مطلق. يُرفض قبل البوابة باعتباره مسارًا غير صالح.
• عدم وجود إذن كتابة / امتلاء القرص. هذا فشل في كتابة الملف بعد الموافقة. أظهِره. لا تُعِد المحاولة على نحو أعمى.
• تدمير الجلسة قبل إعادة الاستدعاء. إذا استخدم output_pdf سابقًا destroy: true، فقد زالت الجلسة. استخدم destroy: false عندما تتوقّع دورة موافقة ذهابًا وإيابًا.

الأداء

تضيف البوابة عملية بحث في مخزن الرموز المميزة ودورة ذهاب وإياب للموافقة البشرية. يحدّد الإنسان الزمن الفعلي، لا الخادم. ملف الأداء هو structural.

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

البوابة هي الحدّ الفاصل بين الوكيل ونظام ملفات الخادم. وهي موجودة لأن كتابة الملف أثر جانبي لا رجعة فيه، وينبغي أن يأذن به إنسان. الرمز المميز صالح لمرة واحدة، ومرتبط بالأداة، ومحدود زمنيًا. لا تُدمَج الوسائط فيه بالتجزئة عمدًا، لأن العملاء قد يعيدون تسلسل ⁨JSON⁩ بترتيب مفاتيح مختلف. لذلك يكون الربط هو الأداة + ⁨nonce⁩ + ⁨TTL⁩، لا مطابقة دقيقة للوسائط. لا تسجّل الرمز المميز. عامِله كسرّ لمرة واحدة.

المطابقة

العبارة	المواصفة	البند	⁨reference_id⁩
الموافقة المعلّقة استجابة عادية، وليست فشلًا.	⁨PSR-18⁩	§3
يُرجع الناقل استجابة بصرف النظر عن النتيجة.	⁨PSR-18⁩	§⁨p2⁩

تصف هذه الوصفة آلية البوابة. وهي لا تؤكّد أن البوابة تجعل أي عملية “آمنة”. تجعل البوابة الأثر الجانبي مأذونًا به من إنسان.

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

غير منطبق — البوابة وoutput_pdf من النواة (⁨Core⁩).

توافر الناقل

الناقل	متاح	ملاحظات
⁨MCP⁩ (⁨stdio⁩)	نعم	يُعرَض التحدّي على المضيف كنتيجة أداة ليؤكّده الإنسان.
⁨REST⁩	نعم	يُرجَع التحدّي في متن الاستجابة؛ أعِد الاستدعاء باستخدام الرمز المميز.
⁨gRPC⁩	نعم	أحادي الاتجاه؛ التحدّي هو رسالة الاستجابة؛ أعِد الاستدعاء باستخدام الرمز المميز.

فئة مخاطر ⁨HITL⁩

سلّم المخاطر هو آمن (0) ← حذر (1) ← مراجعة (2) ← موافقة مطلوبة (3). أدوات “موافقة مطلوبة” وحدها تستلزم تأكيدًا بشريًا. output_pdf من نوع “موافقة مطلوبة”. يخفّض وضع ⁨base64⁩ مستواه إلى “مراجعة” ويتخطّى البوابة. أما وضع الملف فيُبقيه عند “موافقة مطلوبة” ويُخضِع الاستدعاء للبوابة. تجد السلّم المعتمد وحلّ السياسة في مرجع فئات مخاطر ⁨HITL⁩.

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

لنتيجة البوابة شكلان فقط، تكشفهما بوابة التأكيد في الخادم:

مسموح (آمن/حذر/مراجعة، أو استهلاك رمز مميز صالح):

{ "allowed": true }

تحدٍّ (موافقة مطلوبة دون رمز مميز صالح):

{
  "allowed": false,
  "challenge": "⚠️ CONFIRMATION REQUIRED\n\nOperation: output_pdf\nDescription: <tool description>\n\nTo proceed, call output_pdf again with parameter _confirmation_token: \"confirm_<single-use-hex>\"\nExpires in 300 seconds.",
  "token": "confirm_<single-use-hex>"
}

عندما يكون الملف الهدف موجودًا بالفعل، يحتوي نص challenge أيضًا على سطر تحذير من الاستبدال. تؤدي إعادة استدعاء الأداة نفسها مع تعيين _confirmation_token إلى قيمة token إلى إرجاع { "allowed": true }، ثم تستمر العملية. الرمز المميز صالح لمرة واحدة، وتنتهي صلاحيته بعد النافذة الزمنية المذكورة في التحدّي.

انظر أيضًا

• مرحبًا بالعالم
• معالجة الأخطاء
• فئات مخاطر ⁨HITL⁩
• كتالوج الأدوات