[Step 4-1] Docker-based AI execution engine implementation

[takaokouji]

概要

Issue #25 Step 4のsub issueとして、DockerベースのAI実行エンジンを実装します。

現在のAiEngineを完全に置き換え、AIコードを独立したDockerコンテナプロセスで実行し、標準入出力でのJSON通信により安全なAI実行環境を提供します。

背景

現在の実装では、AIコードが同一プロセス内で実行されるため、グローバル変数の定義や危険な操作によるセキュリティリスクがあります。Dockerコンテナによる独立プロセス実行により、これらの問題を解決します。

実装要件

Docker実行環境

• ベースイメージ: 現在のsmalruby-koshienと同じ公式イメージ
• Dockerfile更新: gui/smalruby-koshien/Dockerfileの更新でAIプロセスイメージも更新される構成
• コンテナ実行単位: 1ラウンド単位でPlayer A/B独立実行
• リソース制限:
  • メモリ: 256MB
  • 実行時間: 5秒（標準出力への出力がない場合タイムアウト）

標準入出力プロトコル（JSON形式）

// 入力例（AiEngine → AIプロセス）
{
  "type": "turn_start", 
  "map": [...], 
  "player": {...}, 
  "turn": 1
}

// 出力例（AIプロセス → AiEngine）
{
  "type": "action", 
  "command": "move_to", 
  "args": ["1:2"]
}

// デバッグログ出力例
{
  "type": "debug", 
  "message": "探索開始"
}

AI段階別テストケース実装

以下のテストケースをspec/fixtures/player_ai/に作成：

(1) 何もせずにタイムアウト

• 成功条件:
  • 1ターンで終了
  • 得点が0のまま

(2) 最後までターンを進めるだけ

• 成功条件:
  • 50ターンまで進行
  • プレイヤー位置が変化しない
  • 得点が0のまま

(3) 最後まで左右に往復

• 成功条件:
  • 50ターンまで進行
  • x座標が+1, -1, +1, -1と変化
  • 移動得点が加算される

(4) 最後まで上下に往復

• 成功条件:
  • 50ターンまで進行
  • y座標が+1, -1, +1, -1と変化
  • 移動得点が加算される

(5) 同じ場所を探索するだけ

• 成功条件:
  • 50ターンまで進行
  • プレイヤー位置が変化しない
  • マップ探索情報の受け渡しが正常動作

(6) 全領域を順に探索するだけ

• 成功条件:
  • 50ターンまで進行
  • プレイヤー位置が変化しない
  • 全領域探索情報の受け渡しが正常動作

(7) 最後まで全領域を順に探索後、ゴールに向かう

• 成功条件:
  • 最初の8ターンで全領域を探索し終えること
  • 最短経路でゴールまで向かうこと
  • ゴール後にAiプロセスが停止すること
  • 途中に加点アイテムがあっても避けないこと
  • 途中に減点アイテムがあっても避けないこと
  • 途中に妨害キャラクターがいても避けないこと
  • 移動した分の得点が加算されること (5回移動するごとに3点)
  • enemyと接触した回数だけ減点されること (1回接触するごとに-10点)

(8) 最後まで全領域を順に探索後、減点アイテムを避けてゴールに向かう

• 成功条件:
  • 最初の8ターンで全領域を探索し終えること
  • 減点アイテムを避けたうえで、最短経路でゴールまで向かうこと
  • このコード自体は無限ループだが、ゴール後にAiプロセスが停止すること
  • 途中に加点アイテムがあっても避けないこと
  • 途中に減点アイテムがあると避けること
  • 途中に妨害キャラクターがいても避けないこと
  • 移動した分の得点が加算されること (5回移動するごとに3点)
  • enemyと接触した回数だけ減点されること (1回接触するごとに-10点)

実装タスク

1. アーキテクチャ設計

• Docker-based AI execution engine の詳細設計
• JSON通信プロトコルの仕様策定
• エラーハンドリング・タイムアウト処理の設計

2. AIテストケース作成

• spec/fixtures/player_ai/stage_01_timeout.rb - 何もせずタイムアウト
• spec/fixtures/player_ai/stage_02_wait_only.rb - ターンを進めるだけ
• spec/fixtures/player_ai/stage_03_horizontal_move.rb - 左右往復
• spec/fixtures/player_ai/stage_04_vertical_move.rb - 上下往復
• spec/fixtures/player_ai/stage_05_explore_local.rb - 同じ場所探索
• spec/fixtures/player_ai/stage_06_explore_all.rb - 全領域探索

3. Docker環境構築

