文档：同步 review 修正后的会话滚动契约

- ADR 第 1 条补「一次加载与它所属的世代绑定」，第 2 条补块集合缓存与失效信号 - 决策记录追加两处内部缺陷的症状、修正与验证口径 Co-authored-by: Junie <junie@jetbrains.com>
2026-10-02 19:59:34 +08:00
parent 1caf8ae8b0
commit a589dad003
2 changed files with 4 additions and 0 deletions
@@ -22,6 +22,7 @@ DirectProject 聊天区（`apps/ai-game-creator-shell/src/view/project-developme
 - 两个触发都不越过既有的首屏订阅锚点 `lastCompletedItemId`；一次加载仍最多连拉 5 页（口径见 [`【ADR】DirectProject对话历史单一事实源-2026-09-16`](./【ADR】DirectProject对话历史单一事实源-2026-09-16.md)）。
 - 加载中在列表最上方（比最旧一条回合更靠上）挂载一行 `role="status"`、`aria-live="polite"` 的「正在加载更早的对话」，带旋转圈；延迟 150ms 才显示，加载结束即卸载。它按需挂载，靠位置补偿（见第 2 条）保证下面的消息不跳。
 - 失败：挂起自动加载，列表顶部保留一行 `role="alert"` 的「加载更早对话失败 · 重试」，重试是可聚焦按钮；**不自动重试**，只有点重试（或切换项目）才重新开始；重试成功后错误行消失。
+- 一次加载与它所属的**世代**绑定：切换项目或新起一次读取都推进世代号（`historyLoadTokenRef`），旧世代落地时整段失效——不合并条目、不写游标、不关加载态。只比项目路径不够：A→B→A 之后在飞的旧读取又落回同一个路径，原守卫放行，会把新一代的加载行与 `historyLoadingRef` 这道并发闸门一起改掉。

 ### 2. 前插锚定：回合 key + 偏移，关掉浏览器原生锚定

@@ -29,6 +30,7 @@ DirectProject 聊天区（`apps/ai-game-creator-shell/src/view/project-developme
 - 合并更早历史前记录锚点，合并后按同一 key/序号把偏移还原，较早内容出现在上方而用户正在读的位置不动。
 - 列表上加 `overflow-anchor: none`，关掉浏览器原生 scroll anchoring，保证只有一套补偿在跑（不做「两套补偿交替生效」）。
 - 一次加载期间（`historyLoading` 为真）所有补偿——ResizeObserver 回调、加载行挂载、历史合并——都还原同一个冻结锚点；加载结束再刷新锚点。
+- 块集合（列表里所有带 `data-turn-key` 的节点）在列表子元素没变时复用同一份缓存，缓存由子元素增删（与 `ResizeObserver` 重订阅共用同一个 `MutationObserver`）失效：否则一次滚动帧里读锚点、还原锚点会各查一遍整份列表，长会话下就是 O(块数) 的滚动抖动。

 ### 3. 回到底部胶囊

@@ -10,6 +10,8 @@
 - 验证（2026-10-02 追加）：同目录用例补齐到 48 条（新增 `toggleRevealDelta` 六例、hook 的四例程序化滚动用例，其中两例在修正前确实红）全部通过；Chromium 真机脚本复验三处——点回到底部收敛到 `scrollHeight - clientHeight`、底部展开贴到新底、视口外展开补 269px 后正文底边正好贴视口下缘。
 - 追加（2026-10-02，换会话复位滚动所有权）：`useConversationScroll` 的跟随最新 / `atBottom` / `hasNewReply` / 前插锚点 / 折叠头 / 程序化滚动标记只在挂载时初始化一次，而 `DirectProjectChatView` 切项目时不重挂载——在项目 A 往上滚过再切 B，B 首屏不贴底且胶囊直接显示「有新回复 · 回到底部」。现在把会话身份（`conversationKey`，DirectProject 传项目路径）作为显式信号传进 hook，身份变化即复位这批状态、同步终态指纹并重新贴底；不改成 `key` 重建列表，避免消息列表重建与加载行 150ms 延迟计时重来，同一个项目重开也不算换会话。
 - 验证（2026-10-02 追加，换会话复位）：`useConversationScroll` 新增两例换会话用例（新会话首屏贴底且不出现胶囊、切会话后在 B 里往上滚只显示「回到底部」而不是「有新回复」），修正前确实红、修正后绿；chat 范围用例全绿。
+- 追加（2026-10-02，review 两处内部缺陷的修正）：①更早历史读取的守卫从「项目路径相等」改成「世代号相等」（`historyLoadTokenRef`，切项目与每次读取各推进一格）——A→B→A 之后在飞的旧读取又落回同一路径，原守卫会放行，把新一代的加载态、并发闸门与游标一起改掉；现在非最新一次读取落地时整段丢弃。②锚点的块集合按列表缓存（`WeakMap`），由已有的子元素 `MutationObserver` 在同一处 `invalidateTurnBlocks` 失效——原来一个滚动帧里读锚点、还原锚点各查一遍整份列表，长会话下是 O(块数) 的 DOM 查询。
+- 验证（2026-10-02 追加，review 修正）：新增一例控制器用例（驱动 A→B→A 且同路径新读取在飞，修正前在「旧读取落地」处红）与两例锚点缓存用例（连续收集只查一次 DOM、子元素变化并失效后重新收集）；chat 范围用例全绿，`npm run ai-game-creator-shell:typecheck`、`eslint --max-warnings 0`、`npm run check:encoding`、`git diff --check` 通过。

 ## 2026-10-01 Web、后台与 AGC 一键联调