goodbuddy/docs/features/chat-history-navigation/progress.md

# 实施进度

## 2026-10-08

- 已确认 80 条限制由 `ChatHistoryPane` 的 `messageRenderBatchSize` 和 `revealEarlierMessages` 驱动。
- 已确认消息窗口化仍以高度占位和最多约 60 条挂载消息为上限。
- 已建立基线、本阶段和 minimap 阶段的对比测试计划。
- 已将生产会话接线改为直接使用当前已加载消息总数，保留 DOM 窗口化。
- `ChatHistoryPane` 与 `ChatTimeline` 定向测试通过：58/58。
- 改动文件定向 web 类型检查和 lint 通过。
- `npm run build:bundle` 通过。
- `npm run perf:app` 通过。本次 B 组测量中，长会话打开交互延迟为 86.9 ms，长会话滚动帧间隔 p95 为 16.9 ms、无长任务；流式输入场景帧间隔 p95 为 16.9 ms，输入延迟 p95 为 17.1 ms。
- B 组第二次运行仍通过：长会话打开交互延迟为 46.9 ms，长会话滚动帧间隔 p95 为 16.8 ms、无长任务；流式输入场景输入延迟 p95 为 19.1 ms。
- App 测试通过 341/349；剩余 8 个失败集中在既有图片附件异步场景，未出现聊天历史窗口相关失败。
- 全局 `npm run typecheck` 仍被既有 `src/main/desktop-storage-electron-fixture.ts:215-217` 类型错误阻断；全局 lint 仍包含生成的 VitePress cache 错误。
- A 组临时恢复后连续两次在 composer 初始化阶段超时，未进入性能场景，因此没有有效 A 组数据，不能据此推导 A/B 数值差异。B 组代码已恢复并重新完成 bundle、定向类型检查、定向 lint 和 58/58 聊天窗口测试。

## 2026-10-11

- 已确认工作区干净，生产代码保持 `47917094` 的 A 组：向上滚动仍按 80 条揭示，DOM 窗口化仍保留。
- 当前聊天窗口和时间线定向测试：59/59 通过，包含 2,000 条消息连续滚动、实际挂载数量上限、锚点稳定、状态恢复和 80 条历史揭示。
- App 单元测试：342/350 通过；8 个失败均为等待状态圆点的既有异步断言，失败位置不涉及历史窗口逻辑。
- `npm run build:bundle`：通过。
- 当前 A 组首次可重复的 `npm run perf:app`：通过。长会话打开交互延迟 54.4 ms；长会话滚动无长任务，帧间隔 p95 8.5 ms；流式输入延迟 p95 10.0 ms；流式输入场景无长任务。
- 性能基准内存回收：24 次切换后 mounted panes 保持 6，DOM 从 24,746 降至约 2,446，堆从 50.5 MB 回收至约 22 MB，后半段增长约 0.1 MB。
- 之前记录的“A 组 composer 初始化超时”未在当前回退后的基线复现；现在已经取得有效 A 组数据，后续可在同一 bundle 和环境下重新接线 B 组做严格交替 A/B。
- minimap 尚未实现；在 B 组完成交替测量前不进入 minimap 性能对比。
- B 组已重新接线：`ConversationHistorySlot` 对完整会话传入 `conversation.messages.length`，App 层不再维护 80 条可见数量状态；摘要会话仍走原有历史加载流程。
- B 组 App 历史回归：4/4 通过，覆盖无历史闸门、长会话有界提交、暖切换位置和展开状态、超过 500 条历史保留。
- B 组 `npm run build:bundle`：通过；改动文件 web 类型检查和 lint：通过。
- B 组 `npm run perf:app`：通过。长会话打开交互延迟 46.8 ms，长会话滚动无长任务、帧间隔 p95 8.5 ms；流式输入延迟 p95 9.5 ms，无长任务。
- A/B 基准对比：B 组 DOM 在长会话滚动后约 2,644、24 次切换回收后约 2,446；A 组对应约 2,632 和 2,446。B 组 24 次切换后的堆约 22.9 MB，后半段增长约 0.1 MB；A 组约 22.0 MB，后半段增长约 0.1 MB。当前没有观察到明显滚动、流式或内存回收回归。
- 全量 App 测试：B 组 341/350 通过；剩余 9 个中 1 个为已迁移历史测试前的旧断言结果，8 个仍为既有等待状态圆点异步断言。迁移后的历史相关测试已单独通过。
- B 组尚未提交；下一步继续做多轮交替 A/B 和低端机模拟，再决定是否进入 minimap。

