lynx-devtool

Agent Lynx DevTool スキル

このスキルを使用すると、agent-lynx CLI で、接続済みデバイス（Android、iOS、Desktop）上で実行中の Lynx アプリを操作できます。

使用方法

agent-lynx CLI を使用します。公開パッケージは agent-lynx です。 このパッケージ @lynx-js/skill-lynx-devtool は、この スキルの手順とリソースの正式な提供元です。agent-lynx はこのパッケージに依存し、 skills list/get で直接読み取ります。また、互換性のためのランチャーにより、従来の npx -y @lynx-js/skill-lynx-devtool の一度限りの呼び出しも引き続き使用できます。

プログラム API は agent-lynx/connector からエクスポートされます。このエントリは @lynx-js/devtool-connector、@lynx-js/devtool-connector/transport、および @lynx-js/devtool-connector/streams のすべてを再エクスポートし、デーモン専用の createDefaultTransports() と createDefaultConnector() ヘルパーも提供します。これらの ヘルパーは 1 つの DaemonTransport を使用するため、独立したスクリプト間でデーモンが 所有するデバイス接続を共有できます。デーモンを使用しない経路を意図的にテストする場合に 限り、トランスポートを明示して Connector を構築してください。

オンライン CLI コマンドは、デフォルトで同じくデーモンのみを使用します。--no-daemon は、 その呼び出しに限り、デーモンを Android、iOS、および Desktop の直接トランスポートに置き換える 明示的なオプションです。ADB_SERVER_HOST と ADB_SERVER_PORT は、この直接モードのみを 設定します。デーモンモードでは無視され、stderr に警告が出力されます。

通常、agent-lynx CLI は PATH 上で利用できます。command -v agent-lynx が失敗する場合は、 代わりに npx を使用してください。

npx --yes agent-lynx <command>

この公開スキルには、ローカル CLI エントリースクリプトは含まれていません。次を使用してください。

agent-lynx <command>

注記： ほとんどのコマンド出力は JSON です。jq または Node.js を使用してデータを処理できます。

組み込みスキルを見つける

インストール済みの @lynx-js/skill-lynx-devtool 依存パッケージには、 lynx-devtool スキルが含まれています。次のコマンドでスキルを見つけるか、手順全体を読み込めます。

agent-lynx skills list
agent-lynx skills get lynx-devtool

skills list は、各スキルの名前と説明を、そのパッケージの SKILL.md の YAML フロントマターから直接読み取ります。skills get は、選択した Markdown 本文を返し、 references/、assets/、および examples/ ディレクトリが存在する場合は、その下にある通常ファイルを 再帰的に一覧表示します。シンボリックリンクとビルド出力は含まれません。安定した名前は lynx-devtool です。

スナップショットのワークフロー

agent-lynx snapshot
agent-lynx tap @e3 --snapshot
agent-lynx fill @e1 "Alice"
agent-lynx clear @e1
agent-lynx scroll @e2 --direction down
agent-lynx get text @e3
agent-lynx get style @e3 --property color,width
agent-lynx wait --text Ready
agent-lynx screenshot --annotate -o page.jpeg

スナップショットの参照は、CLI の呼び出しをまたいでデーモンのメモリに保持されます。 snapshot、tap、long-press、fill、clear、scroll、 get text、get style、wait、または screenshot に --no-daemon を渡さないでください。 wait はデーモンの SSE コマンドルートを使用し、それ以外のスナップショットコマンドは POST /command/<action> を使用します。

screenshot --annotate はスナップショット参照を更新してキャッシュし、番号付きラベルを 1 枚の JPEG に 直接描画します。ラベル [N] は参照 @eN に対応するため、エージェントは画像を確認して、対応する参照を すぐに使用できます。画像には、表示されている参照のうち、アクション可能なものが絞り込まれて表示されます。 対象への直接操作、編集可能なフィールド、明示的なテスト対象、およびスクロールコンテナーが対象です。 一般的なレイアウトやテキストの参照は、画像が煩雑にならないよう、キャッシュ済みスナップショット内で引き続き 利用できます。ビューポートと同じサイズのスクロールコンテナーには、フレーム全体の境界線ではなく、角のバッジが 表示されます。--json を指定すると、結果には同じ ActionCore 呼び出しで使用された最新のスナップショット全体も 含まれるため、2 回目の更新を行わずに画像と参照を比較できます。ピクセルの対応付けには、スナップショットの ビューポートに挿入領域がある可能性を考慮して、スクリーンキャストフレームの論理サイズのメタデータを別途使用します。 このメタデータが利用できない場合、コマンドは推測せずに失敗します。--annotate と --fullscreen は 組み合わせないでください。代わりに、注釈なしの screenshot --fullscreen または従来の take-screenshot --fullscreen コマンドを使用してください。注釈付きスクリーンショットのリファレンスを参照してください。

