quest-tooling

Quest 工具链：一个 CLI、两种接口、每个 Agent 一个通道

metavr（Meta VR CLI）是一个工具，有两种使用方式：命令行，以及由 Agent 自行驱动的 stdio MCP 服务。以下所有功能都可通过两种方式使用——这里列出 CLI 命令，是因为未配置 MCP 服务时也可用它们作为后备方案。

规划研究、选择采集／自动化路径、处理相互冲突的来源或在没有工具时开展工作，请阅读 references/research-navigation.md。使用这份有日期的命令映射表之前，请先解析可执行文件并检查该版本的帮助信息；生成的配套说明可能描述的是其他版本。

若要了解整个产品的路线图或审查阶段，请使用 quest-lifecycle；单项技术任务仍由此工具负责。如果该工具不存在，请在行内说明当前阶段、相关证据和下一个前置条件。

如需了解当前来源的发现、无法获取的 Markdown、相互冲突的需求、带版本的 API 索引以及现有 CLI／MCP 注册信息，请阅读 references/source-research.md。

通过一个渠道安装一次

渠道	命令	更新
原生安装程序（首选）	curl -fsSL https://developers.meta.com/horizon/install-cli/ | sh → ~/.metavr/bin	metavr update，原地更新
npx，无需安装	npx -y metavr@latest <cmd>	始终为最新版本
npm 全局安装	npm install -g metavr	不会自动更新——需要运行 npm update -g metavr

同时安装其中两种，会导致版本分裂，让人误以为是程序错误： 在这套环境中，~/.metavr/bin/metavr（1.3.2.2.2）和 /opt/homebrew/bin/metavr （npm 1.3.2）都能响应 metavr，最终使用哪个取决于 PATH 顺序。使用 which -a metavr 检查，并保留一个。

登录——运行 metavr auth login，再用 metavr auth status 验证。登录后即可使用 Store 命令；无人值守自动化可使用 METAVR_TOKEN。

metavr init 是陷阱，而不是设置步骤

init 会安装技能、配置 MCP 服务并安装 Agent 插件。未指定目标标志时，它表示 --all-agents，而“所有 Agent”指的是它自己的固定列表，并非你实际拥有的 Agent。在项目目录中运行时，它会为每个 Agent 在该目录中写入一棵 skills/ 目录树。

2026-09-20 在一个游戏仓库中测得：29 个技能 × 25 个目录 = 4129 个文件，47 MB，这些文件未被跟踪，也未被 .gitignore 覆盖——随后执行的 git add -A 就把它们全部提交进产品中。

在这套环境中，设置前请先检查网关／插件注册情况。新的独立 metavr stdio 服务应接入网关；metavr mcp install 示例会直接配置 Agent，在这里并非默认做法。如果需要安装到选定的宿主中，请先检查 metavr init --help 和目标路径。不要笼统忽略项目自有的 .agents 或其他现有文件。

命令速查表

任务	命令
查看已连接设备	metavr device list / device info <id> / device battery
通过 Wi-Fi 配对	metavr device connect（先通过 USB 连接）、device wait、device health-check
让设备稳定用于测试	metavr device configure-testing（关闭动画，保持唤醒）
安装 / 启动 / 停止构建	metavr app install <apk> / app launch <pkg> / app stop <pkg>
日志	metavr log（logcat）、metavr shell <cmd>
屏幕	metavr capture screenshot
设备上的文件	metavr files push / pull / ls / rm
UI 自动化	metavr ui dump / tap / type / swipe / wait
性能	metavr perf capture / start / stop / analyze-trace / compare / simpleperf
文档和 API 参考	metavr docs search / fetch / api-search
3D 资源	metavr asset search "<thing>"
商店分发	metavr store dist apps / channels / upload / copy-build；store test-user
模拟器	metavr ssim（SpatialSim）
受管理的工具	metavr tools list / install <name>
设置报告	metavr doctor

metavr doctor 仅报告已安装的软件——它不会测试设备连接、登录或 MCP 接线。即使没有连接头显，doctor 显示绿色，机器仍然无法运行任何内容。

MCP 服务，以及为什么会被注册两次

