> 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/component-reference.md).

# 场景元数据组件参考

场景元数据系统由两个组件组成。 `ConvaiObjectMetadata` 用于每个 AI 应该了解的对象。 `ConvaiSceneMetadataCollector` 用于 `ConvaiManager` GameObject，并处理收集和传输。

#### ConvaiObjectMetadata

**添加组件路径：** `Convai → World Object`

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

**检视器字段**

| 字段                       | 类型                                   | 默认值               | 约束             | 描述                                                                      |
| ------------------------ | ------------------------------------ | ----------------- | -------------- | ----------------------------------------------------------------------- |
| **对象名称**                 | `string`                             | *（GameObject 名称）* | 必填。最多 50 个字符。  | Convai 用于在对话中识别并引用此对象的名称。组件首次添加时，会自动从 GameObject 的名称填充。请修改为清晰易读的标签。     |
| **对象描述**                 | `string`                             | `""`              | 可选。最多 200 个字符。 | 一段事实性、具体的描述——该对象是什么、位于何处以及任何关键属性。AI 使用这段文字作为回答依据。                       |
| **Include In Metadata**  | `bool`                               | `true`            | —              | 取消勾选时，该对象会被排除在下一次元数据收集之外，而不会移除或禁用该组件。可用它来管理运行时包含情况。                     |
| **跟踪属性**                 | `List<ConvaiTrackedContextProperty>` | *（空）*             | 可选。            | 每个条目的运行时属性会作为动态上下文状态键暴露给所有已连接角色。请参见 [跟踪属性](#tracked-properties) 下方。     |
| **Is Registered** *（只读）* | `bool`                               | —                 | 只读             | 调试指示器。显示 `true` 当该组件当前已在 `ConvaiMetadataRegistry`中注册时的状态。仅在 Play 模式下可见。 |

**生命周期**

`ConvaiObjectMetadata` 自主管理其注册：

| 事件           | 行为                                                   |
| ------------ | ---------------------------------------------------- |
| `OnEnable`   | 注册到 `ConvaiMetadataRegistry`                         |
| `OnDisable`  | 从…注销 `ConvaiMetadataRegistry`                        |
| `OnDestroy`  | 从…注销 `ConvaiMetadataRegistry`                        |
| `OnValidate` | 自动填充 **对象名称** 来自 `gameObject.name` 如果为空；会在编辑器中记录验证错误 |

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

更改 **对象名称**, **对象描述**，或 **Include In Metadata** 通过公开的 `ObjectName`, `ObjectDescription`，或 `IncludeInMetadata` 属性会将元数据标记为已更改，并在会话处于活动状态时立即重新同步所有已连接角色——该更改不会延迟到下一次连接。

**验证规则**

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

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

{% hint style="warning" %}
`OnValidate` 当验证失败时，会在编辑器中记录警告，但不会阻止组件被添加。添加组件后请检查控制台，以便在进入 Play 模式前捕获配置错误。
{% endhint %}

**跟踪属性**

每个 **跟踪属性** 是一个 `ConvaiTrackedContextProperty` ——一个可序列化的逐条目定义，会将一个运行时值作为动态上下文状态键暴露给每个已连接角色。

| 字段                     | 类型                  | 默认值  | 描述                                                                                                                                                                      |
| ---------------------- | ------------------- | ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **属性名称**               | `string`            | `""` | 启用此条目所必需。与 **对象名称** 组合以形成动态上下文状态键。                                                                                                                                      |
| **反应**                 | `ConvaiRespondMode` | `静默` | 当此属性值更改时应用于角色的反应。请参见 [`ConvaiRespondMode`](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/dynamic-context/relay-component-reference.md#convairespondmode). |
| **初始值**                | `string`            | `""` | 对象注册时发送的值，以及用于没有 **Source Component** 配置的条目的值。                                                                                                                          |
| **Source Component**   | `组件`                | `无`  | 可选。每次轮询时用于读取实时值的组件。若要固定值，请保持未设置。                                                                                                                                        |
| **Source Member Name** | `string`            | `""` | 可选。要读取的 **Source Component** 上的属性、字段或无参数方法的名称。                                                                                                                          |

每个条目的状态键构建为 `"{ObjectName}.{PropertyName}"` 通过 `ConvaiObjectMetadata.BuildStateKey`.

当两者都 **Source Component** 和 **Source Member Name** 已设置时， `ConvaiTrackedContextProperty` 会通过反射在每次轮询时实时读取值，按顺序检查：匹配的属性、字段、再到无参数方法（包括非公开成员）。当任一字段未设置时，该条目将固定为 **初始值** ，直到被代码更改。

对已连接角色的轮询和传递由内部 `ConvaiWorldObjectPollDriver` ——无需添加面向用户的组件。它会在 `ConvaiManager` GameObject 上创建，当第一个 `ConvaiObjectMetadata` 组件注册时，它会每 `0.25` 秒评估所有已注册对象上的跟踪属性，并在最后一个 `ConvaiObjectMetadata` 组件注销时销毁。

#### ConvaiSceneMetadataCollector

`ConvaiSceneMetadataCollector` 是协调器。它会监听房间连接事件，从 `ConvaiMetadataRegistry`中读取所有有效元数据，并将负载发送给 Convai。在检视器中，点击 **添加组件** 并搜索 `Convai Scene Metadata Collector`。将其放在与 `ConvaiManager` 处于同一场景中的任意 GameObject 上——其所需依赖项会在启动时通过 `ConvaiManager.ActiveManager`.

**检视器字段**

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

**依赖项与注入**

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

如果未注入这些依赖项（例如，如果 `ConvaiManager` 在场景中缺失），收集器会记录错误，且所有收集调用都会变为无操作。

{% hint style="danger" %}
不要在没有 `ConvaiSceneMetadataCollector` 的情况下将其添加到场景中。 `ConvaiManager`当 `ConvaiManager` 缺失时，该组件会记录 `[ConvaiSceneMetadataCollector] Dependencies not injected. Add ConvaiManager to scene.` 作为一条 **错误** 在控制台中的错误并自行禁用。
{% endhint %}

**手动触发**

当 **Collect On Start** 被禁用时，从脚本调用 `CollectAndSendSceneMetadata()` 以在应用需要的时刻触发收集。如果房间未连接，该方法不会执行任何操作——请使用 `IsReadyToSendMetadata()` 先检查是否已准备好发送。

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

有关完整的公共方法列表，请参见 [场景元数据脚本 API](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/scene-metadata/scripting-api-reference.md).

#### 下一步

{% 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 %}

{% content-ref url="/pages/16c5aa93667aec71180b560b3408b114f488e893" %}
[场景元数据使用示例](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/scene-metadata/usage-examples.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/component-reference.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.