> 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/character-actions/attention-and-reference-grounding.md).

# 注意与指代锚定

参考锚定是 Convai 如何将含糊的玩家语言——“抓住那个”、“去那个地方”、“看看左边那个”——解析为某个已注册的特定对象或角色的方式。锚定由两个输入驱动：你为 `ConvaiActionConfigSource`中每个目标编写的详细描述，以及你在运行时随着玩家注意力变化而更新的当前注意对象。

### 锚定的工作原理

当玩家说“捡起那个圆柱体”时，Convai 会评估两件事：

1. **对象描述** ——你在连接时注册的名称和描述文本。Convai 使用它们将“圆柱体”匹配到你注册的对象。
2. **当前注意对象** ——NPC 当前“关注”的对象。设置后，Convai 会在处理“那个”或“它”这类歧义引用时赋予其很高权重。

描述在连接时固定，且无法在会话中途更新。当前注意对象可以在活动对话中的任何时刻更改。

### 编写有效的对象描述

该 `描述` 中每个 `ConvaiActionObjectDefinition` 上的字段是决定锚定准确性的最重要文本。请将每个描述写成一个包含以下内容的单句自然语言：

* **对象类型** ——它是什么种类的东西
* **识别属性** ——颜色、材质、大小或标签
* **位置** ——它相对于场景中地标的位置
* **用途** ——它的用途

|               | 示例                                  |
| ------------- | ----------------------------------- |
| **太模糊——请避免**  | `场景中的一个对象`                          |
| **没有位置——请避免** | `一个灭火器`                             |
| **良好**        | `一个红色便携式 CO2 灭火器，安装在主泵控制面板左侧的墙壁支架上` |
| **良好**        | `一个黄色安全帽，放在场地入口闸门右侧紧挨着的设备架上`        |

模糊的描述会导致 Convai 选错目标，或无法解析歧义引用。

