حل تبعيات Plugin

يتعامل OpenClaw مع تبعيات Plugin أثناء التثبيت/التحديث فقط. ولا يشغّل التحميل في وقت التشغيل مدير حزم مطلقًا، ولا يصلح شجرة تبعيات، ولا يعدّل دليل حزمة OpenClaw.

تقسيم المسؤوليات

تمتلك حزم Plugin رسم تبعياتها:

• توجد تبعيات وقت التشغيل في dependencies أو optionalDependencies الخاصة بحزمة Plugin.
• تكون استيرادات SDK/النواة تبعيات نظيرة أو استيرادات مقدَّمة من OpenClaw.
• تجلب إضافات التطوير المحلية تبعياتها المثبّتة مسبقًا.
• تُثبَّت إضافات npm وgit في جذور حزم مملوكة لـ OpenClaw.

يمتلك OpenClaw دورة حياة Plugin فقط:

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

جذور التثبيت

يستخدم OpenClaw جذورًا ثابتة لكل مصدر:

• تُثبَّت حزم npm في مشاريع منفصلة لكل Plugin ضمن ~/.openclaw/npm/projects/<encoded-package>.
• تُستنسخ حزم git ضمن ~/.openclaw/git.
• تُنسخ تثبيتات المصدر المحلي/المسار/الأرشيف أو يُشار إليها من دون إصلاح التبعيات.

تُشغَّل تثبيتات npm في جذر المشروع الخاص بكل Plugin باستخدام:

cd ~/.openclaw/npm/projects/<encoded-package>npm install --omit=dev --omit=peer --legacy-peer-deps --ignore-scripts --no-audit --no-fund

يستخدم openclaw plugins install npm-pack:<path.tgz> جذر مشروع npm نفسه الخاص بكل Plugin لملف tarball محلي من npm-pack: يقرأ OpenClaw بيانات npm الوصفية لملف tarball، ويضيفه إلى المشروع المُدار كتبعية file: منسوخة، ويشغّل تثبيت npm المعتاد أعلاه، ثم يتحقق من بيانات ملف القفل المثبّت الوصفية قبل الوثوق بـ Plugin. يوجد هذا المسار لإثبات قبول الحزمة والنسخة المرشحة للإصدار، حيث ينبغي أن تتصرف أداة الحزمة المحلية مثل أداة السجل التي تحاكيها.

استخدم npm-pack: عند اختبار حزم Plugin الرسمية أو الخارجية قبل النشر. يفيد تثبيت أرشيف أو مسار خام في تصحيح الأخطاء محليًا، لكنه لا يثبت مسار التبعيات نفسه الخاص بحزمة npm أو ClawHub مثبّتة. يثبت npm-pack: بنية تثبيت الحزمة المُدارة؛ لكنه لا يثبت بمفرده أن Plugin محتوى رسمي مرتبط بالفهرس.

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

إذا أخفق Plugin في وقت التشغيل بسبب استيراد مفقود، فأصلح بيان الحزمة بدلًا من إصلاح المشروع المُدار يدويًا. تنتمي استيرادات وقت التشغيل إلى dependencies أو optionalDependencies الخاصة بحزمة Plugin؛ ولا تُثبَّت devDependencies لمشاريع وقت التشغيل المُدارة. يمكن أن يزيل تنفيذ npm install محليًا داخل ~/.openclaw/npm/projects/<encoded-package> عائقًا أمام تشخيص مؤقت، لكنه ليس إثباتًا لقبول الحزمة لأن التثبيت أو التحديث التالي يعيد إنشاء المشروع من بيانات الحزمة الوصفية.

قد يرفع npm التبعيات المتعدية إلى node_modules الخاص بمشروع كل Plugin بجوار حزمة Plugin. يفحص OpenClaw جذر المشروع المُدار قبل الوثوق بالتثبيت، ويزيل ذلك المشروع عند إلغاء التثبيت، لذلك تظل تبعيات وقت التشغيل المرفوعة داخل حدود التنظيف الخاصة بذلك Plugin.

