OmniRoute/docs/i18n/ar/docs/guides/USER_GUIDE.md

User Guide (العربية)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇭🇺 hu · 🇦🇲 hy · 🇮🇩 id · 🇳🇬 ig · 🇮🇹 it · 🇯🇵 ja · 🇬🇪 ka · 🇰🇭 km · 🇮🇳 kn · 🇰🇷 ko · 🇱🇹 lt · 🇱🇻 lv · 🇮🇳 ml · 🇮🇳 mr · 🇲🇾 ms · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇱 nl · 🇳🇴 no · 🇮🇳 or · 🇮🇳 pa · 🇵🇭 phi · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇱🇰 si · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW

---

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇭🇺 hu · 🇦🇲 hy · 🇮🇩 id · 🇳🇬 ig · 🇮🇹 it · 🇯🇵 ja · 🇬🇪 ka · 🇰🇭 km · 🇮🇳 kn · 🇰🇷 ko · 🇱🇹 lt · 🇱🇻 lv · 🇮🇳 ml · 🇮🇳 mr · 🇲🇾 ms · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇱 nl · 🇳🇴 no · 🇮🇳 or · 🇮🇳 pa · 🇵🇭 phi · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇱🇰 si · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW

دليل شامل لتكوين موفري الخدمات، وإنشاء التركيبات، ودمج أدوات واجهة سطر الأوامر، ونشر OmniRoute.

---

جدول المحتويات

• نظرة سريعة على الأسعار
• حالات الاستخدام
• إعداد مزوّد الخدمة
• تكامل واجهة سطر الأوامر
• النشر
• النماذج المتاحة
• الميزات المتقدمة
• التوجيه التلقائي (من دون إعداد)
• تكامل MCP وA2A
• نظام المهارات
• نظام الذاكرة
• خطافات الويب
• الوكلاء السحابيون
• الإدارة البرمجية
• واجهة سطر الأوامر الداخلية
• تطبيق سطح المكتب (Electron)

---

💰 نظرة سريعة على الأسعار

الفئة	مزوّد الخدمة	التكلفة	إعادة تعيين الحصة	الأنسب لـ
💳 اشتراك	Claude Code (Pro)	$20/شهريًا	5 ساعات + أسبوعيًا	المشتركين بالفعل
	Codex (Plus/Pro)	$20-200/شهريًا	5 ساعات + أسبوعيًا	مستخدمي OpenAI
	GitHub Copilot	$10-19/شهريًا	شهريًا	مستخدمي GitHub
🔑 مفتاح API	DeepSeek	الدفع حسب الاستخدام	لا توجد	الاستدلال منخفض التكلفة
	Groq	الدفع حسب الاستخدام	لا توجد	الاستدلال فائق السرعة
	xAI (Grok)	الدفع حسب الاستخدام	لا توجد	استدلال Grok 4
	Mistral	الدفع حسب الاستخدام	لا توجد	نماذج مستضافة في الاتحاد الأوروبي
	Perplexity	الدفع حسب الاستخدام	لا توجد	البحث المعزّز
	Together AI	الدفع حسب الاستخدام	لا توجد	النماذج مفتوحة المصدر
	Fireworks AI	الدفع حسب الاستخدام	لا توجد	صور FLUX السريعة
	Cerebras	الدفع حسب الاستخدام	لا توجد	سرعة على مستوى الرقاقة
	Cohere	الدفع حسب الاستخدام	لا توجد	RAG باستخدام Command R+
	NVIDIA NIM	الدفع حسب الاستخدام	لا توجد	نماذج المؤسسات
	Baidu Qianfan	الدفع حسب الاستخدام	لا توجد	نماذج ERNIE
💰 منخفض التكلفة	GLM-4.7	$0.6/1M	يوميًا الساعة 10 صباحًا	خيار احتياطي اقتصادي
	MiniMax M2.1	$0.2/1M	متجدد كل 5 ساعات	الخيار الأرخص
	Kimi K2	$9/شهريًا بسعر ثابت	10M رمز/شهريًا	تكلفة قابلة للتوقع
🆓 مجاني	Qoder	$0	تُطبّق حدود مزوّد الخدمة	تحقّق من القائمة الحالية
	Kiro	$0	نحو 50 رصيدًا/شهريًا	Claude مجانًا

---

🎯 حالات الاستخدام

الحالة 1: "لدي اشتراك Claude Pro"

المشكلة: تنتهي صلاحية الحصة من دون استخدامها، وتظهر حدود المعدل أثناء البرمجة المكثفة

التوليفة: "maximize-claude"
  1. cc/claude-opus-4-7        (استخدام الاشتراك بالكامل)
  2. glm/glm-4.7               (خيار احتياطي رخيص عند نفاد الحصة)
  3. if/qwen3.8-max-preview       (خيار احتياطي مجاني للطوارئ)

التكلفة الشهرية: $20 (الاشتراك) + نحو $5 (الخيار الاحتياطي) = إجمالي $25
مقابل $20 + بلوغ الحدود = إحباط

الحالة 2: "أريد تكلفة صفرية"

المشكلة: لا أستطيع تحمّل تكلفة الاشتراكات، وأحتاج إلى ذكاء اصطناعي موثوق للبرمجة

التوليفة: "zero-cost"
  1. if/kimi-k2.7-code          (وصول مجاني مُدرج؛ قد تُطبّق حدود المعدل)
  2. kr/qwen3-coder-next        (خيار Kiro الاحتياطي المجاني)

التكلفة الشهرية: $0
الجودة: تحقّق من النموذج والحدود والخصوصية واتفاقية مستوى الخدمة لأعباء عملك

الحالة 3: "أحتاج إلى البرمجة على مدار الساعة طوال أيام الأسبوع، بلا انقطاع"

المشكلة: لدي مواعيد نهائية، ولا يمكنني تحمّل فترات التوقف

التوليفة: "always-on"
  1. cc/claude-opus-4-7        (أفضل جودة)
  2. cx/gpt-5.5                (اشتراك ثانٍ)
  3. glm/glm-4.7               (رخيص، ويُعاد تعيينه يوميًا)
  4. minimax/MiniMax-M2.1      (الأرخص، ويُعاد تعيينه كل 5 ساعات)
  5. if/deepseek-v4-flash       (وصول مجاني مُدرج؛ قد تُطبّق حدود المعدل)

النتيجة: توسّع 5 طبقات احتياطية نطاق المرونة؛ ولا يمكن ضمان توافر الخدمات الأساسية
التكلفة الشهرية: $20-200 (الاشتراكات) + $10-20 (الخيار الاحتياطي)

الحالة 4: "أريد ذكاءً اصطناعيًا مجانيًا في OpenClaw"

المشكلة: أحتاج إلى مساعد ذكاء اصطناعي في تطبيقات المراسلة، مجانًا بالكامل

التوليفة: "openclaw-free"
  1. if/qwen3.8-max-preview     (وصول مجاني مُدرج؛ قد تُطبّق حدود المعدل)
  2. if/deepseek-v4-flash       (وصول مجاني مُدرج؛ قد تُطبّق حدود المعدل)
  3. if/kimi-k2.7-code          (وصول مجاني مُدرج؛ قد تُطبّق حدود المعدل)

التكلفة الشهرية: $0
الوصول عبر: WhatsApp، Telegram، Slack، Discord، iMessage، Signal...

---

📖 إعداد مزوّدي الخدمة

لإضافة اتصالات مفاتيح API بشكل جماعي من ملف CSV أو JSON، استخدم لوحة التحكم → مزوّدو الخدمة → استيراد من ملف. ترتيب الأعمدة ثابت (provider,name,apiKey,baseUrl,priority)؛ ويجب أن تكون قيمة provider موجودة مسبقًا كمزوّد مُدار أو كعقدة متوافقة. راجع استيراد مزوّدي الخدمة من ملف CSV أو JSON.

🔐 مزوّدو الاشتراكات

Claude Code (Pro/Max)

لوحة التحكم → مزوّدو الخدمة → ربط Claude Code
→ تسجيل الدخول عبر OAuth → تحديث الرمز المميز تلقائيًا
→ تتبّع الحصة كل 5 ساعات + أسبوعيًا

النماذج:
  cc/claude-opus-4-7
  cc/claude-sonnet-4-6
  cc/claude-haiku-4-5-20251001

نصيحة احترافية: استخدم Opus للمهام المعقدة وSonnet للسرعة. يتتبّع OmniRoute الحصة لكل نموذج!

تحافظ مسارات Claude والمسارات المتوافقة مع Claude Code على مستوى جهد التفكير max لنماذج Opus وSonnet. لا تقبل نماذج Haiku مستوى الجهد max، لذلك يخفض OmniRoute ذلك الطلب إلى ميزانية تفكير عالية قبل إرساله إلى المزوّد الرئيسي.

OpenAI Codex (Plus/Pro)

لوحة التحكم → مزوّدو الخدمة → ربط Codex
→ تسجيل الدخول عبر OAuth (المنفذ 1455)
→ إعادة تعيين كل 5 ساعات + أسبوعيًا

