> 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-unreal-engine-plugin/features/gaze-attention/gaze-attention-reference.md).

# 注视注意力参考

注视注意力系统的完整属性、事件、方法和类参考，包括所有默认值和版本特定行为。

凝视注意系统中每个属性、事件、方法和类的权威参考。该 [Convai 玩家组件](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/blueprint-reference/convai-player-component.md) 和 [Convai 对象组件](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/blueprint-reference/convai-object-component.md) 页面仅总结其组件本地的凝视表面；完整的跨组件 API、默认值和版本特定行为请使用本页。

事实来源： `Source/Convai/Public/ConvaiPlayerComponent.h`, `Source/Convai/Public/ConvaiObjectComponent.h`, `Source/Convai/Public/Gaze/ConvaiGazeHighlightActor.h`, `Source/Convai/Public/Gaze/ConvaiGazeCursorWidget.h`，以及 `Source/Convai/Public/ConvaiChatbotComponent.h`.

### `UConvaiPlayerComponent` — 凝视注意属性

除非另有说明，所有属性都位于 **Convai | 凝视注意力** 详细信息面板中的类别。

#### 核心开关

| 属性                     | 类型     | 默认值     | 说明                             |
| ---------------------- | ------ | ------- | ------------------------------ |
| `bEnableGazeAttention` | `bool` | `false` | 总开关。启用之前，所有其他凝视属性都会变灰。 `true`. |

#### 注意行为

| 属性                       | 类型                | 默认值     | 说明                                                                                     |
| ------------------------ | ----------------- | ------- | -------------------------------------------------------------------------------------- |
| `GazeShouldRespond`      | `EC_RunLLMOption` | `Never` | 当某个凝视目标被提升为注意对象时会发生什么。 `Always` — 聊天机器人会立即生成回复。 `自动` — 由 Convai 决定。 `Never` — 仅静默更新状态。 |
| `GazeAttentionText`      | `FString`         | `""`    | 随注意提升一并发送的叙事事件文本（例如 `“玩家正在看阀门。”`)。仅在以下情况下才有效 `GazeShouldRespond` 是 `自动` 或 `Always`.    |
| `GazeAttentionDelay`     | `float` （秒）       | `1.0`   | 持续注视时长，超过后高亮对象会被提升为“正在注意”。                                                             |
| `GazeAttentionLossDelay` | `float` （秒）       | `5.0`   | 离开注视时长，超过后当前注意槽会被释放。                                                                   |

#### 追踪设置

| 属性                   | 类型                                    | 默认值              | 说明                                                                                                                       |
| -------------------- | ------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `GazeMaxDistance`    | `float` （厘米，AdvancedDisplay）          | `5000.0`         | 从玩家摄像机或 VR HMD 发出的最大线段追踪距离。                                                                                              |
| `GazeAngleTolerance` | `float` （度）                           | `5.0`            | 点积回退圆锥的半角。当严格追踪未能捕获有效凝视目标，且未被非 Convai 几何体阻挡时，系统会遍历子系统池中的所有 `UConvaiObjectComponent` 实例，并在该圆锥内选取与视线方向最对齐的那个。设为 `0` 可禁用回退。 |
| `GazeTraceChannel`   | `ECollisionChannel` （AdvancedDisplay） | `ECC_Visibility` | 凝视线追踪使用的碰撞通道。                                                                                                            |

#### 高亮属性（类别：Convai | 凝视注意 | 高亮）

