> 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" %}
该 **初始注意对象** 必须与 **名称** 你已注册的某个 **可操作对象** 的字段完全匹配（不区分大小写）。如果不匹配，该字段将被忽略，并且会在控制台记录一条警告。
{% endhint %}

### 对话中的注意力

随着对话推进，后端会根据上下文动态更新其内部注意力——包括玩家和角色提到的对象、执行的动作等。后端会在大多数情况下自动处理。

### 运行时更新注意对象

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

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

```csharp
// 玩家在培训界面中选择一个对象
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` 需要一个 **活动会话**。该名称必须与会话的 Objects 列表中已注册的条目匹配——它不会注册新目标。请在 `ConnectAsync` 完成后调用。
{% endhint %}

***

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

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

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

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

在此设置下：

> 玩家： *“我应该先去哪里？”* 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
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>
```

The question should be specific, self-contained, and written in natural language.
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.