プログラムからコネクターをインポートするには、プロジェクトの依存関係が必要です。

npm install agent-lynx

このプロジェクト内へのインストールが必要なのはコネクターのワークフローのみです。PATH 上の agent-lynx CLI または npx を使用する CLI のみの利用には必要ありません。

ライブラリとして使用する

シェルから CLI を実行する代わりに、JavaScript から Lynx DevTool を直接操作する場合は、agent-lynx/connector からインポートしてください。

import { Connector, createDefaultConnector } from "agent-lynx/connector";

const connector = createDefaultConnector();
const clients = await connector.listClients();

console.log(clients);

より詳細なプログラムによるワークフローについては、ライブラリ使用リファレンス と プログラムによるデバッグの例 をご覧ください。

カスタムの非デーモン型トランスポートが必要な場合は、コネクターを手動で構築することもできます。

import {
  AndroidTransport,
  Connector,
  DesktopTransport,
  iOSTransport,
} from "agent-lynx/connector";

const connector = new Connector([
  new AndroidTransport({ host: "127.0.0.1", port: 5037 }),
  new DesktopTransport(),
  new iOSTransport(),
]);

グローバルオプション

• -h, --help：コマンドのヘルプを表示します。
• --no-daemon：共有デーモンを介さず、この呼び出しではデバイスへの直接トランスポートを使用します。同じ DebugRouter ターゲットへの接続をデーモンが所有している可能性がある場合は、先にデーモンを停止してください。

注： 各サブコマンドは --help フラグに対応しています（例：agent-lynx cdp --help）。使用可能な引数とその説明の全一覧を確認するには、このフラグを使用してください。

コマンド

1. クライアント一覧

使用可能なすべての Lynx クライアント（DevTool が有効なアプリ）を一覧表示します。

agent-lynx list-clients

2. クライアントを待機

クライアントが使用可能になるまで待機します。

agent-lynx wait-for-client --client-name com.lynx.uiapp

• --client-name <name>：待機するパッケージ名またはアプリ名を指定します（省略可）。AppProcessName、bundleId、bundleName、または App と照合します。一致するクライアントが複数ある場合は、一致したすべてのクライアントが返されます。省略した場合は、最初に使用可能になったクライアントが返されます。出力は常に JSON 配列です。
• --timeout <seconds>：待機する最大秒数です。既定値は 30 です。
• --interval <seconds>：検出を試みる間隔を秒数で指定します。既定値は 1 です。

3. セッション一覧

アクティブなデバッグセッションをすべて一覧表示します。セッションは、特定の Lynx ビューまたはコンテキストに対応します。

agent-lynx list-sessions
# Optional: Filter by client ID
agent-lynx list-sessions --client <clientId>

4. CDP コマンドを送信

特定のセッションに Chrome DevTools Protocol（CDP）コマンドを送信します。

Lynx は標準 CDP コマンドの一部のみをサポートしている点に注意してください。 LynxView に関する注意：対象のセッションが LynxView の場合、CDP コマンドを送信する前に、サポートされている CDP メソッドを必ず確認してください。 WebView に関する注意：対象のセッションが WebView（例：type: "web" または HTTP/HTTPS URL）の場合は、CDP メソッド名、パラメーター、事前に有効化が必要な項目について、標準の Chrome DevTools Protocol ドキュメントを参照してください。ローカルの references/cdp ページは LynxView のサポートと Lynx 固有の拡張機能を中心に扱っており、WebView の対象では method not found が返される場合があります。

agent-lynx cdp -m <method> [options] [params]

• -m, --method <method>：CDP メソッド名です（例：DOM.getDocument、Page.reload）。
• -c, --client <clientId>：（省略可）クライアント ID です。省略した場合は、最初に使用可能なクライアントを使用します。
• -s, --session <sessionId>：（省略可）セッション ID です。省略した場合は、最新のセッション（セッション ID が最大のもの）を使用します。
• --thread <thread>：（省略可）対象の VM スレッドを background または main で指定します。既定値は background です。
• [params]：（省略可）コマンドのパラメーターを指定する JSON 文字列です。

--thread main を使用する場合、サポートされるのは Debugger.*、Runtime.*、HeapProfiler.*、および Profiler.* メソッドのみです。

例：

# Get the document root
agent-lynx cdp -m DOM.getDocument

5. JavaScript を評価する

