> 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 将玩家模糊的语言——“抓住那个”、“去那里”、“看左边那个”——解析为某个已注册对象或角色的方式。消解由两个输入驱动：你为每个目标注册的详细描述，以及你在运行时随着玩家关注点变化而更新的当前注意对象。

### 消解如何工作

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

1. **对象描述** —— 为每个可交互对象和角色注册的 Name 和 Description 文本。Convai 使用这些来将“cylinder”匹配到你注册的对象。
2. **当前注意对象** —— NPC 当前“关注”的对象。设置后，Convai 会在“that”或“it”这类歧义指代上给予它很高权重。

`ConvaiActionConfigSource` 在连接时固定描述，但活动会话可以将 objects 或 characters 列表替换为一个 `ConvaiActionConfigPatch` ——参见 [配置角色动作](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/configuring-actions.md) 用于 patch 语义。当前注意对象可以在活动对话中的任何时刻更改。

一旦 Convai 返回的动作的目标与某个已注册名称匹配，Unity 会在增强参数的 `已解析引用` 字段中将该匹配暴露为一个 `ConvaiActionParameterReference` (`Convai.Shared.Types.ConvaiActionParameterReference`）。其 `种类` 属性是一个 `ConvaiActionTargetKind` 值—— `无`, `对象`，或 `角色` —— 告诉你消解结果是已注册对象还是已注册角色。参见 [角色动作脚本参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/actions-scripting-reference.md) 以了解完整的参数值类型。

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

该 `描述` 每个对象定义上的字段 `ConvaiActionObjectDefinition` 是影响消解准确性的最重要文本。请将每个描述写成一句自然句子，并包含：

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

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

模糊的描述会导致 Convai 选择错误的目标，或无法解析歧义指代。

{% hint style="warning" %}
`ConvaiActionConfigSource` 描述在会话连接后就固定了。对于事先已知的场景，请使用 `RoomSessionConnectOptions.ActionConfigOverride` 在连接前。对于在活动会话期间会变化的场景——对象被移动、生成或销毁——请发送一个 `ConvaiActionConfigPatch` ： `character.DynamicContext.Apply(...)` ，而不是重新连接。参见 [配置角色动作](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/configuring-actions.md) 以了解覆盖和 patch 语义。
{% endhint %}

### 运行时注意力 API

可在活动对话中的任意时刻通过以下方式更新 NPC 的当前注意对象： `ConvaiCharacter.DynamicContext`:

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

// 通过定义引用设置
character.DynamicContext.SetCurrentAttentionObject(myObjectDefinition);

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

#### 方法签名

```csharp
void SetCurrentAttentionObject(object currentAttentionObject, ConvaiRespondMode reaction = ConvaiRespondMode.Silent)
void ClearCurrentAttentionObject(ConvaiRespondMode reaction = ConvaiRespondMode.Silent)
```

`currentAttentionObject` 接受一个 `string` 对象名称或 `ConvaiActionObjectDefinition` 引用。其他任何类型都会被拒绝。

#### reaction 参数

可选的 `reaction` 参数（`ConvaiRespondMode`，命名空间 `Convai.Runtime`）控制注意对象变化是否触发新的 LLM 回合。默认的 `ConvaiRespondMode.Silent` 会更新消解上下文，而不会提示回复。传入 `ConvaiRespondMode.MustRespond` 如果你希望 Convai 以自然语言回复来响应关注点变化，或者传入 `ConvaiRespondMode.Auto` 让模型自行决定。

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

// NPC 可能会口头回应关注点变化
character.DynamicContext.SetCurrentAttentionObject("GasValve", ConvaiRespondMode.MustRespond);
```

注意对象的更改会先在本地暂存，并在下一个 dynamic-context 批次中发送（最长 `ConvaiCharacter.DynamicContextBatchDelaySeconds`，默认 0.5 秒），或者在你调用时立即发送 `character.DynamicContext.Flush()`.

### 静默失败条件

{% hint style="warning" %}
无效更新会在暂存前被拒绝。每种情况下都会向 Console 记录一条警告。
{% endhint %}

| 条件                                | 结果                                                                                                    |
| --------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `currentAttentionObject` 是 `null` | 已拒绝。警告： `动态上下文注意对象不能为空`                                                                               |
| 对象名称不在当前的 action-config objects 中 | 已拒绝。警告： `动态上下文注意对象更新被拒绝（invalid_attention）：current_attention_object 'X' 不存在于 action_config.objects 中` |
| 角色尚未就绪，或不在活动对话中                   | 先在本地暂存，待角色就绪后自动发送。不记录警告。                                                                              |

对象名称必须与以下中的某个条目匹配： `ConvaiActionConfigSource.Objects` （不区分大小写）。它不需要匹配 `GameObjectReference` name——它必须匹配 `名称` 对象定义中的 field。

### 注意范围

注意对象只会影响后续回合中后端的指代消解。设置注意对象不会：

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

### 连接时的初始注意对象

要在玩家第一回合之前预先设定 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.DynamicContext.SetCurrentAttentionObject(_objectDefinition);
    }

    public void OnPointerExit(PointerEventData eventData)
    {
        _instructor.DynamicContext.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.DynamicContext.SetCurrentAttentionObject(_objectName);
    }

    private void OnTriggerExit(Collider other)
    {
        if (!other.CompareTag("Player")) return;
        _instructor.DynamicContext.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, and the optional `goal` 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>&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.