تكوين واستخدام الوكلاء الفرعيين في Cursor

الوكلاء الفرعيون في Cursor يتيحون لك تفكيك المهام المعقدة إلى وحدات أصغر متخصصة يمكن أن تعمل بالتوازي أو بالتسلسل. وكيل مخطط ينسق المهمة الإجمالية بينما يعالج الوكلاء الفرعيون المهام الفرعية المحددة بنماذجهم ونطاقاتهم وحدود أمانهم الخاصة. يغطي هذا الدليل كل شيء من اختيار النموذج إلى تكوين الأمان، مما يساعدك على بناء سير عمل متعدد الوكلاء قوي.

فهم الوكلاء الفرعيين

ما هم الوكلاء الفرعيون؟

الوكلاء الفرعيون هم مثيلات وكيل مستقلة تعمل تحت إشراف وكيل مخطط. يمكن لكل وكيل فرعي أن يمتلك:

• نموذج: نماذج ذكاء اصطناعي مختلفة لأنواع مهام مختلفة
• نطاق: وصول مقيد إلى الملفات والدلائل
• حدود أمان: قيود على الإجراءات التي يمكنهم اتخاذها
• سياق: نافذة سياق معزولة لمنع التدخل

يقوم وكيل المخطط بتفكيك مهمة معقدة، وتعيين المهام الفرعية للوكلاء الفرعيين، وجمع نتائجهم، وتركيب مخرج نهائي. تعكس هذه البنية كيف تقسم الفرق البشرية العمل بين المتخصصين.

متى تستخدم الوكلاء الفرعيين

يتألق الوكلاء الفرعيون في السيناريوهات التي قد يكافح فيها وكيل واحد مع اتساع أو تعقيد المهمة:

• إعادة هيكلة كبيرة تمتد عبر وحدات متعددة
• تنفيذ ميزة تتطلب تغييرات في الواجهة الأمامية والخلفية
• تشغيل الاختبارات وإصلاح الأخطاء وتحديث التوثيق في وقت واحد
• مراجعة الشفرة عبر مستودعات متعددة
• توليد والتحقق من تغييرات الشفرة بالتوازي

تلميح

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

اختيار النموذج

اختيار النماذج للمخطط مقابل الوكلاء الفرعيين

واحدة من أهم القرارات في إعداد الوكلاء الفرعيين هي النموذج الذي يجب تعيينه للمخطط والنموذج الذي يجب تعيينه للوكلاء الفرعيين. للنماذج المختلفة نقاط قوة وتكاليف وخصائص سرعة مختلفة.

النماذج المتاحة

النموذج	نقاط القوة	السرعة	التكلفة	الأفضل لـ
cursor-pro	استدلال وسرعة متوازنان	متوسطة	متوسطة	المخطط، المهام العامة
cursor-fast	تكرار سريع، مهام بسيطة	سريع	منخفض	وكلاء فرعيون بسيطون
cursor-max	استدلال عميق، منطق معقد	بطيء	مرتفع	وكلاء فرعيون معقدون
cursor-think	استدلال ممتد، بنية	الأبطأ	الأعلى	مخطط للمهام المعقدة

التكوين

كون تكوين تعيينات النماذج في إعدادات Cursor أو تكوين المشروع:

// في settings.json
{
  "cursor.subagents.enabled": true,
  "cursor.subagents.plannerModel": "cursor-pro",
  "cursor.subagents.defaultModel": "cursor-fast",
  "cursor.subagents.maxConcurrent": 4,
  "cursor.subagents.timeout": 300000
}

تكوين النموذج لكل وكيل فرعي

يمكنك تعيين نماذج مختلفة لوكلاء فرعيين مختلفين بناءً على مهامهم:

# .cursor/subagents/config.yaml
planner:
  model: cursor-pro
  description: "Orchestrates the overall task and synthesizes results"
  maxSubagents: 5

