hz-quest-verify-first

请先核实 — Meta Quest 开发

阅读其余内容前需要了解的信息

接下来会让你调用一些可能不熟悉名称的工具。请先阅读本节，以便理解后续内容。

• Meta Quest 是 Meta 的独立式 VR／混合现实头显系列（Quest 2、Quest 3、Quest 3S、Quest Pro）。它们运行基于 Android 的操作系统。
• Horizon OS 是该操作系统的名称。它源自 Android 分支，搭载于每款 Quest 头显上，并由 Meta 按自己的节奏更新（与上游 Android 分开）。许多 API 是 Horizon OS 专属的，在原生 Android 中没有对应功能。
• metavr（“Meta VR CLI”）是 Meta 发布的 Rust 命令行工具，以独立二进制文件形式提供，也可通过 npm 使用 metavr。使用 metavr <args> 调用（无需安装时可使用 npx -y metavr <args>；npx 始终会获取最新发布版本）。它将 adb 和 Meta 的开发者 API 封装为更高级的命令，用于 Meta VR 设备开发：列出设备、安装应用、捕获 Perfetto 跟踪记录、搜索 Meta VR 文档、查询 3D 资源库、自动执行 UI 交互等。metavr 是 Meta VR 开发工作的主要操作层，相当于 GCP 中的 gcloud 或源代码管理中的 git。
• metavr MCP server 是 metavr 的内置模式，可通过 Model Context Protocol 向 AI 编码 Agent 提供一组精简工具。此技能相关的工具包括：
  • vr_docs_search — 搜索 Meta 官方开发者文档
  • vr_docs_get_page — 获取指定文档页面的全文
  • device — 查询和控制已连接的 Meta VR Glasses 和 Meta Quest 头显（列表、信息、连接、重启、电池、控制器、接近传感器等）
  • app — 查询和管理已安装的应用（列表、信息、安装、卸载、启动、停止、清除）
  • files — 对已连接的 Meta VR 设备执行文件操作（ls、push、pull、rm、mkdir）
  • run — 用于调用没有专用工具的任意 metavr 子命令的通用入口（perf、ovrmetrics、ui、audio、casting、window、unity、sideload、asset、config 等）。其 JSON Schema 由 clap 生成，因此工具定义中会显示可用子命令及其类型化参数。
  • cli_help — 以 Markdown 格式查找 metavr 子命令和标志
• 你可能不熟悉、但 Quest 项目中常用的 Meta SDK：Meta XR All-in-One SDK（Unity）、Meta XR Core／Interaction／Platform／Voice／Movement SDK、Meta Spatial SDK（Kotlin／Android 面板）、IWSDK（用于 WebXR 的 Immersive Web SDK）、MRUK（Mixed Reality Utility Kit）、Presence Platform、Horizon Platform SDK。这些 SDK 按各自的发布节奏更新，与 Quest OS 分开。Meta Spatial SDK 是沉浸式 Android／Kotlin 开发路径；普通的 2D Android 面板应用不需要它。
• OVR 与 Meta XR — 较早的 Quest Unity 内容和大多数公开网络资料使用 OVR 命名空间及 “Oculus Integration” Unity 软件包。两者都已弃用，改由 Meta XR All-in-One SDK 系列取代。大多数训练数据仍会推荐这些已弃用的名称。推荐此领域的内容前，请先核实。

此技能存在的原因

Meta Quest 和 Horizon OS 发展迅速。Meta SDK 每隔几周就会发布新版本。API 在正式发布前就会更名。清单权限和商店政策每月都会更新。整个 SDK 系列（Meta Spatial SDK、IWSDK、Horizon OS shell）都晚于大多数 LLM 训练语料的时间。

你几乎可以肯定，对 Quest 相关细节的了解已经过时。 你记得的包名已经更名。Unity 菜单路径已经变动。之前 Horizon OS 版本上可用的设置步骤，在当前版本上可能会悄然失效。你惯用的 “OVR” 命名空间已拆分到六七个 Meta XR 包中。

