阶段 3：参数化动作

第 2 阶段新增了一个无参数的自定义动作。大多数真实动作都需要携带数据—— “等待 5 秒”, “拿起立方体”, “把球放到桌子上”。本阶段将讲解：

1. 一个简单的数值参数（Wait For 的回顾）。
2. 一个角色引用（单个参数解析为一个 AActor*).
3. 一个带两个参数 + 一个连接词的复合动作（Put ... on ...).
4. 通过以下方式约束值： Choices （手动列表）和 Enum （取自一个 UENUM).
5. 实时编辑器预览——既可作为调试辅助，也可直接用于编写模板。

参数类型矩阵

每个 FConvaiActionParam 都有一个 Type 字段，它同时决定发送给 LLM 的线协议提示以及解析器如何解释响应：

Type	线协议提示	解析器
Auto	（无）	按 Reference → Number → Bool 的顺序尝试，最后回退到 String。新参数的默认值。
Reference	：ref	根据以下内容查找该值： Environment.Objects 然后 .Characters.
String	：string	按文本处理。
Number	：number	Atof.
Bool	：bool	true 用于“true”/“yes”/“1”，否则为 false。
Enum	：enum	约束为你选择的一个 UEnum （自动填充 Choices).

无论声明的类型是什么， 上所有值字段 FConvaiResultParam 都会尽力填充。一个 String类型的参数，即使其值刚好是场景中某个对象的名称，也仍然会有 RefValue 被设置。读取你觉得方便的字段即可—— Type 它只表示 LLM 期望填入的是哪个槽位。

示例 A——数值参数

我们重新来过 Wait For ，展示 typed-param 流程的完整端到端过程。

声明模板

1. 选择 Convai 聊天机器人，打开 Environment → Actions.
2. 随附的 Wait For 条目已经有一个参数 秒数 已类型化 Number ，描述为 “等待多长时间，单位为秒”。可直接使用，或添加你自己的。

渲染后的预览（在结构化字段下方自动填充）如下：

Wait For "<time in seconds: number>" — 等待一段时长。time in seconds：等待多长时间，单位为秒。

该 ：number 提示会告诉 LLM 返回一个数值。 "<...>" 加上引号包装则会让它用双引号输出响应值，这样即使值中包含空格，解析器也能明确无歧义地拆分。

在 BP 中读取参数

在你的 OnActionReceivedEvent_V2 处理器中的 Wait For switch 分支：

1. 拖一个 Get Param As Number 节点从聊天机器人引用上拉出。

   • Action：当前的 FConvaiResultAction ，来自循环。
   • Name: 秒数.
2. 把返回的 float 连接到一个 Delay (Duration) 节点。
3. 延迟结束后，调用 Handle Action Completion(true, 0, EventText="Done waiting", ShouldRespond=Auto).

该 EventText 参数可让你告诉机器人 “这已经完成了” ，并且在同一次调用中完成——这对于在不单独调用 Add Context Event.

测试

提问： “等待 3 秒。” 机器人应当暂停，然后说 “Done waiting” 或类似的话（取决于 ShouldRespond 以及 LLM 的情绪）。

示例 B——角色引用

Move To 默认随附配置已经这么做了，但这里给出一个自定义配置的配方。

声明

添加一个动作 Greet ，带一个参数：

• Name: target
• Type: Reference
• 描述: 要问候谁

预览变为：

Greet "<target: ref>" — <action description if any>. target：要问候谁。

在 BP 中读取

1. Get Param As Ref ，使用 Name = "target" 会返回一个 FConvaiObjectEntry。该 Ref 字段是解析出的 AActor* （因为该值匹配到了 Environment.Objects 中的某个内容，自动设置） .Characters).
2. 或 Greet 使用该角色——让他们转向、播放动画，或者取决于你的

意思。

示例 C——带连接词的复合动作 可以用两个 Reference 参数和一个用于第二个参数的连接词来清晰表达：

声明

Action Put，两个参数：

Name	Type	连接词	描述
ball	Reference	（空——第一个参数）	要拿起什么
table	Reference	on	放置到哪里

预览：

Put "<ball: ref>" on "<table: ref>" — 将一个物体放到另一个物体上。ball：要拿起什么。table：放置到哪里。

该 连接词 字段 不是 仅限于介词——它可以是“任何将参数与前文关联起来的文本”。 到, ，使用, 使用, 用于，等等，都可以。

在 BP 中读取

