Skip to main content
قائمة تحقق للتحقق من التحديثات والإضافات: أثبت أن الحزمة القابلة للتثبيت تستطيع تحديث حالة المستخدم الفعلية، وإصلاح الحالة القديمة المتقادمة عبر doctor، مع استمرار قدرتها على تثبيت الإضافات وتحميلها وتحديثها وإلغاء تثبيتها من كل مصدر مدعوم. لخريطة مشغّل الاختبارات الأشمل، راجع الاختبار. ولمفاتيح المزوّدين الفعلية وحزم الاختبارات التي تتصل بالشبكة، راجع الاختبار الفعلي.

​
ما نحميه

  • حزمة tarball مكتملة، وتحتوي على ملف dist/postinstall-inventory.json صالح، ولا تعتمد على ملفات مستودع غير مضغوطة.
  • يمكن للمستخدم الانتقال من حزمة منشورة أقدم إلى الحزمة المرشحة دون فقدان الإعدادات أو الوكلاء أو الجلسات أو مساحات العمل أو قوائم السماح للإضافات أو إعدادات القنوات.
  • يتولى openclaw doctor --fix --non-interactive مسارات التنظيف والإصلاح القديمة. ويجب ألا يضيف بدء التشغيل عمليات ترحيل توافق مخفية لحالة الإضافات المتقادمة.
  • تعمل عمليات تثبيت الإضافات من الأدلة المحلية، ومستودعات git، وحزم npm، ومسار سجل ClawHub.
  • تُثبَّت تبعيات npm الخاصة بكل إضافة في مشروع npm مُدار واحد لكل إضافة، وتُفحص قبل منح الثقة، وتُزال عبر npm uninstall عند إلغاء تثبيت الإضافة كي لا تبقى التبعيات المرفوعة.
  • لا يُجري تحديث الإضافة أي عملية عندما لا يتغير شيء: تظل سجلات التثبيت، والمصدر المحلول، وتخطيط التبعيات المثبتة، وحالة التفعيل سليمة.

​
الإثبات المحلي أثناء التطوير

ابدأ بنطاق ضيق:
بالنسبة إلى تغييرات تثبيت الإضافات أو إلغاء تثبيتها أو تبعياتها أو مخزون الحزمة، شغّل أيضًا الاختبارات المركزة التي تغطي الحد الفاصل المعدَّل:
قبل أن يستهلك أي مسار Docker للحزم ملف tarball، أثبت سلامة أثر الحزمة:
يشغّل release:check فحوصات انحراف الإعدادات/التوثيق/API (مخطط الإعدادات، وخط أساس توثيق الإعدادات، وخط أساس API الخاص بـ SDK للإضافات وصادراته، وإصدارات الإضافات/مخزونها)، ويكتب مخزون توزيع الحزمة، ويشغّل npm pack --dry-run، ويرفض الملفات المحظورة المضمّنة في الحزمة، ويثبّت ملف tarball في بادئة مؤقتة، ويشغّل ما بعد التثبيت، ويجري اختبارًا أوليًا لنقاط دخول القنوات المضمّنة.

​
مسارات Docker

