Jyotisha/docs/tasks/PROGRESS-chat-streaming-ux-20260901.md

# PROGRESS · Agent 聊天流式体验与双会话面统一（2026-09-01）

工作树：`.worktrees/streaming-ux-20260901`
分支：`codex/streaming-ux-20260901`
基线：任务 0–2 时为 `origin/staging` @ `fbb80fa3`；2026-09-02 远端前进到 `058e5db9`（`bf6989ec` 第三批拆页、`124d3990` 引擎卫生、`058e5db9` Home lint 修复）后本分支 **rebase 到其上**，任务 3 在该基线上做。

**BUG 编号顺延**：staging 的 lint 修复占用了 BUG-470，本分支四条整体后移（470→471、471→472、472→473、473→474），`docs/BUG_HISTORY.md`、本文件、四个测试文件里的注释与四个 commit message 一并改（用 `git filter-branch --tree-filter/--msg-filter` 在原提交上逐个改，再 rebase，只在 `BUG_HISTORY.md` 冲突一次）。任务书 `TASK-chat-streaming-ux-20260901.md` 未动。

未改 `.gitea/workflows/**`。未合并 staging，未碰 main。未手写 `useCallback` / `useMemo`（`rectification-agentic-chat.tsx` 既有的 `useCallback` 原样保留）。未动服务端事件语义；校正 `thinking.delta` 在 `stream-mapping.ts` 公开边界的丢弃原样保留。`page.tsx` 一行未动。

| 任务 | 状态 | commit | BUG |
| --- | --- | --- | --- |
| 0 · 流式按帧合并 + 匀速吐字 + Markdown 前缀记忆 | 完成 | `dd4e3b37` | BUG-473 |
| 1 · 结算不闪、时间线开合过渡、流式可折叠、queued 行 | 完成 | `69d19e0f` | BUG-474、BUG-475 |
| 2 · 校正接入同一套时间线、删三条死路径、移除 thinking-orbs | 完成 | `cc17d971` | BUG-476 |
| 3 · 校正复用 ChatComposer / 统一滚动跟随 / JumpToLatest / 900px | 完成（第三批合入后解除阻塞） | `b72c1efc` | BUG-477、BUG-478 |
| 4 · DESIGN.md | 与 0/1/2 对应的条目随各任务改；与 3 对应的四条随任务 3 同 commit | — | — |

**第二次 rebase 与编号再顺延（2026-09-02）**：远端又合入 `1a3e14e7`（问题题干显示/占用后解锁采用），占了 BUG-471/472。本分支再次用 `filter-branch` 在原提交上改号后 rebase 到 `1a3e14e7`：471→473、472→474、473→475、474→476、475→477、476→478，`BUG_HISTORY`、本文件、测试注释、commit message 一并改。冲突两处：`docs/BUG_HISTORY.md`（取 staging 全文 + 我方条目续在后面）；`rectification-agentic-chat.tsx`（两边都保留——staging 的 `collectSpokenPromptId` 与题干 `<p>` 原样，staging 加在 `<Textarea>` 上的 `aria-describedby` 改为经 `ChatComposer` 新增的 `describedBy` prop 传入，composer 把它与字数计数 id 合并成一个 `aria-describedby`）。staging 新测试 `rectification-spoken-collect` 锁 `aria-describedby={collectSpokenPrompt`（内联 Textarea），按红线 3 改锁 `describedBy={collectSpokenPrompt …}` + composer 的合并表达式，注释原值。`character-remaining-contract` 的 `aria-describedby={showRemaining ? remainingId : undefined}` 锁随之改为合并表达式。

## 任务 0 · 流式渲染

改动：`src/lib/stream-frame-buffer.ts`（新）、`src/lib/chat-markdown-split.ts`（新）、`src/components/chat-message-content.tsx`、`src/components/chat-message-row.tsx`（`streaming` prop）、`src/hooks/use-consultation-run.ts`、`src/components/rectification-agentic-chat.tsx`。

