صيانة الإضافات المثبّتة

استخدم المثبّت لفحص حالة التثبيت المُدارة وتغييرها. عند تقصي مشكلة، احتفظ بمصدر الحزمة والعملاء المختارين والنطاق وهوية التثبيت مع التقرير. تستخدم الأمثلة التالية نطاق المستخدم ما لم تحدد مشروعًا صراحةً.

افحص الوضع أولًا

agentplugins list
agentplugins doctor
agentplugins outdated --all

يعرض list التثبيتات، ويشخّص doctor الحالة المُدارة، ويبحث outdated عن التحديثات المتاحة من دون تطبيقها. ولا يثبت أي منها سلامة خدمة بعيدة أو اكتمال مصادقة العميل.

العَرَض	الخطوة التالية
الحزمة غير موجودة	ارجع إلى البحث والتثبيت.
الملفات المملوكة مفقودة أو تغيرت	راجع خطة إصلاح الحزمة ضمن النطاق المعني.
يتوفر إصدار أحدث من مصدر متابَع	راجع خطة تحديث.
يحتاج العميل إلى الثقة أو التفعيل أو تسجيل الدخول	اتبع تعليمات العميل التي أبلغ عنها الهدف.
تفشل الحزمة المحلية في التحقق	أعطِ المؤلف تقرير الحزمة وإرشادات الفحص.

واجهة API للإدارة المحلية (CLI 0.1.95)

يضيف CLI 0.1.95 الأمر agentplugins manage serve للتطبيقات التي تدمج المثبّت، والأمر agentplugins manage discover لاكتشاف العملاء وملفات التعريف المحلية للقراءة فقط. لا ينفّذ الاكتشاف العملاء، ولا يفحص إصداراتهم، ولا يجلب المصادر، ولا يغيّر الملفات.

manage serve عملية يدير التطبيق المضيف دورة حياتها، وتستخدم سياقًا يُلتقط عند بدء التشغيل وواجهة API خاصة ومصادَقًا عليها عبر عنوان استرجاع IPv4 محلي. يرسل المضيف JSON عبر stdin ويحافظ على خصوصية عنوان URL للتهيئة وقدرة التفويض bearer. افحص مساعدة الأوامر قبل الدمج:

agentplugins version
agentplugins manage serve --help
agentplugins manage discover --help

راجع عقد بروتوكول الإدارة لقواعد بدء التشغيل ودورة الحياة. تُدار إصدارات حزمة SDK للإدارة بلغة TypeScript بشكل مستقل باسم الحزمة universal-agent-plugins-management-sdk. راجع ملف README الخاص بها لمعرفة إصدارات محرك agentplugins المتوافقة وتعليمات تثبيت الحزمة. اختر إصدارًا منشورًا على npm، أو ابنِ حزمة واختبرها انطلاقًا من commit محدد وثابت للشيفرة المصدرية للعمل على تغييرات لم تُنشر بعد. ثبّت كلًّا من SDK والمحرك على إصدار محدد.

حدّث عن قصد

agentplugins update context7 --target codex,cursor --dry-run

راجع المصدر والإصدار والوجهات المختارة. احذف --dry-run للتطبيق:

agentplugins update context7 --target codex,cursor

يشمل update --all جميع التحديثات المتاحة للتثبيتات المُدارة. استخدمه عندما تكون المجموعة بأكملها هي النطاق المقصود. يبقى مصدر الالتزام الدقيق غير قابل للتغيير؛ ولا يجعله التحديث يتابع فرعًا. لا تتقدم نطاقات الاعتماديات المحفوظة والمراجع المتحركة إلا عبر عملية التحديث الصريحة المناسبة.

أصلح الحالة المسجلة

agentplugins repair context7 --target codex,cursor --dry-run
agentplugins repair context7 --target codex,cursor