JavaScript 式を評価します。バックグラウンド VM では、現在のアプリの lynx オブジェクトと nativeLynx オブジェクトがローカル変数として利用できます。メイン VM を対象とする式はそのまま送信されます。

agent-lynx evaluate 'JSON.stringify(lynx.__globalProps)'
agent-lynx evaluate '2 + 2' --thread main
agent-lynx evaluate 'lynx' --no-return-by-value

• <expression>: 評価する JavaScript 式。
• -c, --client <clientId>: (任意) クライアント ID。
• -s, --session <sessionId>: (任意) セッション ID。
• --thread <thread>: (任意) 対象の VM スレッド、background または main。デフォルトは background です。lynx と nativeLynx を公開するためにラップされるのはバックグラウンドの式のみで、メインスレッドの式はそのまま送信されます。
• このコマンドはデフォルトで値による結果を要求します。returnByValue をサポートするエンジンは、通常の JSON ライクなオブジェクトを result.value にシリアライズします。現在の Android Lynx ランタイムでは、オブジェクト値に対してこれを無視し、引き続き objectId を返す場合があります。JSON 出力が必要な場合は JSON.stringify(lynx.__globalProps) を使用してください。後で Runtime.getProperties や Runtime.callFunctionOn リクエストに使用するために、意図的に objectId を受け取るには --no-return-by-value を使用します。--return-by-value はデフォルトの明示的な形式として引き続き受け付けられます。
• --silent、--context-id、--throw-on-side-effect、--generate-preview、--object-group、--await-promise、--include-command-line-api: 任意の評価パラメータ。エンジンのサポート状況は異なります。

6. アプリコマンドを送信する

アプリレベルのコマンドを送信します。

agent-lynx app -m <method> [options] [params]

• -m, --method <method>: アプリのメソッド名 (例: App.openPage)。
• -c, --client <clientId>: (任意) クライアント ID。
• [params]: (任意) パラメータの JSON 文字列。

アプリコマンドを送信する前に、必ず サポートされているアプリメソッド をお読みください。

7. URL を開く

Lynx アプリで特定の URL を開きます。

agent-lynx open <url> [options]

• <url>: 開く URL。
• -c, --client <clientId>: (任意) クライアント ID。

例:

agent-lynx open "lynx://example/page"

8. コンソールを取得する

デバイスからコンソールログをキャプチャします。

agent-lynx get-console [options]

• -c, --client <clientId>: (任意) クライアント ID。
• -s, --session <sessionId>: (任意) セッション ID。
• --offset <number>: N 件のメッセージをスキップします。
• --limit <number>: メッセージ数を制限します。
• --include-stack-traces: エラー以外のメッセージにスタックトレースを含めます。
• --level <levels>: ログレベルをフィルタリングします (例: error,warning)。
• --thread <thread...>: 対象の VM スレッド: background または main。省略した場合、デフォルトで両方のスレッドが収集されます。

9. ソースを取得する

パースされたすべてのスクリプトを一覧表示します。これは、他のコマンド (例: Debugger.getScriptSource) で使用するスクリプト ID を見つけるのに便利です。このコマンドは、現在ロードされているすべてのスクリプトを自動的に取得します。

agent-lynx get-sources [options]

• -c, --client <clientId>: (任意) クライアント ID。
• -s, --session <sessionId>: (任意) セッション ID。

10. 検査する

クライアント/セッションのペアに対してコネクタデーモンが提供する DevTool インスペクタ URL を出力します。出力された URL をブラウザで開くと、CLI が対象とするのと同じセッションにグラフィカルインスペクタを接続できます。

agent-lynx inspect [options]

• -c, --client <clientId>: (任意) クライアント ID。
• -s, --session <sessionId>: (任意) セッション ID。
• --port <port>: (任意) デーモンポート。デフォルトは 21783 です。

11. エージェントスクリーンショット

ActionCore を通じてキャプチャし、オプションで新しいスナップショットの参照を結果の JPEG に直接描画します。

agent-lynx screenshot [options]

• -c, --client <clientId>: (任意) クライアント ID。
• -s, --session <sessionId>: (任意) セッション ID。
• --annotate: (任意) 参照を更新し、[N] ラベルを描画します。ここで [N] は @eN に対応します。
• --fullscreen: (任意) LynxView の代わりにフルスクリーンでキャプチャします。--annotate と組み合わせることはできません。
• -o, --output <path>: (任意) JPEG の出力パス。
• --json: (任意) パス、画像の寸法、完全な最新スナップショット、および注釈メタデータを返します。

