RN Agent Observer

VI · English

RN Agent Observer 2.4.0 は、React Native/Expo 向けのローカルランタイム可観測性ブリッジです。CLI と MCP の両方で同じ TypeScript コアを使用し、ADB/UIAutomator 経由で Android を制御し、開発用インストルメンテーションからテレメトリを受信し、Metro の Chrome DevTools Protocol を通じて console/exception/heap/JS CPU プロファイルをエクスポートし、アプリのインストルメンテーションなしでリクエストごとのネットワークを取得し、エージェント向けに state/headline/actions/UI findings を含む構造化された画面理解を生成し、セッション安定の ref スナップショット + diff + 自動記録リプレイを提供し、画面ビデオを録画し、セッションを SQLite に保存し、スクリーンショット/トレース/UI ツリーをディスク上のアーティファクトとして保持します。

現在のリリースは Windows 上の Android v1 を完了しています: 45 の MCP ツール、対応する CLI、決定的なラボを備えた Expo デモ、透明なヒューリスティック診断、ピクセル + 構造的 UI 比較。

要件

• Node.js 22.12 以上

• pnpm 9.6

• Android Platform Tools (adb)

• USB デバッグが有効な Android エミュレータまたは実機

• アプリ固有のテレメトリが必要な場合の Expo development build

Related MCP server: React Native MCP Server

クイックスタート

pnpm install
pnpm check
adb devices -l
pnpm rn-observe --help
pnpm mcp:check

observer を Expo/React Native アプリに向けます:

$env:RN_OBSERVER_PROJECT_ROOT = 'C:\path\to\expo-app'
$env:RN_OBSERVER_DEVICE_ID = 'emulator-5554'
# Có thể bỏ qua nếu app.json chứa expo.android.package
$env:RN_OBSERVER_APP_ID = 'com.example.app'

pnpm rn-observe launch
pnpm rn-observe observe
pnpm rn-observe understand-screen
pnpm rn-observe ui-model
pnpm rn-observe tap --test-id buy-button
pnpm rn-observe performance
pnpm rn-observe diagnose

アーティファクトと SQLite データは <projectRoot>/.artifacts/ の下に作成されます。大きなバイナリは MCP レスポンスに埋め込まれることはありません。

決定的デモ

pnpm --filter @rn-agent-observer/demo-expo android -- --device <device-name>

デモには PerformanceLab、NetworkLab、RenderLab、AnimationLab、ErrorLab、VisualLab が含まれています。NetworkLab は内部フィクスチャ（0/500/2000ms と HTTP 503）を使用するため、インターネットサービスに依存しません。PerformanceLab は意図的な 100ms の長い JS タスクをインストルメンテーションを通じて正確に報告します。

MCP

pnpm mcp:check
pnpm mcp:start

サーバーは stdio を使用します。クライアント設定と 45 ツールの完全なリストは docs/protocol.md に文書化されています。

AI エージェント統合

エージェント（OpenCode/Claude Code/Cursor/Codex...）が observer を使用する方法は 3 つあります:

1. MCP サーバー（推奨 — 構造化ツール）

{
  "mcpServers": {
    "rn-agent-observer": {
      "command": "node",
      "args": [
        "C:\\abs\\rn-agent-observer\\packages\\mcp-server\\dist\\server.js"
      ],
      "env": {
        "RN_OBSERVER_PROJECT_ROOT": "C:\\path\\to\\expo-app",
        "RN_OBSERVER_DEVICE_ID": "emulator-5554"
      }
    }
  }
}

2. スキルとしてインストール（CLI でエージェントにデバッグワークフローを教える）

npx skills add GinzaTech/rn-agent-observer

スキルは skills/rn-agent-observer/SKILL.md にあります — observe -> understand-screen -> reproduce -> diagnose -> fix -> understand-screen -> compare のループ、メトリクスを正直に読む方法、一般的な障害からの回復を教えます。インストール後、「アプリ X が遅い」と言うだけで、エージェントは rn-observe を使うことを自動的に認識します。

3. AGENTS.md（エージェントがこのリポジトリ内で作業する場合） — ルートに既に存在し、エージェントが自動的に読み取ります。

3 つの方法はすべて併用できます: skill/AGENTS.md は ワークフロー を教え、MCP は 直接呼び出し可能なツール を提供します。

ドキュメント

• 詳細な使用ガイド

• 完全なプロジェクト概要（VI/EN）

• アーキテクチャ

• CLI と MCP プロトコル

• メトリクス定義

• 機能マトリックス

• テストとランタイム検証

• 標準テストロードマップ（テストブループリント）

• トラブルシューティング

• チェンジログ

現在のバージョン

• Android/Windows は Observer 2.4.0 の唯一のターゲットです。

• ADB には信頼できる JS FPS シグナルがありません。フィールドは available: false として返され、数値を推測することはありません。