تمثّل مسارات Docker إثباتًا على مستوى المنتج. فهي تثبّت حزمة فعلية أو تحدّثها داخل حاويات Linux، وتتحقق من السلوك عبر أوامر CLI، وبدء تشغيل Gateway، ومجسّات HTTP، وحالة RPC، وحالة نظام الملفات. استخدم المسارات المركزة أثناء التكرار:
المسارات المهمة:
  • يغطي test:docker:plugins الاختبار الأولي لتثبيت الإضافات، وعمليات التثبيت من المجلدات المحلية، وسلوك تخطي تحديث المجلدات المحلية، والمجلدات المحلية ذات التبعيات المثبتة مسبقًا، وعمليات تثبيت حزم file:، وعمليات التثبيت من git مع تنفيذ CLI، وتحديثات المراجع المتحركة في git، وعمليات التثبيت من سجل npm مع التبعيات الانتقالية المرفوعة، وعدم تنفيذ تحديثات npm عند غياب التغييرات، ورفض بيانات تعريف حزم npm المشوهة، وعمليات التثبيت من تجهيزات ClawHub المحلية وعدم تنفيذ التحديثات عند غياب التغييرات، وسلوك تحديث السوق، وتفعيل/فحص حزمة Claude. عيّن OPENCLAW_PLUGINS_E2E_CLAWHUB=0 لإبقاء كتلة ClawHub معزولة/دون اتصال.
  • يثبّت test:docker:plugin-lifecycle-matrix الحزمة المرشحة في حاوية فارغة، ويمرّر إضافة npm عبر التثبيت والفحص والتعطيل والتفعيل والترقية الصريحة والرجوع الصريح إلى إصدار أقدم وإلغاء التثبيت بعد حذف شيفرة الإضافة. ويسجل مقاييس RSS وCPU لكل مرحلة.
  • يتحقق test:docker:plugin-update من أن الإضافة المثبتة التي لم تتغير لا تُعاد تثبيتها ولا تفقد بيانات تعريف التثبيت أثناء openclaw plugins update.
  • يثبّت test:docker:upgrade-survivor ملف tarball المرشح فوق تجهيز مستخدم قديم غير نظيف، ويشغّل تحديث الحزمة مع doctor غير التفاعلي، ثم يبدأ Gateway عبر local loopback ويتحقق من الحفاظ على الحالة.
  • يثبّت test:docker:published-upgrade-survivor أولًا خط أساس منشورًا، ويضبطه عبر وصفة openclaw config set مضمّنة، ثم يحدّثه إلى ملف tarball المرشح، ويشغّل doctor، ويتحقق من تنظيف العناصر القديمة، ويبدأ Gateway، ويفحص /healthz و/readyz وحالة RPC.
  • يثبّت test:docker:update-restart-auth الحزمة المرشحة، ويبدأ Gateway مُدارًا بمصادقة الرمز المميز، ويلغي تعيين متغيرات بيئة مصادقة Gateway الخاصة بالمتصل لأمر openclaw update --yes --json، ويشترط أن يعيد أمر تحديث الحزمة المرشحة تشغيل Gateway قبل المجسّات المعتادة.
  • يمثّل test:docker:update-migration مسار التحديث المنشور كثيف التنظيف. فهو يبدأ من حالة مستخدم مضبوطة بأسلوب Discord/Telegram، ويشغّل doctor الخاص بخط الأساس كي تتاح لتبعيات الإضافات المضبوطة فرصة التحقق ماديًا، ويزرع بقايا قديمة لتبعيات إضافة معبأة ومضبوطة، ثم يحدّث إلى ملف tarball المرشح، ويشترط أن يزيل doctor بعد التحديث جذور التبعيات القديمة.
تنويعات مفيدة لمسار النجاة من ترقية منشورة:
السيناريوهات المتاحة: base وacpx-openclaw-tools-bridge وfeishu-channel وbootstrap-persona وchannel-post-core-restore وplugin-deps-cleanup وconfigured-plugin-installs وstale-source-plugin-shadow وtilde-log-path وversioned-runtime-deps. في عمليات التشغيل المجمعة، تتوسع OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=reported-issues (الاسم البديل far-reaching) لتشمل جميع السيناريوهات، بما فيها ترحيل تثبيت الإضافات المضبوطة. يُفصل ترحيل التحديث الكامل عمدًا عن CI للإصدار الكامل. استخدم سير العمل اليدوي Update Migration عندما يكون سؤال الإصدار هو: «هل يمكن لكل إصدار مستقر منشور بدءًا من 2026.4.23 التحديث إلى هذه الحزمة المرشحة وتنظيف بقايا تبعيات الإضافات؟»:

​
قبول الحزمة