このコマンドには常駐デーモンが必要です。単一画像の出力契約と対象の制限については、注釈付きスクリーンショットリファレンス を参照してください。

12. レガシー・スクリーンショット撮影

Agent-Lynx 以前のコマンドを使用して、現在のページのスクリーンショットを直接撮影します。

agent-lynx take-screenshot [options]

• -c, --client <clientId>: (任意) クライアント ID。
• -s, --session <sessionId>: (任意) セッション ID。
• --fullscreen: (任意) スクリーンショットを fullscreen モードでキャプチャします。指定しない場合は lynxview モードがデフォルトになります。
• -o, --output <path>: (任意) 出力ファイルパス。

13. コンテンツ・スクリーンショット撮影

CSS セレクターに一致する最初のノードのスクロール可能なコンテンツ全体をキャプチャします。

agent-lynx take-content-screenshot --selector <selector> [options]

• --selector <selector>: scroll-view または互換性のある list の CSS セレクター。必須です。
• --format <jpeg|png>: (任意) 画像フォーマット。デフォルトは jpeg です。
• --scale <number>: (任意) 正の出力スケール。デフォルトは 1 です。
• -c, --client <clientId>: (任意) クライアント ID。
• -s, --session <sessionId>: (任意) セッション ID。
• -o, --output <path>: (任意) 出力ファイルパス。

takeContentScreenshot は scroll-view に対して公式に定義されています。このコマンドは任意の CSS セレクターを受け付けるため、list に同じメソッドを公開するランタイムでも使用できます。サポートされていないノードは UI Method failure を返します。

動作と例については、Take Content Screenshot リファレンスを参照してください。

14. グローバルスイッチ

DevTool のグローバルスイッチを管理します。

# List all supported keys and their current values
agent-lynx global-switch list [options]

# Get one key
agent-lynx global-switch get --key <globalKey> [options]

# Set one key
agent-lynx global-switch set --key <globalKey> --status <on|off> [options]

• -c, --client <clientId>: (任意) クライアント ID。

global-switch list のオプション:

• --fail-fast: 最初のキー読み取り失敗で中止します。

global-switch get のオプション:

• --key <globalKey>: グローバルスイッチキー。(必須)

global-switch set のオプション:

• --key <globalKey>: グローバルスイッチキー。(必須)
• --status <on|off>: 対象のスイッチステータス。(必須)

キーの完全なリストと例については、Global Switch リファレンスを参照してください。

15. ヒープスナップショット撮影

現在の Lynx セッションから QuickJS ヒープスナップショットをキャプチャし、.heapsnapshot ファイルとして保存します。

agent-lynx take-heap-snapshot [options]

• -c, --client <clientId>: (任意) クライアント ID。
• -s, --session <sessionId>: (任意) セッション ID。
• --thread <thread>: (任意) 対象の VM スレッド、background または main。デフォルトは background です。
• -o, --output <path>: (任意) 出力ファイルパス。デフォルトは OS の一時ディレクトリです。

16. グローバルメモリ使用量のクエリ

グローバルな Memory.* CDP ドメインを通じて Lynx のグローバルメモリ使用量をクエリします。汎用の cdp コマンドを使用し、セッション ID -1 を指定してグローバル DevTool ハンドラーにリクエストを送信します。

# Get global Lynx memory usage across live instances
agent-lynx cdp -s -1 -m Memory.getAllMemoryUsage
agent-lynx cdp -s -1 -m Memory.getAllMemoryUsage '{"timeoutMs":50000}'

• -c, --client <clientId>: (任意) クライアント ID。
• -s, --session <sessionId>: CDP セッション ID。プラットフォーム固有の理由で上書きする必要がない限り、グローバル DevTool ハンドラーには -1 を使用します。
• params.timeoutMs (任意): ミリ秒単位の非負のタイムアウト。最大値は 300000 です。

このコマンドは生の Memory.getAllMemoryUsage JSON を出力します。CLI 出力に派生フィールドである summary、topMemoryItems、topInstances のラッパーが含まれることは期待しないでください。

DevTool MCP サーバーが利用可能な場合、CLI を呼び出す代わりに、同じ生のペイロードを取得する Memory_getAllMemoryUsage MCP ツールを優先してください。

エージェント側のレポート標準:

1. ユーザーがキャプチャを要求した場合、または結果が大きすぎてインラインで表示できない場合は、完全な生の JSON をファイルに保存します。
2. バイナリ単位(KiB、MiB、GiB)を小数点以下 2 桁で使用します。ratioToApp と寄与率は小数点以下 2 桁のパーセンテージとして表示します。
3. 最初に次の固定サマリーを報告します:
   • collectionStatus
   • ${completedInstanceCount}/${expectedInstanceCount} Lynx インスタンス
   • totalBytes
   • appBytes
   • ratioToApp
   • elementNodeCount
   • viewBytes
   • mainThreadRuntimeBytes
   • backgroundThreadRuntimeBytes
