argent-vega

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Argent Vega (Amazon Fire TV)

Critical

重要说明

Vega is a TV platform
D-pad only. Drive every interaction with
```
tv-remote
```
. Never use
```
gesture-*
```
/ touch — they are unsupported on Vega.
Always
describe
before navigating. Find the live cursor from the tree — the
```
[focused]
```
element, or
```
[selected]
```
when nothing reports
```
[focused]
```
(the toolkit often marks the highlighted item
```
[selected]
```
while
```
focused
```
stays false). Never guess focus position from a screenshot.
All tools take the Vega
```
serial
```
(from
```
list-devices
```
) as
```
udid
```
.

Vega是一个电视平台
仅支持D-pad。所有交互都通过
```
tv-remote
```
完成。请勿使用
```
gesture-*
```
/触摸操作——Vega不支持这些方式。
导航前务必调用
describe
。从元素树中找到实时光标——
```
[focused]
```
元素，如果没有元素标记
```
[focused]
```
则找
```
[selected]
```
元素（工具包通常会将高亮项标记为
```
[selected]
```
，而
```
focused
```
保持为false）。切勿通过截图猜测焦点位置。
所有工具都将Vega的
```
serial
```
（来自
```
list-devices
```
）作为
```
udid
```
参数。

The navigation loop

导航循环

Per screen, two calls:

```
describe
```
— find the cursor (
```
[focused]
```
, or
```
[selected]
```
if no
```
[focused]
```
) and your target.
Compute the full D-pad path from focus → target (count rows/columns from the frames) and fire it as one
```
tv-remote {button:[...]}
```
ending in
```
select
```
.

Then

describe

again to confirm. On a miss, run the loop again.

每个屏幕操作包含两步调用：

```
describe
```
——找到光标（
```
[focused]
```
元素，若无则找
```
[selected]
```
元素）和目标元素。
计算从焦点到目标的完整D-pad路径（根据框架统计行数/列数），并将其作为单次
```
tv-remote {button:[...]
```
调用发送，最后以
```
select
```
结束。

之后再次调用

describe

确认。如果操作失败，重复上述循环。

Tools

工具

Device lifecycle

设备生命周期

```
list-devices
```
→ Vega devices appear with a
```
serial
```
(use as
```
udid
```
) and a
```
vvdImage
```
. Start here to get both.
```
boot-device {vvdImage}
```
— starts the single SDK-managed VVD (e.g.
```
vvdImage:"tv"
```
) and returns its
```
serial
```
. Skip if
```
list-devices
```
already shows a running device.
Stopping the VVD — run
```
vega virtual-device stop
```
in your shell.

```
list-devices
```
→ Vega设备会显示
```
serial
```
（用作
```
udid
```
）和
```
vvdImage
```
。先调用此工具获取这两个参数。
```
boot-device {vvdImage}
```
——启动由SDK管理的单个VVD（例如
```
vvdImage:"tv"
```
）并返回其
```
serial
```
。如果
```
list-devices
```
已显示运行中的设备，则跳过此步骤。
停止VVD ——在终端中运行
```
vega virtual-device stop
```
。

App lifecycle

应用生命周期

```
launch-app {udid, bundleId}
```
—
```
bundleId
```
= interactive component app id from manifest.toml (e.g.
```
com.example.app.main
```
)
```
restart-app {udid, bundleId}
```
— terminate + launch

reinstall-app {udid, bundleId, appPath}

— uninstall + install;

appPath

= a

.vpkg

```
describe {udid}
```
→ on-screen element tree. The discovery tool — call before navigating
```
tv-remote {udid, button}
```
— D-pad; single key, path array, or
```
repeat
```
```
keyboard {udid, text}
```
or
```
{udid, key:"enter"}
```
— focus the field with the D-pad first
```
screenshot {udid, scale?}
```
— captured host-side via
```
adb
```

