> 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/unity-plugin-beta-overview/features/actions/attention-and-reference-grounding.md).

# 注意力与引用落地

后端如何解析模糊的玩家引用——以及对象描述和当前注意力对象如何影响目标解析。

## 什么是指代锚定？

当玩家说“去那里”或“把那个捡起来”时，Convai 后端需要弄清楚他们指的是哪个对象或角色。这个过程——把自然语言中的模糊指代关联到场景中的具体事物——称为 **指代锚定**.

SDK 通过在会话开始时发送两类上下文，帮助后端进行指代锚定：

1. **对象和角色描述** —— 场景中的每个事物是什么 *是*
2. **当前关注对象** —— AI 当前正在 *关注的对象*

上下文越丰富，AI 就越能更好地解析玩家的模糊请求。

***

## 对象和角色描述

你在 `ConvaiActionConfigSource` 中注册的每个对象和角色，都有一个会发送到后端的文本字段：

| 类型                                    | 字段     | 作用                  |
| ------------------------------------- | ------ | ------------------- |
| 对象（`ConvaiActionObjectDefinition`)    | **说明** | 描述该对象是什么，以及它在场景中的位置 |
| 角色（`ConvaiActionCharacterDefinition`) | **简介** | 描述该角色是谁以及其职责        |

这些字段会在会话开始时包含在发送到 Convai 后端的会话配置中。后端会读取它们，以了解场景中每个名称指代什么，并用它们来解析玩家讲话中的指代。

### 为什么描述很重要

比较同一个实体的这两个对象定义：

| 名称    | 说明                       | 锚定质量                                          |
| ----- | ------------------------ | --------------------------------------------- |
| `灭火器` | *（空）*                    | 后端只知道名称                                       |
| `灭火器` | `一个红色的灭火器，安装在紧急出口左侧的墙上。` | 后端知道它是什么、它在哪里，并且可以结合上下文解析“红色那个”“靠近出口的那个”或“它”。 |

{% hint style="info" %}
将描述写成一句自然的句子，描述场景中的该对象。包含类型、颜色、位置或用途——任何有助于将此对象与其他对象区分开的细节。
{% endhint %}

### 编写有效描述

**具体说明位置：**

> `一顶黄色安全帽，挂在入口附近的设备架上。` `安装在北侧墙上的火警控制面板，旁边有出口标志。`

**在相关时包含对象用途：**

> `用于扑灭 A 类和 B 类火灾的便携式灭火器。` `切断整个楼层电力的总电源开关。`

**对于角色，请描述其职责和位置：**

> `站在培训室前方的资深安全讲师。` `负责监督仓库运营的现场主管。`

**避免使用模糊描述：**

| 避免          | 改为使用              |
| ----------- | ----------------- |
| `场景中的一个对象。` | `一个木箱，堆放在装卸区门旁。`  |
| `一个人。`      | `站在主办公室入口旁的仓库经理。` |
| `设备。`       | `安装在火灾出口旁墙上的急救箱。` |

***

## 当前关注对象

该 **关注对象** 会告诉后端 AI 当前关注的是哪个对象。当玩家使用代词或模糊指代（“去那儿”、“把它捡起来”）时，后端会利用当前关注对象来解析“它”指什么。

### 设置初始关注对象

在 `ConvaiActionConfigSource`，该 **初始关注对象** 字段会在会话开始时为关注提供初始值。将其设置为 **名称** 你已注册对象之一的

```
初始关注对象：灭火器
```

在会话开始时，后端会接收 `current_attention_object: "灭火器"` 作为配置。如果玩家在提到任何具体内容之前说“告诉我它的情况”，后端就知道“它”指的是灭火器。

{% hint style="info" %}
该 **初始关注对象** 必须与 **名称** 你已注册的某个 **Actionable Objects** 字段完全匹配（不区分大小写）。如果不匹配，该字段将被忽略，并且会在控制台中记录警告。
{% endhint %}

### 会话中的关注对象

