清空会话历史节点

清空会话历史节点用于重置指定会话的上下文：保留会话本身及其 ID、名称，但清除当前可查询的消息，并为后续消息切换到新的上下文段。

适用场景

• 用户希望在同一会话中开始一个不受旧内容影响的新话题。
• 历史消息已经过时，继续传给模型会干扰回答。
• 测试流程需要保留会话对象，但重新建立空上下文。
• 业务已经取得用户确认，需要移除当前会话中的消息记录。

这是有数据影响的操作。执行后，标准的查询会话历史和查询消息列表节点都无法再返回被清空的旧消息。

清空范围

当前实现会处理当前会话项目、当前用户和目标会话共同作用域内的全部有效消息：

• 会话对象保留，conversationId 和会话名称不变。
• 当前有效消息被清除；不仅是大模型可见的一问一答，也包括工具调用等中间消息。
• 会话记录写入新的上下文段标识，之后创建的消息进入新的段。
• 长期记忆库、知识库、数据库和其他会话不受影响。
• 主数据库中的消息使用删除标记，内存模式直接移除；产品节点和标准查询能力都没有恢复入口。

不要把该节点理解为“临时隐藏历史”。即使数据库底层可能保留带删除标记的记录，也不能依赖它恢复业务数据。

使用前提与作用域

• conversationName 必须指向当前运行用户和会话项目下仍然有效的会话。
• 当前执行器会先把输入尝试作为会话 ID 查询，未命中时再按名称查询。
• 使用名称查找时不区分大小写；存在同名记录时选择最近更新的一条。
• 资源库工作流试运行应关联目标应用，使运行上下文提供会话项目。
• 没有关联会话项目时，当前节点返回 isSuccess=false，而不是“必须关联应用”的结构化错误。
• 有明确会话项目时会进行访问权限校验，校验失败则节点执行失败。

添加与配置节点

1. 在工作流画布中单击“添加节点”。
2. 选择“会话历史节点”中的“清空会话历史”。
3. 为 conversationName 传入受控的会话名称或会话 ID。
4. 在节点前增加目标确认、权限判断或业务条件。
5. 根据 isSuccess 分别处理成功与失败分支。
6. 试运行时使用专门创建的测试会话，并关联目标应用。

输入参数

参数	类型	必填	说明
conversationName	String	是	待清空的会话名称；当前执行器也支持传入会话 ID。新建节点时默认值为 Default

参数支持固定值或引用上游变量。推荐从“查询会话列表”节点取得 conversationId 后传入，避免同名、改名或用户输入导致清错目标。

输出参数

参数	类型	说明
isSuccess	Boolean	true 表示目标会话存在并完成了上下文重置；false 表示目标未命中，或资源库运行上下文没有会话项目

当前节点只暴露 isSuccess，不会输出清除了多少条消息、新上下文段 ID 或失败原因。需要审计时，应在节点前后由业务流程记录目标会话、操作者、时间和执行结果。

重复清空

目标会话存在但已经没有消息时，再次清空仍会生成新的上下文段并返回 isSuccess=true。因此：

• isSuccess=true 不代表本次一定删除了消息。
• 该节点不能用于统计清理数量。
• 自动流程应避免无意义的重复清空和重复审计记录。

当前版本的执行逻辑

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

1. 解析运行上下文中的会话项目和当前用户。
2. 读取 conversationName，先尝试按会话 ID 查找，再按名称查找。
3. 找不到会话时返回 isSuccess=false。
4. 为目标会话生成并保存新的上下文段标识。
5. 清除该会话的全部有效消息：主数据库写入删除标记，内存模式移除消息集合。
6. 保留会话对象，返回 isSuccess=true。
7. 后续新消息继续写入同一个会话 ID，但归入新的上下文段。

推荐编排

用户确认后开始新话题

查询会话列表 → 取得 conversationId → 二次确认 → 清空会话历史 → 判断 isSuccess → 写入新话题首条消息

清空前应明确告诉用户旧消息将无法通过标准消息查询恢复。清空成功后再写入新话题，避免新消息在重置前进入旧上下文。

