OmniRoute/docs/i18n/ar/CLAUDE.md

CLAUDE.md (العربية)

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

---

هذا الملف يوفر إرشادات لـ Claude Code (claude.ai/code) عند العمل مع الكود في هذا المستودع.

البداية السريعة

npm install                    # تثبيت التبعيات (توليد .env تلقائيًا من .env.example)
npm run dev                    # خادم التطوير على http://localhost:20128
npm run build                  # بناء الإنتاج (Next.js 16 مستقل)
npm run lint                   # ESLint (0 أخطاء متوقعة؛ التحذيرات موجودة مسبقًا)
npm run typecheck:core         # فحص TypeScript (يجب أن يكون نظيفًا)
npm run typecheck:noimplicit:core  # فحص صارم (لا أي ضمني)
npm run test:coverage          # اختبارات الوحدة + بوابة التغطية (75/75/75/70 — العبارات/الأسطر/الدوال/الفروع)
npm run check                  # lint + اختبار مجتمعة
npm run check:cycles           # اكتشاف الاعتماديات الدائرية

تشغيل الاختبارات

# ملف اختبار فردي (جهاز اختبار Node.js الأصلي — معظم الاختبارات)
node --import tsx/esm --test tests/unit/your-file.test.ts

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

# جميع المجموعات
npm run test:all

للحصول على مصفوفة الاختبار الكاملة، راجع CONTRIBUTING.md → "تشغيل الاختبارات". للحصول على بنية عميقة، راجع AGENTS.md.

---

نظرة عامة على المشروع

OmniRoute — وكيل/موجه AI موحد. نقطة نهاية واحدة، أكثر من 160 مزود LLM، تراجع تلقائي.

الطبقة	الموقع	الغرض
مسارات API	src/app/api/v1/	موجه تطبيق Next.js — نقاط الدخول
المعالجات	open-sse/handlers/	معالجة الطلبات (الدردشة، التضمينات، إلخ)
المنفذون	open-sse/executors/	إرسال HTTP محدد لمزود الخدمة
المترجمون	open-sse/translator/	تحويل التنسيق (OpenAI↔Claude↔Gemini)
المحول	open-sse/transformer/	واجهات برمجة التطبيقات للردود ↔ إكمالات الدردشة
الخدمات	open-sse/services/	توجيه مجموعة، حدود المعدل، التخزين المؤقت، إلخ
قاعدة البيانات	src/lib/db/	وحدات مجال SQLite (أكثر من 45 ملف، 55 ترحيل)
المجال/السياسة	src/domain/	محرك السياسة، قواعد التكلفة، منطق التراجع
خادم MCP	open-sse/mcp-server/	37 أداة (30 قاعدة + 3 ذاكرة + 4 مهارات)، 3 وسائل نقل، ~13 نطاقات
خادم A2A	src/lib/a2a/	بروتوكول وكيل JSON-RPC 2.0
المهارات	src/lib/skills/	إطار عمل مهارات قابل للتوسيع
الذاكرة	src/lib/memory/	ذاكرة محادثة دائمة

Monorepo: src/ (تطبيق Next.js 16)، open-sse/ (مساحة عمل محرك البث)، electron/ (تطبيق سطح المكتب)، tests/، bin/ (نقطة دخول CLI).

---

خط أنابيب الطلب

العميل → /v1/chat/completions (مسار Next.js)
  → CORS → تحقق Zod → مصادقة؟ → فحص السياسة → حماية حقن المطالبات
  → handleChatCore() [open-sse/handlers/chatCore.ts]
    → تحقق من التخزين المؤقت → حد معدل الطلبات → توجيه مجموعة؟
      → resolveComboTargets() → handleSingleModel() لكل هدف
    → translateRequest() → getExecutor() → executor.execute()
      → fetch() upstream → إعادة المحاولة مع التراجع
    → ترجمة الاستجابة → تدفق SSE أو JSON
    → إذا كانت واجهة برمجة التطبيقات Responses: responsesTransformer.ts TransformStream

تتبع مسارات واجهة برمجة التطبيقات نمطًا متسقًا: Route → CORS preflight → Zod body validation → مصادقة اختيارية (extractApiKey/isValidApiKey) → تنفيذ سياسة مفتاح واجهة برمجة التطبيقات → تفويض المعالج (open-sse). لا توجد وسائط عالمية لـ Next.js — الاعتراض خاص بالمسار.

