DeepSeek Harness: تحميل الإضافات المحلية

آخر تحديث: 2026-08-31

فهم آلية تحميل الإضافات هو القفزة الأساسية من "كتابة إضافة" إلى "تطوير إضافات بكفاءة." cordis.yml هو مركز إعدادات DSH، وآلية تراكب --patch تتيح لك تركيب الإضافات المحلية بمرونة دون تعديل الإعدادات الافتراضية.

📋 المتطلبات المسبقة: أكمل 11-first-plugin.md، قادر على إنشاء إضافة أدنى

1. ما ستتعلمه

• تفاصيل ملف إعدادات cordis.yml
• عمليات $insert و $replace
• اختيار المسار المطلق مقابل النسبي
• مبادئ آلية تراكب --patch
• --dump-config لعرض الإعدادات النهائية
• سير عمل التطوير والتصحيح المحلي

2. تفاصيل إعدادات cordis.yml

(1) موقع ملف الإعدادات

cordis.yml هو ملف الإعدادات الأساسي لـ DSH، يقع في جذر المشروع:

my-dsh-project/
├── cordis.yml        ← الإعدادات الرئيسية
├── cordis.patch.yml  ← إعدادات التصحيح (اختياري)
├── package.json
└── src/

(2) ▶ مثال 2

# الهيكل الأساسي ل cordis.yml
plugins:
  plugin-name:
    # عناصر إعدادات الإضافة
    enabled: true
    config:
      key: value

# إعدادات عامة
hostname: localhost
port: 5173

(3) صيغة دخول الإضافة

كل دخول إضافة يحتوي ثلاث معلومات:

plugins:
  # إضافة حزمة npm
  @dsh-plugin/database:
    config:
      connection: "postgresql://localhost/mydb"
  
  # إضافة محلية
  my-local-plugin:
    $insert: /home/alice/dev/my-plugin
    config:
      debug: true

3. عمليات $insert و $replace

(1) $insert: إلحاق إضافة

$insert يُضيف إضافة إلى قائمة الإضافات الموجودة:

plugins:
  my-tool:
    $insert: /home/alice/dev/dsh-plugin-my-tool

التأثير يُعادل:

قائمة الإضافات الافتراضية: [core, llm, tools, shell, ...]
بعد الإدراج:       [core, llm, tools, shell, ..., my-tool]

(2) $replace: استبدال إضافة

$replace يستبدل إضافة موجودة بتنفيذ جديد:

plugins:
  # استبدال محول LLM الافتراضي بواحد مخصص
  llm:
    $replace: /home/alice/dev/custom-llm-adapter

التأثير:

الافتراضي: llm → @deepseek-ai/dsh-plugin-llm
المستبدَل: llm → /home/alice/dev/custom-llm-adapter

⚠️ $replace يجب أن يُحدد اسم إضافة موجودة؛ لا يمكنك استبدال دخول غير موجود.

(3) ▶ مثال 3

plugins:
  # إلحاق أداة محلية
  my-tool:
    $insert: /home/alice/dev/dsh-plugin-my-tool
  
  # استبدال shell الافتراضي بنسخة آمنة
  shell:
    $replace: /home/alice/dev/dsh-plugin-safe-shell
  
  # إلحاق إضافة محلية أخرى
  my-monitor:
    $insert: /home/alice/dev/dsh-plugin-monitor

(4) أولوية العمليات

عندما يكون لإضافة واحدة كل من $insert و $replace:

الأولوية: $replace > $insert

إذا كان هدف $replace غير موجود، يرتجع إلى سلوك $insert.

4. استراتيجية المسار

(1) ▶ مثال 1

plugins:
  my-plugin:
    $insert: /home/alice/dev/my-plugin

المزايا:

• لا يتأثر بدليل العمل
• مسار واضح أثناء التصحيح
• إعدادات قابلة لإعادة الاستخدام عبر المشاريع

العيوب:

