查询消息列表节点

查询消息列表节点用于分页读取一个已有会话中的有效消息。当前节点按消息创建时间倒序返回结果，也就是最新消息在前；它只读取当前会话项目和当前用户作用域内的数据，并自动排除已经删除或清空的消息。

适用场景

• 在工作流中读取指定会话的最近消息。
• 为页面或列表组件提供会话消息数据。
• 获取消息 ID，供修改消息或删除消息节点使用。
• 分页加载更早的历史消息，或刷新游标之前出现的新消息。
• 验证创建、修改、删除和清空历史等消息操作的实际结果。

节点不会一次无上限地返回“所有历史消息”。未填写 limit 时当前默认返回 20 条，更多消息必须使用游标继续查询。

使用前提与作用域

• 目标会话必须已经存在，并属于当前会话项目和当前用户。
• conversationName 可以填写会话名称；当前执行器也会优先把该值尝试作为会话 ID 查找。
• 使用名称查找时不区分大小写；如果存在同名会话，选择最近更新的一条。
• 资源库工作流试运行应关联目标应用，使运行上下文提供会话项目。
• 有明确会话项目时，会按当前用户的项目访问权限执行。

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

添加与配置节点

1. 在工作流画布中单击“添加节点”。
2. 选择“消息节点”中的“查询消息列表”。
3. 配置目标会话和单页数量。
4. 首次查询时将 beforeId、afterId 留空。
5. 需要更旧数据时，把上次输出的 lastId 传给下一次查询的 afterId。
6. 将 messageList 交给循环、列表组件或后续消息处理逻辑。
7. 每次翻页都保存本页的 firstId、lastId 和 hasMore。

输入参数

参数	类型	必填	说明
conversationName	String	是	待查询的会话名称；当前执行器也支持传入会话 ID。节点定义不预置非空默认值，截图中的 Default 只是示例配置
limit	Integer	否	本次最多返回的消息数；空值默认 20，有效范围为 1～100
beforeId	String	否	只保留排序结果中位于该消息之前的消息；当前倒序下即比该游标更新的消息
afterId	String	否	只保留排序结果中位于该消息之后的消息；当前倒序下即比该游标更旧的消息

四个参数都可填写固定值或引用上游变量。conversationName 去除首尾空白后不能为空；其他参数为空时按未设置处理。

limit 的当前规则

• 未填写、空白或无法解析为非负整数时，使用默认值 20。
• 传入 0 时会被收敛为 1。
• 传入 1～100 时使用实际值。
• 大于 100 时会被收敛为 100。
• 正式流程应主动传入 1～100 的明确整数，不要依赖非法值的降级行为。

旧文档中的“默认返回 100 条”不符合当前执行器；当前默认值是 20。

排序与游标语义

默认排序

当前节点没有对外开放排序参数，执行器默认按 created_at 倒序返回：

最新消息 → 较新消息 → 较旧消息 → 最旧消息

因此：

• firstId 是本页第一条、也就是本页最新消息的 ID。
• lastId 是本页最后一条、也就是本页最旧消息的 ID。

连续加载更旧消息

首次查询将两个游标留空。假设第一页返回：

M100, M99, ... M81

下一页应传：

afterId = 上一页 lastId = M81

节点会从 M81 之后继续读取更旧消息，例如：

M80, M79, ... M61

这是当前实现中连续向历史方向翻页的推荐方式。

查询游标之前的更新消息

传入 beforeId = firstId 会筛选比该游标更新的消息。但当前实现会从筛选结果的最新位置开始取 limit 条；如果游标之前已经积累了超过一页的新消息，结果会直接返回最新的一页，而不是保证返回与当前页相邻的上一页。

因此 beforeId 更适合“刷新并查看游标之后出现的新消息”或“回到最新页”，不应当被当成严格的相邻上一页游标。

游标空值和未命中

• 空字符串、纯空白和字符串 0 都按未设置处理。
• 游标 ID 在当前有效消息集合中未命中时，当前实现会忽略该游标，不会返回专门错误。
• 无效 afterId 可能使查询重新返回最新一页，从而产生重复数据。
• 不建议同时设置 beforeId 和 afterId；当前执行顺序先应用 afterId，再在剩余结果上应用 beforeId，组合结果不适合作为通用双边区间查询。

分页调用方应保存服务端实际返回的游标，并按消息 ID 去重，避免游标失效或并发写入造成重复展示。

输出参数