توجيه المجموعة (open-sse/services/combo.ts): 14 استراتيجية (الأولوية، الوزن، ملء أولاً، التناوب، P2C، عشوائي، الأقل استخدامًا، الأمثل من حيث التكلفة، الواعي بإعادة التعيين، عشوائي صارم، تلقائي، lkgp، الأمثل من حيث السياق، نقل السياق). كل هدف يستدعي handleSingleModel() الذي يلف handleChatCore() مع معالجة الأخطاء الخاصة بكل هدف وفحوصات قاطع الدائرة. راجع docs/routing/AUTO-COMBO.md لتسجيل 9 عوامل Auto-Combo و docs/architecture/RESILIENCE_GUIDE.md للطبقات الثلاث من المرونة.

---

حالة وقت التشغيل للمرونة

يمتلك OmniRoute ثلاث آليات فشل مؤقتة مرتبطة ولكن متميزة. حافظ على نطاقها منفصلًا عند تصحيح سلوك التوجيه. راجع مخطط المرونة ذو 3 طبقات (المصدر: docs/diagrams/resilience-3layers.mmd) لخريطة سريعة.

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

النطاق: المزود بالكامل، مثل glm، openai، anthropic.

الغرض: إيقاف إرسال الحركة إلى مزود يفشل بشكل متكرر على مستوى الخدمة/التيار، حتى لا يؤدي مزود غير صحي إلى إبطاء كل طلب.

التنفيذ:

• الفئة الأساسية: src/shared/utils/circuitBreaker.ts
• توصيل بوابة الدردشة/التنفيذ: src/sse/handlers/chatHelpers.ts، src/sse/handlers/chat.ts
• واجهة برمجة التطبيقات لحالة وقت التشغيل: src/app/api/monitoring/health/route.ts
• الأغطية المشتركة: open-sse/services/accountFallback.ts
• جدول الحالة المستمرة: domain_circuit_breakers

الحالات:

• CLOSED: يُسمح بحركة المرور العادية.
• OPEN: تم حظر المزود مؤقتًا؛ يحصل المتصلون على استجابة قاطع دائرة المزود مفتوح أو يتخطى توجيه المجموعة إلى هدف آخر.
• HALF_OPEN: انتهت مهلة إعادة التعيين؛ يسمح بطلب اختبار. النجاح يغلق القاطع، والفشل يفتحه مرة أخرى.

الإعدادات الافتراضية (open-sse/config/constants.ts):

• مزودو OAuth: العتبة 3، مهلة إعادة التعيين 60s.
• مزودو مفتاح واجهة برمجة التطبيقات: العتبة 5، مهلة إعادة التعيين 30s.
• المزودون المحليون: العتبة 2، مهلة إعادة التعيين 15s.

يجب أن تؤدي حالات الفشل على مستوى المزود فقط إلى تفعيل قاطع المزود:

(408, 500, 502, 503, 504);

لا تقم بتفعيل قاطع المزود بالكامل لأخطاء الحساب/المفتاح/النموذج العادية مثل معظم حالات 401، 403، أو 429. عادةً ما تنتمي تلك إلى فترة تبريد الاتصال أو قفل النموذج. يجب أن يكون مزود مفتاح واجهة برمجة التطبيقات العام 403 قابلاً للاسترداد ما لم يتم تصنيفه كخطأ نهائي للمزود/الحساب.

يستخدم القاطع استردادًا كسولًا، وليس مؤقتًا في الخلفية. عندما تنتهي حالة OPEN، فإن عمليات القراءة مثل getStatus(), canExecute(), و getRetryAfterMs() تقوم بتحديث الحالة إلى HALF_OPEN، بحيث لا تستمر لوحات المعلومات وبناة مرشحي المجموعة في استبعاد مزود منتهي الصلاحية إلى الأبد.

فترة تبريد الاتصال

النطاق: اتصال/حساب/مفتاح مزود واحد.

الغرض: تخطي مؤقت لمفتاح/حساب سيئ واحد مع السماح للاتصالات الأخرى لنفس المزود بالاستمرار في تقديم الطلبات.

