# إضافة منصة جديدة

إضافة موقع دردشة جديد تتضمن طبقتين منفصلتين:

1. **محوّل الموقع** `catalog/sites/<site>/site.json`، ويعلّم Voyager كيف يتعرف على الموقع ويجد رسائل المستخدم ورسائل المساعد وحقل الإدخال والشريط الجانبي وعلامات السمة.
2. **إضافة** ضمن `catalog/sites/<site>/plugins/<id>/`، تحل مشكلة واحدة يواجهها المستخدم على ذلك الموقع، مثل عرض القراءة أو إصلاح عرض معين.

يحمل `site.json` الحقول `id` (ويساوي اسم مجلده)، و`label`، و`matches`، و`selectors`، و`theme`، و`brandColor`، و`capabilities`، إضافةً إلى الحقلين الاختياريين `conversationIdPattern` و`turnKeyAttributes`. يسمّي `turnKeyAttributes` السمات التي تحفظ هوية رسالة المستخدم عندما تعيد الصفحة عرضها؛ ولا يعمل تتبع الإرسال (الذي يستخدمه عرض Activity في المجلدات وطوابع الوقت في الجدول الزمني) إلا على موقع يحدد هذه السمات، إلى جانب `composer` و`userTurn` و`conversationIdPattern`. يتحقق `validateSiteAdapterData` في `src/features/plugins/sites/siteAdapterData.ts` من صحة الملف، ويتحقق `bun run catalog:build` من كل موقع وكل إضافة قبل النشر.

المنصات الحالية هي ChatGPT وClaude وDeepSeek وKimi. أما Gemini وAI Studio فهما واجهتان أصليتان في Voyager ولكل منهما `site.json` خاص به (`catalog/sites/gemini/` و`catalog/sites/aistudio/`)، لكنه يُشحن داخل الحزمة ولا يُنشر أبدًا في الفهرس البعيد؛ وأصبحت الملفات `sites/adapters/gemini.ts` و`aistudio.ts` و`claude.ts` و`chatgpt.ts` و`deepseek.ts` أغلفة من سطر واحد فوق `site.json`، لذا عدّل ملف JSON لا ملف TypeScript. كما يحمل الفهرس المنشور لكل مضيف بيانات الموقع أيضًا، لذلك يصل إصلاح المحددات إلى المستخدمين دون إصدار جديد للإضافة. لكن الموقع الجديد تمامًا يحتاج إلى محوّل من الأساس، لأنه يحتاج أيضًا إلى إذن المضيف وتسجيل سكريبتات المحتوى، وهذان يُشحنان داخل الحزمة.

في حالة منصة جديدة مثل DeepSeek، اجعل عمل المحوّل مركّزًا على عقد المنصة. ضع `site.json` واختبارات المحددات المطلوبة والحد الأدنى من التوثيق الذي يشرح الدعم في تغيير واحد متكامل. يلتقط سجل المواقع المحوّل الجديد من الملف نفسه، فلا توجد قائمة تسجيل تحتاج إلى تعديل. ولا تُضِف موقعًا جديدًا لكل إضافة.

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

لا يتطلب دعم الموقع تكاملًا مع واجهة نموذج (Model API). لا تضِف سكريبتات محتوى ثابتة ولا أذونات مضيف مطلوبة لمنصة جديدة؛ بل استخدم مسار الأذونات الاختيارية والتسجيل الديناميكي للمواقع الخاصة بالإضافات فقط.

يعتمد مسار الأذونات الاختيارية والتسجيل الديناميكي على إصدار المتصفح. يدعم Chrome وEdge المسار الذي تستخدمه الإضافة. ويتطلب Firefox الإصدار 128 أو أحدث للأذونات الاختيارية لمضيفات الويب، ويتطلب Safari الإصدار 16.4 أو أحدث للتسجيل الديناميكي لسكريبتات المحتوى. وفي إصدارات المتصفح المدعومة الأقدم، قد تمتنع النافذة المنبثقة بشكل صحيح عن تفعيل إضافة لموقع مخصص، لأن الواجهات المطلوبة لا توفر منحًا دائمًا. فلا تتجاوز ذلك بإضافة إذن مضيف واسع وثابت دون موافقة المشرفين.