يمكن لحزم Plugin المنشورة على npm تضمين npm-shrinkwrap.json؛ ويستخدم npm ملف القفل القابل للنشر هذا أثناء التثبيت، ويدعمه جذر مشروع npm المُدار في OpenClaw عبر مسار التثبيت المعتاد. يجب أن تتضمن حزم Plugin القابلة للنشر والمملوكة لـ OpenClaw ملف shrinkwrap محليًا للحزمة ومولّدًا من رسم التبعيات المنشور لتلك الحزمة:

pnpm deps:shrinkwrap:generatepnpm deps:shrinkwrap:check

يزيل المولّد devDependencies الخاصة بـ Plugin، ويطبّق سياسة تجاوز مساحة العمل، ويكتب extensions/<id>/npm-shrinkwrap.json لكل Plugin يحتوي على openclaw.release.publishToNpm: true. يمكن لحزم Plugin التابعة لجهات خارجية أيضًا تضمين ملف shrinkwrap؛ ولا يشترط OpenClaw وجوده لحزم المجتمع، لكن npm يلتزم به عند وجوده.

قبل اعتبار حزمة محلية إثباتًا لنسخة مرشحة للإصدار، افحص ملف tarball الذي سيُثبَّت:

npm pack --pack-destination /tmptar -xOf /tmp/<plugin-package>.tgz package/package.jsontar -tf /tmp/<plugin-package>.tgz | grep '^package/dist/'

بالنسبة إلى تغييرات التبعيات، تحقق أيضًا من قدرة تثبيت إنتاجي على حل حزم وقت التشغيل من دون تبعيات التطوير:

tmpdir=$(mktemp -d)(  cd "$tmpdir"  npm init -y >/dev/null  npm install --package-lock-only --omit=dev --omit=peer --legacy-peer-deps --ignore-scripts /tmp/<plugin-package>.tgz)rm -rf "$tmpdir"

يمكن أيضًا لحزم npm الخاصة بـ Plugin والمملوكة لـ OpenClaw أن تُنشر باستخدام bundledDependencies صريحة. يضع مسار نشر npm قائمة أسماء تبعيات وقت التشغيل كطبقة فوقية، ويزيل بيانات مساحة العمل المخصصة للتطوير فقط من البيان المنشور، ويشغّل تثبيت npm من دون نصوص برمجية لتبعيات وقت التشغيل المحلية للحزمة، ثم يحزم ملف tarball الخاص بـ Plugin أو ينشره مع تضمين ملفات تلك التبعيات. تلغي الحزم كثيفة الاعتماد على المكونات الأصلية (Codex وACPX وCopilot وllama.cpp وmemory-lancedb وTlon) ذلك باستخدام openclaw.release.bundleRuntimeDependencies: false؛ وتظل تشحن ملف shrinkwrap، لكن npm يحل تبعيات وقت التشغيل أثناء التثبيت بدلًا من تضمين كل ملف ثنائي لكل منصة في ملف tarball الخاص بـ Plugin. لا تجمع حزمة openclaw الجذرية شجرة تبعياتها الكاملة.

