argent-tv-interact

Argent TV（Apple TV + Android TV + Fire TV）

重要

• 电视是焦点驱动，而非触控驱动。 每次交互都使用 describe + tv-remote + keyboard；不要使用 gesture-* / 坐标点击，这些操作不适用于任何电视平台。
• 导航前务必先调用 describe，找到当前焦点和目标；不要根据截图猜测焦点。光标就是当前获得焦点的元素；在 Vega 上，工具包常会将 focused 标记为 false，并用 [selected] 标记高亮项，因此当没有元素报告 [focused] 时，应将 [selected] 视为光标。
• 传入 list-devices 返回的 udid：Apple TV 模拟器 UDID，或 Android TV / Vega 的 serial。工具会根据 ID 自动分派，同一组工具可操作这三种设备。

导航循环

1. describe：找到光标和目标（返回获得焦点的元素及所有可聚焦元素，而非点击树）。
2. tv-remote：将焦点移向目标。优先使用一次调用，并以 select 结尾，例如 {button:["down","right","select"]}；根据 frame 计算行列，构建导航路径。
3. 再次调用 describe 进行确认。若未命中，重复上述步骤。

工具

• describe {udid}：焦点视图：获得焦点的 / [selected] 元素，以及带标签和归一化 frame 的可聚焦元素。在导航前后调用。树为空时，请参阅各平台说明。
• tv-remote {udid, button}：方向键 / 遥控器。button 可以是一个按键，也可以是完整路径（一次调用执行）。按键：up/down/left/right、select、back、menu、home、playPause，以及媒体按键 rewind/fastForward/next/previous/volumeUp/volumeDown/mute。单次按键：{button:"down"}；重复按键：{button:"down", repeat:3}；路径：{button:["up","right","select"]}。
• keyboard {udid, text}：向当前获得焦点的字段输入文本（先用 tv-remote 聚焦该字段）。一次调用只能传入 text 或 key，不能同时传入；若要先输入文本再按键，请在同一个 run-sequence 中发送两个 keyboard 步骤。命名的 key 按键（例如 {key:"enter"}）在 Vega 上有效；在 Apple TV / Android TV 上，请改用 tv-remote 移动焦点。
• launch-app / restart-app / reinstall-app {udid, bundleId}：bundleId 取自应用清单。Vega 的 reinstall-app 使用 appPath，值为 .vpkg 文件。
• screenshot {udid, scale?}：Apple TV 通过 xcrun simctl io 截图（会缩小）；Android TV / Vega 在主机端通过 adb / screencap 截图。

各平台说明

Apple TV（tvOS 模拟器）

• 像启动任何 iOS 模拟器一样启动（boot-device）；AX + HID 守护进程会在首次调用 describe / tv-remote 时自动启动（首次调用可能需要几秒）。首次调用 describe 前，请等待 RN bundle 渲染几秒。
• 媒体传输 / 音量按键会被拒绝：模拟器的 HID 堆栈会忽略这些按键（它们在 Android TV / Vega 上有效）。
• 开发构建：open-url {udid, url:"<scheme>://expo-development-client/?url=http%3A%2F%2F<HOST_IP>%3A8081"}（<HOST_IP> = 你的 Mac 的局域网 IP，可在启动器上查看）。

Android TV（leanback 模拟器）

• 像启动任何模拟器一样启动 leanback AVD；请参阅 argent-android-emulator-setup。
• 在显示可见磁贴的屏幕上，describe 可能报告没有可聚焦元素：许多 react-native-tvos 屏幕使用 RN 自带的焦点引擎，该引擎在 OS 无障碍树中不可见。describe 会自动回退到完整 UI 树（并在提示中说明）；tv-remote 仍可移动焦点，因此请盲操作并通过 screenshot 确认。
• 开发构建：adb -s <serial> reverse tcp:8081 tcp:8081，深层链接 <pkg>://expo-development-client/?url=http%3A%2F%2F10.0.2.2%3A8081，使用 adb shell input keyevent KEYCODE_DPAD_CENTER 关闭首次出现的开发菜单（不要按 Back：Back 会退出应用）。