| 属性                               | 类型                                       | 默认值                          | 说明                                                                                                  |
| -------------------------------- | ---------------------------------------- | ---------------------------- | --------------------------------------------------------------------------------------------------- |
| `GazeHighlightActorClass`        | `TSubclassOf<AConvaiGazeHighlightActor>` | 插件默认值                        | 在被注视对象上方生成的高亮 actor 类。可分配子类以实现自定义视觉效果。                                                              |
| `GazeHighlightColor`             | `FLinearColor`                           | `(1.0, 0.9, 0.2, 1.0)` （浅黄色） | 传递给高亮 actor 的 `HighlightColor` 属性之前 `SetTarget` 被调用。                                                |
| `GazeOverlayMaterial`            | `TSoftObjectPtr<UMaterialInterface>`     | 未设置                          | 叠加材质。未设置时，插件使用 `/ConvAI/Highlights/M_ConvaiGazeOverlay` （菲涅耳边缘轮廓）。可替换为任何暴露 `EmissiveColor` 向量参数的材质。 |
| `GazeHighlightEmissiveIntensity` | `float` （AdvancedDisplay）                | `2.5`                        | 传递给高亮 actor 的 `EmissiveIntensity` 标量参数。插件的叠加材质会在内部将 `EmissiveColor` 乘以该值。                           |

#### 光标属性（类别：Convai | 凝视注意 | 光标）

| 属性                      | 类型                                     | 默认值              | 说明                                        |
| ----------------------- | -------------------------------------- | ---------------- | ----------------------------------------- |
| `bShowGazeCursor`       | `bool`                                 | `true`           | 在凝视追踪激活时显示屏幕中央准星。                         |
| `bAlwaysShowGazeCursor` | `bool`                                 | `false`          | 即使凝视不在 Convai 对象上，也将光标保持在“活动”视觉状态。        |
| `GazeCursorWidgetClass` | `TSubclassOf<UConvaiGazeCursorWidget>` | 插件默认值            | 用于光标的小部件类。可用 Blueprint 子类覆盖以实现自定义准星外观。    |
| `凝视光标激活颜色`              | `FLinearColor`                         | 白色 `(1,1,1,1)`   | 当凝视在 Convai 对象上时的光标颜色。                    |
| `凝视光标空闲颜色`              | `FLinearColor` （AdvancedDisplay）       | `(1,1,1,0)` （透明） | 当凝视未指向任何对象时的光标颜色。默认 alpha 为 0，使光标在空闲时不可见。 |
| `GazeCursorDotSize`     | `float` （Slate 单位，AdvancedDisplay）     | `6.0`            | 未缩放 Slate 单位下光标方块的边长。                     |
| `凝视光标淡入时间`              | `float` （秒，AdvancedDisplay）            | `0.1`            | 从 Idle 到 Active 的淡入持续时间。 `0` 会立即吸附。       |
| `凝视光标淡出时间`              | `float` （秒，AdvancedDisplay）            | `0.25`           | 从 Active 到 Idle 的淡出持续时间。 `0` 会立即吸附。       |

### `UConvaiPlayerComponent` — 凝视事件

所有事件都位于 **Convai | 凝视注意 | 事件** 类别中，并使用委托类型 `FConvaiPlayerGazeEvent`.

**委托签名：** `(UConvaiPlayerComponent* PlayerComponent, UConvaiObjectComponent* ObjectComponent)`

| 事件                  | 触发时机                                                                                                                            |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `OnGazeBegin`       | 玩家的视线进入某个 Convai 对象的瞬间触发。会在达到任何注意阈值之前触发。                                                                                        |
| `OnGazeEnd`         | 玩家的视线离开某个 Convai 对象的瞬间触发，不受注意状态影响。                                                                                              |
| `OnAttentionGained` | 当某个被注视对象在持续 `GazeAttentionDelay` 秒后被提升为“正在注意”时触发。即使所有聊天机器人都拒绝此更新也会触发（例如当 **启用操作** 关闭或 `AttentionSource` 是 `显式（Blueprint/C++）`). |
| `OnAttentionLost`   | 当“正在注意”槽被释放时触发——无论是因失去计时器到期、凝视切换到另一个对象，还是目标 actor 被销毁。 `ObjectComponent` 可以是 `nullptr` 当注意目标被销毁时。                               |