• JS blocking、route、React renders、ネットワークメタデータにはアプリ内の開発用インストルメンテーションが必要です。

• CDP 経由の DevTools エクスポート（devtools-export、devtools-profile）とリクエストごとのネットワーク（metro-network）には、Metro が実行中でアプリが Metro に接続されている必要があります（adb reverse tcp:8081 tcp:8081）。別の React Native DevTools セッションが接続を保持している場合は使用できません。

• reload --fast は CDP Page.reload（JS のみ）を使用し、Metro が利用できない場合は自動的に force-stop にフォールバックします。

• record（screenrecord）は Android により 180 秒/クリップに制限されています。

• Perfetto トレースは Android をサポートしています。深いトレース分析は引き続き Perfetto UI/Android Studio を使用します。

• CDP コマンドはプロセス間でキューされます。外部の React Native DevTools は observer のロックに参加しないため、閉じる必要があります。

• session stop は自動的にリプレイを生成します。セッション内の ref は reorder/scroll でも安定しています。セッションがない場合は EVIDENCE_NOT_RECORDED を発行します。

• understand-screen/MCP understand_screen は、利用可能な場合は route インストルメンテーション、画面状態、ヘッドライン、テキスト/アクション ref、UI findings、スクリーンショット/UI ツリーのエビデンスを返します。繰り返し呼び出すと、変化のないローディングを検出します。分類はヒューリスティックであり、テキストフィールドの値は常に redact されます。

• ui-model/MCP runtime_ui_model は TypeScript AST を使用して TSX を解析し、コンポーネント + file:line を取得し、インストルメンテーションおよびネイティブツリーと関連付けます。結果は rendered、visible/offscreen/hidden/unmounted/flattened-or-unobserved、enabled、canPress（理由付き）を区別します。

• Babel プラグイン（開発時のみ）はソース由来の testID を自動的に追加し、onPress をラップします。セッション停止時に interaction start/success/error を収集し、testID を持つタップをリプレイに含めます。ハンドラー引数、props、入力値は記録されません。

• Observer はデフォルトでネットワークボディを収集しません。開発時のみのオプトインは fail-closed の allowlist を使用しますが、それでもフィクスチャに限定して使用する必要があります。

• インストルメンテーションのないアプリ: フォールバックエビデンスとして metro-network（CDP）、app-state（フォアグラウンドアクティビティ、PID）、device-network（デバイスレベルのバイトカウンター、アプリに帰属しない）を使用します。

RN Agent Observer (英語)

RN Agent Observer 2.4.0 は、React Native/Expo 向けのローカルランタイム可観測性ブリッジです。CLI と MCP サーバーの両方の背後で共有 TypeScript コアを使用し、ADB/UIAutomator を通じて Android を駆動し、開発用インストルメンテーションからテレメトリを受信し、Metro の Chrome DevTools Protocol を通じて console/例外/ヒープ/JS CPU プロファイルをエクスポートし、アプリのインストルメンテーションなしでリクエストごとのネットワークトラフィックをキャプチャし、エージェント向けに構造化された画面理解（state/headline/actions/UI findings）を生成し、セッション安定の ref スナップショット + diff + 自動記録されたリプレイスクリプトを提供し、画面上のビデオを録画し、セッションを SQLite に永続化し、スクリーンショット/トレース/UI ツリーをディスク上のアーティファクトとして保持します。

現在のリリースは Windows 上の Android v1 を完了しています: 45 の MCP ツール、対応する CLI、決定的なラボを備えた Expo デモアプリ、透明なヒューリスティック診断、ピクセル + 構造的 UI 比較。

要件

• Node.js 22.12 以上

• pnpm 9.6

• Android Platform Tools (adb)

• USB デバッグが有効な Android エミュレータまたは実機

• アプリ固有のテレメトリが必要な場合の Expo development build

クイックスタート

pnpm install
pnpm check
adb devices -l
pnpm rn-observe --help
pnpm mcp:check

observer を Expo/React Native アプリに向けます:

$env:RN_OBSERVER_PROJECT_ROOT = 'C:\path\to\expo-app'
$env:RN_OBSERVER_DEVICE_ID = 'emulator-5554'
# Optional when app.json contains expo.android.package
$env:RN_OBSERVER_APP_ID = 'com.example.app'

pnpm rn-observe launch
pnpm rn-observe observe
pnpm rn-observe understand-screen
pnpm rn-observe ui-model
pnpm rn-observe tap --test-id buy-button
pnpm rn-observe performance
pnpm rn-observe diagnose

アーティファクトと SQLite データは <projectRoot>/.artifacts/ の下に作成されます。大きなバイナリは MCP レスポンスに埋め込まれることはありません。

決定的デモ

pnpm --filter @rn-agent-observer/demo-expo android -- --device <device-name>