自动重置测试会话

识别测试环境与测试会话 → 清空会话历史 → 判断 isSuccess → 初始化测试数据

仅对明确标记的测试会话执行，不要根据模糊名称批量清空。正式用户会话应要求确认或经过审批条件。

试运行与验收

不要使用生产用户的真实会话进行清空测试。建议按以下步骤验证：

1. 创建专用测试会话，记录其 conversationId。
2. 写入至少两条测试消息，先用“查询消息列表”确认能够返回。
3. 把该 ID 传给清空会话历史节点并执行，确认 isSuccess=true。
4. 再次查询会话列表，确认会话仍存在且 ID 不变。
5. 分别执行“查询会话历史”和“查询消息列表”，确认旧消息均不再返回。
6. 在同一会话中创建新消息，确认新消息可以正常查询。
7. 对不存在的会话执行，确认 isSuccess=false。
8. 对已经为空的测试会话再次执行，确认仍返回 true，但不要据此推断清理数量。

常见问题与处理

现象	原因	处理
isSuccess=false	会话不存在、名称或 ID 错误、用户/项目作用域不匹配，或资源库运行上下文没有会话项目	核对应用关联、当前用户和会话 ID；先查询会话列表确认目标
清空后查询消息列表也为空	当前实现会清除全部有效消息，旧文档“仍可查询完整消息”已不适用	清空前完成必要归档；不要依赖标准查询恢复
清空后会话仍在	该节点只清消息并切换上下文段，不删除会话对象	需要删除会话时使用“删除会话节点”
空会话重复清空仍返回成功	目标会话存在时会生成新的上下文段，即使没有消息可清	在业务侧避免重复触发；不要用返回值统计条数
传入名称清空了错误目标	名称可能重复、被修改或来自不受控输入	优先使用唯一 conversationId，并增加确认与审计
权限校验失败	当前用户无权访问明确关联的会话项目	切换到正确应用，或由管理员授权
希望恢复被清空的消息	节点和标准产品查询没有恢复能力；内存模式已直接移除	清空前另行归档；如有合规恢复需求，走受控的数据运维流程

与其他操作的区别

操作	会话对象	当前有效消息	后续是否沿用原会话 ID
清空会话历史	保留	全部清除，并建立新上下文段	是
删除会话	删除	同步删除	否
删除消息	保留	只删除指定消息	是
删除长期记忆	不直接影响	不直接影响	是

与旧文档的核对结论

旧文档内容	当前处理
清空后模型不再看到旧上下文	保留，与当前执行结果一致
清空只影响模型可见上下文，不删除存储消息	更正；当前实现清除全部有效消息，主数据库加删除标记，内存模式直接移除
清空后仍可通过查询消息列表查看完整旧消息	删除；当前标准查询会排除已清空消息
会话本身继续存在，可以开始新话题	保留，并补充会生成新的上下文段、沿用原会话 ID
输入固定为 conversationName	保留，并补充当前执行器也支持会话 ID
输出固定为 isSuccess	保留；补充空会话重复清空仍可返回 true
豆包渠道不支持该节点	不沿用；当前执行链路没有按豆包渠道禁用该节点
资源库试运行需要关联智能体或应用	调整；当前节点需要明确会话项目，通常通过关联应用提供；缺失时返回 false
试运行只能影响测试数据	不作为节点契约沿用；数据环境取决于实际部署和运行配置
会话管理页面展示“清空上下文”提示	不作为当前契约沿用；现有执行器只保证数据操作和布尔输出

发布前检查

• 已确认目标是专用测试会话，或已获得真实用户的明确确认。
• 已优先使用唯一 conversationId，未依赖模糊名称。
• 已确认运行上下文中的应用、用户和会话作用域正确。
• 已在清空前完成必要的数据归档和审计记录。
• 已理解查询会话历史和查询消息列表都不会再返回旧消息。
• 已处理 isSuccess=false，没有在失败后写入依赖新上下文的消息。
• 未把 isSuccess=true 误认为实际清除了至少一条消息。
• 未把清空会话历史误当成删除会话或删除长期记忆。