叙事设计故障排查

诊断并修复叙事设计问题，包括章节事件缺失、过渡错误、模板键被忽略以及获取失败。

使用此页面诊断叙事设计问题，例如缺少章节事件、错误的过渡、被忽略的模板键以及获取失败。打开 Unreal Engine 输出日志 通过 窗口 > 输出日志 以捕获来自以下内容的连接和会话错误： ConvaiChatbotComponentLog 和 ConvaiNarrativeHTTP 同时重现问题。

On Narrative Section Received 从不触发

症状： 绑定到 On Narrative Section Received 的 Blueprint 事件在调用后未执行 Invoke Narrative Design Trigger.

原因——触发器名称不匹配： 该 TriggerName 字符串与 Convai 控制台中当前章节配置的任何触发器名称都不匹配。

修复： 打开 Convai 控制台，导航到该角色的叙事图，并按输入内容精确复制触发器名称。将其粘贴到 Blueprint 节点的 TriggerName 输入框中。确认没有前导或尾随空格。

原因——角色 ID 错误： 该 CharacterID 在 UConvaiChatbotComponent 与配置了其叙事图的角色不匹配。

修复： 验证该 CharacterID 在 详细信息 面板与 Convai 控制台中显示的角色 ID 相匹配。

原因——触发器名称为空： 该 TriggerName 输入为空。

修复： 确认 Blueprint 节点传递了非空字符串。输出日志会显示 Invoke Narrative Design Trigger: TriggerName is missing 当名称为空时。

原因——会话未连接且组件已销毁： 命名触发器会排队到 PendingTriggers 中，等待断开连接期间执行；但如果组件在会话重新连接前被销毁，队列会被丢弃。

修复： 确认 bAutoInitializeSession 为 true 或调用 StartSession 显式地。确保在会话打开前组件不会被销毁。检查 输出日志 以查看连接错误。

验证： 再次调用 Invoke Narrative Design Trigger 。一个非空的 NarrativeSectionID 传递到事件中，便可确认章节已切换。

章节过渡推进到了错误的章节

症状： On Narrative Section Received 触发了，但 NarrativeSectionID 识别到了意外的章节。

原因： 多个触发器在控制台中的名称或条件重叠，或者当触发器触发时，角色已经处于与预期不同的章节。

修复： 打开 Convai 控制台并检查当前章节上的所有触发器。确认每个触发器名称在该章节内都是唯一的。在调用触发器之前，打印当前 NarrativeSectionID 来自上一个 On Narrative Section Received 事件中的内容，以验证角色是否处于预期章节。

验证： 在控制台中确认返回的 NarrativeSectionID 与 destination_section 匹配，即目标触发器的章节。

模板键未应用到章节目标

症状： 角色的行为没有反映在 NarrativeTemplateKeys，或 {key} 中设置的值，token 在角色回复中被原样显示。

原因——在目标评估之后才设置键： 在地图被填充之前，该章节目标已由 Convai 处理完毕。

修复： 在任何触发器触发之前，或在调用会推进到其目标引用这些键的章节的触发器之前， Begin Play 分配所有必需的模板键。

原因——键名称不匹配： 地图中的键名与控制台目标中的占位符 token 不匹配。

修复： 将控制台目标中的占位符文本与 Narrative Template Keys 映射中的键字符串逐字符对比。

原因——映射为空： 该 NarrativeTemplateKeys 映射没有条目。

修复： 在 详细信息 面板中或通过 Blueprint 打印确认触发器触发时该映射已填充。

验证： 打印 NarrativeTemplateKeys 映射后再调用触发器，并确认存在预期的键值对。确认 输出日志 没有显示连接错误，并且在分配映射时会话已打开。

Invoke Narrative Design Trigger 触发但没有发生章节切换

症状： 函数调用无错误地完成，但 On Narrative Section Received 未触发，且角色行为没有变化。

原因： 叙事图中没有与 TriggerName 匹配且可从当前章节到达的触发器。该触发器可能存在于控制台中，但未连接到活动章节。

