moai-domain-adb

moai-domain-adb：ADB 自動化ドメインスペシャリスト

インテリジェントな Android 自動化、ゲームボット開発、リアルタイムのデバイスオーケストレーション向けのTier 3 モジュール化スキルです。

---

🎯 クイックリファレンス

中核となる能力

ドメイン	能力	モジュール
デバイス制御	ADB 接続、シェル実行、プロパティの検査	adb-fundamentals
デバイス管理	複数デバイスのオーケストレーション、状態追跡、ライフサイクル	device-management
ゲーム自動化	ボットのスクリプト作成、アクションシーケンス、タイミング制御	game-automation
ビジョンと検出	テンプレートマッチング、OCR、領域ベースの検出	computer-vision
Tauri 統合	UI と Python のブリッジ、リアルタイム通信、デプロイ	tauri-integration

主な関数（クイックアクセス）

デバイス操作

# Check device status
adb devices --list-long

# Execute shell command
adb shell input tap 540 960

# Get device property
adb shell getprop ro.build.version.sdk

# Install APK
adb install -r game.apk

ボット制御

# Start bot
adb shell am start -n com.game/.MainActivity

# Send input sequence
adb shell input tap x y && sleep 1 && adb shell input tap x2 y2

# Capture screenshot
adb shell screencap -p /sdcard/screen.png

モジュール選択ガイド

次のような場合に使用します……

• ADB の基礎を理解する：adb-fundamentals モジュールを読み込みます

  • 接続プロトコル、認証、基本的なシェル操作
  • デバイスの検出、プロパティの読み取り、システムとの対話

• 複数のデバイスを管理する：device-management モジュールを読み込みます

  • デバイス状態の追跡、接続プーリング、フェイルオーバー戦略
  • 一括操作、監視、ライフサイクル管理

• ゲームボットを開発する：game-automation モジュールを読み込みます

  • クリックシーケンス、タイミング、OCR の解析、状態検出
  • カスタムルーチン、アクションテンプレート、ボットのパターン

• 検出にビジョンを使用する：computer-vision モジュールを読み込みます

  • テンプレートマッチング（OpenCV）、OCR（Tesseract）
  • 領域ベースの検出、画像分析、パターン認識

• Tauri UI と統合する：tauri-integration モジュールを読み込みます

  • ボットのステータスをリアルタイムで更新、コマンドのキューイング
  • UI ↔ Python 通信、リソース管理

---

📚 実装ガイド

アーキテクチャ概要

moai-domain-adb は、5 モジュールの段階的開示パターンに従います。

moai-domain-adb/
├── SKILL.md                    # This file (documentation hub)
├── modules/
│   ├── adb-fundamentals.md     # Level 1: Core ADB operations
│   ├── device-management.md    # Level 2: Multi-device orchestration
│   ├── game-automation.md      # Level 3: Bot development patterns
│   ├── computer-vision.md      # Level 4: Vision-based detection
│   └── tauri-integration.md    # Level 5: UI orchestration
└── scripts/                    # IndieDevDan UV scripts
    ├── adb_device_analyzer.py  # Analyze device capabilities
    ├── adb_bot_generator.py    # Generate bot skeletons
    ├── adb_template_creator.py # Create action templates
    ├── adb_performance_profiler.py  # Profile bot performance
    ├── adb_config_validator.py # Validate configurations
    ├── adb_game_tester.py      # Test bot on devices
    └── adb_deployment_helper.py # Deploy to production

Tier 3 の特徴

✅ モジュール化：独立した 5 つのモジュール（モジュール間のインポートなし） ✅ 本番環境対応：包括的なドキュメントを含む 500 行以上の SKILL.md ✅ スクリプト化：IndieDevDan の 13 のルールに従う 7 つの UV スクリプト ✅ 委任可能：expert-* および manager-* エージェントと連携 ✅ 再利用可能：あらゆる Android 自動化プロジェクトに適用可能

使用パターン

# Pattern 1: Load skill for general ADB knowledge
Skill("moai-domain-adb")

# Pattern 2: Load specific module for targeted expertise
# In agent prompt: "Use moai-domain-adb:adb-fundamentals for device operations"

# Pattern 3: Reference UV script for automated tasks
# Command: uv run .claude/skills/moai-domain-adb/scripts/adb_device_analyzer.py --device emulator-5554