يعاين الأمر الأول الخطة ويطبّقها الثاني. يعيد الإصلاح استخدام المصدر المسجل لاستعادة المحتوى المملوك. ولا يختار مراجعة بعيدة جديدة أو يستبدل بصمت إدخالات أصلية تغيّرت خارجيًا. راجع التعارضات وأي تعليمات استرداد معلّقة قبل المتابعة.

أزل التثبيت المختار

agentplugins remove context7 --target codex,cursor --dry-run
agentplugins remove context7 --target codex,cursor

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

استخدم بيئة اعتماديات محفوظة

يسجل uap.toml الحزم والأهداف التي تريدها، ويسجل uap.lock مصادرها الدقيقة المحسومة وبصماتها. افحص البيئة المختارة باستخدام:

agentplugins deps status
agentplugins deps tree

لبيئة جديدة، استخدم agentplugins deps init، وعدّل ملف البيان بعناية، ثم شغّل agentplugins deps lock لحسم الاعتماديات وagentplugins install --locked --scope user لتطبيق القفل. راجع طلبات التأكيد واستخدم --dry-run للمعاينة. يشرح دليل الاعتماديات صيغة البيان واعتماديات الحزم الإلزامية ونطاقات الإصدارات وقواعد التحديث.

تحفظ عمليات add البعيدة المؤهلة تعريف الاعتماديات القابلة للنقل افتراضيًا في CLI 0.1.93. أما المسارات المحلية الصريحة ومصادر الاكتشاف والتجهيز الخاص بـ ChatGPT فقط و--no-save فتستخدم مسار التنفيذ المباشر. لا تفترض أن تثبيتًا مباشرًا أقدم مشمول بالاتفاق؛ افحص deps status والملفات الفعلية قبل نقلها.

استعد على آلة أخرى

انقل بيئة مستخدم محفوظة عبر مجلد تبادل. من ذلك المجلد على الآلة المصدر:

agentplugins deps export

انسخ المجلد إلى الوجهة، وثبّت العملاء المستهدفين، ثم شغّل هناك:

agentplugins deps import
agentplugins install --locked --scope user

أو اجمع الاستيراد والاستعادة:

agentplugins deps import --install

تختار وسيطة المجلد الاختيارية مجلد تبادل آخر. تقرأ عملية التصدير بيئة المستخدم وتكتب عملية الاستيراد إليها؛ ويمكن استخدام AGENTPLUGINS_HOME لاختيار بيئة بعينها. ليس المجلد المنقول بحد ذاته بديلًا لملف تعريف العميل. يُبقي --scope user الصريح الاستعادة ضمن بيئة المستخدم.

لا يُنقل سوى uap.toml وuap.lock دون تغيير وبعد التحقق الصارم منهما. تعرض عملية النسخ الفعلية معاينة وتتطلب تأكيدًا أو --yes؛ ويعرض --dry-run المعاينة فقط. يعمل التحقق عند الاستيراد بلا اتصال، أما التثبيت فيحتاج إلى المصادر المسجلة أو الحزم المخزنة مؤقتًا التي جرى التحقق منها. تجلب الاستعادة دون ذاكرة مؤقتة المراجع المثبتة الدقيقة وتفحص بصماتها، ولا تختار إصدارات أحدث.

لا يشمل النقل ملفات تعريف العملاء أو الإعدادات أو بيانات الاعتماد أو الإيصالات أو PLUGIN_DATA. اضبط المصادقة على الآلة الجديدة وانسخ البيانات احتياطيًا بشكل منفصل. إذا فشل التثبيت بعد حفظ الملفين أثناء الاستيراد، فأصلح السبب المبلّغ عنه وأعد install --locked --scope user. شغّل deps recover --scope user أولًا إذا أُبلغ عن استرداد معلّق. لا تُعد إنشاء المراجع المنقولة باستخدام deps lock، لأن المحدد المتحرك قد يُحسم إلى نتيجة مختلفة.

استعد مشروعًا وحافظ عليه

