argent-tv-interact

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Argent TV (Apple TV + Android TV + Fire TV)

Critical

关键注意事项

A TV is focus-driven, not touch-driven. Drive every interaction with
```
describe
```
+
```
tv-remote
```
+
```
keyboard
```
; never use
```
gesture-*
```
/ coordinate taps — they don't apply on any TV platform.
Always
describe
before navigating to find the live cursor and your target — never guess focus from a screenshot. The cursor is the focused element; on Vega the toolkit often leaves
```
focused
```
false and marks the highlighted item
```
[selected]
```
, so treat
```
[selected]
```
as the cursor when nothing reports
```
[focused]
```
.
Pass the
```
udid
```
from
```
list-devices
```
— an Apple TV simulator UDID or an Android TV / Vega
```
serial
```
. Dispatch is automatic from the id; the same tools drive all three.

TV 应用是以焦点为驱动，而非触控驱动。所有交互都需通过
```
describe
```
+
```
tv-remote
```
+
```
keyboard
```
完成；切勿使用
```
gesture-*
```
/ 坐标点击——这些操作在任何 TV 平台上都不适用。
导航前务必调用
describe
，以找到实时光标和目标元素——切勿通过截图猜测焦点位置。光标即为已聚焦元素；在 Vega 平台上，工具包常将
```
focused
```
标记为 false，而是用
```
[selected]
```
标记高亮项，因此当没有元素显示
```
[focused]
```
时，需将
```
[selected]
```
视为光标。
传入
```
list-devices
```
返回的
```
udid
```
——可以是 Apple TV 模拟器的 UDID，也可以是 Android TV / Vega 的
```
serial
```
。工具会根据 ID 自动分发指令；同一套工具可驱动上述三种平台。

The navigation loop

导航流程

```
describe
```
— find the cursor and your target (returns the focused element + all focusable ones, not a tap tree).
```
tv-remote
```
— move focus toward the target. Prefer one call with a path ending in
```
select
```
, e.g.
```
{button:["down","right","select"]}
```
; count rows/columns from the frames to build the path.
```
describe
```
again to confirm. On a miss, repeat.

```
describe
```
—— 找到光标和目标元素（返回已聚焦元素 + 所有可聚焦元素，而非点击树）。
```
tv-remote
```
—— 将焦点移向目标元素。优先使用单次调用并传入包含
```
select
```
的路径，例如
```
{button:["down","right","select"]}
```
；根据框架计算行数/列数以构建路径。
再次调用
```
describe
```
确认。若操作失败，重复上述步骤。

Tools

工具列表

```
describe {udid}
```
— focus view: the focused /
```
[selected]
```
element + focusable elements with labels and normalized frames. The discovery tool — call before and after navigating. Empty tree → see the per-platform notes.

tv-remote {udid, button}

— D-pad / remote.

button

is one key or a whole path (run in one call). Keys:

up

down

left

right

select

back

menu

home

playPause

, plus media keys

rewind

fastForward

next

previous

volumeUp

volumeDown

mute

. Single:

{button:"down"}

; repeat:

{button:"down", repeat:3}

; path:

{button:["up","right","select"]}

```
keyboard {udid, text}
```
— type into the focused field (focus it with
```
tv-remote
```
first). Named
```
key
```
presses (e.g.
```
{key:"enter"}
```
) work on Vega; on Apple TV / Android TV move focus with
```
tv-remote
```
instead.

launch-app

restart-app

reinstall-app {udid, bundleId}

—

bundleId

from the app manifest. Vega

reinstall-app

takes

appPath

= a

.vpkg

```
screenshot {udid, scale?}
```
— Apple TV via
```
xcrun simctl io
```
(downscaled); Android TV / Vega host-side via
```
adb
```
/
```
screencap
```
.