النماذج:
  cx/gpt-5.5
  cx/gpt-5.4
  cx/gpt-5.3-codex
  cx/gpt-5.3-codex-spark

GitHub Copilot

لوحة التحكم → مزوّدو الخدمة → ربط GitHub
→ المصادقة عبر OAuth من خلال GitHub
→ إعادة تعيين شهرية (في اليوم الأول من الشهر)

النماذج:
  gh/gpt-5.5
  gh/gpt-5.4
  gh/claude-sonnet-4.6
  gh/claude-opus-4.7
  gh/gemini-3.1-pro-preview

💰 مزوّدو الخدمة منخفضو التكلفة

GLM-4.7 (إعادة تعيين يومية، $0.6/1M)

1. سجّل: Zhipu AI
2. احصل على مفتاح API من Coding Plan
3. لوحة التحكم → إضافة مفتاح API: مزوّد الخدمة: glm، مفتاح API: your-key

الاستخدام: glm/glm-4.7 — نصيحة احترافية: توفّر Coding Plan حصة أكبر بمقدار 3× مقابل 1/7 من التكلفة! تُعاد التعيئة يوميًا الساعة 10:00 صباحًا.

MiniMax M2.1 (إعادة تعيين كل 5 ساعات، $0.20/1M)

1. سجّل: MiniMax
2. احصل على مفتاح API ← لوحة التحكم ← إضافة مفتاح API

الاستخدام: minimax/MiniMax-M2.1 — نصيحة احترافية: الخيار الأقل تكلفة للسياق الطويل (مليون رمز مميز)!

Kimi K2 (اشتراك ثابت بقيمة $9 شهريًا)

1. اشترك: Moonshot AI
2. احصل على مفتاح API ← لوحة التحكم ← إضافة مفتاح API

الاستخدام: kimi/kimi-k2.5 — نصيحة احترافية: اشتراك ثابت بقيمة $9 شهريًا مقابل 10 ملايين رمز مميز = تكلفة فعلية قدرها $0.90/1M!

Baidu Qianfan / ERNIE

1. سجّل: Baidu AI Cloud Qianfan
2. أنشئ مفتاح API لـ Qianfan ← لوحة التحكم ← إضافة مفتاح API: مزوّد الخدمة: qianfan

الاستخدام: qianfan/ernie-5.1 أو qianfan/ernie-x1.1 أو معرّف نموذج آخر من Qianfan متوافق مع OpenAI.

🆓 مزوّدو الخدمة المجانيون

تتضمن مزوّدات الخدمة المجانية التي لا تتطلب مصادقة مفتاح تبديل بجانب لا تتطلب مصادقة في صفحة كل مزوّد. يؤدي إيقافه إلى تعطيل مزوّد الخدمة، وإزالته من عرضي مزوّدي الخدمة المُهيّئين والمختصرين، وإزالة نماذجه من /v1/models.

Qoder (9 نماذج مجانية)

لوحة التحكم → ربط Qoder → تسجيل الدخول عبر OAuth → يخضع الوصول للحدود الحالية لمزوّد الخدمة

النماذج: if/qwen3.8-max-preview, if/qwen3.7-max, if/qwen3.7-plus, if/kimi-k3, if/kimi-k2.7-code, if/glm-5.2, if/deepseek-v4-pro, if/deepseek-v4-flash, if/minimax-m3

Kiro (Claude مجانًا)

لوحة التحكم → ربط Kiro → AWS Builder ID أو Google/GitHub → نحو 50 رصيدًا شهريًا

النماذج: kr/claude-sonnet-4.5, kr/claude-haiku-4.5

---

🎨 التركيبات

يمكنك إعادة ترتيب بطاقات التركيبات مباشرةً في لوحة التحكم → التركيبات عن طريق سحب المقبض الموجود على كل بطاقة. يُخزَّن الترتيب في SQLite ويُستعاد عند إعادة التحميل.

المثال 1: تعظيم الاستفادة من الاشتراك → نسخة احتياطية رخيصة

لوحة التحكم → التركيبات → إنشاء جديد

الاسم: premium-coding
النماذج:
  1. cc/claude-opus-4-7 (النموذج الأساسي ضمن الاشتراك)
  2. glm/glm-4.7 (نسخة احتياطية رخيصة، $0.6/1M)
  3. minimax/MiniMax-M2.7 (الخيار الاحتياطي الأرخص، $0.3/1M)

الاستخدام في CLI: premium-coding

المثال 2: مجاني فقط (دون تكلفة)

الاسم: free-combo
النماذج:
  1. if/kimi-k2.7-code (مدرج بوصول مجاني؛ قد تُطبَّق حدود المزوّد)
  2. kr/qwen3-coder-next (خيار Kiro الاحتياطي المجاني)

التكلفة: مدرجة حاليًا بقيمة $0؛ قد تتغير الشروط والإتاحة

---

🔧 تكامل CLI

Cursor IDE

استخدام Cursor كعميل OmniRoute (توجيه دردشة Cursor عبر OmniRoute):

الإعدادات → النماذج → متقدم:
  عنوان URL الأساسي لـ OpenAI API: http://localhost:20128/v1
  مفتاح OpenAI API: [من لوحة تحكم omniroute]
  النموذج: cc/claude-opus-4-7

استخدام OmniRoute كمزوّد لـ Cursor (يستدعي OmniRoute خدمة Cursor المصدرية): يُفضَّل استخدام لوحة التحكم → المزوّدون → Cursor → تسجيل الدخول باستخدام Cursor. في Docker، راجع docs/providers/CURSOR-DOCKER.md.

Claude Code

عدّل ~/.claude/settings.json:

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:20128",
    "ANTHROPIC_AUTH_TOKEN": "your-omniroute-api-key"
  }
}

استخدم هنا نقطة النهاية الجذرية المتوافقة مع Claude. لا تُلحق /v1 بـ ANTHROPIC_BASE_URL.

Codex CLI

export OPENAI_BASE_URL="http://localhost:20128"
export OPENAI_API_KEY="your-omniroute-api-key"
codex "your prompt"

OpenClaw

عدّل ~/.openclaw/openclaw.json:

{
  "agents": {
    "defaults": {
      "model": { "primary": "omniroute/if/kimi-k2.7-code" }
    }
  },
  "models": {
    "providers": {
      "omniroute": {
        "baseUrl": "http://localhost:20128/v1",
        "apiKey": "your-omniroute-api-key",
        "api": "openai-completions",
        "models": [{ "id": "if/kimi-k2.7-code", "name": "Kimi K2.7 Code" }]
      }
    }
  }
}

أو استخدم لوحة التحكم: أدوات CLI → OpenClaw → الإعداد التلقائي

Cline / Continue / RooCode

المزوّد: متوافق مع OpenAI
عنوان URL الأساسي: http://localhost:20128/v1
مفتاح API: [من لوحة التحكم]
النموذج: cc/claude-opus-4-7

---

🚀 النشر

التثبيت العام عبر npm (موصى به)

npm install -g omniroute

# إنشاء دليل الإعدادات
mkdir -p ~/.omniroute

# إنشاء ملف .env (راجع .env.example)
cp .env.example ~/.omniroute/.env

# بدء تشغيل الخادم
omniroute
# أو باستخدام منفذ مخصص:
omniroute --port 3000

تحمّل CLI ملف .env تلقائيًا من ~/.omniroute/.env أو ./.env.

وضع صينية النظام

شغّل OmniRoute في صينية النظام:

omniroute serve --tray

ينتهي الأمر بعد أن يصبح الخادم وصينية النظام جاهزين.

يستمر الخادم في العمل من دون الطرفية.

يدعم وضع صينية النظام macOS وWindows وجلسات Linux الرسومية. لا يفتح وضع صينية النظام لوحة التحكم تلقائيًا.

استخدم قائمة صينية النظام لتنفيذ الإجراءات التالية:

• فتح لوحة التحكم.
• فتح /dashboard/logs.
• تغيير إعداد التشغيل التلقائي.
• إيقاف OmniRoute.

لا تستخدم --tray مع الخيارات التالية:

• --daemon
• --log
• --no-recovery

تتطلب هذه الأوضاع ملكية مختلفة للعملية.

فعّل التشغيل عند تسجيل الدخول التالي إلى الجهاز:

omniroute autostart enable

يستخدم التشغيل التلقائي وضع صينية النظام على macOS وWindows وجلسات Linux الرسومية. يستخدم Linux دون واجهة رسومية خدمة مستخدم systemd الحالية.

عطّل التشغيل عند تسجيل الدخول:

omniroute autostart disable

إلغاء التثبيت

عندما لا تعود بحاجة إلى OmniRoute، نوفر نصَّيْن برمجيَّيْن سريعين للإزالة النظيفة:

الأمر	الإجراء
npm run uninstall	يزيل تطبيق النظام، لكنه يحتفظ بقاعدة بياناتك وإعداداتك في ~/.omniroute.
npm run uninstall:full	يزيل التطبيق ويمحو نهائيًا جميع الإعدادات والمفاتيح وقواعد البيانات.

