> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/vision/troubleshooting-and-diagnostics.md).

# 排查视觉问题

请从上到下阅读本页。Vision 失败大致分为四类：连接配置错误、帧源故障、平台特定限制或 WebGL 来源策略。

### 快速检查清单

在深入具体问题之前，请按顺序验证以下五项：

{% stepper %}
{% step %}

#### 确认 Connection Type 是 Video

选择 `ConvaiRoomManager` 在 Hierarchy 中。确认 **连接类型** 设置为 **视频**. `ConvaiVisionPublisher` 在 Connection Type 为 `音频` 时保持完全空闲——它会记录一条消息并正常返回。
{% endstep %}

{% step %}

#### 确认房间已连接

`ConvaiVisionPublisher` 在房间连接之前不会发布。请在 Console 中查看 `[ConvaiRoomManager]` 连接日志。确认 `ConvaiManager.ActiveManager` 在运行时不是 null。
{% endstep %}

{% step %}

#### 确认已存在帧源

在原生平台（非 WebGL）上， `ConvaiVisionPublisher` 需要帧源。确认 `CameraVisionFrameSource`, `WebcamVisionFrameSource`，或一个自定义的 `IVisionFrameSource` 位于同一个 GameObject 上，或其子对象上。请查看 Console 中的：

```
[ConvaiVisionPublisher] 未找到 IVisionFrameSource。
```

{% endstep %}

{% step %}

#### 确认帧源处于 Ready

在运行时打开 Inspector 中的帧源组件。确认 `State` 为 `Ready`. 如果它是 `Failed`，请检查 `ErrorKind` 和 `StatusMessage` 在 Inspector 或 Console 中。
{% endstep %}

{% step %}

#### 将 VisionDebugPreview 添加到任意场景 GameObject。按下 Play。若覆盖层显示实时图像并且