التنفيذ:

• مسار الكتابة/التحديث: src/sse/services/auth.ts::markAccountUnavailable()
• اختيار/تصفية الحساب: src/sse/services/auth.ts::getProviderCredentials...
• حساب فترة التبريد: open-sse/services/accountFallback.ts::checkFallbackError()
• الإعدادات: src/lib/resilience/settings.ts

الحقول المهمة على اتصالات المزود:

rateLimitedUntil;
testStatus: "unavailable";
lastError;
lastErrorType;
errorCode;
backoffLevel;

أثناء اختيار الحساب، يتم تخطي الاتصال بينما:

new Date(rateLimitedUntil).getTime() > Date.now();

فترات التبريد أيضًا كسولة: عندما تكون rateLimitedUntil في الماضي، يصبح الاتصال مؤهلاً مرة أخرى. عند الاستخدام الناجح، تقوم clearAccountError() بمسح testStatus، rateLimitedUntil، حقول الأخطاء، و backoffLevel.

سلوك فترة تبريد الاتصال الافتراضي:

• فترة تبريد أساسية لمزود OAuth: 5s.
• فترة تبريد أساسية لمزود مفتاح واجهة برمجة التطبيقات: 3s.
• يجب أن يفضل مفتاح واجهة برمجة التطبيقات 429 تلميحات إعادة المحاولة من المصدر (Retry-After، رؤوس إعادة التعيين، أو نص إعادة التعيين القابل للتحليل) عند توفرها.
• تستخدم الفشل القابلة للاسترداد المتكررة التراجع الأسي:

baseCooldownMs * 2 ** failureIndex;

تحمي حراسة مكافحة قطيع الرعد من الفشل المتزامن على نفس الاتصال من تمديد فترة التبريد بشكل متكرر أو زيادة backoffLevel مرتين.

الحالات النهائية ليست فترات تبريد. banned، expired، و credits_exhausted مصممة للبقاء غير متاحة حتى تتغير بيانات الاعتماد/الإعدادات أو يقوم مشغل بإعادة تعيينها. لا تقم بكتابة الحالات النهائية فوق حالة فترة التبريد العابرة.

قفل النموذج

النطاق: المزود + الاتصال + النموذج.

الغرض: تجنب تعطيل اتصال كامل عندما يكون نموذج واحد فقط غير متاح أو محدود الحصة لذلك الاتصال.

أمثلة:

• مزودو الحصة لكل نموذج الذين يعيدون 429.
• مزودون محليون يعيدون 404 لنموذج مفقود واحد.
• فشل إذن وضع/نموذج محدد للمزود مثل أوضاع Grok المختارة.

يعيش قفل النموذج في open-sse/services/accountFallback.ts ويسمح لنفس الاتصال بالاستمرار في تقديم نماذج أخرى.

إرشادات التصحيح

• إذا تم تخطي جميع المفاتيح لمزود، تحقق من حالة قاطع المزود وحالة rateLimitedUntil/testStatus لكل اتصال.
• إذا بدا أن مزودًا ما مستبعدًا بشكل دائم بعد نافذة إعادة التعيين، تحقق مما إذا كان الكود يقرأ state الخام بدلاً من استخدام getStatus()/canExecute().
• إذا فشل مفتاح مزود واحد ولكن يجب أن تعمل المفاتيح الأخرى، يفضل استخدام فترة تبريد الاتصال على قاطع المزود.
• إذا فشل نموذج واحد فقط، يفضل استخدام قفل النموذج على فترة تبريد الاتصال.
• إذا كان يجب أن يتعافى حالة ما ذاتيًا، يجب أن تحتوي على طابع زمني مستقبلي/مهلة إعادة تعيين ومسار قراءة يقوم بتحديث الحالة المنتهية. تتطلب الحالات الدائمة تغييرات يدوية في بيانات الاعتماد أو التكوين.

الاتفاقيات الرئيسية

نمط الكود