随着对话推进，后端会根据上下文更新其内部关注对象——玩家和角色提到了哪些对象、执行了哪些动作。对于大多数情况，后端会动态处理这一点。

### 在运行时更新关注对象

对于需要显式控制的场景——例如玩家在 UI 中点击某个对象，或 NPC 移动到新的工作站—— `ConvaiCharacter` 提供在活动会话中更新关注对象的方法：

| 方法                                                            | 说明                         |
| ------------------------------------------------------------- | -------------------------- |
| `SetCurrentAttentionObject(string name)`                      | 按对象名称设置关注对象（必须存在于会话的对象列表中） |
| `SetCurrentAttentionObject(ConvaiActionObjectDefinition obj)` | 使用类型化定义设置关注对象              |
| `ClearCurrentAttentionObject()`                               | 移除当前关注锚定                   |

```csharp
// 玩家在培训 UI 中选择一个对象
private void OnPlayerSelectsObject(string objectName)
{
    _character.SetCurrentAttentionObject(objectName);
}

// 玩家移动到新的工作站——将关注点转移到该工作站的主要对象
private void OnPlayerMovesToStation(string equipmentName)
{
    _character.SetCurrentAttentionObject(equipmentName);
}

// 子任务完成——在进入下一个主题前清除关注对象
private void OnSubTaskComplete()
{
    _character.ClearCurrentAttentionObject();
}
```

{% hint style="warning" %}
`SetCurrentAttentionObject` 需要一个 **活动会话**。该名称必须与会话对象列表中已注册的条目完全匹配——它不会注册新的目标。请在 `ConnectAsync` 完成后调用。
{% endhint %}

***

## 实际示例：消防安全培训模拟

一个消防安全培训室注册了以下对象：

| 名称     | 说明                              |
| ------ | ------------------------------- |
| `灭火器`  | 一个红色便携式 CO2 灭火器，安装在主工作台左侧的墙上。   |
| `警报面板` | 安装在墙上的火警控制面板，带有一个大的红色把手，位于主门附近。 |
| `紧急出口` | 房间尽头带有绿色发光标志的紧急出口门。             |
| `急救箱`  | 一个白色急救箱，安装在工作台和储物柜之间的墙上。        |

**初始关注对象：** `灭火器`

在此设置下：

> 玩家： *“我应该先去哪里？”* AI： *“先去灭火器那里。”* → 后端锚定到 `灭火器`

> 玩家： *“现在呢？”* AI： *“拔掉保险销，并将其对准火源根部。”* → 关注对象仍然是 `灭火器`

> 玩家： *“那块面板呢？”* AI： *“那是警报面板——在使用灭火器之前，你应该先触发它。”* → 后端将“那块面板”锚定到 `警报面板` 基于描述上下文

***

## 提示

{% hint style="info" %}
**唯一的名称有助于提升锚定效果。** 如果两个对象有相似的名称（例如， `红色灭火器` 和 `蓝色灭火器`），请让描述明显不同，以帮助后端区分它们。
{% endhint %}

{% hint style="info" %}
**名称在运行时匹配时不区分大小写**，但它们会作为文本原样发送到后端。请使用一致、自然的名称（建议使用标题式大小写： `灭火器`，而不是 `fire_extinguisher`).
{% endhint %}

{% hint style="warning" %}
**描述会在连接时发送到后端。** 它们无法在会话中途更改。如果你的场景是动态的（对象生成或被销毁），可以考虑使用连接时覆盖在每次会话前以编程方式构建配置。
{% endhint %}

***

## 结论

指代锚定使玩家能够自然地说话——使用代词、部分名称和依赖上下文的指代——而不是必须使用精确的对象名称。对象描述的质量以及初始关注对象的准确性，会直接影响 AI 解析玩家意图的可靠程度。把描述当作 AI 的元数据：具体、具有关联上下文，并用朴素的语言编写。


---

# 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/unity-plugin-beta-overview/features/actions/attention-and-reference-grounding.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.