Tworzenie wtyczek

Wtyczka rozszerza Speedwave o skonteneryzowanego workera MCP wywoływanego przez Claude lub o zestaw zasobów promptów (skille, komendy, subagenci i hooki). Wtyczki są przygotowywane, weryfikowane i dystrybuowane wyłącznie przez Speednet. Jeśli twoja wtyczka zawiera workera MCP, kontrakt uruchomieniowy oraz konwencje narzędzi opisano w przewodniku Tworzenie serwera MCP.

Struktura i cykl życia wtyczki

Tworzenie wtyczki polega na przygotowaniu plików źródłowych, a nie gotowej paczki instalacyjnej. Tworzysz manifest plugin.json, a w przypadku wtyczek MCP również kod workera i definicję kontenera. Speednet weryfikuje źródła i generuje podpisane archiwum ZIP, z którego Speedwave lokalnie buduje obrazy kontenerów na podstawie potwierdzonej zawartości.

Manifest plugin.json z zadeklarowanym polem service_id, plik Containerfile oraz kod źródłowy workera. Może również zawierać katalog claude-resources.

Manifest plugin.json bez deklaracji service_id lub Containerfile, uzupełniony o katalog claude-resources (skille, komendy, subagenci i hooki). Nie wymaga kontenera workera.

Manifest wymaga podania pól name, slug, version oraz description. Identyfikator slug służy jako główny identyfikator dla katalogów instalacyjnych, kluczy konfiguracji, nazw usług Docker Compose, zmiennych środowiskowych workera i ścieżek do tokenów. Musi pasować do wzorca ^[a-z][a-z0-9-]{0,63}$ i nie może kolidować z wbudowanymi usługami (slack, github, office), generowanymi nazwami compose (mcp-<slug>) ani słowami zastrzeżonymi (np. claude). W przypadku wtyczek usług MCP pole service_id musi być identyczne ze slug.

Pola opcjonalne obejmują definicje poświadczeń (auth_fields), schemat ustawień (settings_schema), instrukcje konfiguracji (instructions), konfigurację OAuth (oauth), połączenie z aplikacją desktopową (host_bridge) oraz ograniczenia zasobów (mem_limit, cpu_limit). Szczegółowe wymagania walidacji wszystkich pól opisano w rozdziale Mechanizm wtyczek i weryfikacja podpisów.

Model wykonawczy w środowisku uruchomieniowym

W przypadku wtyczek MCP plik Containerfile definiuje workera, który dziedziczy zabezpieczenia kontenerów Speedwave: odebrane uprawnienia jądra (Linux capabilities), blokadę eskalacji uprawnień, główny system plików w trybie tylko do odczytu oraz tmpfs w /tmp z flagą noexec. Ograniczenia te nie podlegają modyfikacji, co wymusza uruchamianie workera w trybie nieuprzywilejowanym bez możliwości zapisu w głównym systemie plików, w ramach maksymalnych limitów zasobów 16 GiB pamięci RAM oraz 4 rdzeni CPU. Speedwave automatycznie wstrzykuje zastrzeżoną zmienną SPEEDWAVE_VERSION, której wtyczka nie może modyfikować.

Dwa punkty montowania łączą kontener ze środowiskiem: katalog /tokens zamontowany w trybie tylko do odczytu (skąd worker odczytuje poświadczenia pod ścieżką /tokens/<key>) oraz /workspace zamontowany w trybie do odczytu i zapisu (stanowiący jedyny trwały magazyn stanu workera). Wartości jawne zadeklarowane w settings_schema trafiają do pliku /tokens/_settings.json w trybie tylko do odczytu; pola z danymi poufnymi (sekrety) są wykluczone.

Jeśli wtyczka uwierzytelnia się przez OAuth, należy zadeklarować blok konfiguracyjny oauth. Wewnętrzny worker oauth Speedwave zarządza pobieraniem i odnawianiem tokenów, dzięki czemu długoterminowe poświadczenia pozostają na hoście, a do kontenera trafia wyłącznie krótkotrwały token nośnika (bearer token). Speedwave obsługuje trzy typy nadań uprawnień (grant types): authorization_code (wymaga oauth.authorize_url), device_code (wymaga oauth.device_authorization_url) oraz client_credentials (wymaga oauth.client_secret_field). Wszystkie adresy URL punktów końcowych są walidowane przed zaakceptowaniem manifestu.

Przygotowanie i dystrybucja wtyczki

Przygotuj manifest plugin.json, plik Containerfile (w przypadku wtyczek MCP), kod źródłowy workera oraz ewentualne zasoby w katalogu claude-resources.
Przekaż repozytorium źródłowe do Speednetu w celu weryfikacji. Speednet buduje archiwum ZIP, podpisuje je kluczem prywatnym Ed25519 i dołącza plik SIGNATURE.
Zainstaluj podpisaną paczkę w Speedwave, który weryfikuje podpis kryptograficzny za pomocą wbudowanego klucza publicznego Speednet.
Speedwave przeprowadza walidację instalacyjną i buduje obraz kontenera lokalnie ze zweryfikowanych plików.
Włącz wtyczkę w wybranym projekcie i podaj wymagane poświadczenia. Interfejs aplikacji Desktop wyświetla zapisane parametry jawne, zachowując dane poufne jako pola wyłącznie do zapisu.

Przed przekazaniem kodu przetestuj workera lokalnie: zbuduj obraz z pliku Containerfile, zamontuj /tokens w trybie tylko do odczytu oraz /workspace w trybie do odczytu i zapisu, a następnie upewnij się, że worker uruchamia się bez uprawnień roota na systemie plików w trybie tylko do odczytu. Speedwave wymusza dokładnie taką konfigurację w środowisku uruchomieniowym, więc wczesna weryfikacja zapobiega powtarzaniu cykli podpisywania.

Granice bezpieczeństwa

Kontener wtyczki ma dostęp wyłącznie do własnego katalogu /workspace oraz może odczytywać swój katalog /tokens. Nie może modyfikować poświadczeń, eskalować uprawnień systemowych ani uzyskiwać dostępu do katalogów tokenów należących do innych wtyczek. Podpisy cyfrowe są ponownie weryfikowane przy każdym generowaniu konfiguracji compose, budowaniu obrazu oraz wyświetlaniu wtyczek w aplikacji Desktop, co zapobiega załadowaniu zmodyfikowanych pakietów. Żadne właściwości manifestu nie pozwalają na wyłączenie tych granic bezpieczeństwa.

Wyczerpujące informacje o weryfikacji podpisów, schematach i architekturze przechowywania znajdziesz w rozdziale Mechanizm wtyczek i weryfikacja podpisów.