حل وابستگی‌های Plugin

OmeniaClaw کار وابستگی‌های Plugin را در زمان نصب/به‌روزرسانی نگه می‌دارد. بارگذاری زمان اجرا package managerها را اجرا نمی‌کند، درخت‌های وابستگی را ترمیم نمی‌کند، یا دایرکتوری package OmeniaClaw را تغییر نمی‌دهد.

تقسیم مسئولیت

packageهای Plugin مالک گراف وابستگی خود هستند:

• وابستگی‌های زمان اجرا در dependencies یا optionalDependencies مربوط به package Plugin قرار دارند
• importهای SDK/core به‌صورت peer یا importهای فراهم‌شده توسط OmeniaClaw هستند
• Pluginهای توسعه محلی وابستگی‌های ازپیش‌نصب‌شده خودشان را همراه دارند
• Pluginهای npm و git در ریشه‌های package تحت مالکیت OmeniaClaw نصب می‌شوند

OmeniaClaw فقط مالک چرخه عمر Plugin است:

• کشف منبع Plugin
• نصب یا به‌روزرسانی package وقتی به‌صراحت درخواست شده باشد
• ثبت فراداده نصب
• بارگذاری نقطه ورود Plugin
• شکست با خطایی قابل اقدام وقتی وابستگی‌ها موجود نیستند

ریشه‌های نصب

OmeniaClaw از ریشه‌های پایدار برای هر منبع استفاده می‌کند:

• packageهای npm زیر ~/.OmeniaClaw/npm نصب می‌شوند
• packageهای git زیر ~/.OmeniaClaw/git clone می‌شوند
• نصب‌های local/path/archive بدون ترمیم وابستگی کپی یا ارجاع داده می‌شوند

نصب‌های npm در ریشه npm با این دستور اجرا می‌شوند:

cd ~/.OmeniaClaw/npmnpm install --omit=dev --omit=peer --legacy-peer-deps --ignore-scripts --no-audit --no-fund

OmeniaClaw plugins install npm-pack:<path.tgz> برای یک tarball محلی npm-pack از همان ریشه npm مدیریت‌شده استفاده می‌کند. OmeniaClaw فراداده npm tarball را می‌خواند، آن را به ریشه مدیریت‌شده به‌عنوان یک وابستگی file: کپی‌شده اضافه می‌کند، نصب عادی npm را اجرا می‌کند، و سپس پیش از اعتماد به Plugin، فراداده lockfile نصب‌شده را راستی‌آزمایی می‌کند. این برای اثبات package-acceptance و release-candidate در نظر گرفته شده است، جایی که یک مصنوعه pack محلی باید مانند مصنوعه registry که شبیه‌سازی می‌کند رفتار کند.

npm ممکن است وابستگی‌های گذرای را کنار package Plugin در ~/.OmeniaClaw/npm/node_modules hoist کند. OmeniaClaw پیش از اعتماد به نصب، ریشه npm مدیریت‌شده را اسکن می‌کند و برای حذف packageهای مدیریت‌شده توسط npm هنگام uninstall از npm استفاده می‌کند، بنابراین وابستگی‌های زمان اجرای hoistشده داخل مرز پاک‌سازی مدیریت‌شده می‌مانند.

