> 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 角色忽略场景对象。

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

### 首要排查

启用 **日志统计** 在 `ConvaiSceneMetadataCollector` （它默认已开启），在进入播放模式后检查控制台。成功采集会记录类似如下的调试条目：

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

如果没有出现此日志，则采集未运行。如果它出现并显示 `已收集 0 个元数据对象`，则负载为空。

调用 `ValidateAllMetadata()` 在临时调试脚本中调用，以获取逐对象的细分：

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

### 症状参考

| 症状                        | 可能原因                                                  | 修复方法                                                     | 验证                                                                      |
| ------------------------- | ----------------------------------------------------- | -------------------------------------------------------- | ----------------------------------------------------------------------- |
| 控制台中没有采集日志                | `启动时采集` 已禁用且没有手动调用                                    | 启用 **启动时采集** 或者调用 `CollectAndSendSceneMetadata()` 在会话连接后 | 重新进入播放模式并确认 `[ConvaiSceneMetadataCollector] 已收集 N 个元数据对象...` 该条目出现在控制台中 |
| `“依赖未注入”` error           | `ConvaiSceneMetadataCollector` 位于一个没有 `ConvaiManager` | 添加 `ConvaiManager` 添加到场景中；采集器会自动解析它                      | 进入播放模式时错误不再出现                                                           |
| `已收集 0 个元数据对象` 在日志中       | 所有对象都被排除在负载之外                                         | 参见 [空负载](#empty-payload) 如下所示                            | `GetMetadataCount()` 返回一个大于 `0`                                         |
| 编辑器中的对象名称验证警告             | 名称为空或超过 50 个字符                                        | 设置一个不为空且少于 50 个字符的名称                                     | 控制台警告会在下一次 `OnValidate` 校验通过后清除（取消选择并重新选择该 GameObject）                  |
| 尽管已确认发送，AI 仍忽略对象          | 描述缺失或过于模糊                                             | 参见 [改进描述](#improving-descriptions) 如下所示                  | 向角色提出一个需要改写后细节的问题，并确认该细节出现在回复中                                          |
| 对象存在于注册表中，但不在负载中          | `包含到元数据中` 未勾选，或者组件已禁用                                 | 在检查器中检查该字段；如有需要，重新启用该组件                                  | 该对象出现在 `GetValidMetadata()` 或下一次 `ValidateAllMetadata()` pass           |
| `是否已注册` 显示为 `false` 在检查器中 | 组件已添加，但 `OnEnable` 尚未触发                               | 确保 GameObject 和组件都已启用                                    | `是否已注册` 显示为 `true` 在播放模式下                                               |
| 被跟踪的属性从未在角色上更新            | **源成员名称** 与某个属性、字段或目标上的零参数方法不匹配 **Source Component**  | 修正成员名称；不匹配会静默失败，且该条目会保留其最后已知值而不是报错                       | 角色的回复会在一个 0.25 秒轮询间隔内反映新值                                               |
| 静态元数据编辑未能到达已连接的角色         | 会话未连接，或者角色当前不在对话中                                     | 实时重新同步仅在角色已连接且处于对话中时才会刷新——请重新连接，或等待下一次连接时发送              | 重新连接后询问角色关于已编辑对象的问题，并确认使用了更新后的文本                                        |

### 空负载

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

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

**2. 是否 `包含到元数据中` 已勾选？** 此字段默认 `true` 为开启，但运行时代码可能已将其设置为 `false`。调用前请检查 `ConvaiMetadataRegistry.GetStatistics()` 以查看被排除对象的数量。

**3. 是否 `中搜索“Convai World Object”` 非空？** 名称为空的对象会通过 `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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
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=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.