# القابلية للتوسيع والتخصيص (/ar/docs/verdent-for-vscode/advanced-features/extensibility)

> قم بتوسيع قدرات Verdent من خلال الوكلاء الفرعيين المخصصين والقواعد وتكامل MCP



### ماذا ستتعلم [#ماذا-ستتعلم]

كيفية تخصيص وتوسيع Verdent for VS Code باستخدام ثلاث طرق قوية للتوسّع: الوكلاء الفرعيون المخصصون، ونظام القواعد، وتكامل MCP.

***

## نظرة عامة على القابلية للتوسيع [#نظرة-عامة-على-القابلية-للتوسيع]

يوفر Verdent for VS Code ثلاث طرق أساسية لتوسيع قدراته وتخصيص سلوكه:

1. **الوكلاء الفرعيون المخصصون** - أنشئ وكلاء ذكاء اصطناعي متخصصين لمهام محددة النطاق
2. **نظام القواعد** - وجّه السلوك من خلال VERDENT.md و AGENTS.md و plan\_rules.md
3. **تكامل MCP** - اربط الأدوات والخدمات الخارجية عبر Model Context Protocol

تخدم كل طريقة حاجات تخصيص مختلفة، ويمكن دمجها معًا لتحقيق تحسين شامل لسير العمل.

***

## الطريقة الأولى: الوكلاء الفرعيون المخصصون [#الطريقة-الأولى-الوكلاء-الفرعيون-المخصصون]

### نظرة عامة [#نظرة-عامة]

الوكلاء الفرعيون المخصصون هم وكلاء ذكاء اصطناعي متخصصون لديهم prompt نظام مخصص، وسياسات استدعاء، وخبرة مرتبطة بمهام محددة. إنهم يوسّعون الوكلاء الفرعيين المدمجين في Verdent (`@Verifier`، `@Explorer`، `@Code-reviewer`) بقدرات خاصة بالمشروع.

**موقع التخزين:** `~/.verdent/subagents/`

### إنشاء وكلاء فرعيين مخصصين [#إنشاء-وكلاء-فرعيين-مخصصين]

**بنية الملف:**

```markdown
---
name: subagent-name
description: One-line purpose description
---
# System Prompt

[Behavior definition, personality, task interpretation approach]

Invocation policy (strict|flexible): Policy description

When to use:
- Scenario 1
- Scenario 2

When NOT to use:
- Avoid scenario 1
- Avoid scenario 2
```

**طرق الإنشاء:**

**الطريقة الأولى: قائمة الإعدادات**

1. الإعدادات ← الوكلاء الفرعيون
2. "إنشاء وكيل فرعي جديد"
3. حدد الاسم والوصف وprompt النظام
4. اضبط سياسة الاستدعاء
5. احفظ في `~/.verdent/subagents/`

**الطريقة الثانية: إنشاء الملف مباشرة**

1. انتقل إلى `~/.verdent/subagents/`
2. أنشئ ملف markdown (مثل `security-reviewer.md`)
3. أضف YAML frontmatter
4. اكتب prompt النظام وإرشادات الاستخدام

### حالات استخدام الوكلاء الفرعيين المخصصين [#حالات-استخدام-الوكلاء-الفرعيين-المخصصين]

**خبرة متخصصة في مجال معين:**

* **الحسابات المالية:** الامتثال الضريبي، اللوائح المالية
* **الامتثال لمعايير HIPAA في الرعاية الصحية:** معايير التعامل مع بيانات المرضى
* **التشفير:** أفضل ممارسات تنفيذ الأمان

**سير العمل الخاص بالفريق:**

* **أدوات فرض نمط الكود:** معايير ترميز الفريق التي تتجاوز قواعد الـ linter
* **اتساق التوثيق:** التأكد من أن المستندات تتبع قوالب الفريق
* **مدققو التبعيات:** رصد الحزم الخارجية مقابل القوائم المعتمدة

**متخصصون في مجموعات تقنية محددة:**

* **محسّنو أداء React:** تحديد عمليات إعادة الرسم غير الضرورية
* **محسّنو استعلامات SQL:** تحليل وتحسين أداء قاعدة البيانات
* **مراجعو تهيئة Docker:** التحقق من ممارسات الحوسبة داخل الحاويات

**ضمان الجودة:**

