quest-tooling

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

The Quest toolchain: one CLI, two interfaces, one channel per agent

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

metavr

(Meta VR CLI) is a single tool with two faces: a command line, and a stdio MCP server an agent drives on its own. Everything below is available through both — the CLI names are given because they are also the fallback when no MCP server is configured.

Read

references/research-navigation.md

when planning research, choosing a capture/automation path, handling conflicting sources or working without a tool. Resolve the executable and inspect that version's help before using this dated command map; generated companion instructions may describe a different version.

For a whole-product roadmap or stage audit, use

quest-lifecycle

; a single technical task stays with this owner. If absent, identify the current stage, its evidence and the next prerequisite inline.

Read

references/source-research.md

for current-source discovery, unavailable Markdown, conflicting requirements, versioned API indexes and existing CLI/MCP registrations.

metavr

（Meta VR CLI）是一个具有两种形态的单一工具：一个是命令行，另一个是 Agent 可自行驱动的 stdio MCP server。以下所有能力均可通过这两种接口使用——之所以同时给出 CLI 名称，是因为未配置 MCP server 时，它们也是备用方案。

在规划调研、选择 capture/自动化路径、处理相互冲突的来源，或没有可用工具时，请读取

references/research-navigation.md

。使用这份带日期的命令映射前，先确定可执行文件的实际位置并检查该版本的帮助信息；自动生成的配套说明可能描述的是不同版本。

对于完整产品的路线图或阶段审计，请使用

quest-lifecycle

；单项技术任务仍归本 skill 处理。如果该 skill 不可用，请在当前回复中直接说明当前阶段、相关证据和下一项前置条件。

读取

references/source-research.md

，了解如何发现当前有效来源、处理不可用的 Markdown、冲突需求、分版本 API 索引，以及现有的 CLI/MCP 注册项。

Install it once, through one channel

一次安装，只用一个通道

Channel	Command	Updates
Native installer (preferred)	`curl -fsSL https://developers.meta.com/horizon/install-cli/ \| sh` → `~/.metavr/bin`	`metavr update` , in place
npx, no install	`npx -y metavr@latest <cmd>`	always current
npm global	`npm install -g metavr`	never on its own — needs `npm update -g metavr`

Two of these installed at once is a version split waiting to be read as a bug: on this estate

~/.metavr/bin/metavr

(1.3.2.2.2) and

/opt/homebrew/bin/metavr

(npm 1.3.2) both answered to

metavr

, and PATH order decided which. Check with

which -a metavr

and keep one.

metavr auth login

, verify with

metavr auth status

. It unlocks the Store commands;

METAVR_TOKEN

covers unattended automation.

通道	命令	更新方式
原生安装器（推荐）	`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`

同时安装其中两种会造成版本分裂，最终看起来就像一个 bug：在当前环境中，

~/.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

is the trap, not the setup

metavr init

是陷阱，而不是正确的设置方式

init

installs skills, configures MCP servers and installs agent plugins. With no target flag it means
--all-agents
, and "all agents" is its own fixed list, not the agents you have. Run inside a project directory it writes one

skills/

tree per agent into that directory.

Measured 2026-09-20 in a game repository: 29 skills × 25 directories = 4129 files, 47 MB, untracked, uncovered by

.gitignore

— and the next

git add -A

committed the lot into the product.

On this estate, inspect the gateway/plugin registration before setup. A new standalone metavr stdio server belongs in the gateway;

metavr mcp install

examples configure agents directly and are not the default here. If a selected host installation is needed, inspect

metavr init --help

and the target paths first. Do not ignore project-owned

.agents

or other existing files broadly.

init

会安装 skills、配置 MCP servers，并安装 agent plugins。如果未指定目标 flag，它就等同于

--all-agents

；而这里的“all agents”是一份固定列表，并不是你实际拥有的 Agents。如果在项目目录中运行，它会在该目录内为每个 Agent 写入一棵独立的

skills/

目录树。

在某个游戏仓库中于 2026-09-20 实测：29 个 skills × 25 个目录 = 4129 个文件、47 MB，这些文件未被 Git 跟踪，也未被

.gitignore

忽略——紧接着下一次执行

git add -A

，就会把它们全部提交进产品代码库。

在当前环境中，设置前先检查 gateway/plugin 注册情况。新增的独立 metavr stdio server 应由 gateway 承载；

metavr mcp install