添加 `VisionDebugPreview` FPS > 0 `，则数据流已到达发布器。如果覆盖层为空白或 FPS 一直为零，则帧源未在生成帧——继续查看`帧源问题 [帧源问题](#frame-source-issues) 下方。
{% endstep %}
{% endstepper %}

### 常见问题

| 症状                        | 可能原因                                                                     | 修复方法                                                                                                                                       | 验证                                                                                                                                                                                                            |
| ------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `IsPublishing` 保持 `false` | Connection Type 为 `音频`                                                   | 将 **连接类型** 到 **视频** 在 `ConvaiRoomManager`.                                                                                                 | 确认 `IsPublishing` 变为 `true` 在将 Connection Type 切换为 Video 并重新连接后。                                                                                                                                              |
| `IsPublishing` 保持 `false` | 房间未连接                                                                    | 等待连接，或检查 API key / 网络。                                                                                                                     | 检查 Console 中的 `[ConvaiRoomManager]` 连接日志并确认 `ConvaiManager.ActiveManager` 不是 `null`.                                                                                                                          |
| `IsPublishing` 保持 `false` | 未找到帧源                                                                    | 添加 `CameraVisionFrameSource` 到同一个 GameObject 或其子对象。                                                                                        | 确认 Console 不再记录 `[ConvaiVisionPublisher] 未找到 IVisionFrameSource。`                                                                                                                                             |
| 调试覆盖层为空白，FPS = 0          | 帧源中的 `Failed` state                                                      | 检查 `ErrorKind` ——参见 [帧源问题](#frame-source-issues).                                                                                          | 确认 `State` 在帧源组件上 `Failed` 应用下方对应修复后会退出                                                                                                                                                                       |
| 数据流是黑屏                    | 错误的 `CameraCaptureMode` ，用于渲染管线                                          | 参见 [黑屏数据流](#black-feed).                                                                                                                   | 确认 `VisionDebugPreview` 在切换模式后覆盖层显示非黑色图像。                                                                                                                                                                     |
| `SrpNative` 已选中           | 未实现的后端                                                                   | `CameraVisionFrameSource` 立即进入 `Failed` 状态——请使用 `ExplicitRenderCompatibility` 用于 SRP/URP。                                                  | 确认 `State` 不再报告 `Failed` 和 `ErrorKind = UnsupportedPlatform`.                                                                                                                                                 |
| 摄像头无法打开                   | 权限被拒绝（Android / iOS）                                                     | 声明 `android.permission.CAMERA` 在 manifest 中；在 `NSCameraUsageDescription` 中添加                                                               | 确认 `State` 不再报告 `PermissionDenied` ，并且在权限对话框被授予后摄像头预览会出现。                                                                                                                                                     |
| Quest 数据流未开始              | 缺少 manifest 权限                                                           | 同时声明 `horizonos.permission.HEADSET_CAMERA` 和 `android.permission.CAMERA`.                                                                  | 确认旁路传输捕获已开始，并且 `State` 到达 `Ready` 在重新部署并声明这两项后。                                                                                                                                                               |
| Quest 数据流未开始              | 错误的硬件                                                                    | `QuestVisionFrameSource` 需要 Quest 3 或 3S。Quest 2 和 Quest Pro 不受支持。                                                                         | 确认目标设备是 Quest 3 或 3S—— `State` 在不受支持的硬件上无法到达 `Ready` ，无论权限如何。                                                                                                                                                 |
| WebGL 数据流未发布              | 非 HTTPS 来源                                                               | 部署到 HTTPS。 `http://localhost` 是唯一例外。                                                                                                       | 确认部署的 URL 使用 `https://` （或者是 `http://localhost`).                                                                                                                                                             |
| WebGL 数据流未发布              | 已分配帧源                                                                    | 在 WebGL 上帧源会被忽略——移除它或留空；发布器使用 `canvas.captureStream()`.                                                                                    | 确认 `IsPublishing` 变为 `true` 在移除帧源引用后。                                                                                                                                                                         |
| WebGL 上调试覆盖层为空白           | 符合预期——没有 RenderTexture                                                   | `VisionDebugPreview` 在 WebGL 上没有可显示的纹理。通过 `IsPublishing` 替代。                                                                               | 确认 `IsPublishing` 为 `true` 进行验证，即使覆盖层保持空白。                                                                                                                                                                    |
| 采样窗口对帧选择没有影响              | 某个 **Sampling Windows** 条目具有 **Count** 已设为 **Interval Ms** 保持为 `0` （或相反） | 将这两项都设为 **Count** 和 **Interval Ms** 中每个条目的非零值 **Sampling Windows** 在 `ConvaiRoomManager` （或者 `ConvaiRoomManagerProfile` 资源）而不是把某个字段留为 `0`. | 确认 Inspector 中两个字段都显示非零值。丢弃的窗口不会记录 Console 警告——SDK 只会在窗口数量超过 **Frames Per Turn** 预算时发出警告——因此静默并不能确认窗口已发送。                                                                                                     |
| 响应模式变更没有可见效果              | `UpdateRespondMode` 返回了 `false`，或者后端拒绝了请求                                | 检查 `bool` 的返回值 `UpdateRespondMode` ，再假定它已生效之前；仅在 `IsConnected` 为 `true`时调用它。订阅 `RespondModeUpdateResultReceived` 并检查 `Status` 和 `消息`.      | 确认 `RespondModeUpdateResultReceived.Status` 为 `"success"` 和 `Modality` / `模式` 是否与请求的通道和模式匹配。参见 [Vision 脚本 API](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/vision/scripting-api.md) 了解事件订阅模式。 |

### 帧源问题

#### 黑屏数据流

在 `CameraVisionFrameSource` 上出现黑屏（覆盖层可见但所有像素都是黑色）

| 表示活动渲染管线使用了错误的捕获后端。     | 渲染管线                                   | 推荐模式                                                      |
| ----------------------- | -------------------------------------- | --------------------------------------------------------- |
| 内置渲染管线                  | `自动` 原因 `（使用`)                         | `BuiltInHooks` / `Camera.onPreRender` Camera.onPostRender |
| 钩子可以正常工作。               | `自动` 原因 `ExplicitRenderCompatibility`) | URP / SRP `Explicit` 中的 `LateUpdate` ——可在所有 SRP 版本上工作。    |
| 在 Auto 下出现黑屏的 URP / SRP | `ExplicitRenderCompatibility`          | 强制使用显式渲染路径；可解决自定义 SRP 配置下的黑屏。                             |

{% hint style="danger" %}
不要选择 `SrpNative`。此 SDK 版本中未实现它。选择它会导致 `CameraVisionFrameSource` 立即进入 `Failed` 状态，并显示 `ErrorKind = UnsupportedPlatform`.
{% endhint %}

#### 未分配摄像头

如果 **目标摄像机** 为空，且场景中没有任何摄像机标记为 **MainCamera**, `CameraVisionFrameSource` 立即进入 `Failed` 状态，在启动时：

```
ErrorKind = InvalidConfiguration
StatusMessage = "未分配摄像机且 Camera.main 为空"
```

修复：将摄像机分配到 **目标摄像机** 字段，或将一台摄像机标记为 **MainCamera**.