ملاحظة: لتشغيل هذه الأوامر، انتقل إلى مجلد مشروع OmniRoute (إذا كنت قد استنسخته) ثم شغّلها. بدلاً من ذلك، إذا كان مثبتًا بشكل عام، فيمكنك ببساطة تشغيل npm uninstall -g omniroute.

النشر على VPS

git clone https://github.com/diegosouzapw/OmniRoute.git
cd OmniRoute && npm install && npm run build

export JWT_SECRET="your-secure-secret-change-this"
export INITIAL_PASSWORD="your-password"
export DATA_DIR="/var/lib/omniroute"
export PORT="20128"
export HOSTNAME="0.0.0.0"
export NODE_ENV="production"
export NEXT_PUBLIC_BASE_URL="http://localhost:20128"
export API_KEY_SECRET="endpoint-proxy-api-key-secret"

npm run start
# أو: pm2 start npm --name omniroute -- start

النشر باستخدام PM2 (ذاكرة منخفضة)

بالنسبة إلى الخوادم ذات ذاكرة RAM المحدودة، استخدم خيار حد الذاكرة:

# بحدّ 512MB (الافتراضي)
pm2 start npm --name omniroute -- start

# أو بحد ذاكرة مخصص
OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start

# أو باستخدام ecosystem.config.js
pm2 start ecosystem.config.js

أنشئ ecosystem.config.js:

module.exports = {
  apps: [
    {
      name: "omniroute",
      script: "npm",
      args: "start",
      env: {
        NODE_ENV: "production",
        OMNIROUTE_MEMORY_MB: "512",
        JWT_SECRET: "your-secret",
        INITIAL_PASSWORD: "your-password",
      },
      node_args: "--max-old-space-size=512",
      max_memory_restart: "300M",
    },
  ],
};

Docker

# بناء الصورة (الافتراضي = runner-cli مع codex/claude/droid مثبتة مسبقًا)
docker build -t omniroute:cli .

# الوضع المحمول (موصى به)
docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli

للوضع المتكامل مع المضيف الذي يتضمن ملفات CLI التنفيذية، راجع قسم Docker في الوثائق الرئيسية.

Void Linux (xbps-src)

يمكن لمستخدمي Void Linux تحزيم OmniRoute وتثبيته بشكل أصلي باستخدام إطار عمل الترجمة المتقاطعة xbps-src. يؤدي ذلك إلى أتمتة بناء الإصدار المستقل من Node.js إلى جانب روابط better-sqlite3 الأصلية المطلوبة.

عرض قالب xbps-src

# ملف القالب الخاص بـ 'omniroute'
pkgname=omniroute
version=3.8.0
revision=1
hostmakedepends="nodejs python3 make"
depends="openssl"
short_desc="Universal AI gateway with smart routing for multiple LLM providers"
maintainer="zenobit <zenobit@disroot.org>"
license="MIT"
homepage="https://github.com/diegosouzapw/OmniRoute"
distfiles="https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz"
checksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b
system_accounts="_omniroute"
omniroute_homedir="/var/lib/omniroute"
export NODE_ENV=production
export npm_config_engine_strict=false
export npm_config_loglevel=error
export npm_config_fund=false
export npm_config_audit=false

do_build() {
	# تحديد معمارية وحدة المعالجة المركزية المستهدفة لـ node-gyp
	local _gyp_arch
	case "$XBPS_TARGET_MACHINE" in
		aarch64*) _gyp_arch=arm64 ;;
		armv7*|armv6*) _gyp_arch=arm ;;
		i686*) _gyp_arch=ia32 ;;
		*) _gyp_arch=x64 ;;
	esac

	# 1) تثبيت جميع التبعيات – مع تخطي البرامج النصية
	NODE_ENV=development npm ci --ignore-scripts

	# 2) بناء حزمة Next.js المستقلة
	npm run build

	# 3) نسخ الأصول الثابتة إلى الحزمة المستقلة
	cp -r .next/static .next/standalone/.next/static
	[ -d public ] && cp -r public .next/standalone/public || true

	# 4) ترجمة الرابط الأصلي لـ better-sqlite3
	local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
	(cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")

	# 5) وضع الرابط المترجم داخل الحزمة المستقلة
	local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
	mkdir -p "$_bs3_release"
	cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"

	# 6) إزالة حزم sharp الخاصة بالمعمارية
	rm -rf .next/standalone/node_modules/@img

	# 7) نسخ تبعيات وقت تشغيل pino التي أغفلها التحليل الثابت لـ Next.js:
	for _mod in pino-abstract-transport split2 process-warning; do
		cp -r "node_modules/$_mod" .next/standalone/node_modules/
	done
}

do_check() {
	npm run test:unit
}

do_install() {
	vmkdir usr/lib/omniroute/.next
	vcopy .next/standalone/. usr/lib/omniroute/.next/standalone

	# منع خطاف ما بعد التثبيت من إزالة أدلة موجّه تطبيق Next.js الفارغة
	for _d in \
		.next/standalone/.next/server/app/dashboard \
		.next/standalone/.next/server/app/dashboard/settings \
		.next/standalone/.next/server/app/dashboard/providers; do
		touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
	done

	cat > "${WRKDIR}/omniroute" <<'EOF'
#!/bin/sh
export PORT="${PORT:-20128}"
export DATA_DIR="${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}"
export APP_LOG_TO_FILE="${APP_LOG_TO_FILE:-false}"
mkdir -p "${DATA_DIR}"
exec node /usr/lib/omniroute/.next/standalone/server.js "$@"
EOF
	vbin "${WRKDIR}/omniroute"
}

post_install() {
	vlicense LICENSE
}

متغيرات البيئة