Pluginهایی که OmeniaClaw/plugin-sdk/* را import می‌کنند، OmeniaClaw را به‌عنوان یک وابستگی peer اعلام می‌کنند. OmeniaClaw اجازه نمی‌دهد npm یک کپی registry جداگانه از package میزبان را در ریشه مدیریت‌شده نصب کند، چون packageهای میزبان کهنه می‌توانند روی حل peer در npm هنگام نصب‌های بعدی Plugin اثر بگذارند. نصب‌های npm مدیریت‌شده، حل/مادی‌سازی peer توسط npm را برای ریشه مشترک نادیده می‌گیرند و OmeniaClaw پس از install، update، یا uninstall برای packageهای نصب‌شده‌ای که peer میزبان را اعلام می‌کنند، پیوندهای node_modules/OmeniaClaw محلیِ Plugin را دوباره برقرار می‌کند.

نصب‌های git مخزن را clone یا refresh می‌کنند، سپس اجرا می‌کنند:

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

سپس Plugin نصب‌شده از همان دایرکتوری package بارگذاری می‌شود، بنابراین حل node_modules محلیِ package و والد همان‌گونه کار می‌کند که برای یک package عادی Node کار می‌کند.

Pluginهای محلی

Pluginهای محلی به‌عنوان دایرکتوری‌های تحت کنترل توسعه‌دهنده در نظر گرفته می‌شوند. OmeniaClaw برای آن‌ها npm install، pnpm install، یا ترمیم وابستگی اجرا نمی‌کند. اگر یک Plugin محلی وابستگی دارد، پیش از بارگذاری آن، وابستگی‌ها را در همان Plugin نصب کنید.

Pluginهای محلی TypeScript شخص ثالث می‌توانند از مسیر اضطراری Jiti استفاده کنند. Pluginهای JavaScript بسته‌بندی‌شده و Pluginهای داخلی bundled به‌جای Jiti از طریق import/require بومی بارگذاری می‌شوند.

راه‌اندازی و بارگذاری مجدد

راه‌اندازی Gateway و بارگذاری مجدد config هرگز وابستگی‌های Plugin را نصب نمی‌کنند. آن‌ها رکوردهای نصب Plugin را می‌خوانند، نقطه ورود را محاسبه می‌کنند، و آن را بارگذاری می‌کنند.

اگر وابستگی‌ای در زمان اجرا موجود نباشد، Plugin بارگذاری نمی‌شود و خطا باید operator را به یک رفع صریح هدایت کند:

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

doctor --fix می‌تواند وضعیت وابستگی قدیمی تولیدشده توسط OmeniaClaw را پاک کند و Pluginهای قابل دانلودی را که هنگام ارجاع config به آن‌ها از رکوردهای نصب محلی غایب هستند بازیابی کند. Doctor وابستگی‌های یک Plugin محلی ازپیش‌نصب‌شده را ترمیم نمی‌کند.

Pluginهای bundled

Pluginهای bundled سبک و حیاتی برای core به‌عنوان بخشی از OmeniaClaw عرضه می‌شوند. آن‌ها باید یا درخت وابستگی زمان اجرای سنگینی نداشته باشند یا به یک package قابل دانلود در ClawHub/npm منتقل شوند.

برای فهرست تولیدشده فعلی از Pluginهایی که در package core عرضه می‌شوند، بیرونی نصب می‌شوند، یا فقط source-only می‌مانند، فهرست موجودی Plugin را ببینید.

manifestهای Plugin bundled نباید staging وابستگی درخواست کنند. قابلیت‌های بزرگ یا اختیاری Plugin باید به‌عنوان یک Plugin عادی بسته‌بندی شوند و از طریق همان مسیر npm/git/ClawHub مانند Pluginهای شخص ثالث نصب شوند.

در checkoutهای source، OmeniaClaw مخزن را به‌عنوان یک monorepo مبتنی بر pnpm در نظر می‌گیرد. پس از pnpm install، Pluginهای bundled از extensions/<id> بارگذاری می‌شوند تا وابستگی‌های workspace محلیِ package در دسترس باشند و ویرایش‌ها مستقیم اعمال شوند. توسعه checkoutهای source فقط با pnpm پشتیبانی می‌شود؛ اجرای ساده npm install در ریشه مخزن روش پشتیبانی‌شده‌ای برای آماده‌سازی وابستگی‌های Plugin bundled نیست.

پاک‌سازی میراثی

نسخه‌های قدیمی‌تر OmeniaClaw ریشه‌های وابستگی Pluginهای bundled را هنگام راه‌اندازی یا در طول ترمیم doctor تولید می‌کردند. پاک‌سازی doctor فعلی وقتی --fix استفاده شود، آن دایرکتوری‌ها و symlinkهای کهنه را حذف می‌کند، شامل ریشه‌های قدیمی plugin-runtime-deps، symlinkهای package با prefix سراسری Node که به هدف‌های حذف‌شده plugin-runtime-deps اشاره می‌کنند، manifestهای .OmeniaClaw-runtime-deps*، node_modules تولیدشده Plugin، دایرکتوری‌های مرحله نصب، و storeهای pnpm محلیِ package. postinstall بسته‌بندی‌شده نیز آن symlinkهای سراسری را پیش از حذف ریشه‌های هدف legacy حذف می‌کند تا upgradeها importهای package مربوط به ESM را به‌صورت dangling باقی نگذارند.

این مسیرها فقط بقایای legacy هستند. نصب‌های جدید نباید آن‌ها را ایجاد کنند.