4. 次に、各 instances[] エントリの詳細な候補項目を使用して「メモリ寄与度トップ 5」を報告します:
   • instances[i].backgroundThreadRuntimeBytes
   • instances[i].mainThreadRuntimeBytes
   • instances[i].elementBytes
   • 各 instances[i].viewDetail[category].sizeBytes
   • instances[i].viewBytes が viewDetail[*].sizeBytes の合計より大きい場合は、残りの分を other view memory 項目として含めます。
5. トップ 5 の寄与項目をバイト数の降順で並べ替えます。各行には、順位、項目の種類/カテゴリ、サイズ、% of totalBytes、% of instance.totalBytes、instanceId、URL を含めます。
6. 次に、instance.totalBytes の降順で並べ替えた「インスタンス」を報告します。各インスタンスには、instanceId、URL、totalBytes、mainThreadRuntimeBytes、backgroundThreadRuntimeBytes、viewBytes、elementBytes、および image=12 / 4.15 MiB のような簡潔な viewDetail サマリーを含めます。
7. 存在しないフィールドをでっち上げないでください。viewDetail が空である場合、またはカテゴリのバイト数が 0 の場合は、そのまま明記してください。現在の CDP ペイロードは、ネストされた子 LynxView オブジェクトツリーを公開していません。

Memory.getAllMemoryUsage は Runtime.getHeapUsage とは異なります。これは、存続している登録済み Lynx インスタンス全体にわたるグローバルな Lynx 帰属メモリスナップショットを返し、element、view、メインスレッドランタイム、バックグラウンドランタイム、アプリのフットプリント、インスタンスごとの内訳を含みます。現在の CDP ペイロードは、ネストされた子 LynxView メモリツリーを別途公開していません。viewDetail は UI ビューのカテゴリまたはタグごとに集計されます。レスポンスの完全な形状については、Memory CDP メソッドを参照してください。

17. 記録

TestBench(CDP ベース)を通じて Lynx ページの操作を記録します。すべてのアクション(テンプレートの読み込み、タッチイベント、JS モジュール呼び出し、データ更新)をキャプチャし、JSON リプレイファイルを生成します。

# Start recording (BEFORE opening the target page)
agent-lynx recorder start [options]

# Stop recording and save the replay file
agent-lynx recorder end [options]

• -c, --client <clientId>: (任意) start および end 用のクライアント ID。
• -o, --output <path>: (任意) end 用の出力ファイルまたはディレクトリパス。デフォルトは ~/.lynx-devtool/files/lynxrecorder/recording-<clientId>-<timestamp>.json です。

ワークフロー:

1. recorder start を実行します。enable_debug_mode が有効になった場合は、アプリを再起動して recorder start を再度実行します。
2. ユーザーが Lynx ページを開いて操作します。
3. recorder end --output <file.json> を実行して停止し、保存します。
4. 絶対ファイルパスをユーザーに報告します。

重要: リプレイ可能なファイルにするには、recorder start の後にターゲットページを開くか再読み込みして、記録に loadTemplate が含まれるようにしてください。

詳細については、記録リファレンスを参照してください。

18. パフォーマンストレースの記録

圧縮された Lynx パフォーマンストレースを記録し、.pftrace ファイルとして保存します。 対象ページをビルドまたは開く前にトレースを開始すると、キャプチャに最初のフレームが含まれます。

# Discover the client first; keep the same ID throughout the workflow.
agent-lynx list-clients

# Start before opening the target page.
agent-lynx trace start --client <clientId>

# Open and interact with the page, then stop and capture the stream handle.
agent-lynx trace end --client <clientId>

# Download the handle returned by trace end.
agent-lynx trace read-data --client <clientId> --stream <handle> -o ./my-trace.pftrace

# Inspect the downloaded file locally without a device or daemon.
agent-lynx trace event-summary ./my-trace.pftrace
agent-lynx trace query ./my-trace.pftrace \
  --sql "SELECT name, COUNT(*) AS count FROM slice GROUP BY name"