参数	类型	说明
messageList	Array<Object>	当前页消息，按创建时间从新到旧排列
messageList[].messageId	String	消息唯一 ID
messageList[].role	String	消息角色，通常为 user 或 assistant
messageList[].contentType	String	当前消息内容类型字符串，例如 text
messageList[].content	String	标准化后的消息内容文本
firstId	String	当前页第一条消息 ID；空页通常为空字符串，缺少资源项目时为 0
lastId	String	当前页最后一条消息 ID；空页通常为空字符串，缺少资源项目时为 0
hasMore	Boolean	当前游标和数量限制之后是否还有更多结果

节点没有 isSuccess、总条数或错误原因输出。hasMore=false 只表示当前过滤结果在本页之后没有更多消息，不能单独证明会话存在或查询上下文正确。

消息对象的标准化

当前执行器把底层消息压缩为四个固定字段：

• messageId 统一转换为字符串。
• role 读取字符串角色；底层缺失角色时当前会回退为 user。
• contentType 读取字符串类型；底层缺失或不是字符串时回退为 text。
• content 始终转换为 String；底层为对象或数组时会序列化为 JSON 文本，而不是按结构化对象输出。

旧文档使用数字 1、2 表示内容类型，这不是当前节点输出契约。当前字段类型是 String，流程应判断实际字符串值，不要继续依赖旧数字编码。

中间消息的可见性

当前查询请求固定包含中间消息，可能返回以下类型的工具或过程记录：

• function_call
• tool_response
• tool_output
• follow_up
• verbose

但是当前输出对象不包含 messageType 或 chatId，下游无法仅凭节点标准输出准确区分这些中间消息与普通问答消息。role 缺失时还会回退为 user，因此不要仅依赖角色做严格消息分类。

如果页面只允许展示用户和助手的最终消息，当前节点契约还不足以提供可靠的类型筛选，应在上游接口或节点能力补充消息类型字段后再实现严格过滤。

空结果与失败边界

下列情况都可能得到 messageList=[]、hasMore=false：

• 会话真实存在，但当前没有有效消息。
• 消息已经删除或会话历史已经清空。
• 会话名称或 ID 未命中。
• 当前用户、项目作用域与会话不匹配。
• 资源库工作流没有关联可提供会话项目的应用。

其中，资源库缺少会话项目时，当前执行器返回 firstId="0"、lastId="0"；会话不存在或正常空页通常返回空字符串。即便如此，下游也不应把游标值当作稳定的错误码。

因为节点没有成功标志，正式流程应在查询前确保应用关联和会话 ID 来源可信；需要区分“空会话”和“查询失败”时，应在业务层增加会话存在性校验。

参数校验失败、权限校验失败或存储服务异常可能使节点直接执行失败，而不是返回空列表。

当前版本的执行逻辑

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

1. 解析运行上下文中的会话项目和当前用户。
2. 校验 conversationName 非空，并解析 limit、beforeId、afterId。
3. 资源库运行上下文没有会话项目时，返回空列表和 0 游标。
4. 按“会话 ID 优先、名称兜底”的方式定位当前用户的有效会话。
5. 读取该会话中尚未删除的全部有效消息，并包含工具和过程类中间消息。
6. 按创建时间倒序排列。
7. 依次应用 afterId、beforeId、隐藏的偏移量和 limit。
8. 生成 firstId、lastId、hasMore，并把每条消息标准化为四个固定字段。

推荐分页编排

首次加载

conversationName=conversationId, limit=20, beforeId="", afterId=""

保存返回的 messageList、firstId、lastId 和 hasMore。

加载更旧消息

afterId=上一页 lastId, beforeId=""

只有当 hasMore=true 且 lastId 非空、非 0 时继续请求。把新页追加到旧页尾部，并按 messageId 去重。

刷新更新消息

beforeId=当前缓存的 firstId, afterId=""

把结果与现有列表按 messageId 合并，再按业务需要排序。不要假定返回的一定是严格相邻上一页。

绑定列表组件

将 messageList 绑定到列表组件时：

• 使用 messageId 作为稳定键，不要使用数组下标。
• 当前返回顺序是最新在前；聊天界面通常需要反转为最旧在上后再渲染。
• 显示前根据 contentType 处理文本；结构化内容目前已经被转换为字符串。
• 保留空状态、加载态、失败态和重复请求保护。
• 加载下一页时按消息 ID 去重，避免无效游标或并发新增消息造成重复。
• 不要把 hasMore=false 直接展示成“会话不存在”。