• مسافتان، فاصلات منقوطة، علامات اقتباس مزدوجة، عرض 100 حرف، فاصلات متأخرة ES5 (تطبق بواسطة lint-staged عبر Prettier)
• الاستيرادات: خارجي → داخلي (@/, @omniroute/open-sse) → نسبي
• التسمية: الملفات=camelCase/kebab، المكونات=PascalCase، الثوابت=UPPER_SNAKE
• ESLint: no-eval، no-implied-eval، no-new-func = خطأ في كل مكان؛ no-explicit-any = تحذير في open-sse/ و tests/
• TypeScript: strict: false، الهدف ES2022، الوحدة esnext، دقة التجميع. يفضل الأنواع الصريحة.

قاعدة البيانات

• دائمًا مرر عبر وحدات المجال في src/lib/db/ — لا تكتب SQL خام في المسارات أو المعالجات
• لا تضف منطقًا إلى src/lib/localDb.ts (طبقة إعادة تصدير فقط)
• لا تستورد من localDb.ts بشكل مجمع — استورد وحدات db/ المحددة بدلاً من ذلك
• مثيل قاعدة البيانات المفردة: getDbInstance() من src/lib/db/core.ts (تدوين WAL)
• الترحيلات: src/lib/db/migrations/ — ملفات SQL ذات إصدار، متكررة، تعمل في معاملات

معالجة الأخطاء

• try/catch مع أنواع أخطاء محددة، سجل باستخدام سياق pino
• لا تبتلع الأخطاء في تدفقات SSE — استخدم إشارات الإنهاء للتنظيف
• أعد القيم الصحيحة لرموز الحالة HTTP (4xx/5xx)

الأمان

• لا تستخدم eval()، new Function()، أو eval الضمني
• تحقق من جميع المدخلات باستخدام مخططات Zod
• قم بتشفير بيانات الاعتماد عند الراحة (AES-256-GCM)
• قائمة حظر رأس المصدر: src/shared/constants/upstreamHeaders.ts — حافظ على التنظيف، ومخططات Zod، واختبارات الوحدة متوافقة عند التحرير
• بيانات الاعتماد العامة للمصدر (Gemini/Antigravity/Windsurf-style OAuth client_id/secret + مفاتيح Firebase Web المستخرجة من CLIs العامة): يجب تضمينها عبر resolvePublicCred() من open-sse/utils/publicCreds.ts — لا كأدلة نصية. انظر docs/security/PUBLIC_CREDS.md للنمط الإلزامي.
• استجابات الأخطاء (HTTP / SSE / المعالج / MCP): يجب توجيهها عبر buildErrorBody() أو sanitizeErrorMessage() من open-sse/utils/error.ts — لا تضع err.stack أو err.message الخام في جسم الاستجابة. انظر docs/security/ERROR_SANITIZATION.md.
• أوامر الصدفة المبنية من المتغيرات: عند استدعاء exec()/spawn() مع نص يحتاج إلى قيم وقت التشغيل، مررها عبر خيار env (تُهرب تلقائيًا) — لا تدمج مسارات غير موثوقة/خارجية في جسم النص. المرجع: src/mitm/cert/install.ts::updateNssDatabases.
• المكتبات الآمنة بشكل افتراضي (tldrsec/awesome-secure-defaults): يفضل Helmet.js، DOMPurify، ssrf-req-filter، safe-regex، Google Tink على التنفيذات المخصصة كلما تم إضافة أسطح حساسة جديدة للأمان.

---

سيناريوهات التعديل الشائعة

إضافة مزود جديد

1. سجل في src/shared/constants/providers.ts (تم التحقق منه بواسطة Zod عند التحميل)
2. أضف معالج في open-sse/executors/ إذا كانت هناك حاجة إلى منطق مخصص (قم بتمديد BaseExecutor)
3. أضف مترجمًا في open-sse/translator/ إذا كان بتنسيق غير OpenAI
4. أضف تكوين OAuth في src/lib/oauth/constants/oauth.ts إذا كان يعتمد على OAuth — إذا كان CLI المصدر يرسل client_id/secret عام، قم بتضمينه عبر resolvePublicCred() (انظر docs/security/PUBLIC_CREDS.md)، لا كأدلة نصية
5. سجل النماذج في open-sse/config/providerRegistry.ts
6. اكتب اختبارات في tests/unit/ (تضمن تأكيد شكل publicCreds إذا أضفت افتراضيًا جديدًا مضمنًا)

إضافة مسار API جديد