如果你回答 Meta Quest 相关问题，或编写面向 Quest 的代码，却没有先核实，就会产生幻觉。用户直到构建失败、应用被商店拒绝，或 AndroidManifest 无法发布时才会发现问题。

此技能是必须通过的关卡。请将其视为前提，而不是建议。

何时适用此技能

如果当前任务符合以下任一条件，你 MUST 执行下方的验证流程：

• 用户提到 Meta Quest、Quest 2 / 3 / 3S / Pro、Oculus、Horizon OS、MR、VR、XR、OpenXR（在 Quest 上）、Meta SDK、Meta XR、OVR、Spatial SDK、IWSDK、MRUK、Movement SDK、Voice SDK、Presence Platform、Horizon Platform SDK、手部追踪、透视、锚点、场景网格、投屏、眼动追踪、身体追踪、控制器或平台合规性 / 商店政策
• 仓库包含以下任意内容：
  • Unity 文件中的 OVRPlugin、"Meta XR All-in-One SDK"，或 manifest.json / Packages/manifest.json 中的 com.meta.xr.*
  • Spatial SDK Gradle 插件（com.meta.spatial.plugins.*）
  • 包含 com.oculus.*、com.meta.quest.* 或 horizon 功能声明的 AndroidManifest
  • 以 com.meta.* 或 com.oculus.* 开头的包 ID
  • 表明使用 Unity 的 .meta 文件，或 Quest_*.uplugin / *.unrealhxr 文件
• 用户的问题引用了 developers.meta.com/horizon、developer.oculus.com、oculus.com/sparkle-updates 或任何 Meta Quest 文档 URL
• Agent 即将推荐任何 Meta SDK API、命名空间、包或 AndroidManifest 权限
• Agent 即将回答关于应用审核、Meta Horizon Store 提交、商店就绪或发布要求、内容评级或分发的问题
• Agent 即将编写针对特定设备的 adb 命令
• Agent 即将断言用户的 Meta VR 设备上安装了或未安装什么

如果不确定，答案就是 YES——执行验证流程。

验证流程

步骤 1 — 确定构建路径

在选择 SDK、文档范围或专业技能之前，先对项目进行分类：

构建路径	特征	路由至
标准 Android	Activities、Views、Compose、React Native、Expo，或在系统面板中呈现的现有手机／平板应用	hz-android-2d-porting；React Native 或 Expo 项目使用 hz-react-native-expo；新应用使用 hz-new-project-creation
Meta Spatial SDK	com.meta.spatial 依赖项或沉浸式 Kotlin／Android 场景	hz-spatial-sdk；设置使用 hz-new-project-creation
Unity	Unity 项目文件或 Meta XR Unity 软件包	现有项目使用 hz-unity-project-analyzer；核心 SDK 设置使用 hz-unity-meta-core-sdk；新应用使用 hz-new-project-creation
Unreal Engine	.uproject 文件、Unreal 模块或 Meta XR Unreal 插件	新应用使用 hz-new-project-creation；目前尚无专用技能，因此使用步骤 2 并设置 scope="unreal"；模拟使用 hz-xr-simulator-install-and-configure
原生 OpenXR	直接使用 OpenXR loader 的 C/C++ 或 NDK 应用	目前尚无专用技能；使用步骤 2 并设置 scope="native"；模拟使用 hz-xr-simulator-install-and-configure
WebXR	通过浏览器交付的沉浸式内容或 IWSDK	hz-iwsdk-webxr；PWA 交付使用 hz-store-pwa；新应用使用 hz-new-project-creation

不要仅仅因为目标设备是 Quest，就将 Meta Spatial SDK 添加到标准 Android 应用中。如果特征有所重叠，请按以下顺序分类：

