用途
hz-vr-debug 是一个用于调试 Meta VR、MR 及 Android 应用的技能，通过 metavr 命令行接口操作。它适用于调试连接中的 Meta VR 设备上运行的应用、查看实时或历史应用日志（logcat）、抓取 VR/MR 视图截图、诊断应用崩溃、渲染故障或性能问题，以及排查追踪、手柄、音频或权限问题。该技能适用于运行 Horizon OS 的 Meta VR Glasses 和 Meta Quest 头显（Quest 2、Quest 3、Quest 3S、Quest Pro）。
前提条件
使用前需确保：metavr CLI 已安装并在 PATH 中，或通过 npx 调用（发布为 npm 包 metavr）；Meta VR 设备通过支持数据传输的 USB-C 线连接；在手机的 Meta Horizon 应用中开启开发者模式；首次连接时在头显中接受“允许 USB 调试”提示。
快速开始
# 1. 验证设备已连接并识别
metavr device list
# 2. 列出当前安装的应用
metavr app list
# 3. 查看实时日志（最近 100 行）
metavr log
# 4. 抓取当前 VR 视图截图
metavr capture screenshot
主要命令
设备命令：metavr device list、device info <id>、device battery、device wake、device reboot、device connect <ip>。
日志命令：metavr log、log -n 500、log --tag Unity、log --level E、adb logcat、adb logcat --follow。
应用命令：app list、app info <package>、app launch <package>、app stop <package>、app clear <package>、app install <apk>、app uninstall <package>。
抓取命令：capture screenshot、capture screenshot -o file.png。
文件命令：files ls /sdcard/、files pull、files push、files rm、files mkdir。
常见调试工作流
典型流程为：连接并验证设备、识别应用包名、复现问题并捕获日志、抓取视觉状态、分析诊断、迭代修复。诊断时关注 FATAL EXCEPTION、native crash / SIGABRT / SIGSEGV、ANR、OOM 等特征。
症状诊断决策树
技能提供了覆盖以下症状的诊断决策树：应用启动崩溃（包名错误、ClassNotFound、SecurityException、空指针、原生崩溃、被系统杀死）、应用冻结/ANR（主线程阻塞、后台服务超时）、头显黑屏（应用未运行、VrApi 未初始化、着色器编译、渲染 API 问题）、掉帧/卡顿（FPS 检查、GC 暂停、热节流、主线程资源加载）、追踪问题（手柄配对、手部追踪权限、光照、遮挡）以及音频问题（输出设备、空间音频、缓冲欠载）。
常见陷阱
Logcat 环形缓冲很快填满，需在复现问题前开始记录；USB 线质量重要，部分线仅支持充电；WiFi 调试在设备休眠后会断开；发布版本会剥离日志，调试时应使用 debug 构建；Unity 可能使用 Unity、il2cpp、mono 等多个标签；OVR Metrics Tool 叠加层可能干扰应用渲染或输入。
最佳实践
使用严重级别和标签过滤日志、搜索崩溃特征、检查权限声明（如 HAND_TRACKING、USE_SCENE、RECORD_AUDIO、CAMERA）、进行性能调试（检查电池与热状态、热节流消息、VrApi 帧时序）。
限制
本文档未提供 metavr CLI 的具体安装步骤、版本信息、收费情况或价格；部分命令参数（如 --filter、--regex、--buffer 等）在资料中提及但未完整展开说明。