## 2026-10-12

- C 组已实现 minimap：使用单个 canvas 绘制用户、助手、工具／待处理和错误消息色带，不为每条消息增加 DOM 节点。
- minimap 显示当前滚动视口，支持点击、指针拖动、Home、End、PageUp 和 PageDown；使用现有滚动容器和消息高度估算定位。
- 新增 `ChatMinimap.test.tsx`，覆盖颜色分类、坐标边界、跳转和键盘操作；minimap、历史窗口和时间线定向测试共 62/62 通过。
- C 组 App 历史相关回归 4/4 通过；改动文件 lint、web 类型检查和 `npm run build:bundle` 通过。
- C 组 `npm run perf:app`：通过。长会话打开交互延迟 46.4 ms；长会话滚动帧间隔 p95 8.5 ms、无长任务；流式输入延迟 p95 9.6 ms、无长任务。
- B/C 单次对比：滚动 p95 均为 8.5 ms 且无长任务；B 组流式输入 p95 9.5 ms，C 组 9.6 ms；B 组 24 次切换后 DOM／堆约 2,446／22.9 MB，C 组约 2,449／23.1 MB，后半段堆增长均约 0.1 MB。
- C 组尚未做多轮交替和低端机模拟；当前结果支持继续保留实现并进入更广泛验证，不能单凭单次数据宣称最终性能结论。

### 2026-10-12 交互修订

评审发现初版 minimap 是悬浮在中部的 220 px 小条，视口指示经 `requestAnimationFrame` + React 状态更新而滞后于滚动，且没有悬停放大。已修订：

- minimap 替代消息滚动区的原生滚动条：`.chat-history-pane > .chat` 隐藏原生滚动条，minimap 高度与滚动区 `clientHeight` 一致并贴合右侧。
- 视口滑块在 `scroll` 事件和 `ResizeObserver` 回调中同步写入 `transform`，不经过 React 提交或下一帧；滚动区尺寸不变时只写 `transform`，不读布局。
- canvas 仅在消息变化、行高测量变化、尺寸变化或展开／收起时重绘；普通滚动不重绘。
- 悬停时展开为 96 px（窄屏 64 px）的缩略长图：用户消息靠右、助手消息靠左并按内容长度给出线宽；拖动中离开不收起。
- 点击轨道将滑块中心移到指针处，拖动滑块保持抓取偏移；滚轮转发给消息区；保留 Home／End／PageUp／PageDown；无障碍角色为 `scrollbar`，文案使用 i18n `chat.minimap`。
- 验证：minimap、历史窗口和时间线定向测试 65/65；web 类型检查和改动文件 lint 通过；`App.test.tsx` 342/350，8 个失败与此前相同（等待状态圆点异步断言）；`npm run build:bundle` 通过。
- `npm run perf:app` 通过：长会话打开帧 p95 8.6 ms、无长任务；长会话滚动帧 p95 8.6 ms、无长任务；`stream-seeded`／`stream-and-type` 无长任务、帧 p95 8.5 ms；24 次切换后 DOM 2,449、堆 23 MB，后半段增长 0.1 MB。
- 未验证：真实鼠标悬停／拖动的视觉效果仍需在桌面端人工确认；多轮交替与低端机模拟仍未做。

### 2026-10-12 第二次交互修订