示例会直接配置 Agents，并非此处的默认做法。如果需要为选定的 host 进行安装，请先检查

metavr init --help

和目标路径。不要笼统地忽略项目自有的

.agents

或其他现有文件。

The command map

命令映射

Job	Command
What is attached	`metavr device list` / `device info <id>` / `device battery`
Pair over Wi-Fi	`metavr device connect` (USB first), `device wait` , `device health-check`
Make a device test-stable	`metavr device configure-testing` (animations off, stay awake)
Install / launch / stop a build	`metavr app install <apk>` / `app launch <pkg>` / `app stop <pkg>`
Logs	`metavr log` (logcat), `metavr shell <cmd>`
Screens	`metavr capture screenshot`
Files on device	`metavr files push` / `pull` / `ls` / `rm`
UI automation	`metavr ui dump` / `tap` / `type` / `swipe` / `wait`
Performance	`metavr perf capture` / `start` / `stop` / `analyze-trace` / `compare` / `simpleperf`
Docs and API reference	`metavr docs search` / `fetch` / `api-search`
3D assets	`metavr asset search "<thing>"`
Store distribution	`metavr store dist apps` / `channels` / `upload` / `copy-build` ; `store test-user`
Emulator	`metavr ssim` (SpatialSim)
Managed tools	`metavr tools list` / `install <name>`
Setup report	`metavr doctor`

metavr doctor

reports installed software only — it does not test device connectivity, sign-in or MCP wiring. A green doctor with no headset attached is still a machine that cannot run anything.