```
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-pad操作；支持单个按键、路径数组或
```
repeat
```
参数

keyboard {udid, text}

或

{udid, key:"enter"}

——先使用D-pad聚焦输入框

```
screenshot {udid, scale?}
```
——通过
```
adb
```
在主机端捕获截图

describe

describe

Nested element tree from the on-device automation toolkit — each line is a

button

text

image

with its label,

id

(test_id),

[clickable]

, and [focused]
/
[selected]
+ a normalized [0,1] frame.

[focused]

is the live D-pad cursor when present; in practice the toolkit usually leaves

focused

false and marks the highlighted item

[selected]

, so treat

[selected]

as the cursor whenever no element reports

[focused]

. Navigate on the tree alone. If the tree comes back empty →

restart-app

and retry.

由设备端自动化工具包生成的嵌套元素树——每一行是一个

button

text

image

元素，包含其标签、

id

（test_id）、

[clickable]

属性，以及**

[focused]

[selected]

**属性和标准化的[0,1]框架。当存在

[focused]

时，它代表实时D-pad光标；实际使用中，工具包通常会将

focused

设为false，而将高亮项标记为

[selected]

，因此当没有元素报告

[focused]

时，将

[selected]

视为光标。仅根据元素树进行导航。如果返回的元素树为空 → 调用

restart-app

并重试。

tv-remote

tv-remote

button

is a single key or a whole path. Keys:

up

down

left

right

select

back

home

menu

playPause

rewind

fastForward

. Single:

{button:"down"}

. Repeat one key:

{button:"down", repeat:3}

. Whole path in one call:

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

— strongly prefer this for any multi-step move.

button

可以是单个按键或完整路径。支持的按键：

up

down

left

right

、

select

、

back

、

home

、

menu

、

playPause

、

rewind

、

fastForward

。单个按键示例：

{button:"down"}

。重复单个按键：

{button:"down", repeat:3}

。单次调用完整路径：

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

——强烈推荐使用这种方式完成多步移动。

Fast Refresh

快速刷新

Needs a Debug build + Metro running. argent only connects to Metro — it does not start Metro or port-forward (any platform); do these in your shell.

Build a Debug

.vpkg

and install it:

vega device install-app -p <path/to/debug.vpkg>

npm start

(Metro on :8081; use

npm start

, not

npx react-native start

)

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

(reverse)

```
vega device launch-app -a <appId>
```

Metro must be up before launch; confirm

http://localhost:8081/json/list

lists a

Hermes React Native

target. Then

.tsx

edits hot-reload live.

需要Debug构建版本 + 运行中的Metro。argent仅连接到Metro——它不会启动Metro或进行端口转发（任何平台）；这些操作需要在终端中完成。

构建Debug版本的

.vpkg

并安装：

vega device install-app -p <path/to/debug.vpkg>

运行
```
npm start
```
（Metro运行在:8081端口；使用
```
npm start
```
，而非
```
npx react-native start
```
）

运行

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

（反向端口转发）

运行
```
vega device launch-app -a <appId>
```

必须在启动应用前启动Metro；确认

http://localhost:8081/json/list

中列出了

Hermes React Native

目标。之后

.tsx

文件的修改会实时热重载。

Troubleshooting

故障排查

describe
returns an empty tree →
```
restart-app
```
(the automation toolkit attaches at launch), then retry.
Keyboard / D-pad input is ignored → enable developer mode inside the VVD:
```
vsm developer-mode enable
```
.
Editing
node_modules
has no effect → you are on a Release build. Release Vega apps load JavaScript and native code split and stored on device, so patching
```
node_modules
```
only works in Debug builds.

describe
返回空元素树 → 调用
```
restart-app
```
（自动化工具包在应用启动时附加），然后重试。
键盘/D-pad输入被忽略 → 在VVD内启用开发者模式：
```
vsm developer-mode enable
```
。
修改
node_modules
无效果 → 你正在使用Release构建版本。Vega的Release版本应用会拆分加载JavaScript和原生代码并存储在设备上，因此仅在Debug构建版本中修改
```
node_modules
```
才会生效。

Platform notes

平台说明

Metro connects only on port 8081 — fixed, cannot be changed.

Profiling / crashes → use the

amazon-devices-buildertools-mcp

server (

analyze_perfetto_traces

get_app_hot_functions

symbolicate_acr

Unsupported tools, with the Vega equivalent:
```
gesture-*
```
→ use
```
tv-remote
```
;
```
open-url
```
→ not wired;
```
debugger-*
```
→ JS debugger not supported on Vega. These fail with
```
Tool '<id>' is not supported on vega vvd.
```
(or
```
... is not yet implemented on vega.
```
).

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.
```
）。

Knowledgebase

知识库

Search Vega docs with the

search_documentation

tool (

amazon-devices-buildertools-mcp

server).

Community Q&A at community.amazondeveloper.com.

使用

search_documentation

工具（

amazon-devices-buildertools-mcp

服务器）搜索Vega文档。

社区问答可访问community.amazondeveloper.com。

argent-vega

Original

Translation

Argent Vega (Amazon Fire TV)

Argent Vega (Amazon Fire TV)

Critical

重要说明

The navigation loop

导航循环

Tools

工具

Device lifecycle

设备生命周期

App lifecycle

应用生命周期

`describe`

`describe`

`tv-remote`

`tv-remote`

Fast Refresh

快速刷新

Troubleshooting

故障排查

Platform notes

平台说明

Knowledgebase

知识库