قبول الحزمة هو بوابة الحزمة الأصلية في GitHub. فهو يحوّل حزمة مرشحة واحدة إلى ملف tarball باسم package-under-test، ويسجل الإصدار وSHA-256، ثم يشغّل مسارات Docker E2E القابلة لإعادة الاستخدام على ملف tarball نفسه تمامًا. ويكون مرجع تجهيز سير العمل منفصلًا عن مرجع مصدر الحزمة، بحيث يمكن لمنطق الاختبار الحالي التحقق من الإصدارات الأقدم الموثوقة. مصادر الحزمة المرشحة:
  • source=npm: التحقق من openclaw@extended-stable أو openclaw@beta أو openclaw@latest أو إصدار منشور محدد.
  • source=ref: حزم فرع أو وسم أو التزام موثوق باستخدام التجهيز الحالي المحدد.
  • source=url: التحقق من ملف tarball عام عبر HTTPS مع package_sha256 مطلوب. يرفض هذا المسار بيانات الاعتماد في URL، ومنافذ HTTPS غير الافتراضية، وأسماء المضيفين الخاصة/الداخلية أو نتائج DNS/IP، ونطاقات IP ذات الاستخدام الخاص، وعمليات إعادة التوجيه غير الآمنة.
  • source=trusted-url: التحقق من ملف tarball عبر HTTPS مع package_sha256 وtrusted_source_id مطلوبين وفق السياسة التي يملكها المشرفون في .github/package-trusted-sources.json. استخدم هذا للمرايا المؤسسية/الخاصة بدلًا من إضعاف source=url بمفتاح سماح بالخصوصية على مستوى الإدخال. تستخدم مصادقة Bearer، عندما تضبطها السياسة، السر الثابت OPENCLAW_TRUSTED_PACKAGE_TOKEN.
  • source=artifact: إعادة استخدام ملف tarball رفعته عملية تشغيل Actions أخرى.
يستخدم التحقق الكامل من الإصدار source=artifact افتراضيًا، ويُبنى من SHA المحلول للإصدار. ولإثبات ما بعد النشر، مرّر package_acceptance_package_spec=openclaw@YYYY.M.PATCH كي تستهدف مصفوفة الترقية نفسها حزمة npm المشحونة بدلًا من ذلك. تستدعي فحوصات الإصدار قبول الحزمة مع مجموعة الحزمة/التحديث/إعادة التشغيل/الإضافة:
عند تفعيل فترة مراقبة الإصدار (تُفرض عند release_profile=stable و full)، فإنها تمرّر أيضًا:
يُبقي ذلك ترحيل الحزمة، وتبديل قناة التحديث، وتحمل الإضافات المُدارة التالفة، وتنظيف تبعيات الإضافات المتقادمة، وتغطية الإضافات دون اتصال، وسلوك تحديث الإضافات، وضمان جودة حزمة Telegram على الأثر المحلول نفسه، دون جعل بوابة حزمة الإصدار الافتراضية تمر على كل إصدار منشور. يُحل last-stable-4 إلى أحدث أربعة إصدارات مستقرة من OpenClaw منشورة على npm. يثبّت قبول حزمة الإصدار 2026.4.23 باعتباره أول حد توافق لتحديث الإضافات، و2026.5.2 باعتباره حدًا لاضطراب بنية الإضافات، و2026.4.15 باعتباره خط أساس أقدم لتحديث منشور من سلسلة 2026.4.1x؛ وتزيل أداة الحل التثبيتات المكررة الموجودة أصلًا ضمن أحدث أربعة إصدارات. ولتغطية شاملة لترحيل التحديثات المنشورة، استخدم all-since-2026.4.23 في سير عمل ترحيل التحديث المنفصل بدلًا من CI للإصدار الكامل. ويظل release-history متاحًا لأخذ عينات يدوية أوسع عندما تريد أيضًا مرساة قديمة تسبق التاريخ. عند تحديد عدة خطوط أساس للنجاة من الترقية المنشورة، يقسم سير عمل Docker القابل لإعادة الاستخدام كل خط أساس إلى مهمة مشغّل مستهدفة خاصة به. يظل كل قسم لخط الأساس يشغّل مجموعة السيناريوهات المحددة، لكن السجلات والآثار تبقى خاصة بكل خط أساس، ويُحدَّد الزمن الكلي بأبطأ قسم بدلًا من مهمة تسلسلية كبيرة واحدة. شغّل ملف تعريف للحزمة يدويًا عند التحقق من حزمة مرشحة قبل الإصدار:
بالنسبة إلى إصدار تجريبي ممتد الاستقرار منشور، عيّن package_spec=openclaw@extended-stable. يحوّل قبول الحزمة هذا المحدد إلى ملف tarball دقيق قبل تشغيل مسارات Docker. استخدم suite_profile=product عندما يشمل سؤال الإصدار قنوات MCP، أو تنظيف Cron/الوكلاء الفرعيين، أو بحث الويب من OpenAI، أو OpenWebUI. استخدم suite_profile=full فقط عندما تحتاج إلى تغطية كاملة لمسار إصدار Docker.

​
الإعداد الافتراضي للإصدار

