# اكتب إضافتك الخاصة

الإضافة المحلية إضافة تصنعها لنفسك. تغيّر مظهر Gemini أو AI Studio أو ChatGPT أو Claude أو DeepSeek أو تخطيطه، وتبقى في متصفحك وحده، ولا تحتاج إلى أي PR ولا إلى نسخة من الشيفرة المصدرية لـ Voyager.

ومثل كل إضافات Voyager، فهي تعريفية: ملف manifest باسم `plugin.json` ومعه CSS، ولا تشغّل أي شيفرة خاصة بها. يفحصها Voyager عند الاستيراد، ويطبّق تغييراتها، ويزيل كل تلك التغييرات عند إيقافها. وتبدأ الإضافة المستوردة متوقفة، حتى تتمكن من مراجعتها أولًا.

## ثلاث طرق لصنعها

### صِف التغيير ودع أي ذكاء اصطناعي يكتبها

1. افتح الموقع الذي تريد تغييره، ثم افتح popup الخاص بـ Voyager وابحث عن بطاقة **الإضافات المحلية** (في Gemini وAI Studio هي آخر عنصر في الإعدادات).
2. اختر **صِف تغييرًا**، واكتب جملة واحدة («اجعل رسائلي أضيق وأخفِ الشريط الجانبي»)، ثم اختر **اكتب الموجّه**.
3. انسخ الموجّه بنفسك إلى أي محادثة ذكاء اصطناعي، ثم الصق ردّه كاملًا واختر **افحص الرد**.
4. يشرح Voyager بلغة بسيطة ما الذي تغيّره الإضافة. استوردها، ثم شغّلها من قائمة الإضافات.

لا يرسل Voyager الموجّه إلى أي مكان: أنت من يختار الذكاء الاصطناعي، وأنت من ينقل النص ذهابًا وإيابًا.

### سلّمها إلى وكيل برمجة

إذا كنت تستخدم وكيل برمجة (مثل Claude Code أو Codex أو Cursor)، فأعطه skill الإضافات الخاصة بـ Voyager:

```text
https://voyager.nagi.fun/skills/write-voyager-plugin/SKILL.md
```

في بطاقة **الإضافات المحلية**، افتح **صِف تغييرًا** لتجد زر **نسخ رابط المهارة**. يضم الـ skill العقد الكامل: حقول الـ manifest، وما يعلنه كل موقع، والبدائيات، وما لا تستطيع الإضافة فعله. اطلب من الوكيل التغيير الذي تريده، فينشئ مجلدًا ويكتب `plugin.json` و`style.css` ويفحصهما دون اتصال. بعد ذلك اختر **استيراد ملفات** في popup وحدد الملفين.

لإبقاء الـ skill مثبّتًا، احفظ الملف باسم `write-voyager-plugin/SKILL.md` داخل مجلد skills لدى وكيلك (في Claude Code هو `~/.claude/skills/`).

### اكتبها بنفسك

باستخدام Node.js 18 أو أحدث:

```sh
npx create-voyager-plugin@latest init my-plugin --site claude
# عدّل my-plugin/plugin.json و my-plugin/style.css
npx create-voyager-plugin@latest check my-plugin
```

ينشئ `init` ملفي `plugin.json` و`style.css` يجتازان الفحص من البداية، إضافة إلى ملف `AGENTS.md` يضم قواعد ذلك الموقع. ويقبل `--site` القيم `gemini` أو `aistudio` أو `chatgpt` أو `claude` أو `deepseek`.

يشغّل `check` دون اتصال الفحوص نفسها التي يجريها الاستيراد في popup. ينتهي برمز الخروج 0 إذا كانت الإضافة قابلة للاستيراد، وإلا فيطبع سطر `path: message` لكل مشكلة. أضف `--json` لتحصل على مخرجات قابلة للقراءة آليًا.

## ما الذي تستطيع الإضافة فعله

- إضافة CSS محصور تحت صنف `gv-` تضيفه الإضافة إلى الصفحة.
- إضافة صنف، أو ضبط سمة آمنة أو نمط مضمّن، أو إخفاء عناصر. والأهداف إما مفاتيح دلالية يعلنها الموقع (`userTurn` و`assistantTurn` و`composer` وغيرها) وإما محددات CSS.
- توفير إعدادات في popup: مفاتيح تبديل ومنزلقات وقوائم منسدلة، تصل قيمها إلى CSS عبر رموز `{{key}}`.
- في ChatGPT وClaude وDeepSeek، تفعيل إحدى بدائيات Voyager (نسخ الصيغ، والخط الزمني، ومخططات Mermaid وغيرها) وتغيير ألوان واجهة Voyager نفسها.

## ما الذي لا تستطيع فعله

لا تستطيع الإضافة تشغيل JavaScript، ولا الاستجابة للنقرات أو المفاتيح، ولا تحميل أي شيء من الشبكة (خطوط أو صور أو أوراق أنماط)، ولا قراءة محتوى الرسائل أو إعادة كتابته، ولا العمل على مواقع أخرى. وإذا تطلّب الطلب شيئًا من ذلك، فإن مواد الكتابة توجّه الذكاء الاصطناعي إلى التصريح بذلك وبناء أقرب نسخة ممكنة تعمل فعلًا.

## القواعد التي يفحصها الاستيراد