• مسار المستخدم مُرمّز بثبات، غير قابل للنقل
• أعضاء الفريق لديهم مسارات مختلفة

(2) المسارات النسبية

plugins:
  my-plugin:
    $insert: ./plugins/my-plugin

المسارات النسبية تُحل بناءً على الدليل الحاوي لـ cordis.yml.

المزايا:

• قابل للنقل، مناسب لتعاون الفريق
• يمكن إدارة الإضافات بإصدارات المشروع

العيوب:

• يعتمد على دليل العمل عند البدء
• حساب المسار معقد للأدلة المتداخلة

(3) توصيات اختيار المسار

5. آلية تراكب --patch

(1) نموذج تراكب الإعدادات

إعدادات DSH تُبنى من طبقات متعددة:

graph TB
    BASE[الطبقة الأساسية<br/>الإعدادات الافتراضية] --> BUNDLE[طبقة Bundle<br/>dsh-base / dsh-web-app]
    BUNDLE --> PROFILE[طبقة Profile<br/>web / headless]
    PROFILE --> PATCH[طبقة التصحيح<br/>cordis.yml + --patch]
    PATCH --> FINAL[الإعدادات النهائية]

graph TB
    BASE[الطبقة الأساسية<br/>الإعدادات الافتراضية] --> BUNDLE[طبقة Bundle<br/>dsh-base / dsh-web-app]
    BUNDLE --> PROFILE[طبقة Profile<br/>web / headless]
    PROFILE --> PATCH[طبقة التصحيح<br/>cordis.yml + --patch]
    PATCH --> FINAL[الإعدادات النهائية]

كل طبقة تتجاوز عناصر الإعدادات ذات الاسم من الطبقة السابقة، مشابهة لأولوية تتالي CSS.

(2) معامل --patch

# تطبيق طبقة التصحيح عند البدء
pnpm dsh web --patch

بدون --patch، يقرأ DSH الإعدادات الافتراضية فقط ويتجاهل $insert/$replace في cordis.yml. مع --patch، عمليات التجاوز في cordis.yml تسري.

(3) cordis.patch.yml

بالإضافة للإعدادات الرئيسية، يمكنك استخدام cordis.patch.yml كطبقة تصحيح إضافية:

# cordis.patch.yml — لبيئات التطوير فقط
plugins:
  debug-tools:
    $insert: ./dev-plugins/debug-tools

--patch يقرأ كل من cordis.yml و cordis.patch.yml، والأخير له أولوية أعلى.

(4) قواعد دمج التراكب

الإعدادات الأساسية:  { a: 1, b: 2, c: 3 }
طبقة التصحيح:  { b: 20, d: 4 }
─────────────────────────────
الإعدادات النهائية: { a: 1, b: 20, c: 3, d: 4 }

• حقول بنفس الاسم: طبقة التصحيح تتجاوز الطبقة الأساسية
• حقول جديدة: تُلحق مباشرة
• حقول غير متأثرة: تبقى بدون تغيير

6. --dump-config لعرض الإعدادات النهائية

(1) الاستخدام الأساسي

pnpm dsh web --patch --dump-config

يُخرج الإعدادات النهائية المدمجة بالكامل:

# === الإعدادات المدمجة ===
hostname: localhost
port: 5173
plugins:
  core:
    enabled: true
  llm:
    enabled: true
    config:
      provider: deepseek
  tools:
    enabled: true
  my-tool:              # ← إدراجك
    $insert: /home/alice/dev/my-tool
    config:
      debug: true
  debug-tools:          # ← أُضيف بواسطة patch.yml
    $insert: ./dev-plugins/debug-tools

(2) تصحيح مشاكل الإعدادات

عندما لا تُحمّل إضافة كما هو متوقع، استخدم --dump-config لاستكشاف الأخطاء:

# خطوات استكشاف الأخطاء
pnpm dsh web --patch --dump-config > config-dump.yml
# تحقق إن كانت إضافتك تظهر في الإعدادات النهائية
# تحقق إن كان مسار $insert صحيحاً

