创建消息节点

创建消息节点用于向一个已经存在的会话写入一条文本消息。消息会进入该会话的历史记录，后续的查询会话历史、查询消息列表或大模型上下文处理可以读取它。

适用场景

• 把用户输入以 user 角色写入指定会话。
• 把模型或业务系统生成的文本以 assistant 角色写入会话。
• 为测试会话构造可查询的上下文消息。
• 在清空会话历史后，为同一会话的新上下文段写入首条消息。

节点每次只创建一条消息，不会自动调用模型生成回复，也不会自动创建目标会话。

使用前提与作用域

• 目标会话必须已经存在，并且属于关联应用和执行用户。
• conversationName 可以填写会话名称；执行器也会优先把该值尝试作为会话 ID 查找。
• 使用名称查找时不区分大小写；如果存在同名会话，选择最近更新的一条。
• 资源库工作流试运行应关联目标应用，使运行上下文提供会话项目。
• 没有会话项目时返回 isSuccess=false 和占位消息对象，而不是自动创建会话。
• 有明确会话项目时会校验执行用户的访问权限。

推荐先使用“创建会话”或“查询会话列表”取得 conversationId，再把它传给 conversationName。这样可以避免名称重复、改名或用户输入造成歧义。

添加与配置节点

1. 在工作流画布中单击“添加节点”。
2. 选择“消息节点”中的“创建消息”。
3. 配置目标会话、消息角色和文本内容。
4. 将 isSuccess 接入条件分支。
5. 仅在成功分支中使用返回的 message。
6. 试运行时关联应用，并使用专门创建的测试会话。

输入参数

参数	类型	必填	说明
conversationName	String	是	目标会话名称；也支持传入会话 ID。节点定义不预置非空默认值，截图中的 Default 只是示例配置
role	String	是	消息角色，编辑器提供 user 和 assistant 两个选项，默认 user
content	String	是	消息文本；去除首尾空白后不能是空字符串

所有参数均可填写固定值或引用上游变量。

角色处理

执行器只对精确的小写字符串 assistant 做特殊识别，其他非空值都会被归一为 user；空值或空字符串会触发必填校验。因此：

• 使用编辑器下拉选项最安全。
• 引用变量时必须保证值是精确的 user 或 assistant。
• Assistant、USER 及其他非空自定义角色会变成 user，空字符串则执行失败。

角色不会触发任何自动回复：写入 user 消息后，如果需要模型回答，还必须在后续显式调用大模型，并另行写入回答。

内容与内容类型

节点固定以 text 内容类型创建消息：

• 不支持直接上传图片、音频、视频或文件对象形成多模态消息。
• 文本中可以包含 URL，但系统只会把 URL 当作普通字符串保存，不会自动下载或解析媒体。
• 虽然运行时能把数字、布尔值或对象转换为字符串，正式流程仍应传入明确的 String，避免产生不可控的序列化文本。
• 空值、空字符串或仅包含空白的内容会使节点执行失败。

输出参数

参数	类型	说明
isSuccess	Boolean	是否成功创建消息
message	Object	创建结果对象；失败时也可能存在占位结构，必须结合 isSuccess 判断
message.messageId	String	新消息 ID；成功时应为非空值
message.role	String	实际写入的角色
message.contentType	String	固定为 text
message.content	String	实际写入的文本内容

不要仅根据 message 对象是否存在判断成功。资源库没有关联会话项目时，执行器会返回 isSuccess=false，同时给出 messageId="0" 的占位对象；会话不存在时也可能返回空字段组成的消息对象。

执行逻辑

节点执行时按以下顺序处理：

1. 解析运行上下文中的关联应用和执行用户。
2. 校验 conversationName、role 和 content 是否可解析，内容是否非空。
3. 把精确的 assistant 保留为助手角色，其余角色值归一为 user。
4. 把内容转换为字符串，并固定设置 contentType=text。
5. 先把 conversationName 当作会话 ID 查找，未命中后再按名称查找。
6. 会话不存在时返回 isSuccess=false，不会隐式创建会话。
7. 为消息生成新的唯一 ID；如果会话刚清空过历史，则自动沿用新的上下文段标识。
8. 写入消息并返回标准化的 message 对象。

重复执行与顺序

创建消息节点没有业务幂等键。相同输入执行两次会生成两个不同的消息 ID，并留下两条消息。因此：

• 不要在不确定结果时盲目重试。
• 可能重复触发的流程应在业务侧保存执行标识或增加去重判断。
• 构造对话历史时应显式控制执行顺序，通常按 user → assistant → user → assistant 写入。
• 并行创建多条消息时，不应仅依赖节点连线推断最终时间顺序。

推荐编排

写入一轮完整问答

取得 conversationId → 创建 user 消息 → 判断成功 → 调用大模型 → 创建 assistant 消息 → 判断成功

两次创建都应检查 isSuccess。用户消息写入成功但助手消息失败时，应进入补偿、重试或人工检查分支，避免留下不完整问答。

清空后开始新话题

确认目标 → 清空会话历史 → 判断成功 → 创建 user 消息 → 调用大模型

清空成功后，创建消息节点会把新消息写入同一个会话 ID 的新上下文段。不要在清空成功前并行写入新消息。

试运行建议

建议使用专门的测试会话：

1. 创建测试会话并保存其 conversationId。
2. 使用该 ID、role=user 和一段唯一测试文本执行节点。
3. 确认 isSuccess=true，并检查 messageId 非空、contentType=text、内容一致。
4. 使用“查询消息列表”确认新消息位于同一会话。
5. 再以 role=assistant 写入回答，确认角色正确。
6. 对不存在的会话执行，确认返回 isSuccess=false 且没有创建新会话。
7. 使用空白内容执行，确认节点明确失败。
8. 在测试环境重复执行同一输入，确认会产生不同消息 ID，从而验证流程必须自行防重。

常见问题与处理

现象	原因	处理
isSuccess=false	目标会话不存在、作用域不匹配，或资源库运行上下文没有会话项目	核对应用关联、执行用户和会话 ID；先查询会话列表
提示 content is required	内容为空、仅含空白，或上游变量没有值	在上游增加非空校验，确保传入有效文本
角色意外变成 user	传入值不是精确的小写 assistant	使用编辑器选项，或在上游把角色归一为 user/assistant
返回了 message 但 ID 为 0 或为空	创建失败时执行器仍可能返回占位消息结构	始终先判断 isSuccess，失败分支不要使用消息字段
同一内容出现多次	工作流重复执行或重试，节点没有幂等保护	保存业务执行标识，创建前做去重或由上游避免重复触发
传入图片 URL 后没有形成图片消息	URL 仅作为普通文本保存，内容类型固定为 text	使用支持媒体协议的专用能力，不要把文本 URL 当作多模态消息
创建成功但模型没有自动回复	节点只写消息，不调用模型	在后续增加大模型节点，并把回答以 assistant 角色写回
权限校验失败	执行用户无权访问明确关联的会话项目	切换到正确应用，或由管理员授权

发布前检查

• 已确认目标会话真实存在，且应用、用户作用域正确。
• 已优先传入唯一 conversationId，未依赖模糊名称。
• role 只可能是精确的小写 user 或 assistant。
• content 是非空文本，且未把文件对象或 URL 当作多模态消息。
• 下游先判断 isSuccess，失败时不使用占位 message。
• 已为重复执行设计去重、补偿或人工检查策略。
• 需要完整问答时，已按顺序分别写入用户和助手消息。
• 已通过查询消息列表验证测试消息写入正确会话。