* **محلّلو تغطية الاختبار:** تحديد مسارات الكود غير المُختبرة
* **مراجعو معالجة الأخطاء:** التأكد من معالجة شاملة للاستثناءات
* **أدوات فرض معايير التسجيل (logging):** التحقق من ممارسات التسجيل

### مثال: أداة إنشاء توثيق API [#مثال-أداة-إنشاء-توثيق-api]

```markdown
---
name: api-documenter
description: Generates comprehensive API documentation from code
---
# System Prompt

You are an API documentation specialist.

Documentation approach:
- Extract endpoints, parameters, and responses from code
- Generate OpenAPI/Swagger specifications
- Include usage examples and error codes
- Document authentication requirements

Output format:
- Markdown tables for endpoints
- Code examples in multiple languages
- Authentication flow diagrams

Invocation policy (strict): Only run when explicitly requested.

When to use:
- User requests API documentation generation
- Need to document REST/GraphQL endpoints
- Creating developer guides

When NOT to use:
- Inline code comments
- User-facing documentation
```

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

```
@api-documenter document the /api/users endpoints
```

### مثال: مراجع ترحيل قاعدة البيانات [#مثال-مراجع-ترحيل-قاعدة-البيانات]

```markdown
---
name: migration-reviewer
description: Reviews database migrations for safety and correctness
---
# System Prompt

You are a database migration safety specialist.

Review checklist:
- Check for destructive operations (DROP, DELETE without WHERE)
- Verify reversible migrations (up/down compatibility)
- Identify potential data loss scenarios
- Validate index creation strategies
- Check for blocking operations on large tables

Risk assessment:
- Categorize migrations: low/medium/high risk
- Recommend staging environment testing for high-risk changes
- Suggest rollback procedures

Invocation policy (strict): Only run when explicitly requested.

When to use:
- User creates or modifies migration files
- Pre-deployment migration review
- Investigating migration failures

When NOT to use:
- Schema design from scratch
- Query optimization
```

### سياسات الاستدعاء [#سياسات-الاستدعاء]

**السياسة الصارمة:**

* يعمل الوكيل الفرعي فقط عند طلبه صريحًا عبر إشارة @
* يحتفظ المستخدم بالتحكم الكامل في الاستدعاء
* الأفضل للوكلاء الفرعيين المتخصصين ذوي الاستخدام العرضي

**السياسة المرنة:**

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

***

## الطريقة الثانية: نظام القواعد [#الطريقة-الثانية-نظام-القواعد]

### نظرة عامة [#نظرة-عامة-1]

ملفات القواعد هي مستندات Markdown توجّه سلوك Verdent وتنسيق المخرجات وعملية اتخاذ القرار دون تغييرات في الكود. توفر ثلاثة أنواع من القواعد تخصيصًا شاملاً:

| نوع القاعدة        | النطاق                  | الأولوية | التخزين                    |
| ------------------ | ----------------------- | -------- | -------------------------- |
| **VERDENT.md**     | عالمي عبر جميع المشاريع | متوسطة   | `~/.verdent/VERDENT.md`    |
| **AGENTS.md**      | خاص بالمشروع (الفريق)   | الأعلى   | مجلد جذر المشروع           |
| **plan\_rules.md** | تنسيق Plan Mode         | مستقلة   | `~/.verdent/plan_rules.md` |

### أولوية القواعد [#أولوية-القواعد]

عند حدوث تعارض:

1. **AGENTS.md** (الأعلى) - تتجاوز قواعد المشروع تفضيلات المستخدم
2. **VERDENT.md** (المتوسطة) - تُطبَّق عند عدم وجود تعارض مع المشروع
3. **السلوك الافتراضي** (الأدنى) - الإعدادات الافتراضية المدمجة في Verdent

**مثال على تعارض:**

```
VERDENT.md: "Use 2-space indentation"
AGENTS.md: "Use 4-space indentation for this project"
→ Result: 4-space indentation (project rules win)
```

### VERDENT.md (التفضيلات العامة) [#verdentmd-التفضيلات-العامة]

**الغرض:** نمط الترميز الشخصي والتفضيلات عبر جميع المشاريع

**مثال:**