(3) عرض إضافة محددة فقط

# تصفية لعرض إعدادات إضافة محددة
pnpm dsh web --patch --dump-config | grep -A 10 "my-plugin"

7. سير عمل التطوير والتصحيح المحلي

(1) حلقة التطوير القياسية

graph LR
    CODE[كتابة كود الإضافة] --> REG[التسجيل في cordis.yml]
    REG --> START[بدء dsh web --patch]
    START --> TEST[اختبار سلوك الإضافة]
    TEST --> BUG{أخطاء؟}
    BUG -->|نعم| CODE
    BUG -->|لا| DONE[تم]

graph LR
    CODE[كتابة كود الإضافة] --> REG[التسجيل في cordis.yml]
    REG --> START[بدء dsh web --patch]
    START --> TEST[اختبار سلوك الإضافة]
    TEST --> BUG{أخطاء؟}
    BUG -->|نعم| CODE
    BUG -->|لا| DONE[تم]

(2) نصائح للتكرار السريع

سير عمل Alice النموذجي عند تطوير إضافة أداة:

# 1. إعداد cordis.yml لمرة واحدة
cat > cordis.yml << 'EOF'
plugins:
  my-tool:
    $insert: /home/alice/dev/dsh-plugin-my-tool
EOF

# 2. حلقة التطوير
# تعديل الكود → إعادة التشغيل → الاختبار
pnpm dsh web --patch
# عند الانتهاء من الاختبار، Ctrl+C للتوقف

# 3. التحقق من الإعدادات
pnpm dsh web --patch --dump-config | grep my-tool

(3) التطوير المتوازي لإضافات متعددة

Bob يطور إضافتين في نفس الوقت:

# cordis.yml
plugins:
  tool-a:
    $insert: /home/bob/dev/dsh-plugin-a
  tool-b:
    $insert: /home/bob/dev/dsh-plugin-b

طوّر في طرفيات منفصلة؛ كلتا الإضافتين تُحمّلان عند إعادة تشغيل DSH.

(4) تعطيل إضافة مؤقتاً

لا حاجة لإلغاء التثبيت — علّقها فقط في الإعدادات:

plugins:
  my-tool:
    $insert: /home/alice/dev/my-tool
  # experimental-tool:       # معطّلة مؤقتاً
  #   $insert: /home/alice/dev/exp-tool

❓ أسئلة شائعة

📖 ملخص

• cordis.yml هو مركز إعدادات إضافات DSH، يحتوي مسارات الإضافات وعناصر الإعدادات
• $insert يُلحق إضافات، $replace يستبدل إضافات موجودة
• المسارات المطلقة تناسب التطوير الشخصي، النسبية تناسب تعاون الفريق
• --patch يُفعّل آلية التراكب، يركّب cordis.yml فوق الإعدادات الافتراضية
• --dump-config يعرض الإعدادات المدمجة النهائية — أداة قوية لاستكشاف مشاكل التحميل
• حلقة التطوير: تعديل الكود → التسجيل في cordis.yml → dsh web --patch → الاختبار

📝 تمارين

1. ⭐ أساسي： سجّل إضافة hello-world من الدرس السابق باستخدام $insert في cordis.yml، واستخدم --dump-config للتأكد من ظهورها في الإعدادات النهائية.

2. ⭐⭐ متوسط： سجّل نفس الإضافة باستخدام كل من المسار المطلق والنسبي، واستخدم --dump-config لمقارنة فروق المخرجات بين الإعدادين.

3. ⭐⭐⭐ تحدٍ： أنشئ إضافتين محليتين A و B، و $insert كليهما في cordis.yml. جرّب استخدام $replace لاستبدال إحدى إضافات الأدوات المدمجة في DSH بنسختك المخصصة، وتحقق من الاستبدال باستخدام --dump-config.

فريق Web-Tutorial التقني

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

من نحن