• -c, --client <clientId>: （任意）クライアント ID。複数のクライアントが接続されている場合は、それらを一覧表示し、1 つを明示的に選択します。
• trace start --no-systrace: systrace を無効にします。デフォルトでは有効です。
• trace start --include-categories <categories> / --exclude-categories <categories>: カンマ区切りのトレースカテゴリを含めるか除外します。
• trace start --enable-memory-trace: メモリデータ収集を有効にします。
• trace start --no-force-gc: デフォルトで有効になっている自動ガベージコレクションを無効にします。
• trace start --enable-auto-heap-snapshot: shared-group VM の自動ヒープスナップショットをキャプチャします。--shared-group-id <id> を追加して 1 つの VM を選択します。
• trace start --js-profile-interval <interval>: JS サンプリング間隔。プロファイリングが有効で、指定した間隔が 0 または -1 の場合は 100 がデフォルトになります。それ以外の場合は -1 がデフォルトになります。
• trace start --js-profile-type <quickjs|v8>: 選択した JS ランタイムのプロファイリングを有効にします。このオプションを省略すると、プロファイリングは無効になります。
• trace end --timeout <seconds>: Tracing.tracingComplete を待機する時間。デフォルトは 30 です。
• trace read-data --stream <handle>: trace end によって返される数値のストリームハンドル。
• trace read-data -o, --output <path>: 出力パス。デフォルトでは、OS の一時ディレクトリにタイムスタンプ付きの .pftrace が作成されます。
• trace read-data --timeout <seconds>: ダウンロードの合計タイムアウト。デフォルトは 30 です。
• trace event-summary <trace>: すべての Perfetto slice.name とその出現回数を、回数の降順で出力します。構造化された証拠を取得するには --json を追加し、ファイルに書き込むには -o, --output <path> を追加します。
• trace query <trace> --sql <query>: インラインの Perfetto SQL を実行し、JSON を出力します。
• trace query <trace> --sql-file <path>: ファイルから SQL を実行します。--sql と --sql-file のいずれか 1 つのみを使用してください。--max-rows のデフォルトは 1000 です。

trace query と trace event-summary はローカルのオフラインコマンドです。デバイスに接続したり、デーモンを起動したり、コネクタトランスポートを作成したりすることはありません。それらの JSON には、トレースの絶対パス、バイト長、SHA-256 が含まれるため、エージェントは検査したファイルを証明できます。SQL の bigint 値は 10 進数の文字列であり、blob は { "base64": "..." } オブジェクトです。

Android では、最初の trace start で enable_debug_mode が有効になり、アプリの再起動を求められる場合があります。アプリを再起動し、ページを開く前に再度 trace start を実行してください。トレースをサポートしていないランタイムでは、Android の local_test ビルドまたは iOS の Lynx Profile ビルドが必要です。完全なワークフローとトラブルシューティングについては、Performance Trace Reference を参照してください。

19. ReactLynx コンポーネントツリー

実行中の ReactLynx ページのコンポーネントツリーを、@lynx-js/preact-devtools からデコードして出力します。CLI はコネクタデーモンの ReactLynx ActionCore を呼び出します。デーモンは Lynx.onVMEvent ストリーム、init+refresh ハンドシェイク、operation_v2 のデコード、およびセッションごとのコンポーネントキャッシュを管理します。CLI は返されたツリーをレンダリングするだけです。

agent-lynx reactlynx tree [options]

• -c, --client <clientId>: (任意) クライアント ID。
• -s, --session <sessionId>: (任意) セッション ID。
• --depth <n>: (任意) 出力するツリーの最大深さ。デフォルト: 無制限。
• --show-shells: ReactLynx が挿入する合成の Fragment / Root / Anonymous ラッパーを含めます。これらはデフォルトでは非表示です。
• --json: ASCII の代わりに { labels, roots, nodes } を出力します。スクリプトがツリーを消費する場合に使用します。

出力は @cN [type] Name 形式の参照を使用します（agent-react-devtools の規約です）。ラベルは可視のルートに対する先行順 DFS です。reactlynx tree は常に新しい世代をキャプチャし、--depth を含め、出力した正確なラベルビューをキャッシュします。その後 component @cN および update-* @cN 呼び出しは、独立した CLI 呼び出しをまたいでそのビューを再利用します。コンパクトおよび --show-shells のラベルビューは別々にキャッシュされます。

@c1 [fn] App
├─ @c2 [fn] Header
│  └─ @c3 [fn] Logo
└─ @c4 [fn] Body

要件:

