Merge branch 'master' into fix/issue-550

docs/project-memory/shared-memory/decision-log.md

@@ -1,4 +1,26 @@
 # 决策记录
+
+## 2026-10-02 DirectProject 对话：更早历史自动加载、前插锚定与回到底部胶囊
+
+- 背景：右侧对话更早历史只靠常驻按钮「显示更早的对话」拉，且没有任何加载反馈（`historyLoadingRef` 是 ref，渲染不出来）；用户滚上去之后没有「回到最新」的入口；展开「执行过程」/工具组/思考块时浏览器保持 `scrollTop`，新展开的正文长在视口下方，在底部展开更是直接顶出可视区。
+- 决策：删按钮改自动加载——触顶 24px 与「首帧后内容填不满视口」共用一道门（有更早历史 ∧ 不在加载中 ∧ 无失败记录），失败挂起、只留内联「加载更早对话失败 · 重试」且不自动重试；加载行挂载在列表最上方、延迟 150ms 才显示。前插按「回合 key（`data-turn-key`）+ 块内序号 + 相对列表顶边偏移」冻结锚点，列表显式 `overflow-anchor: none`；加载期间所有补偿还原同一个冻结锚点，加载结束后的下一次补偿再刷新。底部居中 `sticky` 胶囊「回到底部」（不跟随时来了新终态内容改「有新回复 · 回到底部」）：距底 48px 阈值、点击平滑滚动并恢复跟随。`ResizeObserver` 观察列表直接子元素（`MutationObserver` 负责子元素变化时重订阅）：跟随时任何高度变化贴底，否则冻结刚展开的折叠头，头部锚不住再对齐展开正文顶边；新一回合开始（`turnInFlight` 假转真）强制恢复跟随。滚动所有权（列表 ref、跟随最新、补偿、胶囊显隐）从 `DirectProjectChatView` 搬进 `DirectProjectConversation` 及其同目录 hook，控制器新增可渲染的 `historyLoading` / `historyError` 与 `retryEarlierHistory`。
+- 边界：只做 DirectProject；`PlanningChatView` 与 `App.tsx` 里的 `message-history-more` 遗留路径不动，因此该样式保留（后续项已写进 ADR）。新增元素全部用内联 Tailwind，`styles.css` 未改；阈值、文案与判据集中在同目录 `conversationScrollPolicy.ts`，契约见 [`【ADR】DirectProject对话滚动与历史自动加载-2026-10-02`](../../adr/【ADR】DirectProject对话滚动与历史自动加载-2026-10-02.md)，旧「单一事实源」ADR 的分页条目已改为引用它。
+- 验证：新增 37 条与实现同目录的用例（阈值与加载门、锚点读取/还原、折叠头冻结与正文对齐、hook 的触顶/填充/胶囊/未读/延迟加载行、组件层的按钮移除与内联重试行）由根 `vitest.config.ts` 的 include 收进门禁；`npm run ai-game-creator-shell:typecheck`、`eslint`（含新文件）、`npm run check:encoding`、`npm run check:doc-index`、`git diff --check` 通过；滚动观感（顶部加载圈、胶囊显隐、底部展开回贴、历史前插不跳）留真机手动验收。
+- 追加（2026-10-02，两个真机缺陷的根因与修正）：①「点回到底部只下去一屏、到不了底」——平滑动画期间滚动事件把「跟随最新」翻成假，布局补偿与锚点还原接着写 `scrollTop`，而真实浏览器里任何一次写都会取消正在跑的平滑动画；现在滚动位置由这次程序化滚动独占（滚动事件只在贴底时才结算并交还，补偿整段跳过），滚轮 / 触摸 / 键盘接手立刻交还，避免标记永远挂着。②「展开折叠块没有自动滚动到位」——旧规则只在展开正文比视口还高时才动，正文矮的折叠块（工具组、思考块）展开后正文仍在视口外；现在冻结折叠头之后统一补「刚好露出新展开正文」的最小位移（底边超出就补超出量，比视口还高则对齐正文顶边），两段位移合成一次写。落在 `conversationToggleReveal.ts`（新增纯函数 `toggleRevealDelta`）与 `useConversationScroll.ts`（新增 `programmaticScrollRef`）。
+- 验证（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-02，锚点改用稳定块身份）：review 第 3 条（`findTurnBlock` 按块序号定位）成立，采纳「换一套块身份」。锚点从 `{回合 key, 块序号, 偏移}` 改为 `{回合 key, 块身份, 偏移}`，块身份即 `DirectChatBlock.key`（`${回合 key}:${条目 itemId}` / 本地说明 `messageId`），只要求同一回合内唯一；展示层给每个可锚定块加 `data-block-key`（`DirectProjectTurn` 的正文块与终态文案、折进 `<details>` 的过程包装块、`ToolCallGroup`、`AgentReasoning` 各自透传），`conversationScrollAnchor.ts` 的收集选择器因此收敛为 `[data-turn-key][data-block-key]`。原因：`renderTurnProcess` 对运行中的回合平铺过程块、对已结束的回合折进一个 `<details>`，收口时整个回合的块序号后移一格，序号锚点会解析到隔壁块并按错误基准写 `scrollTop`。同时补上 review 指出、原方案漏掉的一半：锚点块没有布局盒（被折进收起的 `<details>`）时读锚点跳过它、`restoreTurnAnchor` 判为失败，调用方放弃这次补偿并重新起锚——不回跳，也不按别的块硬对齐。
+- 验证（2026-10-02 追加，稳定块身份）：锚点纯函数用例改为按块身份构造（`buildList` 传 `[回合 key, 块身份]`），新增「回合收口后块序号整体后移，块身份仍指向同一块且还原成功」「收起的 `<details>` 里的块没有布局盒：读锚点跳过、还原返回 false 且不写 `scrollTop`」；组件层新增用例断言每个带 `data-turn-key` 的块都有 `data-block-key`、同回合内块身份唯一、回合 running→finished 后同一块身份仍在。修正前锚点用例在「收口后按身份定位」处红。
+- 追加（2026-10-02，review：动画期间内容变高会把程序化滚动标记卡住）：`scrollToBottom` 把点击那一刻的 `scrollHeight` 当动画目标，而流式正文 / 图片撑开会让它在动画期间继续变高；`programmaticScrollRef` 只在「贴底」那次滚动事件里交还，于是动画停在旧目标后标记永远为真——布局补偿整段被跳过（列表不再跟随新内容），胶囊又已按「已贴底」隐掉，用户停在底部之上却没有任何指示和自动跟随。修正：程序化滚动期间布局补偿不写 `scrollTop`，但内容变高时把动画目标重新对准新的底部（`scrollListToBottom(list, 'smooth')`），动画继续跑到真正的底，标记照常在贴底时交还。
+- 验证（2026-10-02 追加，动画目标重对准）：`useConversationScroll.test.tsx` 新增一例——点击回到底部后内容变高（`scrollHeight` 1200→1500）触发一次布局变化，断言动画目标从 `[1200]` 变为 `[1200, 1500]`、落到新底部后仍能交出控制权；修正前在目标数组处红。
+- 追加（2026-10-02，review：错误行的重试按钮在断言式 live region 内）：`DirectProjectHistoryErrorRow` 原来把重试按钮渲染在 `<p role="alert">` 里面，而 `role="alert"` 隐含 `aria-live="assertive"` + `aria-atomic="true"`，交互控件会被卷进整段断言性播报、读屏也不一定把它当可聚焦按钮。修正：容器改为普通 `<div>`，`role="alert"` 只包住「加载更早对话失败」文案本身，重试按钮是 live region 之外的兄弟。
+- 验证（2026-10-02 追加，错误行结构）：`DirectProjectConversation.test.tsx` 新增一例断言 `role="alert"` 节点不包含重试按钮、且文案仍在 alert 内并仍可点击；修正前红。
+- 追加（2026-10-02，review：世代号推进时机）：`historyLoadTokenRef` 的换项目推进原来只在复位 effect 里，而 `projectPathRef.current` 是渲染期赋值的——交接窗口里守卫不再即时生效：React 的 passive effect 走宏任务、promise 续体走微任务，切换提交之后、复位 effect 之前落地的旧读取拿到的仍是旧世代号，会照常合并条目、写游标、关加载态（复位 effect 随后清掉状态，故终态没坏，但白跑一次跨项目读取且留下瞬时脏状态）。修正：推进移到渲染期，与 `projectPathRef` 同一处、只在路径真的变化时推进；复位 effect 不再推进。安全性依据：同一提交里子组件「填充视口」effect 的判据（`turns` / `historyHasMore` / `historyLoading` / `historyError` / 稳定的 `loadEarlier`）都不变，订阅状态复位本身也是 effect，因此这个窗口里不可能新起一次带旧游标的读取，去掉 effect 里的那一次推进不会放过它。
+- 验证（2026-10-02 追加，世代号推进时机）：该窗口依赖 React 调度（act 会把 effect 与断言放在同一个作用域里冲掉），jsdom 下无法构造出「旧读取先于复位 effect 落地」的确定性用例，因此没有新增红灯用例；既有的控制器世代用例（切项目、A→B→A）保持全绿，行为等价性由「本窗口内不会有新读取启动」的依赖分析支撑。真机若要硬证据，需在慢读取期间切项目并观察是否多打一次跨项目读取。
+
 ## 2026-10-01 Web、后台与 AGC 一键联调
 
 - 背景：Web、管理后台和 AGC 同时开发时，分别启动入口容易产生两套 API/worker/SpacetimeDB，以及重复后台 Vite。