{% hint style="warning" %}
`OnAttentionGained` 在玩家组件上表示停留阈值已达到，而不是聊天机器人已接受该更新。请检查 `AttentionSource` 在聊天机器人上并确认 **启用操作** 在角色应答时处于开启状态。
{% endhint %}

### `AConvaiGazeHighlightActor`

由 `UConvaiPlayerComponent` 生成的轻量级 actor，用于在当前凝视目标上方提供视觉反馈。

**UE 版本行为：**

* UE 5.3 及更高版本：将带色调的自发光叠加应用到目标上的每个 `上不可用：` 通过 `SetOverlayMaterial`.
* UE 5.0–5.2：回退为 `DrawDebugBox` 围绕目标边界的盒状线框。 `FallbackBoxThickness` 和 `FallbackBoxPadding` 仅在这些版本上控制线框外观。

**Blueprint 方法：**

| 方法                   | 签名                                                                 | 说明                                                                     |
| -------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------- |
| `SetTarget`          | `(AActor* InTarget, USceneComponent* InTargetComponent = nullptr)` | 应用或清除高亮。传入 `nullptr` 可清除。若 `InTargetComponent` 是一个 `上不可用：`，叠加层将仅限于该组件。 |
| `GetTarget`          | `() → AActor*`                                                     | 对当前目标的只读访问。                                                            |
| `GetTargetComponent` | `() → USceneComponent*`                                            | 可选的子组件范围。 `nullptr` 当高亮覆盖整个 actor 时。                                   |

**属性：**

| 属性                     | 类型                                   | 默认值                    | 说明                                                                                                                                                             |
| ---------------------- | ------------------------------------ | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `HighlightColor`       | `FLinearColor`                       | `(1.0, 0.9, 0.2, 1.0)` | 叠加层的 `EmissiveColor` 参数色调。由 `UConvaiPlayerComponent::GazeHighlightColor`.                                                                                      |
| `EmissiveIntensity`    | `float`                              | `2.5`                  | 写入叠加材质的标量值。 `EmissiveIntensity` 参数。插件材质会将 `EmissiveColor` 乘以该值。                                                                                                |
| `OverlayMaterial`      | `TSoftObjectPtr<UMaterialInterface>` | 未设置                    | 叠加材质。默认值为 `/ConvAI/Highlights/M_ConvaiGazeOverlay`。若在已烘焙构建中缺少插件资源，则回退为 `/Engine/EngineMaterials/EmissiveMeshMaterial` （注意：该回退材质没有参数，因此 `HighlightColor` 不会生效）。 |
| `FallbackBoxThickness` | `float` （AdvancedDisplay）            | `2.0`                  | UE 5.0–5.2 线框盒的线条粗细。                                                                                                                                           |
| `FallbackBoxPadding`   | `float` （AdvancedDisplay）            | `1.05`                 | UE 5.0–5.2 线框盒的尺寸倍数。                                                                                                                                           |

若要使用自定义高亮视觉效果，请在 Blueprint 中子类化 `AConvaiGazeHighlightActor` 并将该子类分配给 `UConvaiPlayerComponent::GazeHighlightActorClass`.

### `UConvaiGazeCursorWidget`

由 `UConvaiPlayerComponent` 在凝视追踪激活时绘制的屏幕中央准星小部件。它是一个纯 C++ 小部件，使用 Unreal 的 `FCoreStyle::WhiteBrush` —— 插件不附带任何纹理资源。

**Blueprint 方法：**

| 方法                   | 签名                                                   | 说明                                               |
| -------------------- | ---------------------------------------------------- | ------------------------------------------------ |
| `SetGazeActive`      | `(bool bInGazeActive)`                               | 当凝视进入或离开某个 Convai 对象时由玩家组件调用。                    |
| `IsGazeActive`       | `() → bool`                                          | 返回当前凝视状态。在 `OnGazeStateChanged` 实现中很有用。          |
| `OnGazeStateChanged` | `(bool bInGazeActive)` （BlueprintImplementableEvent） | 在 Blueprint 子类中重写，以在每次状态变化时运行自定义过渡——切换图像画刷或播放动画。 |

