> 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 的语言匹配到 Unity 的本地查找。

当玩家说“拿起那个圆柱体”或“走到它那里”时，两个独立的系统必须就“那个”或“它”指的是什么达成一致：Convai 将这些词匹配到目标名称，Unity 则将该名称匹配到场景中实际的 `GameObject` 。本页介绍这两个步骤，以及影响含糊指代的当前注意对象。

### Convai 如何选择目标名称

Convai 在确定含糊指代所指的目标时，会评估两类输入：

1. **对象和角色描述** ——为每个可操作对象和角色注册的 `Name` 和 `Description` （或 `Bio`）文本。Convai 利用这些信息将“圆柱体”匹配到你注册的对象。
2. **当前注意对象** ——NPC 当前“关注”的对象。设置后，Convai 在处理“那个”或“它”等含糊指代时会给予该对象较高权重。

`ConvaiActionConfigSource` 在连接时确定描述，但在活动会话中，可以使用 `ConvaiActionConfigPatch` 替换对象列表或角色列表——有关补丁的语义，请参阅 [配置角色动作](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/configuring-actions.md) 。在对话进行期间，可以随时更改当前注意对象。

对象不一定要在 `ConvaiActionConfigSource` 上配置才能被 Convai 识别。对象自身的 `ConvaiActionTarget` 组件一经启用，就会将该对象注册到 Convai，并自动跟踪对象的生成和销毁。当两者指定相同的目标名称时，始终以手动配置的条目为准——有关字段级别的区别，请参阅 [角色动作脚本参考](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/actions-scripting-reference.md) 。

