DeepSeek Harness: تثبيت الإضافات وترتيب تحميل التكوين

Q: هل يمكنني التثبيت من سجل npm خاص؟

نعم. هيّئ .npmrc : text @dsh-plugin:registry=https://my-registry.com/

Q: هل يمكن تراكب ملفات patch متعددة؟

حاليًا يُدعم ملف cordis.patch.yml واحد فقط. إذا احتجت عدة تصحيحات، ادمجها في ملف واحد.

Q: كيف أزيل إضافة بالكامل؟

bash # 1. أزل مدخل الإضافة من cordis.yml # 2. أزل حزمة npm pnpm remove @dsh-plugin/database # 3. أعد تشغيل DSH

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

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

💡 نصيحة: أهم خطوة بعد تثبيت إضافة هي --dump-config — تأكد أن إضافتك تظهر فعلاً في التكوين النهائي. كثير من مشاكل "الإضافة لا تعمل" هي مجرد أخطاء في أولوية التكوين.

📋 المتطلبات المسبقة: إكمال 12-local-plugin.md و 26-bundle-profile.md

1. ما ستتعلمه

تثبيت إضافات npm
التثبيت المباشر من مستودع GitHub
التثبيت من tarball
أولوية تحميل التكوين
تصحيحات cordis.patch.yml الساخنة
حل تعارضات الإضافات

ترتيب تحميل التكوين

2. تثبيت إضافات npm

(1) ▶ مثال 1

BASH

# تثبيت أحدث إصدار
pnpm add @dsh-plugin/database

# تثبيت إصدار محدد
pnpm add @dsh-plugin/database@1.2.0

# تثبيت كـ devDependency
pnpm add -D @dsh-plugin/debug-tools

(2) التسجيل بعد التثبيت

الإضافات المثبتة عبر npm تحتاج إلى التسجيل في cordis.yml:

YAML

# cordis.yml
plugins:
  '@dsh-plugin/database':
    config:
      connection: 'postgresql://localhost/mydb'

(3) استخدام dsh plugin add

يوفر DSH أمر تثبيت أكثر ملاءمة:

BASH

# تثبيت وتسجيل تلقائي
dsh plugin add @dsh-plugin/database

# تثبيت مع تكوين
dsh plugin add @dsh-plugin/database --config.connection='postgresql://localhost/mydb'

# مخرجات التثبيت
📦 Installing @dsh-plugin/database@1.2.0...
✅ Plugin installed and registered!

(4) ▶ مثال 4

JSON

// package.json
{
  "dependencies": {
    "@dsh-plugin/database": "^1.2.0",
    "@dsh-plugin/redis": "~2.1.0"
  }
}

الرمز	المعنى	نطاق التحديث
`^1.2.0`	متوافق مع 1.x	1.2.0 ~ 1.9.9
`~2.1.0`	متوافق مع 2.1.x	2.1.0 ~ 2.1.9
`1.2.0`	إصدار محدد	فقط 1.2.0

3. التثبيت المباشر من مستودع GitHub

(1) طرق التثبيت

BASH

# تثبيت الفرع الافتراضي
pnpm add github:alice/dsh-plugin-redis

# تثبيت فرع محدد
pnpm add github:alice/dsh-plugin-redis#feature/cluster

# تثبيت وسم محدد
pnpm add github:alice/dsh-plugin-redis#v2.1.0

# تثبيت commit محدد
pnpm add github:alice/dsh-plugin-redis#abc1234

(2) استخدام dsh plugin add

BASH

dsh plugin add github:alice/dsh-plugin-redis

(3) ملاحظات تثبيت GitHub

ملاحظة	الوصف
يتطلب Git	يجب أن يكون Git مثبتًا على الجهاز
بنية المستودع	يجب أن يكون حزمة Node.js صالحة (يحتوي package.json)
خطوة البناء	قد يحتاج المستودع إلى بناء أولًا
الشبكة	يتطلب وصولًا إلى GitHub
قفل الإصدار	يُفضّل تجزئة commit على اسم الفرع

(4) تمثيل في package.json

JSON

{
  "dependencies": {
    "@dsh-plugin/redis": "github:alice/dsh-plugin-redis#v2.1.0"
  }
}

4. التثبيت من tarball

(1) التثبيت من URL

BASH

# التثبيت من tarball بعيد
pnpm add https://example.com/dsh-plugin-custom-1.0.0.tgz

# التثبيت من tarball محلي
pnpm add ./packages/dsh-plugin-custom-1.0.0.tgz

(2) إنشاء tarball باستخدام npm pack