統合ポイント

エージェントとの連携：

• adb-bot-runner：game-automation のパターンを使用してボットを実行します
• adb-device-manager：device-management の専門知識を活用してデバイスを管理します
• adb-game-tester：computer-vision と game-automation を使用してボットをテストします
• adb-config-manager：config-validator スクリプトを使用して設定を検証します
• adb-workflow-orchestrator：tauri-integration のパターンを使用してすべてのエージェントを調整します

コマンドとの連携：

• /adb:init → adb-fundamentals + adb_device_analyzer を使用します
• /adb:bot → game-automation + adb_bot_generator を使用します
• /adb:test → computer-vision + adb_game_tester を使用します
• /adb:deploy → tauri-integration + adb_deployment_helper を使用します

UV スクリプトとの連携： 7 つのスクリプトはすべて自己完結型（相互依存なし）で、PEP 723 に準拠し、二重出力（人間が読める形式と JSON）を実装しています。

段階的な情報開示戦略

レベル 1：はじめに

• 読む：adb-fundamentals モジュール
• 実行する：adb_device_analyzer.py を実行してデバイスを一覧表示します
• 理解する：基本的なデバイス接続とプロパティの読み取り

レベル 2：複数デバイスのワークフロー

• 読む：device-management モジュール
• 理解する：接続プーリング、状態追跡、フェイルオーバー
• 作成する：5 台以上のデバイスを同時に管理するスクリプト

レベル 3：ゲームボットの開発

• 読む：game-automation モジュール
• 理解する：クリックシーケンス、タイミング制御、OCR の統合
• 作成する：ゲーム固有のタスクに対応するカスタムルーチン

レベル 4：ビジョンベースの自動化

• 読む：computer-vision モジュール
• 理解する：テンプレートマッチング、OCR の解析、領域検出
• 作成する：UI の変更に動的に適応するボット

レベル 5：本番環境のオーケストレーション

• 読む：tauri-integration モジュール
• 理解する：リアルタイム UI 更新、コマンドキューイング、リソース管理
• 作成する：Tauri UI 制御を使ったエンタープライズワークフロー

---

🚀 高度なトピック

スキルの構成戦略

moai-domain-adb はモジュール式に構成できるよう設計されています。

# Example 1: Simple device check
# Required: adb-fundamentals
agent = Task(
    subagent_type="expert-backend",
    prompt="Use moai-domain-adb:adb-fundamentals to list ADB devices"
)

# Example 2: Multi-device bot deployment
# Required: device-management + game-automation + tauri-integration
agent = Task(
    subagent_type="adb-workflow-orchestrator",
    prompt="Deploy game bot to 3 devices"
)

# Example 3: Vision-based testing
# Required: computer-vision + game-automation
agent = Task(
    subagent_type="adb-game-tester",
    prompt="Test bot with computer vision verification"
)

パフォーマンスの最適化

デバイスのバッチ処理：

• デバイスごとにコマンドをまとめて、往復レイテンシーを削減します
• adb_performance_profiler.py を使用してボトルネックを特定します
• 目標：5 秒未満で 100 件のアクションを実行します

キャッシュ戦略：

• デバイスのプロパティをキャッシュします（60 秒ごとに更新）
• テンプレート画像をキャッシュします（検出に失敗した場合に更新）
• ボットの設定をキャッシュします（ユーザーが編集したときに無効化）

並行処理：

• ThreadPoolExecutor を使用して複数デバイスの操作を実行します
• ホストごとの同時 ADB 操作を 5 件に制限します
• デバイスが 5 台を超える場合はキューイングを使用します

セキュリティに関する考慮事項

認証：

• ADB は RSA キー交換を使用します。デバイス証明書を検証してください
• 暗号化されていないデバイスのペアリングキーは決して保存しないでください
• 本番デバイスのペアリングキーは四半期ごとにローテーションしてください

権限：

• 必要最小限のシェルコマンドを要求します（必要がない限り su は避けてください）
• root アクセスの代わりに、アプリ固有のコマンドを使用します
• 意図しない副作用がないか、ボットのアクションを監査します

データ保護：

