From 54908caea8d9c2b0b1c10a3fa2f400ff28c9675f Mon Sep 17 00:00:00 2001
From: pikastech <liang6516@outlook.com>
Date: Tue, 21 Jul 2026 13:38:09 +0200
Subject: [PATCH] docs(web): record Workbench replay regression workflow

---
 .agents/skills/unidesk-webdev/SKILL.md |  8 ++++++
 docs/reference/hwlab.md                | 34 ++++++++++++++++++++++++++
 2 files changed, 42 insertions(+)

diff --git a/.agents/skills/unidesk-webdev/SKILL.md b/.agents/skills/unidesk-webdev/SKILL.md
index bb6c59ed..bbac766a 100644
--- a/.agents/skills/unidesk-webdev/SKILL.md
+++ b/.agents/skills/unidesk-webdev/SKILL.md
@@ -130,6 +130,10 @@ description: UniDesk Web 开发与受控浏览器验证技能。用户提到 Web
   - 不把 WebProbe 的硬编码 DOM selector、长等待、临时 Playwright 脚本或探针自身超时作为 Workbench 业务终态的唯一门禁；探针异常时保留其作为工具证据，并以 CLI 终态和截图继续归因；
   - CLI 必须走同一产品 dispatcher 和身份语义，禁止以 direct manager、snapshot、result polling 或其他第二业务路径替代。
   - 一次性截图默认按 `domcontentloaded` 导航，持续 SSE 页面不得改用 `networkidle`；完整边界见 [references/web-probe.md](references/web-probe.md)。
+  - 流式 Conversation/Trace 贴底问题按 `docs/reference/hwlab.md#workbench-浏览器回归专项` 执行：
+    - 先用 L0 证明内容增长不误关 following；
+    - 再用真实长回复或 retention 回放做 L1；
+    - API readiness 若被 Kafka session index 维护阻塞，停止前端与浏览器重试并转独立架构 issue。
 - Native 阶段采用短反馈循环：
   - 修改后先执行最小语法检查和目标功能验证；
   - 使用 `web-probe` 从 YAML 选择的固定 HTTPS 或公网 HTTP 入口验证真实 DOM、交互、布局和截图；custom/local 仅记录为 preflight，不能宣称 L1 通过；
@@ -202,6 +206,10 @@ description: UniDesk Web 开发与受控浏览器验证技能。用户提到 Web
   - `tool_call`/`command_output` 与 HWLAB `tool`/`status` 是条件事件对，仅在实际出现时校验数量和 lineage；
   - 直接答复不得为了通过探针而合成工具事件，超时证据必须披露已经观测和仍然缺失的事件族；
   - refresh 启用时必须证明 retention 到 live handoff、正式 `user` event、`hwlab.event.v1` 同 envelope，以及主页面单一 EventSource 和同一 UI reducer 终态；
+  - 已有 session 的 rail、turn card、Final Response 或回放提示不一致时：
+    - 先执行一次 `workbench events inspect --over-api` 证明服务端 connected、核心事件族和 terminal；
+    - 服务端完整后只执行一次 `validateExistingSessionRefresh` 核对 DOM identity、live handoff 与 forbidden request；
+    - 若刷新后消息渐进恢复但分钟级不收敛，先按 `docs/reference/hwlab.md#workbench-浏览器回归专项` 检查后台标签页调度，不重复扫描 Kafka 或增加恢复路径；
   - 禁止用“陈旧快照不得覆盖 sealed final”一类优先级或封口 guard 处理刷新：
     - 该模型仍保留多个业务写入路径及竞争仲裁；
     - 必须删除 HTTP snapshot、submit response、result fallback 等业务状态写入；