يتوفر التثبيت التلقائي للمشروع في CLI 0.1.94 وأحدث. أضف uap.toml وuap.lock الخاصين بالمشروع إلى نظام التحكم بالإصدارات. في نسخة عمل أخرى موجودة، ثبّت العملاء المطلوبين وشغّل الأمر من مجلد المشروع نفسه:

agentplugins install

يخضع القفل الموجود لتحقق صارم. ويشترط --locked وجوده أيضًا، مما يفيد في CI؛ أما دون قفل فيمكن للتثبيت الأول إنشاء واحد. عند تنفيذ الأمر من مجلد آخر، اختر المشروع الموجود صراحةً:

agentplugins install --locked --scope project --project-root /path/to/project

اختر النطاق والجذر نفسيهما للصيانة:

agentplugins list --scope project --project-root /path/to/project
agentplugins deps status --scope project --project-root /path/to/project
agentplugins repair review --target cursor --scope project --project-root /path/to/project
agentplugins deps recover --scope project --project-root /path/to/project

استخدم هوية التثبيت من list إذا كان الاسم ملتبسًا. تستخدم أوامر الصيانة نطاق المستخدم افتراضيًا، لذا اختر نطاق المشروع صراحةً. يتبع install دون وسيطة مصدر قاعدة اختيار 0.1.94 الموضحة أدناه. ويستخدم --scope project الصريح من دون --project-root مجلد تنفيذ الأمر فقط.

أبقِ إيصالات .uap/ وسجلات الاسترداد والبيانات المحتفظ بها محلية. استعد المكونات الأصلية من الاتفاق القابل للنقل واتبع تعليمات الثقة أو التفعيل الخاصة بالعميل. يجب أن تظل المصادر وإمكانية الوصول إلى المصادر الخاصة متاحة. راجع تثبيت المشاريع وحدود كل عميل.

الاختيار الافتراضي للتثبيت في CLI 0.1.94

تحقّق أولًا من agentplugins version. يتطلب هذا السلوك 0.1.94؛ وإذا كانت قناة مدير الحزم أقدم، فاستخدم المثبّت الأصلي أو Homebrew. تبقى أوامر نطاق المشروع الصريح أعلاه متوافقة مع 0.1.93.

متاح في CLI 0.1.94: يختار agentplugins install دون وسيطة مصدر أو نطاق صريح نطاق المشروع إذا وُجد ملف عادي باسم uap.toml في المجلد الحالي نفسه. ولا يبحث في المجلدات الأب. يُرفض أثناء الاختيار التلقائي مجلد أو رابط رمزي بهذا الاسم؛ حدّد النطاق صراحةً لإزالة الالتباس. دون ذلك البيان المحلي، يختار التثبيت بيئة المستخدم. تكون الأولوية دائمًا لـ --scope user أو --scope project الصريح. وتستمر الأوامر الأخرى في استخدام نطاق المستخدم افتراضيًا.

يُتحقق من uap.lock الموجود بصرامة قبل التغييرات، حتى دون --locked. يوقف عدم التطابق العملية؛ استخدم update لتقديم المراجع المثبتة، ولا تتوقع أن يحدّثها install. لا يُسمح بحسم اعتماديات التثبيت الأول وإنشاء قفل إلا عند غياب القفل. ويشترط --locked وجود قفل مسبق أيضًا. تبقى أمثلة النطاق الصريح و--locked أعلاه مناسبة للأتمتة المتوقعة واستعادة المشاريع.

أبلغ عن المشكلة بوضوح

سجّل إصدار CLI والعملية والنطاق ومصدر الحزمة والعملاء المستهدفين وتعليمات التفعيل المتبقية. بيّن هل وقع الفشل أثناء جلب المصدر، أم التخطيط، أم تطبيق الملفات، أم الاسترداد، أم اكتشاف العميل، أم المصادقة، أم الاستخدام وقت التشغيل. أزل بيانات الاعتماد قبل مشاركة التشخيص. يفحص doctor ./my-plugin الخاص بالتأليف حزمة مصدر؛ أما doctor الخاص بالمثبّت فيشخّص حالة التثبيت المُدارة.