Współtworzenie Speedwave
Rdzeń Speedwave ma otwarty kod źródłowy. Jeśli chcesz naprawić błąd, dodać nową platformę albo poprawić dokumentację, zacznij od konfiguracji środowiska, żeby uruchomić Rust, Node.js i narzędzia platformowe, a przed otwarciem pull requesta sprawdź testowanie.
Makefile to punkt wejścia do wszystkiego: make setup-dev instaluje zależności, make dev uruchamia aplikację desktopową w trybie hot-reload, a make check-all odpala pełną bramkę jakości (check, czyli lint, clippy, sprawdzanie typów i formatowanie, a do tego testy, pokrycie kodu i audyt zależności). Nie wywołuj cargo ani npm bezpośrednio. Makefile utrzymuje spójne katalogi robocze i flagi między crate’ami Rusta, frontendem w Angularze i serwerami MCP.
Zasady inżynierskie
Dział zatytułowany „Zasady inżynierskie”Skrócona wersja reguł, które kształtują ten kod:
- KISS. Speedwave to cienka warstwa orkiestracji nad Limą, nerdctl i containerd, a nie reimplementacja tych narzędzi. Wywołaj właściwe istniejące narzędzie, zamiast budować własne.
- YAGNI. Buduj to, czego wymaga plan implementacji.
speedwave logs,statusistopnie są subkomendami CLI, bo Desktop GUI już je obsługuje. - DRY. Zduplikowana logika trafia do
speedwave-runtime(albo domcp-servers/shared/dla kodu MCP). Rejestry z jednym źródłem prawdy, takie jak ciągi znaków modeli Anthropic, edytuje się w tym źródle, a nie w każdym miejscu wywołania. - SOLID. Każdy typ runtime ma jedno zadanie (
ContainerRuntimezarządza tylko kontenerami), platformy dodają nowe implementacje bez ingerencji w kod wywołujący (LimaRuntime,WslRuntime), a kod wywołujący zależy od interfejsuLockedRuntime, a nie od konkretnej platformy. - Reguła trzech. Nie wydzielaj abstrakcji, dopóki dany wzorzec nie pojawi się po raz trzeci.
Logowanie rządzi się własnymi zasadami: cały kod Rusta przechodzi przez fasadę crate’a log, nigdy przez eprintln!/println! do celów diagnostycznych, a każdy sink logów przechodzi przez sanitizer sekretów w log_sanitizer.rs, zanim cokolwiek trafi do pliku, stderr albo webview aplikacji desktopowej.
Także w pracy z gitem obowiązuje jasno wyznaczona granica: nigdy nie omijaj hooka gita, nigdy nie scalaj z --admin ani z osłabioną regułą ochrony brancha i nigdy nie oznaczaj niezaliczonego checka jako oczekiwanego. Każdy commit zawiera testy razem z kodem i obejmuje scenariusze podstawowe, przypadki brzegowe, ścieżki błędów oraz przejścia stanów, tam gdzie mają zastosowanie. Nie wolno pomijać testów: niezaliczony test trzeba naprawić albo usunąć. Trzymaj się zasady skauta: napraw drobne błędy, literówki i martwy kod, na które natrafisz po drodze, a jeśli coś jest zbyt duże na bieżącą zmianę, zgłoś to zamiast zostawiać komentarz TODO.