> 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/scene-metadata/troubleshooting-and-diagnostics.md).

# 排查场景元数据问题

大多数场景元数据问题都属于以下三类之一：有效载荷从未发送、有效载荷已发送但对象被排除，或者描述过于模糊，导致 AI 无法有效使用。

### 第一线排查

启用 **日志统计** on `ConvaiSceneMetadataCollector` （默认已开启）并在进入 Play Mode 后检查 Console。成功收集时会记录类似以下的调试条目：

```
[ConvaiSceneMetadataCollector] 在 X.XXXX 秒内收集了 N 个元数据对象。注册表统计：Y 个总计，Z 个有效，W 个无效
```

如果没有出现这条日志，说明收集没有运行。如果它显示 `已收集 0 个元数据对象`，则有效载荷为空。

调用 `ValidateAllMetadata()` 来自一个临时调试脚本，以获取逐对象的细分：

```csharp
void Start()
{
    FindObjectOfType<ConvaiSceneMetadataCollector>()?.ValidateAllMetadata();
}
```

### 症状参考

| 症状                                       | 可能原因                                                  | 修复                                                                 |
| ---------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------ |
| Console 中没有收集日志                          | `Collect On Start` 已禁用且没有手动调用                         | 启用 **Collect On Start** 或调用 `CollectAndSendSceneMetadata()` 在会话连接后 |
| `“未注入依赖项”` error                         | `ConvaiSceneMetadataCollector` 位于一个没有 `ConvaiManager` | 添加 `ConvaiManager` 添加到场景中的对象；收集器会自动解析它                             |
| `已收集 0 个元数据对象` 在日志中                      | 所有对象都被从有效载荷中排除                                        | 请参见 [空有效载荷](#empty-payload) 如下                                     |
| 编辑器中的对象名称验证警告                            | 名称为空或超过 50 个字符                                        | 设置一个非空且少于 50 个字符的名称                                                |
| 尽管已确认发送，AI 仍忽略对象                         | 描述缺失或过于模糊                                             | 请参见 [改进描述](#improving-descriptions) 如下                             |
| 对象存在于注册表中，但不在有效载荷中                       | `Include In Metadata` 未勾选，或组件被禁用                      | 在 Inspector 中检查该字段；如有需要重新启用组件                                      |
| `Is Registered` 显示 `false` 在 Inspector 中 | 组件已添加，但 `OnEnable` 尚未触发                               | 确保 GameObject 和组件都已启用                                              |

### 空有效载荷

当 `已收集 0 个元数据对象` 出现时，按以下顺序检查：

**1. 是否有任何 `ConvaiObjectMetadata` 组件已启用？** 已禁用的组件不会注册。选择目标 GameObject，并检查 Inspector 中的组件开关。

**2. 是否 `Include In Metadata` 已勾选？** 此字段 `true` 默认已开启，但运行时代码可能已将其设置为 `false`。检查 `ConvaiMetadataRegistry.GetStatistics()` 以获取被排除对象的数量。

**3. 是否 `Object Name` 非空？** 名称为空的对象会通过 `IsRegistered` 但会在 `IsValid` 中失败，并被排除在发送之外。调用 `ValidateAllMetadata()` 来识别这些对象。

```csharp
// 调试统计细分
var stats = ConvaiMetadataRegistry.GetStatistics();
foreach (var kv in stats)
    Debug.Log($"{kv.Key}: {kv.Value}");
```

### 改进描述

AI 使用 `Object Description` 字段作为事实依据。模糊的描述会产生模糊的回复。

| 避免        | 改用                                 |
| --------- | ---------------------------------- |
| `“一个灭火器”` | `“安装在南墙与紧急出口旁、与视线齐平的红色 ABC 干粉灭火器”` |
| `“桌子”`    | `“实验室中央的钢制检查台，高 90 厘米，带可调节腿托”`     |
| `“门”`     | `“带黄色警示条纹、通往冷却室的重型钢制压力门”`          |

指南：

* 包含相对于地标或房间特征的位置
* 包含视觉标识——颜色、大小、材质
* 在相关情况下包含功能或用途
* 保持在 200 个字符以内

### 决策树

当 AI 对场景对象没有响应时，使用这棵树：

```
Is IsReadyToSendMetadata() 返回 true 吗？
├── 否 → 场景中有 ConvaiManager 吗？房间已连接吗？
│         修复：添加 ConvaiManager，确保会话达到 Connected 状态
└── 是 → GetMetadataCount() > 0 吗？
          ├── 否 → 运行 ValidateAllMetadata()。检查 Include In Metadata 和 Object Name 字段
          └── 是 → 描述是否真实且具体？
                    ├── 否 → 结合位置和关键属性重写
                    └── 是 → 检查 Convai 控制台字符设置
```

### 下一步

{% content-ref url="/pages/553ff838d38639ef80a27f8380dc466768470562" %}
[场景元数据脚本 API](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/scene-metadata/scripting-api-reference.md)
{% endcontent-ref %}


---

# 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:

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

The question should be specific, self-contained, and written in natural language.
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.