WSL (Linux 用 Windows サブシステム) の統合¶

WSL を使用すると、完全な Linux 環境を Windows 上で直接実行できます。セットアップが完了すると、STT シェル統合は Linux Bash または Zsh ガイドと同様に動作します。シェル関数自体に Windows 固有の調整を行う必要はありません。

推奨対象者: Linux ターミナルに慣れている、または開発作業のために WSL がすでにインストールされている Windows ユーザー。 WSL は、最も忠実なエクスペリエンスと互換性の侵害を最小限に抑えます。

前提条件¶

WSL をインストールする (1 回限りのセットアップ)¶

PowerShell または CMD を 管理者 として開き、以下を実行します。

wsl --install

これにより、デフォルトで WSL2 が Ubuntu とともにインストールされます。プロンプトが表示されたらマシンを再起動します。

特定のディストリビューションをインストールするには:

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

利用可能なすべてのディストリビューションをリストします。

wsl --list --online

WSL バージョンを確認する¶

wsl --list --verbose

「VERSION」列に「2」が表示されていることを確認してください。「1」と表示されている場合は、次のようにアップグレードします。

wsl --set-version <DistroName> 2

WSL 内でのシェルの統合¶

WSL が実行されたら、Linux ターミナルを開き、希望するシェルの Linux シェルガイドに従います。

シェル	ガイド
Bash (WSL のデフォルト)	bash-integration.md
ズシュ	zsh-integration.md
魚	fish-integration.md
キシュ	ksh-integration.md
POSIX sh / ダッシュ	posix-sh-integration.md

Bash を使用したデフォルトの Ubuntu/Debian WSL セットアップのクイックパスは次のとおりです。

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

WSL 固有の考慮事項¶

WSL から Windows ファイルにアクセスする¶

Windows ドライブは /mnt/ の下にマウントされます。

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

プロジェクトが Windows ファイルシステム (例 C:\Projects\stt) 上にある場合は、SL5NET_AURA_PROJECT_ROOT を次のように設定します。

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

この行を ~/.bashrc (またはシェルの同等のもの) の s() 関数の上に追加します。

パフォーマンスのヒント: 最高の I/O パフォーマンスを得るには、プロジェクトファイルを /mnt/c/... ではなく WSL ファイルシステム (例: ~/projects/stt) 内に保持してください。 WSL と Windows 間のファイルシステム間のアクセスは大幅に遅くなります。

WSL 内の Python 仮想環境¶

WSL 内で標準の Linux 仮想環境を作成して使用します。

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

関数内の PY_EXEC パス ($SL5NET_AURA_PROJECT_ROOT/.venv/bin/python3) はそのままで正しく動作します。

Windows ターミナルから `s` を実行する¶

Windows で WSL を使用するには、Windows Terminal が推奨される方法です。各 WSL ディストリビューションの複数のタブ、ペイン、プロファイルをサポートします。 Microsoft Store から、または次の方法でインストールします。

winget install Microsoft.WindowsTerminal

最もシームレスなエクスペリエンスを実現するには、Windows ターミナル設定で WSL ディストリビューションをデフォルトのプロファイルとして設定します。

Docker オンデマンド (Linux)¶

システムリソースを節約するために、Docker をバックグラウンドで常に実行するのではなく、必要なとき (Aura が Trino データベースを要求したときなど) にのみ起動するように設定できます。

次のコマンドを実行して、継続的なバックグラウンドサービスを無効にし、代わりに「ソケットアクティベーション」を有効にします。

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

安全に更新できるようにします (Linux Arch/Manjaro ユーザー): パッケージの更新によりソケット構成がリセットされる場合があります。これを防ぐには、永続的なローカルオーバーライドを作成します。

sudo systemctl edit docker.socket

次の行が存在し、コメントが解除されていることを確認し (「#」を削除)、保存して終了します。

[Install]
WantedBy=sockets.target

WSL 内の Docker と Kiwix¶

Kiwix ヘルパースクリプト (kiwix-docker-start-if-not-running.sh) には Docker が必要です。 Docker Desktop for Windows をインストールし、WSL 2 統合を有効にします。

1.Docker Desktopをダウンロードしてインストールします。 2. [Docker Desktop] → [設定] → [リソース] → [WSL 統合] で、WSL ディストリビューションを有効にします。 3. WSL 内で確認します。

docker --version

Windows から WSL `s` 関数を呼び出す (オプション)¶

WSL ターミナルを開かずに Windows CMD または PowerShell ウィンドウから「s」ショートカットを呼び出したい場合は、それをラップできます。

# 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 %*"

-i フラグは対話型シェルをロードし、~/.bashrc (および s 関数) が自動的にソースされるようにします。

＃＃特徴

完全な Linux 互換性: すべての Unix ツール (timeout、pgrep、mktemp、grep) はネイティブに動作します。回避策は必要ありません。
動的パス: シェル設定に設定された SL5NET_AURA_PROJECT_ROOT 変数を介してプロジェクトルートを自動的に検索します。
自動再起動: バックエンドがダウンしている場合、「start_service」とローカルの Wikipedia サービスの実行を試みます (Docker が実行されている必要があります)。
スマートタイムアウト: 最初に 2 秒の素早い応答を試み、その後 70 秒の詳細な処理モードに戻ります。