**اللغة:** [English](../../README.md) | **العربية** | [বাংলা](../bn/README.md) | [Deutsch](../de-DE/README.md) | [Español](../es/README.md) | [Português (Brasil)](../pt-BR/README.md) | [简体中文](../../README.zh-CN.md) | [繁體中文](../zh-TW/README.md) | [日本語](../ja-JP/README.md) | [한국어](../ko-KR/README.md) | [Türkçe](../tr/README.md) | [Русский](../ru/README.md) | [Tiếng Việt](../vi-VN/README.md) | [ไทย](../th/README.md) | [Українська](../uk-UA/README.md) | [Polski](../pl/README.md)

# ECC

![ECC — نظام تشغيل مهام الوكلاء الأصلي لبيئات العمل](../../assets/hero.png)

> يغطي هذا التوثيق دليل البدء السريع والواجهات والمفاهيم الأساسية لنظام ECC.
> مصدر المحتوى الإنجليزي المعتمد هو الفرع main في المستودع الرسمي.
> يظل الكتالوج الكامل والمحدّث باستمرار متوفراً في [README باللغة الإنجليزية](../../README.md)؛
> وتتم متابعة وتحديث الأقسام دورياً لضمان الدقة والتوافق.

---

**نظام تشغيل مهام الوكلاء الأصلي لبيئات العمل (Harness-Native Agent Operating System).**

مشروع ECC ليس مجرد مجموعة من ملفات الإعداد الثابتة. بل يدمج وكلاء متخصصين (Agents)،
ومهارات معيارية (Skills)، ومعالجات أحداث تلقائية (Hooks)، وقواعد توجيهية (Rules)،
وتكوينات بروتوكول سياق النموذج (MCP)، وطبقة توافق للأوامر السابقة (Commands).
صُمم النظام بناءً على ممارسات عمل حقيقية ويمتد ليعمل بتناسق عبر بيئات متعددة:
**Claude Code**، **Codex**، **Cursor**، **OpenCode**، **Gemini**، **Zed**، **GitHub Copilot** وغيرها الكثير.

## المصادر الرسمية

ثبّت ECC حصرياً عبر القنوات الرسمية المعتمدة:

