docs: 固化 Workbench 前端无破坏性投影权
This commit is contained in:
Codex
@@ -77,6 +77,7 @@ Web工作台负责 HWLAB 登录后的浏览器主入口，使用户能够在同
|
||||
| Workbench Server State | Web 工作台从 REST snapshot、SSE event、trace page 和 submit optimistic 归一化得到的服务端事实缓存。 |
|
||||
| Timeline Projection | 只从 messages、parts、turn status 和 trace events 派生用户可见 timeline row 的渲染投影，不发请求也不写事实状态。 |
|
||||
| 唯一投影 | [PJ2026-0104010803 Workbench唯一投影](PJ2026-0104010803-workbench-unique-projection.md) 定义的状态链路：AgentRun 执行事实只经 HWLAB projection writer/finalizer 写入 durable Workbench facts，REST、SSE、CLI、fake-server 和 Web 前端只消费该投影。 |
|
||||
| 破坏性投影权 | 删除 session、清空 active session、清空当前消息页、把 composer 改为无 session 或把 session lifecycle 改写为 not-found/archived/deleted 的权力。Web 前端 reducer、selectors、route hydrate、GET/list/detail/messages/SSE consumer 和测试 helper 没有破坏性投影权；只有显式用户 mutation 成功或后端 canonical lifecycle projection 可以改变这些事实。 |
|
||||
| 读侧推理 | Web、API、CLI、fake-server 或测试根据 trace tail、message text、tool event、result cache、session summary、list row、workspace snapshot、localStorage 或 elapsed timeout 推断 lifecycle、terminal、running 或 final response 的行为；Web工作台禁止该模式。 |
|
||||
| 0repair | Web 工作台在首次进入、刷新、deep link、session 切换、SSE 重连和 trace 补洞时必须按同一 authority 自然收敛；不得通过 reload、切走再切回、`sessionRepair`、`realignFreshSession`、workspace selection repair、active tab repair、GET read-through、localStorage truth 或测试 helper 自动点击，把已经分裂的 route/session/message/trace 状态补成看起来正确。 |
|
||||
| 初发刷新一致性 | 同一 prompt 在初次发送、切换 session 后回到该 session、刷新页面和 SSE 重连后，都以同一 userMessageId、assistantMessageId、turnId 和 traceId 还原同一语义结果。 |
|
||||
@@ -242,6 +243,8 @@ Web工作台必须使用显式 Agent session：无 session 时先让用户创建
|
||||
|
||||
active session 只能由路由中的 sessionId 或用户显式选择产生。REST detail、session list、workspace summary、SSE event、trace page 或 turn snapshot 晚到时，只能更新其声明 `sessionId` 对应的 server-state bucket；不得重新选择 session、替换 URL、覆盖当前消息区、改变 composer 或把另一个 session 的 running/terminal 状态投射到当前页面。若 `routeSessionId`、`activeSessionId`、`activeConversationId`、message session 或 trace session 不一致，Web 必须暴露 authority mismatch/blocker 并让测试失败；不得通过 `sessionRepair`、`realignFreshSession`、reload、切走再切回或测试 helper 自动点击修正后判通过。
|
||||
|
||||
显式新建 session、用户点击 session 标签和用户确认删除 session 是 active selection 与 lifecycle 变化的 mutation authority。`POST /v1/agent/sessions` 或等价 create mutation 返回成功后，Web 必须立即把返回的 sessionId 作为当前 active session 投影到 URL、session tab、当前消息区和 composer；后续 `GET /v1/workbench/sessions`、session detail、messages、SSE、route hydrate 或 list refresh 的失败、404、空列表、网络瞬断、迟到响应和投影滞后，都不能删除该 session、清空 active selection、清空当前消息页、把 composer 变成 `session_required`，也不能把“无法读取详情”解释成该 session 不存在。deleted、archived、not-found 只能来自后端 canonical lifecycle projection，或来自用户显式 DELETE mutation 成功后的前端展示更新；前端读侧不得自己拥有破坏 projection 的权力。
|
||||
|
||||
用户切换 session 标签、通过深链进入 session 或从其他 session 切回时，若当前主工作区的 session detail/message page 尚未返回并应用，Web 工作台必须在主任务区显示明确的加载中转圈或等价 loading state。该状态表示已有会话正在加载，不等同于 Code Agent 已经加载完但尚未产生第一条可读消息的“思考中...”。Web 不得在主工作区尚未就绪时显示空对话、空 Code Agent 卡片、空 Trace 面板或静默留白，使用户无法判断切换是否生效。
|
||||
|
||||
当前 selected session 若需要出现在列表中，必须由 session list API 在显式 `includeSessionId` 或等价稳定业务 id 参数下返回，不得由后端隐藏读取 Web workspace selected 状态实现。Workspace API 只提供工作台选择、composer 配置和稳定业务 id，不作为 session 消息本体 authority；列表 API 只提供 rail 排序和摘要，不作为当前消息面板 authority。Web 只能把 route、用户显式选择或后端返回的稳定 session/turn/trace id 作为权威 API 的显式参数，不得把前端拼接出的 status、final response、markdown、running 动效或 stub 传回后端变成事实。Web 在权威 API 失败时只能保留上一份成功结果或显示未加载/错误态，不得从 workspace selected snapshot、stub 或本地缓存拼出单条 session tab、running 状态或 final response。运行中的 turn 必须同时反映在主任务区和对应 session tab；已进入终态的 turn 不得继续以 `Code Agent 处理中`、running 动效或旧 snapshot 文案呈现。
|
||||
@@ -328,6 +331,8 @@ Timeline Projection 只能从 messages、parts、turn status 和 trace events
|
||||
|
||||
Web 工作台严禁读侧推理。`turn.status`、`message.status`、`session.running`、`trace terminal`、`finalResponse` 和 `projectionStatus` 只能来自唯一 durable projection。Trace event row 的 `completed` 只表示该事件或工具行完成，不能终结 turn；message text 为空只表示无可展示正文，不能生成占位 final response；session list summary、workspace selected state、localStorage mirror、轮询耗时或 elapsed timeout 不能改写 running/terminal。若 API 返回缺字段、投影滞后或多字段矛盾，Web 只能展示 loading、degraded、unknown 或 blocker，并把问题暴露给投影层修复，不得在 reducer、selector、组件或测试 helper 中合成“看起来正确”的状态。
|
||||
|
||||
Web reducer/selectors 必须同时遵守无破坏性投影权。读侧路径中的 `forgetSession`、`replaceActiveSessionSelection(null)`、清空 messages、清空 tabs、把 composer 降级为 `session_required` 或把 route session 标记为 not-found/archived/deleted，都是 lifecycle mutation，不能由 GET/list/detail/messages/SSE 失败、空响应、404、route hydrate、refreshSessions 或 late response 触发。读侧只能把目标 session 的 loading、degraded、unknown、blocker 或 canonical lifecycle projection 展示出来；若需要删除、归档或失活，必须走后端 lifecycle projection 或用户显式 mutation 的成功结果。
|
||||
|
||||
初发刷新一致性是 Web 工作台的硬约束：同一 prompt 从 admission 开始生成稳定 userMessageId、assistantMessageId、turnId 和 traceId；初发 UI 可以 optimistic 展示这些 ID，但刷新、切换 session、SSE 重连和 REST 补洞必须用同 ID 的 durable message、part、turn 和 trace projection 确认。若 trace events 缺失，只影响 trace detail；主 timeline 的用户消息、assistant final response 和 turn terminal 状态不得因此退化为“思考中”。
|
||||
|
||||
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 共同竞争当前消息面板。
|
||||
@@ -360,6 +365,8 @@ mock 数据应优先来自目标 node/lane 的真实受控样本，而不是从
|
||||
|
||||
浏览器回归验证至少覆盖以下用户可见路径：切换 session 后主工作区显示 loading 并恢复目标 session；fresh browser context 深链进入 session 后以同一 message、turn 和 trace 标识还原 timeline；SSE 事件丢失或重连后通过 REST snapshot 和 trace page 补洞；session 标签、workspace card、message card、composer 主按钮和 Trace 终态显示 running、completed、failed、canceled 等状态时保持一致；Trace 阅读视图按事件顺序渲染可读 row，正确处理分页、终态、失败、自动展开和终态折叠；深链进入 session 与普通点击 session 走同一 authority path，删除或归档 session 后 deep link 不得复活 archived active tab。
|
||||
|
||||
状态投影回归必须覆盖新建 session 后读侧失败的负向用例：用户显式 create mutation 成功并进入新 session 后，即使随后的 session detail、messages、list refresh、SSE 或 route hydrate 返回失败、404、空列表或网络错误，URL、active tab、当前消息区和 composer 仍归属新 session；页面可以展示该 session 的 loading/degraded/blocker，但不得回退到旧 session、清空 active selection、清空 tabs/messages 或显示 `session_required`。这类用例必须作为 fake-server Playwright 红灯保留，线上 web-probe 只做同一 public origin 的原入口验收，不用 repair helper 修正页面后判通过。
|
||||
|
||||
测试实现应优先使用用户可见文本、ARIA role 和稳定 DOM 标识断言，不通过内部 store、localStorage 或后端数据库直接判定通过。失败时必须保留 Playwright screenshot、trace 或等价 artifact；关键路径可以生成命名截图用于人工审阅。远程执行默认在目标 node/lane 上通过 UniDesk Playwright route 运行，截图和报告应回传到调用端，但这些 artifact 只是验证证据，不进入业务事实或监控指标。
|
||||
|
||||
## 7. 过程控制
|
||||
|
||||
Reference in New Issue
Block a user