Get Param As Ref(action, "ball")  → FConvaiObjectEntry（球）
Get Param As Ref(action, "table") → FConvaiObjectEntry（桌子）

只要 LLM 选择的名称与你的 Ref 匹配，两者的 Environment.Objects.

都会被填充。

示例 D——受约束的值（Choices） 如果你希望 LLM 从一个固定列表 Choices:

声明

Action 中选择，请填充，一个参数：

• Name: mood
• Type: String
• 描述: 机器人应该呈现的状态
• Choices: happy, sad, angry

预览：

Set Mood "<mood [happy|sad|angry]: string>" — 设置机器人情绪。mood：机器人应该呈现的状态。

该 [choices] 在线协议格式中的这个块会约束 LLM。解析器在接收时也会根据该列表进行验证——不在集合中的值仍会进入结果，但会记录警告。

示例 E——Enum 类型的值

当你的 Blueprint 已经有一个 UENUM 想要使用的时，将该参数 Type 到 Enum切换过去。Details 面板会隐藏手动的 Choices 字段，并显示一个 Enum Type 选择器。

声明

UENUM(BlueprintType)
enum class EBotMood : uint8 { Happy, Sad, Angry };

Action 中选择，请填充，一个参数：

• Type: Enum
• Enum Type: EBotMood
• Name / 描述：与之前一样。

预览：

Set Mood "<mood [Happy|Sad|Angry]: enum>" — 设置机器人情绪。mood：机器人应该呈现的状态。

Choice 块会根据枚举的显示名称自动派生。如果你忘记设置 Enum Type，预览会内联嵌入 [ERROR: EnumType not set] ，这样配置错误在编辑时就会非常明显。

在 BP 中读取

Get Param As String(action, "mood") 返回 “Happy” / “Sad” / “Angry”。使用以下方式把它转换为枚举值： Convert String to Byte 或 UE 为 EBotMood.

渲染字符串——调试 + 编写

该 Rendered String 字段在每个 FConvaiAction 上都是一个支持双向同步的多行文本框：

• 读取它 即可准确看到发送给 LLM 的内容。适用于：

  • 在连接之前检查你的描述是否合理。
  • 粘贴到其他工具中测试提示词变体。
  • 并排比较两个角色的动作契约。
• 写入它 ，结构化字段就会更新。插件会把该格式解析 Name <connector> "<param: type>"… — Description. param: desc. 回 Name / Description / Parameters。适用于：

  • 在角色之间粘贴模板。
  • 快速编辑长描述，而无需在嵌套结构字段中滚动。

如果你的编辑无法被干净地解析 （括号损坏、无法识别的类型词等），预览会在下一次刷新时静默回退为结构化字段的规范渲染。只要遵守格式规则，就不会有问题。

这种双向同步是保守的：只有当渲染字符串实际上与结构化字段生成的内容不同时，才会重新解析，因此偶发提交（焦点变化、误点击）不会降低类型。

从旧字段迁移

如果你有较旧的处理器图在读取 FConvaiResultAction.RelatedObjectOrCharacter 中的某个内容，自动设置） .ConvaiExtraParams.Number/Text，它们仍然可以编译——这些字段作为新 Parameters 映射的已弃用镜像而被填充。BP 节点提示会显示指向替代项的弃用信息：

旧版	新版
Result.RelatedObjectOrCharacter.Ref	Get Param As Ref(action, "<name>").Ref （或 Get First Param).
Result.ConvaiExtraParams.Number	Get Param As Number(action, "<name>").
Result.ConvaiExtraParams.Text	Get Param As String(action, "<name>").
Get Action Param(extraParams, name)	Get Param As String(action, name).

你可以按处理器逐个迁移，按自己的节奏来；没有任何东西强制你立即重写。

下一步去哪

你现在已经知道：

• 参数类型矩阵以及它生成的线协议格式。
• 如何使用连接词来构建复合动作。
• 如何通过 Choices 中的某个内容，自动设置） Enum.
• 如何通过类型化访问器在 Blueprint 中读取参数。
• 如何使用渲染预览进行调试或直接编写。

这就是完整的动作编写界面。关于驱动一切的运行时契约（四条服务器提示通道、动态上下文管线、场景元数据更新、对话伙伴、注视目标），请参见插件内参考： Convai/Docs/ActionsAndEnvironment.md 以及更深入的 V2 参考： Convai/Docs/ActionsV2.md.