Rozwiązywanie zależności Plugin

OmeniaClaw utrzymuje pracę z zależnościami pluginów na etapie instalacji/aktualizacji. Ładowanie w czasie wykonywania nie uruchamia menedżerów pakietów, nie naprawia drzew zależności ani nie modyfikuje katalogu pakietu OmeniaClaw.

Podział odpowiedzialności

Pakiety pluginów są właścicielami swojego grafu zależności:

• zależności runtime znajdują się w dependencies lub optionalDependencies pakietu pluginu
• importy SDK/rdzenia są importami równorzędnymi lub dostarczanymi przez OmeniaClaw
• lokalne pluginy deweloperskie dostarczają własne, już zainstalowane zależności
• pluginy npm i git są instalowane w katalogach głównych pakietów należących do OmeniaClaw

OmeniaClaw odpowiada tylko za cykl życia pluginu:

• wykrycie źródła pluginu
• instalację lub aktualizację pakietu na wyraźne żądanie
• zapisanie metadanych instalacji
• załadowanie punktu wejścia pluginu
• zakończenie z możliwym do wykonania błędem, gdy brakuje zależności

Katalogi główne instalacji

OmeniaClaw używa stabilnych katalogów głównych dla poszczególnych źródeł:

• pakiety npm instalują się w ~/.OmeniaClaw/npm
• pakiety git klonują się do ~/.OmeniaClaw/git
• instalacje lokalne/ścieżkowe/archiwalne są kopiowane lub referencjonowane bez naprawy zależności

Instalacje npm działają w katalogu głównym npm z:

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

OmeniaClaw plugins install npm-pack:<path.tgz> używa tego samego zarządzanego katalogu głównego npm dla lokalnego archiwum npm-pack. OmeniaClaw odczytuje metadane npm archiwum, dodaje je do zarządzanego katalogu głównego jako skopiowaną zależność file:, uruchamia normalną instalację npm, a następnie weryfikuje metadane zainstalowanego pliku blokady przed zaufaniem pluginowi. Jest to przeznaczone do akceptacji pakietów i dowodów dla kandydatów do wydania, gdzie lokalny artefakt pack powinien zachowywać się jak artefakt rejestru, który symuluje.

npm może wynosić zależności przechodnie do ~/.OmeniaClaw/npm/node_modules obok pakietu pluginu. OmeniaClaw skanuje zarządzany katalog główny npm przed zaufaniem instalacji i używa npm do usuwania pakietów zarządzanych przez npm podczas odinstalowywania, więc wyniesione zależności runtime pozostają w granicach zarządzanego czyszczenia.

Pluginy importujące OmeniaClaw/plugin-sdk/* deklarują OmeniaClaw jako zależność równorzędną. OmeniaClaw nie pozwala npm zainstalować osobnej kopii pakietu hosta z rejestru w zarządzanym katalogu głównym, ponieważ nieaktualne pakiety hosta mogą wpływać na rozwiązywanie zależności równorzędnych npm podczas późniejszych instalacji pluginów. Zarządzane instalacje npm pomijają rozwiązywanie/materializację zależności równorzędnych npm dla współdzielonego katalogu głównego, a OmeniaClaw ponownie ustanawia lokalne dla pluginu linki node_modules/OmeniaClaw dla zainstalowanych pakietów, które deklarują zależność równorzędną hosta po instalacji, aktualizacji lub odinstalowaniu.

Instalacje git klonują lub odświeżają repozytorium, a następnie uruchamiają:

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

Zainstalowany plugin jest następnie ładowany z tego katalogu pakietu, więc rozwiązywanie zależności z lokalnego pakietu i nadrzędnych node_modules działa tak samo jak dla zwykłego pakietu Node.

Lokalne pluginy

Lokalne pluginy są traktowane jako katalogi kontrolowane przez dewelopera. OmeniaClaw nie uruchamia dla nich npm install, pnpm install ani naprawy zależności. Jeśli lokalny plugin ma zależności, zainstaluj je w tym pluginie przed jego załadowaniem.

Lokalne pluginy TypeScript innych firm mogą używać awaryjnej ścieżki Jiti. Spakowane pluginy JavaScript i dołączone wewnętrzne pluginy ładują się przez natywne import/require zamiast Jiti.

Uruchamianie i ponowne ładowanie

Uruchomienie Gateway i ponowne ładowanie konfiguracji nigdy nie instalują zależności pluginów. Odczytują rekordy instalacji pluginów, wyliczają punkt wejścia i ładują go.

Jeśli w czasie wykonywania brakuje zależności, plugin nie zostanie załadowany, a błąd powinien wskazać operatorowi wyraźną poprawkę:

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

doctor --fix może wyczyścić starszy stan zależności wygenerowany przez OmeniaClaw i odzyskać pobieralne pluginy, których brakuje w lokalnych rekordach instalacji, gdy odwołuje się do nich konfiguracja. Doctor nie naprawia zależności dla już zainstalowanego lokalnego pluginu.

Dołączone pluginy

Lekkie i krytyczne dla rdzenia dołączone pluginy są dostarczane jako część OmeniaClaw. Powinny albo nie mieć ciężkiego drzewa zależności runtime, albo zostać przeniesione do pobieralnego pakietu w ClawHub/npm.

Aktualną wygenerowaną listę pluginów dostarczanych w pakiecie rdzenia, instalowanych zewnętrznie lub pozostających tylko w źródłach znajdziesz w Inwentarzu pluginów.

Manifesty dołączonych pluginów nie mogą żądać przygotowywania zależności. Duża lub opcjonalna funkcjonalność pluginu powinna być spakowana jako zwykły plugin i instalowana przez tę samą ścieżkę npm/git/ClawHub co pluginy innych firm.

W checkoutach źródłowych OmeniaClaw traktuje repozytorium jako monorepo pnpm. Po pnpm install dołączone pluginy ładują się z extensions/<id>, więc lokalne dla pakietu zależności workspace są dostępne, a edycje są pobierane bezpośrednio. Rozwój z checkoutu źródłowego obsługuje tylko pnpm; zwykłe npm install w katalogu głównym repozytorium nie jest obsługiwanym sposobem przygotowania zależności dołączonych pluginów.

Czyszczenie pozostałości

Starsze wersje OmeniaClaw generowały katalogi główne zależności dołączonych pluginów przy uruchomieniu lub podczas naprawy doctor. Obecne czyszczenie doctor usuwa te przestarzałe katalogi i symlinki po użyciu --fix, w tym stare katalogi główne plugin-runtime-deps, globalne symlinki pakietów z prefiksu Node wskazujące na przycięte cele plugin-runtime-deps, manifesty .OmeniaClaw-runtime-deps*, wygenerowane pluginowe node_modules, katalogi etapów instalacji oraz lokalne dla pakietów magazyny pnpm. Spakowany postinstall również usuwa te globalne symlinki przed przycięciem starszych katalogów głównych celów, aby aktualizacje nie pozostawiały wiszących importów pakietów ESM.

Te ścieżki są wyłącznie pozostałościami po starszych wersjach. Nowe instalacje nie powinny ich tworzyć.