subagents:
  - name: "frontend-agent"
    model: cursor-max
    description: "Handles React component changes"
    scope:
      files: ["src/components/**", "src/pages/**"]
    tools: ["read", "write", "edit"]

  - name: "backend-agent"
    model: cursor-max
    description: "Handles API and server logic"
    scope:
      files: ["src/api/**", "src/server/**", "src/models/**"]
    tools: ["read", "write", "edit", "terminal"]

  - name: "test-agent"
    model: cursor-fast
    description: "Writes and runs tests"
    scope:
      files: ["test/**", "src/**/*.test.*"]
    tools: ["read", "write", "terminal"]

  - name: "docs-agent"
    model: cursor-fast
    description: "Updates documentation"
    scope:
      files: ["docs/**", "README.md", "CHANGELOG.md"]
    tools: ["read", "write"]

تلميح

استخدم نموذجاً قوياً مثل cursor-max للوكلاء الفرعيين الذين يعالجون منطقاً معقداً أو مسارات شفرة حرجة. استخدم cursor-fast للمهام الأبسط مثل التنسيق أو التوثيق أو تشغيل أوامر محددة مسبقاً. هذا يوازن التكلفة والجودة بشكل فعال.

أفضل ممارسات اختيار النموذج

عند اتخاذ قرار بشأن تعيينات النماذج، اعتبر هذه الإرشادات:

1. يحتاج المخطط إلى استدلال قوي: يجب على المخطط أن يفهم المهمة الكاملة، ويفككها، ويركيب النتائج. استخدم cursor-pro أو cursor-think للمخطط.
2. مطابقة النموذج مع التعقيد: لا تحتاج تحريرات الملفات البسيطة إلى cursor-max. احتفظ بالنماذج المكلفة للمهام التي تتطلب فهماً عميقاً.
3. اعتبر نافذة السياق: قد تحتاج المهام الفرعية المعقدة إلى نوافذ سياق أكبر. يدعم cursor-max سياقاً أكثر من cursor-fast.
4. التوسع الواعي بالتكلفة: تشغيل أربعة وكلاء فرعيين cursor-fast أرخص من وكيل cursor-max واحد. لكن إذا كانت الجودة مهمة، استثمر في نماذج أفضل للمهام الفرعية الحرجة.

// تكوين محسن للتكلفة
{
  "cursor.subagents.plannerModel": "cursor-pro",
  "cursor.subagents.models": {
    "frontend-agent": "cursor-fast",
    "backend-agent": "cursor-max",
    "test-agent": "cursor-fast",
    "docs-agent": "cursor-fast"
  }
}

// تكوين محسن للجودة
{
  "cursor.subagents.plannerModel": "cursor-think",
  "cursor.subagents.models": {
    "frontend-agent": "cursor-max",
    "backend-agent": "cursor-max",
    "test-agent": "cursor-max",
    "docs-agent": "cursor-fast"
  }
}

warning

استخدام النماذج المكلفة لجميع الوكلاء الفرعيين يمكن أن يستهلك ميزانية الرموز في خطتك بسرعة. راقب استخدامك باستخدام أمر Cursor: Show Token Usage. إذا اقتربت من الحد، خفّض الوكلاء الفرعيين غير الحرجين إلى cursor-fast.

التحكم في النطاق

قيود الوصول إلى الملفات

يحدد التحكم في النطاق الملفات والدلائل التي يمكن لكل وكيل فرعي الوصول إليها. هذا إجراء أمني وتحسين جودة، حيث يمنع الوكلاء الفرعيين من إجراء تغييرات غير مقصودة.

تكوين نطاقات الملفات

# .cursor/subagents/scopes.yaml
subagents:
  - name: "auth-module-agent"
    scope:
      # الملفات التي يمكن لهذا الوكيل قراءتها وتعديلها
      files:
        include:
          - "src/auth/**"
          - "src/middleware/auth.ts"
          - "config/auth.json"
        exclude:
          - "src/auth/legacy/**"
      # الدلائل التي يمكن لهذا الوكيل سردها واستكشافها
      directories:
        - "src/auth"
        - "src/middleware"
      # ما إذا كان الوكيل يمكنه الوصول إلى ملفات خارج نطاقه
      strictMode: true