1. 存在 com.meta.spatial 依赖项或 Gradle 插件 -> Meta Spatial SDK
2. 存在 Unity 项目文件 -> Unity
3. 存在 .uproject 或 Unreal 模块 -> Unreal Engine
4. 直接从 C/C++ 或 NDK 使用 OpenXR loader -> 原生 OpenXR
5. 使用 IWSDK 或通过浏览器交付项目 -> WebXR
6. 其他情况：使用 Activities、Views、Compose、React Native 或 Expo 的 Android 应用 -> 标准 Android

步骤 2 — 对照权威文档进行验证

在撰写或推荐任何 Quest 相关内容之前，调用 vr_docs_search MCP 工具。如果 MCP 不可用，请使用等效的 metavr CLI 命令 metavr docs search。

MCP：

vr_docs_search(
  query="<the specific claim or API you are about to make>",
  scope="auto",   # or unity / unreal / spatial_sdk / android / native / web /
                  #    policy / distribution / design
  mode="verify"
)

CLI：

metavr docs search "<query>"

如果需要准确措辞（清单条目、完整 API 签名、商店政策文本、代码片段），请根据验证返回的 canonical_url 或 doc_path，继续调用 vr_docs_get_page。当准确性至关重要时，绝不要改述被截断的 片段。

CLI：

metavr docs fetch "<canonical_url_or_path>"

步骤 3 — 验证用户的实际环境

在建议命令应针对哪台设备、声称某个应用已安装、推荐 adb 命令，或编写安装／启动／ 侧载步骤之前，先查询用户实际由 metavr 管理的环境。

MCP：

device(action="list")                        # ALWAYS start here
device(action="info", target="<serial>")
app(action="list", target="<serial>")
app(action="info", package="<package>")
run(subcommand=["config", "show"])           # catch-all for misc reads

CLI：

metavr device list
metavr device info <serial>
metavr app list -d <serial>
metavr app info <package>
metavr config list

用户可能有零台、一台或多台通过 USB 和 WiFi 连接的 Meta VR 设备——多种 Quest 机型、开发套件、侧载构建版本，以及固定使用的旧版 Horizon OS。 你的训练数据无法看到这些信息。

步骤 4 — 不确定时，发现 metavr 的功能

如果你不知道哪个 metavr 子命令或 run 调用适用于用户的请求，请先调用 cli_help（MCP）或 metavr --markdown-help（CLI）。 不要臆造标志或子命令——metavr 每次发布都会增加新功能，而你的训练数据并不包含这些内容。

对于长尾子命令（perf、ovrmetrics、ui 等）， run 工具的输入架构会通过 JSON Schema oneOf 枚举所有子命令路径及其类型化参数。你可以直接从工具定义中读取，而不必猜测。

MCP：

cli_help(topic="perf")   # focused help for a subcommand tree
cli_help()               # full top-level command tree

CLI：

metavr --markdown-help
metavr perf --help

跳过验证会导致的特定故障

以下是具体且反复出现的问题，验证流程可以避免这些问题：

• 已弃用的 API 编译通过，但在运行时不起作用。 OVR 命名空间中的函数名称曾在一个版本中转发，下一版本就被移除。代码看起来正确，构建顺利，运行时也没有报错，但在设备上没有任何可观察到的行为。
• AndroidManifest 权限声明导致应用被 Meta Horizon Store 拒绝。 所需的权限名称已更改；你“知道”需要的权限现在已无法识别；新的强制功能标志缺失。
• 不存在的 Meta SDK 软件包名称。 Meta XR All-in-One SDK 是一系列 UPM 软件包，其名称因版本而异；猜测名称会导致“找不到软件包”错误。
• 过时教程中的 Unity 菜单路径。 Meta XR 菜单项会随 SDK 版本变化；引用 Oculus → ... 的设置步骤现在可能位于 Meta XR → ... 下，也可能已被完全移除。
• 公开发布前已重命名的 Spatial SDK 类名。 Spatial SDK 在后期调整了其公共 API；旧博客文章或训练数据中的许多类名和方法名都是错误的。
• 在先前 Horizon OS 版本上可用的透视 / 锚点 / 场景网格设置。 权限流程、系统叠加层 API 和清单功能会随 Quest OS 版本变化。去年教程中的做法在当前 Horizon OS 上可能会悄无声息地失效。
• 列出但 Quest 运行时不支持的 OpenXR 扩展。 通用 OpenXR 文档会列出 Meta 尚未实现的扩展。务必根据 Meta 文档进行验证，而不是依据 OpenXR 规范。
• 目标设备错误。 未先列出设备就推荐 adb shell 命令，之后只能看着命令失败或在错误的设备上执行。
• 过时的商店政策声明。 审核要求、评级类别和分发规则都会更新——回答用户关于提交的问题前，请先验证。