**属性：**

| 属性            | 类型                          | 默认值              | 说明                                       |
| ------------- | --------------------------- | ---------------- | ---------------------------------------- |
| `ActiveColor` | `FLinearColor`              | 白色 `(1,1,1,1)`   | 当凝视在 Convai 对象上时的点颜色。                    |
| `IdleColor`   | `FLinearColor`              | `(1,1,1,0)` （透明） | 当凝视未指向任何对象时的点颜色。默认 alpha 为 0，使光标在空闲时不可见。 |
| `DotSize`     | `float` （Slate 单位）          | `6.0`            | 未缩放 Slate 单位下光标方块的边长。                    |
| `FadeInTime`  | `float` （秒，AdvancedDisplay） | `0.1`            | 从 Idle 到 Active 的淡入持续时间。 `0` 会瞬间吸附。      |
| `FadeOutTime` | `float` （秒，AdvancedDisplay） | `0.25`           | 从 Active 到 Idle 的淡出持续时间。 `0` 会瞬间吸附。      |

覆盖 `GazeCursorWidgetClass` 位于 `UConvaiPlayerComponent` 以切换为 Blueprint 子类。 `SetGazeActive` 在运行时仍会在覆盖实现上被调用。

### `UConvaiObjectComponent` — 凝视表面

带有 `UConvaiObjectComponent` 标记的对象会暴露凝视属性、方法和事件（详细信息面板类别 **Convai | 对象 | 凝视**).

#### 属性