عندما يكون strictMode بقيمة true، لا يمكن للوكيل الفرعي قراءة أو سرد أو تعديل أي ملفات خارج نطاقه المعلن. هذا هو الإعداد الموصى به لمعظم حالات الاستخدام.

warning

أبلغ المستخدمون أن الوكلاء يستكشفون أحياناً ملفات خارج الدليل المفتوح، حتى عند تكوين قيود النطاق. يحدث هذا عادةً عندما:

1. لم يتم ضبط إعداد strictMode بشكل صريح على true (الافتراضي هو false)
2. يستخدم الوكيل الفرعي أوامر الطرفية للوصول إلى الملفات (تجاوز فحوصات نطاق الملف)
3. يستخدم تكوين النطاق مسارات نسبية يتم حلها بشكل مختلف عن المتوقع
4. يرث الوكيل الفرعي النطاق الأوسع للمخطط

لمنع هذا، اضبط دائماً strictMode: true وقيّد أيضاً وصول أدوات الطرفية. راجع قسم حدود الأمان أدناه.

أنماط نطاق شائعة

نطاق قائم على الوحدة: تقييد وكيل على وحدة محددة:

- name: "user-module-agent"
  scope:
    files:
      include: ["src/modules/user/**"]
    strictMode: true

نطاق قائم على الطبقة: تقييد وكيل على طبقة بنية محددة:

- name: "api-layer-agent"
  scope:
    files:
      include:
        - "src/api/routes/**"
        - "src/api/controllers/**"
        - "src/api/middleware/**"
    strictMode: true

نطاق للقراءة فقط: السماح بالقراءة ولكن عدم تعديل الملفات:

- name: "code-review-agent"
  scope:
    files:
      include: ["src/**"]
    tools: ["read"]  # لا أدوات كتابة أو تحرير
    strictMode: true

نطاق ملف مشترك: يمكن للعديد من الوكلاء الوصول إلى ملفات تكوين مشتركة:

- name: "config-aware-agent"
  scope:
    files:
      include:
        - "src/features/feature-a/**"
        - "src/shared/config.ts"  # ملف تكوين مشترك
        - "src/shared/types.ts"   # تعريفات أنواع مشتركة
    strictMode: true

حدود الأمان

قيود الأدوات

يمكن تقييد كل وكيل فرعي بأدوات محددة. هذا يمنع الوكلاء الفرعيين من تنفيذ إجراءات لا ينبغي أن يكونوا قادرين على القيام بها.

# .cursor/subagents/security.yaml
subagents:
  - name: "read-only-analyzer"
    description: "Analyzes code without modifying anything"
    tools:
      - read
    # لا أدوات كتابة أو تحرير أو طرفية
    scope:
      files:
        include: ["src/**"]
      strictMode: true

  - name: "test-runner"
    description: "Runs tests and reports results"
    tools:
      - read
      - terminal
    scope:
      files:
        include: ["test/**", "src/**"]
      strictMode: true
    terminal:
      allowedCommands:
        - "npm test"
        - "npm run test:unit"
        - "npm run test:integration"
      blockedCommands:
        - "rm"
        - "git push"
        - "npm publish"

  - name: "file-editor"
    description: "Edits source files only"
    tools:
      - read
      - write
      - edit
    # لا وصول للطرفية
    scope:
      files:
        include: ["src/**"]
      strictMode: true

تلميح

توفر إعدادات allowedCommands و blockedCommands لوصول الطرفية طبقة أمان مزدوجة. حتى لو حصل وكيل فرعي بطريقة ما على وصول للطرفية، يمكنه فقط تشغيل أوامر معتمدة بشكل صريح. هذا مهم بشكل خاص عند تشغيل الوكلاء في خطوط أنابيب CI/CD أو البيئات المؤتمتة.

منع تداخل الوكلاء الفرعيين

يجب أن يعمل الوكلاء الفرعيون بشكل مستقل. لمنعهم من التدخل في بعضهم البعض:

1. نطاقات ملفات غير متداخلة: التأكد من عدم وجود وصول كتابة متداخل للوكلاء الفرعيين إلى نفس الملفات
2. فروع منفصلة: النظر في جعل كل وكيل فرعي يعمل على فرع Git منفصل
3. التنفيذ المرحلي: استخدام التنفيذ المتسلسل عندما يعتمد الوكلاء الفرعيون على مخرجات بعضهم البعض