• ReactLynx コマンドにはコネクタデーモンが必要です。--no-daemon と組み合わせないでください。
• ページは @lynx-js/preact-devtools を実行している dev ビルド である必要があります（本番バンドルでは setupReactLynx() が除去されます）。初期化に成功すると、デバイスコンソールに [PREACT DEVTOOLS] Devtools initialized successfully が出力されます。
• @lynx-js/preact-devtools には document.body および preactDevtoolsCtx.Node の修正（lynx-family/preact-devtools に対する PR #2 + PR #5）が含まれている必要があります。これらがないと、refresh チャネルは operation_v2 フレームを 0 個返し、CLI は「stale preact-devtools」の診断を出力します。

ツリーが空で返された場合、CLI は終了コード 1 で終了し、stderr に 3 つの的を絞った診断のいずれかを書き込みます:

• saw 0 frames: PreactDevtools チャネルで何も応答しませんでした。アプリに @lynx-js/preact-devtools がない、本番ビルドである、setupReactLynx() がまだ完了していない、または誤った --session を選択した可能性が高いです。
• saw N frames but no operation_v2: フックはロードされていますが、その refresh ハンドラーにバグがあります。@lynx-js/preact-devtools を PR #2 と #5 を含むビルドにアップグレードしてください。
• tree is empty: コミット間ですべてのノードがアンマウントされました -- まれなケースです。DEBUG（下記）を付けて再実行し、生のエンベロープを確認してください。

詳細なデバッグには、DEBUG=devtool-mcp-server:reactlynx を設定すると、すべての PreactDevtools フレーム（type + payload サイズ）を stderr にログ出力しつつ、stdout（ツリー / JSON）をクリーンに保ちます:

DEBUG='devtool-mcp-server:reactlynx' agent-lynx reactlynx tree
# 2026-05-25T... devtool-mcp-server:reactlynx frame 1: type=operation_v2 dataSize=54
# 2026-05-25T... devtool-mcp-server:reactlynx frame 2: type=operation_v2 dataSize=756
# 2026-05-25T... devtool-mcp-server:reactlynx frame 3: type=root-order dataSize=1
# 2026-05-25T... devtool-mcp-server:reactlynx frame 4: type=root-order-page dataSize=object

20. ReactLynx コンポーネントのインスペクト

Preact DevTools の inspect エンベロープを送信し、inspect-result を読み戻すことで、単一の ReactLynx コンポーネント (props / state / hooks / context / signals) をインスペクトします。

agent-lynx reactlynx component <ref> [options]

• <ref>: reactlynx tree / reactlynx find が生成したラベル @cN、または数値の vnode id のいずれかです。
  • @cN の場合、デーモンは最新の一致するラベルビューに対してラベルを解決します。キャッシュミス時にはツリーを一度キャプチャします。ラベルがシェルを表示した状態で生成された場合に限り、--show-shells を渡してください。
  • 数値 id (例: 3856353762) の場合、コンポーネントキャッシュはバイパスされます。
• -c, --client <clientId>, -s, --session <sessionId>: (任意) 標準のターゲティングフラグです。
• --show-shells: @cN を解決する際に、reactlynx tree --show-shells と同じ方法で合成 Fragment / Root / Anonymous ラッパーをカウントします。
• --refresh: @cN を解決する前に、新しい完全なツリーをキャプチャします。数値 id に対しては効果がありません。
• --json: 生の InspectData ペイロードを JSON として出力します。デフォルトの出力はコンパクトな ASCII サマリーです。

出力例:

@c5 (id=3856353783) [fn] TUXIntroViewListCell key=1. HMR
  source: src/TUXIntroViewListCell.tsx:42:3
  props:
    {
      "title": "1. HMR",
      "icon": { "type": "vnode", "name": "TUXIcon" }
    }

複雑な値は上流の serialize.ts によってタグ付けされます -- { "type": "function", "name": "..." }、{ "type": "vnode", "name": "..." }、{ "type": "signal", "value": ... }、{ "type": "map", "entries": [...] } などです。完全なスキーマについては serialize.ts を参照してください。

App が inspect-result を返信できない場合、デーモンはそのセッションの ReactLynx キャッシュを削除し、CLI はコード 1 で終了します。再試行する前に reactlynx tree を実行してください。同じ DEBUG=devtool-mcp-server:reactlynx 名前空間がすべてのフレームをトレースします。

21. ReactLynx コンポーネントの検索

名前が部分文字列または正規表現に一致するすべてのコンポーネントを検索します。出力は reactlynx tree (先行順 DFS) とまったく同じ順序で並ぶため、@cN ラベルは他のサブコマンドと相互にやり取りできます。

agent-lynx reactlynx find <pattern> [options]

