# 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](/pl/docs/contributing/writing-an-mcp-server/).
**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

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

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](/pl/docs/under-the-hood/plugin-mechanism/).

## 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](/pl/docs/security/isolation/). 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)](/pl/docs/security/credentials/). 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](/pl/docs/under-the-hood/plugin-mechanism/).