文档：同步 DirectProject 对话滚动契约与旧口径
- ADR 修正样式删除口径：.message-history-more 因策划对话仍在用而保留，后续项一并说明 - 历史技术方案去掉「必须显示显示更早的对话按钮」的过期要求，改为引用新 ADR 的入口形态 - 决策记录新增本次滚动契约、边界与验证口径 Co-authored-by: Junie <junie@jetbrains.com>
This commit is contained in:
@@ -16,7 +16,7 @@ DirectProject 聊天区（`apps/ai-game-creator-shell/src/view/project-developme
|
||||
|
||||
### 1. 更早历史：删掉按钮，自动加载 + 内联加载行
|
||||
|
||||
- 删除「显示更早的对话」按钮、`message-history-more` 样式与 `DirectProjectConversation` 里的条件渲染。
|
||||
- 删除「显示更早的对话」按钮与 `DirectProjectConversation` 里的条件渲染；`.message-history-more` 样式**保留**——策划对话（`PlanningChatView`）仍在用同一套类名与按钮，等它一起改造时再删（见「影响」的后续项）。
|
||||
- 触发一（滚动）：`scrollTop <= 24` 且 `historyHasMore` 且不在加载中且没有失败记录时自动加载。
|
||||
- 触发二（填充视口）：首帧之后内容填不满视口（`scrollHeight <= clientHeight`）时继续加载，直到填满或 `hasMore=false`；不允许出现「历史比视口短、又没有按钮」的死局。
|
||||
- 两个触发都不越过既有的首屏订阅锚点 `lastCompletedItemId`；一次加载仍最多连拉 5 页（口径见 [`【ADR】DirectProject对话历史单一事实源-2026-09-16`](./【ADR】DirectProject对话历史单一事实源-2026-09-16.md)）。
|
||||
|
||||
@@ -1,4 +1,12 @@
|
||||
# 决策记录
|
||||
|
||||
## 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-01 Web、后台与 AGC 一键联调
|
||||
|
||||
- 背景：Web、管理后台和 AGC 同时开发时，分别启动入口容易产生两套 API/worker/SpacetimeDB，以及重复后台 Vite。
|
||||
|
||||
@@ -98,7 +98,7 @@ readHistory(threadId, { beforeItemId?, limit }) -> {
|
||||
}
|
||||
```
|
||||
|
||||
`subscribe` 不返回完整历史。`lastCompletedItemId` 只是历史读取锚点，前端自行按 item ID 懒加载需要的历史切片。`events` 是当前运行态重建所需的未完成 item 原始事件，以及当前 turn 的生命周期锚点；前端用同一个 reducer 重放 bootstrap 和后续事件。Rust 不保存或理解前端 reducer state。只要 DirectProject 历史切片返回 `hasMore`，聊天视图必须显示“显示更早的对话”入口，并允许按钮或滚动触发下一页，即使当前可见消息窗口没有隐藏消息。
|
||||
`subscribe` 不返回完整历史。`lastCompletedItemId` 只是历史读取锚点，前端自行按 item ID 懒加载需要的历史切片。`events` 是当前运行态重建所需的未完成 item 原始事件，以及当前 turn 的生命周期锚点；前端用同一个 reducer 重放 bootstrap 和后续事件。Rust 不保存或理解前端 reducer state。只要 DirectProject 历史切片返回 `hasMore`，聊天视图就必须能继续往前取页，即使当前可见消息窗口没有隐藏消息；入口形态（触顶自动加载 + 填充视口补载、加载行与失败重试、前插不跳）由 [`【ADR】DirectProject对话滚动与历史自动加载-2026-10-02`](../adr/【ADR】DirectProject对话滚动与历史自动加载-2026-10-02.md) 规定，已不再有常驻按钮。
|
||||
|
||||
`consume` 不接收或返回 cursor。每个 subscriber 在 Rust 内部持有自己的 cursor，并在加锁的临界区内完成过期判断、读取和 cursor 前进。前端只持有 `subscriptionId` 与 reducer state。并发 `consume` 不重复返回同一批事件。
|
||||
|
||||
@@ -106,7 +106,7 @@ readHistory(threadId, { beforeItemId?, limit }) -> {
|
||||
|
||||
`subscribe` 在同一个边界内先把新 subscriber 的游标钉在当时的队尾，再收集 bootstrap 的运行态事件，因此 bootstrap 返回的那批事件**就是**该 subscriber 此刻应处理的事件：前端直接 reduce 它们即可，不存在"先补一次 `consume` 才能拿到已暂存事件"的步骤。第一个例外只有回执竞态：Rust 侧一注册完 subscriber 就开始 `notify`，而前端要等回执到达才知道自己的 `subscriptionId`，这段窗口内的通知拿不到订阅身份。前端因此必须记一笔欠账，回执到达后立刻补一次 `consume` 取回那批事件；否则事件会卡在队列里等下一次通知，而一次回合的最后一个事件之后可能再也没有通知。除此之外不轮询，也不设任何定时 `consume`——唤醒只由 `notify` 负责。用定时器兜底既自举不了（判断"有活动回合"本身依赖事件），也把唤醒机制变成两套。
|
||||
|
||||
首屏历史不通过"读取整份对话"的命令获取：`subscribe` 返回的 `lastCompletedItemId` 就是首屏锚点，前端据此调用 `readHistory` 取最近的切片，再按滚动或按钮继续向前分页。系统不提供返回整份对话历史的命令。
|
||||
首屏历史不通过"读取整份对话"的命令获取：`subscribe` 返回的 `lastCompletedItemId` 就是首屏锚点，前端据此调用 `readHistory` 取最近的切片，再按滚动继续向前分页（入口形态见上条 ADR）。系统不提供返回整份对话历史的命令。
|
||||
|
||||
### 事件和顺序
|
||||
|
||||
|
||||
Reference in New Issue
Block a user