```markdown
# User Rules

## TypeScript Preferences
- Use strict mode in tsconfig.json
- Prefer interfaces over type aliases
- Include return types on all functions

## Code Organization
- One component per file
- Named exports instead of default exports
- Organize imports: external, internal, types

## Documentation
- TSDoc comments for public APIs
- Include @param and @returns tags

## Communication
- Provide explanations before showing code
- Highlight breaking changes explicitly
```

**الوصول:** الإعدادات ← القواعد ← قواعد المستخدم

### AGENTS.md (قواعد المشروع) [#agentsmd-قواعد-المشروع]

**الغرض:** معايير الترميز الخاصة بالفريق وعُرف المشروع

**مثال:**

```markdown
# AGENTS.md

## Dev environment tips
- Use `pnpm dlx turbo run where <project_name>` to navigate
- Run `pnpm install --filter <project_name>` for dependencies
- Check package.json name field for correct package name

## Testing instructions
- Run `pnpm turbo run test --filter <project_name>`
- From package root: `pnpm test`
- Focus on one test: `pnpm vitest run -t "<test name>"`
- Fix all errors before merge

## PR instructions
- Title format: [<project_name>] <Title>
- Always run `pnpm lint` and `pnpm test` before committing
```

**الوصول:** مجلد جذر المشروع (تحت التحكم بالإصدارات)

### plan\_rules.md (تخصيص الخطة) [#plan_rulesmd-تخصيص-الخطة]

**الغرض:** التحكم في تنسيق مخرجات Plan Mode ومستوى التفاصيل

**مثال:**

```markdown
# Plan Rules

## Plan Structure
- Start with brief summary (2-3 sentences)
- Include estimated time for each major step
- List prerequisites before implementation steps
- Identify potential risks

## Level of Detail
- Break tasks into subtasks of 15-30 minutes
- Include specific file paths for modifications
- List functions/components to create/modify

## Format
- Use numbered lists for sequential steps
- Use bullet points for options
- Include code snippets for complex changes
```

**الوصول:** الإعدادات ← القواعد ← قواعد الخطة

### أفضل ممارسات كتابة القواعد [#أفضل-ممارسات-كتابة-القواعد]

**كن محددًا وتوجيهيًا:**

```
✓ Good: "Always use async/await for asynchronous operations"
✗ Vague: "Try to use modern JavaScript"
```

**نظّم بشكل منطقي:**

* جمّع القواعد المرتبطة تحت عناوين أقسام
* فصل الاهتمامات (النمط، الاختبار، التوثيق، الأمان)
* استخدم بنية متسقة عبر الملفات

**رتّب أولوية القواعد الحرجة:**

* ضع القواعد المهمة أولًا في كل قسم
* استخدم التأكيد للمعايير غير القابلة للتفاوض: `**NEVER** commit credentials`
* ركّز على منع الأخطاء والأمان

**اختبر الفعالية:**

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

***

## الطريقة الثالثة: تكامل MCP [#الطريقة-الثالثة-تكامل-mcp]

### نظرة عامة [#نظرة-عامة-2]

يوسّع Model Context Protocol (MCP) قدرات Verdent عبر ربط الأدوات ومصادر البيانات والخدمات الخارجية. تعمل خوادم MCP كجسور بين Verdent والأنظمة الخارجية.

**التهيئة:** `~/.verdent/mcp.json` عبر الإعدادات ← خوادم MCP

### قدرات MCP [#قدرات-mcp]

**الوصول إلى الأنظمة الخارجية:**

* أدوات استعلام قواعد البيانات (PostgreSQL، MySQL، MongoDB)
* APIات الخدمات السحابية (AWS، Azure، GCP)
* إدارة المشاريع (Jira، Linear، Asana)
* خطوط أنابيب CI/CD (Jenkins، GitHub Actions)
* خدمات المراقبة (Datadog، New Relic)

**تطوير أدوات مخصصة:**
أنشئ خوادم MCP للأنظمة الخاصة:

* تكاملات API الداخلية
* جسور الأنظمة القديمة (Legacy)
* مصادر بيانات متخصصة
* أدوات أتمتة سير العمل

### MCP مقابل الوكلاء الفرعيين المخصصين مقابل القواعد [#mcp-مقابل-الوكلاء-الفرعيين-المخصصين-مقابل-القواعد]

