排查场景元数据问题

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

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

第一线调查

启用 日志统计 在 ConvaiSceneMetadataCollector （默认已开启）并在进入播放模式后检查 Console。成功采集会记录类似以下的调试条目：

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

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

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

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

症状参考

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

负载为空

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

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

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

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

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

改进描述

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

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

指南：

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

决策树

当 AI 不响应场景对象时使用此树：

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

下一步

场景元数据脚本 API