- 两个会话面的事件回调都不再直接 `setState`：事件写入累加器，`requestAnimationFrame` 每帧最多一次 flush；`run.completed` / `run.failed` / abort / 读流结束时 `settle()` 同步冲干净；`finally` 里 `dispose()`；校正 `attempt.reset` 走 `reset()`。
- 释放节奏：`max(2, ceil(积压 ÷ 12))` 字/帧，积压按「新文本到达时的未释放量」记，所以 3,000 字突发恰好 12 帧追平（测试锁死），稳态约落后网络 12 帧（≈200ms）；页面隐藏走 250ms `setTimeout` 并一次放完。
- 重活只做一次：`parseAgentReply` / `applyThinkingSectionProgress` 只在 flush 里对已释放文本跑。
- Markdown：流式时在最后一个空行切「稳定前缀 / 尾块」，不切进代码围栏、同一列表的项之间、表格行之间；前缀交给 `memo` 的 `StableMarkdownPrefix`，只有尾块每帧 parse；切分对象是 `splitSpokenAnswerAndTechniqueAudit(text).spoken`，技法审计表留在审计折叠里。结算后仍整篇一次 parse，DOM 结构与流式时一致（react-markdown 不加包裹元素）。
- 没有另写"薄 hook"：`use-consultation-run` 按前两轮拆页公证是"内部 0 个 React hook"，缓冲器按每次 send 创建/销毁的工厂用法更贴合，两处调用都是这个形态。

渲染次数探针（`tests/home-streaming-render-split.test.ts` 新增用例，假 rAF 驱动）：200 个单字 token、每帧到 4 个、共 50 帧 → **`streamingRowRenders = 50`**（改前的架构每 token 一次 = 200）。`tests/stream-frame-buffer.test.ts` 同一场景 flush 50 次，且每次释放 ≥2 字、结算后与网络全文一致。

Performance 面板录制（3k 字回答无 >50ms 长任务）**未做**：无登录态、无 Chrome，见 `BLOCKED.md`。

## 任务 1 · 结算与时间线

改动：`src/components/chat-transcript.tsx`（重写）、`src/lib/chat-message-view.ts`（`latestAssistantView`）、`src/lib/home-streaming-render-probe.ts`（`latestEntryMounts`）、`src/components/consultation-run-timeline.tsx`（重写）、`src/components/chat-message-row.tsx`（GSAP 0.16）、`src/app/globals.css`、`scripts/home-streaming-render-benchmark.mts`（改用 `LatestAssistantEntry`）。

- `ChatTranscript` = `SettledMessageList excludeLatestAssistant` + 一个 `LatestAssistantEntry key={renderKey}`。同一个 `MessageEntry` 渲染历史行、流式行、刚结算行，动作条与追问只在 settled 出现。`renderKey` 在流式（`message-N`，N=历史条数）与结算（末条下标 N）下相同，纯函数 `latestAssistantView` 有测试锁。
- `.message` 的 CSS `message-enter` 关键帧删除，只剩 GSAP 一份，时长 0.18 → 0.16（DESIGN.md §6 = 160ms）。
- 时间线：去掉 `key={live…}`；外层 `<section>` + `button[aria-expanded][aria-controls]`；`open = userOpen ?? live`；折叠是 `grid-template-rows 0fr↔1fr` 180ms，折叠后内容 `inert`；summary 文案换行 120ms 淡入；live 行与 summary 文案共用既有 `agent-activity-status__text` shimmer；`rows` 为空且 live 时渲染 `QUEUED_TIMELINE_ROW`「正在处理…」。reduced-motion 下三处过渡为 0（全局 `*` 规则之外再显式写了一次）。
- `latestEntryMounts` 探针只能在浏览器里手动读（无 DOM 测试库，`renderToString` 不跑 effect），见 `BLOCKED.md`。

## 任务 2 · 双会话面统一

改动：`src/lib/rectification-timeline-adapter.ts`（新）、`src/components/rectification-agentic-chat.tsx`、`src/components/agent-activity-status.tsx`（重写为兜底）、`src/components/chat-message-row.tsx`、`src/app/globals.css`、`package.json` / `package-lock.json`（`npm uninstall thinking-orbs`）；删除 `consultation-thinking-report.tsx`、`thinking-step-tree.tsx`、`completed-activity-receipt.tsx`。