| الحاجة                                      | الطريقة الأفضل           | السبب                                   |
| ------------------------------------------- | ------------------------ | --------------------------------------- |
| تحليل ذكاء اصطناعي متخصص                    | وكيل فرعي مخصص           | يتطلب استدلال ذكاء اصطناعي مع سياق مخصص |
| فرض معايير الترميز                          | القواعد (AGENTS.md)      | توجيه سلوك بسيط                         |
| الوصول إلى قاعدة بيانات خارجية              | تكامل MCP                | يتطلب اتصالًا بنظام خارجي               |
| تفضيلات الترميز الشخصية                     | القواعد (VERDENT.md)     | تخصيص سلوك عالمي                        |
| عُرف الفريق                                 | القواعد (AGENTS.md)      | معايير مشروع مشتركة                     |
| تكامل API                                   | تكامل MCP                | تفاعل مع خدمة خارجية                    |
| تخصيص تنسيق الخطة                           | القواعد (plan\_rules.md) | التحكم في مخرجات Plan Mode              |
| خبرة في مجال معين (المالية، الرعاية الصحية) | وكيل فرعي مخصص           | تطبيق معرفة متخصصة                      |

### مثال: الجمع بين الطرق الثلاث [#مثال-الجمع-بين-الطرق-الثلاث]

**السيناريو:** فريق تطوير full-stack مع متطلبات امتثال صارمة

**الوكيل الفرعي المخصص:**

```markdown
---
name: compliance-auditor
description: Audits code for regulatory compliance (SOC2, HIPAA)
---
[System prompt for compliance checking]
```

**AGENTS.md (قواعد المشروع):**

```markdown
## Security Standards
- All API endpoints must validate inputs
- Never log PII or credentials
- Encrypt sensitive data at rest and in transit

## Compliance
- Run @compliance-auditor before all PRs
- Document data retention policies in code comments
- Include audit trails for data access
```

**تكامل MCP:**

* **خادم MCP لقاعدة بيانات الامتثال:** التحقق من العمليات مقابل قواعد الامتثال
* **خادم MCP لسجل التدقيق:** تسجيل جميع عمليات الوصول إلى البيانات الحساسة

**سير العمل:**

```
User: "Create endpoint for user profile updates"
Verdent: [Applies AGENTS.md rules]
         [Generates secure endpoint with validation]
         [Automatically invokes @compliance-auditor]
         [Uses MCP to log operation in audit system]
         Result: Compliant, secure, audited endpoint
```

***

## أفضل ممارسات القابلية للتوسيع [#أفضل-ممارسات-القابلية-للتوسيع]

### ابدأ ببساطة، ثم توسّع تدريجيًا [#ابدأ-ببساطة-ثم-توسّع-تدريجيًا]

**التبني التدريجي:**

1. **المرحلة الأولى:** ابدأ بقواعد أساسية (VERDENT.md أو AGENTS.md)
2. **المرحلة الثانية:** أضف وكلاء فرعيين مخصصين للمهام المتخصصة المتكررة
3. **المرحلة الثالثة:** دمج MCP لربط الأنظمة الخارجية

### اجمع الطرق بشكل استراتيجي [#اجمع-الطرق-بشكل-استراتيجي]

**أمثلة على التآزر:**

**القواعد + الوكلاء الفرعيون:**

* يحدد AGENTS.md متى يتم استدعاء الوكلاء الفرعيين المخصصين
* تفرض القواعد اتباع توصيات الوكيل الفرعي

**القواعد + MCP:**

* يحدد AGENTS.md خوادم MCP المعتمدة للاستخدام
* تحدد القواعد الحالات التي يتطلب فيها الأمر الوصول إلى بيانات خارجية

**الوكلاء الفرعيون + MCP:**

* يستخدم الوكيل الفرعي المخصص أدوات MCP للوصول إلى الأنظمة الخارجية
* يفسّر الوكيل الفرعي نتائج MCP بخبرة متخصصة

### وثّق التخصيصات [#وثّق-التخصيصات]

**توثيق الفريق:**
بالنسبة للوكلاء الفرعيين المخصصين وقواعد المشروع (AGENTS.md):

* وثّق الأساس المنطقي للقواعد أو الوكلاء الفرعيين غير الواضحين
* قدّم أمثلة على الاستخدام الصحيح
* أضف أدلة استكشاف الأخطاء وإصلاحها
* ضع النسخ تحت التحكم بالإصدارات مع الكود

