Napisz wtyczkę

Wtyczka rozszerza Speedwave o workera MCP działającego w kontenerze, którego może wywołać Claude, albo o zestaw umiejętności, poleceń, agentów i hooków. Ta strona wyjaśnia, z czego składa się wtyczka i jak przejść od źródła do pakietu, który Speedwave wczyta. Wtyczki pisze, rozwija i dostarcza wyłącznie Speednet: także wtyczka zbudowana według tego przewodnika trafia do użytkowników dopiero po podpisaniu i wydaniu przez Speednet. Jeśli twoja wtyczka dostarcza workera, jego kontrakt startowy i konwencje narzędzi opisuje przewodnik Napisz serwer MCP.

Wtyczki podpisuje wyłącznie Speednet

Speedwave wczytuje wyłącznie wtyczki podpisane prywatnym kluczem Speednetu. Kod źródłowy piszesz i testujesz sam, a gotowy wynik wysyłasz do Speednetu do przeglądu i podpisu.

Co robi

Napisanie wtyczki polega na przygotowaniu źródła, a nie gotowego pakietu. Piszesz manifest, a dla wtyczki MCP także kod workera i definicję kontenera. Speednet zamienia to źródło w podpisany plik ZIP, a Speedwave buduje z niego obraz lokalnie, na podstawie zweryfikowanej zawartości.

Z czego się składa

Wtyczka usługi MCP

Manifest plugin.json z service_id, Containerfile i kodem źródłowym workera. Może też zawierać katalog claude-resources.

Wtyczka tylko z zasobami

Manifest plugin.json bez service_id i Containerfile, plus claude-resources: umiejętności, polecenia, agenci i hooki. Nie ma tu kontenera workera.

Manifest wymaga pól name, slug, version i description. slug to identyfikator, z którego wynika wszystko inne: katalog instalacji, klucz konfiguracji dla każdego projektu, nazwa usługi w compose, zmienna środowiskowa workera i katalog tokenów. Musi pasować do wzorca ^[a-z][a-z0-9-]{0,63}$ i nie może pokrywać się z wbudowaną usługą, czy to po identyfikatorze (slack, github, office), po wynikającej z niego nazwie usługi w compose (mcp-<slug>), czy w gołej formie (slug claude zostaje odrzucony). Dla wtyczki usługi MCP service_id musi być równe slug.

Opcjonalne pola obejmują dane uwierzytelniające (auth_fields), formularz ustawień (settings_schema), instrukcje konfiguracji (instructions), przepływ OAuth (oauth), link do mostu na pulpicie (host_bridge) oraz limity zasobów (mem_limit, cpu_limit). Limity rozmiaru i reguły walidacji dla każdego z tych pól opisuje Mechanizm wtyczek.

Jak to działa

Dla wtyczki MCP Containerfile buduje workera, który przejmuje zabezpieczenia kontenerów Speedwave: odebrane uprawnienia Linuksa (capabilities), brak możliwości podniesienia uprawnień, główny system plików tylko do odczytu oraz tmpfs w /tmp z opcją noexec. Niczego z tego nie da się zmienić, więc zaprojektuj workera tak, żeby działał bez podniesionych uprawnień i nie zapisywał niczego w głównym systemie plików. Jego zasoby są też ograniczone do 16 GiB pamięci i 4 CPU.

Granicę kontenera przekraczają dwa punkty montowania. /tokens jest zawsze tylko do odczytu: worker czyta stąd dane uwierzytelniające (/tokens/<key>) i nigdy tu nie zapisuje. /workspace jest do odczytu i zapisu, a zarazem to jedyna zapisywalna powierzchnia kontenera, więc trafia tam cały stan, który worker musi zachować.

Jeśli wtyczka uwierzytelnia się przez OAuth, zadeklaruj blok oauth. Autoryzację i odświeżanie tokenów prowadzi wtedy osobny worker oauth Speedwave, dzięki czemu długowieczne sekrety zostają po stronie hosta, a do kontenera dociera jedynie krótkotrwały token dostępu (bearer token). Speedwave obsługuje trzy typy przyznawania dostępu (grant types), każdy powiązany z wymaganym polem manifestu: authorization_code wymaga oauth.authorize_url, device_code wymaga oauth.device_authorization_url, a client_credentials wymaga oauth.client_secret_field. Każdy podany przez ciebie adres URL punktu końcowego Speedwave sprawdza, zanim przyjmie manifest.

Skonfiguruj to

1. Napisz plugin.json, Containerfile (dla wtyczki MCP), kod workera i ewentualne claude-resources.

2. Wyślij źródło do Speednetu do przeglądu i podpisu. Speednet buduje plik ZIP, podpisuje go prywatnym kluczem Ed25519 i dodaje plik SIGNATURE.

3. Zainstaluj podpisany pakiet w Speedwave, który sprawdza podpis względem wbudowanego klucza publicznego Speednetu.

4. Speedwave sprawdza poprawność instalacji, a następnie buduje lokalny obraz ze zweryfikowanego źródła.

5. Włącz wtyczkę dla projektu i uzupełnij dane uwierzytelniające, o które prosi manifest.

Zanim wyślesz źródło dalej, przetestuj je lokalnie: zbuduj Containerfile, zamontuj /tokens tylko do odczytu i /workspace do odczytu i zapisu, po czym sprawdź, czy worker startuje bez podniesionych uprawnień na systemie plików tylko do odczytu. Dokładnie taki układ Speedwave wymusza po instalacji, więc wychwycenie niezgodności już teraz oszczędzi ci kolejnej rundy podpisywania.

Granice bezpieczeństwa

Wtyczka ma dostęp do własnego /workspace i może odczytać własny /tokens. Nie może natomiast zapisywać danych uwierzytelniających, podnosić sobie uprawnień ani sięgać do katalogu tokenów innej wtyczki. Sprawdzenie podpisu nie jest jednorazową bramką przy instalacji: Speedwave weryfikuje go za każdym razem, gdy generuje konfigurację compose, buduje obraz albo wyświetla wtyczkę w Desktop, więc podmieniony pakiet przestaje się wczytywać. Nic w plugin.json nie pozwala samodzielnie podpisać pakietu ani osłabić tych zabezpieczeń.

To, jak od środka działają weryfikacja podpisu, schemat manifestu i przechowywanie danych, opisuje Mechanizm wtyczek.