> 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 无法有效使用。

### 初步排查

启用 **记录统计信息** 开启 `ConvaiSceneMetadataCollector` （默认已开启），并在进入 Play 模式后检查 Console。成功收集会记录一条类似以下的调试条目：

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

如果没有出现这条日志，则说明收集未运行。如果它出现了 `收集了 0 个元数据对象`，则负载为空。

调用 `ValidateAllMetadata()` ，从一个临时调试脚本中获取按对象划分的明细：

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

### 症状参考

| 症状                                       | 可能原因                                                         | 修复方法                                                                 |
| ---------------------------------------- | ------------------------------------------------------------ | -------------------------------------------------------------------- |
| Console 中没有收集日志                          | `Collect On Start` 已禁用且没有手动调用                                | 启用 **Collect On Start** 或者调用 `CollectAndSendSceneMetadata()` 在会话连接之后 |
| `“未注入依赖项”` 错误                            | `ConvaiSceneMetadataCollector` 位于一个没有 `ConvaiManager`        | 添加 `ConvaiManager` 到场景中；收集器会自动解析它                                    |
| `收集了 0 个元数据对象` 在日志中                      | 所有对象都被排除在负载之外                                                | 参见 [空负载](#empty-payload) 如下                                          |
| 编辑器中的对象名称验证警告                            | 名称为空或超过 50 个字符                                               | 设置一个非空且少于 50 个字符的名称                                                  |
| 尽管已确认发送，AI 仍忽略对象                         | 描述缺失或过于含糊                                                    | 参见 [改进描述](#improving-descriptions) 如下                                |
| 对象存在于注册表中，但不在负载中                         | `Include In Metadata` 未勾选，或者组件已禁用                            | 在 Inspector 中检查该字段；如有需要，重新启用该组件                                      |
| `Is Registered` 显示 `false` 在 Inspector 中 | 组件已添加，但 `OnEnable` 尚未触发                                      | 确保 GameObject 和组件都已启用                                                |
| 跟踪属性从未在角色上更新                             | **Source Member Name** 与上的属性、字段或无参方法不匹配 **Source Component** | 修正成员名称；名称不匹配会静默失败，该条目会保留其上次已知值，而不会报错                                 |
| 静态元数据编辑未到达已连接的角色                         | 会话未连接，或者角色当前不在对话中                                            | 实时重新同步只会在角色已连接且处于对话中时刷新——重新连接，或等待下一次连接时发送                            |

### 空负载

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

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

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

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

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

### 改进描述

AI 使用 `对象描述` 字段作为事实依据。含糊的描述会产生含糊的回复。

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

指南：

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

### 决策树

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

```
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, and the optional `goal` 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>&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.