• <pattern>: 部分文字列 (デフォルト、大文字と小文字を区別しない)、または --regex を指定した場合は JavaScript 正規表現です。
• -c, --client <clientId>, -s, --session <sessionId>: (任意) 標準のターゲティングフラグです。
• --regex: <pattern> を JavaScript 正規表現として扱います (例: --regex '^Toast(List)?$')。
• --show-shells: 合成 Fragment / Root / Anonymous ラッパーを含めます。
• --refresh: 検索前に新しいコンポーネントの世代をキャプチャします。指定しない場合、find はデーモンキャッシュを再利用します (キャッシュミス時には一度キャプチャします)。
• --limit <n>: 出力する一致数の上限です。デフォルトは 50 です。
• --json: スクリプトによる後処理のために [{ label, id, name, type, key, ancestors: [{label, name}] }, ...] を出力します。

出力例:

@c8 [fn] TUXCenterToastActivator
  in @c1 TUXApp > @c2 Provider > @c3 App
@c10 [fn] TUXTopToastActivator
  in @c1 TUXApp > @c2 Provider > @c3 App

reactlynx find は、ツリーが大きすぎて目視で確認できない場合に、後続の reactlynx component @cN 呼び出し用のラベルを発見するための推奨される方法です。検索が成功すると、その完全な深さのラベルビューが、選択されたシェルモードの最新ビューとして公開されます。

22. ReactLynx 要素/コンポーネントリンク

最新のデーモンキャッシュ済み DOM スナップショットと、デーモンキャッシュ済みの ReactLynx コンポーネントツリーとの間の、1 つの厳密な関係を解決します:

# Snapshot element -> nearest surfaced ReactLynx component
agent-lynx snapshot
agent-lynx reactlynx link @e7

# ReactLynx component -> first host element in the latest Snapshot
agent-lynx reactlynx tree
agent-lynx reactlynx link @c8

このコマンドは @cN の代わりに数値の Preact VNode id も受け付け、--json、--show-shells、--refresh をサポートします。デフォルトでは、選択されたシェルモードに対して最新のコンポーネント世代と正確なラベルビューを再利用します。コンポーネントキャッシュのミス時には、1 つの世代をキャプチャします。--refresh は、関係を解決する前にコンポーネント世代を明示的に置き換えます。

これは Lynx の nodeId / ReactLynx の uniqueId による厳密な同一性ルックアップであり、座標、テキスト、ツリー位置によるマッチングにフォールバックすることは決してありません。既存の App 側の element-picked および highlight プロトコルを使用するため、App には互換性のある @lynx-js/preact-devtools の開発ビルドが含まれている必要があります。JSON は完全なスナップショット参照、コンポーネントの label/id/type/name/key、およびコンポーネントキャッシュ世代を返します。

このコマンドは DOM スナップショットを意図的に更新しません。更新すると、ユーザーが関連付けようとしている @eN 参照が暗黙的に無効化されてしまうためです。まず agent-lynx snapshot を実行し、デーモンが参照の欠落または古さを報告した場合は明示的に再実行してください。コンポーネントから要素へのルックアップは、Preact DevTools が公開する最初のホスト要素を返します。要素からコンポーネントへのルックアップは、最も近い表面化されたコンポーネントを返します。したがって、複数のホスト要素をレンダリングするコンポーネントに対して、これらの方向が全単射を形成することは保証されません。

23. ReactLynx コンポーネント更新

1 つのフィールドを変更し、アプリ側アダプターの更新後 inspect-result 確認を待機します:

agent-lynx reactlynx update-prop <ref> <path> <value> [options]
agent-lynx reactlynx update-state <ref> <path> <value> [options]
agent-lynx reactlynx update-context <ref> <path> <value> [options]

• <ref> は reactlynx component と同じキャッシュ済み @cN または数値の vnode-id の規則に従います。
• <path> は選択された props/state/context オブジェクトから始まります。例えば count、user.name、items.0.title などです。root.、props.、state.、context. を先頭に付けないでください。
• <value> は JSON として解析されます。文字列 JSON はシェル用にクォートするか、--raw を渡して引数を文字列としてそのまま送信してください。
• --show-shells はシェルを含むラベルビューを選択します。--refresh は @cN を解決する前に新しいツリーをキャプチャします。
• --json は更新後の生の InspectData 確認を出力します。

デーモンは同じクライアント/セッションの ReactLynx 操作を直列化するため、ブロードキャストされる Preact VM イベントが同時実行されるコマンド間で混信することはありません。異なるセッションは並行して進めることができます。キャッシュはライブサブスクリプションではなく世代ベースです。tree と明示的な --refresh はキャッシュを置き換え、find はデフォルトでキャッシュを再利用し、キャッシュされた inspect/update が失敗するとキャッシュを破棄します。