OmniRoute/docs/i18n/ar/CONTRIBUTING.md

Contributing to OmniRoute (العربية)

🌐 Languages: 🇺🇸 English · 🇪🇸 es · 🇫🇷 fr · 🇩🇪 de · 🇮🇹 it · 🇷🇺 ru · 🇨🇳 zh-CN · 🇯🇵 ja · 🇰🇷 ko · 🇸🇦 ar · 🇮🇳 hi · 🇮🇳 in · 🇹🇭 th · 🇻🇳 vi · 🇮🇩 id · 🇲🇾 ms · 🇳🇱 nl · 🇵🇱 pl · 🇸🇪 sv · 🇳🇴 no · 🇩🇰 da · 🇫🇮 fi · 🇵🇹 pt · 🇷🇴 ro · 🇭🇺 hu · 🇧🇬 bg · 🇸🇰 sk · 🇺🇦 uk-UA · 🇮🇱 he · 🇵🇭 phi · 🇧🇷 pt-BR · 🇨🇿 cs · 🇹🇷 tr

---

شكرا لاهتمامك بالمساهمة! يغطي هذا الدليل كل ما تحتاجه للبدء.---##إعداد التطوير### Prerequisites

-Node.js>= 18 < 24 (موصى به: 22 LTS) -npm10+ -جيت### النسخ والتثبيتbash استنساخ بوابة https://github.com/diegosouzapw/OmniRoute.git قرص مضغوط OmniRoute تثبيت npm

Environment Variables

# قم بإنشاء .env الخاص بك من القالب
cp .env.example .env

# توليد الأسرار المطلوبة
صدى "JWT_SECRET=$(openssl rand -base64 48)" >> .env
صدى "API_KEY_SECRET=$(openssl rand -hex 32)" >> .env```

المساهمة في التنمية الرئيسية:

| فنية | التطوير الافتراضي | الوصف |
| ---------------------- | ------------------------ | --------------------- |
| "ميناء" | `20128` | منفذ الخادم |
| `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | عنوان URL الأساسي للواجهة |
| `JWT_SECRET` | (أنشئ أعلاه) | سر توقيع JWT |
| `INITIAL_PASSWORD` | "التغيير" | كلمة المرور الأولى لتسجيل الدخول |
| `APP_LOG_LEVEL` | `معلومات` | تسجيل مستوى الإسهاب |### إعدادات لوحة التحكم

توفر أدوات تعديل لوحة المعلومات للمستخدم للميزات التي يمكن تهيئتها أيضًا عبر البيئات المتنوعة:

| تحديد الموقع | تغيير | الوصف |
| ------------------- | ------------------ | ------------------------------ |
| الإعدادات → متقدمة | وضع الرقعة | أرشيف الطلبات التصحيح (UI) |
| الإعدادات → عام | رؤية الشريط الجانبي | إخفاء/ إخفاء أقسام الفصل الجانبي |

يتم تخزين هذه الإعدادات في قاعدة البيانات وتستمر من خلال عمليات إعادة تشغيل التشغيل، مما يؤدي إلى تجاوز إعدادات env var الافتراضية عند ضبطها.### التشغيل محليًا```bash
# Development mode (hot reload)
npm run dev

# Production build
npm run build
npm run start

# Common port configuration
PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev

عناوين URL الافتراضية:

-لوحة المعلومات: http://localhost:20128/dashboard -واجهة برمجة التطبيقات: http://localhost:20128/v1---## Git Workflow

⚠️**لا تلتزم مطلقًا بـ "الرئيسي".**استخدم ميزات الميزات دائمًا.```bash git checkout -b feat/your-feature-name #...إجراءات جديدة... git الالتزام -m "الفذ: وصف التغيير الخاص بك" git Push -u Origin feat/your-feature-name

قم بتسجيل الطلب على GitHub```### Branch Naming

المبادئ	الحصاد
الفذ/	مميزات جديدة
/	إصلاحات الشويب
إعادة البناء/	إعادة هيكلة الكود
المستندات/	تأثيرات التوثيق
اختبار/	الإضافات/إصلاحات الاختبار
العمل الرتيب/	الأدوات، CI، التبعيات	### رسائل الالتزام

اتبع الالتزامات التقليدية: الفذ: إضافة قاطع الدائرة لمكالمات المزود الإصلاح: حل حالة حافة التحقق السري من JWT المستندات: قم بتحديث SECURITY.md مع حماية معلومات تحديد الهوية الشخصية (PII). الاختبار: إضافة اختبارات وحدة الملاحظة refactor(db): توحيد جداول حدود المعدل

النطاقات: db، sse، oauth، dashboard، api، cli، docker، ci، mcp، a2a، memory، skills.---## Running Tests

# جميع الاختبارات (الوحدة + فيتيست + النظام البيئي + e2e)
اختبار تشغيل npm: الكل

# ملف اختبار فردي (مشغل الاختبار الأصلي لـ Node.js — تستخدمه معظم الاختبارات)
العقدة - استيراد tsx/esm - اختبارات الاختبار/الوحدة/your-file.test.mjs