#### 摄像头权限被拒绝

在 Android 和 iOS 上， `WebcamVisionFrameSource` 会在 `StartCapture()`请求摄像头权限。如果用户拒绝：

```
State = Failed
ErrorKind = PermissionDenied
```

**Android：** 验证 `AndroidManifest.xml` 声明 `android.permission.CAMERA`.\
**iOS：** 验证 `Info.plist` 包含 `NSCameraUsageDescription` 且字符串非空。

如果用户之前已拒绝过权限，系统不会再次显示对话框。请引导用户前往设备的 设置 应用重新启用。

#### Quest 旁路传输未开始

`QuestVisionFrameSource` 需要 manifest 权限和正确的硬件。

所需的 manifest 条目：

```xml
<uses-permission android:name="horizonos.permission.HEADSET_CAMERA" />
<uses-permission android:name="android.permission.CAMERA" />
```

如果没有这两个声明，旁路传输捕获会静默失败，且帧源会进入 `Failed` 状态。设备不会显示权限对话框——而是直接拒绝访问。

支持的硬件：仅限 Meta Quest 3 和 Quest 3S。Quest 2 和 Quest Pro 不会公开 `PassthroughCameraAccess`.

### 决策树

```mermaid
flowchart TD
    A[IsPublishing = false?] --> B{Connection Type = Video?}
    B -- 否 --> B1[将 ConvaiRoomManager 上的 Connection Type 设为 Video]
    B -- 是 --> C{房间已连接？}
    C -- 否 --> C1[检查 API key、网络、Console 中的连接错误]
    C -- 是 --> D{找到帧源？}
    D -- 否 --> D1[将 CameraVisionFrameSource 添加到同一个 GameObject 或其子对象]
    D -- 是 --> E{帧源 State = Ready？}
    E -- 否 --> F{ErrorKind？}
    F -- InvalidConfiguration --> F1[分配 Target Camera 或标记 MainCamera]
    F -- PermissionDenied --> F2[添加 manifest 权限；引导用户到 Settings]
    F -- UnsupportedPlatform --> F3[检查是否未选择 SrpNative；Quest 源需要 Quest 3/3S]
    F -- DeviceUnavailable --> F4[检查摄像头设备名称；验证硬件已连接]
    E -- 是 --> G{数据流是黑屏？}
    G -- 是 --> G1[将 Camera Capture Mode 切换为 ExplicitRenderCompatibility]
    G -- 否 --> H[IsPublishing = true — 检查 VisionDebugPreview 覆盖层]
```

### 启用帧健康探针

对于持续空白或黑屏且不会产生 `Failed` 状态的情况，请在 `CameraVisionFrameSource`:

1. 选择 **ConvaiVisionRoot** GameObject 上启用诊断探针。
2. 开启 `CameraVisionFrameSource`，启用 **启用诊断帧健康探针**.
3. 按下 Play 并查看 Console。

该探针每帧执行一次同步 GPU 到 CPU 的像素回读并记录结果。这可确认 `RenderTexture` 是否包含图像数据，还是确实为空白。

{% hint style="warning" %}
禁用 **启用诊断帧健康探针** 在发布之前。它每帧执行一次同步 GPU 回读，会导致 GPU 管线停顿并显著降低帧率。
{% endhint %}

### 日志记录

所有 Vision 日志消息都使用 `LogCategory.Vision`。将日志级别设为 `Verbose` 中的 **Tools → Convai → Configuration → Logging** 以查看所有状态转换、帧源发现和发布事件。

| 前缀                           | 组件                      |
| ---------------------------- | ----------------------- |
| `[ConvaiVisionPublisher]`    | 发布器生命周期、帧源发现、策略变更       |
| `[VisionPublishCoordinator]` | 跟踪打开/关闭、帧路由             |
| `[CameraVisionFrameSource]`  | 摄像头捕获后端选择、状态转换          |
| `[WebcamVisionFrameSource]`  | 设备打开、权限请求、状态转换          |
| `[QuestVisionFrameSource]`   | Passthrough API 绑定、状态转换 |
| `[VisionDebugPreview]`       | 帧源发现、备用切换               |

### 下一步

如果这里未涵盖该问题，请订阅 `VisionCaptureStopped` 和 `VideoTrackUnpublished` 并记录 `原因` 和 `错误消息` 字段。参见 [Vision 脚本 API](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/vision/scripting-api.md) 了解事件订阅模式。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/vision/troubleshooting-and-diagnostics.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.