- minimap 只覆盖阅读区：顶部从 `--chat-context-height`（任务条）开始，毛玻璃模式下再让出 58 px 标题栏；滑块轨道高度取 rail 实际高度，rail 自身尺寸变化由独立 `ResizeObserver` 触发重算。
- 展开宽度调为 120 px（后续按反馈改为 80 px）。展开视图改为逐行描线：`minimapLines` 按约 72 列折行（CJK 按两列计）、保留空行、代码块缩进并降低不透明度，每条消息最多取 600 行；消息块高度装不下时按行均匀抽样。行剖面按消息对象缓存在 `WeakMap`，流式更新产生新对象时才重算。
- 验证：定向测试 67/67（新增折行剖面和逐行绘制用例）；web 类型检查与 lint 通过；`npm run build:bundle` 通过。
- `npm run perf:app` 通过，各场景帧 p95 8.5–8.6 ms；长会话打开、长会话滚动、两个流式场景均无长任务；内存回收与上一轮一致。运行中出现的 renderer error 为网络更新检查 `AbortError`，与本功能无关。

### 2026-10-12 第三次交互修订

- 展开宽度改为 80 px（窄屏仍为 64 px）。
- 已取消的回复在缩略图中改为助手灰色，与正文状态行一致；只有失败的回复显示红色（复用 `isCancelledMessage`）。
- 修正滚动时缩略图密度变化：此前每条消息的色块高度取 `MessageRowHeights.size()`，未测量行使用“已测行平均高度”估算；滚动挂载新行后估算值和实测值变化，每次提交都会按新高度重画整张图。现改为双轴：
  - 绘制轴：`minimapMessageWeight`（折行数 + 3 行头部 + 每个工具 2 行），只依赖消息内容；画布只在消息数组变化（新消息、流式输出）或尺寸、展开状态变化时重画，行测量不再触发重画。
  - 滚动轴：行高前缀和，仅在 `scrollHeight` 变化时重建。滑块位置和高度按行在两轴之间分段线性映射，覆盖视口内消息在缩略图上的实际区段（最小 16 px）；点击和拖动走反向映射。
- 验证：minimap、历史窗口、时间线定向测试 69/69（新增“行测量不��发重画”和“滑块对齐可见行的概览区段”用例）；web 类型检查与 lint 通过；`npm run build:bundle` 通过。
- `npm run perf:app` 连续两次通过。第二次结果：长会话打开、长会话滚动、`stream-seeded`、`stream-and-type` 均无长任务，帧 p95 8.5 ms；24 次切换后 DOM 2,449、堆 23.2 MB，后半段增长 0.2 MB。第一次运行中长会话滚动帧 p95 为 16.6 ms，`stream-seeded` 有 1 个 62 ms 长任务，第二次未复现，按单次噪声记录。
- 未验证：真实桌面端滚动时的视觉稳定性需人工确认。

### 2026-10-12 外观设置开关

- 新增应用设置 `chatMinimapEnabled`（`z.boolean().default(true)`），旧设置文件缺省时读为开启，无需升级设置版本；`application.update` 配置工具复用同一更新 schema，自动接受该字段。
- 设置 › 外观新增开关“滚动条缩略图”／“Scrollbar minimap”，位于“透明磨砂特效”之后，保存后立即生效。
- 关闭时 `ChatHistoryPane` 不挂载 `ChatMinimap`，也不再设置 `data-minimap`，原生滚动条随之恢复；历史窗口（完整已加载消息）和约 60 条 DOM 窗口不变。
- 验证：设置存储（缺省默认、两种取值的持久化与重载、非法值拒绝）、外观开关（中英文）、窗格开关切换用例均通过；相关 8 个测试文件 410 项中修正配置快照夹具后全部通过；`App.test.tsx` 342/350，8 个失败与此前相同；web／node 类型检查（除既有 `desktop-storage-electron-fixture.ts`）与改动文件 lint 通过。