- 适配：tool trace → `calculate` 行（started=live / completed=done，标签沿用 `RECTIFICATION_TOOL_*_LABELS`）；`failedTool` 的行标签加「未完成」且不挂 chips；回执 `methods` 经 `PUBLIC_RECTIFICATION_METHOD_LABELS` 去重 ≤8 作为最后一条完成 calculate 行的 `sources`；没有 live 行且 `activity.label` 以「正在」开头时补一条 live 行（`answer-composition` → `write`，其余 → `calculate`）；think 类 trace 项映射为 think 行（现网不会出现，服务端丢弃）。
- 校正结算后与普通会话一样收成「已完成 N 步」一行，方法 chips 在行内展开；第二个回执折叠块、消息上方红字失败行、重新生成时的假「正在组织回答…」全部删除；失败走既有 `error` 通知；重新生成显示 queued 行。
- `chat-message-row.tsx` 只剩 timeline 一条主路径 + `AgentActivityStatus` 兜底（无 trace 分支、无 orb）；live 标记全部 `InlineSpinner`；`.conversation.is-rectification .agent-thinking-step/.agent-thinking-marker` 14px 覆写删除。
- 校正的「已用时 N 秒」计时（`ActivityElapsed`）随 trace 面板一起退出——时间线本来就没有这个元素，两面一致优先。

## 任务 3 · 校正复用 ChatComposer、统一滚动跟随与「跳到最新」

开工时 `git log origin/staging -- frontend/src/app/page.tsx` 最新为 `551d6317`，第三批未合入，先按红线 7 登记 `BLOCKED.md`；远端合入 `bf6989ec`/`058e5db9` 后 rebase，阻塞解除，`BLOCKED.md` 该条改为已完成。

改动：`src/hooks/use-conversation-scroll-anchor.ts`、`src/components/jump-to-latest-button.tsx`（新）、`src/components/chat-composer.tsx`、`src/app/page.tsx`、`src/components/rectification-agentic-chat.tsx`、`src/app/globals.css`；删除 `src/lib/rectification-sticky-scroll.ts`。

- **ChatComposer**：新增可选 `value`（受控）与 `remainingId`。`const storeDraft = useComposerDraft(); const draft = value ?? storeDraft;`——store 订阅仍在组件内，主会话行为不变；校正面传 `value={draft}`，`grep composer-draft` 在校正文件里为 0（契约锁死）。校正面 `maxLength=500`（`RECTIFICATION_COMPOSER_MAX_LENGTH`，与主对话同上限），footer 放 `CharacterRemaining`（id 用 `useId`）；三段 placeholder、Enter/Shift+Enter/`isComposing`、「停止回答」文案与 `stopRun` 原样。
- **滚动跟随只留一份**：`useConversationScrollAnchor` 增加 follow：`ResizeObserver` 观察滚动容器的子元素（`MutationObserver childList` 跟踪子元素增删并重新观察），anchored 时下一帧 `scrollTop = scrollHeight`；`resetKey` 变化时先落底一次；`anchored` 经 `anchoredRef` 在 effect 里同步（不在 render 写 ref，过 `react-hooks` 规则）。`page.tsx` 那个按 `activeStreamingText` 触发、结算时再补 smooth 的 effect 删除；hook 调用签名 `(conversation, !rectificationSurfaceOpen && !starterHomeVisible, activeSessionId)` 不变，starter home 不滚动的性质由 `active=false` 承担。校正面 `useConversationScrollAnchor(conversation, true, caseId)`，删除 `followTailRef` / `scrollFrameRef` / `updateFollowState` / `scrollToLatest` / `followLatestContent` / `showJumpToLatest` / `choiceCardsOpen` 与两个 `useLayoutEffect`；`rectification-sticky-scroll.ts` 删除。选择卡 360px 带宽的特例随之退出：卡片本来就在 transcript 里，看着它的人离底 ≤96px，本就 anchored。
- **JumpToLatestButton**：`.jump-to-latest`（absolute、`bottom: 100%`、`pointer-events: none`）+ `.jump-to-latest__button`（44px、`--shadow-elevated`、focus ring、hover 暖卡片色），两面共用，文案统一「跳到最新」带 `ArrowDown`；`page.tsx` 内联 Tailwind 版（`shadow-md`）与 `.rectification-jump-latest` 三条规则删除。
- **宽度**：`.rectification-workspace__chat .message-list { max-width: 720px }` 删除，两面同 `.message-list` 的 900px；`--rectification-jump-clearance` 底部留白保留。
- 手工项（两面各做一次「流式中上滚→停跟随→出现按钮→点回底并恢复跟随」）**未做**，无登录态无 Chrome；行为由 `chat-notice-and-scroll-contract`、`rectification-agentic-entry`、`rectification-answer-choice` 的 hook/组件锁与 `nextAnchorState` 纯函数断言代替。

