トラブルシューティング手法
自動化システムにおけるトラブルの多くは「システム全体の破損」ではなく、「特定のステップが期待通りに完了しなかった」ことに起因します。当てずっぽうに設定を変更するよりも、レイヤーごとに階層的に切り分けるアプローチが最も迅速です。
まずレイヤーを切り分ける
text
第 0 層：ランチャー / APK アプリ自体が正常に起動できるか
第 1 層：バックエンドプロセスが起動できるか（ポート競合、パスワード、フロントエンド）
第 2 層：エミュレーター/実機と接続できるか（ADB、スクリーンショット、タップ操作）
第 3 層：画面の画像認識が正しく行われているか（ページ判定、ボタン検出、OCR）
第 4 層：タスクロジックとスケジューリング（タスク選定、スケジュール時刻、エラー復帰）
第 5 層：ゲーム側の仕様変更やイベントギミックへの適合調査は必ず下位レイヤーから上位レイヤーへ順に進めてください。第2層（デバイス接続）が成立していない状態で第4層（タスク設定）を変更しても問題は解決しません。
証跡収集チェックリスト
| 証跡データ | 格納場所・確認方法 |
|---|---|
| 現在のタスクとステータス | WebUI ダッシュボード |
| 直近の実行ログ | log/<日付>_<インスタンス>.txt |
| エラー発生時の現場記録 | log/error/<インスタンス>/<タイムスタンプ>/（スクリーンショット ＋ log.txt） |
| ランチャーのログ | log/<日付>_launcher.txt |
| Android ホストのログ | log/app.log、log/proot/session.log |
| デバイスの接続状態 | adb devices、WebUI のスクリーンショットテスト |
| ソフトウェアバージョン | コアのコミットハッシュ、ランチャーのバージョン、Runtime のバージョン |
共有前のマスキング（個人情報の除外）
設定のエクスポートファイルにはエミュレーターの Serial、SSH 秘密鍵、WebUI パスワード、リモート接続用認証情報が含まれます。Issue 等に投稿する前にこれらの機密フィールドを必ず削除してください。
代表的な症状と最初の確認ポイント
| 現象 | 最初に確認すべきポイント |
|---|---|
| WebUI が開かない | プロセスが生存しているか、ポートが競合していないか、リッスンアドレスの設定 |
| スクリーンショットが真っ黒 | スクリーンショット方式の選定、解像度の設定、エミュレーターのグラフィックス描画エンジン |
| 画面をタップできない | 操作方式の設定、仮想画面の権限、ユーザー補助/特権サービスの状態 |
| 画像認識の位置がずれる | 解像度が 1280×720 固定になっているか、スキンや特殊装備による立ち絵の遮蔽 |
| タスクが繰り返し失敗する | ログ内の具体的な例外型（単に「失敗」という文字ではなくトレースバック） |
| タスクが実行されない | Enable スイッチ、NextRun の時刻、優先度設定、重要タスク失敗による一時停止 |
| 設定を変更しても反映されない | タスクが現在実行中であるか（境界時のみリロード）、override.yaml による強制上書き |
| アップデート後にクラッシュする | 直前のバージョンへのロールバック、自動生成ファイルの差分確認、依存関係の同期状態 |
変数の隔離（一度に一箇所のみ変更）
トラブルシューティング時は一度に一つの項目のみを変更し、変更前と変更後の結果を記録してください：
- スクリーンショット方式を変更する場合 → スクリーンショット方式のみ変更し、操作方式には触れない。
- 操作方式を変更する場合 → 操作方式のみを変更。
- 海域や編成を変更する場合 → タスクパラメータのみを変更。
- インスタンスを切り替える場合 → 設定固有の問題か環境全体の問題かを切り分け。
同時に複数の箇所を変更すると、どの修正が有効であったかを判別できなくなります。
直ちに自動化を停止すべきケース
| 状況 | 推奨アクション |
|---|---|
| 重要タスク（月またぎ処理、SP海域、アビサル等）での連続失敗 | 無理にリトライを繰り返さず、エラー現場のログと画面を保存して停止 |
| アカウントに異常ログインや運営からの警告通知が表示された | 直ちにすべての自動化スクリプトの実行を停止 |
| ログ内にパスワードや個人情報が出力されているのを発見した | ログの公開・共有を中止し、速やかにマスキングを実施 |
| エミュレーターの連続自動再起動が閾値を超過した | スクリプトの再試行回数を増やすのではなく、エミュレーター側の異常を点検 |
適切な Issue 報告の構成
記載すべき項目：
- 各種バージョン（コアのコミットハッシュ / ランチャー / Runtime）
- OS プラットフォームおよびエミュレーター名（実機の場合は端末型番と Android バージョン）
- 正確な再現手順（どの画面で何を操作したか）
- 期待していた結果 vs 実際の結果
- 該当部分のログ抜粋およびエラー発生時のスクリーンショット
- すでに試行した切り分け作業
記載してはならない項目：
deploy.yaml、password.txt、remote-access.jsonなどの認証情報- アカウント情報（UID や艦隊情報等）が無加工で写り込んだスクリーンショット
- 「使えません」などの具体性のない報告