1. أنشئ دليلًا تحت src/app/api/v1/your-route/
2. أنشئ route.ts مع معالجات GET/POST
3. اتبع النمط: CORS → تحقق من صحة جسم Zod → مصادقة اختيارية → تفويض المعالج
4. يذهب المعالج في open-sse/handlers/ (استورد من هناك، وليس داخل السطر)
5. تستخدم استجابات الأخطاء buildErrorBody() / errorResponse() من open-sse/utils/error.ts (تم تنظيفها تلقائيًا — لا تضع err.stack أو err.message الخام في الجسم). انظر docs/security/ERROR_SANITIZATION.md.
6. أضف اختبارات — بما في ذلك على الأقل تأكيد واحد بأن استجابات الأخطاء لا تسرب تتبع المكدس (!body.error.message.includes("at /"))

إضافة وحدة DB جديدة

1. أنشئ src/lib/db/yourModule.ts — استورد getDbInstance من ./core.ts
2. صدر وظائف CRUD لجدول (جداول) المجال الخاص بك
3. أضف ترحيلًا في src/lib/db/migrations/ إذا كانت هناك حاجة إلى جداول جديدة
4. أعد تصدير من src/lib/localDb.ts (أضف إلى قائمة إعادة التصدير فقط)
5. اكتب اختبارات

إضافة أداة MCP جديدة

1. أضف تعريف الأداة في open-sse/mcp-server/tools/ مع مخطط إدخال Zod + معالج غير متزامن
2. سجل في مجموعة الأدوات (موصول بواسطة createMcpServer())
3. عيّن إلى النطاق (النطاقات) المناسبة
4. اكتب اختبارات (تسجيل استدعاء الأداة في جدول mcp_audit)

إضافة مهارة A2A جديدة

1. أنشئ مهارة في src/lib/a2a/skills/ (يوجد 5 بالفعل: التوجيه الذكي، إدارة الحصص، اكتشاف المزود، تحليل التكلفة، تقرير الصحة)
2. تتلقى المهارة سياق المهمة (الرسائل، البيانات الوصفية) → تعيد نتيجة منظمة
3. سجل في A2A_SKILL_HANDLERS في src/lib/a2a/taskExecution.ts
4. اعرض في src/app/.well-known/agent.json/route.ts (بطاقة الوكيل)
5. اكتب اختبارات في tests/unit/
6. وثق في جدول المهارات في docs/frameworks/A2A-SERVER.md

إضافة وكيل سحابي جديد

1. أنشئ فئة وكيل في src/lib/cloudAgent/agents/ تمتد من CloudAgentBase (يوجد 3 بالفعل: codex-cloud، devin، jules)
2. نفذ createTask، getStatus، approvePlan، sendMessage، listSources
3. سجل في src/lib/cloudAgent/registry.ts
4. أضف معالجة OAuth/بيانات الاعتماد إذا لزم الأمر (src/lib/oauth/providers/)
5. اختبارات + وثق في docs/frameworks/CLOUD_AGENT.md

إضافة حواجز جديدة / تقييم / مهارة / حدث Webhook

• الحواجز: src/lib/guardrails/ → الوثائق: docs/security/GUARDRAILS.md
• مجموعة التقييم: src/lib/evals/ → الوثائق: docs/frameworks/EVALS.md
• المهارة (الصندوق الرمل): src/lib/skills/ → الوثائق: docs/frameworks/SKILLS.md
• حدث Webhook: src/lib/webhookDispatcher.ts → الوثائق: docs/frameworks/WEBHOOKS.md

وثائق المرجع

لأي تغيير غير تافه، اقرأ الغوص العميق المطابق أولاً:

