创建消息节点

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

适用场景

• 把用户输入以 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 角色写回
权限校验失败	当前用户无权访问明确关联的会话项目	切换到正确应用，或由管理员授权

与旧文档的核对结论

旧文档内容	当前处理
每次只能创建一条消息	保留，与当前执行器一致
角色限制为 user 或 assistant	保留；补充运行时只有精确 assistant 会保留，其余值归一为 user
内容为必填文本，不支持直接创建多模态消息	保留；补充 URL 仍只是普通文本，contentType 固定为 text
输出 isSuccess 和完整消息对象	保留；补充失败时也可能返回占位消息，必须先判断布尔值
插入消息会进入会话历史	保留；补充清空历史后自动使用新的上下文段
可以在静态会话或动态会话中创建	不作为当前契约沿用；执行器按项目、用户和会话 ID/名称查找，没有输出或校验该分类
资源库试运行需要关联智能体或应用	调整；当前节点需要明确会话项目，通常通过关联应用提供；缺失时返回 false
试运行结果可以在应用会话管理页面查看	不作为节点契约承诺；可通过查询消息列表验证实际写入结果
草稿与线上数据隔离	不作为节点契约沿用；数据环境取决于实际部署和运行配置

发布前检查

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