[Bug]: 长会话中手动向上滚动查看历史时，偶发自动跳回底部

[oceaman]

Summary

在多轮对话的长会话中，使用鼠标向上滚动查看历史消息时，会话视图会突然自动刷新并跳回最底部（最新消息位置），导致之前滚动定位的历史内容丢失，需要重新手动翻找。

Area

Web UI / Flow Chat / VirtualMessageList

Environment

• BitFun 版本：0.2.11
• 操作系统：Windows 11 x64
• 模型：DeepSeek V4-Pro

Reproduction

1. 在一个已有较多轮次对话的会话中（10 轮以上效果更明显）
2. 使用鼠标滚轮向上滚动，查看较早轮次的内容
3. 持续向上翻阅一段时间（期间可能有新的 tool event 产生、token 统计更新、或 Agent 仍在后台执行任务）
4. 实际结果： 会话视图突然刷新，滚动位置被重置到最底部（最新消息处），之前翻阅到的位置丢失
5. 期望结果： 滚动位置保持稳定，不受后台数据更新影响；仅当用户主动滚动到底部或点击"回到底部"按钮时才回到最新消息

Observed Behavior Details

• 问题并非每次必现，但在长会话中触发频率较高
• 跳回底部时没有明显的加载动画或提示，表现为"闪回"
• 左右箭头按钮的逐轮跳转可以正常工作（说明底层 turn 定位能力存在）
• 跳回后需要重新手动向上翻找，体验极差

Likely Root Cause

推测与 VirtualMessageList 的 scroll position 管理有关，可能的触发路径：

1. Re-render 导致 virtual list state 丢失

// ModernFlowChatContainer.tsx 中，以下状态变化可能触发 VirtualMessageList 重新渲染：
// - dialogTurns 数组更新（新 turn 产生）
// - turnSummaries 更新（轮次摘要重新计算）
// - tool event 到达（工具卡片状态变化）
// - token usage 更新（用量统计刷新）

VirtualMessageList 使用虚拟滚动（react-virtuoso 或自研），当 items 数组引用变化时可能触发 scrollToIndex(0) 或重置 scrollTop。在用户手动滚动到历史位置时，新事件的到达会导致 items 重新计算，可能意外触发滚动重置。

2. Auto-scroll-to-bottom 缺少"用户正在查看历史"的判断

// 推测存在类似逻辑：
// 新消息到达 → 自动滚动到底部（这是正确的默认行为）
// 但缺少检查：用户当前是否正在手动浏览历史？
// 如果用户 scrollTop 距离底部超过一定阈值，不应强制滚动

3. 与 #1281 的共同根因

VirtualMessageList.pinTurnToTop() 在 #1281 中暴露了"列表不完全就绪时返回 false"的问题。同一个组件可能在以下场景中同样不稳定：

• items 重建时 scroll position 保持
• 异步更新期间的 scroll 状态一致性
• scrollToIndex / scrollTo 在 reconcile 期间的可靠性

Relevant Code

• src/web-ui/src/flow_chat/components/modern/VirtualMessageList.tsx — 虚拟滚动核心，pinTurnToTop、scroll position 管理
• src/web-ui/src/flow_chat/components/modern/ModernFlowChatContainer.tsx — handleJumpToTurn、状态管理和重渲染触发
• src/web-ui/src/flow_chat/components/modern/FlowChatHeader.tsx — turn 导航入口
• src/web-ui/src/flow_chat/components/modern/useFlowChatNavigation.ts — 导航事件流

Suggested Fix Direction

1. 判断用户是否在浏览历史：在 VirtualMessageList 或 ModernFlowChatContainer 中追踪 isUserViewingHistory 状态——当 scrollTop 距离底部超过一定阈值（如 200px）时设为 true，仅当用户主动回到底部或点击"回到底部"按钮时才清除
2. 新消息到达时：如果 isUserViewingHistory === true，显示一个浮动的"新消息 ↓"按钮，而不是强制滚动
3. items 更新时保持 scroll position：在 VirtualMessageList 的 items 重建逻辑中，保存并恢复 scrollTop 或目标 turn 的锚点位置
4. 增加回归测试：在 FlowChatHeader.test.tsx 或 container 测试中补充 scroll position 保持的场景

Relation