```
describe {udid}
```
—— 获取焦点视图：返回已聚焦/
```
[selected]
```
元素以及带有标签和标准化框架的可聚焦元素。这是核心发现工具——导航前后都需调用。若返回空树，请查看各平台说明。
```
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
```
聚焦输入框）。Vega 平台支持指定按键（例如
```
{key:"enter"}
```
）；而在 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
```
实现。

Per-platform

各平台说明

Apple TV (tvOS simulator)

Apple TV (tvOS 模拟器)

Boot like any iOS sim (
```
boot-device
```
); the AX + HID daemons auto-start on the first
```
describe
```
/
```
tv-remote
```
(first call may take a few seconds). Give the RN bundle a few seconds to render before the first
```
describe
```
.
Media-transport / volume keys are rejected — the sim's HID stack ignores them (they work on Android TV / Vega).

Dev build:

open-url {udid, url:"<scheme>://expo-development-client/?url=http%3A%2F%2F<HOST_IP>%3A8081"}

(

<HOST_IP>

= your Mac's LAN IP, shown on the launcher).

像启动 iOS 模拟器一样启动设备（
```
boot-device
```
）；首次调用
```
describe
```
/
```
tv-remote
```
时，AX + HID 守护进程会自动启动（首次调用可能需要几秒）。首次调用
```
describe
```
前，请给 RN 包几秒渲染时间。
媒体传输/音量按键会被拒绝——模拟器的 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 emulator)

Android TV (leanback 模拟器)

Boot the leanback AVD like any emulator — see
```
argent-android-emulator-setup
```
.
describe
may report zero focusables on a screen with visible tiles: many
```
react-native-tvos
```
screens use RN's own focus engine, invisible to the OS accessibility tree.
```
describe
```
auto-falls-back to the full UI tree (and says so in the hint);
```
tv-remote
```
still moves focus, so drive blind +
```
screenshot
```
to confirm.

Dev build:

adb -s <serial> reverse tcp:8081 tcp:8081

, deep-link

<pkg>://expo-development-client/?url=http%3A%2F%2F10.0.2.2%3A8081

, dismiss the first dev-menu with

adb shell input keyevent KEYCODE_DPAD_CENTER

(not Back — Back exits the app).

像启动普通模拟器一样启动 leanback AVD——参考
```
argent-android-emulator-setup
```
。
describe
可能在有可见磁贴的屏幕上返回零个可聚焦元素：许多
```
react-native-tvos
```
屏幕使用 RN 自身的焦点引擎，该引擎对系统无障碍树不可见。
```
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
```
shows a
```
serial
```
(use as
```
udid
```
) and a
```
vvdImage
```
.
```
boot-device {vvdImage}
```
(e.g.
```
"tv"
```
) starts the single SDK-managed VVD; skip if one already runs.
Stop the VVD with
```
vega virtual-device stop
```
in your shell. The CLI only tracks VVDs it started in the foreground, so it may report "not running" for one started via
```
boot-device
```
; to restart that one use
```
boot-device {vvdImage, force:true}
```
(stops then re-boots).
Empty
```
describe
```
tree →
```
restart-app
```
(the automation toolkit attaches at launch), then retry. Input ignored → enable developer mode in the VVD:
```
vsm developer-mode enable
```
.
Editing
```
node_modules
```
has no effect on a Release build — only Debug
```
.vpkg
```
builds load patchable JS.

Profiling / crashes →

amazon-devices-buildertools-mcp

server (

analyze_perfetto_traces

get_app_hot_functions

symbolicate_acr

); docs via its

search_documentation

tool.

```
list-devices
```
会返回
```
serial
```
（用作
```
udid
```
）和
```
vvdImage
```
。使用
```
boot-device {vvdImage}
```
（例如
```
"tv"
```
）启动由 SDK 管理的单个 VVD；若已有 VVD 在运行，可跳过此步骤。
停止 VVD：在终端中执行
```
vega virtual-device stop
```
。CLI 仅跟踪其在前台启动的 VVD，因此对于通过
```
boot-device
```
启动的 VVD，可能会显示“未运行”；如需重启该 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

工具查看文档。

Common gotchas

常见问题

Empty focus right after
launch-app
/
restart-app
is the splash / loading window —
```
describe
```
retries internally; wait ~2-3s and retry on a cold start.
Passing a phone/tablet (
```
runtimeKind: "mobile"
```
) udid to
```
tv-remote
```
fails with a clear "tvOS-only" / "Android-TV-only" error — pick a TV target from
```
list-devices
```
.

启动应用/重启应用后焦点为空：这是启动页/加载窗口导致的——
```
describe
```
会自动重试；冷启动时请等待约 2-3 秒后重试。
若将手机/平板（
```
runtimeKind: "mobile"
```
）的 udid 传入
```
tv-remote
```
，会返回明确的“仅 tvOS”/“仅 Android TV”错误——请从
```
list-devices
```
中选择 TV 目标设备。

Fast Refresh (dev builds)

Fast Refresh（开发构建）

Needs a Debug build + Metro running. argent only connects to Metro — start Metro and port-forward yourself (any platform). Metro is fixed on :8081.

Apple TV / Android TV: use the dev-build deep-links above;
```
npm start
```
for Metro.

Vega: build/install a Debug

.vpkg

(

vega device install-app -p <path>

npm start

vega device start-port-forwarding --port 8081 --forward false

, then

vega device launch-app -a <appId>

. Confirm

http://localhost:8081/json/list

shows a

Hermes React Native

target;

.tsx

edits then hot-reload.

需要 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

文件后即可热重载。