BASH

# في مشروع الإضافة
cd dsh-plugin-my-tool
npm pack
# يُنشئ: dsh-plugin-my-tool-1.0.0.tgz

# في مشروع DSH
pnpm add ../dsh-plugin-my-tool/dsh-plugin-my-tool-1.0.0.tgz

(3) حالات استخدام tarball

السيناريو	الوصف
إضافات خاصة	غير منشورة على npm، يُوزَّع tgz مباشرة
تثبيت دون اتصال	بلا وصول إلى npm أو GitHub
CI/CD	تثبيت مخرجات البناء مباشرة
اختبار ما قبل الإصدار	تثبيت إصدارات مرشحة للاختبار

(4) مقارنة بين طرق التثبيت الثلاث

الطريقة	الأمر	تتطلب شبكة	إدارة الإصدار	الأنسب لـ
npm	`pnpm add @dsh-plugin/xxx`	سجل npm	✅ semver	الإضافات العامة
GitHub	`pnpm add github:user/repo`	GitHub	⚠️ فرع/وسم	الإضافات قيد التطوير
tarball	`pnpm add ./xxx.tgz`	لا	❌ يدوي	الإضافات الخاصة/دون اتصال

5. أولوية تحميل التكوين

(1) خمس طبقات أولوية

graph TB
    L5["الطبقة 5: معاملات CLI<br/>(الأولوية القصوى)"]
    L4["الطبقة 4: cordis.patch.yml"]
    L3["الطبقة 3: cordis.yml الخاص بالمشروع"]
    L2["الطبقة 2: تكوين Profile"]
    L1["الطبقة 1: افتراضيات Bundle<br/>(الأولوية الأدنى)"]
    L5 --> L4 --> L3 --> L2 --> L1

(2) ▶ مثال 2

TEXT 📖 للعرض فقط

افتراضيات Bundle:    plugins: [core, llm, tools], port: 5173
Profile (web):     plugins: [+web-ui]
تكوين المشروع:    plugins: [+my-tool], port: 8080
Patch:             plugins: [+debug-tools], debug: true
CLI:               port: 3000

النهائي:           plugins: [core, llm, tools, web-ui, my-tool, debug-tools]
                   port: 3000, debug: true

(3) معالجة الإضافات بنفس الاسم

عند تسجيل طبقات متعددة لنفس اسم الإضافة، تتجاوز الطبقة ذات الأولوية الأعلى الأدنى:

TEXT 📖 للعرض فقط

Bundle:           llm → deepseek-adapter
تكوين المشروع:   llm → openai-adapter (يتجاوز)
Patch:            llm → custom-adapter (يتجاوز مرة أخرى)

النهائي: llm → custom-adapter

(4) عرض ترتيب التحميل

BASH

pnpm dsh web --patch --dump-config

المخرجات تُعلِّم الطبقة المصدر لكل قيمة تكوين.

6. تصحيحات cordis.patch.yml الساخنة

(1) غرض التصحيح الساخن

تُعدِّل التصحيحات الساخنة الإعدادات مؤقتًا دون تعديل التكوين الأساسي:

YAML

# cordis.patch.yml
plugins:
  debug-tools:
    $insert: ./dev-plugins/debug-tools
  llm:
    config:
      debug: true

(2) تفعيل التصحيحات الساخنة

BASH

# يجب إضافة --patch لتحميل ملف التصحيح
pnpm dsh web --patch

(3) تصحيحات الإنتاج الساخنة

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

YAML

# cordis.patch.prod.yml — تعطيل إضافة مشكلة بشكل طارئ
plugins:
  problematic-plugin:
    enabled: false
  llm:
    config:
      maxRetries: 5  # زيادة محاولات الإعادة مؤقتًا

(4) التراجع عن التصحيح الساخن

BASH

# تطبيق التصحيح الساخن
cp cordis.patch.prod.yml cordis.patch.yml
pnpm dsh web --patch

# التراجع عن التصحيح الساخن (حذف ملف التصحيح)
rm cordis.patch.yml
pnpm dsh web

(5) التصحيحات الساخنة و Git

TEXT 📖 للعرض فقط

# .gitignore
cordis.patch.yml           # تجاهل التصحيح الحالي
cordis.patch.prod.yml      # تجاهل تصحيح الإنتاج
# cordis.patch.dev.yml    # أودع تصحيح التطوير (لمشاركة الفريق)

7. حل تعارضات الإضافات

(1) أنواع التعارضات الشائعة

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

(2) تعارض الأدوات بنفس الاسم

