排查场景元数据问题

修复场景元数据问题，包括空负载、缺失的收集日志、依赖注入失败以及 AI 角色忽略场景对象。

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

第一线排查

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

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

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

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

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

症状参考

症状	可能原因	修复
Console 中没有收集日志	Collect On Start 已禁用且没有手动调用	启用 Collect On Start 或调用 CollectAndSendSceneMetadata() 在会话连接后
“未注入依赖项” error	ConvaiSceneMetadataCollector 位于一个没有 ConvaiManager	添加 ConvaiManager 添加到场景中的对象；收集器会自动解析它
已收集 0 个元数据对象 在日志中	所有对象都被从有效载荷中排除	请参见 空有效载荷 如下
编辑器中的对象名称验证警告	名称为空或超过 50 个字符	设置一个非空且少于 50 个字符的名称
尽管已确认发送，AI 仍忽略对象	描述缺失或过于模糊	请参见 改进描述 如下
对象存在于注册表中，但不在有效载荷中	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() 来识别这些对象。

// 调试统计细分
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 控制台字符设置

下一步

场景元数据脚本 API