## 任务 4 · DESIGN.md

已改：§3 思考正文 13px 写成显式例外；§5 Message 正文 16px → 17px（≤767px 时 16px，与 `globals.css` 一致）、Motion 改为"只有 GSAP 一份 160ms、结算不重放"、新增「Streaming states」七态表（含 failed 不用消息内红字、pacing 公式、reduced-motion 行为、校正只差不显示思考正文）；§6 表新增 Thinking collapse 180ms / Timeline label swap 120ms / Text reveal；§9 等待表把时间线 live 步写成两面共用，注明 live 标记只有 `InlineSpinner`、orb 已移除。

随任务 3 已改：§4 阅读宽度写明两面同 900px；§5 Input and composer 加「One composer」条；§5 新增「Jump to latest」条目；§7 写明 `--shadow-soft` 的实际归属（叙事卡、会话内 composer 字段、starter 主题卡 focus、auth 模式 tab）与「浮动控件一律 `--shadow-elevated`、不得用工具类阴影」。

## 被触碰的既有断言（红线 3，每处源码上方均有原值与错因注释）

| 文件 | 原断言 | 现在 | 理由 |
| --- | --- | --- | --- |
| `tests/home-streaming-render-split.test.ts` | `split.streamingRowRenders === tokens.length` | `≤ tokens.length && ≥ 1`，另加按帧驱动的新用例 | 原值是"每 token 一次提交"的现状快照（BUG-473） |
| `tests/chat-bundle-splitting-contract.test.ts` | `duration: 0\.18` | `0\.16` | DESIGN.md §6 160ms，0.18 是 GSAP 副本漂移（BUG-474） |
| `tests/session-conversation-layout.test.ts` | `duration:\s*0\.18` | `0\.16` | 同上 |
| `tests/class-name-definition-contract.test.ts` | `knownUnstyled` 含 `consultation-run-timeline__summary`、`consultation-step-tree` | 两条移除 | 前者现在有样式（按钮），后者类名已随组件删除；该测试本身要求列表无过期项 |
| `tests/chat-bundle-splitting-contract.test.ts` | "the thinking orb loads on demand…"（`OrbState` 导入、`dynamic(...)`、20px 占位、`prefetchOnIdle(importThinkingOrb)`） | 改为"live 标记是共享 InlineSpinner，无 orb chunk" | orb 是第二种 live 标记且被 14px 裁切（BUG-476） |
| `tests/chat-stream-layout.test.ts` | `reportSource`/`treeSource` 读取；`<ThinkingOrb … size={20}`；`ConsultationThinkingReport`、`hasTrace`、`activityTrace={message.activityTrace}`、`activityTrace ?? []`、`function TraceStep`、`.agent-thinking-step.is-think:has(...)`、report/tree 内容锁、`consultation-step-tree__*` CSS 锁、`.consultation-thinking-report .message-thinking` | 改为锁"只剩一条路径"（`doesNotMatch` 这些符号）+ `InlineSpinner size={12}` | 锁的正是被删除的第二/第三条思考渲染路径（BUG-476） |
| `tests/rectification-agentic-entry.test.ts` | 读取 `completed-activity-receipt.tsx` 并锁其 `<details>`/不 open/「本轮完成 · N 个步骤」；`activityStatus /activityTrace/` | 改为锁 `chat /rectificationTimelineRows/`、`chat /completedReceipt/`、`activityStatus` 不含 `activityTrace` | 锁的是校正专属第二折叠块与 trace 面板（BUG-476） |
| `tests/rectification-activity-receipt.test.ts` | `deltaBranch` 内 `state: raw.trim() ? "streaming" : "thinking"`、`text: raw,`；`message.state === "settled" && message.failed` | 状态派生改锁 frame flush 段（`state: text.trim() ? …`、`text,`、`frames.setAnswer(raw)`）；失败行改锁 `&& !message.failed` 且无 `rectification-activity-failure` | 前者锁的是每 chunk 一次 setMessages（BUG-473），后者锁的是校正专属红字失败行（BUG-476）。**注**：这个文件在任务 0 的聚焦跑里漏跑了，任务 2 跑全量前才发现，改在 `cc17d971` |