• スクリーンショットに機密データを決して含めないでください
• API キーを含む保存済みの設定を暗号化します
• ゲームの認証情報には安全なストレージを使用します

デバッグとトラブルシューティング

よくある問題：

問題	診断	解決方法
デバイスが見つからない	adb_device_analyzer.py --check-connection	USB 接続を確認し、ADB デーモンを確認します
ボットの実行が遅い	adb_performance_profiler.py --device <id>	クリック間隔を短縮し、操作をまとめます
テンプレートマッチングに失敗する	画像の DPI／解像度を確認します	adb_template_creator.py --device <id> を実行します
OCR の精度が低い	画像を前処理します（コントラスト、しきい値）	ヒントについては computer-vision モジュールを参照してください
Tauri との通信が遅延する	Python プロセスの CPU 使用率を確認します	ログの詳細度を下げ、レンダーループを最適化します

デバッグモード：

# Enable verbose logging
export ADB_DEBUG=1
uv run .claude/skills/moai-domain-adb/scripts/adb_device_analyzer.py --verbose

# Trace ADB commands
adb logcat | grep "adb_bot_runner"

テスト戦略（TRUST 5 フレームワーク）

テストカバレッジの目標：≥85%

• ユニットテスト：個々のモジュール関数（py.test）
• 統合テスト：モジュール間の連携（デバイスのモック）
• E2E テスト：実デバイスを使ったワークフロー全体（任意）
• パフォーマンステスト：実行時間のベンチマーク
• セキュリティテスト：入力検証、権限チェック

テストの実行：

# Run all tests
pytest tests/ -v --cov=.claude/skills/moai-domain-adb

# Run specific module tests
pytest tests/test_device_management.py -v

# Profile performance
pytest tests/ --benchmark-only

---

📖 モジュールナビゲーション

各モジュールは前の知識を基にしていますが、単独でも使用できます。

• adb-fundamentals（250 行）

  • ADB のアーキテクチャ、接続プロトコル、デバイスの検出
  • シェルの実行、プロパティの読み取り、デバイス操作

• device-management（280 行）

  • 複数デバイスのオーケストレーション、状態の追跡、接続プーリング
  • ライフサイクル管理、監視、フェイルオーバー戦略

• game-automation（300 行）

  • ボットスクリプトのパターン、クリックシーケンス、タイミング制御
  • OCR の統合、状態の検出、アクションテンプレート

• computer-vision（270 行）

  • テンプレートマッチング（OpenCV）、OCR（Tesseract）
  • 領域検出、画像の前処理、パターン認識

• tauri-integration（240 行）

  • Tauri-Python IPC、リアルタイム更新、コマンドのキューイング
  • リソース管理、デプロイ戦略、監視

---

🛠️ スクリプトとツール

すべてのスクリプトは IndieDevDan 13 Rules（PEP 723、9 セクション構成、デュアル出力）に準拠しています。

# Analyze device capabilities
uv run scripts/adb_device_analyzer.py --device emulator-5554 --json

# Generate bot skeleton
uv run scripts/adb_bot_generator.py --game "My Game" --output my_bot.py

# Create action template
uv run scripts/adb_template_creator.py --screenshot screen.png --region "0,0,1080,1920"

# Profile bot performance
uv run scripts/adb_performance_profiler.py --bot bot.py --iterations 100

# Validate configuration
uv run scripts/adb_config_validator.py --config config.yaml --strict

# Test bot on device
uv run scripts/adb_game_tester.py --bot bot.py --device emulator-5554

# Prepare deployment
uv run scripts/adb_deployment_helper.py --bot bot.py --target production

スクリプト一覧（全 36 件）

すべてのスクリプトは scripts/ ディレクトリにあり、カテゴリ別に整理されています。各スクリプトは次のオプションに対応しています。

• --device/-d - デバイス ID を指定します（デフォルトは最初に接続されたデバイスです）
• --toon - 自動化向けに TOON/YAML 形式で出力します
• --verbose/-v - 詳細なログを有効にします
• --help - 詳細なヘルプと使用例を表示します

150 件以上の使用例を含む詳細なドキュメントについては、scripts/README.md を参照してください。

🔌 接続（スクリプト 4 件）

場所：scripts/connection/

