查询会话历史节点

查询会话历史节点用于读取指定会话中已经存储的上下文消息，输出每条消息的角色和内容。它适合在继续处理旧会话、生成摘要或把历史交给下游节点前获取最近的消息。

适用场景

• 在继续某个会话前取得最近的上下文消息。
• 将最近消息交给代码节点进行筛选、重排或摘要。
• 检查指定会话是否已有历史内容。
• 在生成回复前补充有限范围的会话上下文。

该节点只读取消息，不会修改会话名称、创建新消息或清空历史。

使用前提与作用域

节点按运行上下文中的会话项目和当前用户查询数据：

• 只会命中当前会话项目与当前用户作用域内、尚未删除的会话。
• conversationName 可以填写会话名称；当前执行器也会优先把该值尝试作为会话 ID 查询。
• 使用名称查询时不区分大小写；如果存在同名记录，存储层选择最近更新的一条。
• 会话不存在、会话没有消息，以及资源库试运行没有提供会话项目时，最终都可能表现为 messageList=[]。

资源库工作流试运行时应关联目标应用，使运行上下文提供明确的会话项目。没有关联时，当前查询节点不会像创建、修改或删除会话节点那样直接提示“必须关联应用”，而是返回空列表，因此不能仅根据空列表判断会话确实没有历史。

添加与配置节点

1. 在工作流画布中单击“添加节点”。
2. 选择“会话历史节点”中的“查询会话历史”。
3. 配置目标会话名称或会话 ID。
4. 明确填写需要读取的消息数量。
5. 将 messageList 连接到代码、循环、条件、大模型或结束节点。
6. 在试运行配置中关联实际承载该会话的应用。

输入参数

参数	类型	必填	当前执行语义
conversationName	String	是	目标会话名称；当前执行器也支持传入会话 ID。编辑器新建节点时默认填入 Default
rounds	Integer	是	当前实现实际把该值作为“最多返回多少条消息”，不是逻辑对话轮次或指定的第几轮；运行时范围为 1～100

两个参数均支持填写固定值或引用上游变量。推荐从“查询会话列表”节点取得 conversationId 后传入 conversationName，避免同名会话或改名造成歧义。

rounds 的真实含义

旧文档将一条用户消息和一条模型回复定义为一轮，并把 rounds=1 解释为查询最新一轮。但当前运行时没有按问答对分组，而是直接读取最近的 N 条存储消息：

• rounds=1：最多返回最近 1 条消息。
• rounds=2：最多返回最近 2 条消息，不保证一定构成完整的一问一答。
• 工具调用、工具响应等中间消息也可能计入数量。
• 返回结果默认按时间倒序，即最新消息在前。

运行时会把有效数字收敛到 1～100。未填写或无法解析时，执行器会回退为 20，但节点定义和编辑器仍将该字段标记为必填；正式流程应填写明确的正整数，不要依赖隐式回退。

输出参数

参数	类型	说明
messageList	Array<Object>	最近的消息列表；会话不存在或没有可返回消息时为空数组
messageList[].role	String	消息角色，例如 user、assistant；中间消息可能出现其他角色
messageList[].content	String	消息内容

节点声明的稳定输出只有 role 和 content。下游流程不要依赖运行时记录中可能附带但未在节点输出结构中声明的消息 ID、类型、时间或元数据。

当前版本的执行逻辑

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

1. 解析运行上下文中的会话项目和当前用户。
2. 读取 conversationName，先尝试按会话 ID 查找；未命中时再按名称查找。
3. 解析 rounds，把它作为消息数量限制，并收敛到 1～100。
4. 查询目标会话中未删除的消息；当前执行器允许返回中间消息。
5. 按创建时间倒序排列，从最新消息开始截取指定数量。
6. 输出 messageList，稳定字段为 role 和 content。

当前编辑器不提供顺序、偏移量、消息游标或是否包含中间消息的配置项。因此，该节点不适合分页浏览完整消息历史；需要分页时应使用“查询消息列表”节点。

推荐编排