diff --git a/docs/reference/hwlab.md b/docs/reference/hwlab.md
index 324e92d0..5c840e72 100644
--- a/docs/reference/hwlab.md
+++ b/docs/reference/hwlab.md
@@ -265,6 +265,40 @@ Workbench 浏览器回归需求以 UniDesk OA [PJ2026-010401 Web工作台](../..
     - `kafkaRefreshReplay=true` 时要求 `deliverySemantics=kafka-retention-then-live`、`replay=true`、`liveOnly=false`；
     - capability 已启用但仍返回 `live-only` 时，优先定位 L1 native API 是否仍保留独立 live-only SSE adapter；
     - 此时 retention 查询尚未开始，不得先归因 Kafka 扫描超时或历史事件缺失；
+  - 已有 session 出现 rail、turn card、Final Response 或回放提示不一致时，最短分层固定为：
+    - 先用 `hwlab-cli workbench events inspect --over-api` 检查同一 session/trace 的 connected contract、核心事件族和 terminal；
+    - 服务端完整时，只执行一次 `web-probe observe command <observer> --type validateExistingSessionRefresh --profile <yaml-profile> --session-id <session>`，核对刷新前后 DOM identity、业务帧数、live handoff 和 forbidden request 数；
+    - 禁止先扫描大型 artifact、重复重启 L1、增加 snapshot/polling，或用 session rail 的相对时间推测运行耗时；
+  - Kafka retention 回放队列必须在后台标签页继续推进：
+    - 禁止用 `requestAnimationFrame` 作为 SSE ingress/reducer 分批处理的唯一调度源，因为后台标签页降频会把有限回放放大成分钟级状态分裂；
+    - 零延迟合作式调度使用不依赖绘制帧的任务队列，并保留有界 chunk、事件顺序、稳定 event identity 去重和同一 reducer；
+    - L0 必须模拟 rAF 不回调，批量送入 retention 业务帧和最后的 `workbench.connected`，并在有界时间内证明全部帧按序排空；
+    - 该规则只修正客户端调度，不允许引入第二投影、REST 补洞、sealed guard 或终态仲裁；
+  - Conversation 与 Trace 等流式容器的贴底状态必须区分内容增长和用户滚动：
+    - 退出 following：
+      - 只有 `scrollTop` 实际向上移动才能退出；
+      - 内容先增长、贴底帧尚未执行时出现的临时 bottom distance 不得关闭 following；
+    - 程序性贴底：
+      - 释放后若内容继续增长，仍处于 following 时补一次合并对齐；
+      - 恢复 session 历史位置后必须按恢复位置显式同步 following；
+    - 观察器：
+      - `MutationObserver` 可以响应字符与子树变化来调度贴底；
+      - 只在滚动容器直属子节点集合变化时重建 `ResizeObserver` 目标；
+      - 禁止每个流式字符都 disconnect、遍历并重新 observe；
+    - L0 至少覆盖：
+      - 高度先增长但 `scrollTop` 未下降时仍保持 following；
+      - 用户真实上滚后暂停，回到底部后恢复；
+    - L1 使用真实长回复或 retention 回放：
+      - 检查最终内容、终态和 Composer 同时可见；
+    - 外层 Conversation 与内层 Trace 必须复用同一贴底状态机，禁止分别维护阈值、竞态修复或轮询补偿；
+  - API readiness 连续超时而进程仍存活时，先读取受控 API 日志：
+    - 若周期性 Kafka session index 全量重建与超时窗口重合：
+      - 归类为后端事件循环或索引维护问题；
+      - 不得继续重试 WebProbe、GC、前端贴底修复或浏览器刷新；
+    - 若涉及索引维护策略、增量更新或执行隔离：
+      - 必须进入独立架构 issue；
+      - 前端任务只保留已完成的 L0 和浏览器证据；
+      - 明确最新 patch 后尚未覆盖的 L1 边界；
   - 通过条件是 `connected=true`、`missingSemantics=[]` 且 `terminalStatuses` 出现明确终态；
   - `eventCount` 和 `--min-events` 不能证明 assistant、terminal 或 final，不得通过反复猜事件数量重开 inspect；
   - 业务交互优先使用项目正式 CLI 的 `--over-api` 完成 session/turn 与产品 SSE 终态对账，并保留精确 sessionId、traceId；