> 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 的本地查找。

当玩家说“pick up that cylinder”或“go to it”时，有两个独立系统必须就“that”或“it”的含义达成一致：Convai 会把词语匹配到某个目标名称，而 Unity 会把该名称匹配到一个真实 `GameObject` 的场景对象。本页说明这两个步骤，以及用于引导歧义引用的当前注意对象。

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

当 Convai 判断一个模糊引用指向什么时，会评估两个输入：

1. **对象和角色描述** —— `名称` 和 `说明` （或 `简介`）文本，已为每个可操作对象和角色注册。Convai 使用这些文本将“cylinder”匹配到你已注册的对象。
2. **当前注意对象** —— NPC 当前“聚焦”的对象。设置后，Convai 会对“that”或“it”这类歧义引用赋予很高权重。

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

对象不必在 `ConvaiActionConfigSource` 上预先编写，Convai 才能识别它。一个 `ConvaiActionTarget` 组件本身会在组件启用的那一刻引入它，并会在生成和消失时自动跟随。若两者都使用相同的目标名称，已编写的条目总是优先——见 [角色动作脚本参考](/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` —— 告诉你锚定解析到的是已注册对象还是已注册角色。请参见 [角色动作脚本参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/actions-scripting-reference.md) 获取完整的参数值类型。

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

该 `说明` 每个 `ConvaiActionObjectDefinition` 上的字段是锚定准确性最重要的文本——Convai  სწორედ读取它来决定像“cylinder”这样的词指的是哪个对象。请将每个描述写成一句自然语言句子，并包含：

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

|              | 示例                                  |
| ------------ | ----------------------------------- |
| **过于模糊——避免** | `场景中的一个对象`                          |
| **没有位置——避免** | `一个灭火器`                             |
| **良好**       | `一个红色便携式 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) 了解覆盖与补丁语义。
{% endhint %}

### Unity 如何将目标名称匹配到场景对象

一旦 Convai 返回一个目标字符串，将其解析到真实 `GameObject` 对象是本地的、确定性的匹配——它绝不会再次调用 Convai。Unity 会针对当前激活的 `ConvaiActionConfig` 按四步阶梯查找，并在找到结果的第一步停止：

1. **完全匹配** —— 返回的名称与已注册的 `名称`匹配，不区分大小写。
2. **别名** —— 返回的名称与该目标的 `Aliases` 列表中的条目匹配，不区分大小写。别名仅限本地：它们不会发送给 Convai，因此只在已注册名称本身会遗漏该表述时才添加一个（例如`lamp` 用于 `Lantern`）。
3. **规范化** —— 去掉前导的“the”/“a”/“an”并折叠空白后的相同比较。
4. **包含** —— 一种基于子字符串的模糊匹配，仅在不会产生歧义时使用。如果有多个目标都大致匹配，这一步会拒绝猜测，并且解析会失败，而不是选错对象。

具有 `可用` 设为 `false` —— 例如通过 `ConvaiCharacter.Actions` 撤回的已消失对象——会在每一步被跳过。当同一类的两个目标在同一步打平时，离角色更近的那个获胜；绑定到真实 `GameObjectReference` 的目标总会胜过同名但后面没有任何真实对象支撑的条目。

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

没有 `GameObjectReference` 且没有显式 `TextOnly` 标志的目标会被报告为设置错误，因为目标动作永远无法解析它。请在一个刻意没有场景对应物的条目上勾选 `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 参数

可选的 `反应` 参数（`ConvaiRespondMode`，命名空间 `Convai.Runtime`）用于控制注意对象变更是否触发新的 LLM 回合。默认值会更新锚定上下文，而不会提示回复。如果你希望 Convai 对焦点变化做出自然语言回应，请传入 `ConvaiRespondMode.Silent` ，或者传入 `ConvaiRespondMode.MustRespond` ConvaiRespondMode.MustRespond `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" %}
无效更新会在暂存之前被拒绝。每种情况都会在 Console 中记录一条警告。
{% endhint %}

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

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

### 注意范围

注意对象只会影响 Convai 在未来回合中的引用解析。设置注意对象不会：

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

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

要在玩家首次回合前预先设定 NPC 的焦点，请将 **Initial Attention** 字段在 `ConvaiActionConfigSource` 中设置为你 **Actionable Objects** 列表中某个对象的名称。这等同于在连接时调用 `SetCurrentAttentionObject` 。

初始注意对象必须与 **Actionable Objects** 中的条目完全匹配（不区分大小写）。如果不匹配，该字段会被静默从连接载荷中省略，并记录一条警告。

### 使用示例

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

**场景：** 一个工业检查模拟。当受训者的光标悬停在某件设备上时，更新讲师 NPC 的注意对象，这样“point at it”就能正确解析。

```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();
    }
}
```

**预期结果：** 当受训者将光标悬停在气阀上时，讲师的锚定会切换到该气阀。“point at it”现在能够可靠地解析到悬停的对象。

#### 示例 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 的锚定会自动切换到该设备。

**预期结果：** 当学生走到除颤仪站旁时，“show me how to use it” 会可靠地解析到除颤仪，而无需学生明确说出它的名称。

### 下一步

{% 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 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.