React Native VisionCamera v5…

在 React Native 项目中使用或从 v4 迁移到 VisionCamera v5 时，按任务路由到对应参考文档并遵守 v5 新 API 规则。

适用场景

解决思路

1. 按任务加载对应参考文档：新安装/上屏/权限/最小样板 → references/quickstart-v5.md；从 v4 迁移 → references/migration-v4-to-v5.md（用户提到 v4、takePhoto、useCameraFormat、format prop、photo/video 布尔 props 或核心 CodeScanner 时优先加载）；整屏迁移模板 → references/migration-templates.md；输出与约束选择 → references/outputs-and-constraints.md；帧处理器/worklet/异步帧/像素格式/原生插件 → references/frame-processors.md；拍照/录像/手动 AE/AF/AWB/曝光/变焦/对焦 → references/capture-and-controls.md；深度流/多摄/Skia 预览/GPU 缩放/条码/GPS/自定义原生输出 → references/advanced-features.md；不确定时加载 migration-v4-to-v5.md。
2. 安装 Nitro 依赖：必须安装 react-native-nitro-modules 和 react-native-nitro-image；使用帧处理器时还需 react-native-vision-camera-worklets 和 react-native-worklets（Software Mansion 的，不是 -core）。
3. 用 outputs={[...]} 替代 photo/video/frameProcessor/codeScanner props：通过 usePhotoOutput、useVideoOutput、useFrameOutput、useDepthOutput、useObjectOutput（或条码包的 useBarcodeScannerOutput）创建输出并传入数组；capturePhoto、createRecorder 等方法在 Output 上，不在 Camera ref 上。
4. 不再使用 format prop 和 useCameraFormat：改用 constraints={[...]}，数组顺序即优先级（降序），Camera 自动协商最接近的配置，不可能满足的约束（如 { fps: 99999 }）不会抛错。
5. 不再使用 takePhoto()：用 photoOutput.capturePhoto(settings, callbacks) 获取内存中的 Photo，或用 photoOutput.capturePhotoToFile(...) 获取文件路径；默认走内存路径，除非明确要求否则不要写临时文件。
6. 帧处理器插件必须是 Nitro Modules：v4 的 FrameProcessorPlugin 基类、VISION_EXPORT_SWIFT_FRAME_PROCESSOR 宏和 VisionCameraProxy.addFrameProcessorPlugin 已移除；v5 插件是带类型化 Nitro spec 的 HybridObject。
7. 每个 Frame（和 Depth）必须调用 .dispose()：缓冲池有限，泄漏帧会阻塞管线；用 try { ... } finally { frame.dispose() } 包裹；通过 asyncRunner.runAsync(...) 卸载时，若返回 true 则在异步回调内 dispose，若返回 false 则在 else 分支立即 dispose。
8. CodeScanner 不在核心包中：react-native-vision-camera-barcode-scanner 是独立包，两端基于 MLKit；仅 iOS 的对象检测（QR、人脸、人体，走原生 AVFoundation metadata，无 ML 依赖）用核心的 useObjectOutput。
9. 保持 Camera 挂载，通过切换 isActive 控制：重新挂载会销毁会话；结合 react-navigation 的 useIsFocused()，使不在屏幕时会话从 Idle → Ready，并保持偏好以便快速恢复。
10. 帧输出 pixelFormat 默认是 'native'（零拷贝），不是 'yuv'：'native' 以会话协商的 nativePixelFormat 流式传输且零转换（可能解析为 YUV、RGB、RAW 或 'private'，通过 frame.pixelFormat 验证实际格式）；'yuv' 选择最接近原生的 YUV 格式，是通用 CPU 可访问的最佳选择（MLKit/OpenCV/Skia）；'rgb' 强制 YUV 转 RGB，带宽约多 2.6 倍，仅在消费者硬性要求 RGB 时使用；useDepthOutput 没有 pixelFormat 选项；对需要 CPU 可见 RGB 或张量输入的 ML 消费者，优先用 react-native-vision-camera-resizer，而不是在 Camera 管线中每帧付 RGB 转换成本。
11. 不要用 Math.min/Math.max 手动钳制 FPS/分辨率：那是 v4 的变通做法；v5 的 Constraints API 内部协商，表达意图让 Camera 选择。
12. v5 中 worklet 直接修改 Reanimated SharedValues：适用于普通异步 UI 或动画状态；帧锁定叠加层请用独立的实时技能，并用 Skia 或 WebGPU 从同一帧绘制。
13. 不要臆造 v4→v5 的 API 形态：若 v4 API 在参考文档中没有对应的 v5 等价物，直接说明并链接 https://visioncamera.margelo.com，不要猜测。
14. 除非用户要求，不要添加文档文件（README、CHANGELOG）。
15. 默认假设用户使用 v5，除非他们展示 v4 代码；若展示 v4 代码，先加载 references/migration-v4-to-v5.md 再写任何内容。
16. 编写新 Camera 示例时默认用基于 hook 的声明式写法（useCameraPermission + useCameraDevice + usePhotoOutput + <Camera />）；仅在用户要求多摄或完全程序化控制时用命令式 VisionCamera.createCameraSession(...)。
17. 对需要 CPU 可见输入的基础 ML 路径，推荐 react-native-vision-camera-resizer 而非 v4 时代的 vision-camera-resize-plugin；延迟敏感的 ML、GPU 推理和实时叠加层路由到 react-native-vision-camera-realtime，而不是普遍推荐 Resizer。
18. 验证 peer 依赖安装：安装后出现原生崩溃的用户，95% 是漏装了 react-native-nitro-modules、react-native-nitro-image，或（帧处理器场景）react-native-worklets + react-native-vision-camera-worklets。
19. 生产级低延迟 GPU、ML、CV 或帧耦合叠加层工作使用独立的 react-native-vision-camera-realtime 技能；仅在同时需要基础设置或 API 基础时再加载基础帧处理参考。

适用边界 · 注意事项

• 生产级低延迟 GPU、ML、CV 或帧耦合叠加层管线应使用独立的 react-native-vision-camera-realtime 技能，而非本技能。
• 不要一次加载所有参考文档：每个参考都是自包含的，只加载任务所需的那一个。
• 不要为 v4 中已移除的 API 猜测 v5 等价物，也不要添加用户未要求的文档文件。