المجال	الوثيقة
تنقل المستودع	docs/architecture/REPOSITORY_MAP.md
الهندسة	docs/architecture/ARCHITECTURE.md
مرجع الهندسة	docs/architecture/CODEBASE_DOCUMENTATION.md
Auto-Combo (تقييم 9 عوامل، 14 استراتيجية)	docs/routing/AUTO-COMBO.md
المرونة (3 آليات)	docs/architecture/RESILIENCE_GUIDE.md
إعادة تشغيل التفكير	docs/routing/REASONING_REPLAY.md
إطار المهارات	docs/frameworks/SKILLS.md
نظام الذاكرة (FTS5 + Qdrant)	docs/frameworks/MEMORY.md
وكلاء السحابة	docs/frameworks/CLOUD_AGENT.md
حواجز الأمان (PII / حقن / رؤية)	docs/security/GUARDRAILS.md
بيانات اعتماد عامة (Gemini/إلخ.)	docs/security/PUBLIC_CREDS.md
تطهير رسائل الخطأ	docs/security/ERROR_SANITIZATION.md
التقييمات	docs/frameworks/EVALS.md
الامتثال / التدقيق	docs/security/COMPLIANCE.md
Webhooks	docs/frameworks/WEBHOOKS.md
خط أنابيب التفويض	docs/architecture/AUTHZ_GUIDE.md
التخفي (TLS / بصمة)	docs/security/STEALTH_GUIDE.md
بروتوكولات الوكلاء (A2A / ACP / سحابة)	docs/frameworks/AGENT_PROTOCOLS_GUIDE.md
خادم MCP	docs/frameworks/MCP-SERVER.md
خادم A2A	docs/frameworks/A2A-SERVER.md
مرجع API + OpenAPI	docs/reference/API_REFERENCE.md + docs/reference/openapi.yaml
كتالوج المزودين (تم إنشاؤه تلقائيًا)	docs/reference/PROVIDER_REFERENCE.md
تدفق الإصدار	docs/ops/RELEASE_CHECKLIST.md

الاختبار

ما	الأمر
اختبارات الوحدة	npm run test:unit
ملف واحد	node --import tsx/esm --test tests/unit/file.test.ts
Vitest (MCP, autoCombo)	npm run test:vitest
E2E (Playwright)	npm run test:e2e
بروتوكول E2E (MCP+A2A)	npm run test:protocols:e2e
النظام البيئي	npm run test:ecosystem
بوابة التغطية	npm run test:coverage (75/75/75/70 — العبارات/الأسطر/الدوال/الفروع)
تقرير التغطية	npm run coverage:report

قاعدة PR: إذا قمت بتغيير كود الإنتاج في src/، open-sse/، electron/، أو bin/، يجب عليك تضمين أو تحديث الاختبارات في نفس PR.

تفضيل طبقة الاختبار: الوحدة أولاً → التكامل (حالة متعددة الوحدات أو قاعدة البيانات) → e2e (واجهة المستخدم/سير العمل فقط). قم بتشفير إعادة إنتاج الأخطاء كاختبارات آلية قبل أو بالتزامن مع الإصلاح.

سياسة تغطية Copilot: عندما يغير PR كود الإنتاج وتكون التغطية أقل من 75% (العبارات/الأسطر/الدوال) أو 70% (الفروع)، لا تقم بالإبلاغ فقط — أضف أو قم بتحديث الاختبارات، أعد تشغيل بوابة التغطية، ثم اطلب التأكيد. قم بتضمين الأوامر التي تم تشغيلها، وملفات الاختبار التي تم تغييرها، ونتيجة التغطية النهائية في تقرير PR.

---

سير عمل Git

# لا تقم بالالتزام مباشرة إلى main
git checkout -b feat/your-feature
git commit -m "feat: وصف التغيير الخاص بك"
git push -u origin feat/your-feature

بادئات الفروع: feat/، fix/، refactor/، docs/، test/، chore/

تنسيق الالتزام (Commits التقليدية): feat(db): إضافة قاطع الدائرة — النطاقات: db، sse، oauth، dashboard، api، cli، docker، ci، mcp، a2a، memory، skills

خطافات Husky:

• pre-commit: lint-staged + check-docs-sync + check:any-budget:t11
• pre-push: npm run test:unit

---

البيئة

