Integracja WSL (podsystem Windows dla systemu Linux).

WSL umożliwia uruchomienie pełnego środowiska Linux bezpośrednio w systemie Windows. Po skonfigurowaniu integracja powłoki STT działa identycznie z przewodnikami Linux Bash lub Zsh — nie jest wymagana żadna adaptacja specyficzna dla systemu Windows dla samej funkcji powłoki.

Zalecane dla: użytkowników systemu Windows, którzy znają terminal Linux lub którzy mają już zainstalowaną wersję WSL do prac programistycznych. WSL zapewnia najwierniejsze wrażenia i najmniejszą liczbę kompromisów w zakresie kompatybilności.

Warunki wstępne

Zainstaluj WSL (jednorazowa konfiguracja)

Otwórz PowerShell lub CMD jako administrator i uruchom:

KOD_BLOKU_0

To domyślnie instaluje WSL2 z Ubuntu. Po wyświetleniu monitu uruchom ponownie maszynę.

Aby zainstalować konkretną dystrybucję:

KOD_BLOKU_1

Lista wszystkich dostępnych dystrybucji:

KOD_BLOKU_2

Sprawdź wersję WSL

KOD_BLOKU_3

Upewnij się, że kolumna „WERSJA” pokazuje „2”. Jeśli pokazuje „1”, uaktualnij za pomocą:

KOD_BLOKU_4

Integracja powłoki w WSL

Po uruchomieniu WSL otwórz terminal Linux i postępuj zgodnie z przewodnikiem po powłoce Linuksa dla preferowanej powłoki:

Powłoka

Przewodnik

Bash (domyślnie WSL)

bash-integration.md

Zsz

zsh-integration.md

Ryba

fish-integration.md

Ksz

ksh-integration.md

POSIX sh / Dash

posix-sh-integration.md

W przypadku domyślnej konfiguracji WSL Ubuntu/Debian z Bash szybka ścieżka to:

KOD_BLOKU_5

Uwagi specyficzne dla WSL

Dostęp do plików Windows z WSL

Twoje dyski Windows są zamontowane w /mnt/:

KOD_BLOKU_6

Jeśli Twój projekt znajduje się w systemie plików Windows (np. C:\Projects\stt), ustaw SL5NET_AURA_PROJECT_ROOT na:

KOD_BLOKU_7

Dodaj tę linię do swojego ~/.bashrc (lub odpowiednika twojej powłoki) nad funkcją s().

Wskazówka dotycząca wydajności: Aby uzyskać najlepszą wydajność we/wy, przechowuj pliki projektu w systemie plików WSL (np. ~/projects/stt), a nie w /mnt/c/.... Dostęp między systemami plików pomiędzy WSL i Windows jest znacznie wolniejszy.

Wirtualne środowisko Pythona w WSL

Utwórz i używaj standardowego środowiska wirtualnego Linux w WSL:

KOD_BLOKU_8

Ścieżka PY_EXEC w funkcji ($SL5NET_AURA_PROJECT_ROOT/.venv/bin/python3) będzie działać poprawnie bez zmian.

Uruchamianie „s” z terminala Windows

Windows Terminal to zalecany sposób korzystania z WSL w systemie Windows. Obsługuje wiele kart, paneli i profili dla każdej dystrybucji WSL. Zainstaluj go ze sklepu Microsoft Store lub poprzez:

KOD_BLOKU_9

Ustaw swoją dystrybucję WSL jako profil domyślny w ustawieniach terminala Windows, aby uzyskać najbardziej płynne działanie.

Docker na żądanie (Linux)

Aby zaoszczędzić zasoby systemowe, możesz skonfigurować Dockera tak, aby uruchamiał się tylko wtedy, gdy jest to wymagane (np. gdy Aura żąda bazy danych Trino), zamiast stale działać w tle.

Uruchom następujące polecenia, aby wyłączyć ciągłą usługę w tle i zamiast tego włączyć „aktywację gniazda”:

KOD_BLOKU_10

Zapewnij bezpieczeństwo aktualizacji (użytkownicy Linux Arch/Manjaro): Aktualizacje pakietów mogą czasami zresetować konfigurację gniazda. Aby temu zapobiec, utwórz trwałe lokalne zastąpienie:

KOD_BLOKU_11 Upewnij się, że następujące linie są obecne i nie są skomentowane (usuń #), a następnie zapisz i wyjdź: KOD_BLOKU_12

Docker i Kiwix w WSL

Skrypt pomocniczy Kiwix („kiwix-docker-start-if-not-running.sh”) wymaga Dockera. Zainstaluj Docker Desktop dla Windows i włącz integrację WSL 2:

  1. Pobierz i zainstaluj Docker Desktop.

  2. W Docker Desktop → Ustawienia → Zasoby → Integracja WSL włącz dystrybucję WSL.

  3. Sprawdź w WSL: KOD_BLOKU_13

Wywołanie funkcji WSL s z Windows (opcjonalnie)

Jeśli chcesz wywołać skrót s z okna CMD systemu Windows lub PowerShell bez otwierania terminala WSL, możesz go owinąć:

KOD_BLOKU_14

KOD_BLOKU_15

Flaga -i ładuje interaktywną powłokę, dzięki czemu ~/.bashrc (i funkcja s) są pobierane automatycznie.

Cechy

  • Pełna kompatybilność z Linuksem: Wszystkie narzędzia uniksowe (timeout, pgrep, mktemp, grep) działają natywnie — nie są potrzebne żadne obejścia.

  • Ścieżki dynamiczne: Automatycznie znajduje katalog główny projektu poprzez zmienną SL5NET_AURA_PROJECT_ROOT ustawioną w konfiguracji powłoki.

  • Auto-Restart: Jeśli backend nie działa, próbuje uruchomić start_service i lokalne usługi Wikipedii (musi być uruchomiony Docker).

  • Inteligentne limity czasu: Najpierw próbuje uzyskać szybką reakcję w ciągu 2 sekund, a następnie powraca do trybu głębokiego przetwarzania trwającego 70 sekund.