> 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/utilities/gaze-and-attention/troubleshooting.md).
# 注视与注意力故障排除
请先使用下面的诊断分流来确定是哪个系统出了问题，然后在表格中查找你的症状。
{% hint style="info" %}
**第一步诊断：** 在 Play 模式下，读取 `ConvaiAttentionController.Current.IsValid` 通过调试脚本或 Inspector。
* `IsValid = false` → 问题出在 **注意力系统** (没有提供者返回候选，或所有相关性分数都为零)
* `IsValid = true` 但眼睛/头部静止不动 → 问题出在 **注视系统** (Avatar 配置、配置文件或组件设置)
{% endhint %}
***
### 症状表
| 症状 | 可能原因 | 修复 |
| ---------------------------------------- | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- |
| 眼睛完全不动 | Avatar 中未分配眼睛骨骼 | 打开角色的 Avatar 配置（**Avatar Inspector → 配置 Avatar**）并分配 Left Eye 和 Right Eye 骨骼 |
| 眼睛不动——Avatar 已有眼睛骨骼 | `ConvaiEyeGazeActuator` 缺失 | 添加 Eye Gaze 组件（**Convai → Embodiment → Eye Gaze**）到角色的根 GameObject |
| 头部不旋转 | `ConvaiHeadLookActuator` 缺失 | 添加 Head Look 组件（**Convai → Embodiment → Head Look**）到角色的根 GameObject |
| 头部不旋转——组件已存在 | Avatar 的 humanoid 映射中没有颈部/头部骨骼 | 打开 Avatar 配置并确认已分配颈部和头部骨骼 |
| 角色从不看向玩家/摄像机 | 未创建默认焦点提供者 | 启用 **自动创建默认焦点提供器** on `ConvaiAttentionController`，或者实现自定义 `IFocusTargetProvider` 以摄像机为目标 |
| `AttentionReading.IsValid` 总是 `false` | 所有提供者都返回 `false` 来自 `TryGetCandidate()`，或者都返回相关性 `0` | 在……中记录每个提供者的返回值 `TryGetCandidate()`。检查距离——如果玩家超过 `DefaultFocusMaxDistance` (默认：8m)，内置提供者返回零相关性。 |
| 自定义 `IFocusTargetProvider` 被忽略 | **在层级中发现提供器** 已禁用，或者提供者不在角色或其子对象上 | 启用 **在层级中发现提供器**，或者调用 `RefreshProviders()` 在运行时添加组件后 |
| 两个提供者冲突——眼睛在目标之间抖动 | 提供者具有相同优先级且相关性分数振荡 | 分配不同的 `优先级` 值。默认摄像机提供者的优先级为 `0`；使用 `10`对应该占主导的自定义提供者使用 +。 |
| 在大幅注视角度下，眼睑穿过网格 | 未配置眼睑 blendshape 跟随，或 blendshape 索引错误 | 在……中确认眼睑 blendshape 驱动已设置 `ConvaiEyeGazeActuator` Inspector。眼睑跟随需要网格上具有命名的 blendshape。 |
| 眼睛持续抖动或震颤 | `TrackingSharpness` 对于该骨架的骨骼分辨率来说太高 | 降低 `TrackingSharpness` 在 `ConvaiGazeEyeProfile` (默认：18——低多边形骨架可尝试 10–14) |
| 注视感觉很机械——没有自然变化 | 扫视或微颤已禁用 | 启用 `EnableSaccades` 是位于 `EnableMicroTremor` 在 `ConvaiGazeEyeProfile` |
| 角色会一直盯着不移开视线 | `MaxContinuousHoldSeconds` 设置得太高，或者 `InterestDecayPerSecond` 接近零 | 降低 `MaxContinuousHoldSeconds` (默认：5秒) 或提高 `InterestDecayPerSecond` 在 `ConvaiAttentionProfile` |
| 眼睛会跟踪，但头部完全不动 | `MinimumHeadContribution` 为 `0` 在 `ConvaiGazeHeadProfile`，或头部驱动器缺失 | 添加 `ConvaiHeadLookActuator` 如果缺失。提高 `MinimumHeadContribution` (默认：0.45)，使头部始终参与一定的旋转。 |
| `ConvaiGazeCoordinator` 在……中为空 `Awake()` | Coordinator 在……期间创建 `ConvaiEyeGazeActuator` 初始化期间，在……之后 `Awake()` | 将对 coordinator 的访问移到 `Start()` 或更晚的生命周期事件 |
| `AnimationRiggingGazeBridge` 没有效果 | `CONVAI_ANIMATION_RIGGING` 未设置定义符号 | 添加 `CONVAI_ANIMATION_RIGGING` 到 **Player Settings → Scripting Define Symbols**。只有在存在此符号时，桥接组件才会编译。 |
***
### 诊断步骤
验证 Avatar 眼睛骨骼配置
1. 在 Project 窗口中选择角色的模型资源
2. 在 Inspector 中切换到 **Rig** 选项卡 → 单击 **配置 Avatar**
3. 在 Avatar Inspector 中展开 **头部** 部分
4. 请确认 **左眼** 是位于 **右眼** 已分配到正确的骨骼
5. 单击 **完成** 并重新进入 Play 模式
如果骨架未暴露眼睛骨骼， `ConvaiEyeGazeActuator` 如果已配置 blendshape，则将回退为仅使用 blendshape 的眼球运动；如果两者都不可用，则不会执行任何操作。
注意力管线检查清单
当……时，按顺序执行这些检查 `AttentionReading.IsValid` 仍然 `false`:
1. **组件存在** ——确认 `ConvaiAttentionController` 位于角色根对象上
2. **提供者存在** ——要么 **自动创建默认焦点提供器** 已启用，或者至少有一个 `IFocusTargetProvider` 组件存在于角色或其子对象上
3. **相关性非零** ——在你的提供者的……中添加临时日志 `TryGetCandidate()` 以确认它返回 `true` 以及一个带有 `相关性 > 0`
4. **距离检查** ——如果使用默认提供者，请确认玩家/摄像机位于……以内 `DefaultFocusMaxDistance` (默认：8m)
5. **Coordinator 状态** ——确认 `ConvaiGazeCoordinator` 存在于角色上（由眼睛驱动器自动创建）。如果它为空， `ConvaiEyeGazeActuator` 则说明未正确初始化——请检查是否缺少骨骼或 Console 中是否有初始化错误。
***
### 下一步
有关完整 API 参考，包括 `IFocusTargetProvider` 实现约定和可读的注意力状态属性，请参阅 Scripting API 页面。
{% content-ref url="/pages/5a9422b007899ae59891f1bd5d95035da644a167" %}
[注视与注意力脚本 API](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/utilities/gaze-and-attention/scripting-api.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:
```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/utilities/gaze-and-attention/troubleshooting.md?ask=
```
The question should be specific, self-contained, and written in natural language.
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.