تعلن الإضافات التي تستورد openclaw/plugin-sdk/* عن openclaw كتبعية نظيرة. لا يسمح OpenClaw لـ npm بتثبيت نسخة منفصلة من حزمة المضيف من السجل داخل مشروع مُدار، لأن حزمة مضيف قديمة يمكن أن تؤثر في حل npm للتبعيات النظيرة داخل ذلك Plugin. تتخطى تثبيتات npm المُدارة حل npm للتبعيات النظيرة وتجسيدها، ويعيد OpenClaw فرض روابط node_modules/openclaw المحلية الخاصة بـ Plugin للحزم المثبّتة التي تعلن عن تبعية المضيف النظيرة، بعد التثبيت أو التحديث.

تستنسخ تثبيتات git المستودع أو تحدّثه، ثم تشغّل:

npm install --omit=dev --ignore-scripts --no-audit --no-fund

بعد ذلك يُحمَّل Plugin المثبّت من دليل تلك الحزمة، لذلك يعمل حل node_modules المحلي للحزمة والأبوي بالطريقة نفسها التي يعمل بها في حزمة Node عادية.

الإضافات المحلية

الإضافات المحلية هي أدلة يتحكم فيها المطور. لا يشغّل OpenClaw مطلقًا npm install أو pnpm install أو إصلاح التبعيات لها؛ فإذا كانت لـ Plugin محلية تبعيات، فثبّتها داخل تلك الإضافة قبل تحميلها.

تُحمَّل إضافات TypeScript المحلية التابعة لجهات خارجية عبر Jiti كمسار طوارئ. وتُحمَّل إضافات JavaScript المحزّمة والإضافات الداخلية المضمّنة عبر import/require الأصليين بدلًا من ذلك.

بدء التشغيل وإعادة التحميل

لا يثبّت بدء تشغيل Gateway وإعادة تحميل الإعدادات تبعيات Plugin مطلقًا. فهما يقرآن سجلات تثبيت Plugin، ويحسبان نقطة الدخول، ويحمّلانها.

يؤدي فقدان تبعية في وقت التشغيل إلى إخفاق تحميل Plugin مع خطأ يوجّه المشغّل إلى إصلاح صريح:

openclaw plugins update <id>openclaw plugins install <source>openclaw doctor --fix

ينظف doctor --fix حالة التبعيات القديمة التي أنشأها OpenClaw، ويمكنه استعادة الإضافات القابلة للتنزيل والمفقودة من سجلات التثبيت المحلية عندما تظل الإعدادات تشير إليها. لا يصلح Doctor تبعيات Plugin محلية مثبّتة بالفعل.

الإضافات المضمّنة

تأتي الإضافات المضمّنة خفيفة الوزن والضرورية للنواة كجزء من OpenClaw. وينبغي إما ألا تحمل شجرة كبيرة من تبعيات وقت التشغيل، أو أن تنتقل إلى حزمة قابلة للتنزيل على ClawHub/npm.

للاطلاع على القائمة المولّدة الحالية للإضافات التي تأتي ضمن الحزمة الأساسية، أو تُثبَّت خارجيًا، أو تظل متاحة كمصدر فقط، راجع مخزون Plugin.

يجب ألا تطلب بيانات الإضافات المضمّنة تجهيز التبعيات. ينبغي تحزيم وظائف Plugin الكبيرة أو الاختيارية كإضافة عادية وتثبيتها عبر مسار npm/git/ClawHub نفسه المستخدم لإضافات الجهات الخارجية.

في نسخ المصدر، يتعامل OpenClaw مع المستودع بوصفه مستودعًا أحاديًا لـ pnpm. بعد pnpm install، تُحمَّل الإضافات المضمّنة من extensions/<id> كي تتوفر تبعيات مساحة العمل المحلية للحزمة وتُلتقط التعديلات مباشرةً. يقتصر تطوير نسخة المصدر على pnpm؛ ولا يجهّز تنفيذ npm install العادي في جذر المستودع تبعيات Plugin المضمّنة.

تنظيف المكوّنات القديمة

أنشأت إصدارات OpenClaw الأقدم جذور تبعيات للإضافات المضمّنة عند بدء التشغيل أو أثناء إصلاح Doctor. يزيل التنظيف الحالي في Doctor تلك الأدلة والروابط الرمزية القديمة باستخدام --fix، بما في ذلك جذور plugin-runtime-deps القديمة، والروابط الرمزية العامة لحزم بادئة Node التي تشير إلى أهداف plugin-runtime-deps المشذّبة، وبيانات .openclaw-runtime-deps*، وnode_modules المولّدة للإضافات، وأدلة مراحل التثبيت، ومخازن pnpm المحلية للحزم. كما تزيل مرحلة ما بعد التثبيت للحزمة تلك الروابط الرمزية العامة قبل تشذيب الجذور القديمة المستهدفة، كي لا تترك الترقيات استيرادات حزم ESM معلّقة.

استخدمت تثبيتات npm الأقدم أيضًا جذرًا مشتركًا في ~/.openclaw/npm/node_modules. ولا تزال مسارات التثبيت والتحديث وإلغاء التثبيت وDoctor الحالية تتعرف على ذلك الجذر المسطّح القديم لأغراض الاستعادة والتنظيف فقط. أما تثبيتات npm الجديدة فتنشئ جذور مشاريع منفصلة لكل Plugin بدلًا منه.