反模式

请勿进行以下任何操作：

• 因为“你记得”答案，就不先调用 vr_docs_search 来回答 Meta Quest 问题
• 未先调用 device(action="list") 查看已连接设备，就推荐 adb shell 命令
• 在验证调用可以消除歧义时，仍根据训练数据猜测软件包名称、命名空间或类名
• 对清单条目、API 签名或商店政策的验证结果片段进行转述，而这些内容需要精确措辞时（请使用 vr_docs_get_page）
• Meta 的权威文档只需调用一个工具即可获取，却仍去开放网络搜索 Meta Quest 文档
• 因为“文档里大概是这么说的”就跳过验证——先验证，再给出答案
• 假设 metavr 没有用户所需的子命令——先检查 cli_help

语气与呈现方式

完成验证后，请在回答中提供引用，并简要说明文档的时效性。用户为验证步骤付费——请让用户知道你确实执行了验证。

Per the current Meta Spatial SDK docs (verified just now via
vr_docs_search):

  <answer grounded in retrieved content>

Source: <canonical_url returned by the tool>

这既能证明验证已执行，也能让用户逐渐信任经过验证的回答，而不是凭记忆给出的回答。

如果 metavr MCP 工具不可用

如果 Agent 宿主未安装 metavr MCP 服务，请改用 metavr CLI（使用相同的权威后端和内容；如果使用 npm 发行版而不是独立二进制文件，请在命令前加上 npx -y），并告知用户一次如何安装 MCP 服务，以便下次使用：

metavr mcp install <your-tool>   # claude-code | cursor | claude-desktop | vscode | ...
metavr mcp install project       # install at the repo root for this project only

验证步骤是必需的，不可跳过——即使 MCP 服务尚未接入，也要在第一个问题上通过 metavr docs search "<query>" 执行验证。

相关技能

• metavr-cli — 完整的 metavr CLI 参考（命令、标志、示例）
• hz-vr-debug — 使用日志和屏幕截图进行设备端调试
• hz-perfetto-debug — 分析 Perfetto 跟踪，排查卡顿、GPU 和 CPU 瓶颈
• hz-store-submit — 端到端提交应用至 Meta Horizon Store（包含商店就绪情况检查）
• hz-android-2d-porting — 将标准 Android 应用适配为 Horizon OS 面板
• hz-react-native-expo — 在标准 Android 路径上运行 React Native 和 Expo 应用
• hz-new-project-creation — 针对特定构建路径的新 Android 项目设置
• hz-spatial-sdk — Meta Spatial SDK API 指南
• hz-platform-sdk — Horizon Platform SDK API 指南
• hz-xr-simulator-install-and-configure — 为 Unity、Unreal 和原生 OpenXR 项目安装并配置模拟器
• hz-unity-project-analyzer — 检查并分类现有的 Unity 项目
• hz-unity-meta-core-sdk — 在 Unity 中设置 Meta XR Core SDK
• hz-iwsdk-webxr — 使用 IWSDK 构建沉浸式 WebXR 体验
• hz-store-pwa — 将 WebXR 体验打包并作为 PWA 分发