• وقت التشغيل: Node.js ≥20.20.2 <21 || ≥22.22.2 <23 || ≥24 <25، وحدات ES
• TypeScript: 5.9+، الهدف ES2022، الوحدة esnext، دقة المجمع
• أسماء المسارات: @/* → src/، @omniroute/open-sse → open-sse/، @omniroute/open-sse/* → open-sse/*
• المنفذ الافتراضي: 20128 (API + لوحة التحكم على نفس المنفذ)
• دليل البيانات: متغير البيئة DATA_DIR، الافتراضي هو ~/.omniroute/
• المتغيرات البيئية الرئيسية: PORT، JWT_SECRET، API_KEY_SECRET، INITIAL_PASSWORD، REQUIRE_API_KEY، APP_LOG_LEVEL
• الإعداد: cp .env.example .env ثم توليد JWT_SECRET (openssl rand -base64 48) و API_KEY_SECRET (openssl rand -hex 32)

---

القواعد الصارمة

1. لا تقم بالالتزام بالأسرار أو بيانات الاعتماد
2. لا تضف منطقًا إلى localDb.ts
3. لا تستخدم eval() / new Function() / eval الضمني
4. لا تقم بالالتزام مباشرة إلى main
5. لا تكتب SQL الخام في المسارات — استخدم وحدات src/lib/db/
6. لا تبتلع الأخطاء بصمت في تدفقات SSE
7. تحقق دائمًا من المدخلات باستخدام مخططات Zod
8. قم دائمًا بتضمين الاختبارات عند تغيير كود الإنتاج
9. يجب أن تبقى التغطية ≥75% (العبارات، الأسطر، الدوال) / ≥70% (الفروع). القياس الحالي: ~82%.
10. لا تتجاوز خطافات Husky (--no-verify، --no-gpg-sign) بدون موافقة مشغل صريحة.
11. لا تقم بتضمين client_id/secret العامة من OAuth أو مفاتيح Firebase Web كقيم نصية — دائمًا استخدم resolvePublicCred() (open-sse/utils/publicCreds.ts). انظر docs/security/PUBLIC_CREDS.md.
12. لا تقم بإرجاع err.stack / err.message الخام في HTTP / SSE / استجابات المنفذ — دائمًا قم بتوجيهها عبر buildErrorBody() أو sanitizeErrorMessage() (open-sse/utils/error.ts). انظر docs/security/ERROR_SANITIZATION.md.
13. لا تقم بإدراج مسارات خارجية أو قيم وقت التشغيل في سكربتات الشل المرسلة إلى exec()/spawn() — مرر عبر خيار env بدلاً من ذلك. المرجع: src/mitm/cert/install.ts::updateNssDatabases.
14. لا تتجاهل تنبيه CodeQL / Secret-Scanning بدون (أ) التحقق أولاً من وثائق النمط أعلاه لمعرفة ما إذا كان المساعد ينطبق، و (ب) تسجيل التبرير الفني في تعليق الإلغاء. سابقة: js/stack-trace-exposure التي تم رفعها على مواقع الاتصال التي تمر بالفعل عبر sanitizeErrorMessage() هي قيود معروفة لـ CodeQL (المعقمات المخصصة غير معترف بها) — تجاهل كـ false positive مع الإشارة إلى docs/security/ERROR_SANITIZATION.md.
15. لا تعرض المسارات التي تولد عمليات فرعية (/api/mcp/، /api/cli-tools/runtime/) بدون تصنيف isLocalOnlyPath() في src/server/authz/routeGuard.ts. يتم تنفيذ التحقق من الحلقة بشكل غير مشروط قبل أي تحقق من المصادقة — لا يمكن أن يؤدي تسرب JWT عبر النفق إلى تشغيل العملية. انظر docs/security/ROUTE_GUARD_TIERS.md.
16. لا تضمن أبدًا ملحقات Co-Authored-By التي تنسب لمساعد ذكاء اصطناعي أو LLM أو حساب آلي (مثل الأسماء التي تحتوي على "Claude" أو "GPT" أو "Copilot" أو "Bot"؛ والبريد الإلكتروني على anthropic.com / openai.com / عناوين noreply.github.com المملوكة للبوتات). تلك الملحقات توجه نسبة الالتزامات إلى حساب البوت على GitHub، مما يخفي المؤلف الحقيقي (diegosouzapw) في تاريخ PR. المساهمون البشريون — بما في ذلك مؤلفو PRs upstream ومُبلغو الـ issues الذين يتم نقلهم إلى OmniRoute — يجوز ويجب أن يُنسبوا باستخدام ملحقات Co-authored-by: Name <email> القياسية؛ تعتمد سير عمل النقل (/port-upstream-features و /port-upstream-issues) على ذلك.