# مثال: تنفيذ متسلسل مع تبعية
execution:
  strategy: sequential
  steps:
    - agent: "schema-agent"
      description: "Generate database schema first"
      scope:
        files:
          include: ["src/models/**", "migrations/**"]
      tools: ["read", "write", "edit"]

    - agent: "api-agent"
      description: "Build API endpoints based on schema"
      dependsOn: "schema-agent"
      scope:
        files:
          include: ["src/api/**"]
      tools: ["read", "write", "edit"]

    - agent: "test-agent"
      description: "Write tests for the new API"
      dependsOn: "api-agent"
      scope:
        files:
          include: ["test/**"]
      tools: ["read", "write", "terminal"]

warning

إذا قام وكيلان فرعيان بالكتابة إلى نفس الملف في وقت واحد، ستحصل على تعارضات دمج لا يمكن للمخطط حلها تلقائياً. تحقق دائماً من أن نطاقات الملفات لا تتداخل للوكلاء الفرعيين القادرين على الكتابة. استخدم أمر Cursor: Validate Subagent Scopes للتحقق من التداخلات قبل التشغيل.

الوصول إلى متغيرات البيئة

تحكم في متغيرات البيئة التي يمكن لكل وكيل فرعي الوصول إليها:

- name: "deploy-agent"
  scope:
    env:
      allow:
        - "DEPLOY_TARGET"
        - "CI_COMMIT_SHA"
      deny:
        - "AWS_SECRET_ACCESS_KEY"
        - "DATABASE_PASSWORD"

هذا يضمن عدم تعرض الأسرار الحساسة للوكلاء الفرعيين الذين لا يحتاجونها.

التنفيذ المتوازي للوكلاء

تكوين التنفيذ المتوازي

يتيح التنفيذ المتوازي للعديد من الوكلاء الفرعيين العمل في وقت واحد، مما يقلل وقت إكمال المهمة الإجمالي بشكل كبير.

// في settings.json
{
  "cursor.subagents.execution": {
    "strategy": "parallel",
    "maxConcurrent": 4,
    "staggerDelay": 1000
  }
}

• maxConcurrent: الحد الأقصى لعدد الوكلاء الفرعيين الذين يعملون في نفس الوقت
• staggerDelay: مللي ثانية للانتظار بين بدء كل وكيل فرعي (يمنع ذروات الموارد)

مثال على التنفيذ المتوازي

# .cursor/subagents/parallel-config.yaml
planner:
  model: cursor-pro
  description: "Refactor the authentication system across frontend and backend"

execution:
  strategy: parallel

subagents:
  - name: "frontend-auth"
    model: cursor-max
    description: "Refactor React authentication components to use new auth context"
    scope:
      files:
        include: ["src/components/auth/**", "src/contexts/AuthContext.tsx"]
      strictMode: true
    tools: ["read", "write", "edit"]

  - name: "backend-auth"
    model: cursor-max
    description: "Refactor backend authentication middleware and JWT handling"
    scope:
      files:
        include: ["src/api/middleware/auth.ts", "src/utils/jwt.ts"]
      strictMode: true
    tools: ["read", "write", "edit"]

  - name: "auth-tests"
    model: cursor-fast
    description: "Update authentication tests for the new structure"
    scope:
      files:
        include: ["test/auth/**"]
      strictMode: true
    tools: ["read", "write", "terminal"]

  - name: "auth-docs"
    model: cursor-fast
    description: "Update authentication documentation"
    scope:
      files:
        include: ["docs/auth/**", "README.md"]
      strictMode: true
    tools: ["read", "write"]

في هذا التكوين، يبدأ جميع الوكلاء الفرعيين الأربعة في وقت واحد (مع تأخير قدره ثانية واحدة) ويعملون على مناطقهم المعنية بالتوازي.

معالجة نتائج التنفيذ المتوازي

يجمع المخطط النتائج من جميع الوكلاء الفرعيين المتوازيين ويركبها:

// تكوين تركيب المخطط
{
  "cursor.subagents.planner": {
    "synthesisStrategy": "merge",
    "conflictResolution": "planner-decides",
    "generateSummary": true,
    "summaryFormat": "markdown"
  }
}

تلميح

إذا أنتج الوكلاء الفرعيون المتوازيون تغييرات متعارضة، يمكن للمخطط حلها عن طريق اختيار نهج على آخر. فعّل generateSummary بحيث يشرح المخطط قرارات حل التعارض بتنسيق يمكن للبشر قراءته. راجع هذا الملخص قبل قبول التغييرات.

تنسيق الوكلاء الفرعيين

استراتيجيات التنسيق

يمكن للمخطط استخدام استراتيجيات مختلفة لتنسيق الوكلاء الفرعيين:

الاستراتيجية 1: توزيع / تجميع

يفكك المخطط المهمة، ويعين المهام الفرعية للوكلاء الفرعيين المتوازيين، ويجمع جميع النتائج، ويركبها.

execution:
  strategy: parallel
  synthesis:
    type: "merge"
    order: "completion"  # جمع النتائج عند إكمالها

الاستراتيجية 2: خط أنابيب

ينفذ الوكلاء الفرعيون بالتسلسل، كل واحد يستهلك مخرج السابق.

execution:
  strategy: sequential
  pipeline:
    - agent: "schema-generator"
      output: "schema_result"
    - agent: "api-builder"
      input: "schema_result"
      output: "api_result"
    - agent: "test-writer"
      input: "api_result"
      output: "test_result"

الاستراتيجية 3: تكيفية

يقرر المخطط ديناميكياً ما إذا كان سيشغل الوكلاء الفرعيين بالتوازي أو بالتسلسل بناءً على تبعيات المهام.

execution:
  strategy: adaptive
  rules:
    - condition: "no_dependencies"
      action: "parallel"
    - condition: "has_dependencies"
      action: "sequential"
    - condition: "partial_dependencies"
      action: "mixed"

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

يمكن للمخطط إنشاء وكلاء فرعيين ديناميكياً بناءً على ما يكتشفه أثناء تنفيذ المهمة:

// في settings.json
{
  "cursor.subagents.dynamicCreation": true,
  "cursor.subagents.dynamicMaxAgents": 8,
  "cursor.subagents.dynamicTemplate": {
    "model": "cursor-fast",
    "tools": ["read", "write", "edit"],
    "scope": {
      "strictMode": true
    }
  }
}

مع تفعيل الإنشاء الديناميكي، يمكن للمخطط توليد وكلاء فرعيين جدد حسب الحاجة. على سبيل المثال، إذا اكتشف المخطط أن المهمة تتضمن ملفات Python و TypeScript، يمكنه إنشاء وكيل فرعي مخصص لـ Python ووكيل فرعي مخصص لـ TypeScript أثناء التنفيذ.

warning

الإنشاء الديناميكي للوكلاء الفرعيين يمكن أن يؤدي إلى تناسل وكلاء غير منضبط إذا بالغ المخطط في تقدير الحاجة إلى التوازي. اضبط دائماً dynamicMaxAgents إلى حد معقول (4-8) وراقب إجمالي استخدام الرموز. إذا أنشأ المخطط عدداً كبيراً جداً من الوكلاء الفرعيين، فقد يستنفد ميزانية الرموز قبل إكمال المهمة.

التنسيق مع نقاط التحقق

أضف نقاط تحقق بين تشغيلات الوكلاء الفرعيين للسماح بالمراجعة البشرية أو التحقق المؤتمت:

execution:
  strategy: sequential
  checkpoints:
    - after: "schema-generator"
      action: "validate"
      validator: "npm run typecheck"
      onFail: "retry"
      maxRetries: 2

    - after: "api-builder"
      action: "review"
      reviewer: "human"
      timeout: 300000
      onTimeout: "proceed"

تلميح

نقاط التحقق ذات قيمة خاصة في تكاملات CI/CD حيث تريد التحقق من النتائج الوسيطة قبل المتابعة. نقطة تحقق validate تشغل أمراً ولا تتقدم إلا إذا انتهى بنجاح، بينما نقطة تحقق review تتوقف لانتظار إدخال بشري.

