更新・修復・アンインストール

ランチャー環境には2つの独立した更新系統が存在します：ランチャー本体とコアプログラムです。どちらが更新されたかを把握しておくことで、「UI の文言は変わったのに機能が変わっていない」といった疑問を解消できます。

2つの更新系統

項目	コアプログラム	ランチャー本体
更新方式	起動時の git pull ＋ uv sync --frozen	自己自動更新（mTLS ＋ 複数ミラー）
更新頻度	master ブランチに追従（高頻度）	バージョン番号が付与された Release
影響範囲	ゲーム自動化機能、WebUI、API	外枠ウィンドウ、起動フロー、プロセス管理
ロールバック	git checkout <コミットハッシュ>	旧バージョンのアーカイブへの差し替え

コアプログラムを更新した際の動作

1. 次回のランチャー起動時に git pull により最新のコードが取得されます。
2. uv sync --frozen が実行され、新しい uv.lock に基づいて依存ライブラリが同期されます。
3. gui.py の ensure_frontend() が frontend/dist を検査し、必要に応じてフロントエンドを再ビルドします（Node.js が必要です）。
4. WebUI をリロードすると最新機能が反映されます。実行中だったインスタンスは安全に再起動されます。

フロントエンドのビルドには Node.js が必要です

Windows 環境ではランチャーがシステム上の Node.js を自動検知し、未検出時は自動ダウンロードして導入します。Linux / macOS 環境では手動で Node.js を導入しておく必要があります。未導入の場合、フロントエンドの再ビルドに失敗する可能性があります。

ランチャー本体を更新した際の動作

• ランチャーの実行バイナリのみが差し替えられ、.venv、config/、log/ はすべてそのまま保持されます。
• 新バージョンで Python のバージョンや基本ツールチェーンに変更があった場合は、.venv の再構築が自動実行されます（設定データには影響しません）。
• コアプログラムのコードが古いリビジョンへ巻き戻ることはありません。

バージョン間の互換性

組み合わせ	動作結果
新ランチャー ＋ 旧コア	通常は問題なく動作。新ランチャーがコアの新 API を要求する場合は更新を促す警告を表示
旧ランチャー ＋ 新コア	新しい内部プロトコル（パスワードレス認証やプロセス回収タグ等）が利用できない可能性あり
両方とも旧バージョン	既存機能は利用可能ですが、最新の修正パッチは適用されません

互換性の確認はリポジトリの CHANGELOG.md およびリリースノートを参照してください。

環境の修復手順

依存関係の破損

症状：起動時に ModuleNotFoundError、ImportError が発生する、または uv sync が失敗する。

# プロジェクトルートで実行
uv sync --frozen

それでも解決しない場合：

# 仮想環境を削除し、ランチャーに再構築させる（依存関係が再ダウンロードされます）
rm -rf .venv          # Windows の場合：rmdir /s /q .venv

.venv を削除しても設定は失われません

.venv は Python 実行環境のみを保持しており、ユーザー設定（config/）やログ（log/）は別の場所にあります。ただし再構築にはインターネット接続が必要で、数分程度の時間がかかります。

Git リポジトリの破損

症状：更新に失敗する、fatal: not a git repository、マージ競合の発生。

git status
git stash            # ローカルの変更がある場合は一時退避
git pull --rebase

ローカルで編集した設定テンプレートやパッチを消失させないよう、安易に git reset --hard を実行しないでください。

ポート競合の解消

ランチャーのデフォルトポートは 22267 です。ランチャー起動時に競合プロセスは自動終了されます。ソースコード版（デフォルト 25548）と同時に稼働させる場合はポートが異なるため競合しませんが、ランチャーを2つ起動した場合は競合します。

キャッシュのクリア

ディレクトリ	内容	削除の可否
cache/	ランタイムキャッシュ、画像データ等	削除可能（自動再生成）
frontend/node_modules	フロントエンドのビルド用依存関係	削除可能（ビルド時に再導入）
frontend/dist	フロントエンドのビルド成果物	削除可能（gui.py が再ビルド）
log/	ログファイル	削除可能（トラブルシューティング時は保持を推奨）

ログファイルの場所

ログ種別	格納場所
ランチャー本体	log/<日付>_launcher.txt
コアプログラム	log/<日付>_<インスタンス>.txt
エラー現場記録	log/error/<インスタンス>/<タイムスタンプ>/

ランチャーログには初期化フェーズのコマンドと結果が、コアプログラムログにはタスクの進行と画像認識の詳細が記録されます。Issue 起票時は両方の提出が求められます。

別マシンへのデータ移行

01

旧マシンでインスタンスを全停止

ファイル書き込み中の不整合を防ぐため、すべてのインスタンスを停止します。

01

config フォルダを丸ごとコピー

deploy.yaml を含む config/ ディレクトリ全体をコピーします。アカウントヴォールトはデバイス固有の暗号化キーに紐づいているため、移行先マシンで再登録が必要です。

01

新マシンでの初回起動

新マシンにランチャーを展開して一度起動し、環境自律構築（.venv のセットアップ）が完了したら一度終了します。

01

設定ファイルの配置

コピーしておいた config/ を新環境のルートディレクトリに上書き配置し、ランチャーを再起動します。

01

デバイス設定の再調整

新マシンの環境に合わせて、エミュレーターの Serial、ADB パス、スクリーンショット方式を再設定します。

完全アンインストール

1. システムトレイのアイコンから「終了」を選び、gui.py などのプロセスが残存していないことを確認します。
2. 必要に応じて config/ および AzurPilot_Data_Backup/ を退避します。
3. ランチャーのディレクトリ全体を削除します。
4. OS のスタートアップに登録していた場合は、システム設定から該当の登録エントリを削除します。

トラブルシューティングクイックリファレンス

現象	確認ポイント
「Python のダウンロード」で停止する	通信状況またはミラーの不調。-cn 版への変更や deploy.yaml の編集
「リポジトリ更新」で停止する	プロキシ設定、ブランチ名、GitHub への疎通。--skip-update での起動テスト
「依存関係同期」で停止する	PyPI ミラーの接続性。uv.lock とコードのバージョンの不一致
ウィンドウが真っ白のまま	WebView2 または libwebkit2gtk の不足
ポート競合の警告が出る	別のランチャープロセスが残存していないか確認
ウィンドウを閉じてもタスクが続く	正常な動作です（トレイに最小化されています）
トレイから終了しても python が残る	プロセス回収の失敗。ランチャーログのプロセススキャン記録を確認
更新後に WebUI が開かない	フロントエンドのビルド失敗。Node.js の導入状況と frontend/dist を確認
macOS で「壊れているため開けません」	xattr -dr com.apple.quarantine /Applications/AzurPilot.app を実行

プロセスのライフサイクルの詳細はバックエンドプロセスのライフサイクルを参照してください。