任务	命令
当前连接了什么设备	`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>"`
Store 分发	`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

显示全绿，如果没有连接头显，这台机器仍然无法运行任何内容。

The MCP server, and how it ends up registered twice

MCP server，以及它为何会被注册两次

metavr mcp server

is the stdio server. Meta's plugin may own its registration; otherwise the operator's configured gateway can expose it. Do not register both. On this estate, new standalone stdio/static-token servers go through

~/.config/agentgateway/servers.yaml

and the existing generator/migration flow; OAuth protected-resource servers stay at the agent. Plugin-managed MCP stays with the plugin. A direct

.mcp.json

is appropriate only where the selected deployment policy calls for it, not a universal project setup recipe.

metavr xroperator status

shows whether the XR Operator proxy is installed and federated into metavr's own MCP server — when it is, a running XR app can be inspected through the same connection; no second server to register.

metavr mcp server

是 stdio server。Meta 的 plugin 可能负责管理它的注册；否则，也可由运维方配置的 gateway 对外提供。不要将两者同时注册。在当前环境中，新增的独立 stdio/static-token server 需要通过

~/.config/agentgateway/servers.yaml

及现有 generator/migration 流程接入；受 OAuth 保护的 resource server 保留在 agent 端。由 plugin 管理的 MCP 仍由 plugin 负责。只有在所选部署策略明确要求时，才适合直接使用

.mcp.json

；它并不是通用的项目设置方案。

metavr xroperator status

会显示 XR Operator proxy 是否已安装，以及是否已联邦接入 metavr 自身的 MCP server——启用后，可以通过同一连接检查正在运行的 XR 应用，无需再注册第二个 server。

Meta's 29 skills, and what this pack adds

Meta 的 29 个 skills，以及本 skill 包补充了什么

Meta publishes them at

github.com/meta-quest/agentic-tools

(plugin

meta-vr@meta-quest

, also on

npx skills

gh skill

, Cursor, Codex, Gemini). The split is worth knowing before wondering which one to reach for:

Meta's skills	Count	Owner of the lane
`hz-unity-*`	12	Unity — this pack does not duplicate them
`hz-quest-verify-first` , `metavr-cli` , `portal`	3	doc verification and CLI reference
`hz-perfetto-debug` , `hz-simpleperf-debug` , `hz-vr-debug`	3	driving a specific profiler
`hz-store-submit` , `hz-store-pwa`	2	store mechanics
`hz-spatial-sdk` , `hz-iwsdk-webxr` , `hz-android-2d-porting` , `hz-platform-sdk` , `hz-psdk-integration` , others	9	other build paths

This pack answers the questions that sit above a tool: which lane a project is on, which number to read, what to measure, what the Store will reject. Where a Meta skill drives the tool, use it — and say which one did the work.

Meta 在

github.com/meta-quest/agentic-tools

发布这些 skills（plugin 为

meta-vr@meta-quest

，也可通过

npx skills

、

gh skill

、Cursor、Codex、Gemini 获取）。在考虑该使用哪一个 skill 之前，值得先了解以下分工：

Meta 的 skills	数量	负责领域
`hz-unity-*`	12	Unity——本 skill 包不重复提供
`hz-quest-verify-first` 、 `metavr-cli` 、 `portal`	3	文档核验和 CLI 参考
`hz-perfetto-debug` 、 `hz-simpleperf-debug` 、 `hz-vr-debug`	3	操作特定的 profiler
`hz-store-submit` 、 `hz-store-pwa`	2	Store 机制
`hz-spatial-sdk` 、 `hz-iwsdk-webxr` 、 `hz-android-2d-porting` 、 `hz-platform-sdk` 、 `hz-psdk-integration` 、其他	9	其他构建路径

本 skill 包回答的是工具之上的问题：项目处于哪条开发路径、应该查阅哪个编号、应该测量什么，以及 Store 会拒绝什么。如果某个 Meta skill 负责驱动工具，就应使用它——并说明具体使用了哪一个。

No headset on the desk

桌面上没有头显时

```
xrsim
```
(Meta XR Simulator) and
```
spatialsim
```
(
```
metavr ssim
```
) run app logic on the machine. They check supported simulated behavior and integration.
They cannot answer a performance question: no real GPU, no thermals, no compositor. See
```
quest-perf
```
.
```
metavr device browser <url>
```
and the Store test accounts (
```
metavr store test-user
```
) need a real device and an organization.

```
xrsim
```
（Meta XR Simulator）和
```
spatialsim
```
（
```
metavr ssim
```
）可以在计算机上运行应用逻辑。它们用于检查受支持的模拟行为和集成情况。
它们无法回答性能问题：没有真实 GPU、温控系统，也没有 compositor。参见
```
quest-perf
```
。
```
metavr device browser <url>
```
和 Store 测试账号（
```
metavr store test-user
```
）需要真实设备和组织账户。

Managed developer tools

托管的开发工具

metavr tools install <name>

fetches and installs;

metavr tools list

shows versions and what is present. What each is for — including which need a headset — is in

references/tool-matrix.md

metavr tools install <name>

会下载并安装工具；

metavr tools list

会显示版本及已安装项目。每个工具的用途——包括哪些工具需要头显——见

references/tool-matrix.md

。

Hygiene, because the estate pays for it later

维护规范，因为当前环境最终会承担这些代价

One channel per agent. A plain copy under
```
~/.claude/skills/<name>
```
beats the plugin of the same name and serves its frozen version forever.
Never vendor skills into a product repository. They are installed on the machine; a repo copy is 47 MB of a third party's text your CI now lints.
Skills and plugins load at session start — restart the agent after changing either, or it keeps the old set.
After any install or removal, the check that must print nothing:

bash

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

CLI surface read from
metavr --help
at 1.3.2.2.2 on 2026-09-20; the install and init behaviour was measured on this machine the same day.

每个 Agent 只使用一个通道。 放在
```
~/.claude/skills/<name>
```
下的普通副本优于同名 plugin，并且会一直提供其冻结版本。
绝不把 skills 拷贝进产品仓库。 Skills 应安装在机器上；仓库副本会带来 47 MB 的第三方文本，而 CI 之后还会对其进行 lint。
Skills 和 plugins 在 session 开始时加载——修改任一项后都要重启 Agent，否则它仍会使用旧版本集合。
每次安装或卸载后，以下检查必须不输出任何内容：

bash

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
读取；安装和 init 行为于同日在这台机器上实测。

Triggers

触发词

More phrases that route here: "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".

以下更多短语也会路由到这里（触发词保留原文）：“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”。

quest-tooling

Original

Translation

The Quest toolchain: one CLI, two interfaces, one channel per agent

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

Install it once, through one channel

一次安装，只用一个通道

`metavr init`
is the trap, not the setup

`metavr init`
是陷阱，而不是正确的设置方式

The command map

命令映射

The MCP server, and how it ends up registered twice

MCP server，以及它为何会被注册两次

Meta's 29 skills, and what this pack adds

Meta 的 29 个 skills，以及本 skill 包补充了什么

No headset on the desk

桌面上没有头显时

Managed developer tools

托管的开发工具

Hygiene, because the estate pays for it later

维护规范，因为当前环境最终会承担这些代价

Triggers

触发词