修复： 打开 Convai 控制台，验证该触发器是否被配置为从当前章节发出的边，而不是来自其他章节。

验证： 在控制台中确认该触发器出现在角色当前所在章节的出边列表中。将 Blueprint 中的 TriggerName 与控制台中的 trigger_name 逐字符比较。

重置动态上下文后，待处理触发器丢失

症状： 你调用了 Invoke Narrative Design Trigger 在会话连接之前，但连接后触发器从未重新播放。

原因： Reset Dynamic Context 会清除 PendingTriggers。在重置之前排队的任何命名触发器都会被丢弃。

修复： 避免在 Reset Dynamic Context 命名触发器入队与会话连接之间调用。如果必须重置动态上下文，请在会话打开后重新调用触发器。

验证： 连接后，检查 输出日志 关于 Invoke Narrative Design Trigger: Executed | Character ID : ... | Session ID : ... ，然后再次调用触发器。

Invoke Speech 不会产生章节切换

症状： Invoke Speech 运行时没有错误，但 On Narrative Section Received 从不触发。

原因——消息为空： TriggerMessage 为空。插件会记录 Invoke Speech: TriggerMessage is missing 并返回，而不分阶段地创建上下文事件。

修复： 确认 Blueprint 节点传递了非空字符串。

原因——仅为上下文事件： Invoke Speech 通过动态上下文管线分阶段创建动态上下文事件。它不会调用 SendTriggerMessage 或发送 trigger_name 负载。Convai 只有在响应包含 BTResponse 以及 narrative_section_id.

修复： 时才会推进章节；请在 Convai 控制台中验证叙事图是否可以从你发送的消息内容进行过渡。若要实现确定性的章节切换，请改用 Invoke Narrative Design Trigger 并配合控制台触发器名称。

验证： 确认 输出日志 显示 Invoke Speech: Executed | Character ID : ... | Session ID : ... 并且角色会对已分阶段的消息作出响应。

Convai Fetch Narrative Sections 或 Convai Fetch Narrative Triggers 总是触发 On Failure

症状： 异步获取节点总是路由到 On Failure 执行引脚，并且 Narrative Sections 或 Narrative Triggers 为空。

原因——API key 无效： Convai API key 缺失或不正确。输出日志会显示 UFetchNarrativeSectionsProxy::Activate Invalid Character or API key 或 UFetchNarrativeTriggersProxy::Activate Invalid Character or API key.

修复： 打开 Convai Editor 窗口 或 编辑 > 项目设置 > 插件 > Convai 并验证 API key 与你的 Convai 账户一致。

原因——CharacterId 无效： 该 CharacterId 输入与所连接的 Convai 账户中的任何角色都不匹配。

修复： 从 Convai 控制台角色页面复制角色 ID，并精确粘贴到 Blueprint 节点的 CharacterId 引脚中。

原因——无网络： 在获取节点执行时，设备没有互联网访问。输出日志可能会显示 HTTP request failed with code %d.

修复： 在调用获取节点之前添加网络连通性检查。不要在无法保证网络访问的离线构建中调用获取节点。

验证： 在 Play In Editor 中再次运行获取节点。 成功时 引脚应触发。检查 Narrative Sections 或 Narrative Triggers 以确认返回的数组包含你期望该角色拥有的条目。

获取节点不会触发 On Success 或 On Failure

症状： Convai Fetch Narrative Sections 或 Convai Fetch Narrative Triggers 运行了，但既没有 成功时 也没有 On Failure 被执行。

原因： HTTP 请求可能已成功，但响应数组无法解析为叙事结构。在当前插件源码中，此路径会直接返回，而不会广播任一委托。

修复： 确认该角色在控制台中配置了叙事章节或触发器。检查 输出日志 关于 ConvaiNarrativeHTTP 消息。验证 CharacterId 和 API key 后重试。

验证： 修复控制台数据或凭据后，再次运行获取节点并确认 成功时 以非空数组触发。

晚安