docs: add Workbench browser regression spec
This commit is contained in:
Codex
@@ -43,6 +43,7 @@ Web工作台负责 HWLAB 登录后的浏览器主入口，使用户能够在同
|
||||
- 桌面多栏布局、侧栏折叠、移动端工作台布局和输入区可达性。
|
||||
- Web 与 HWLAB CLI 共用的 Code Agent composer policy、trace renderer 和同源 API 行为。
|
||||
- Web 入口对用户管理、Agent编排、硬件池、HarnessRL 和平台运维输出事实的展示契约。
|
||||
- Workbench 浏览器回归验证，包括基于真实采集脱敏 fixture 的 Playwright 独立测试、mock server 重放、状态投影断言和截图 artifact。
|
||||
|
||||
### 2.3 范围外
|
||||
|
||||
@@ -74,6 +75,8 @@ Web工作台负责 HWLAB 登录后的浏览器主入口，使用户能够在同
|
||||
| Workbench Server State | Web 工作台从 REST snapshot、SSE event、trace page 和 submit optimistic 归一化得到的服务端事实缓存。 |
|
||||
| Timeline Projection | 只从 messages、parts、turn status 和 trace events 派生用户可见 timeline row 的渲染投影，不发请求也不写事实状态。 |
|
||||
| 初发刷新一致性 | 同一 prompt 在初次发送、切换 session 后回到该 session、刷新页面和 SSE 重连后，都以同一 userMessageId、assistantMessageId、turnId 和 traceId 还原同一语义结果。 |
|
||||
| 浏览器回归验证 | 使用 Playwright 在真实浏览器中验证 Workbench 用户可见行为、状态投影和 Trace 阅读正确性的前端端到端单元测试；测试过程使用本地 mock server，不依赖实时 Cloud API、AgentRun、HWPOD 或其他运行组件。 |
|
||||
| 真实采集 fixture | 从目标 node/lane 的受控样本采集 Workbench REST、SSE、conversation、session、turn 和 trace 响应，经稳定伪 ID 映射与敏感字段脱敏后，用于浏览器回归验证的数据集。 |
|
||||
|
||||
## 4. 系统边界和接口
|
||||
|
||||
@@ -101,6 +104,7 @@ Web工作台负责 HWLAB 登录后的浏览器主入口，使用户能够在同
|
||||
| PJ2026-01040107 | 公开入口 | 本规格 6.7 | 正式 Cloud Web public URL、history fallback 和旧入口降级边界 | 平台运维、API契约、用户管理 | 用户访问、Playwright 验收、内测说明 |
|
||||
| PJ2026-01040108 | 状态投影 | 本规格 6.8 | server-state、reducer、selectors、timeline projection 和初发刷新一致性 | API契约、Agent编排 | Web timeline、session rail、trace detail |
|
||||
| PJ2026-01040109 | 前端模块 | 本规格 6.9 | API client、event client、server-state、UI state 和组件职责拆分 | API契约、公开入口 | 可维护前端实现 |
|
||||
| PJ2026-01040110 | 浏览器回归 | 本规格 6.10 | Playwright 独立测试、真实采集 fixture、mock server、截图 artifact 和状态投影断言 | API契约、平台运维 | Workbench 功能回归、防止刷新和会话切换退化 |
|
||||
|
||||
### 5.1 目标数据流程图
|
||||
|
||||
@@ -167,6 +171,34 @@ flowchart LR
|
||||
|
||||
Cloud Web 只拥有浏览器交互和投影；Cloud API 拥有 REST/SSE 合同和 read model；Agent编排和 HWLAB接入拥有执行事实映射；公开入口只负责将 Web/API/health 投递到目标 node/lane。
|
||||
|
||||
### 5.3 浏览器回归验证数据流图
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
subgraph Capture[受控真实采集]
|
||||
LIVE[D601 v0.3 Workbench REST/SSE]
|
||||
REDACT[脱敏与稳定伪 ID 映射]
|
||||
FIX[real-captures fixtures]
|
||||
LIVE --> REDACT
|
||||
REDACT --> FIX
|
||||
end
|
||||
subgraph Test[独立浏览器回归]
|
||||
MOCK[local mock server]
|
||||
WEB[Cloud Web build/preview]
|
||||
PW[Playwright browser]
|
||||
ASSERT[用户可见断言]
|
||||
ART[截图和 trace artifact]
|
||||
FIX --> MOCK
|
||||
MOCK --> WEB
|
||||
PW --> WEB
|
||||
PW --> ASSERT
|
||||
PW --> ART
|
||||
end
|
||||
OPS[D601 remote Playwright route] --> PW
|
||||
```
|
||||
|
||||
浏览器回归验证的数据流必须保证：fixture 优先来自目标 node/lane 的真实受控样本；脱敏后保留 conversationId、sessionId、turnId、traceId、messageId 和 sourceSeq 之间的关系；mock server 只重放和变形这些事实，不成为新的业务事实来源；D601 远程 Playwright route 只负责执行与截图 artifact 回传，功能正确性仍由 Web工作台规格定义。
|
||||
|
||||
## 6. 原子需求
|
||||
|
||||
### 6.1 CLIENT-WB-REQ-001 工作台框架
|
||||
@@ -277,6 +309,8 @@ Timeline Projection 只能从 messages、parts、turn status 和 trace events
|
||||
|
||||
OpenCode 的参照边界是职责结构，不是技术栈照搬。可借鉴的边界包括 route/sessionKey 作为当前 session authority、per-session message/part cache、REST message page 与 optimistic message 通过同一 messageID 合并、SSE delta 只作为实时加速、完整 message/part snapshot 可重建刷新结果。HWLAB 不得继续让 workspace snapshot、trace polling、result polling、list summary 和 localStorage 共同竞争当前消息面板。
|
||||
|
||||
状态投影正确性必须能被独立浏览器回归验证覆盖。测试应在同一 Web 构建产物上使用 mock server 重放真实采集 fixture，断言 session rail、主 timeline、workspace card、composer、message card 和 trace detail 在 session 切换、刷新页面、SSE 断线重连、REST 补洞和 trace 分页补拉后保持同一组 conversationId、sessionId、turnId、traceId、messageId 与终态语义。测试不得依赖 live AgentRun、Cloud API、HWPOD、数据库或 Kubernetes 状态作为通过条件。
|
||||
|
||||
### 6.9 CLIENT-WB-REQ-009 前端模块
|
||||
|
||||
| 编号 | 短名 | 主责模块 | 关联模块 |
|
||||
@@ -287,6 +321,22 @@ Web 工作台实现应按职能拆分为 API client、event/SSE client、server-
|
||||
|
||||
新增或重构的核心前端文件头部必须标注遵循的 SPEC 编号、短名和实现引用版本，例如 `SPEC: PJ2026-010401 Web工作台 draft-2026-06-17-r0; PJ2026-010403 API契约 draft-2026-06-17-r0`，并简述文件职责。实现文件不得只写 issue 编号、`latest` 或 `current` 作为规格引用。
|
||||
|
||||
### 6.10 CLIENT-WB-REQ-010 浏览器回归
|
||||
|
||||
| 编号 | 短名 | 主责模块 | 关联模块 |
|
||||
| --- | --- | --- | --- |
|
||||
| CLIENT-WB-REQ-010 | 浏览器回归 | PJ2026-01040110 浏览器回归 | [PJ2026-010403 API契约](PJ2026-010403-api-contract.md)、[平台运维](PJ2026-0106-platform-ops.md) |
|
||||
|
||||
Web 工作台应建立可独立运行的 Playwright 浏览器回归验证，用真实采集脱敏 fixture 和本地 mock server 驱动 Cloud Web 页面，验证 Workbench 用户可见功能正确性。该验证属于 Web 工作台完成标准：平台运维只提供目标 node/lane 上的远程 Playwright 执行、截图和 artifact 回传能力，不定义 session、message、trace 或状态投影的功能断言。
|
||||
|
||||
mock 数据应优先来自目标 node/lane 的真实受控样本，而不是从零手写理想数据。采集范围至少覆盖 workspace selection、conversation list、conversation detail、session/turn snapshot、trace event page 和 Workbench event stream；采集产物必须记录 `capturedFrom`、`capturedAt`、schema/redaction 版本和脱敏状态，并删除 API key、cookie、auth header、DSN、provider token、真实用户身份和非公开 prompt。脱敏应使用稳定伪 ID 映射，保留 conversation、session、thread、turn、trace、message 和 sourceSeq 之间的关系，使刷新和事件重放可以验证同一事实链路。
|
||||
|
||||
合成 fixture 只能补足真实样本难以稳定覆盖的边界条件，例如延迟响应、SSE 断线、分页缺口、列表缺少当前选中项、可选字段格式异常、空集合和特定 HTTP 错误。每个合成 fixture 必须标明 `derivedFrom` 和 `syntheticReason`，不得替代可从真实运行面采集的常规会话、完成态、失败态或 Trace 数据。
|
||||
|
||||
浏览器回归验证至少覆盖以下用户可见路径：切换 session 后主工作区显示 loading 并恢复目标 conversation；刷新页面后以同一 message、turn 和 trace 标识还原 timeline；SSE 事件丢失或重连后通过 REST snapshot 和 trace page 补洞；session 标签、workspace card、message card、composer 主按钮和 Trace 终态显示 running、completed、failed、canceled 等状态时保持一致；Trace 阅读视图按事件顺序渲染可读 row，正确处理分页、终态、失败、自动展开和终态折叠；深链进入 conversation 与普通点击 session 走同一 authority path。
|
||||
|
||||
测试实现应优先使用用户可见文本、ARIA role 和稳定 DOM 标识断言，不通过内部 store、localStorage 或后端数据库直接判定通过。失败时必须保留 Playwright screenshot、trace 或等价 artifact；关键路径可以生成命名截图用于人工审阅。远程执行默认在目标 node/lane 上通过 UniDesk Playwright route 运行，截图和报告应回传到调用端，但这些 artifact 只是验证证据，不进入业务事实或监控指标。
|
||||
|
||||
## 7. 过程控制
|
||||
|
||||
本规格不单独索引过程 issue；跨 L1 的内测、灰度和阶段活动索引统一保留在 [PJ2026-01 HWLAB 总规格](PJ2026-01-HWLAB.md) 的 `7. 过程控制`。
|
||||
|
||||
Reference in New Issue
Block a user