metavr mcp server 是 stdio 服务。Meta 插件可能负责其注册；否则，操作员配置的网关可以将其公开。不要同时注册两者。在此环境中，新的独立 stdio / 静态令牌服务需通过 ~/.config/agentgateway/servers.yaml 和现有的生成器 / 迁移流程接入；受 OAuth 保护的资源服务由 Agent 管理。由插件管理的 MCP 仍由插件负责。只有在所选部署策略要求时，才适合直接使用 .mcp.json；它并不是通用的项目设置方案。

metavr xroperator status 会显示 XR Operator 代理是否已安装，以及是否已联邦接入 metavr 自己的 MCP 服务——如果已接入，就能通过同一连接检查正在运行的 XR 应用；无需注册第二个服务。

Meta 的 29 个技能，以及这个技能包的补充内容

Meta 在 github.com/meta-quest/agentic-tools 发布这些技能（插件 meta-vr@meta-quest，也可通过 npx skills、gh skill、Cursor、Codex、Gemini 获取）。了解它们的分工，有助于你决定该使用哪个：

Meta 的技能	数量	负责的领域
hz-unity-*	12	Unity——这个技能包不会重复提供这些内容
hz-quest-verify-first、metavr-cli、portal	3	文档验证和 CLI 参考
hz-perfetto-debug、hz-simpleperf-debug、hz-vr-debug	3	使用特定性能分析器
hz-store-submit、hz-store-pwa	2	商店相关操作
hz-spatial-sdk、hz-iwsdk-webxr、hz-android-2d-porting、hz-platform-sdk、hz-psdk-integration 等	9	其他构建路径

这个技能包回答的是高于工具层面的问题：项目属于哪个领域、该查看哪个数值、该测量什么、商店会拒绝什么。如果 Meta 技能能操作相应工具，就使用它——并说明由哪个技能完成了工作。

桌上没有头显

• xrsim（Meta XR Simulator）和 spatialsim（metavr ssim）可在机器上运行应用逻辑。它们可检查受支持的模拟行为和集成情况。
• 它们无法回答性能问题：没有真实的 GPU、热状态或合成器。请参阅 quest-perf。
• metavr device browser <url> 和商店测试账号（metavr store test-user）需要真实设备和组织。

受管理的开发者工具

metavr tools install <name> 会获取并安装工具；metavr tools list 会显示版本和已安装内容。每个工具的用途——包括哪些工具需要头显——请参阅 references/tool-matrix.md。

卫生规范，忽视它们日后会付出代价

1. 每个 Agent 只用一种渠道。 将文件直接复制到 ~/.claude/skills/<name>，胜过安装同名插件，而且能永久使用其固定版本。
2. 绝不要将技能打包进产品仓库。 技能安装在机器上；仓库中的副本会让 CI 现在开始检查第三方的 47 MB 文本。
3. 技能和插件在会话开始时加载——更改任一项后都要重启 Agent，否则它会继续使用旧版本。
4. 每次安装或移除后，都必须运行以下检查，且不应输出任何内容：

for d in ~/.claude/skills/*/; do n=$(basename "$d"); \
  [ -e ~/.claude/plugins/marketplaces/"$n" ] && echo "SHADOW: $n"; done

CLI 界面内容取自 2026-09-20 的 1.3.2.2.2 版 metavr --help；安装和初始化行为也在同一天于本机实测。

触发词

还会通过以下短语路由到此处：“adb to Quest” / “adb к шлему”、“XR Simulator” / “симулятор”、“no headset” / “нет шлем”、“metavr init”、“Meta VR CLI”、“Quest MCP” / “MCP для Quest”、“install the APK” / “поставить apk на шлем”、“developer mode” / “режим разработчика”、“which Quest tools are installed” / “что установлено для Quest”、“hz- skills” / “скилы Meta”。

此内容于 0.4.4 版从描述中移至此处：“connect the headset”。

在 0.4.5 版（hub B-298）中，新增了指明头显的限定形式：“Meta XR Simulator” / “симулятор Quest”、“install the APK on Quest” / “поставить apk на Quest”、“Quest developer mode” / “режим разработчика на Quest”。