metavr-cli

metavr CLI 参考

metavr 的功能

metavr（Meta VR CLI）是用于 Meta VR 和 Horizon OS 开发的 CLI。 它将 ADB 和 Meta 开发者 API 封装为更高级的命令，用于设备 管理、应用生命周期管理、文档查找、屏幕截图、音频控制、 测试设备准备、MCP 集成和 Perfetto 性能分析。

请将此 SKILL.md 保留为路由层。有关准确的标志和完整命令 语法，请查阅生成的完整 CLI 参考 docs/metavr-cli.md，或运行：

metavr --markdown-help

安装

请先安装 metavr CLI。

独立二进制文件

独立二进制文件会安装到 PATH 中（无需前置条件）：

# macOS and Linux
curl -fsSL https://developers.meta.com/horizon/install-cli/ | sh

# Windows (PowerShell)
iwr -useb https://developers.meta.com/horizon/install-cli/windows/ | iex

安装程序会将 metavr 添加到 PATH 中（请加载 shell rc 文件或打开新 终端以使其生效）。如果安装的是独立二进制文件，请使用 metavr update 保持其为最新版本。

npm 发行版

npm 发行版需要 Node.js 16 或更高版本，无需单独安装：

npx -y metavr --version

也可以使用 npm install -g metavr 全局安装（之后使用 npm update -g metavr 更新）。

本文档其余部分的示例均使用不带前缀的 metavr 命令。如果 使用 npm 发行版，请添加 npx -y 前缀（例如 npx -y metavr device list）。

设备连接

使用设备端命令前：

1. 在 Meta VR 设备上启用开发者模式（设置 > 系统 > 开发者）
2. 出现提示时启用USB 调试
3. 使用 USB-C 线缆将 Meta VR 设备连接到计算机

验证连接：

metavr device list

如果没有显示设备：请尝试更换 USB 线缆（支持数据传输，而非仅充电）， 在头显上接受 USB 调试提示，或使用 metavr device connect <ip> 无线连接。

命令发现

采用渐进式披露：

1. 从本技能开始，了解命令组和常见工作流。
2. 用户在某个领域开展工作时，打开对应的专门参考文件。
3. 使用 docs/metavr-cli.md 或 metavr --markdown-help 查看准确的标志、参数和 不常用的子命令。

当前顶层命令组：

命令组	用途
adb / shell	低级 ADB 兼容命令和直接访问设备 shell
app	安装、列出、启动、停止、清除、检查应用，以及检测前台应用
asset	搜索 Meta 的 3D 资源库
audio	读取音量、设置音量、静音和取消设备音频静音
capture	从已连接的头显截取屏幕截图
config	读取、写入、重置和列出 metavr 配置
device	列出/连接设备、等待 ADB 状态、检查控制器、配置测试设备、运行健康检查，以及管理接近传感器
docs	搜索/获取 Meta VR 文档和 API 参考条目
files	在设备上列出、拉取、推送、移除文件和创建目录
log	查看设备近期日志；高级筛选和流式传输请使用 adb logcat
mcp	为 AI 工具启动或安装 metavr MCP 服务
perf	捕获、打开、分析、查询、比较和管理 Perfetto 跟踪

MCP 服务模式

metavr 内置了一个 MCP（模型上下文协议）服务，包含约 40 个工具，可让 AI Agent 以编程方式与 Meta VR 设备交互。

将此命令添加到任意 MCP 配置中即可使用 MCP 服务：

metavr mcp server

该服务提供用于设备管理、应用生命周期管理、性能跟踪 分析、文档搜索、文件操作和 3D 资源搜索的工具。

将 MCP 配置安装到其他 AI 工具中：

metavr mcp install cursor
metavr mcp install claude-desktop
metavr mcp install vscode

如需设置项目本地的 Agent，请将 MCP 配置安装到当前仓库：

cd your-project
metavr mcp install project

对于已能访问主机上仓库、并且需要在该项目中调用 metavr 工具的编码 Agent， 这是最合适的默认选项。

常见 Agent 工作流

如果你正在构建 Meta VR 原生开发工具，或将 Meta VR 头显 UI 与主机端编码 Agent 配对使用，请保持架构简单：

• 让主机端编码 Agent 负责仓库访问、文件编辑、构建、测试和 metavr 工具调用
• 让头显应用或浏览器体验充当轻量客户端，用于预览、提示词采集、状态查看和审批
• 优先使用 metavr mcp install project 进行项目本地 MCP 安装，让集成明确且随仓库一起迁移

# 1. Verify the current docs before coding against an API or workflow
metavr docs search "spatial sdk panel"
metavr docs fetch https://developers.meta.com/horizon/documentation/...

# 2. Build and deploy your app
./gradlew assembleDebug
metavr app install app/build/outputs/apk/debug/app-debug.apk
metavr app launch com.example.app

# 3. Observe on-device behavior
metavr log --tag MyApp
metavr capture screenshot -o latest.png

# 4. Prepare a stable test device when running repeatable tests
metavr device health-check
metavr device configure-testing setup
# ...run tests...
metavr device configure-testing restore

与 ADB 的关系

metavr 封装了 ADB，并提供更高级别的命令。对于大多数 Meta VR 开发任务，你无需直接使用 adb。metavr 会处理设备选择、提供结构化输出，并添加原始 ADB 不支持的 Meta VR 专属功能（通过 metacam 截取屏幕截图、Perfetto 跟踪分析、文档搜索）。

如果需要对设备进行原始 Shell 访问，请使用 metavr shell 或 metavr adb shell。

完整命令参考

请使用 docs/metavr-cli.md 查看生成的命令详情。使用以下命令重新生成：

metavr --markdown-help > docs/metavr-cli.md

参考资料

如需包含工作流、示例和故障排除的详细使用指南，请参阅：

• 设备管理 — 设备命令、音频、屏幕截图、日志、测试设置、健康检查、Shell 访问
• 应用管理 — 应用生命周期、前台应用检测、崩溃调试、常见日志标签
• Agent 工作流 — 项目本地 MCP 安装、文档验证、安全、轻量客户端架构
• 性能工具 — 跟踪采集、引导式分析、Perfetto UI、SQL 查询、比较、GPU 计数器
• 文档搜索 — 文档搜索、API 搜索、类别筛选
• 开发者工具 — 通过 metavr tools 安装、更新和启动模拟器、调试器及 SDK