بالنسبة إلى الحزم المرشحة للإصدار، تكون حزمة الإثبات الافتراضية:
  1. pnpm check:changed وpnpm test:changed لاكتشاف الانحدارات على مستوى المصدر.
  2. pnpm release:check للتحقق من سلامة أثر الحزمة.
  3. ملف تعريف package لقبول الحزمة أو مسارات الحزمة المخصصة لفحص الإصدار للتحقق من عقود التثبيت/التحديث/إعادة التشغيل/الإضافات.
  4. فحوصات إصدار متعددة أنظمة التشغيل لسلوك المثبّت والتهيئة الأولية والمنصة الخاص بكل نظام تشغيل.
  5. حزم الاختبارات الفعلية فقط عندما يمس السطح المتغير سلوك المزوّد أو الخدمة المستضافة.
على أجهزة المشرفين، يجب تشغيل البوابات الواسعة وإثبات منتج Docker/الحزمة في Testbox ما لم يكن الإثبات المحلي مقصودًا صراحةً.

​
التوافق القديم

التساهل في التوافق ضيق ومحدد زمنيًا:
  • قد تتسامح الحزم حتى 2026.4.25، بما فيها 2026.4.25-beta.*، مع فجوات بيانات تعريف الحزمة المشحونة سابقًا في قبول الحزمة.
  • قد تحذّر الحزمة المنشورة 2026.4.26 بشأن ملفات ختم بيانات تعريف البناء المحلي المشحونة سابقًا.
  • يجب أن تستوفي الحزم اللاحقة العقود الحديثة. تفشل الفجوات نفسها بدلًا من إصدار تحذير أو التخطي.
لا تضف عمليات ترحيل جديدة عند بدء التشغيل لهذه الأشكال القديمة. أضف إصلاحًا في doctor أو وسّعه، ثم أثبته باستخدام upgrade-survivor أو published-upgrade-survivor أو update-restart-auth عندما يكون أمر التحديث مسؤولًا عن إعادة التشغيل.

​
إضافة التغطية

عند تغيير سلوك التحديث أو الإضافات، أضف التغطية في أدنى طبقة يمكن أن تفشل للسبب الصحيح:
  • منطق المسار البحت أو البيانات الوصفية: اختبار وحدة بجوار المصدر.
  • سلوك جرد الحزمة أو الملفات المضمّنة فيها: اختبار package-dist-inventory أو اختبار مدقق حزمة tarball.
  • سلوك تثبيت/تحديث CLI: تحقق في مسار Docker أو تجهيز اختباري.
  • سلوك ترحيل الإصدار المنشور: سيناريو published-upgrade-survivor.
  • سلوك إعادة التشغيل الذي يديره التحديث: update-restart-auth.
  • سلوك مصدر السجل/الحزمة: تجهيز اختباري لـ test:docker:plugins أو خادم تجهيز اختباري لـ ClawHub.
  • سلوك تخطيط التبعيات أو التنظيف: تحقق من كلٍ من التنفيذ في وقت التشغيل وحدود نظام الملفات. قد تُرفع تبعيات npm داخل مشروع npm المُدار الخاص بالـ Plugin، لذا ينبغي أن تثبت الاختبارات أن هذا المشروع يُفحص ويُنظّف بدلًا من افتراض فحص شجرة node_modules المحلية لحزمة الـ Plugin فقط.
أبقِ تجهيزات Docker الاختبارية الجديدة معزولة افتراضيًا. استخدم سجلات تجهيز اختبارية محلية وحزمًا وهمية ما لم يكن الغرض من الاختبار هو سلوك السجل الفعلي.

​
فرز حالات الفشل

ابدأ بهوية الأثر:
  • ملخص resolve_package في قبول الحزمة: المصدر، والإصدار، وSHA-256، واسم الأثر.
  • آثار Docker: .artifacts/docker-tests/**/summary.json، وfailures.json، وسجلات المسارات، وأوامر إعادة التشغيل.
  • ملخص النجاة من الترقية: .artifacts/upgrade-survivor/summary.json، بما في ذلك الإصدار الأساسي، والإصدار المرشح، والسيناريو، وتوقيتات المراحل، وتغطية وصفة الإعداد.
فضّل إعادة تشغيل المسار المحدد الذي فشل باستخدام أثر الحزمة نفسه بدلًا من إعادة تشغيل مظلة الإصدار بأكملها.