デモには PerformanceLab、NetworkLab、RenderLab、AnimationLab、ErrorLab、VisualLab が含まれています。NetworkLab は内部フィクスチャ（0/500/2000ms と HTTP 503）を使用するため、インターネットサービスに依存しません。PerformanceLab は意図的な 100ms の長い JS タスクをインストルメンテーションを通じて正確に報告します。

MCP

pnpm mcp:check
pnpm mcp:start

サーバーは stdio を使用します。クライアント設定と 45 ツールの完全なリストは docs/protocol.md に文書化されています。

ドキュメント

• 完全なプロジェクト概要（VI/EN）

• 詳細な使用ガイド（ベトナム語）

• アーキテクチャ

• CLI と MCP プロトコル

• メトリクス定義

• 機能マトリックス

• テストとランタイム検証

• テストブループリント

• トラブルシューティング

• チェンジログ

AI エージェント統合

エージェント（OpenCode/Claude Code/Cursor/Codex...）が observer を使用する方法は 3 つあります:

1. MCP サーバー（推奨 — 構造化ツール）

{
  "mcpServers": {
    "rn-agent-observer": {
      "command": "node",
      "args": [
        "C:\\abs\\rn-agent-observer\\packages\\mcp-server\\dist\\server.js"
      ],
      "env": {
        "RN_OBSERVER_PROJECT_ROOT": "C:\\path\\to\\expo-app",
        "RN_OBSERVER_DEVICE_ID": "emulator-5554"
      }
    }
  }
}

2. スキルとしてインストール（CLI でエージェントにデバッグワークフローを教える）

npx skills add GinzaTech/rn-agent-observer

スキルは skills/rn-agent-observer/SKILL.md にあります — observe -> understand-screen -> reproduce -> diagnose -> fix -> understand-screen -> compare のループ、メトリクスを正直に読む方法、一般的な障害からの回復を教えます。インストール後、「アプリ X が遅い」と言うだけで、エージェントは rn-observe を使うことを自動的に認識します。

3. AGENTS.md（エージェントがこのリポジトリ内で作業する場合） — リポジトリのルートに既に存在し、エージェントが自動的に読み取ります。

3 つの方法はすべて併用できます: skill/AGENTS.md は ワークフロー を教え、MCP は 直接呼び出し可能なツール を提供します。

現在の境界

• Android/Windows は Observer 2.4.0 の唯一のサポート対象ターゲットです。

• ADB には信頼できる JS FPS シグナルがありません。フィールドは available: false として返されます — 値が推測されることはありません。

• JS blocking、route、React renders、ネットワークメタデータにはアプリ内の開発用インストルメンテーションが必要です。

• CDP 機能（devtools-export、devtools-profile、metro-network）には、適切なアプリに対して Metro が実行され、アプリが Metro に接続されている必要があります（adb reverse tcp:8081 tcp:8081）。別の React Native DevTools セッションが接続を保持している間はアタッチできません。

• reload --fast は CDP Page.reload（JS のみ）を使用し、Metro が利用できない場合は自動的に force-stop にフォールバックします。

• Observer の CDP コマンドはプロセス間でキューされます。外部の React Native DevTools は observer のロックに参加しないため、閉じる必要があります。

• session stop は自動的にリプレイを書き込み、セッション ref は reorder/scroll でも存続し、セッションがない場合は EVIDENCE_NOT_RECORDED を生成します。

• understand-screen/MCP understand_screen は、利用可能な場合はインストルメントされた route、画面状態、ヘッドライン、テキスト/アクション ref、UI findings、スクリーンショット/UI ツリーのエビデンスを返します。繰り返し呼び出すと、変化のないローディングを検出します。分類はヒューリスティックであり、テキストフィールドの値は常に redact されます。

• ui-model/MCP runtime_ui_model は TypeScript AST を使用して TSX を解析し、コンポーネント + file:line を取得し、ソースをインストルメンテーションおよびネイティブツリーと関連付けます。rendered、visible/off-screen/hidden/unmounted/flattened-or-unobserved、enabled、エビデンスに基づく canPress 状態を区別します。

• 開発時のみの Babel プラグインはソース由来の testID を注入し、onPress をラップします。セッション停止時に interaction start/success/error を収集し、testID タップをリプレイに昇格させます。ハンドラー引数、props、入力値は決して記録されません。

• ネットワークボディのキャプチャはデフォルトでオフです。開発時のみのオプトインは fail-closed の allowlist を使用し、フィクスチャに限定する必要があります。

• インストルメンテーションのないアプリ: フォールバックエビデンスとして metro-network（CDP）、app-state（フォアグラウンドアクティビティ、PID）、device-network（デバイスレベルのバイトカウンター、アプリに帰属しない）を使用します。

• record（screenrecord）は Android により 180 秒/クリップに制限されています。

• Perfetto トレースは Android でサポートされています。深いトレース分析は Perfetto UI/Android Studio に残ります。