把历史交给大模型

查询会话列表 → 取得 conversationId → 查询会话历史 → 代码节点筛选并按时间正序重排 → 大模型节点

当前历史结果是最新消息在前，而常见大模型上下文通常按旧到新组织。直接传给模型前，应根据业务要求反转顺序，并过滤无关、敏感或不受支持的角色。

读取最近若干次问答

如果业务大致需要最近 5 次问答，可以把 rounds 设置为至少 10，再在代码节点中按角色配对和校验。但因为工具调用等中间消息可能占用数量，这只是一种估算，不保证得到完整的 5 轮。要求严格轮次时，应按消息记录自行分组，而不是依赖 rounds 名称。

无历史时创建初始上下文

查询会话历史 → 判断 messageList 长度 → 有历史分支 / 初始化分支

空列表可能代表没有历史、会话未命中或运行上下文没有会话项目。初始化前应先确认应用关联和会话 ID，避免因为配置错误重复创建内容。

试运行与验收

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

1. 在同一会话中依次写入一条用户消息和一条模型消息。
2. 设置 rounds=1 执行，确认只返回最近 1 条消息，而不是完整问答对。
3. 设置 rounds=2 执行，确认最多返回 2 条，且最新消息位于列表前部。
4. 传入该会话的 ID 再执行，确认仍能命中同一会话。
5. 切换到不存在的名称，确认输出为空数组。
6. 去掉资源库试运行中的应用关联，确认空数组不能被误判为“会话无历史”。

常见问题与处理

现象	原因	处理
rounds=1 只返回一条消息	当前运行时把 rounds 当作消息条数，不是问答轮数	根据所需消息量填写数量，并在下游按角色分组
设置为 30 以上仍能执行	当前运行时上限为 100，前端“最多 30 轮”是沿用旧文档的提示	以当前执行语义为准，但控制数量以避免上下文膨胀
消息顺序与对话展示相反	默认按创建时间倒序返回，最新消息在前	传给模型或按时间阅读前，在代码节点中重排为旧到新
数量不足以组成完整问答	工具调用等中间消息可能计入数量，或目标会话本身缺少成对消息	增大数量后按角色和业务标记过滤、配对
返回空数组	会话不存在、没有历史、作用域不匹配，或资源库试运行没有会话项目	核对应用关联、当前用户和会话 ID；不要仅凭空数组下结论
无法分页或指定消息游标	当前节点只暴露 conversationName 和 rounds	改用“查询消息列表”节点
无法区分空会话与会话不存在	最终输出只有 messageList，两种情况都会变成空数组	查询会话列表确认目标是否存在

与旧文档的核对结论

旧文档内容	当前处理
会话历史用于提供模型可见的上下文	保留，但补充当前执行器还会包含中间消息
用户问题与模型回答固定组成一轮	不作为当前节点的执行契约；存储中可能存在工具调用等中间消息
rounds 表示查询第几轮，每次只返回一轮	更正；当前实现把它作为最近消息的数量限制
最多查询最近 30 轮	更正；当前运行时将消息数量收敛到 1～100，前端 30 轮提示已滞后
输出 messageList，包含 role、content	保留，作为下游可依赖的稳定输出结构
豆包渠道不支持该节点	不沿用；当前执行链路没有按豆包渠道禁用查询会话历史
资源库试运行需要关联应用或智能体	调整；资源库试运行应提供明确的会话项目，通常关联应用；缺失时当前节点返回空列表
试运行只操作草稿态临时会话	不作为节点契约沿用；环境隔离取决于实际部署和运行配置

发布前检查

• 已确认运行上下文对应正确的应用和用户。
• 已优先使用唯一的会话 ID，或确认名称不会产生歧义。
• 已明确填写 1～100 范围内的消息数量。
• 未把 rounds 当成严格的一问一答轮数。
• 已处理空列表的多种可能原因。
• 传给模型前已按需要重排顺序、过滤敏感内容和不支持的角色。
• 需要分页时已改用“查询消息列表”节点。