> 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/narrative-design/troubleshoot-narrative-design.md).

# 排查叙事设计问题

使用此页面诊断叙事设计问题，例如缺少章节事件、错误的过渡、被忽略的模板键以及获取失败。打开 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 后重试。

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

***

### 相关页面

{% content-ref url="/pages/ff19704aac20f7d6e4bf5c3214636ccbe4248151" %}
[叙事触发器](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/narrative-design/narrative-triggers.md)
{% endcontent-ref %}

{% content-ref url="/pages/453cd3ea71434b9c4a8a7da307779eeb39996f99" %}
[模板键](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/narrative-design/template-keys.md)
{% endcontent-ref %}

{% content-ref url="/pages/01a30a9c684189ac16deee8b6b420f60eb8252f8" %}
[获取叙事数据](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/narrative-design/fetching-narrative-data.md)
{% endcontent-ref %}

{% content-ref url="/pages/579f95b35d1b473357f37588e6fc915a03231497" %}
[叙事设计 Blueprint 参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/narrative-design/narrative-design-blueprint-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:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/narrative-design/troubleshoot-narrative-design.md?ask=<question>
```

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.