المراقبة والتصحيح

عرض حالة الوكلاء الفرعيين

راقب جميع الوكلاء الفرعيين قيد التشغيل من الشريط الجانبي لـ Cursor:

# لوحة الأوامر: Cursor: Show Subagent Dashboard

يعرض لوحة المعلومات:

Subagent Dashboard
==================
Planner: [running] cursor-pro
  Task: "Refactor authentication system"
  Steps: 3/5

Subagents:
  [completed] frontend-auth (cursor-max)
    Files changed: 4
    Tokens used: 12,400

  [running] backend-auth (cursor-max)
    Current file: src/api/middleware/auth.ts
    Tokens used: 8,200

  [running] auth-tests (cursor-fast)
    Current file: test/auth/login.test.ts
    Tokens used: 3,100

  [queued] auth-docs (cursor-fast)
    Waiting for: backend-auth to complete

Total tokens: 23,700 / 100,000

تصحيح انتهاكات النطاق

إذا حاول وكيل فرعي الوصول إلى ملفات خارج نطاقه، يتم تسجيل المحاولة:

# عرض سجل انتهاكات النطاق
# لوحة الأوامر: Cursor: Show Subagent Logs

[WARN] Subagent "frontend-auth" attempted to read src/api/routes.ts
       Access denied: file is outside the agent's scope
       Scope includes: src/components/auth/**, src/contexts/AuthContext.tsx

[WARN] Subagent "backend-auth" attempted to run terminal command: npm install
       Command blocked: not in allowedCommands list
       Allowed commands: npm test, npx tsc, git status

تلميح

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

أفضل الممارسات

• استخدم cursor-pro أو أفضل للمخطط، ونماذج أرخص للوكلاء الفرعيين البسيطين
• اضبط دائماً strictMode: true لنطاقات الملفات لمنع الوصول غير المرغوب
• كون allowedCommands لأي وكيل فرعي لديه وصول للطرفية
• تأكد من عدم تداخل نطاقات الكتابة بين الوكلاء الفرعيين المتوازيين
• اضبط حد maxConcurrent للتحكم في استخدام الموارد
• استخدم نقاط التحقق للمهام الحرجة التي تتطلب التحقق
• راقب استخدام الرموز عبر جميع الوكلاء الفرعيين لتجنب استنفاد الميزانية
• ابدأ بالتنفيذ المتسلسل وانتقل إلى المتوازي بعد التحقق من صحة النطاقات
• راجع ملخص التركيب للمخطط قبل قبول النتائج المتوازية
• ضع تكوين الوكلاء الفرعيين تحت التحكم بالنسخ لاتساق الفريق

warning

يرث الوكلاء الفرعيون مطالبة نظام المخطط بشكل افتراضي. إذا كانت مطالبة النظام الخاصة بك تحتوي على معلومات حساسة، فكر في استخدام مطالبات محددة للوكلاء الفرعيين تستبعد السياق غير الضروري. كون هذا باستخدام إعداد cursor.subagents.inheritPlannerPrompt مضبوطاً على false.

الخلاصة

يوفر الوكلاء الفرعيون في Cursor طريقة قوية لتفكيك المهام المعقدة إلى وحدات متخصصة قابلة للإدارة. من خلال اختيار النماذج بعناية، وتكوين نطاقات ملفات صارمة، وإعداد حدود أمان، واختيار استراتيجية التنسيق الصحيحة، يمكنك بناء سير عمل متعدد الوكلاء يكون فعالاً وآمناً في الوقت ذاته.

الاعتبارات الأهم هي: مطابقة النموذج مع تعقيد المهمة، واستخدام تطبيق النطاق الصارم لمنع مشاكل الوصول إلى الملفات، والبدء بالتنفيذ المتسلسل قبل الانتقال إلى المتوازي. مع هذه الممارسات، يصبح الوكلاء الفرعيون أداة موثوقة للتعامل مع مهام التطوير واسعة النطاق التي قد تكون ساحقة لوكيل واحد.