المتغير	القيمة الافتراضية	الوصف
JWT_SECRET	omniroute-default-secret-change-me	سر توقيع JWT (يجب تغييره في بيئة الإنتاج)
INITIAL_PASSWORD	CHANGEME	كلمة مرور تسجيل الدخول الأول
DATA_DIR	~/.omniroute	دليل البيانات (قاعدة البيانات، والاستخدام، والسجلات)
PORT	القيمة الافتراضية لإطار العمل	منفذ الخدمة (20128 في الأمثلة)
HOSTNAME	القيمة الافتراضية لإطار العمل	المضيف الذي يتم الارتباط به (يستخدم Docker القيمة 0.0.0.0 افتراضيًا)
NODE_ENV	القيمة الافتراضية لبيئة التشغيل	اضبطه على production عند النشر
NEXT_PUBLIC_BASE_URL	http://localhost:20128	عنوان URL الأساسي العام الذي يظهر في لوحة المعلومات ويُتاح للخادم (يحل محل BASE_URL القديم)
NEXT_PUBLIC_CLOUD_URL	https://omniroute.dev	عنوان URL الأساسي لنقطة نهاية المزامنة السحابية (يحل محل CLOUD_URL القديم)
API_KEY_SECRET	endpoint-proxy-api-key-secret	سر HMAC لمفاتيح API المُنشأة
REQUIRE_API_KEY	false	فرض استخدام مفتاح API من نوع Bearer على /v1/*
ALLOW_API_KEY_REVEAL	false	السماح لمستخدمي لوحة المعلومات المصادَق عليهم بإظهار القيم الكاملة لمفاتيح API المخزنة عند الطلب
PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES	70	وتيرة تحديث بيانات حدود المزوّد المخزنة مؤقتًا من جانب الخادم؛ تظل أزرار التحديث في الواجهة تشغّل المزامنة اليدوية
DISABLE_SQLITE_AUTO_BACKUP	false	تعطيل لقطات SQLite التلقائية قبل الكتابة/الاستيراد/الاستعادة؛ تظل النسخ الاحتياطية اليدوية متاحة
APP_LOG_TO_FILE	true	تمكين إخراج سجلات التطبيق والتدقيق إلى القرص
AUTH_COOKIE_SECURE	false	فرض سمة Secure على ملف تعريف ارتباط المصادقة (خلف وكيل عكسي يستخدم HTTPS)
CLOUDFLARED_BIN	غير معيّن	استخدام ملف cloudflared ثنائي موجود بدلًا من التنزيل المُدار
CLOUDFLARED_PROTOCOL	http2	بروتوكول النقل للأنفاق السريعة المُدارة (http2 أو quic أو auto)
OMNIROUTE_MEMORY_MB	512	حد ذاكرة الكومة لـ Node.js بالميغابايت
PROMPT_CACHE_MAX_SIZE	50	الحد الأقصى لعدد إدخالات ذاكرة التخزين المؤقت للمطالبات
SEMANTIC_CACHE_MAX_SIZE	100	الحد الأقصى لعدد إدخالات ذاكرة التخزين المؤقت الدلالية

للاطلاع على المرجع الكامل لمتغيرات البيئة، راجع README.

---

📊 النماذج المتاحة

عرض جميع النماذج المتاحة

القائمة أدناه منتقاة من open-sse/config/providerRegistry.ts للإصدار v3.8.0. تتم مزامنة كتالوجات الخدمات السحابية (Gemini وOpenRouter وغيرها) ديناميكيًا — للاطلاع على الكتالوج الكامل والمحدّث، افتح لوحة التحكم → المزوّدون → [المزوّد] → النماذج المتاحة أو استدعِ GET /api/models/catalog.

إذا أصبحت القائمة المضمّنة لأحد المزوّدين قديمة، فاستخدم الاستيراد من /models في تلك الصفحة (أو فعّل المزامنة التلقائية) لجلب الكتالوج المحدّث من المصدر. تم التحقق من ذلك في v3.8.50 لكل من LLM7.io (gemini-3.1-flash-lite) وUncloseAI (solidrust/Hermes-3-Llama-3.1-8B-AWQ)؛ بينما ظل الوصول المجهول إلى Pollinations مقيّدًا من جهة المصدر خلال جولة الاختبار نفسها.

Claude Code (cc/) — مصادقة OAuth لخطتي Pro/Max: cc/claude-opus-4-8، cc/claude-opus-4-7، cc/claude-opus-4-6، cc/claude-opus-4-5-20251101، cc/claude-sonnet-4-6، cc/claude-sonnet-4-5-20250929، cc/claude-haiku-4-5-20251001

Codex (cx/) — مصادقة OAuth لخطتي Plus/Pro: cx/gpt-5.5 (+ مستويات الجهد: gpt-5.5-xhigh، gpt-5.5-high، gpt-5.5-medium، gpt-5.5-low)، cx/gpt-5.4، cx/gpt-5.4-mini، cx/gpt-5.3-codex، cx/gpt-5.3-codex-spark

GitHub Copilot (gh/) — مصادقة OAuth: gh/gpt-5.5، gh/gpt-5.4، gh/gpt-5.4-mini، gh/gpt-5-mini، gh/gpt-5.3-codex، gh/claude-opus-4.7، gh/claude-opus-4.6، gh/claude-opus-4-5-20251101، gh/claude-sonnet-4.6، gh/claude-sonnet-4.5، gh/claude-haiku-4.5، gh/gemini-3.1-pro-preview، gh/gemini-3-flash-preview، gh/oswe-vscode-prime

Kiro (kr/) — مصادقة OAuth مجانية: استخدم الكتالوج المحدّث المعروض ضمن لوحة التحكم → المزوّدون → Kiro → النماذج المتاحة. يعتمد التوفر على الحساب والخطة.

Qoder (if/) — مصادقة OAuth مجانية: if/qwen3.8-max-preview، if/qwen3.7-max، if/qwen3.7-plus، if/kimi-k3، if/kimi-k2.7-code، if/glm-5.2، if/deepseek-v4-pro، if/deepseek-v4-flash، if/minimax-m3

GLM (glm/, glm-cn/, zai/, glmt/) — ‏$0.2–0.6 لكل مليون: glm/glm-5.1، glm/glm-5، glm/glm-5-turbo، glm/glm-4.7، glm/glm-4.7-flash، glm/glm-4.6، glm/glm-4.6v، glm/glm-4.5، glm/glm-4.5v، glm/glm-4.5-air

MiniMax (minimax/, minimax-cn/) — ‏$0.2 لكل مليون: minimax/MiniMax-M2.7، minimax/MiniMax-M2.7-highspeed، minimax/MiniMax-M2.5، minimax/MiniMax-M2.5-highspeed

Kimi (kimi/, kimi-coding/, kimi-coding-apikey/) — ‏$9 شهريًا بسعر ثابت أو حسب الاستخدام: kimi/kimi-k2.6، kimi/kimi-k2.5

DeepSeek (ds/) — مفتاح API: ds/deepseek-v4-pro، ds/deepseek-v4-flash

Groq (groq/) — فائق السرعة: groq/llama-3.3-70b-versatile، groq/meta-llama/llama-4-maverick-17b-128e-instruct، groq/qwen/qwen3-32b، groq/openai/gpt-oss-120b

xAI (xai/) — Grok أصلي: xai/grok-4.3، xai/grok-4.20-multi-agent-0309، xai/grok-4.20-0309-reasoning، xai/grok-4.20-0309-non-reasoning

Mistral (mistral/) — مستضاف في الاتحاد الأوروبي: mistral/mistral-large-latest، mistral/mistral-medium-3-5، mistral/mistral-small-latest، mistral/devstral-latest، mistral/codestral-latest

Perplexity (pplx/) — معزّز بالبحث: pplx/sonar-deep-research، pplx/sonar-reasoning-pro، pplx/sonar-pro، pplx/sonar

Together AI (together/) — مفتوح المصدر: together/meta-llama/Llama-3.3-70B-Instruct-Turbo-Free (مجاني)، together/meta-llama/Llama-Vision-Free، together/deepseek-ai/DeepSeek-R1-Distill-Llama-70B-Free، together/deepseek-ai/DeepSeek-R1، together/Qwen/Qwen3-235B-A22B، together/meta-llama/Llama-4-Maverick-17B-128E-Instruct-FP8

Fireworks AI (fireworks/) — استدلال سريع: fireworks/accounts/fireworks/models/kimi-k2p6، fireworks/accounts/fireworks/models/minimax-m2p7، fireworks/accounts/fireworks/models/qwen3p6-plus، fireworks/accounts/fireworks/models/glm-5p1، fireworks/accounts/fireworks/models/deepseek-v4-pro

Cerebras (cerebras/) — على نطاق الرقاقة: cerebras/zai-glm-4.7، cerebras/gpt-oss-120b

Cohere (cohere/) — موجّه نحو RAG: cohere/command-a-reasoning-08-2025، cohere/command-a-vision-07-2025، cohere/command-a-03-2025، cohere/command-r-08-2024

NVIDIA NIM (nvidia/) — للمؤسسات: nvidia/z-ai/glm-5.1، nvidia/minimaxai/minimax-m2.7، nvidia/google/gemma-4-31b-it، nvidia/mistralai/mistral-small-4-119b-2603، nvidia/mistralai/mistral-large-3-675b-instruct-2512، nvidia/qwen/qwen3.5-397b-a17b، nvidia/deepseek-ai/deepseek-v4-pro، nvidia/openai/gpt-oss-120b، nvidia/nvidia/nemotron-3-super-120b-a12b

Baidu Qianfan (qianfan/) — ERNIE: qianfan/ernie-5.1، qianfan/ernie-5.0-thinking-latest، qianfan/ernie-x1.1

Ollama Cloud (ollama-cloud/): ollama-cloud/deepseek-v4-pro، ollama-cloud/deepseek-v4-flash، ollama-cloud/kimi-k2.6، ollama-cloud/glm-5.1، ollama-cloud/minimax-m2.7، ollama-cloud/gemma4:31b، ollama-cloud/qwen3.5:397b

Gemini (Google Cloud gemini/): تتم مزامنته مباشرةً من Google لكل مفتاح API — لا توجد قائمة ثابتة. اربط مفتاحًا في لوحة التحكم → المزوّدون، ثم استخدم النماذج المتاحة لاستيراد الكتالوج الحالي (مثل gemini/gemini-3-pro وgemini/gemini-3-flash).

مزوّدون متوافقون آخرون (مختارون): cohere، databricks، snowflake، together، vertex، alibaba، alibaba-cn، bedrock (عبر aws-bedrock)، azure-ai، openrouter (كتالوج بالتمرير المباشر)، siliconflow، hyperbolic، huggingface، featherless-ai، cloudflare-ai، scaleway، deepinfra، vercel-ai-gateway، bazaarlink، friendliai، nous-research، reka، volcengine، ai21، gigachat. يحتفظ كل مزوّد بقائمة نماذجه الخاصة في providerRegistry.ts، ويمكن مزامنتها تلقائيًا عندما يوفّر المزوّد نقطة نهاية /models.

ملاحظة حول معرّفات النماذج: يستخدم OmniRoute المعرّفات الأصلية الخاصة بالمزوّد (claude-opus-4-8، gpt-5.5، glm-5.1، MiniMax-M2.7، kimi-k2.5، grok-4.20-0309-reasoning). تتضمن بعض المعرّفات إصدارات منقّطة لأن واجهة API في المصدر تتوقعها بهذه الصيغة. إذا لم يكن أحد النماذج مدرجًا أعلاه، فشغّل omniroute models --search <term> أو استدعِ GET /api/models/catalog للتأكد من توفره.

---

🧩 الميزات المتقدمة

النماذج المخصصة

أضف أي معرّف نموذج إلى أي مزوّد دون انتظار تحديث للتطبيق:

# عبر API
curl -X POST http://localhost:20128/api/provider-models \
  -H "Content-Type: application/json" \
  -d '{"provider": "openai", "modelId": "gpt-5.2", "modelName": "GPT-5.2"}'

# عرض القائمة: curl http://localhost:20128/api/provider-models?provider=openai
# إزالة: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-5.2"

أو استخدم لوحة التحكم: المزوّدون → [المزوّد] → النماذج المخصصة.

ملاحظات:

• تتم إدارة OpenRouter والمزوّدين المتوافقين مع OpenAI/Anthropic من خلال النماذج المتاحة فقط. تنتهي الإضافة اليدوية والاستيراد والمزامنة التلقائية جميعها في قائمة النماذج المتاحة نفسها، لذلك لا يوجد قسم منفصل للنماذج المخصصة لهؤلاء المزوّدين.
• قسم النماذج المخصصة مخصص للمزوّدين الذين لا يتيحون استيراد النماذج المتاحة المُدارة.

ربط بوابات OmniRoute النظيرة

يمكن إضافة بوابة OmniRoute أخرى بوصفها مزوّدًا مخصصًا متوافقًا مع OpenAI. استخدم عنوان URL الأساسي /v1 الخاص بالبوابة النظيرة ومفتاح API مخصصًا بأدنى قدر من الصلاحيات صادرًا عن تلك البوابة.

بالنسبة إلى السلاسل المتبادلة أو متعددة القفزات، فعّل حماية الحلقات الاختيارية على كل بوابة:

# gateway-a
OMNIROUTE_INSTANCE_ID=gateway-a
OMNIROUTE_PEER_URLS=http://gateway-b:20128/v1
OMNIROUTE_PEER_MAX_HOPS=4

# gateway-b
OMNIROUTE_INSTANCE_ID=gateway-b
OMNIROUTE_PEER_URLS=http://gateway-a:20128/v1
OMNIROUTE_PEER_MAX_HOPS=4

لا تتلقى ترويسة X-OmniRoute-Peer-Trace إلا الطلبات المرسلة إلى عنوان URL لنظير مُدرج صراحةً في قائمة السماح. ترفض البوابة معرّف مثيل مكررًا أو استنفاد ميزانية القفزات باستخدام HTTP 508 Loop Detected؛ ولا تتلقى المزوّدات الاعتيادية في المنبع أي بيانات وصفية عن النظراء.

ربط النظراء ليس نسخًا متماثلًا لقاعدة البيانات ولا تجاوزًا لفشل المضيف. تحتفظ كل بوابة بحالة SQLite وذاكرات التخزين المؤقت وعدادات المعدل والجلسات بصورة مستقلة. استخدم وكيلًا عكسيًا خاضعًا لفحوصات السلامة أو تجاوز الفشل من جهة العميل لتحقيق الإتاحة النشطة/الخاملة أو النشطة/النشطة، ولا تقم مطلقًا بتركيب قاعدة بيانات SQLite واحدة في عدة مثيلات OmniRoute قيد التشغيل.

مسارات مخصصة للمزوّدين

وجّه الطلبات مباشرةً إلى مزوّد محدد مع التحقق من النموذج:

POST http://localhost:20128/v1/providers/openai/chat/completions
POST http://localhost:20128/v1/providers/openai/embeddings
POST http://localhost:20128/v1/providers/fireworks/images/generations

تُضاف بادئة المزوّد تلقائيًا إذا كانت مفقودة. تُرجع النماذج غير المتطابقة 400.

تكوين وكيل الشبكة

# تعيين الوكيل العام
curl -X PUT http://localhost:20128/api/settings/proxy \
  -d '{"global": {"type":"http","host":"proxy.example.com","port":"8080"}}'

# وكيل خاص بكل مزوّد
curl -X PUT http://localhost:20128/api/settings/proxy \
  -d '{"providers": {"openai": {"type":"socks5","host":"proxy.example.com","port":"1080"}}}'

# اختبار الوكيل
curl -X POST http://localhost:20128/api/settings/proxy/test \
  -d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}'

الأسبقية: خاص بالمفتاح → خاص بالمجموعة → خاص بالمزوّد → عام → البيئة.

API كتالوج النماذج

curl http://localhost:20128/api/models/catalog

يُرجع النماذج مجمعة حسب المزوّد مع الأنواع (chat، embedding، image).

المزامنة السحابية

• مزامنة المزوّدين والمجموعات والإعدادات عبر الأجهزة
• مزامنة تلقائية في الخلفية مع مهلة زمنية + فشل سريع
• يُفضّل استخدام NEXT_PUBLIC_BASE_URL/NEXT_PUBLIC_CLOUD_URL من جهة الخادم في بيئة الإنتاج

نفق Cloudflare السريع

• متاح في لوحة التحكم → نقاط النهاية لعمليات نشر Docker وغيرها من عمليات النشر ذاتية الاستضافة
• يُنشئ عنوان URL مؤقتًا بالنمط https://*.trycloudflare.com يعيد التوجيه إلى نقطة النهاية الحالية المتوافقة مع OpenAI على /v1
• يؤدي التفعيل الأول إلى تثبيت cloudflared عند الحاجة فقط؛ وتعيد عمليات التشغيل اللاحقة استخدام الملف الثنائي المُدار نفسه
• لا تُستعاد الأنفاق السريعة تلقائيًا بعد إعادة تشغيل OmniRoute أو الحاوية؛ أعد تفعيلها من لوحة التحكم عند الحاجة
• عناوين URL الخاصة بالأنفاق مؤقتة وتتغير في كل مرة توقف فيها النفق أو تشغّله
• تستخدم الأنفاق السريعة المُدارة نقل HTTP/2 افتراضيًا لتجنب تحذيرات مخزن UDP المؤقت المزعجة الخاصة بـ QUIC في الحاويات محدودة الموارد
• عيّن CLOUDFLARED_PROTOCOL=quic أو auto إذا أردت تجاوز اختيار النقل المُدار
• عيّن CLOUDFLARED_BIN إذا كنت تفضّل استخدام ملف cloudflared ثنائي مثبّت مسبقًا بدلًا من التنزيل المُدار
• يمكن إظهار لوحات Cloudflare Quick Tunnel وTailscale Funnel وngrok Tunnel أو إخفاؤها من الإعدادات → المظهر. لا يؤدي إخفاء لوحة إلى إيقاف نفق قيد التشغيل.

ذكاء بوابة LLM (المرحلة 9)

• ذاكرة التخزين المؤقت الدلالية — تخزّن تلقائيًا الاستجابات غير المتدفقة التي تكون فيها temperature=0 (يمكن تجاوزها باستخدام X-OmniRoute-No-Cache: true)
• تفرد الطلبات — تزيل تكرار الطلبات خلال 5 ثوانٍ عبر ترويسة Idempotency-Key أو X-Request-Id
• تتبّع التقدم — أحداث SSE اختيارية من النوع event: progress عبر ترويسة X-OmniRoute-Progress: true

---

ساحة تجارب المترجم

يمكن الوصول إليها عبر لوحة التحكم → المترجم. صحّح الأخطاء وتصور كيفية ترجمة OmniRoute لطلبات API بين المزوّدين.

الوضع	الغرض
ساحة التجارب	حدد تنسيقات المصدر/الهدف، والصق طلبًا، وشاهد الناتج المترجم فورًا
مختبِر المحادثة	أرسل رسائل محادثة مباشرة عبر الوكيل وافحص دورة الطلب/الاستجابة كاملةً
منصة الاختبار	شغّل اختبارات دفعية عبر عدة مجموعات من التنسيقات للتحقق من صحة الترجمة
المراقبة المباشرة	راقب الترجمات في الوقت الفعلي أثناء تدفق الطلبات عبر الوكيل

حالات الاستخدام:

• تصحيح سبب فشل مجموعة محددة من العميل/المزوّد
• التحقق من ترجمة وسوم التفكير واستدعاءات الأدوات وموجّهات النظام ترجمةً صحيحة
• مقارنة اختلافات التنسيق بين OpenAI وClaude وGemini وتنسيقات Responses API

---

استراتيجيات التوجيه

قم بالتكوين عبر لوحة المعلومات → الإعدادات → التوجيه. تعرض لوحة المعلومات الاستراتيجيات الست الأكثر استخدامًا؛ بينما تدعم التركيبات والموجّه التلقائي داخليًا مجموعة أوسع.

الاستراتيجيات الظاهرة في لوحة المعلومات (التوجيه على مستوى الحساب):

الاستراتيجية	الوصف
الملء أولًا	يستخدم الحسابات حسب ترتيب الأولوية — يتولى الحساب الأساسي جميع الطلبات حتى يصبح غير متاح
التناوب الدوري	يتنقل بين جميع الحسابات بحدّ تثبيت قابل للتكوين (الافتراضي: 3 استدعاءات لكل حساب)
P2C (قوة خيارين)	يختار حسابين عشوائيين ويوجّه الطلب إلى الأكثر سلامة بينهما — يوازن الحمل مع مراعاة حالة السلامة
عشوائي	يختار حسابًا عشوائيًا لكل طلب باستخدام خوارزمية خلط Fisher-Yates
الأقل استخدامًا	يوجّه الطلب إلى الحساب ذي أقدم طابع زمني lastUsedAt، ما يوزّع حركة المرور بالتساوي
محسّن التكلفة	يوجّه الطلب إلى الحساب ذي أقل قيمة أولوية، ما يحسّن الاختيار لصالح المزوّدين الأقل تكلفة

استراتيجيات التركيبات والاستراتيجيات التلقائية المتقدمة (قابلة للتكوين لكل تركيبة أو عبر بادئات auto/* — راجع AUTO-COMBO.md):

• priority — ترتيب صارم، ولا يستخدم التناوب الدوري مطلقًا
• weighted — تقسيم متناسب لحركة المرور وفق أوزان كل نموذج
• fill-first — يستنفد النموذج الأول حتى بلوغ الحدود
• round-robin / strict-random / random
• p2c (قوة خيارين)
• least-used وcost-optimized
• auto — يعتمد على الدرجات عبر جميع المرشحين
• lkgp (آخر مزوّد معروف بأنه صالح) — يثبّت التوجيه على آخر مزوّد نجح، ثم يعود إلى القواعد عند الحاجة
• context-optimized — يختار النموذج الذي يمتلك أكبر نافذة سياق متاحة
• context-relay — يربط نماذج السياق الطويل بالتتابع في جولات المتابعة

ترويسة الجلسة الثابتة الخارجية

للحفاظ على ارتباط الجلسة خارجيًا (على سبيل المثال، وكلاء Claude Code/Codex خلف الوكلاء العكسيين)، أرسل:

X-Session-Id: your-session-key

يقبل OmniRoute أيضًا x_session_id ويعيد مفتاح الجلسة الفعلي في X-OmniRoute-Session-Id.

إذا كنت تستخدم Nginx وترسل ترويسات بصيغة تتضمن شرطات سفلية، ففعّل:

underscores_in_headers on;

الأسماء المستعارة للنماذج باستخدام أحرف البدل

أنشئ أنماط أحرف بدل لإعادة تعيين أسماء النماذج:

النمط: claude-sonnet-*     →  الهدف: cc/claude-sonnet-4-6
النمط: gpt-*               →  الهدف: gh/gpt-5.3-codex

تدعم أحرف البدل * (أي عدد من الأحرف) و? (حرفًا واحدًا).

سلاسل الرجوع الاحتياطية

حدّد سلاسل رجوع احتياطية عامة تنطبق على جميع الطلبات:

السلسلة: production-fallback
  1. cc/claude-opus-4-7
  2. gh/gpt-5.3-codex
  3. glm/glm-4.7

---

المرونة وقواطع الدائرة

قم بالتكوين عبر لوحة المعلومات → الإعدادات → المرونة.

يطبّق OmniRoute المرونة على مستوى المزوّد باستخدام خمسة مكوّنات:

1. قائمة انتظار الطلبات وضبط وتيرتها — تنظيم الطلبات على مستوى النظام:

   • الطلبات في الدقيقة (RPM) — الحد الأقصى للطلبات في الدقيقة لكل حساب
   • الحد الأدنى للوقت بين الطلبات — الحد الأدنى للفاصل بالميلي ثانية بين الطلبات
   • الحد الأقصى للطلبات المتزامنة — الحد الأقصى للطلبات المتزامنة لكل حساب

2. فترة تهدئة الاتصال — تكوين حسب نوع المصادقة لاتصال واحد بعد حالات الفشل القابلة لإعادة المحاولة:

   • فترة التهدئة الأساسية — نافذة التهدئة الافتراضية لحالات فشل المصدر القابلة لإعادة المحاولة
   • استخدام تلميحات إعادة المحاولة من المصدر — يلتزم بتلميحات Retry-After أو إعادة الضبط الموثوقة عند توفيرها
   • الحد الأقصى لخطوات التراجع — أقصى مستوى للتراجع الأُسّي عند تكرار حالات الفشل

3. قاطع دائرة المزوّد — يتتبع حالات فشل المزوّد من البداية إلى النهاية، ويصنّف المزوّد على أنه متدهور عند بلوغ حد التحذير المُكوَّن، ويفتح القاطع عند بلوغ حد الفشل المُكوَّن:

   • حد التدهور — عدد حالات فشل المزوّد المتتالية قبل الدخول في حالة DEGRADED
   • حد الفشل — عدد حالات فشل المزوّد المتتالية قبل الدخول في حالة OPEN
   • مهلة إعادة الضبط — النافذة الزمنية قبل اختبار المزوّد مرة أخرى
   • CLOSED (سليم) — تتدفق الطلبات بصورة طبيعية
   • DEGRADED — تستمر الطلبات في التدفق مع تتبع الزيادة في حالات الفشل
   • OPEN — يُحظر المزوّد مؤقتًا بعد تكرار حالات الفشل
   • HALF_OPEN — اختبار ما إذا كان المزوّد قد تعافى

   تبقى حدود المعدل 429 الخاصة بالاتصال ضمن فترة تهدئة الاتصال ولا تُحتسب ضمن قاطع المزوّد.

   تظهر حالة وقت التشغيل لقاطع المزوّد في لوحة المعلومات → السلامة فقط.

4. انتظار فترة التهدئة — إذا كانت جميع الاتصالات المرشحة في فترة تهدئة بالفعل، فيمكن لـ OmniRoute انتظار انتهاء أقرب فترة تهدئة وإعادة محاولة طلب العميل نفسه تلقائيًا.

5. الاكتشاف التلقائي لحد المعدل — عندما يعيد مزوّدو المصدر نوافذ انتظار صريحة، تتجاوز هذه التلميحات فترة تهدئة الاتصال المحلية عند تمكين الإعداد.

نصيحة احترافية: استخدم صفحة السلامة لفحص قواطع المزوّدين النشطة وإعادة ضبطها بعد انقطاع الخدمة. لا تغيّر صفحة المرونة سوى التكوين.

---

تصدير قاعدة البيانات / استيرادها

أدِر النسخ الاحتياطية لقاعدة البيانات في لوحة المعلومات → الإعدادات → النظام والتخزين.

الإجراء	الوصف
تصدير قاعدة البيانات	ينزّل قاعدة بيانات SQLite الحالية كملف .sqlite
تصدير الكل (.tar.gz)	ينزّل أرشيف نسخة احتياطية كاملة يتضمن: قاعدة البيانات، والإعدادات، والمجموعات، واتصالات موفّري الخدمة (من دون بيانات اعتماد)، والبيانات الوصفية لمفاتيح API
استيراد قاعدة البيانات	يرفع ملف .sqlite لاستبدال قاعدة البيانات الحالية. تُنشأ نسخة احتياطية قبل الاستيراد تلقائيًا ما لم يكن DISABLE_SQLITE_AUTO_BACKUP=true

# API: تصدير قاعدة البيانات
curl -o backup.sqlite http://localhost:20128/api/db-backups/export

# API: تصدير الكل (أرشيف كامل)
curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll

# API: استيراد قاعدة البيانات
curl -X POST http://localhost:20128/api/db-backups/import \
  -F "file=@backup.sqlite"

التحقق من صحة الاستيراد: يتم التحقق من سلامة الملف المستورد (فحص pragma في SQLite)، والجداول المطلوبة (provider_connections، وprovider_nodes، وcombos، وapi_keys)، والحجم (بحد أقصى 100 ميغابايت).

حالات الاستخدام:

• ترحيل OmniRoute بين الأجهزة
• إنشاء نسخ احتياطية خارجية للتعافي من الكوارث
• مشاركة الإعدادات بين أعضاء الفريق (تصدير الكل ← مشاركة الأرشيف)

---

لوحة معلومات الإعدادات

تُنظّم صفحة الإعدادات ضمن 7 علامات تبويب لتسهيل التنقل:

علامة التبويب	المحتويات
عام	أدوات تخزين النظام، والسلوك الافتراضي، وإمكانية ظهور نفق نقطة النهاية
المظهر	عناصر التحكم في السمة (فاتحة/داكنة/النظام)، وإمكانية ظهور الشريط الجانبي، ومفاتيح تبديل لوحات بطاقات أنفاق Cloudflare/Tailscale/ngrok
الذكاء الاصطناعي	ميزانية التفكير (تمرير مباشر / إزالة تلقائية / مخصصة / تكيّفية — راجع THINKING_BUDGET.md)، وموجّه النظام العام، وإحصاءات ذاكرة التخزين المؤقت للموجّهات
الأمان	إعدادات تسجيل الدخول/كلمة المرور، والتحكم في الوصول حسب عنوان IP، ومصادقة API للمسار /models، وحظر موفّري الخدمة، والحماية من حقن الموجّهات
التوجيه	استراتيجية التوجيه العامة (الملء أولًا / التناوب الدوري / P2C / عشوائي / الأقل استخدامًا / محسّن التكلفة)، وأسماء النماذج البديلة ذات أحرف البدل، وسلاسل الرجوع الاحتياطي، والإعدادات الافتراضية للمجموعات
المرونة	قائمة انتظار الطلبات، وفترة تهدئة الاتصال، وإعداد قاطع موفّر الخدمة، وسلوك انتظار انتهاء فترة التهدئة
متقدم	إعداد الوكيل العام (HTTP/SOCKS5)، وتجاوزات الوكيل لكل موفّر خدمة

لم يعد القسم «عام» يكرر ملاحظات التسجيل وذاكرة التخزين المؤقت المخصصة للقراءة فقط. تُحفظ إعدادات الاحتفاظ بقاعدة البيانات وتحسينها من خلال /api/settings/database؛ ويستخدم المسح اليدوي لذاكرة التخزين المؤقت DELETE /api/cache. يتم التحكم في الحدود القصوى لصفوف سجلات الطلبات والوكيل بواسطة CALL_LOGS_TABLE_MAX_ROWS وPROXY_LOGS_TABLE_MAX_ROWS.

---

إدارة التكاليف والميزانية

يمكن الوصول إليها عبر لوحة المعلومات ← التكاليف.

علامة التبويب	الغرض
الميزانية	تعيين حدود الإنفاق لكل مفتاح API باستخدام ميزانيات يومية/أسبوعية/شهرية وتتبع فوري
التسعير	عرض إدخالات تسعير النماذج وتعديلها — التكلفة لكل ألف رمز إدخال/إخراج لكل موفّر خدمة

# API: تعيين ميزانية
curl -X POST http://localhost:20128/api/usage/budget \
  -H "Content-Type: application/json" \
  -d '{"keyId": "key-123", "limit": 50.00, "period": "monthly"}'

# API: الحصول على حالة الميزانية الحالية
curl http://localhost:20128/api/usage/budget

تتبع التكلفة: يسجّل كل طلب استخدام الرموز ويحسب التكلفة باستخدام جدول التسعير. اعرض التفاصيل في لوحة المعلومات ← الاستخدام حسب موفّر الخدمة والنموذج ومفتاح API.

---

النسخ النصي للصوت

يدعم OmniRoute النسخ النصي للصوت عبر نقطة النهاية المتوافقة مع OpenAI:

POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data

# مثال باستخدام curl
curl -X POST http://localhost:20128/v1/audio/transcriptions \
  -H "Authorization: Bearer your-api-key" \
  -F "file=@audio.mp3" \
  -F "model=openai/whisper-1"

يمثّل deepgram/nova-3 مسار Deepgram الأصلي ويتطلب مفتاح Deepgram API. إذا كان OpenRouter وحده معدًا، فاستخدم openrouter/deepgram/nova-3.

موفّرو تحويل الكلام إلى نص (النسخ النصي):

• openai/ (متوافق مع whisper)
• groq/ (Groq Whisper Turbo)
• deepgram/ (عائلة Nova)
• assemblyai/
• nvidia/ (Parakeet، وCanary)
• huggingface/ (تنويعات whisper)
• qwen/

موفّرو تحويل النص إلى كلام (POST /v1/audio/speech):

• openai/ (tts-1، وtts-1-hd)
• hyperbolic/
• deepgram/ (Aura)
• nvidia/ (Magpie TTS)
• elevenlabs/
• huggingface/
• inworld/
• cartesia/
• playht/
• kie/
• aws-polly/
• xiaomi-mimo/
• coqui/، وtortoise/
• qwen/

تنسيقات الصوت المدعومة للنسخ النصي: mp3، وwav، وm4a، وflac، وogg، وwebm. تعتمد تنسيقات إخراج TTS على موفّر الخدمة (mp3، وwav، وopus، وpcm، وmulaw).

---

استراتيجيات موازنة المجموعات

اضبط الموازنة لكل مجموعة من خلال لوحة المعلومات ← المجموعات ← إنشاء/تحرير ← الاستراتيجية.

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

يمكن ضبط الإعدادات الافتراضية العامة للمجموعات من لوحة المعلومات ← الإعدادات ← التوجيه ← الإعدادات الافتراضية للمجموعات. ترث مُهل أهداف المجموعة مهلة الطلب الحالية افتراضيًا. استخدم مهلة الهدف (بالثواني) في الإعدادات الافتراضية للمجموعات أو في مجموعة فردية فقط عندما ينبغي لحد أقصر لكل هدف تشغيل الانتقال إلى البديل بسرعة أكبر.

تحسينات المجموعة عديمة زمن الاستجابة اختيارية. اترك تحسينات زمن الاستجابة الصفري معطّلة لمنع ميزات زمن الاستجابة هذه من تسابق الأهداف البديلة، أو تخطي الأهداف استنادًا إلى سجل TTFT، أو ضغط طلبات الانتقال إلى البديل؛ ويتيح تمكينها التحوّط المضبوط، وعمليات التخطي التنبؤية وفق TTFT، والضغط الاستباقي للانتقال إلى البديل، وذلك لاستبدال بعض دقة التوجيه/الطلبات بزمن استجابة أقل في الحالات القصوى.

عطّل المخزن المؤقت لرموز الاستدلال عندما يطلب المزوّدون المصدر قواعد صارمة لحدود max_tokens / maxOutputTokens. عند تمكينه، لا يضيف توجيه المجموعة هامشًا إضافيًا لنماذج الاستدلال إلا للنماذج ذات حد إخراج معروف، ويترك حد رموز العميل دون تغيير عندما تتجاوز القيمة الآمنة ذات المخزن المؤقت ذلك الحد. إذا كان حد العميل أعلى بالفعل من حد معروف، فإن OmniRoute يخفضه إلى ذلك الحد قبل إرسال الطلب إلى المزوّد المصدر.

---

لوحة معلومات الصحة

يمكن الوصول إليها عبر لوحة المعلومات ← الصحة. نظرة عامة آنية على صحة النظام تتضمن 6 بطاقات:

البطاقة	ما تعرضه
حالة النظام	مدة التشغيل، والإصدار، واستخدام الذاكرة، ودليل البيانات
صحة المزوّد	حالة تشغيل قاطع الدائرة العام للمزوّد
حدود المعدل	فترات التهدئة النشطة للاتصالات لكل حساب مع الوقت المتبقي
عمليات الحظر النشطة	عمليات الحظر النشطة الخاصة بالنماذج والاستبعادات المؤقتة
ذاكرة التخزين المؤقت للتوقيعات	إحصاءات ذاكرة التخزين المؤقت لإزالة التكرار (المفاتيح النشطة، معدل الإصابات)
قياس زمن الاستجابة	تجميع زمن الاستجابة p50/p95/p99 لكل مزوّد

نصيحة احترافية: تُحدّث صفحة الصحة تلقائيًا كل 10 ثوانٍ. استخدم بطاقة قاطع الدائرة لتحديد المزوّدين الذين يواجهون مشكلات.

---

🤖 التوجيه التلقائي (دون إعداد)

يأتي OmniRoute مزودًا بموجّه تلقائي قائم على الدرجات يختار أفضل نموذج لكل طلب عبر جميع المزوّدين المتصلين — دون الحاجة إلى صيانة أي تركيبة. ما عليك سوى إرسال الطلب باستخدام إحدى بادئات auto/*، وسيُنشئ OmniRoute تركيبة افتراضية ديناميكيًا، مع تقييم المرشحين بناءً على زمن الاستجابة والتكلفة ومعدل النجاح وملاءمة السياق ومدى ملاءمة النموذج للمهمة والإخفاقات الأخيرة والحصة وحالة قاطع الدائرة.

البادئة	ما تعمل على تحسينه
auto	الإعداد الافتراضي المتوازن (زمن الاستجابة × التكلفة × معدل النجاح)
auto/coding	مهام البرمجة: يفضّل Claude وGPT-5 وGLM وKimi وQwen Coder ونماذج DeepSeek البرمجية
auto/cheap	أقل تكلفة لكل رمز، مع قبول زمن استجابة أعلى
auto/fast	أقل زمن استجابة، مع تجاهل التكلفة
auto/offline	المزوّدون المحليون فقط (Ollama وvLLM وllama.cpp) — مفيد للبيئات المعزولة عن الشبكة
auto/smart	جودة الاستدلال أولًا (Opus وGPT-5 xhigh وR1 واستدلال GLM 5.1)
auto/lkgp	"آخر مزوّد معروف بأنه يعمل جيدًا" — يثبّت آخر مزوّد ناجح، ثم يعود إلى القواعد عند الحاجة

مثال:

curl -X POST http://localhost:20128/v1/chat/completions \
  -H "Authorization: Bearer $OMNIROUTE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto/coding",
    "messages": [{ "role": "user", "content": "Refactor this Python function" }],
    "stream": true
  }'

يُشرَح الموجّه التلقائي بالكامل في AUTO-COMBO.md — بما في ذلك كيفية ضبط أوزان التقييم، وإدراج المزوّدين في القائمة السوداء، وفحص قرارات التوجيه ضمن لوحة المعلومات → التركيبة التلقائية.

---

🔌 تكامل MCP وA2A

يعمل OmniRoute بوصفه خادم MCP (بروتوكول سياق النموذج) وخادم A2A (اتصال وكيل إلى وكيل باستخدام JSON-RPC 2.0). يمكن لأي بيئة تطوير متكاملة أو مضيف وكيل متوافق مع MCP استدعاء أدوات OmniRoute مباشرةً — دون الحاجة إلى غلاف إضافي.

وسائل نقل MCP

• SSE: http://localhost:20128/api/mcp/sse
• HTTP القابل للبث: http://localhost:20128/api/mcp/stream
• stdio: omniroute --mcp (لملحقات بيئات التطوير المتكاملة التي تفضّل stdio)

توصيل Claude Desktop

حرّر ~/Library/Application Support/Claude/claude_desktop_config.json على macOS أو الملف المكافئ على Windows/Linux:

{
  "mcpServers": {
    "omniroute": {
      "command": "omniroute",
      "args": ["--mcp"]
    }
  }
}

توصيل Cursor / Continue / VS Code MCP

استخدم عنوان URL الخاص بـSSE، وهو http://localhost:20128/api/mcp/sse، ومفتاح واجهة API من نوع Bearer تم إنشاؤه ضمن لوحة المعلومات → مفاتيح API.

النطاقات

يعرّف MCP حاليًا 32 نطاقًا مسمّى. يمكن تقييد كل مفتاح Bearer بنطاقات محددة — راجع MCP-SERVER.md للاطلاع على القائمة المرجعية للنطاقات والأدوات، وA2A-SERVER.md للاطلاع على مخطط JSON-RPC.

---

🧠 نظام المهارات

يوفّر OmniRoute إطار عمل قابلًا للتوسعة للمهارات (src/lib/skills/) كي تتمكن الوكلاء ونقطة نهاية A2A من تشغيل إجراءات خاصة بمجالات محددة (مثل code-review وsummarize وextract-facts وweb-research).

• واجهة سوق المهارات — تصفّح المهارات وثبّتها من لوحة التحكم → المهارات
• نطاقات مخصّصة لكل مفتاح — قيّد المهارات التي يمكن لكل مفتاح API استدعاؤها
• مهارات مخصّصة — ضع ملف TypeScript في src/lib/a2a/skills/، وسجّله، وسيصبح قابلًا للاستدعاء فورًا عبر A2A

المرجع الكامل: SKILLS.md.

---

💾 نظام الذاكرة

يحتفظ OmniRoute بذاكرة محادثات طويلة الأمد باستخدام استرجاع هجين:

• SQLite FTS5 للبحث بالكلمات المفتاحية في التفاعلات السابقة
• مخزن Qdrant للمتجهات (اختياري) للاسترجاع الدلالي
• استخراج تلقائي للحقائق — تُلخّص الكيانات والتفضيلات والقرارات بعد كل جلسة وتُخزّن في جدول memory_facts
• تُعزل الذكريات حسب كل مفتاح API وكل جلسة

أدِر الذكريات من لوحة التحكم → الذاكرة (البحث والتعديل والتصدير والحذف النهائي). تتيح واجهة HTTP (/api/memory/*) للوكلاء إرسال الحقائق والاستعلام عنها برمجيًا — راجع MEMORY.md.

---

🔔 خطافات الويب

اشترك في أحداث OmniRoute للمراقبة والأتمتة في الوقت الفعلي.

• أنشئ خطاف ويب في لوحة التحكم → خطافات الويب مع عنوان URL المستهدف وسر توقيع HMAC
• الأحداث المتاحة: request.completed وrequest.failed وprovider.unavailable وbudget.exceeded وcombo.switched وcircuit_breaker.opened وcircuit_breaker.closed
• تتضمن كل حمولة X-OmniRoute-Signature ‏(HMAC-SHA256) للتحقق
• إعادة المحاولة: 3 محاولات مع تراجع أُسّي، ثم النقل إلى قائمة الرسائل غير القابلة للتسليم

المخطط الكامل في WEBHOOKS.md.

---

☁️ الوكلاء السحابيون

يتكامل OmniRoute مع وكلاء البرمجة السحابيين (OpenAI Codex Cloud وDevin وJules وAntigravity) بحيث يمكنك إرسال المهام طويلة الأمد من لوحة التحكم نفسها التي تدير التوجيه المحلي.

• أنشئ المهام في لوحة التحكم → الوكلاء السحابيون أو عبر POST /api/v1/agents/tasks
• تتبّع الحالة والسجلات والمخرجات لكل مهمة
• استخدم مفتاح API خاصًا بك لكل مزوّد — لا تغادر بيانات الاعتماد مثيل OmniRoute أبدًا

المرجع الكامل: CLOUD_AGENT.md.

---

🛠️ الإدارة البرمجية

يمكنك إدارة كل مورد في OmniRoute (المزوّدون والمجموعات والمفاتيح والإعدادات) عبر HTTP باستخدام مفتاح Bearer ذي النطاق manage.

أنشئ المفتاح في لوحة التحكم → مفاتيح API → مفتاح جديد → النطاق: manage، ثم:

# سرد المزوّدين
curl http://localhost:20128/api/providers \
  -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY"

# إضافة اتصال بمزوّد
curl -X POST http://localhost:20128/api/providers \
  -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "provider": "openai", "apiKey": "sk-...", "name": "main" }'

# إنشاء مجموعة
curl -X POST http://localhost:20128/api/combos \
  -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "premium", "strategy": "priority", "models": [{ "model": "cc/claude-opus-4-7" }, { "model": "glm/glm-5.1" }] }'

# سرد/إنشاء مفاتيح API
curl http://localhost:20128/api/keys -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY"
curl -X POST http://localhost:20128/api/keys -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY" \
  -d '{ "name": "ci-bot", "scopes": ["chat"] }'

راجع API_REFERENCE.md للاطلاع على الكتالوج الكامل لنقاط النهاية ومخططات الطلبات/الاستجابات.

---

💻 واجهة سطر الأوامر الداخلية

يتضمن OmniRoute واجهة سطر أوامر داخلية (omniroute …) للإعداد والتشخيص والتحكم في وقت التشغيل. وهي منفصلة عن صفحة "أدوات سطر الأوامر" في لوحة التحكم، التي تهيئ أدوات سطر أوامر تابعة لجهات خارجية (Claude Code وCursor وCodex وCline و…) لكي تتمكن من الاتصال بـ OmniRoute.

omniroute setup                    # معالج تفاعلي (كلمة المرور، والموفرون، والتركيبات)
omniroute setup --non-interactive  # ملائم لبيئات CI
omniroute doctor                   # تشخيصات السلامة (دليل البيانات، وقاعدة البيانات، والموفرون، والمنافذ)
omniroute providers available      # عرض الموفرين المدعومين
omniroute providers list           # عرض الاتصالات المهيأة
omniroute providers test <id>      # اختبار اتصال بموفر مباشرةً
omniroute combos list              # عرض التركيبات
omniroute combos switch <name>     # تعيين التركيبة الافتراضية
omniroute models                   # عرض النماذج المتاحة (--json، --search)
omniroute keys add | list | remove # إدارة مفاتيح API من الطرفية
omniroute backup                   # إنشاء لقطة للإعدادات وقاعدة البيانات
omniroute restore [<timestamp>]    # الاستعادة من لقطة
omniroute health                   # تفاصيل السلامة (قواطع الدارة، وذاكرة التخزين المؤقت، والذاكرة)
omniroute quota                    # استخدام حصة الموفر
omniroute mcp status               # حالة خادم MCP
omniroute a2a status               # حالة خادم A2A
omniroute tunnel list|create|stop  # أنفاق Cloudflare/Tailscale/ngrok
omniroute reset-password           # إعادة تعيين كلمة مرور المسؤول
omniroute --mcp                    # تشغيل خادم MCP عبر stdio
omniroute --port 3000              # تشغيل الخادم على منفذ مخصص

نصيحة: استخدم omniroute doctor --json مع أداة المراقبة لديك لإصدار تنبيهات عند وجود اتصالات غير سليمة بالموفرين.

---

🖥️ تطبيق سطح المكتب (Electron)

يتوفر OmniRoute كتطبيق أصلي لسطح المكتب لأنظمة Windows وmacOS وLinux.

التثبيت

# من دليل electron:
cd electron
npm install

# وضع التطوير (الاتصال بخادم تطوير Next.js قيد التشغيل):
npm run dev

# وضع الإنتاج (يستخدم إصدارًا مستقلًا):
npm start

إنشاء حزم التثبيت

cd electron
npm run build          # المنصة الحالية
npm run build:win      # Windows (.exe NSIS)
npm run build:mac      # macOS (.dmg عام)
npm run build:linux    # Linux (.AppImage)

المخرجات ← electron/dist-electron/

الميزات الرئيسية

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

متغيرات البيئة

المتغير	القيمة الافتراضية	الوصف
OMNIROUTE_PORT	20128	منفذ الخادم
OMNIROUTE_MEMORY_MB	512	حد ذاكرة الكومة لـ Node.js ‏(64–16384 MB)

📖 الوثائق الكاملة: electron/README.md