文档：新增 DirectProject 对话滚动与历史自动加载 ADR
新增 ADR，记录更早历史自动加载、内联加载/错误行、回合 key 锚点前插、回到底部胶囊与折叠展开的滚动契约。 在旧「对话历史单一事实源」ADR 的分页条目上补充指向新 ADR 的引用，保留原分页锚点口径。 docs/README.md 登记新 ADR。 Co-authored-by: Junie <junie@jetbrains.com>
This commit is contained in:
@@ -57,6 +57,7 @@
|
||||
- [DirectProject 命令入队化与待发消息队列归宿主](./adr/【ADR】DirectProject命令入队化与待发消息队列归宿主-2026-09-24.md)：命令只负责入队，放行归 Thread Manager；待发消息队列作为运行态事件归宿主、前端只投影；CLI 直连入口与调用身份守卫一并退役。
|
||||
- [AGC 命令错误结构化与错误报告口径](./adr/【ADR】AGC命令错误结构化与错误报告口径-2026-10-01.md)：AGC 命令失败按具体变体建模并用 ts-rs 导出，前端按变体分流、不匹配文案；报告池只收没人处理的错误。
|
||||
- [AGC 认证失败的 JS 侧载体与抛出时机](./adr/【ADR】AGC认证失败的JS侧载体与抛出时机-2026-10-01.md)：认证命令统一经 `invokeClientAuth` 把拒绝装进 `ClientAuthErrorWrapper`（`error` 字段就是 ts-rs 生成的 `ClientAuthError` 判别联合），不新增手写错误类；判定只写在 catch 子句里，无字段变体用固定文案、带载荷分支先 `as` 取自己的具名载荷类型（可枚举细分再 `switch (payload.reason)` 在类型化枚举上分流），系统变体原样抛出经 `unhandledrejection` 入池，`default: expectNever` 编译期挡住漏接变体。
|
||||
- [DirectProject 对话滚动与历史自动加载](./adr/【ADR】DirectProject对话滚动与历史自动加载-2026-10-02.md)：删掉「显示更早的对话」按钮改为自动加载 + 内联加载/错误行，回合 key 冻结锚点前插不跳，底部居中「回到底部 / 有新回复」胶囊，折叠展开按跟随状态贴底或保锚点。
|
||||
- [DirectProject 命令入队化与待发消息队列归宿主实施计划](./technical/【实施计划】DirectProject命令入队化与待发消息队列归宿主-2026-09-24.md)：五步落地顺序、每步不变式与验收；待实施。
|
||||
- [GameAgent 对话工具调用卡片](./technical/【技术方案】GameAgent对话工具调用卡片-2026-09-14.md)：把右侧对话里的执行命令 / 写文件投影成 Codex 风格可折叠卡片，含采集、独立历史文件、事件字段与回读契约。
|
||||
- [DirectProject 客户端 Skill 与 MCP 扩展导入方案](./technical/【技术方案】DirectProject客户端Skill与MCP扩展导入方案-2026-08-31.md)：客户端扩展导入、按独立 Skill/MCP 拆分、命名、启用和启动时注入边界。
|
||||
|
||||
@@ -35,7 +35,7 @@ AGC 项目开发聊天框当前同时从多处取数据：Direct 回合事件（
|
||||
- 执行通道断开同样是失败终态，也必须带 `failure`：连接级故障（app-server 进程退出 / stdout 流断 / JSON 行越界）与回合事件通道关闭都算，`kind="transport-failed"`、`message` 用宿主当场写下的那份诊断（含 `exitStatus` 与 stderr 摘要，已脱敏截断）。宿主在检测到连接终止的第一时间把这条事实记到本回合的执行适配器上，终态判定再从适配器读：执行适配器的看门狗盯着同一个 `closed` 标志，用调用点局部变量会输给这场调度竞争，失败原因就只剩日志、界面只会看到"本轮已结束"。判据是"适配器是否已由宿主主动关闭"——宿主自己收束（正常终态 / 用户主动停止 / 预算与交付收尾）走的是同一个 `TransportClosed` 事件，但这些不算失败。
|
||||
- 终态由**事实**判定，不由收尾阶段反推：判定按优先级取「宿主当场记下的失败（通道断开 / 等待超时 / app-server 单方面中断）→ 本回合的错误结果是 Err → 只有收尾阶段的账本读不出来时才用交付报告」，**有载荷一定写 `status="failed"`**，没载荷才用收尾阶段推出来的 `status`。收尾会把 ledger 阶段推成 `Interrupted`，让阶段决定终态就会把已经失败的一轮讲成"已结束"。模型自报失败（原生 `turn/completed.status="failed"` 的 `error`，带 `codexErrorInfo` 分类）不为载荷新增输入字段：宿主把原生 `error` 的 `codexErrorInfo` 解析成 typed 分类后当作本回合的错误结果，走同一条通道进载荷；交付报告只说明"收束到哪一步"，不得顶掉原因。
|
||||
- 回合失败在宿主内部是 **typed** 的：`agent/direct_turn_error.rs` 的 `DirectTurnError` 每个变体自带字段（并发拒绝带两个 invocation id、模型失败带分类、超时带撞的是哪条上限、通道断开带宿主诊断），**调用级拒绝**（这一轮没有开始）与**回合级失败**（这一轮已开始并被判失败）不共用判据，分流只认 `is_turn_failure()`。判据不再对原因文本做子串匹配，`LlmError` 只在平台层入口出现一次（`DirectTurnError::from_model_call`）。线上载荷 `{kind, message}`、命令边界字符串与 CLI 返回值都由这一个出口投影出来，Rust 侧任何地方都不再解析它们。
|
||||
- 分页锚点取原始条目 id；一次翻页操作在前端自动连拉，直到出现可显示条目或 `hasMore=false`，上限 5 页。
|
||||
- 分页锚点取原始条目 id；一次翻页操作在前端自动连拉，直到出现可显示条目或 `hasMore=false`，上限 5 页。（**按 2026-10-02 ADR 补充**：更早历史的触发时机、加载指示、失败重试与视口锚定改由 [`【ADR】DirectProject对话滚动与历史自动加载-2026-10-02`](./【ADR】DirectProject对话滚动与历史自动加载-2026-10-02.md) 规定；本条的分页锚点口径与连拉上限仍然有效。）
|
||||
- `notify` 是唯一唤醒来源：`subscribe` 的 bootstrap 事件本身就是该 subscriber 此刻要处理的事件（游标已在队尾），前端直接 reduce 它们，不需要为了取这批事件再补一次 `consume`，之后完全由 `notify` 驱动，不设低频 tick 或任何轮询兜底。唯一例外是回执竞态：Rust 侧一注册完 subscriber 就开始 `notify`，前端却要等回执才知道自己的 `subscriptionId`，这段窗口内的通知只能记成欠账，回执到达后立刻补一次 `consume` 取回，否则该回合的尾部事件会卡在队列里等一个可能永不出现的下一次通知。
|
||||
- 迁移按一次干净切换落地：不做灰度、不做运行时开关、不双跑；允许提交序列里存在「新源已启用、旧代码尚未删除」的中间窗口，禁止反向的「新源未启用、旧源已删」。
|
||||
- 思考过程与工具活动同样从运行态事件与历史条目推断，界面展示保持不变。
|
||||
|
||||
@@ -0,0 +1,68 @@
|
||||
# 【ADR】DirectProject对话滚动与历史自动加载-2026-10-02
|
||||
|
||||
状态：已接受
|
||||
|
||||
## 背景
|
||||
|
||||
DirectProject 聊天区（`apps/ai-game-creator-shell/src/view/project-development/chat/components/DirectProjectConversation/`）当前的滚动与历史体验有三个问题：
|
||||
|
||||
1. 更早历史要靠常驻按钮「显示更早的对话」（`.message-history-more`）手动拉，但 `handleScroll` 里已经有一条「滚到顶部 24px 以内就自动加载」的路径——按钮是半冗余的第二入口，还没有任何加载中的视觉反馈（`historyLoadingRef` 是 ref，渲染不出来）。
|
||||
2. 用户滚上去之后没有任何「回到最新」的入口，只能自己一直滚到底。
|
||||
3. 展开一折叠块（`<details>` 或 `[aria-expanded]`）时浏览器保持 `scrollTop` 不变，新展开的正文长在视口下方，用户必须再滚一次才能看到；反过来在底部展开时内容直接顶出可视区。
|
||||
|
||||
同一目录下的 `PlanningChatView` 复用 `.project-chat-message-list` / `.project-chat-conversation` 两个类名，所以任何滚动容器结构改动都必须留在 DirectProject 本地，不能改公共类。
|
||||
|
||||
## 决策
|
||||
|
||||
### 1. 更早历史：删掉按钮，自动加载 + 内联加载行
|
||||
|
||||
- 删除「显示更早的对话」按钮、`message-history-more` 样式与 `DirectProjectConversation` 里的条件渲染。
|
||||
- 触发一（滚动）：`scrollTop <= 24` 且 `historyHasMore` 且不在加载中且没有失败记录时自动加载。
|
||||
- 触发二（填充视口）：首帧之后内容填不满视口（`scrollHeight <= clientHeight`）时继续加载，直到填满或 `hasMore=false`；不允许出现「历史比视口短、又没有按钮」的死局。
|
||||
- 两个触发都不越过既有的首屏订阅锚点 `lastCompletedItemId`；一次加载仍最多连拉 5 页（口径见 [`【ADR】DirectProject对话历史单一事实源-2026-09-16`](./【ADR】DirectProject对话历史单一事实源-2026-09-16.md)）。
|
||||
- 加载中在列表最上方（比最旧一条回合更靠上）挂载一行 `role="status"`、`aria-live="polite"` 的「正在加载更早的对话」，带旋转圈；延迟 150ms 才显示，加载结束即卸载。它按需挂载，靠位置补偿（见第 2 条）保证下面的消息不跳。
|
||||
- 失败：挂起自动加载，列表顶部保留一行 `role="alert"` 的「加载更早对话失败 · 重试」，重试是可聚焦按钮；**不自动重试**，只有点重试（或切换项目）才重新开始；重试成功后错误行消失。
|
||||
|
||||
### 2. 前插锚定：回合 key + 偏移，关掉浏览器原生锚定
|
||||
|
||||
- 锚点 = 顶部可见回合的 `data-turn-key` + 该回合内的块序号 + 相对列表顶边的像素偏移。
|
||||
- 合并更早历史前记录锚点，合并后按同一 key/序号把偏移还原，较早内容出现在上方而用户正在读的位置不动。
|
||||
- 列表上加 `overflow-anchor: none`，关掉浏览器原生 scroll anchoring，保证只有一套补偿在跑（不做「两套补偿交替生效」）。
|
||||
- 一次加载期间（`historyLoading` 为真）所有补偿——ResizeObserver 回调、加载行挂载、历史合并——都还原同一个冻结锚点；加载结束再刷新锚点。
|
||||
|
||||
### 3. 回到底部胶囊
|
||||
|
||||
- 列表底部居中的悬浮胶囊（`sticky`），跟着滚动容器走、不随内容滚走。
|
||||
- 距底部超过 48px 时出现，文案「回到底部」；用户不跟随时来了新的终态内容就改成「有新回复 · 回到底部」。
|
||||
- 点击：平滑滚到底部 + 恢复跟随最新 + 清除「有新回复」，随后按钮自行消失。
|
||||
|
||||
### 4. 跟随最新与折叠展开
|
||||
|
||||
- 距底部 ≤ 48px 视为「在底部」，即跟随最新；用户手动滚回去（进入阈值）就自动恢复跟随，不需要额外开关。
|
||||
- 用 `ResizeObserver` 观察列表的直接子元素（`MutationObserver` 负责在子元素变化时重订阅）——任何高度变化：
|
||||
- 跟随时 → 贴底；
|
||||
- 不跟随时 → 还原顶部可见回合锚点（用户正在读的那条折叠头留在原位）；若刚刚展开的那个块头部仍然可见，则按展开前记录的屏幕位置把它冻结；
|
||||
- 展开正文比视口还高、头部锚不住时 → 对齐正文顶部。
|
||||
- 新一回合开始（`turnInFlight` 由假转真）时强制恢复跟随并贴底，替代原先由视图直接写 `shouldFollowLatestRef` 的做法。
|
||||
|
||||
### 5. 结构与样式
|
||||
|
||||
- 滚动所有权（列表 ref、跟随最新、ResizeObserver、锚点还原、胶囊可见性）搬进 `DirectProjectConversation` 这一层；`DirectProjectChatView` 只传加载状态与回调，不再持有 `messagesRef` / `shouldFollowLatestRef` / `handleScroll`。
|
||||
- 控制器对渲染层暴露可渲染的 `historyLoading` 与 `historyError`（外加 `retryEarlierHistory`），取代只存在于 ref 里的加载标志。
|
||||
- 新增元素全部用内联 Tailwind 工具类，不改 `styles.css`；列表本身仍保持 `message-list project-chat-message-list` 类名不变，只追加 `overflow-anchor` 工具类。
|
||||
|
||||
## 备选方案与取舍
|
||||
|
||||
1. **保留按钮 + 只加自动加载**：加载中仍靠按钮做唯一反馈，且删掉按钮后失败路径没有补救入口；按钮本身与滚动自动加载重复。
|
||||
2. **在列表外面套一层 viewport 做浮层定位**：`PlanningChatView` 共用同一套容器规则，且工作台里 `.project-chat-conversation` 是 `display: block` + `height: 100%` 几何，套一层就会让 `height: 100%` 的列表塌成内容高度；改公共类会连带策划对话。改用列表内的 `sticky` 胶囊，零结构改动。
|
||||
3. **只依赖原生 CSS scroll anchoring**：前插能免费对齐，但做不到「跟随时展开要贴底」，也无法在加载期间冻结同一套锚点；因此显式补偿 + 关闭原生锚定。
|
||||
4. **展开后总是把正文滚进视口**：会打断正在读历史的用户；采用「跟随时贴底 / 否则保锚点、头部锚不住才对齐正文顶部」。
|
||||
5. **自动重试失败的历史加载**：弱网下会反复打接口，且用户看不出到底在重试还是在挂起；改为挂起 + 内联重试行。
|
||||
|
||||
## 影响
|
||||
|
||||
- 历史加载失败不再只写顶部状态行，而是落到列表里的内联错误行；顶部状态行仍保留首屏读取失败等其它用途。
|
||||
- 滚动是表现层行为，正式状态仍在后端投影与运行态事件；本 ADR 不新增领域概念。
|
||||
- 阈值（触顶 24px、贴底 48px、spinner 150ms）是可按手感调整的常量，集中放在 `components/DirectProjectConversation/conversationScrollPolicy.ts`。
|
||||
- 验收：纯函数与 jsdom 组件测试覆盖阈值、锚点还原、加载/错误行、胶囊文案与显隐；滚动观感（顶部加载圈、胶囊出现与消失、底部展开回贴、历史前插不跳）必须真机手动验收——jsdom 没有布局。
|
||||
- 明确的后续项（不在本次范围）：`PlanningChatView` 与 `App.tsx` 遗留 `message-history-more` 路径的同款改造、未读条数徽标、Playwright 端到端。
|
||||
Reference in New Issue
Block a user