{% hint style="warning" %}
描述会在连接时发送给 Convai，且在会话激活期间不能更改。如果你的场景在运行时发生变化（对象被移动、更换或销毁），请结束会话并使用更新后的描述重新连接，或者在连接时使用 `ActionConfigOverride` 以编程方式构建描述。参见 [配置角色动作 — 动态配置](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/configuring-actions.md#dynamic-configuration-at-connect-time).
{% endhint %}

### 运行时注意力 API

在活动对话期间，可随时使用 `ConvaiCharacter`:

```csharp
// 按对象名称设置
character.SetCurrentAttentionObject("Extinguisher");

// 按定义引用设置
character.SetCurrentAttentionObject(myObjectDefinition);

// 清除 — NPC 没有特定关注点
character.ClearCurrentAttentionObject();
```

#### 方法签名

```csharp
void SetCurrentAttentionObject(string objectName, string runLlm = "false")
void SetCurrentAttentionObject(ConvaiActionObjectDefinition actionObject, string runLlm = "false")
void ClearCurrentAttentionObject(string runLlm = "false")
```

#### runLlm 参数

可选的 `runLlm` 参数用于控制注意力变化是否会立即触发一次新的 LLM 回合。默认 `"false"` 会静默更新锚定上下文。传入 `"true"` ，如果你希望 Convai 以自然语言响应来对焦点变化作出反应。

```csharp
// 静默更新 — NPC 不会口头反应
character.SetCurrentAttentionObject("GasValve");

// NPC 可能会口头回应焦点变化
character.SetCurrentAttentionObject("GasValve", runLlm: "true");
```

### 静默失败条件

{% hint style="warning" %}
如果前置条件未满足，这些调用会被静默忽略。每种情况下都会在 Console 中记录一条警告。
{% endhint %}

| 条件                        | 结果                                                        |
| ------------------------- | --------------------------------------------------------- |
| 不在活动对话中                   | 调用被忽略。警告： `无法设置注意对象：不在对话中`                                |
| 对象名称为空或仅包含空白字符            | 调用被忽略。警告： `无法设置空的注意对象`                                    |
| 对象名称不在活动的 action-config 中 | 调用被忽略。警告： `无法设置注意对象 'X'：它不在当前活跃的 action_config objects 中` |

对象名称必须与 `ConvaiActionConfigSource.Objects` 中的某一项匹配（不区分大小写）。它不需要与 `GameObjectReference` 名称匹配——它必须与对象定义中的 `名称` 字段匹配。

### 注意范围

{% hint style="info" %}
注意对象只会影响 **后端对未来回合的引用解析**。设置注意对象不会：

* 创建一个新的可操作目标
* 更改 action config 中包含哪些对象
* 让 NPC 在物理上看向或移动到该对象
* 影响任何正在进行中的动作步骤
  {% endhint %}

### 连接时的初始注意力

要在玩家第一轮发言前预先设置 NPC 的关注点，请将 **初始注意力** 字段 `ConvaiActionConfigSource` 设置为你的 **可操作对象** 列表中某个对象的名称。这等同于在连接时调用 `SetCurrentAttentionObject` 。

初始注意对象必须与 **可操作对象** 中的一项完全匹配（不区分大小写）。如果不匹配，该字段会被静默省略，不会包含在连接负载中，并会记录警告。

### 用法示例

#### 示例 1——训练模拟中的基于光标选择

**场景：** 一个工业检查模拟。当学员的光标悬停在某个设备上时，更新指导 NPC 的注意力，以便“指向它”能够正确解析。

```csharp
using Convai.Runtime.Components;
using Convai.Shared.Actions;
using UnityEngine;
using UnityEngine.EventSystems;

public sealed class EquipmentFocusTracker : MonoBehaviour, IPointerEnterHandler, IPointerExitHandler
{
    [SerializeField] private ConvaiCharacter _instructor;
    [SerializeField] private ConvaiActionObjectDefinition _objectDefinition;

    public void OnPointerEnter(PointerEventData eventData)
    {
        _instructor.SetCurrentAttentionObject(_objectDefinition);
    }

    public void OnPointerExit(PointerEventData eventData)
    {
        _instructor.ClearCurrentAttentionObject();
    }
}
```

**预期结果：** 当学员将光标悬停在气阀上时，指导者的锚定会切换到该气阀。“指向它”现在会稳定地解析为悬停的对象。

#### 示例 2——基于物理接近的注意力

**场景：** 一个医疗培训场景。NPC 指导者会自动聚焦到学生站在附近的那件设备上。

```csharp
using Convai.Runtime.Components;
using UnityEngine;

public sealed class ProximityAttentionTrigger : MonoBehaviour
{
    [SerializeField] private ConvaiCharacter _instructor;
    [SerializeField] private string _objectName;

    private void OnTriggerEnter(Collider other)
    {
        if (!other.CompareTag("Player")) return;
        _instructor.SetCurrentAttentionObject(_objectName);
    }

    private void OnTriggerExit(Collider other)
    {
        if (!other.CompareTag("Player")) return;
        _instructor.ClearCurrentAttentionObject();
    }
}
```

将此组件放在每件设备周围的触发区域上。设置 `_objectName` 以匹配该对象的 `名称` 在 `ConvaiActionConfigSource`。当学生进入触发区域时，NPC 的锚定会自动切换到该设备。

**预期结果：** 当学生走到除颤器站旁边时，“告诉我怎么使用它”会稳定地解析为除颤器，而无需学生明确说出它的名称。

### 下一步

{% content-ref url="/pages/111bca064ba7041a987662d038af4d71d58a32cd" %}
[配置角色动作](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/configuring-actions.md)
{% endcontent-ref %}

{% content-ref url="/pages/0341126fa4c492311dab4fb6aca6d0c64191016b" %}
[角色动作脚本参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/actions-scripting-reference.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:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-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.