• gui/smalruby-koshien/Dockerfileの更新
• AIプロセス実行用のDockerコンテナ設定
• リソース制限（256MB memory, 5sec timeout）の実装

4. DockerAiEngine実装

• 現在のAiEngineクラスを置き換え
• Dockerコンテナの起動・管理
• JSON形式での標準入出力通信
• タイムアウト・エラーハンドリング
• デバッグログの処理

5. テスト・検証

• 各段階(1-6)のAIコードの動作確認
• リソース制限の動作確認
• エラー・タイムアウト処理の確認
• パフォーマンステスト

参考資料

• /gui/smalruby-koshien/GAME_LOGIC_DOCUMENTATION.md#136 - AIコードサンプル
• Stage.new、list使用方法の参考実装

完了条件

• 段階(1)-(6)のAIコードが想定通りに動作する
• Dockerコンテナでの独立実行が正常動作する
• JSON通信プロトコルが正しく機能する
• リソース制限・タイムアウト処理が正常動作する
• 全てのテストケースがパスする

関連Issue

• [Step 4] ゲームロジック実装 #25 [Step 4] ゲームロジック実装 （親Issue）

注意事項

• 段階(7)以降は本Issue完了後に成功条件を明確化予定
• 既存スモウルビー甲子園の競技プログラムとの結果一致確認は次段階で実施

[takaokouji]

段階的開発ステップの提案

Dockerコンテナは最後にして、まずはローカルプロセス間通信で段階的に実装していきます。ステップ毎にPRを作成してマージする想定です。

Phase 1: 基礎実装とサンプル作成

Step 1.1: AIテストケース作成 🎯

• spec/fixtures/player_ai/に段階(1)-(6)のRubyファイル作成
• 各段階の動作を確認できる最小限の実装
• GAME_LOGIC_DOCUMENTATION.md#136のサンプルを参考にした実装

Step 1.2: JSON通信プロトコル設計

• 標準入出力でのJSON形式通信仕様策定
• 入力フォーマット（ターン開始、マップ情報等）
• 出力フォーマット（アクション、デバッグログ等）
• エラーハンドリング方式の定義

Phase 2: ローカルプロセス実行基盤

Step 2.1: AIプロセス実行ラッパー作成

• ローカルでRubyプロセスを起動するクラス
  • AiEngineからキックされる。
  • 名前は決めていないので、決めてください。
  • 1ラウンド単位でPlayer A/B独立実行可能
• 標準入出力でのJSON送受信機能
• プロセス管理（起動・停止・タイムアウト）
  • AiEngineからキックされて起動
  • 一定時間、AiプロセスからAiEngineへの出力メッセージなければタイムアウト
  • 50ターンに到達したら停止
  • タイムアウトしたら停止

Step 2.2: 基本的なAiEngine置き換え

• 現在のAiEngineをAiProcessManagerを使うように修正
• ローカルプロセス実行による単純なAI実行
• 既存テストの動作確認

Phase 3: 完全なプロセス間通信実装

Step 3.1: 高度なJSON通信実装

• マップ情報、プレイヤー状態の完全な受け渡し
• Koshien APIメソッドの標準入出力での実装
• ターン制御とゲーム状態管理

Step 3.2: 段階の完全動作確認

• 各段階のAIが想定通りに動作することの確認
• 成功条件の自動テスト実装
• デバッグログ機能の実装

Phase 4: リソース制限とセキュリティ

Step 4.1: タイムアウト・リソース制限

• プロセス実行時間制限（10秒）
• メモリ使用量監視（ローカルレベル）
• プロセス強制終了処理

Step 4.2: セキュリティ強化

• 危険な操作の制限
• ファイルアクセス制限
• ネットワークアクセス制限

Phase 5: Docker化

Step 5.1: Dockerファイル更新

• gui/smalruby-koshien/Dockerfileの更新
• AIプロセス実行用環境の構築

Step 5.2: Docker実行エンジン実装

• ProcessBasedAiEngineをDockerAiEngineに拡張
• コンテナ起動・管理機能
• リソース制限のDocker実装（256MB等）

Phase 6: 統合テスト・最適化

Step 6.1: 完全な統合テスト

• 全段階のDocker環境での動作確認
• パフォーマンステスト
• 並列実行テスト（Player A/B同時実行）

Step 6.2: 最適化・ドキュメント整備

• パフォーマンス最適化
• エラーハンドリングの改善
• 実装ドキュメントの整備

---

Step 1.1から開始します。AIテストケース作成のPRを作成して進めていきます。