**任务 3 触碰的断言**（同样每处有原值与错因注释）：

| 文件 | 原断言 | 现在 | 理由 |
| --- | --- | --- | --- |
| `tests/character-remaining-contract.test.ts` | `aria-describedby={showRemaining ? composerRemainingId : undefined}` | `remainingId = composerRemainingId` 默认 + `aria-describedby={showRemaining ? remainingId : undefined}` | composer 现为两面共用，校正传自己的计数 id（BUG-477） |
| `tests/composer-isolation-contract.test.ts` | `const draft = useComposerDraft()` | `const storeDraft = useComposerDraft(); const draft = value ?? storeDraft;` + 校正传 `value={draft}` 且不 import `composer-draft` | 受控 `value` 是任务书要求，隔离性质加强而非减弱（BUG-477） |
| `tests/chat-navigation-a11y-contract.test.ts` | 内联按钮的 `min-h-11` / `focus-visible:ring-3` / `pointer-events-auto` / `<ArrowDown … className="size-4"` | 页面锁 `<JumpToLatestButton onClick={conversationAnchor.anchorToLatest} />`，语义改锁组件源码 + `.jump-to-latest__button` 的 44px / focus-visible / pointer-events | 锁的是内联 Tailwind 按钮本身（BUG-478） |
| `tests/chat-notice-and-scroll-contract.test.ts` | 三处：page effect 内 `anchored` 守卫先于 `container.scrollTo`；jump control 的 Tailwind 类；`absolute inset-x-0 bottom-full` | follow 在 hook 内、`anchoredRef` 守卫先于 `scrollTop` 赋值、`page.tsx` 无 `scrollTo`、`ResizeObserver`/`MutationObserver` 存在；按钮改锁组件与 CSS；定位改锁 `.jump-to-latest { position: absolute; bottom: 100% }` | 锁的是每 token 一次 `scrollTo` 的 effect 与内联按钮（BUG-478） |
| `tests/chat-stream-layout.test.ts` | composerWrap 含 `pointer-events-none absolute inset-x-0 bottom-full` | 含 `<JumpToLatestButton` + CSS 锁 | 同上 |
| `tests/starter-questions.test.ts` | page effect 以 `if (starterHomeVisible) return` 开头并调 `scrollTo` | hook 调用第二参含 `!starterHomeVisible`，follow effect `if (!active \|\| !element) return` 先于赋值，page 无 `scrollTo` | 性质（starter home 不自动滚）由 `active` 承担（BUG-478）。这条在任务 3 第一次全量跑才暴露，改在最后的 docs commit |
| `tests/rectification-agentic-entry.test.ts` | 整段校正专属跟随锁（`followTailRef`、`isNearBottom`、`shouldShowJumpToLatest`、`choiceCardsOpen`、`回到最新`、`.rectification-jump-latest`）；`className="composer-stop"`、`aria-label="停止回答"`；`<form className="composer"` | 锁 `useConversationScrollAnchor(conversation, true, caseId)`、`<JumpToLatestButton …>`、这些符号不再出现、`.jump-to-latest` 居中；`stopLabel="停止回答"`、`onStop={stopRun}`、`composer-stop` 在 `chat-composer.tsx`；`<ChatComposer` + `RECTIFICATION_COMPOSER_MAX_LENGTH = 500` + `<CharacterRemaining` | 锁的是第二套滚动与第二个输入框（BUG-477/476） |
| `tests/rectification-answer-choice.test.ts` | import `rectification-sticky-scroll` 并断言 `isNearBottom`/`shouldFollowLatest`/`shouldShowJumpToLatest`（含 360px 选择卡带宽）；`回到最新`、`followTailRef.current` | import hook 的 `conversationAnchorThreshold`/`nextAnchorState`，断言 96px 与同一组距离判定；锁 `<JumpToLatestButton …>` 与 `conversationAnchor.anchored` | 模块已删除（BUG-478） |

