场景元数据组件参考

ConvaiObjectMetadata 和 ConvaiSceneMetadataCollector 的参考，包括 Inspector 字段、生命周期事件、验证规则以及依赖注入行为。

Scene Metadata 系统由两个组件组成。 ConvaiObjectMetadata 用于每个 AI 应该了解的对象。 ConvaiSceneMetadataCollector 用于 ConvaiManager GameObject，并负责收集和传输。

ConvaiObjectMetadata

添加组件路径： Convai → 对象元数据

ConvaiObjectMetadata 是一个 MonoBehaviour ，它向 Convai 描述单个 GameObject。启用后，它会自动注册到 ConvaiMetadataRegistry。当禁用或销毁时，它会自动注销——无需手动清理。

Inspector 字段

字段	类型	默认值	约束	说明
Object Name	string	（GameObject 名称）	必填。最多 50 个字符。	Convai 用于在对话中识别并引用此对象的名称。首次添加组件时，会自动从 GameObject 的名称填充。可编辑为清晰、易读的标签。
Object Description	string	""	可选。最多 200 个字符。	一段真实、具体的描述——对象是什么、位于哪里，以及任何关键属性。AI 使用这段文本来锚定其回复。
Include In Metadata	bool	true	—	取消勾选后，此对象会在下一次元数据收集中被排除，但不会移除或禁用该组件。可用于管理运行时是否纳入。
Is Registered （只读）	bool	—	只读	调试指示器。显示 true 当该组件当前已注册到 ConvaiMetadataRegistry。在播放模式下可见。

生命周期

ConvaiObjectMetadata 自行管理注册：

事件	行为
OnEnable	注册到 ConvaiMetadataRegistry
OnDisable	从…注销 ConvaiMetadataRegistry
OnDestroy	从…注销 ConvaiMetadataRegistry
OnValidate	自动填充 Object Name 来自 gameObject.name 如果为空；在编辑器中记录验证错误

在运行时被停用的 GameObject 将不会出现在下一次元数据收集中，即使 Include In Metadata 仍然勾选。

验证规则

ConvaiObjectMetadata.IsValid 返回 true 当 Object Name 非空且不全是空白字符。50 字符限制仅通过编辑器警告强制提示，使用 GetValidationErrors() ——名称超过 50 个字符的对象仍然会通过 IsValid 并包含在负载中。

名称为空的对象 Object Name 会失败 IsValid 并会从 GetValidMetadata() 以及发送给 Convai 的负载中排除。名称超过 50 个字符的对象会包含在负载中，但会在编辑器中生成验证警告。

OnValidate 验证失败时会在编辑器中记录警告，但不会阻止添加该组件。添加组件后请检查 Console，以便在进入播放模式前捕获配置错误。

ConvaiSceneMetadataCollector

ConvaiSceneMetadataCollector 是协调器。它监视房间连接事件，从中读取所有有效元数据 ConvaiMetadataRegistry，并将负载发送给 Convai。在 Inspector 中，点击 添加组件 并搜索 Convai 场景元数据收集器。将其放置在与…相同场景中的任意 GameObject 上 ConvaiManager ——其必需依赖会在启动时通过 ConvaiManager.ActiveManager.

Inspector 字段

字段	类型	默认值	说明
Collect On Start	bool	false	启用后，一旦房间会话到达 SessionState.Connected，采集器会自动发送完整的元数据负载。如果需要手动控制元数据发送时机，请禁用此项。
日志统计	bool	true	每次收集都会写入一条 Console 记录，显示对象数量、收集持续时间和注册表分布。适用于验证是否捕获了所有预期对象。
最近收集数量 （只读）	int	—	显示最近一次收集中包含的对象数量。在播放模式下可见。
最近收集时间 （只读）	float	—	显示最近一次收集操作的持续时间（秒）。在播放模式下可见。

依赖项与注入

ConvaiSceneMetadataCollector 需要两个注入的依赖项—— IEventHub 是位于 IConvaiRoomConnectionService ——由 ConvaiManager 在启动时自动提供。无需手动连接。

如果这些依赖项未被注入（例如，如果 ConvaiManager 未出现在场景中），采集器会记录警告，且所有收集调用都将变为无操作。

不要将 ConvaiSceneMetadataCollector 添加到没有 ConvaiManager。当 ConvaiManager 缺失时，组件会记录 "[ConvaiSceneMetadataCollector] 依赖项未注入。请将 ConvaiManager 添加到场景中。" 作为 error 在 Console 中的消息，并自行禁用。

手动触发

当 Collect On Start 被禁用时，请调用 CollectAndSendSceneMetadata() 脚本中的该方法，以便在应用需要的时刻触发收集。如果房间未连接，该方法将不执行任何操作——请使用 IsReadyToSendMetadata() 先检查就绪状态。

if (_collector.IsReadyToSendMetadata())
    _collector.CollectAndSendSceneMetadata();

完整的公共方法列表，请参见 场景元数据脚本 API.

下一步

场景元数据脚本 API场景元数据使用示例