**التوثيق الشخصي:**
بالنسبة لـ VERDENT.md والوكلاء الفرعيين الشخصيين:

* علّق على القواعد المعقدة مع ذكر الأسباب
* حافظ على تنظيم القواعد وتحديثها
* أزل القواعد المتقادمة فورًا

### اختبر بدقة [#اختبر-بدقة]

**عملية التحقق:**

1. أنشئ التخصيص (وكيل فرعي/قاعدة/تهيئة MCP)
2. ابدأ محادثة جديدة للاختبار
3. تحقق من تطابق السلوك مع التوقعات
4. نقّح بناءً على النتائج
5. وثّق الأنماط الناجحة

**سيناريوهات اختبار شائعة:**

* هل يُستدعى الوكيل الفرعي تلقائيًا عند توقع ذلك؟
* هل تتجاوز قواعد المشروع قواعد المستخدم بشكل صحيح؟
* هل يتصل خادم MCP وينفّذ العمليات؟
* هل تتفاعل الطرق المُجمَّعة دون تعارضات؟

***

## استكشاف مشكلات القابلية للتوسيع وإصلاحها [#استكشاف-مشكلات-القابلية-للتوسيع-وإصلاحها]

### مشكلات الوكيل الفرعي المخصص [#مشكلات-الوكيل-الفرعي-المخصص]

**الوكيل الفرعي لا يُستدعى:**

* تحقق من سياسة الاستدعاء (تتطلب السياسة الصارمة إشارة @ صريحة)
* تحقق من أن إرشادات "متى يُستخدم" تطابق طلبك
* تأكد من أن الملف موجود في مجلد `~/.verdent/subagents/`
* تحقق من صياغة YAML frontmatter

**سلوك غير متوقع للوكيل الفرعي:**

* راجع prompt النظام للتأكد من وضوحه
* نقّح إرشادات "متى يُستخدم" و"متى لا يُستخدم"
* اختبر باستخدام إشارة @ صريحة لعزل السلوك
* كرّر التعديل على prompt النظام بناءً على النتائج

### تعارضات القواعد [#تعارضات-القواعد]

**القاعدة لا تُطبَّق:**

* تحقق من أولوية القواعد (AGENTS.md أعلى من VERDENT.md)
* تحقق من أن الملف في الموقع الصحيح
* ابدأ محادثة جديدة لاختبار التطبيق من جديد
* اجعل القواعد أكثر تحديدًا وتوجيهًا

**سلوك غير متوقع:**

* ابحث عن قواعد متعارضة في الملف نفسه
* تحقق مما إذا كانت القواعد غامضة جدًا
* تأكد من تحرير ملف القواعد الصحيح
* استخدم لغة صريحة ("دائمًا"، "أبدًا"، "يُفضَّل")

### مشكلات تكامل MCP [#مشكلات-تكامل-mcp]

**فشل الاتصال:**

* تحقق من صياغة `mcp.json`
* تحقق من بيانات اعتماد المصادقة
* تأكد من أن خادم MCP يعمل ويمكن الوصول إليه
* تحقق من صحة الاتصال بالشبكة

**مشكلات استدعاء الأدوات:**

* تأكد من أن خادم MCP يعرض الأدوات المتوقعة
* تحقق من صيغ معاملات الأدوات
* راجع سجلات خادم MCP بحثًا عن الأخطاء
* اختبر خادم MCP بشكل مستقل

***

## راجع أيضًا [#راجع-أيضًا]

<CardGroup cols="2">
  <Card title="إدارة الوكلاء الفرعيين" icon="users" href="/docs/verdent-for-vscode/agents-rules/subagent-management">
    دليل تفصيلي لإنشاء الوكلاء الفرعيين
  </Card>

  <Card title="أنظمة القواعد" icon="book" href="/docs/verdent-for-vscode/agents-rules/rule-systems">
    توثيق كامل للقواعد
  </Card>

  <Card title="تكامل MCP" icon="plug" href="/docs/verdent-for-vscode/advanced-features/mcp">
    إعداد وتهيئة MCP
  </Card>

  <Card title="مرجع الأدوات" icon="wrench" href="/docs/verdent-for-vscode/advanced-features/tool-reference">
    قدرات الأدوات المدمجة
  </Card>
</CardGroup>