可能与 #1281（轮次列表导航）共享 VirtualMessageList 的 scroll 状态管理根因。PR #1294 修复了 turn list 的面板关闭和 header 状态问题，但底层 pinTurnToTop 的滚动执行仍不稳定。

[limityan]

已在 PR #1393 中同步缓解相关滚动路径：static initial-history 下，用户离底阅读或跳到旧 turn 后，bottom guard、背景更新和回到底部不会互相抢滚动；static anchor 会保留 tail space，并在 latest DOM 恢复后再滚到底。

验证：相关单测、release-fast E2E、long-session scroll matrix 通过（2 个场景，failed=0，blankEvents=0）。本 PR 保持为 Related/Mitigates，#1381 的更广泛 live streaming / tool-collapse 组合仍建议继续在本 issue 跟踪。

[oceaman]

更新：2026-07-03 每日构建（0.2.11-nightly.20260703）测试反馈

PR #1393（fix(flow-chat): stabilize history turn navigation，Fixes #1281 / Related to #1381）已包含在此构建中。测试结果如下：

Bug 1（滚动闪回底部）❌ 未修复

现象与之前完全一致：长会话（20+ 轮）中手动向上滚动查看历史时，仍会突然自动跳回底部。PR #1393 描述的 bottom-guard / manual-scroll / return-to-latest 路径在此场景下未生效。

Bug 2（轮次列表跳转）🟡 部分修复，长会话引入新问题

短会话（5-10 轮）： ✅ 修复生效，点击轮次列表项后可以正常跳转。

长会话（20+ 轮）： ❌ 出现两种异常：

1. 点击后轮次列表不关闭，聊天内容也不跳转，界面卡住
2. 有时直接无响应

推测

PR #1393 的 pending + retry 机制在短会话中工作正常（virtual items 快速 reconcile，retry 一次成功），但在长会话中 virtual items 数量大、reconcile 耗时长，pending turn 可能永远达不到"可用"状态，导致 retry 死循环或永久阻塞。

E2E 测试和交互矩阵脚本可能只覆盖了 5-10 轮会话场景，未覆盖 20+ 轮的长会话边界。

建议

1. 在 run-long-session-interaction-matrix.mjs 中增加 30+ 轮的长会话配置
2. 为 pending retry 增加超时或最大重试次数，防止死循环卡死
3. 考虑在长会话中对 pinTurnToTop 使用非 pending 模式兜底（如 fallback 到 scrollToIndex）

[oceaman]

补充一个体验问题：短会话中轮次跳转虽然功能正常，但交互有明显的卡顿感——

内容先完成跳转（scroll 到位），然后轮次列表要等一小段时间后才关闭。整个过程像是"内容跳了 → 愣一下 → 面板才关"。

推测原因是 PR #1393 的 pending + retry 确认链路有异步延迟：pinTurnToTop 成功后需要等 virtualItems 变化的回调触发，再更新 header 状态，最后才触发 setIsTurnListOpen(false)。在视觉上，面板关闭动作和滚动动作之间有明显的时间差。

建议：如果 pinTurnToTop 已经返回 true，可以不必等 virtualItems 回调就直接关闭面板——滚动已经触发了，视觉反馈应该立刻跟上。

[limityan]

更新：#1413 已合入，针对 2026-07-03 反馈的长会话滚动回底、20+ 轮次列表点击卡住/无响应，以及短会话点击后面板延迟关闭的问题。

主要原因是 Header、Container、VirtualMessageList 对轮次跳转和 auto-follow 的职责边界不够清晰：列表已接管 pin 后 Container 仍可能继续重试；用户上滑时尚未激活的 auto-follow arm 也可能在后续 streaming/tool/background 更新中重新夺回滚动位置。

解决方案：将 turn pin 明确区分为 settled / pending / rejected，只有当场 settled 才立即关闭轮次列表；pending 由 VirtualMessageList 内部继续处理，Container 不再重复抢占；用户上滑会同时取消 active follow 和 armed auto-follow。

也已补充 20+ 轮次场景的 E2E 覆盖：long-session fixture 默认 80 轮，matrix 新增 turn-navigation 场景并加入 core / scroll profile，目标轮次为 index 20；release E2E 同时验证目标跳转和轮次列表及时关闭。