- مستودع المشروع الرسمي: [github.com/affaan-m/ECC](https://github.com/affaan-m/ECC)
- حزم npm المعتمدة: [`ecc-universal`](https://www.npmjs.com/package/ecc-universal) و[`ecc-agentshield`](https://www.npmjs.com/package/ecc-agentshield)
- تطبيق [ECC Tools على GitHub](https://github.com/apps/ecc-tools)
- معرّف الإضافة المعتمد: `ecc@ecc`
- الموقع الرسمي: [ecc.tools](https://ecc.tools)

يُرجى الحذر من النسخ غير الرسمية أو المستودعات البديلة غير المعتمدة حيث لا تخضع للمراجعة الأمنية أو الصيانة من قبل فريق المشروع.

## البدء السريع

اختر **طريقة تثبيت واحدة فقط**. الجمع بين تثبيت الإضافة والتثبيت اليدوي الكامل هو السبب الأكثر شيوعاً لتكرار الوكلاء والمهارات والخطافات.

### الإعداد التفاعلي الموجه (الموصى به)

```bash
npx ecc-universal@2.2.3 setup
```

يمكنك أيضاً استخدام مدير الحزم المفضل لديك:

```bash
pnpm dlx ecc-universal@2.2.3 setup
yarn dlx ecc-universal@2.2.3 setup
bunx ecc-universal@2.2.3 setup
```

قبل تشغيل كود الحزمة، تحقق من مصدر الإصدار وسلامة السجل المعتمد.

### Claude Code

في Claude Code، أضف سوق الإضافات ثم ثبّت الإضافة المعتمدة:

```text
/plugin marketplace add https://github.com/affaan-m/ECC
/plugin install ecc@ecc
```

بعد ذلك، ابدأ بـ `rules/common` بالإضافة إلى حزم اللغات وأطر العمل التي تستخدمها بالفعل في مشروعك.
تحذير مهم: بعد إتمام تثبيت الإضافة عبر `/plugin install`، لا تقم بتشغيل أمر التثبيت الكامل `./install.sh --profile full` إطلاقاً لتجنب تكرار الوكلاء والمهارات.

### Codex

```bash
codex plugin marketplace add affaan-m/ECC
codex plugin add ecc@ecc
```

في Codex، استخدم `$configure-ecc` لإجراء التكوين المخصص المناسب لمزود الخدمة في بيئتك.

### البيئات الأخرى (Other Harnesses)

شغّل الأوامر التالية من المجلد الرئيسي للمستودع المحلي بعد تنزيله. يختار سطر OpenCode الملف التعريفي الكامل ويفعّل الخطافات التلقائية صراحة.

| بيئة العمل (Harness) | أمر التثبيت من المستودع |
|---|---|
| Cursor | `./install.sh --profile minimal --target cursor` |
| Gemini CLI | `./install.sh --profile minimal --target gemini` |
| Zed | `./install.sh --profile minimal --target zed` |
| OpenCode | `npm install && npm run build:opencode && ./install.sh --profile full --target opencode --enable-hooks` |
| Hermes | `./install.sh --profile minimal --target hermes` |
| OpenClaw | `./install.sh --profile minimal --target openclaw` |
| Kimi Code CLI | `./install.sh --profile minimal --target kimi` |

للاطلاع على مصفوفة الدعم الكاملة لكافة المنصات والمتطلبات التفصيلية، راجع [قسم Platform Support في README الأساسي](../../README.md#platform-support).

## تثبيت التوثيق العربي

تستخدم اللغة العربية الرمز `ar`، ويُقبل أيضاً الاسم المستعار `ar-SA`. استخدم نسخة محلية من المستودع تحتوي على الدليل `docs/ar/` والمكوّن `locale:ar`. نفّذ الأوامر التالية من المجلد الرئيسي للمستودع بعد تثبيت تبعيات المشروع (يتطلب Node.js 18 أو أحدث). الإصدار الحالي من حزمة `ecc-universal` قد لا يتضمن التوثيق العربي بعد.

أولاً، عاين خطة التثبيت دون كتابة الملفات (Dry Run):

```bash
node scripts/install-apply.js --target claude --locale ar --dry-run
```

ثم ثبّت التوثيق العربي في المسار `~/.claude/docs/ar/`:

```bash
node scripts/install-apply.js --target claude --locale ar
```

يثبت هذا الخيار وحدة التوثيق `docs-ar` بشكل مستقل؛ ولا يثبت الملف التعريفي الكامل لـ ECC ولا الخطافات التلقائية.

## مكونات وواجهات ECC

| الواجهة | الدور البرمجي والوظيفي |
|---|---|
| `agents/` | وكلاء متخصصون للتخطيط والتنفيذ والمراجعة والتشخيص |
| `skills/` | إجراءات ومعارف نمطية متخصصة تُحمّل عند الحاجة إليها في المهمة |
| `hooks/` | أتمتة ومعالجات أحداث تُنفّذ عند وقوع أحداث محددة في بيئة العمل |
| `rules/` | قواعد توجيهية دائمة ومعايير خاصة باللغات وأطر العمل |
| `commands/` | طبقة توافق مع الأوامر السابقة للأوامر المسبوقة بشرطة مائلة |
| `mcp-configs/` | تكوينات خوادم بروتوكول سياق النموذج (Model Context Protocol) |
| `manifests/` | بيانات تعريفية معيارية للوحدات والمكونات وملفات التثبيت |

يعتمد مسار المشروع منهجية **المهارات أولاً (skills-first)**: حيث تُضاف مهام سير العمل الجديدة أولاً إلى `skills/`؛ وتبقى `commands/` كواجهة توافق حيثما دعت الحاجة.

## المفاهيم الأساسية

### الوكلاء (Agents)

يمتلك كل وكيل دوراً محدداً، ومجموعة أدوات مخصصة، وأسلوب عمل واضحاً؛ مثل وكيل التخطيط، ومراجعي الكود للغات البرمجية المختلفة، ومتخصصي تشخيص وحل أخطاء البناء والترجمة.

### المهارات (Skills)

تحتوي المهارة على إجراء عمل مركز أو معرفة بمجال تقني محدد. بفضل ذلك، يُحمّل السياق فقط عندما يلائم المهمة الحالية، بدلاً من إثقال كل موجّه نظام (System Prompt) بسياق عام غير ضروري.

### الخطافات (Hooks)

تستجيب الخطافات للأحداث البرمجية مثل بدء الجلسة أو استدعاء الأدوات. صُممت الخطافات لتكون آمنة وقابلة للنقل؛ ولا يلزم نسخها يدوياً إلى ملف الإعدادات بعد تثبيت الإضافة، حيث تقوم الإصدارات الحديثة من بيئات العمل بتحميل `hooks/hooks.json` تلقائياً.

### القواعد (Rules)

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

للاطلاع على تفاصيل تعريب المفاهيم والمصطلحات، راجع [مسرد المصطلحات العربي](GLOSSARY.md).

## الأمان والخصوصية

- لا تقم أبداً بتخزين مفاتيح واجهات برمجة التطبيقات (API Keys) أو كلمات المرور أو الرموز السرية داخل المستودع.
- راجع السكربتات ومصادر الحزم قبل تشغيلها في بيئتك.
- تجنب الجمع بين عدة طرق تثبيت لتفادي تضارب وتكرار الملفات.
- لا تنسخ ملف `hooks/hooks.json` الخام مباشرة إلى `~/.claude/settings.json` بعد تثبيت الإضافة.
- التزم بمبدأ الحد الأدنى من الصلاحيات وتحقق من سلامة المدخلات عند حدود النظام.

للمزيد من الإرشادات الأمنية، راجع [قسم Security في README الأساسي](../../README.md#security).

## تحديث التعريب والمساهمة

تتم صيانة التوثيق المترجم وفق أفضل الممارسات المستمرة. يُستحسن في كل طلب سحب (PR) توضيح ما يلي:

1. رقم إيداع المصدر الإنجليزي (Commit SHA) المعتمد.
2. النطاق الدقيق للمحتوى المترجم أو المحدّث.
3. أي تعديلات أو إضافات على [مسرد المصطلحات](GLOSSARY.md).
4. نتائج فحوصات الروابط وسلامة التنسيق ومخططات التثبيت (Manifests).

يُفضل أن تكون طلبات السحب مركزة ومقسمة حسب المجال (مثل `docs/`، `agents/`، `skills/`) لتسهيل المراجعة والمزامنة مع المستودع الأساسي.

## المساهمة في المشروع

قبل البدء في ترجمات موسعة أو ميزات جديدة، راجع المهام وقوائم النقاش المفتوحة لتنسيق الجهود وتجنب العمل المزدوج. للاطلاع على الإرشادات الكاملة للمساهمة، راجع [CONTRIBUTING.md](../../CONTRIBUTING.md).

## الترخيص

مرخص بموجب رخصة MIT — يمنحك ذلك حرية الاستخدام والتعديل ومشاركة التحسينات مع مجتمع المطورين.

---

**إذا كان ECC يقدم لك قيمة في عملك، شارك بنجمة للمستودع، واقرأ الأدلة، وابنِ برمجيات استثنائية.**