当 Convai 返回的动作目标匹配到已注册的名称后，Unity 会在增强参数的 `ResolvedReference` 字段中以 `ConvaiActionParameterReference` (`Convai.Shared.Types.ConvaiActionParameterReference`）的形式提供匹配结果。其 `Kind` 属性是一个 `ConvaiActionTargetKind` 值—— `None`, `Object`或 `Character` ——用于指示指代解析是否指向已注册的对象或角色。有关完整的参数值类型，请参阅 [角色动作脚本参考](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/actions-scripting-reference.md) 。

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

每个 `Description` 字段所属的 `ConvaiActionObjectDefinition` 是确保定位准确性的最重要文本——Convai 会读取它，以判断“圆柱体”这类词指的是哪个物体。请将每条描述写成一个自然的句子，并包含：

* **物体类型** — 它是什么类型的东西
* **识别特征** — 颜色、材质、尺寸或标签
* **位置** — 相对于场景中参照物的位置
* **用途** — 它的用途

|               | 示例                                  |
| ------------- | ----------------------------------- |
| **过于笼统，应避免**  | `场景中的一个物体`                          |
| **未说明位置，应避免** | `一个灭火器`                             |
| **良好示例**      | `一个红色便携式 CO2 灭火器，安装在主泵控制面板左侧的墙壁支架上` |
| **良好示例**      | `一顶黄色安全帽，放在工地入口大门正右侧的设备架上`          |

描述过于笼统会导致 Convai 选错目标，或无法消除指代歧义。

{% hint style="warning" %}
`ConvaiActionConfigSource` 描述在会话连接后便会固定。对于已知的场景，请在连接前通过 `RoomSessionConnectOptions.ActionConfigOverride` 构建备用描述。对于活动会话期间发生变化的场景——例如物体被移动、生成或销毁——请通过 `ConvaiActionConfigPatch` 调用 `character.DynamicContext.Apply(...)` 来更新，而不是重新连接。有关覆盖和补丁的语义，请参阅 [配置角色动作](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/configuring-actions.md) 。
{% endhint %}

### Unity 如何将目标名称与场景物体匹配

Convai 返回目标字符串后，将其解析为实际的 `GameObject` 是一个本地、确定性的匹配过程——不会再次调用 Convai。Unity 会按照四个步骤依次检查当前生效的 `ConvaiActionConfig` ，并在首次找到匹配项时停止：

1. **精确匹配** — 返回的名称与已注册的 `Name`匹配，不区分大小写。
2. **别名匹配** — 返回的名称与该目标的 `Aliases` 列表中的某一项匹配，不区分大小写。别名仅在本地使用，不会发送给 Convai；因此，只有当注册名称本身无法覆盖某种说法时，才添加别名（例如，为`灯`  `Lantern`添加别名）。
3. **规范化匹配** — 去掉开头的“the”/“a”/“an”并合并空白字符后，进行相同的比较。
4. **包含匹配** — 基于子串的模糊匹配，仅在结果唯一时使用。如果多个目标都大致匹配，此步骤会拒绝猜测并判定解析失败，而不会误选目标。

以下条目 `Available` 设为 `false` ——例如通过 `ConvaiCharacter.Actions` 撤回的已消失对象——会在每个步骤中跳过。当同一步骤中两个同类型目标优先级相同时，距离角色较近的目标优先；绑定到真实 `GameObjectReference` 的目标始终优先于没有实际对象的同名条目。

解析后的绑定决定移动或注视执行器前往何处： `InteractionPoint` 位于匹配的 `ConvaiActionObjectDefinition` 或 `ConvaiActionCharacterDefinition` （或 `ConvaiActionTarget` 组件）上（如果已设置）；否则使用绑定的 `GameObjectReference`自身的变换。

如果目标没有 `GameObjectReference` ，且未显式设置 `TextOnly` 标志，则会报告设置错误，因为定向操作无法解析该目标。对于有意不设置场景对应对象的条目，请将 Tick `TextOnly` 设为启用——Convai 仍可谈论该目标，但不会要求任何执行器对其执行操作。

### 运行时注意力 API

在对话进行期间，可随时通过 `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);
```

注意力变化会先暂存于本地，并在下一次动态上下文批次中发送（最多等待 `ConvaiCharacter.DynamicContextBatchDelaySeconds`，默认值为 0.5 秒）；也可以在调用 `character.DynamicContext.Flush()`.

### 静默失败条件

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

| 条件                                | 结果                                                                                                                                            |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `currentAttentionObject` 为 `null` | 已拒绝。警告： `Dynamic context attention object cannot be null`                                                                                     |
| 对象名称不在当前启用的 action-config 对象中     | 已拒绝。警告： `Dynamic context attention update rejected (invalid_attention): current_attention_object 'X' is not present in action_config.objects` |
| 角色尚未就绪，或当前未处于活动对话中                | 会暂存于本地，并在角色就绪后自动发送。不会记录警告。                                                                                                                    |

对象名称必须与 `ConvaiActionConfigSource.Objects` 中的某个条目匹配（不区分大小写）。它不必与 `GameObjectReference` 名称匹配，而必须与对象定义中的 `Name` 字段匹配。

### 注意力范围

注意力对象只会影响 Convai 在后续轮次中的引用解析。设置注意力对象不会：

* 创建新的可执行目标
* 更改动作配置中包含的对象
* 使 NPC 实际看向或移动到该对象
* 影响任何正在进行的动作步骤

### 连接时设置初始注意力

若要在玩家进行第一轮对话前预先设定 NPC 的关注对象，请将 **Initial Attention** 字段（位于 `ConvaiActionConfigSource` 中）设为 **Actionable Objects** 列表中的某个对象名称。这等同于在连接时调用 `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` 使其与对象的 `Name` （位于 `ConvaiActionConfigSource`中）一致。当学生进入触发区域时，NPC 的指向依据会自动转移到该设备。

**预期结果：** 当学生走到除颤器设备旁时，“告诉我如何使用它”可以可靠地解析为除颤器，无需学生明确说出设备名称。

### 后续步骤

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

{% content-ref url="/pages/0341126fa4c492311dab4fb6aca6d0c64191016b" %}
[角色动作脚本参考](https://docs.convai.com/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 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/convai-unity-sdk/features/character-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.
