凝视与注意力故障排查

针对 13 个最常见的凝视与注意力问题的修复方法——静止眼睛、头部冻结、眼睑穿模、注意力未命中以及焦点提供者冲突。

请先使用下面的诊断分流来确定是哪个系统出了问题，然后在表格中查找你的症状。

第一步诊断： 在 Play 模式下，读取 ConvaiAttentionController.Current.IsValid 通过调试脚本或 Inspector。

• IsValid = false → 问题出在 注意力系统 (没有提供者返回候选，或所有相关性分数都为零)
• IsValid = true 但眼睛/头部静止不动 → 问题出在 注视系统 (Avatar 配置、配置文件或组件设置)

---

症状表

症状	可能原因	修复
眼睛完全不动	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 页面。

凝视与注意力脚本 API