القابلية للتوسيع والتخصيص

ماذا ستتعلم

كيفية تخصيص وتوسيع 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/

إنشاء وكلاء فرعيين مخصصين

بنية الملف:

---
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

---
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

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

---
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

سياسات الاستدعاء

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

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

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

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

الطريقة الثانية: نظام القواعد

نظرة عامة

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

أولوية القواعد

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

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 (التفضيلات العامة)

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

مثال:

# 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 (قواعد المشروع)

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

مثال:

# 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 Mode ومستوى التفاصيل

مثال:

# 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

نظرة عامة

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

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

قدرات MCP

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

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

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

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

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

مثال: الجمع بين الطرق الثلاث

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

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

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

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

## 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.json
• تحقق من بيانات اعتماد المصادقة
• تأكد من أن خادم MCP يعمل ويمكن الوصول إليه
• تحقق من صحة الاتصال بالشبكة

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

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

راجع أيضًا