Integración WSL (Subsistema de Windows para Linux)¶

WSL le permite ejecutar un entorno Linux completo directamente en Windows. Una vez configurada, la integración del shell STT funciona de manera idéntica a las guías Linux Bash o Zsh: no se necesita ninguna adaptación específica de Windows para la función del shell en sí.

Recomendado para: Usuarios de Windows que se sienten cómodos con una terminal Linux o que ya tienen WSL instalado para el trabajo de desarrollo. WSL proporciona la experiencia más fiel y los menores compromisos de compatibilidad.

Requisitos previos¶

Instalar WSL (configuración única)¶

Abra PowerShell o CMD como administrador y ejecute:

wsl --install

Esto instala WSL2 con Ubuntu de forma predeterminada. Reinicie su máquina cuando se le solicite.

Para instalar una distribución específica:

wsl --install -d Ubuntu-24.04
# or
wsl --install -d Debian

Lista todas las distribuciones disponibles:

wsl --list --online

Verifica tu versión de WSL¶

wsl --list --verbose

Asegúrese de que la columna “VERSIÓN” muestre “2”. Si muestra “1”, actualice con:

wsl --set-version <DistroName> 2

Integración de Shell dentro de WSL¶

Una vez que WSL se esté ejecutando, abra su terminal Linux y siga la guía de shell de Linux para su shell preferido:

Concha	Guía
Bash (valor predeterminado de WSL)	bash-integration.md
Zsh	zsh-integration.md
Pescado	fish-integration.md
ksh	ksh-integration.md
POSIX sh/guión	posix-sh-integration.md

Para la configuración predeterminada de Ubuntu/Debian WSL con Bash, la ruta rápida es:

nano ~/.bashrc
# Paste the function block from bash-integration.md
source ~/.bashrc

Consideraciones específicas de WSL¶

Accediendo a archivos de Windows desde WSL¶

Sus unidades de Windows están montadas en /mnt/:

/mnt/c/   # → C:\
/mnt/d/   # → D:\

Si su proyecto se encuentra en el sistema de archivos de Windows (por ejemplo, C:\Projects\stt), configure SL5NET_AURA_PROJECT_ROOT en:

export SL5NET_AURA_PROJECT_ROOT="/mnt/c/Projects/stt"

Agregue esta línea a su ~/.bashrc (o el equivalente para su shell) arriba de la función s().

Consejo de rendimiento: Para obtener el mejor rendimiento de E/S, mantenga los archivos del proyecto dentro del sistema de archivos WSL (por ejemplo, ~/projects/stt) en lugar de /mnt/c/.... El acceso entre sistemas de archivos entre WSL y Windows es significativamente más lento.

Entorno virtual Python dentro de WSL¶

Cree y utilice un entorno virtual Linux estándar dentro de WSL:

cd "$SL5NET_AURA_PROJECT_ROOT"
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

La ruta PY_EXEC en la función ($SL5NET_AURA_PROJECT_ROOT/.venv/bin/python3`) funcionará correctamente tal como está.

Ejecutando `s` desde la terminal de Windows¶

Windows Terminal es la forma recomendada de utilizar WSL en Windows. Admite múltiples pestañas, paneles y perfiles para cada distribución WSL. Instálelo desde Microsoft Store o mediante:

winget install Microsoft.WindowsTerminal

Configure su distribución WSL como el perfil predeterminado en la configuración de la Terminal de Windows para disfrutar de la experiencia más fluida.

Docker bajo demanda (Linux)¶

Para ahorrar recursos del sistema, puede configurar Docker para que se inicie solo cuando sea necesario (por ejemplo, cuando Aura solicita la base de datos de Trino), en lugar de ejecutarse constantemente en segundo plano.

Ejecute los siguientes comandos para deshabilitar el servicio en segundo plano continuo y habilitar la “activación de socket” en su lugar:

sudo systemctl disable docker.service
sudo systemctl enable docker.socket
sudo systemctl start docker.socket

Haz que sea seguro para actualizaciones (usuarios de Linux Arch/Manjaro): Las actualizaciones de paquetes a veces pueden restablecer la configuración del socket. Para evitar esto, cree una anulación local persistente:

sudo systemctl edit docker.socket

Asegúrese de que las siguientes líneas estén presentes y descomentadas (elimine el #), luego guarde y salga:

[Install]
WantedBy=sockets.target

Docker y Kiwix dentro de WSL¶

El script auxiliar de Kiwix (kiwix-docker-start-if-not-running.sh) requiere Docker. Instale Docker Desktop para Windows y habilite la integración de WSL 2:

Descargue e instale Docker Desktop.
En Docker Desktop → Configuración → Recursos → Integración WSL, habilite su distribución WSL.
Verifique dentro de WSL:
```
docker --version
```

Llamar a la función WSL `s` desde Windows (opcional)¶

Si desea invocar el acceso directo s desde una ventana CMD de Windows o PowerShell sin abrir una terminal WSL, puede ajustarlo:

# PowerShell wrapper
function s { wsl bash -i -c "s $args" }

:: CMD wrapper — save as s.bat on your PATH
@echo off
wsl bash -i -c "s %*"

El indicador -i carga un shell interactivo para que su ~/.bashrc (y la función s) se genere automáticamente.

Características¶

Compatibilidad total con Linux: todas las herramientas de Unix (timeout, pgrep, mktemp, grep) funcionan de forma nativa, no se necesitan soluciones alternativas.
Rutas dinámicas: encuentra automáticamente la raíz del proyecto a través de la variable SL5NET_AURA_PROJECT_ROOT configurada en su configuración de shell.
Reinicio automático: si el backend está inactivo, intenta ejecutar start_service y los servicios locales de Wikipedia (Docker debe estar ejecutándose).
Tiempos de espera inteligentes: primero intenta una respuesta rápida de 2 segundos y luego vuelve a un modo de procesamiento profundo de 70 segundos.