> 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 **输出日志** 通过 **Window > Output Log** 以捕获来自 `ConvaiChatbotComponentLog` 和 `ConvaiNarrativeHTTP` 在复现问题时。

### 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 缺失` 当名称为空时。

**原因——会话未连接且组件已销毁：** 命名触发器会在 `PendingTriggers` 中排队，但如果组件在会话重新连接前被销毁，队列将被丢弃。

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

**验证：** 调用 **Invoke Narrative Design Trigger** 再次。一个非空的 `NarrativeSectionID` 传递到事件中的值可确认章节已变更。

***

### 章节过渡跳转到了错误的章节

**症状：** **叙事章节已接收** 触发但 `NarrativeSectionID` 识别到意外的章节。

**原因：** 仪表板中的多个触发器具有重叠的名称或条件，或者触发器触发时角色已经位于与预期不同的章节。

**修复：** 打开 Convai 仪表板并查看当前章节上的所有触发器。确认每个触发器名称在该章节内都是唯一的。打印当前 `NarrativeSectionID` 从上一个 **叙事章节已接收** 事件，在调用触发器之前，以验证角色位于预期章节。

**验证：** 在仪表板中确认返回的 `NarrativeSectionID` 与 `destination_section` 与目标触发器相符。

***

### 模板键未应用于章节目标

**症状：** 角色的行为未反映在 `NarrativeTemplateKeys`，或 `{key}` 令牌会原样出现在角色的回复中。

**原因——键是在目标评估之后设置的：** 在映射填充之前，Convai 已经处理了该章节目标。

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

**原因——键名称不匹配：** 映射中的键名与仪表板目标中的占位符令牌不匹配。

**修复：** 将仪表板目标中的占位符文本逐字符与 **叙事模板键** 映射中的键字符串进行比较。

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

**修复：** 在 **详情** 面板，或通过 Blueprint 打印确认在触发器触发时映射已填充。

**验证：** 打印 `NarrativeTemplateKeys` 映射，在调用触发器之前，并确认所需的键值对存在。确认 **输出日志** 在分配映射时没有连接错误，并且会话已打开。

***

### Invoke Narrative Design Trigger 触发了，但没有发生章节变更

**症状：** 函数调用无错误完成，但 **叙事章节已接收** 未触发，且角色行为没有变化。

**原因：** 叙事图中没有与 `TriggerName` 它可从当前章节到达。该触发器可能存在于仪表板中，但未连接到活动章节。

**修复：** 打开 Convai 仪表板并验证该触发器配置为从当前章节出发的出边，而不是从其他章节出发。

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

***

### 在 Reset Dynamic Context 之后，待处理触发器会丢失

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

**原因：** `重置动态上下文` 清除 `PendingTriggers`。在重置之前排队的任何命名触发器都会被丢弃。

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

**验证：** 连接后，检查 **输出日志** 对于 `Invoke Narrative Design Trigger：已执行 | Character ID：... | Session ID：...` 当你再次调用触发器时。

***

### Invoke Speech 不会产生章节变更

**症状：** **Invoke Speech** 运行无错误，但 **叙事章节已接收** 从未触发。

**原因——消息为空：** `TriggerMessage` 为空。插件会记录 `Invoke Speech：TriggerMessage 缺失` 并返回，而不创建上下文事件。

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

**原因——仅有上下文事件：** **Invoke Speech** 通过动态上下文管道暂存一个动态上下文事件。它不会调用 `SendTriggerMessage` 或发送 `trigger_name` 负载。Convai 只有在响应中包含 `BTResponse` 并带有一个 `narrative_section_id`.

**修复：** 在 Convai 仪表板中验证叙事图可以根据你发送的消息内容进行过渡。对于确定性的章节过渡，请使用 **Invoke Narrative Design Trigger** 并改用仪表板中的触发器名称。

**验证：** 确认 **输出日志** 显示 `Invoke Speech：已执行 | Character ID：... | Session ID：...` 并且角色对暂存的消息作出响应。

***

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

**症状：** 异步获取节点总是路由到 **失败时** 执行引脚以及 `Narrative Sections` 或 `Narrative Triggers` 为空。

**原因——API 密钥无效：** Convai API 密钥缺失或不正确。输出日志显示 `UFetchNarrativeSectionsProxy::Activate 无效的角色或 API 密钥` 或 `UFetchNarrativeTriggersProxy::Activate 无效的角色或 API 密钥`.

**修复：** 打开 **Convai 编辑器窗口** 或 **Edit > Project Settings > Plugins > Convai** 并验证 API 密钥与你的 Convai 账户匹配。

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

**修复：** 从 Convai 仪表板的角色页面复制角色 ID，并原样粘贴到 Blueprint 节点的 `CharacterId` 引脚中。

**原因——没有网络：** 在获取节点执行时，设备没有互联网访问。输出日志可能显示 `HTTP 请求失败，错误码为 %d`.

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

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

***

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

**症状：** **Convai Fetch Narrative Sections** 或 **Convai Fetch Narrative Triggers** 运行了，但二者都没有 **成功时** 也没有 **失败时** 执行。

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

**修复：** 确认该角色在仪表板中配置了叙事章节或触发器。检查 **输出日志** 对于 `ConvaiNarrativeHTTP` 消息。验证后重试 `CharacterId` 和 API 密钥。

**验证：** 在修复仪表板数据或凭据后，再次运行获取节点并确认 **成功时** 会触发，并返回非空数组。

***

### 相关页面

{% 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 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/narrative-design/troubleshoot-narrative-design.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.