Fire TV（Vega / VVD）

• list-devices 会显示一个 serial（用作 udid）和一个 vvdImage。boot-device {vvdImage}（例如 "tv"）会启动由 SDK 管理的单个 VVD；如果已有一个在运行，则跳过。
• 停止 VVD：在 shell 中运行 vega virtual-device stop。CLI 只会跟踪它在前台启动的 VVD，因此对于通过 boot-device 启动的 VVD，可能会报告“not running”；要重新启动该 VVD，请使用 boot-device {vvdImage, force:true}（先停止，再重新启动）。
• describe 树为空 → restart-app（自动化工具包会在启动时连接），然后重试。输入无响应 → 在 VVD 中启用开发者模式：vsm developer-mode enable。
• 编辑 node_modules 对 Release 构建没有影响；只有 Debug .vpkg 构建会加载可修补的 JS。
• 性能分析 / 崩溃 → 使用 amazon-devices-buildertools-mcp 服务（analyze_perfetto_traces、get_app_hot_functions、symbolicate_acr）；通过其 search_documentation 工具查阅文档。

常见问题

• 在 launch-app / restart-app 后立即出现焦点为空，表示当前是启动画面 / 加载窗口；describe 会在内部重试；冷启动时请等待约 2-3 秒后重试。
• 将手机 / 平板（runtimeKind: "mobile"）的 udid 传给 tv-remote 会失败，并显示清晰的“tvOS-only” / “Android-TV-only”错误；请从 list-devices 中选择电视设备。

快速刷新（开发构建）

需要 Debug 构建 + 正在运行的 Metro。argent 只会_连接_到 Metro；请自行启动 Metro 并进行端口转发（适用于任何平台）。Metro 固定使用 :8081。

• **Apple TV / Android TV：**使用上文的开发构建深层链接；通过 npm start 启动 Metro。
• **Vega：**构建 / 安装 Debug .vpkg（vega device install-app -p <path>），运行 npm start，再运行 vega device start-port-forwarding --port 8081 --forward false，然后运行 vega device launch-app -a <appId>。确认 http://localhost:8081/json/list 显示一个 Hermes React Native 目标；之后编辑 .tsx 文件即可热重载。

调试 JS 运行时（Vega）

设置好同一个 Debug 构建 + Metro 后，JS 运行时工具可用于 Vega VVD：debugger-connect、debugger-status、debugger-evaluate、debugger-log-registry（控制台日志）、view-network-logs 和 view-network-request-details。通过 debugger-status 验证：未连接时会返回状态结果，而不是错误：status: "connected" 表示设置正常；status: "not_connected" 会附带 reason 和 guidance（例如 metro_not_running → Metro 本身未运行）。Vega 特有情况：出现 no_app_connected 时，在重新启动应用前检查 vega device start-port-forwarding：设备到主机的转发中断通常是原因所在，而通用指导无法识别此问题。参见 argent-metro-debugger 技能。

Vega 的 React Native 分支基于 RN 0.72，并提供旧版 Hermes 检查器，因此有三点与 iOS / Android 不同：

• debugger-component-tree、debugger-inspect-element、debugger-reload-metro 以及 react-profiler-* / profiler-* 工具不受支持。组件树和 inspect-element 会被硬性阻止：它们需要 Runtime.addBinding，而此 Hermes 虽然会确认收到该调用，却从未安装它。其余工具在旧版检查器上未经验证。使用 describe 查看屏幕结构；由于两个组件工具都被禁用，Vega 上没有组件 file:line 追踪途径。
• debugger-status 会报告 isNewDebugger: false。
• projectRoot 为空（RN 0.72 的 Metro 不会发送 project-root 标头），因此，根据项目根目录解析路径的查找不会返回位置。