TEXT 📖 للعرض فقط

الإضافة A: تسجّل أداة 'search'
الإضافة B: تسجّل أداة 'search'
→ النتيجة: أداة search من الإضافة B هي التي تسري

الحل:

YAML

# تعطيل إحداهما
plugins:
  plugin-a:
    config:
      tools:
        disabled: ['search']

أو استخدم عزل realm.

(3) استكشاف تعارضات التكوين

BASH

# 1. عرض التكوين النهائي
pnpm dsh web --patch --dump-config > dump.yml

# 2. البحث عن عناصر التكوين المتعارضة
grep "my-plugin" dump.yml

# 3. التحقق من التجاوز بواسطة patch
diff cordis.yml cordis.patch.yml

(4) توافق الإصدار

BASH

# فحص توافق الإضافة
dsh plugin check @dsh-plugin/database

# المخرجات
✅ @dsh-plugin/database@1.2.0 is compatible with dsh@0.5.0
⚠️ Requires: dsh >= 0.4.0

(5) شجرة قرار حل التعارضات

graph TD
    CONFLICT{نوع التعارض؟}
    CONFLICT -->|أداة/خدمة بنفس الاسم| SCOPE{تحتاج كليهما؟}
    SCOPE -->|لا| DISABLE[عطّل إحداهما]
    SCOPE -->|نعم| REALM[اعزل بـ realm]
    CONFLICT -->|التكوين لا يسري| DUMP[استكشاف بـ --dump-config]
    DUMP --> FIX[أصلح أولوية التكوين]
    CONFLICT -->|الإصدار غير متوافق| UPDATE[حدّث إصدار الإضافة]
    UPDATE --> CHECK[افحص التوافق]

❓ أسئلة شائعة

س هل يجب إعادة التشغيل بعد تثبيت إضافة؟

ج نعم. الإضافات المثبتة تتطلب إعادة تشغيل DSH لتحميلها. HMR يُحدّث فقط تغييرات الكود في الإضافات الموجودة؛ لا يمكنه تحميل إضافات مثبتة حديثًا.

س هل يمكنني التثبيت من سجل npm خاص؟

ج نعم. هيّئ .npmrc: text @dsh-plugin:registry=https://my-registry.com/

س هل يمكن تراكب ملفات patch متعددة؟

ج حاليًا يُدعم ملف cordis.patch.yml واحد فقط. إذا احتجت عدة تصحيحات، ادمجها في ملف واحد.

س كيف أعرض إصدارات جميع الإضافات المثبتة؟

ج bash dsh plugin list # أو pnpm list | grep dsh-plugin

س ماذا لو فشل تثبيت إضافة؟

ج افحص اتصال الشبكة، وإمكانية الوصول لسجل npm، وصحة اسم الحزمة. راجع pnpm-error.log لمعلومات خطأ مفصّلة.

س كيف أزيل إضافة بالكامل؟

bash # 1. أزل مدخل الإضافة من cordis.yml # 2. أزل حزمة npm pnpm remove @dsh-plugin/database # 3. أعد تشغيل DSH

📖 ملخص

أربع طرق تثبيت: npm (قياسي)، GitHub (قيد التطوير)، tarball (خاص/دون اتصال)، مسار محلي (تطوير)
أولوية التكوين بخمس طبقات: Bundle → Profile → المشروع → Patch → CLI
--dump-config هو الأداة الأساسية لاستكشاف مشاكل التكوين
cordis.patch.yml للتجاوزات المؤقتة؛ --patch يُفعّله
تعارضات الإضافات تُحل بالتعطيل أو عزل realm أو ضبط الأولوية
توافق الإصدار يُفحص عبر dsh plugin check

📝 تمارين

1. ⭐ أساسي： ثبّت إضافة مجتمعية عبر npm (مثلاً @dsh-plugin/database)، سجّلها وتهيئتها في cordis.yml، واستخدم --dump-config لتأكيد سريان التكوين.

2. ⭐⭐ متوسط： أنشئ cordis.patch.yml يتجاوز تكوين إضافة في طبقة patch (مثلاً تغيير النموذج الافتراضي لـ LLM). استخدم --dump-config لمقارنة فروق التكوين مع وبدون التصحيح.

3. ⭐⭐⭐ متقدم： حاكِ سيناريو تعارض إضافات — ثبّت إضافتين تسجّلان أدوات بنفس الاسم، ولاحظ أن الأحدث تتجاوز الأقدم. ثم استخدم عزل realm ليكون لكل إضافة فضاء أدوات مستقل.

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

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

من نحن