スクリプト	目的	主なオプション	例
adb_connect.py	IP:ポート経由でデバイスに接続	--device（デフォルト：127.0.0.1:5555）	uv run scripts/connection/adb_connect.py
adb_disconnect.py	デバイスを安全に切断	--device	uv run scripts/connection/adb_disconnect.py
adb_restart_server.py	ADB サーバーを再起動	--verbose	uv run scripts/connection/adb_restart_server.py
adb_device_status.py	すべてのデバイスと状態を一覧表示	--toon	uv run scripts/connection/adb_device_status.py

📱 画面（スクリプト 6 件）

場所：scripts/screen/

スクリプト	目的	主なオプション	例
adb_screenshot.py	スクリーンショットを撮影	--output FILE	uv run scripts/screen/adb_screenshot.py --output capture.png
adb_tap.py	指定座標をタップ	--x X --y Y --count N	uv run scripts/screen/adb_tap.py --x 500 --y 1000
adb_swipe.py	スワイプ操作	--preset {up,down,left,right} または --start X,Y --end X,Y	uv run scripts/screen/adb_swipe.py --preset up
adb_keyevent.py	キーイベントを送信	--key {back,home,menu,power,volume_up}	uv run scripts/screen/adb_keyevent.py --key back
adb_text_input.py	テキストを入力	--text TEXT	uv run scripts/screen/adb_text_input.py --text "Hello"
adb_screenrecord.py	画面の動画を録画	--output FILE --duration SECONDS	uv run scripts/screen/adb_screenrecord.py --duration 60

📦 アプリ（スクリプト 5 件）

場所：scripts/app/

スクリプト	目的	主なオプション	例
adb_app_list.py	インストール済みアプリを一覧表示	--filter TEXT、--system、--all	uv run scripts/app/adb_app_list.py --filter afk
adb_app_start.py	パッケージを指定してアプリを起動	-p PACKAGE、--wait	uv run scripts/app/adb_app_start.py -p com.afk.journey
adb_app_stop.py	アプリを強制停止	-p PACKAGE	uv run scripts/app/adb_app_stop.py -p com.afk.journey
adb_app_install.py	APK をインストール	--apk FILE	uv run scripts/app/adb_app_install.py --apk game.apk
adb_app_uninstall.py	アプリをアンインストール	-p PACKAGE、--keep-data	uv run scripts/app/adb_app_uninstall.py -p com.example

ℹ️ 情報（4 スクリプト）

場所：scripts/info/

スクリプト	目的	主なオプション	例
adb_device_info.py	デバイスの仕様	--toon	uv run scripts/info/adb_device_info.py
adb_display_info.py	ディスプレイの解像度／DPI	--toon	uv run scripts/info/adb_display_info.py
adb_running_app.py	現在フォアグラウンドにあるアプリ	--toon	uv run scripts/info/adb_running_app.py
adb_battery_info.py	バッテリーの状態	--toon	uv run scripts/info/adb_battery_info.py

⚡ パフォーマンス（3 スクリプト）

場所：scripts/performance/

スクリプト	目的	主なオプション	例
adb_cpu_monitor.py	CPU をリアルタイムで監視	--duration SECONDS、--package PKG	uv run scripts/performance/adb_cpu_monitor.py --duration 60
adb_memory_monitor.py	メモリ使用量を監視	--duration SECONDS、--package PKG	uv run scripts/performance/adb_memory_monitor.py --duration 60
adb_logcat_filter.py	logcat ログをフィルタリング	--tag TAG、--priority {V,D,I,W,E,F}、--follow	uv run scripts/performance/adb_logcat_filter.py --tag MyApp --priority E

🤖 自動化（4 スクリプト）

場所：scripts/automation/

スクリプト	目的	主なオプション	例
adb_game_loop.py	繰り返しシーケンスを実行	-s FILE、-l LOOPS、--infinite	uv run scripts/automation/adb_game_loop.py -s daily.json -l 10
adb_wait_for_app.py	アプリの起動を待機	--package PKG、--timeout SECONDS	uv run scripts/automation/adb_wait_for_app.py -p com.afk.journey
adb_click_sequence.py	シーケンスを 1 回実行	-s FILE	uv run scripts/automation/adb_click_sequence.py -s tutorial.json
adb_screenshot_compare.py	スクリーンショットを比較	-b BEFORE -a AFTER、--threshold FLOAT	uv run scripts/automation/adb_screenshot_compare.py -b ref.png -a test.png

