argent-vega

Argent Vega（Amazon Fire TV）

重要

• Vega 是电视平台。
• 仅使用方向键。 所有交互都通过 tv-remote 操作。Vega 不支持 gesture-* / 触控，因此绝不要使用它们。
• 导航前始终先调用 describe。 从树中查找当前光标所在位置：[focused] 元素；如果没有元素报告 [focused]，则查找 [selected] 元素（工具包通常会将高亮项目标记为 [selected]，而 focused 仍为 false）。绝不要根据截图猜测焦点位置。
• 所有工具都使用 Vega 的 serial（来自 list-devices）作为 udid。

导航循环

每个屏幕调用两次：

1. describe — 查找光标（[focused]；如果没有 [focused]，则查找 [selected]）和目标。
2. 计算从焦点到目标的完整方向键路径（根据 frame 计算行列），并通过一次 tv-remote {button:[...]} 调用发送，最后以 select 结束。

然后再次调用 describe 进行确认。如果未成功，重新运行循环。

工具

设备生命周期

• list-devices → Vega 设备会显示 serial（用作 udid）和 vvdImage。从这里开始获取这两项。
• boot-device {vvdImage} — 启动由 SDK 管理的单个 VVD（例如 vvdImage:"tv"），并返回其 serial。如果 list-devices 已显示运行中的设备，则跳过。
• 停止 VVD — 在 shell 中运行 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} — 方向键；单个按键、路径数组或 repeat
• keyboard {udid, text} 或 {udid, key:"enter"} — 先用方向键聚焦输入框
• screenshot {udid, scale?} — 通过 adb 在主机端截取

describe

来自设备端自动化工具包的嵌套元素树 — 每行包含一个 button/text/image 及其标签、id（test_id）、[clickable]，以及**[focused]/[selected]**和归一化的 [0,1] frame。存在 [focused] 时，它表示当前方向键光标；实际使用中，工具包通常会将 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}。一次调用发送完整路径：{button:["up","right","right","select"]} — 强烈建议所有多步移动都使用此方式。

快速刷新

需要 Debug 构建和正在运行的 Metro。argent 只连接 Metro — 不会启动 Metro，也不会进行端口转发（任何平台均如此）；请在 shell 中完成这些操作。

1. 构建一个 Debug .vpkg 并安装：vega device install-app -p <path/to/debug.vpkg>
2. npm start（Metro 在 :8081 端口运行；请使用 npm start，不要使用 npx react-native 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（自动化工具包会在启动时接入），然后重试。
• 键盘 / 方向键输入被忽略 → 在 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 文档。
• 社区问答见 community.amazondeveloper.com。