试运行与验收

建议使用专门的测试会话，并写入超过一页的唯一测试消息：

1. 创建测试会话，并保存其 conversationId。
2. 连续创建至少 25 条带顺序编号的消息。
3. 不填写 limit 查询，确认当前返回 20 条且最新消息排在第一条。
4. 使用 limit=5 查询，确认返回不超过 5 条，firstId 和 lastId 对应首尾项。
5. 将第一页 lastId 传给 afterId，确认下一页是连续的更旧消息且没有重复游标消息。
6. 使用第一页 firstId 作为 beforeId，确认只返回比它更新的消息；必要时先新增消息再测试。
7. 使用不存在的游标，确认当前实现会忽略游标并可能重新返回最新页。
8. 删除一条消息并重新查询，确认已删除消息不再出现。
9. 清空会话历史并重新查询，确认旧消息不再出现。
10. 使用不存在的会话和缺少应用关联的资源库流程分别测试，确认空结果语义不能单靠 hasMore 区分。

常见问题与处理

现象	原因	处理
空着 limit 只返回 20 条	当前执行器默认值是 20，不是旧文档的 100	显式传入 1～100，并通过游标继续查询
下一页重复了最新消息	afterId 无效或没有使用上一页实际 lastId，游标被忽略	保存真实输出游标，使用 afterId=lastId，并按消息 ID 去重
使用 beforeId 后直接回到最新页	当前实现从游标之前的更新消息中取最前面的 limit 条	把它用于刷新更新消息，不要当作严格相邻上一页
messageList=[]	会话为空、已清空、未命中、作用域不匹配或资源项目缺失	先校验应用关联和会话存在性，再判断空状态
hasMore=false 但无法确定是否成功	节点没有成功标志，空结果和未命中结果形状相似	在业务层增加会话存在性校验和运行错误分支
返回了工具过程消息	当前请求固定包含中间消息	当前输出缺少消息类型；需要严格过滤时应补充契约，而不是只看角色
content 看起来像 JSON 字符串	结构化内容被标准化为 String	按 contentType 和业务协议安全解析，处理解析失败
聊天界面顺序反了	节点默认最新消息在前	渲染前反转当前页，并正确处理多页拼接
删除的消息仍在本地列表	服务端已删除，但页面没有重新查询或去重合并	删除成功后重新查询，并按消息 ID 更新本地状态

与旧文档的核对结论

旧文档内容	当前处理
查询指定会话中的所有历史消息	调整；节点分页返回当前有效消息，不包含已删除或清空记录，默认只取 20 条
默认倒序返回最近 100 条	更正；倒序保留，但当前默认数量为 20，有效范围仍为 1～100
beforeId=firstId 向前翻页	细化；当前会筛选更新消息，但数量较多时直接取最新页，不保证严格相邻
afterId=lastId 向后翻页	保留并明确；当前倒序下用于连续加载更旧消息
beforeId、afterId 为必填空字符串	调整；当前节点定义为可选，空白或 0 均视为未设置
输出消息 ID、角色、内容类型和内容	保留；补充结构化内容会被转为字符串，缺失角色和类型存在默认值
内容类型使用数字 1、2	不沿用；当前输出契约为 String，应使用实际字符串值
返回用户和智能体消息	扩充说明；当前还会包含工具和过程类中间消息，但输出不暴露消息类型
消息固定保存 180 天	不作为当前节点契约沿用；当前代码和节点定义没有提供该保留期保证，数据留存由部署与治理策略决定
资源库试运行需要关联智能体或应用	调整；当前节点需要会话项目，通常由关联应用提供；缺失时返回空列表和 0 游标
旧页面操作截图	不沿用；以当前系统的节点面板和字段截图为准

发布前检查

• 已优先使用唯一 conversationId，没有依赖可能重复的会话名称。
• 已显式设置合理的 limit，没有误用旧文档的默认 100。
• 首次查询两个游标均为空；加载更旧数据使用上一页实际 lastId。
• 没有把 beforeId 当作严格相邻上一页游标。
• 已处理无效游标被忽略和结果重复的情况。
• 已按 messageId 去重，并根据界面需要调整倒序结果。
• 已知当前列表可能包含中间消息，且标准输出无法严格识别消息类型。
• 已处理空会话、会话未命中和资源项目缺失结果形状相近的问题。
• 已确认删除或清空后的消息不会继续出现在普通查询中。
• 已通过多页测试验证 firstId、lastId 和 hasMore 的实际行为。