🛠️ ユーティリティ（3 スクリプト）

場所：scripts/utils/

スクリプト	目的	主なオプション	例
adb_shell.py	シェルコマンドを実行	-c COMMAND、--timeout SECONDS	uv run scripts/utils/adb_shell.py -c "ls /sdcard"
adb_push.py	ファイルをデバイスにプッシュ	-l LOCAL -r REMOTE	uv run scripts/utils/adb_push.py -l file.txt -r /sdcard/
adb_pull.py	ファイルをデバイスから取得	-r REMOTE -l LOCAL	uv run scripts/utils/adb_pull.py -r /sdcard/screenshot.png -l .

🔧 監視（7 スクリプト）

場所：scripts/（ルートレベル）

スクリプト	目的	主なオプション	例
adb_bot_generator.py	ボットスクリプトを生成	--template NAME、--output FILE	uv run scripts/adb_bot_generator.py --template daily_quests
adb_config_validator.py	設定を検証	--config FILE、--strict	uv run scripts/adb_config_validator.py --config config.json
adb_deployment_helper.py	デバイスにデプロイ	--apk FILE、--all、--devices IDS	uv run scripts/adb_deployment_helper.py --apk game.apk --all
adb_device_analyzer.py	機能を分析	--aspects LIST、--output FILE	uv run scripts/adb_device_analyzer.py --aspects performance,battery
adb_game_tester.py	ゲームの自動化をテスト	--test-suite FILE、--screenshots	uv run scripts/adb_game_tester.py --test-suite tests.json
adb_performance_profiler.py	パフォーマンスをプロファイリング	--package PKG、--duration SECONDS	uv run scripts/adb_performance_profiler.py -p com.afk.journey
adb_template_creator.py	テンプレートを作成	--name NAME、--category CAT	uv run scripts/adb_template_creator.py --name my_automation

JSON シーケンス形式（自動化スクリプト）

adb_game_loop.py と adb_click_sequence.py では、JSON 形式を使用します：

{
  "name": "Daily Quest Automation",
  "steps": [
    {"action": "tap", "x": 500, "y": 1000, "delay": 2},
    {"action": "swipe", "start": [500, 1500], "end": [500, 500], "duration": 300},
    {"action": "wait", "duration": 3},
    {"action": "screenshot", "output": "/tmp/check.png"},
    {"action": "keyevent", "key": "back"},
    {"action": "text_input", "text": "Hello World"}
  ]
}

対応アクション：tap、swipe、wait、screenshot、keyevent、text_input

共通ユーティリティ

すべてのスクリプトは、scripts/common/ の共有ユーティリティを使用します。

• adb_utils.py - ADB デバイスの操作と接続管理
• cli_utils.py - Click デコレーター、Rich フォーマッター、出力ヘルパー
• error_handlers.py - 標準化されたエラー処理と終了コード（0、2、3、4）
• path_utils.py - プロジェクトルートの検出とパスの解決

終了コード

すべてのスクリプトで、標準化された終了コードを使用します。

• 0 - 成功
• 2 - デバイスがオフライン、または見つかりません
• 3 - ADB コマンドの失敗、または実行エラー
• 4 - 引数または設定が無効です

出力形式

テキスト出力（デフォルト）：色とテーブルを使用した Rich 形式のコンソール出力 TOON 出力（--toon）：自動化と解析に使用する YAML／構造化形式

---

📞 サポートと参考資料

クイックリンク：

• モジュール：modules/ 内の各モジュールファイルを参照してください
• スクリプト：scripts/ 内の各スクリプトで --help を実行してください
• 例：adb-* エージェントの統合パターンを参照してください
• テスト：tests/ 内のテストスイートを参照してください

Context7 の参考資料：

• Android ADB プロトコル（Android Developers）
• Python ADB ライブラリ（Google GitHub）
• OpenCV ドキュメント（OpenCV Docs）
• Tesseract OCR（GitHub）

---

バージョン：1.0.0 ステータス：✅ 本番環境対応（フェーズ 1 の基盤） 最終更新日：2025-12-01 次のフェーズ：5 つのコアモジュールと 7 つの UV スクリプトを作成