Instalacja i zarządzanie wtyczkami

Co to robi

Wtyczka trafia do ciebie jako podpisany pakiet ZIP, a każdą wtyczkę pisze, rozwija i dostarcza wyłącznie Speednet. Instalujesz ją raz dla swojego konta użytkownika, a potem osobno włączasz w każdym projekcie z poziomu aplikacji Desktop albo CLI. Zanim zaczniesz, zajrzyj do katalogu wtyczek i zobacz, co masz do dyspozycji.

Z czego się składa

Podczas instalacji podpisany pakiet zostaje rozpakowany do ~/.speedwave/plugins/<slug>/. Jeśli wtyczka jest usługą MCP, Speedwave buduje z pakietu również jej obraz kontenera. Wtyczka zawierająca same zasoby nie ma obrazu do zbudowania, więc ten krok zostaje w całości pominięty. Speedwave prowadzi też osobny folder ze stanem w ~/.speedwave/plugin-state/<slug>/ i zostawia w nim znacznik, gdy budowa obrazu się nie powiedzie.

Jak to działa

Uruchom polecenie instalacji ze ścieżką do pakietu:

Terminal

speedwave plugin install ./my-plugin.zip

1. Speedwave weryfikuje podpis Ed25519 pakietu i sprawdza jego manifest. To ten sam mechanizm, który opisuje strona Autentyczność plików binarnych: przez ten krok przejdzie tylko pakiet podpisany właściwym kluczem.
2. Rozpakowuje wtyczkę do ~/.speedwave/plugins/<slug>/.
3. Jeśli wtyczka jest usługą MCP, Speedwave buduje jej obraz kontenera. Wtyczka zawierająca same zasoby nie ma obrazu do zbudowania, więc ten krok zostaje pominięty.
4. Speedwave rejestruje wtyczkę.

Zanim to wszystko ruszy, nakładka instalacyjna w aplikacji Desktop podgląda ZIP, żeby pokazać nazwę wtyczki i to, czy deklaruje ona usługę MCP (sygnał, że potrzebna będzie budowa kontenera). Nie weryfikuje przy tym podpisu ani nie rozpakowuje pakietu do docelowej lokalizacji. Właściwa instalacja i tak weryfikuje podpis od nowa.

Polecenie sygnalizuje te fazy jako verifying, extracting i building, a w obu przypadkach kończy się kodem 0:

• Zainstalowano: wtyczka jest na dysku, a w przypadku wtyczki MCP udało się też zbudować jej obraz. Speedwave wypisuje Plugin '<name>' (<slug>) installed successfully.
• Zainstalowano z odłożoną budową: budowa obrazu się nie powiodła, na przykład przez przerwę w sieci albo błędny Containerfile. Speedwave wypisuje wtedy na stderr Plugin '<name>' (<slug>) installed; image build failed and will retry on next launch.

Odłożona budowa też kończy się kodem 0

Te dwa wyniki odróżnisz po komunikacie na stderr powyżej albo po pliku znacznikowym ~/.speedwave/plugin-state/<slug>/image_pending. Speedwave sam ponawia budowę przy następnym uruchomieniu, więc nie musisz nic robić, dopóki budowa nie zawodzi raz za razem.

Włącz wtyczkę dla projektu poleceniem:

Terminal

speedwave plugin enable <service_id> --project my-project

Włączyć da się tylko zweryfikowaną wtyczkę. Jeśli jej pliki przestały odpowiadać temu, co zostało podpisane, operacja się nie powiedzie. Naprawisz to, instalując podpisany pakiet ponownie.

Skonfiguruj to

Desktop

1. Otwórz Plugins w bocznym pasku nawigacji po lewej.
2. Kliknij $ install plugin i wskaż podpisany pakiet .zip.
3. Gdy wtyczka pojawi się na liście jako podpisana (✓ ed25519), przestaw jej przełącznik na włączony dla danego projektu.

Installed plugins $ install plugin my my-project

plugintypesignedon

figmamcp✓ ed25519

glpimcp✓ ed25519

CLI

1. Zainstaluj pakiet: speedwave plugin install ./my-plugin.zip.
2. Włącz go w projekcie: speedwave plugin enable <service_id> --project my-project.
3. W dowolnej chwili sprawdź, co masz zainstalowane, poleceniem speedwave plugin list. Pokazuje ono nazwę i wersję każdego wpisu wraz ze znacznikiem [verified] albo [UNVERIFIED: <reason>]. list pomija sprawdzanie podpisu przy starcie, dzięki czemu działa nawet wtedy, gdy to sprawdzanie akurat zawodzi dla innej wtyczki.
4. Usuń wtyczkę poleceniem speedwave plugin remove my-plugin. Kasuje ono ~/.speedwave/plugins/<slug>/ oraz towarzyszący mu folder stanu ~/.speedwave/plugin-state/<slug>/. Nie usuwa za to danych uwierzytelniających projektu, które podałeś dla tej wtyczki, ani jej wpisów w konfiguracji. Te uprzątniesz z poziomu aplikacji Desktop albo usuwając foldery z tokenami samodzielnie.

Zakładka Changelog

Jeśli pakiet zweryfikowanej wtyczki zawiera plik CHANGELOG.md, jej szczegóły w Desktop pokazują obok pozostałych zakładkę Changelog, dzięki czemu sprawdzisz, co się zmieniło, zanim zaktualizujesz wtyczkę. Changelog jest objęty tym samym podpisem co reszta pakietu, a zakładka pojawia się dopiero po zweryfikowaniu wtyczki: niezweryfikowana wtyczka nie pokaże changeloga, nawet jeśli pakiet go zawiera.

Granice bezpieczeństwa

Przed uruchomieniem większości poleceń CLI Speedwave sprawdza podpis każdej zainstalowanej wtyczki. Jeśli pakiet przestał odpowiadać temu, co zostało podpisane, polecenie kończy się kodem 2 tak długo, aż zainstalujesz wtyczkę ponownie albo ją usuniesz.

Z tego sprawdzania przy starcie zwolnione są plugin install, plugin list i plugin remove, bo to właśnie po nie sięgasz, żeby naprawić wtyczkę, która sprawdzania nie przechodzi. remove zadziała nawet na wtyczce, która nie przechodzi weryfikacji podpisu, i dlatego to nim odzyskasz kontrolę po naruszonej instalacji.