> 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 负责将该名称匹配到一个真实的 `GameObject` 场景中的对象。本页说明这两个步骤，以及用于引导歧义指代解析的当前注意对象。

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

Convai 在决定模糊指代指向什么时，会评估两个输入：

1. **对象和角色描述** —— `Name` 和 `描述` （或 `Bio`）文本，为每个可操作对象和角色注册。Convai 使用这些内容将“cylinder”匹配到你注册的对象。
2. **当前注意对象** ——NPC 当前“聚焦”的对象。设置后，Convai 会在“那个”或“它”之类的歧义指代上强烈权重考虑它。

`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`）。其 `类型` 属性是一个 `ConvaiActionTargetKind` 值—— `无`, `对象`，或 `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. **精确** ——返回的名称与某个已注册的 `Name`名称匹配，不区分大小写。
2. **别名** ——返回的名称匹配该目标的某个 `别名` 列表中的条目，不区分大小写。别名仅限本地：它们绝不会发送给 Convai，因此只在已注册名称本身会遗漏某种叫法时才添加一个（`灯` 对于一个 `提灯`，例如）。
3. **规范化** ——在去掉开头的“the”/“a”/“an”并折叠空白后进行相同的比较。
4. **包含** ——一种基于子字符串的模糊匹配，仅在不会产生歧义时使用。如果多个目标都大致匹配，这一步会拒绝猜测，并使解析失败，而不是选错。

带有 `可用状态的` 设置为 `false` ——例如通过 `ConvaiCharacter.Actions` ——都会在每一步被跳过。当两个同类目标在同一步打平时，离角色更近的那个获胜；绑定到真实 `GameObjectReference` 始终会胜过后面没有实体的同名条目。

解析后的绑定决定移动或注视执行器的目标位置： `InteractionPoint` 在匹配到的 `ConvaiActionObjectDefinition` 或 `ConvaiActionCharacterDefinition` （或者 `ConvaiActionTarget` 组件）中；如果已设置，则使用它，否则使用绑定的 `GameObjectReference`自身的 transform。

一个没有 `GameObjectReference` 且没有明确的 `TextOnly` 标志会被报告为设置错误，因为带目标的动作永远无法解析它。勾选 `TextOnly` 在一个故意没有场景对应项的条目上——Convai 仍然可以谈论它，但不会要求任何执行器对其执行动作。

### 运行时注意对象 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);
```

注意对象的变更会先在本地暂存，并在下一批动态上下文中发送（最长可达 `ConvaiCharacter.DynamicContextBatchDelaySeconds`，默认 0.5 秒），或者在你调用 `character.DynamicContext.Flush()`.

### 静默失败条件

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

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

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

### 注意对象作用范围

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

* 创建新的可操作目标
* 更改 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` 设置为与该对象的 `Name` 中的 `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.