# CLAUDE.md (العربية) 🌐 **Languages:** 🇺🇸 [English](../../../CLAUDE.md) · 🇦🇿 [az](../az/CLAUDE.md) · 🇧🇬 [bg](../bg/CLAUDE.md) · 🇧🇩 [bn](../bn/CLAUDE.md) · 🇨🇿 [cs](../cs/CLAUDE.md) · 🇩🇰 [da](../da/CLAUDE.md) · 🇩🇪 [de](../de/CLAUDE.md) · 🇪🇸 [es](../es/CLAUDE.md) · 🇮🇷 [fa](../fa/CLAUDE.md) · 🇫🇮 [fi](../fi/CLAUDE.md) · 🇫🇷 [fr](../fr/CLAUDE.md) · 🇮🇳 [gu](../gu/CLAUDE.md) · 🇮🇱 [he](../he/CLAUDE.md) · 🇮🇳 [hi](../hi/CLAUDE.md) · 🇭🇺 [hu](../hu/CLAUDE.md) · 🇮🇩 [id](../id/CLAUDE.md) · 🇮🇩 [in](../in/CLAUDE.md) · 🇮🇹 [it](../it/CLAUDE.md) · 🇯🇵 [ja](../ja/CLAUDE.md) · 🇰🇷 [ko](../ko/CLAUDE.md) · 🇮🇳 [mr](../mr/CLAUDE.md) · 🇲🇾 [ms](../ms/CLAUDE.md) · 🇳🇱 [nl](../nl/CLAUDE.md) · 🇳🇴 [no](../no/CLAUDE.md) · 🇵🇭 [phi](../phi/CLAUDE.md) · 🇵🇱 [pl](../pl/CLAUDE.md) · 🇵🇹 [pt](../pt/CLAUDE.md) · 🇧🇷 [pt-BR](../pt-BR/CLAUDE.md) · 🇷🇴 [ro](../ro/CLAUDE.md) · 🇷🇺 [ru](../ru/CLAUDE.md) · 🇸🇰 [sk](../sk/CLAUDE.md) · 🇸🇪 [sv](../sv/CLAUDE.md) · 🇰🇪 [sw](../sw/CLAUDE.md) · 🇮🇳 [ta](../ta/CLAUDE.md) · 🇮🇳 [te](../te/CLAUDE.md) · 🇹🇭 [th](../th/CLAUDE.md) · 🇹🇷 [tr](../tr/CLAUDE.md) · 🇺🇦 [uk-UA](../uk-UA/CLAUDE.md) · 🇵🇰 [ur](../ur/CLAUDE.md) · 🇻🇳 [vi](../vi/CLAUDE.md) · 🇨🇳 [zh-CN](../zh-CN/CLAUDE.md) --- هذا الملف يوفر إرشادات لـ Claude Code (claude.ai/code) عند العمل مع الكود في هذا المستودع. ## البداية السريعة ```bash 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 # اكتشاف الاعتماديات الدائرية ``` ### تشغيل الاختبارات ```bash # ملف اختبار فردي (جهاز اختبار 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/exported/resilience-3layers.svg) (المصدر: [docs/diagrams/resilience-3layers.mmd](./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`. يجب أن تؤدي حالات الفشل على مستوى المزود فقط إلى تفعيل قاطع المزود: ```ts (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` الحقول المهمة على اتصالات المزود: ```ts rateLimitedUntil; testStatus: "unavailable"; lastError; lastErrorType; errorCode; backoffLevel; ``` أثناء اختيار الحساب، يتم تخطي الاتصال بينما: ```ts new Date(rateLimitedUntil).getTime() > Date.now(); ``` فترات التبريد أيضًا كسولة: عندما تكون `rateLimitedUntil` في الماضي، يصبح الاتصال مؤهلاً مرة أخرى. عند الاستخدام الناجح، تقوم `clearAccountError()` بمسح `testStatus`، `rateLimitedUntil`، حقول الأخطاء، و `backoffLevel`. سلوك فترة تبريد الاتصال الافتراضي: - فترة تبريد أساسية لمزود OAuth: `5s`. - فترة تبريد أساسية لمزود مفتاح واجهة برمجة التطبيقات: `3s`. - يجب أن يفضل مفتاح واجهة برمجة التطبيقات `429` تلميحات إعادة المحاولة من المصدر (`Retry-After`، رؤوس إعادة التعيين، أو نص إعادة التعيين القابل للتحليل) عند توفرها. - تستخدم الفشل القابلة للاسترداد المتكررة التراجع الأسي: ```ts 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](https://github.com/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 ```bash # لا تقم بالالتزام مباشرة إلى 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 ` القياسية؛ تعتمد سير عمل النقل (`/port-upstream-features` و `/port-upstream-issues`) على ذلك.