إلى جانب فحوص الـ manifest المشتركة (راجع [المساهمة في الإضافات](./plugin-contribution.md))، يجب على الإضافة المحلية أن:

- تطابق فقط عناوين URL داخل موقع يدعمه Voyager؛
- تستخدم فقط المفاتيح الدلالية التي يعلنها كل موقع تطابقه؛
- تضيف صنفًا واحدًا بالضبط في كل `addClass`، يبدأ بـ `gv-`؛
- تستخدم إعدادات من نوع boolean أو number أو select فقط (لا يوجد بعد عنصر تحكم في popup لـ string وcolor)؛
- لا تستخدم `theme` على Gemini أو AI Studio، ولا تستخدم من البدائيات إلا ما يسمح به كل موقع: `formulaCopy` و`vimInput` و`userLatex` و`codeCollapse` و`mermaid` و`wavedrom` و`echarts` و`sendShortcut` و`draftSave` و`turnNavigator` على Gemini، و`formulaCopy` و`sendShortcut` على AI Studio. تشغّل هذه البدائيات الشيفرة نفسها التي تشغّلها إعدادات Voyager المدمجة المقابلة. أما `formulaCopy` و`vimInput` (نسخ المعادلات ووضع Vim لمربع الإدخال) فيعمل كلٌّ منهما مرة واحدة في الصفحة: الإعداد المدمج أو إضافة، لا كلاهما. عند تحميل الصفحة، أو ما دام لا يعمل أي منهما، تكون الأولوية للإعداد المدمج؛ وبعد ذلك يواصل ما يعمل بالفعل عمله ويظهر الآخر متوقفًا مؤقتًا. أوقف أحدهما ليتولى الآخر العمل. أما `userLatex` و`codeCollapse` و`mermaid` و`wavedrom` و`echarts` فتتولى عناصر الصفحة عنصرًا عنصرًا وتعمل جنبًا إلى جنب مع الإعداد المدمج: السطر أو كتلة الشيفرة التي يتولاها الطرف الآخر تُترك له.

أصبحت `turnNavigator` متاحة للإضافات المحلية على Gemini للمستخدمين الأفراد مع `params.dataBackend: "shared"` و`engine: ">=1.9.0"`. تقرأ بيانات النجوم والبنية الهرمية الأصلية نفسها التي يستخدمها الجدول الزمني الرسمي وتعدّلها؛ ولا يمكن تجاوز معاملات هوية المحادثة أو الحساب أو الدور. تتعارض معها ميزة **إظهار الجدول الزمني** الرسمية: عطّل الإعداد الرسمي أولًا، ثم فعّل الإضافة المحلية. للعودة إلى الميزة الرسمية، عطّل الإضافة المحلية أولًا، ثم فعّل الإعداد الرسمي. لا تدعم Business أو Enterprise أو نطاق مواقع مخصصًا.

الترجمات (`i18n`) اختيارية.

## مشاركتها

تبقى الإضافة المحلية في متصفحك؛ ولنقلها إلى مكان آخر صدّر ملف JSON الخاص بها من قائمة الإضافات. وإذا كانت ستفيد الجميع، فاقترح ضمّها إلى الكتالوج الرسمي: يشرح [المساهمة في الإضافات](./plugin-contribution.md) هذا المسار.

على جميع المواقع تعمل إضافة اختصار إرسال واحدة فقط في كل صفحة. عندما تستخدم إضافة وضع الإرسال، تظهر الإضافة الأخرى تعارضًا وتبقى متوقفة مؤقتًا. قيمة `mode` الاختيارية (تتطلب `"engine": ">=1.9.0"`) هي `ctrlEnterSends` (الافتراضية) أو `enterSends`. لا يؤدي تأكيد IME إلى الإرسال. أصبح هذا المكوّن متاحًا في Gemini وAI Studio؛ والأوضاع المدعومة موضحة أدناه.

في Gemini يمكن أن يحل `sendShortcut` محل إرسال Ctrl/Cmd+Enter الرسمي: عطّل الإعداد الرسمي ثم فعّل الإضافة المحلية. يقبل `ctrlEnterSends` فقط ولا يعمل في Enterprise. يشمل `composerRoot` الإدخال الرئيسي والتحرير، ويستثني `sendButton` زر الإيقاف.

على AI Studio، يتطلب `sendShortcut` ضبط `params.mode: "enterSends"`. عطّل إعداد الإرسال الرسمي بزر Enter لتتولى الإضافة المحلية العمل. يضيف Ctrl/Cmd+Enter سطرًا جديدًا، ويتولى الموقع معالجة Shift/Alt+Enter.

على Gemini، تشارك `draftSave` سجلات `gvDraft_<pathname كامل>` مع الميزة الرسمية، بما فيها مسارات `/u/N` وGem. تبقى المسودات المحفوظة عند التعطيل، ويمكن لإضافات الصفحة مشاركتها. تحاول الصفحة حفظ آخر إدخال قبل الإغلاق، لكن إغلاق المتصفح لا يضمن اكتمال التخزين غير المتزامن. يقتصر تنسيق الكتابة والتنظيف على هذه الصفحة؛ ويظل تغيير البريد الإلكتروني داخل خانة `/u/N` نفسها يستخدم المسودات المحفوظة المشتركة.