المراجع

أخطاء الرفع عبر MCP في PlayDrop وطريقة الاستعادة منها

شكل الأخطاء التي تعيدها أدوات MCP في PlayDrop، ومتى تعيد المحاولة بـ requestId نفسه، وطريقة إصلاح كل رمز خطأ شائع.

يحتفظ كل خطأ من أدوات MCP في PlayDrop برمز error الثابت الخاص به وبأي تفاصيل مثل path أو field أو name أو expected، ويضيف:

message: ما الذي حدث، بكلمات بسيطة.
retryable: true فقط عندما يمكن أن ينجح الاستدعاء المطابق لاحقًا.
nextAction: التصحيح المحدد المطلوب.
docsUrl وdocumentationTopic: الدليل الذي يجب قراءته، والمتاح أيضًا عبر get_documentation.

أعد المحاولة أو صحّح

الأخطاء القابلة لإعادة المحاولة (الأعطال المؤقتة، وحدود المعدل، والإكمال المنقطع): أعد الاستدعاء المطابق بـ requestId نفسه بعد انتظار قصير. لا تنشئ إصدارًا آخر.
ضياع الرد: لا يمكنك معرفة هل نجح الاستدعاء، لذا أعد إرسال المحتوى المطابق بـ requestId نفسه. يعيد PlayDrop النتيجة الأصلية بدل النشر مرتين.
رفض المدخلات: أصلح الحقل أو الملف المذكور أولًا. يحتاج المحتوى المتغير إلى requestId جديد؛ وإعادة المحاولة بمدخلات لم تتغير تفشل مجددًا.
نتائج الحزمة الجزئية: تبقى العناصر المكتملة منشورة. يجب أن يحتوي الطلب المصحح على العمل غير المكتمل فقط.
send_feedback ليس له مفتاح إعادة محاولة. بعد فشل غامض لا تعد الإرسال تلقائيًا: فقد تكون الرسالة الأولى قد وصلت.

الأخطاء الشائعة

الرمز	ماذا تفعل
`advanced_upload_required`	تستخدم اللعبة SDK أو خادمًا أو ملفات منفصلة أو حقولًا خاصة بالحزم. احتفظ بتلك الميزات وارفع حزمة بـ `requestId` جديد.
`invalid_html_file`	ملف HTML فارغ أو أكبر من 10 MiB. استخدم حزمة للألعاب الأكبر.
`visibility_required`	تطبيق في الحزمة بلا قيمة ظهور. عيّن `visibility` في الطلب أو في التطبيق: `public` أو `unlisted` أو `private`.
`invalid_visibility`	استخدم `public` أو `unlisted` أو `private`.
`visibility_conflict`	يطلب الطلب ومدخل تطبيق ظهورين مختلفين. حدّد قيمة واحدة، حتى لا يتغير الجمهور بصمت أبدًا.
`expected_current_version_required`	أضف اسم كل تطبيق إلى `expectedCurrentVersion`: `null` للعبة جديدة، وإلا فالإصدار الحالي من `list_games`.
`current_version_changed`	نشر شخص ما إصدارًا أحدث. استدعِ `list_games`، وأكّد الهدف مع الشخص الذي تعمل معه، ثم ارفع بالإصدار الحالي و`requestId` جديد.
`game_exists_use_id`، `game_not_found`	استدعِ `list_games`، واستخدم `gameId` أو الاسم الصحيح، واحتفظ بالاسم الحالي للعبة.
`request_id_content_conflict`	هذا `requestId` ينتمي بالفعل إلى محتوى مختلف. استخدم معرّفًا جديدًا، أو أعد إرسال المحتوى الأصلي دون تغيير.
`catalogue_file_missing_or_invalid`	لم يُرفع ملف ما أو أن بايتاته لا تتطابق. استدعِ `prepare_catalogue_upload` مجددًا بالمدخلات نفسها و`requestId` نفسه، وارفع الملفات الناقصة بطلب PUT، ثم أكمل الرفع مجددًا.
`catalogue_files_unclaimed`	بعض الملفات لا يستخدمها أي مدخل في الكتالوج. أشر إليها، أو أعطِ ملفات صفحة اللعبة `role: "LISTING"` و`app`، أو احذفها.
`entry_point_missing`	يسمّي `apps[].file` ملفًا لم يُرفع. ودون `file`، تكون صفحة الدخول الافتراضية `<name>.html`.
`archive_catalogue_required`	ضع catalogue.json في جذر ملف ZIP، لا داخل مجلد.
`archive_too_large`	أكثر من 20 MiB مضغوطًا: فك ضغطه وارفع ملفات المجلد عبر روابط موقّعة، ما يسمح بما يصل إلى 50 MiB لكل ملف. أكثر من 200 MiB بعد فك الضغط: اللعبة نفسها أكبر من أن تُرفع في إصدار واحد؛ اضغط الأصول أو احذف بعضها.
`procedural_module_validation_unavailable`	لا يمكن رفع النماذج الإجرائية ثلاثية الأبعاد القابلة للتنفيذ أو نماذج الصيغ المخصصة عبر MCP. حوّلها مسبقًا إلى صيغة ثابتة أو أشر إلى أصل منشور.
`upload_expired`، `upload_cancelled`	حضّر الرفع مجددًا بـ `requestId` جديد وأكمله خلال 30 دقيقة.
`invalid_token`، `insufficient_scope`	أعد ربط حساب PlayDrop في تطبيق الذكاء الاصطناعي واسمح بالنشر.

تشير أخطاء حقول الكتالوج، مثل وسم غير صالح أو تصريح خاطئ بوحدات التحكم أو بطريقة اللعب، إلى مرجع catalogue.json.

الاتصال والمرفقات

انتهاء صلاحية الاتصال: يتجدد الاتصال النشط تلقائيًا ما دام مستخدمًا. أما الاتصال غير المستخدم منذ 30 يومًا، أو الذي انتهت صلاحيته قبل هذه القاعدة، فيحتاج إلى إعادة الربط.
رفض المرفق: لا ينزّل PlayDrop الملفات إلا من خدمة المرفقات الخاصة بالمضيف. هذا قيد على مضيف الملفات، وليس قيدًا على البلد. مرّر المرفق كما يوفّره المضيف نفسه، أو ارفع الملفات بروابط موقّعة. لا تختلق أبدًا download_url أو file_id.

أبلغ عن مشكلة

إذا بدا خطأ غير صحيح أو لم ينجح الإجراء التالي، فاستدعِ send_feedback مرة واحدة مع اسم الأداة ورمز الخطأ وما أرسلته (دون رموز الوصول أو الروابط الموقّعة) وما توقعته.