| 属性            | 类型                   | 默认值    | 说明                                                                                                                                                                                                                                                                                                                          |
| ------------- | -------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `bGazeable`   | `bool`               | `true` | 此对象是否参与凝视检测。当 `false`时，该对象会同时从线追踪匹配和点积回退中被排除。                                                                                                                                                                                                                                                                               |
| `ObjectEntry` | `FConvaiObjectEntry` | —      | 此对象的身份和目标数据。按凝视范围的子网格过滤使用 `ObjectEntry.ComponentName` 当 `ObjectEntry.ObjectReference` （Details 面板标签 **对象为**) 为 `特定组件`。请参阅 [组件作用域凝视](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/gaze-attention/how-gaze-attention-works.md#component-scoped-gaze) 和 [`FConvaiObjectEntry`](#fconvaiobjectentry). |

#### Blueprint 方法

| 方法                         | 签名                                                                                     | 说明                                                                                                                                                                                                                |
| -------------------------- | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GetResolvedComponent`     | `() → USceneComponent*`                                                                | 返回由 `ObjectEntry.ComponentName`解析得到的子组件。每次调用都会重新验证缓存的匹配——如果缓存组件的所有者或名称不再符合过滤条件，会自动重新扫描该 actor 的组件树，因此不存在手动刷新调用。返回 `nullptr` 当 `ObjectEntry.ObjectReference` 不是 `特定组件`，当 `ObjectEntry.ComponentName` 为空，或者名称无法解析时。 |
| `NotifyGazeBegin`          | `(UConvaiPlayerComponent* Player)`                                                     | 由 `UConvaiPlayerComponent` 调用，当玩家的视线进入此对象时。还会触发 `OnGazedIn`。可从 Blueprint 调用，以模拟此组件上的凝视进入事件。                                                                                                                       |
| `NotifyGazeEnd`            | `(UConvaiPlayerComponent* Player)`                                                     | 由 `UConvaiPlayerComponent` 当玩家的视线离开此对象时调用。还会触发 `OnGazedOut`。可从 Blueprint 调用，以模拟凝视离开事件。                                                                                                                            |
| `NotifyGazeAttentionBegin` | `(UConvaiPlayerComponent* Player, const FString& Text, EC_RunLLMOption ShouldRespond)` | 由 `UConvaiPlayerComponent` 当此对象被提升为“正在注意”时调用。还会触发 `OnAttentionGained`。可从 Blueprint 调用，以手动将此对象在任意聊天机器人上提升为注意对象。                                                                                                    |
| `NotifyGazeAttentionEnd`   | `(UConvaiPlayerComponent* Player = nullptr)`                                           | 由 `UConvaiPlayerComponent` 当此对象从注意状态中释放时调用。还会触发 `OnAttentionLost`之后，将其调用到聊天机器人组件上。传入 `nullptr` 以在没有特定玩家上下文的情况下释放。                                                                                                 |

#### 事件

**委托签名：** `FConvaiObjectGazeEvent` — `(UConvaiObjectComponent* ObjectComponent, UConvaiPlayerComponent* PlayerComponent)`

| 事件                  | 触发时机                                                                                            |
| ------------------- | ----------------------------------------------------------------------------------------------- |
| `OnGazedIn`         | 在玩家视线进入此对象的瞬间触发，早于达到任何注意阈值之前。                                                                   |
| `OnGazedOut`        | 在玩家视线离开此对象的瞬间触发。                                                                                |
| `OnAttentionGained` | 当凝视系统在持续凝视阈值之后提升此对象时触发。聊天机器人接受与否是独立的，并且如果 **启用操作** 关闭或 `AttentionSource` 是 `显式（Blueprint/C++）`. |
| `OnAttentionLost`   | 当此对象从“正在注意”槽中释放时触发。 `PlayerComponent` 可以是 `nullptr` 在目标被销毁的路径上——使用前请先做空值检查。                     |

### `UConvaiChatbotComponent` — 注意 API

| 成员                     | 签名                                                                                                                                                                                                                      | 说明                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SetObjectInAttention` | `(FConvaiObjectEntry AttentionObject, FString Text = "", EC_RunLLMOption ShouldRespond = Auto, EConvaiContextDelivery Delivery = Send Normally, bool bAddAttentionEvent = true, bool bFlushImmediately = false) → void` | 设置聊天机器人当前处于注意状态的对象，可选带叙事上下文文本和 LLM 响应选项。写入 `AttentionSource` 到 `显式` （或 `None` 当 `AttentionObject.Name` 为空时，则释放该槽位）。当 `ShouldRespond` 是 `自动` 或 `Always` 和 `bAddAttentionEvent` 是 `true` （默认值）时，会排队一个一次性即时事件，内容为 `“<observer> 正在关注 <object name>”` —— 永不持久化，每次调用只触发一次。当 `EnvironmentData.bEnableActions` 是 `false` (**启用操作** 在详细信息面板中），或者对象尚未出现在聊天机器人的环境列表中，或未包含在连接时发送的对象中时，不起作用；这些情况都会记录一条警告，指出对象及原因。 `bFlushImmediately` 会立即发送更新，而不是批量处理。 |
| `AttentionSource`      | `EConvaiAttentionSource` （BlueprintReadOnly，Transient）                                                                                                                                                                  | 最后设置注意槽的人。 `None`, `Gaze`，或 `显式（Blueprint/C++）`。读取此属性可诊断注意锁定。                                                                                                                                                                                                                                                                                                                                                                             |

#### 凝视门控方法

以下方法由凝视系统内部调用，但也可由 Blueprint 调用，用于自定义凝视集成。

| 方法                                  | 签名                                                                                                                                                                                                                      | 返回                          | 说明                                                                                                                                                                                                                                                                     |
| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `TrySetObjectInAttentionFromGaze`   | `(FConvaiObjectEntry AttentionObject, FString Text = "", EC_RunLLMOption ShouldRespond = Auto, EConvaiContextDelivery Delivery = Send Normally, bool bAddAttentionEvent = true, bool bFlushImmediately = false) → bool` | `true` 如果接受， `false` 如果拒绝   | 仅在以下情况下设置注意槽 `EnvironmentData.bEnableActions` 是 `true` 和 `AttentionSource` 是 `None` 或 `Gaze`。成功后，写入 `AttentionSource = Gaze`。返回 `false` ，并在操作被禁用或该槽被以下对象锁定时记录一条包含对象名称的警告 `显式` 调用方——该调用会被拒绝，而不是静默失败。内部由 `UConvaiPlayerComponent`使用；也向 Blueprint 暴露，用于必须遵守所有权协议的自定义凝视集成。 |
| `TryClearObjectInAttentionFromGaze` | `(FConvaiObjectEntry ExpectedObject) → bool`                                                                                                                                                                            | `true` 如果已清除， `false` 如果已跳过 | 仅在以下情况下清除注意槽 `AttentionSource == Gaze` 且当前被注意的对象匹配 `ExpectedObject`。可防止过时或延迟的失去凝视调用清除一个已被其他玩家或系统占用的注意槽。                                                                                                                                                                |

#### `EConvaiAttentionSource`

| 值      | 显示名称              | 含义                                                                 |
| ------ | ----------------- | ------------------------------------------------------------------ |
| `None` | None              | 注意槽为空。凝视可以占用它。                                                     |
| `Gaze` | Gaze              | 槽位由凝视系统拥有。凝视可以更新或释放它。                                              |
| `显式`   | 显式（Blueprint/C++） | 槽位被直接 `SetObjectInAttention` 调用锁定。直到调用方用空的 `SetObjectInAttention`. |

#### `EC_RunLLMOption`

| 值        | 显示名称   | 含义                    |
| -------- | ------ | --------------------- |
| `自动`     | 自动     | 由 Convai 决定是否生成口语回复。  |
| `Always` | Always | 聊天机器人始终生成口语回复。        |
| `Never`  | Never  | 注意更新静默进行；不会触发 LLM 调用。 |

### `FConvaiObjectEntry`

结构体携带于 `UConvaiObjectComponent::ObjectEntry`。凝视注意会读取身份字段，而对于组件范围的目标定位，则读取下面的运动模式字段。

| 字段     | 类型                       | 默认值        | 凝视相关性                                                                           |
| ------ | ------------------------ | ---------- | ------------------------------------------------------------------------------- |
| `引用`   | `TWeakObjectPtr<AActor>` | `nullptr`  | 此对象条目的 actor 引用。                                                                |
| `名称`   | `FString`                | `""`       | 发送给 Convai 的对象名称为 `current_attention_object`。对象要注册，此项不能为空。                      |
| `说明`   | `FString`                | `""`       | Convai 用来理解对象的自然语言描述。                                                           |
| `对象引用` | `EConvaiObjectReference` | `整个 Actor` | 详细信息面板标签 **对象为**。必须为 `特定组件` 对于 `组件名称` 以将凝视限定到子网格。使用默认 `整个 Actor`时，无论 `组件名称`.    |
| `组件名称` | `FString`                | `""`       | 如何，凝视都会匹配该 actor 的任意原语。 `对象引用` 是 `特定组件` 子组件名称上的大小写不敏感子串过滤器。凝视仅在以下情况下使用此字段 `引用`. |

以及名称解析为`接受半径`, `插槽或骨骼名称`与相关输出）在 [角色动作参考中有文档说明。](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/character-actions/actions-blueprint-reference.md).

### 下一步

{% content-ref url="/pages/2f301cf695f654f0b6dc66672ff9462854021237" %}
[注视注意力使用示例](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/gaze-attention/gaze-attention-usage-examples.md)
{% endcontent-ref %}

{% content-ref url="/pages/ca4f4235151ab1fee69bb58487611f1c6ec30cc6" %}
[排查凝视注意力问题](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/gaze-attention/troubleshoot-gaze-attention.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-unreal-engine-plugin/features/gaze-attention/gaze-attention-reference.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.