argent-vega

Argent Vega（Amazon Fire TV）

重要

• Vega は TV プラットフォームです
• D パッドのみを使用してください。 すべての操作は tv-remote で行ってください。Vega ではサポートされていないため、gesture-* やタッチ操作は使用しないでください。
• 移動する前に必ず describe を実行してください。 ツリーから現在のカーソルを確認します。[focused] の要素、または [focused] が報告されない場合は [selected] の要素を確認してください（ツールキットでは、focused が false のまま、強調表示された項目に [selected] が付くことがよくあります）。スクリーンショットからフォーカス位置を推測しないでください。
• すべてのツールには、Vega の serial（list-devices から取得）を udid として指定します。

ナビゲーションのループ

各画面で、2 回呼び出します。

1. describe — カーソル（[focused]、または [focused] がなければ [selected]）と目的の項目を確認します。
2. フォーカスから目的の項目までの D パッドの経路全体を計算し（フレームから行と列を数えます）、select で終わる経路を 1 回の tv-remote {button:[...]} で実行します。

その後、もう一度 describe を実行して確認します。目的の項目に移動できなかった場合は、ループをもう一度実行します。

ツール

デバイスのライフサイクル

• list-devices → Vega デバイスには serial（udid として使用）と vvdImage が表示されます。まずこれを実行して両方を取得します。
• boot-device {vvdImage} — SDK 管理下の単一の VVD（例：vvdImage:"tv"）を起動し、serial を返します。list-devices にすでに実行中のデバイスが表示されている場合は不要です。
• VVD の停止 — シェルで vega virtual-device stop を実行します。注意：CLI が追跡するのは、フォアグラウンドで起動した VVD のみです。そのため、boot-device で起動した VVD に対しては「virtual device not running」と報告され、停止できないことがあります。その VVD を再起動するには、boot-device {vvdImage, force: true} を実行します。これにより、実行中の VVD プロセスを停止してから再起動します。

アプリのライフサイクル

• launch-app {udid, bundleId} — bundleId = manifest.toml のインタラクティブコンポーネントのアプリ ID（例：com.example.app.main）
• restart-app {udid, bundleId} — 終了してから起動します
• reinstall-app {udid, bundleId, appPath} — アンインストールしてからインストールします。appPath = .vpkg
• describe {udid} → 画面上の要素ツリーです。移動前に呼び出す、要素の検出ツールです
• tv-remote {udid, button} — D パッド操作です。単一キー、経路配列、または repeat を指定します
• keyboard {udid, text} または {udid, key:"enter"} — 先に D パッドでフィールドにフォーカスします
• screenshot {udid, scale?} — adb を介してホスト側でキャプチャします

describe

デバイス上の自動化ツールキットから取得した、入れ子になった要素ツリーです。各行には button／text／image、ラベル、id（test_id）、[clickable]、[focused]／[selected]、正規化された [0,1] のフレームが表示されます。[focused] がある場合は、現在の D パッドカーソルを示します。実際には、ツールキットは focused を false のままにして、強調表示された項目に [selected] を付けることが多いため、[focused] を報告する要素がない場合は [selected] をカーソルとして扱ってください。ツリーだけを基準に操作してください。ツリーが空の場合は、restart-app を実行して再試行します。

tv-remote

button には、単一キー または経路全体 を指定できます。キー：up／down／left／right、select、back、home、menu、playPause、rewind、fastForward。単一キー：{button:"down"}。キーを繰り返す場合：{button:"down", repeat:3}。経路全体を 1 回で実行する場合：{button:["up","right","right","select"]} — 複数手順の移動では、こちらを強く推奨します。

Fast Refresh

Debug ビルドと Metro の実行が必要です。argent は Metro に接続するだけで、Metro の起動やポートフォワーディングは行いません（どのプラットフォームでも同様です）。これらはシェルで実行してください。

1. Debug .vpkg をビルドしてインストールします：vega device install-app -p <path/to/debug.vpkg>
2. npm start（Metro を :8081 で起動します。npx react-native start ではなく npm start を使用してください）
3. vega device start-port-forwarding --port 8081 --forward false（リバース）
4. vega device launch-app -a <appId>

起動前に Metro が実行されている必要があります。http://localhost:8081/json/list に Hermes React Native ターゲットが表示されることを確認してください。その後、.tsx の編集内容がライブでホットリロードされます。

トラブルシューティング

• describe が空のツリーを返す → restart-app を実行します（自動化ツールキットは起動時に接続します）。その後、もう一度試してください。
• キーボード／D-pad の入力が無視される → VVD 内で開発者モードを有効にします：vsm developer-mode enable。
• node_modules を編集しても反映されない → Release ビルドを使用しています。Release ビルドの Vega アプリは JavaScript とネイティブコードを分割してデバイス上に保存するため、node_modules のパッチが機能するのは Debug ビルドのみです。

プラットフォームに関する注意事項

• Metro はポート 8081 にのみ接続します。固定されており、変更できません。
• プロファイリング／クラッシュ → amazon-devices-buildertools-mcp サーバー（analyze_perfetto_traces、get_app_hot_functions、symbolicate_acr）を使用してください。
• サポート対象外のツールと Vega での代替手段：gesture-* → tv-remote を使用します。open-url → 接続されていません。debugger-* → Vega では JS デバッガーはサポートされていません。これらは Tool '<id>' is not supported on vega vvd.（または ... is not yet implemented on vega.）というエラーになります。

ナレッジベース

• search_documentation ツール（amazon-devices-buildertools-mcp サーバー）で Vega のドキュメントを検索します。
• コミュニティの Q&A は community.amazondeveloper.com にあります。