新增测试：`tests/stream-frame-buffer.test.ts`（7）、`tests/chat-markdown-split.test.ts`（4）、`tests/chat-stream-settle-contract.test.ts`（4）、`tests/rectification-timeline-adapter.test.ts`（6）、`home-streaming-render-split` +1。

## 命令输出

`./node_modules/.bin/tsc --noEmit` → **0**（任务 0/1/2 各一次；rebase 后一次；任务 3 后一次，均无诊断）。

`./node_modules/.bin/eslint` 触及文件 → **0 error**。warning 只落在 `page.tsx`（43 条，与 `origin/staging` 同文件同数）与 `use-consultation-run.ts`（9 条既有 `no-unused-vars`，本轮只加一行 import）；本轮新建的六个文件 0 warning。

`./node_modules/.bin/tsx --test tests/*.test.ts`（基线在干净的 `origin/staging` @ `058e5db9` 独立 worktree 里 `npm ci` 后跑）：

| | 旧基线 `fbb80fa3` | 基线 `058e5db9` | 任务 3 后（`058e5db9` 上） | 最终（rebase 到 `1a3e14e7` 后，HEAD 树） |
| --- | ---: | ---: | ---: | ---: |
| tests | 2460 | 2461 | 2482 | 2484 |
| pass | 2426 | 2427 | 2448 | 2450 |
| fail | 24 | 24 | 24 | 24 |
| skipped | 10 | 10 | 10 | 10 |

`1a3e14e7` 本身只改了校正类测试文件（+2 用例），没有另跑一份干净基线；最终列的 24 条失败清单与 `058e5db9` 基线逐条比对差集为空，仍是同一组环境缺口。

24 条失败与新基线逐条比对**完全同一集合**（`comm` 差集为空）：全部是本机无 Docker / PostgreSQL / 部署夹具的数据库、Better Auth、staging workflow YAML、live sync 类（admin code functions、Owner recovery、local PostgreSQL、redeem security、personal report job/sections RLS、migration runner、v9 migration 等）。10 条 skipped 同基线。无产品逻辑新增失败。任务 3 第一次全量跑曾多出 1 条 `starter-questions` 的源码锁失败，按红线 3 改锁 hook 后（见上表）复跑归零。

rebase 后、任务 3 前的聚焦 14 套件 117/117；任务 3 后的聚焦 17 套件 177/177。

`./node_modules/.bin/next build` → **0**。`✓ Compiled successfully in 22.6s`、`Finished TypeScript in 28.4s`、`Generating static pages (62/62)`，`/` 仍是 `○ (Static)`。5 条既有 `skill-package-registry.ts` filesystem-tracing warning，未失败。

## 未做与原因

见 `BLOCKED.md` 顶部：任务 3 已解除并完成；仍未做的是浏览器级手工验收（Performance 录制、结算录屏、两面并排截图、流式期间折叠、两面滚动跟随实机）——无登录态无 Chrome；`latestEntryMounts` 探针无 DOM 测试库不可驱动。