# Vitest (خادم MCP، autoCombo، ذاكرة التخزين المؤقت)
اختبار تشغيل npm: vitest

# اختبارات E2E (يتطلب الكاتب المسرحي)
اختبار تشغيل npm: e2e

# عملاء البروتوكول E2E (نقل MCP، A2A)
اختبار تشغيل npm: البروتوكولات: e2e

# اختبارات توافق النظام البيئي
اختبار تشغيل npm: النظام البيئي

# التغطية (60% الحد الأدنى من البيانات/السطور/الوظائف/الفروع)
اختبار تشغيل npm: التغطية
تغطية تشغيل npm: تقرير

# فحص الوبر + التنسيق
npm تشغيل الوبر
فحص تشغيل npm```

تغطية التعليقات:

- `npm run test:coverage` يقيس المصدر لمجموعة اختبار الوحدة الرئيسية، ويستبعد `tests/**`، بما في ذلك `open-sse/**`
- يجب أن تحافظ على طلبات التنظيف على بوابة التغطية الشاملة عند**60% أو أعلى**للكشوفات والخطوط والوظائف والأروع
- إذا قام ممثل العلاقات العامة تغيير رمز الإنتاج في `src/` أو `open-sse/` أو `electron/` أو `bin/`، فيجب عليه إضافة أو تحديث النقاشة التلقائية في نفس العلاقات العامة
- `تغطية تشغيل npm: التقرير' يطبع التقرير التفصيلي لكل ملف على المدى الطويل من أحدث طرق التغطية
- `اختبار تشغيل npm:التغطية:التراث` يحافظ على قياس الأقدم للمقارنة التاريخية
- راجع`docs/COVERAGE_PLAN.md` للحصول على خارطة طريق تحسين التغطية العامة### سحب متطلبات الطلب

قبل فتح أو دمج العلاقات العامة:

- اختبار تشغيل npm: الوحدة
- اختبار تشغيل npm: التغطية
- تأكد من بقاء بوابة التغطية عند**60%+**لجميع المعايير
- تتضمن ملفات الاختبار التي تم تغييرها أو الهاتفا في وصف العلاقات العامة عند تغيير رمز الإنتاج
- التحقق من نتيجة SonarQube على PR عندما يتم التأكد من أسرار المشروع في CI

الاختبار الحالي:**ملفات اختبار 122 وحدة**تغطي:

- تحويل المترجمين باستمرار
- الحد من المعدل، وقواطع الضوء، والمرونة
- ذاكرة تخزين مؤقتة الدلالية، والعجز، وتتبع التقدم
- عمليات قاعدة البيانات والمخطط (21 وحدة قاعدة بيانات)
- تدفقات OAuth والمصادقة
- التحقق من صحة نقطة نهاية واجهة برمجة التطبيقات (Zod v4)
- أدوات خادمة MCP وكارثة النطاق
- لأنظمة الذاكرة والمهارات---## Code Style

-**ESLint**— يسمح npm run lint قبل الالتزام
-**Prettier**— يتم بشكل متزايد من خلال ``التجهيز المرحلي`` عند الالتزام (مسافتان، فواصل منقوطة، علامات رسل مزدوجة، عرض 100 حرف، فاصلة زائدة es5)
-**TypeScript**— يستخدم جميع أكواد `src/` `.ts`/`.tsx`؛ `open-sse/` يستخدم `.ts`/`.js`؛ مستند باستخدام TSDoc (`@param`، `@returns`، `@throws`)
-**لا يوجد `eval()`**- يفرض ESLint `no-eval`، `no-implied-eval`، `no-new-func`.
-**التحقق من صحة Zod**— استخدم مخطط Zod v4 للتأكد من صحة واجهة برمجة التطبيقات (API).
-**التسميه**: الملفات = الجمله/علبة الكباب، المكونات = PascalCase، الثوابت = UPPER_SNAKE---## Project Structure

src/ # تايب سكريبت (.ts / .tsx) ├── التطبيق/ # Next.js 16 App Router │ ├── (لوحة المعلومات)/ # صفحات لوحة المعلومات (23 قسم) │ ├── واجهة برمجة التطبيقات/ # مسارات واجهة برمجة التطبيقات (51 دليلاً) │ └── تسجيل الدخول/ # صفحات المصادقة (.tsx) ├── المجال/ # محرك السياسة (policyEngine، comboResolver، costRules، إلخ.) ├── lib/ # منطق العمل الأساسي (.ts) │ ├── a2a/ # خادم بروتوكول وكيل إلى وكيل v0.3 │ ├── acp/ # تسجيل بروتوكول اتصال الوكيل │ ├── الامتثال/ # محرك سياسة الامتثال │ ├── db/ # طبقة قاعدة بيانات SQLite (21 وحدة + 16 عملية ترحيل) │ ├── الذاكرة/ # ذاكرة المحادثة المستمرة │ ├── oauth/ # موفرو OAuth والخدمات والأدوات المساعدة │ ├── المهارات/ # إطار المهارات الموسعة │ ├── الاستخدام/ # تتبع الاستخدام وحساب التكلفة │ └── localDb.ts # طبقة إعادة التصدير فقط - لا تقم أبدًا بإضافة المنطق هنا ├── البرامج الوسيطة/ # طلب البرامج الوسيطة (promptInjectionGuard) ├── mitm/ # وكيل MITM (الشهادة، DNS، التوجيه المستهدف) ├── مشترك/ │ ├── المكونات/ # مكونات التفاعل (.tsx) │ ├── الثوابت/ # تعريفات الموفر (60+)، نطاقات MCP، استراتيجيات التوجيه │ ├── utils/ # قاطع الدائرة، المطهر، مساعدي المصادقة │ └── التحقق من الصحة/ # مخططات Zod v4 └── sse/ # خط أنابيب الوكيل SSE

open-sse/ # @omniroute/open-sse Workspace ├── المنفذون/ # 14 منفذو الطلبات الخاصة بموفر الخدمة ├── المعالجات/ # 11 معالجات الطلب (الدردشة والردود والتضمين والصور وما إلى ذلك) ├── mcp-server/ # خادم MCP (25 أداة، 3 عمليات نقل، 10 نطاقات) ├── الخدمات/ # 36+ خدمة (combo، autoCombo، RateLimitManager، إلخ.) ├── مترجم/ # مترجمو التنسيق (OpenAI ↔ كلود ↔ الجوزاء ↔ الردود ↔ أولاما) ├── محول/ # محول API الردود └── utils/ # 22 وحدة مساعدة (الدفق، TLS، الوكيل، التسجيل)

إلكترون/ # تطبيق إلكترون لسطح المكتب (متعدد المنصات)

الاختبارات/ ├── الوحدة/ # مشغل اختبار Node.js (122 ملف اختبار) ├── التكامل/ # اختبارات التكامل ├── e2e/ # اختبارات الكاتب المسرحي ├── الأمان/ # اختبارات الأمان ├── المترجم/ # اختبارات خاصة بالمترجم └── تحميل/ # اختبارات التحميلمستندات/ # التوثيق ├── ARCHITECTURE.md # بنية النظام ├── API_REFERENCE.md # جميع نقاط النهاية ├── USER_GUIDE.md # إعداد الموفر، تكامل CLI ├── استكشاف الأخطاء وإصلاحها.md # المشكلات الشائعة ├── MCP-SERVER.md # خادم MCP (25 أداة) ├── A2A-SERVER.md # بروتوكول الوكيل A2A ├── AUTO-COMBO.md # محرك التحرير والسرد التلقائي ├── تكامل أدوات CLI-TOOLS.md # تكامل أدوات CLI ├── COVERAGE_PLAN.md # اختبار خطة تحسين التغطية ├── openapi.yaml # مواصفات OpenAPI └── adr/ # سجلات قرارات الهندسة المعمارية```

---

Adding a New Provider

Step 1: Register Provider Constants

أضف إلى src/shared/constants/providers.ts - تم التحقق من صحة Zod عند تحميل الوحدة.### الخطوة 2: إضافة Executor (إذا كانت هناك حاجة إلى منطق مخصص)

موجود بالفعل منفذ تنفيذي في open-sse/executors/your-provider.ts لتوسيع المنفذ الأساسي.### الخطوة 3: إضافة مترجم (إذا كان تنسيق غير OpenAI)

يجب أن تكون موجودة في الطلب المترجم/الاستجابة في open-sse/translator/.### الخطوة 4: إضافة تكوين OAuth (إذا كان يعتمد على OAuth)

إضافة بيانات موثوقة OAuth في src/lib/oauth/constants/oauth.ts وتطبيقات في src/lib/oauth/services/.### الخطوة 5: تسجيل النماذج

أضف تعريفات الارتباطات في "open-sse/config/providerRegistry.ts".### الخطوة 6: إضافة الاختبارات

اكتب السيولة الوحدة في الاختبارات/الوحدة/ التي تغطي الحد الأدنى:

• تسجيل المزود

• ترجمة الطلب/الرد -تسبب سبب---## Pull Request Checklist

• اجتياز الاختبار (اختبار npm)

• طباعات القلم (npm run lint)

• نجاح البناء (npm run build)

• تمت إضافة أنواع TypeScript للوظائف والواجهات العامة الجديدة

• لا توجد أسرار ضمنية أو قيم بيعة

• تم التحقق من صحة جميع المدخلات باستخدام مخططات Zod

• تم تحديث سجل التغيير (في حالة التغيير الذي يواجهه المستخدم)

• تم تحديث الوثائق (إن وجدت)---## Releasing

تم إدارة الاختلاف عبر سير العمل /generate-release. عند إنشاء إصدار GitHub جديد، يتمنشر المنتج اليدوي إلى npmعبر إجراءات GitHub.---## Getting Help

-الهندسة المعمارية: تجدد docs/ARCHITECTURE.md -مرجع واجهة برمجة التطبيقات: راجع docs/API_REFERENCE.md -المشاكل: github.com/diegosouzapw/OmniRoute/issues -ADRs: راجع docs/adr/