pikasTech-unidesk/project-management/PJ2026-01/specs/PJ2026-010401-web-workbench.md

PJ2026-010401 Web工作台

修改历史

版本	对应 commit id	更新日期	变更说明

当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 待提交 版本。

正文

PJ2026-010401 Web工作台需求规格

1. 文档控制

字段	内容
编号	PJ2026-010401
短名	Web工作台
层级	L2 课题
状态	已生效
实现引用版本	draft-2026-06-20-p0-long-running-workbench; draft-2026-06-20-p0-error-diagnostics; draft-2026-06-20-p0-passive-web-probe-observer; draft-2026-06-20-p1-view-local-timing-ticker; draft-2026-06-24-p0-no-ui-timing-fabrication; draft-2026-06-25-p0-web-caserun-e2e; draft-2026-06-25-p0-project-management-mdtodo; PJ2026-0104010803 唯一投影 draft-2026-06-20-p0-durable-facts-model; draft-2026-06-20-p1-zero-split-durable-realtime; draft-2026-06-20-p2-terminal-outbox-recovery; draft-2026-06-24-p0-aggregate-event-stream; draft-2026-06-25-p0-serve-session-aggregate-authority
需求规格模板	ISO/IEC/IEEE 29148 需求规格模板
上级规格	PJ2026-0104 客户端
规格治理索引	规格治理

本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留 Web 工作台的稳定使命、范围、术语、系统边界、内部分工和原子需求。

2. 目的和范围

2.1 目的

Web工作台负责 HWLAB 登录后的浏览器主入口，使用户能够在同一 Web 工作面完成会话选择、任务输入、执行状态理解、结果查看和必要诊断。

本课题的目标状态是：主任务入口优先、诊断信息低噪声、状态反馈及时、桌面和移动端都能直接找到输入区，并且用户可以从基本工作台发起最小 Agent 调用并获得可查询执行状态。Web 工作台与 HWLAB CLI 必须共用同源 API、composer policy 和 trace renderer 语义，使浏览器问题可以通过同一运行端点的 CLI 非视觉复现。

长程可靠 Workbench 是本课题的黄金用例：用户在同一 public origin 内新建或选择 session，发送 hi 或等价最小任务，等待真实 Agent turn 运行，看到主消息区 final response 和 Trace terminal，随后刷新页面、切换到其他 session、再回到原 session、多标签页打开同一 deep link，仍看到同一组 sessionId、turnId、traceId、messageId、sealed final response 和 trace page。主 timeline 不等待完整长 Trace 全量拉完；Trace detail、projection diagnostic、transport diagnostic 和性能指标只解释可见性，不拥有主消息 lifecycle 或 final response 写权。trace/timeline 顺序、完成行位置、terminal sealed duration 和 SSE replay 必须来自唯一投影的 aggregate event stream revision，不能由浏览器 arrival order、trace hydration 顺序、session list 刷新或 probe 后处理重排。

命令输入区的 prompt、steer、cancel 和 retry 都必须先成为唯一投影的 serve/session aggregate control command。Web 可以展示 optimistic placeholder，但不得从 DOM active card、session list、trace tail、localStorage 或 request timeout 推断 active turn、final response、running、duration 或 cancel 结果。

2.2 范围内

• 登录后 Cloud Web shell、topbar、导航、工作台路由、页面切换反馈和同源 API 状态展示。
• 会话列表、当前 session、用户消息、Agent 消息、命令输入区、发送、引导、取消、重试和 pending 状态展示。
• 基本工作台 Agent 调用，包括最小任务输入、发送、短返回执行标识、状态查询入口和失败原因展示。
• 工作台诊断入口、运行状态摘要、probe/build/HWPOD/Agent 状态的低噪声展示方式。
• CaseRun 用户入口，包括 HWPOD 资源选择、case 列表、run 提交、run stage、Trace、HWPOD evidence、artifact manifest、aggregate 和 blocker 展示。
• Workbench 公共 launch context 消费，包括从项目管理等外部登录后页面创建或选择 session，并把脱敏 projectId/taskRef 元数据写入 session projection。
• 桌面多栏布局、侧栏折叠、移动端工作台布局和输入区可达性。
• Web 与 HWLAB CLI 共用的 Code Agent composer policy、trace renderer 和同源 API 行为。
• Web 入口对用户管理、Agent编排、硬件池、HarnessRL 和平台运维输出事实的展示契约。
• Workbench 浏览器回归验证，包括基于真实采集脱敏 fixture 的 Playwright 独立测试、mock server 重放、状态投影断言和截图 artifact。

2.3 范围外

• 用户身份、角色、session、API key、额度和账本事实归 用户管理。
• Code Agent session、trace、workspace、provider profile 和执行生命周期事实归 Agent编排。
• HWPOD 资源、节点健康和硬件事实归 硬件池。
• CaseRun 评价、回放和训练反馈语义归 HarnessRL。
• 公开入口、CI/CD、GitOps、Secret、FRP、Caddy 和 runtime 健康归 平台运维。
• CLI 参数、CLI 输出和 HTTP API 契约仍归 PJ2026-0104 客户端 中对应 L2 课题。
• 项目管理根导航、MDTODO source、Markdown 解析、任务投影、ProjectWorkbenchLink 和外部 PM adapter 归 PJ2026-010404 项目管理。

3. 术语表

术语	定义
Web工作台	登录后用于提交任务、管理会话、查看结果和进入辅助诊断的 Cloud Web 主工作面。
主任务区	用户完成主要工作流的区域，包括会话消息和命令输入区。
命令输入区	用户输入新任务、引导运行中任务、取消或重试任务的 Web 控件集合。
诊断入口	用户主动打开的工作台状态详情入口，通常以 topbar 内的小型按钮或状态图标呈现。
低噪声展示	诊断、trace、状态和辅助信息不抢占主任务区，也不伪装成用户或 Agent 正文。
响应式工作台	同一工作台在桌面和移动端按不同可视空间重排，但仍优先保证任务输入和状态理解。
同源业务入口	Cloud Web 与 HWLAB CLI 通过同一 Web origin、相对 REST/JSON API path 和业务标识访问 HWLAB 能力的入口。
Web CaseRun 视图	Web 工作台或其相邻登录后页面中用于提交、观察和阅读 CaseRun 的用户界面。
CaseRun run 卡	展示一次 CaseRun 的 runId、caseId、hwpodId、stage、Trace、HWPOD evidence、artifact manifest、aggregate 和 blocker 的紧凑工作态组件。
WorkbenchLaunchContext	项目管理等外部页面传给公共 Workbench Launch API 的脱敏启动上下文，Workbench 只把它作为 session metadata 保存和展示，不反解外部任务来源。
ProjectTaskRef	项目管理 API 返回的 opaque taskRef；Workbench 可保存和显示其摘要，但不得解析 Markdown、文件路径或 adapter 内部结构。
selected Web origin	Web 工作台、CLI 和 web-probe 共同使用的 YAML-selected origin；默认 public，D601/v03 端到端验收可由 YAML 切换到 internal IP。
浏览器登录态	Cloud Web 随同源请求携带的 hwlab_session Web session transport；前端只负责传递，不解释权限、project 归属或资源可见性。
canonical identity	Web 工作台从 /auth/session 读取的最小身份结果，包含 actor、authMethod、identityAuthority、sessionKind 和 capability 摘要；它是 Web shell、导航和业务页面的唯一身份输入。
Session权威入口	Web 工作台按 sessionId 或后端认可的 opaque session handle 恢复当前会话消息、turn 摘要、trace 指针和状态的 RESTful detail API。
共享 trace renderer	Web trace 面板和 HWLAB CLI trace --render web 共用的 trace row 转换语义。
Trace阅读视图	工作台中面向用户阅读 Code Agent trace 的默认视图，只展示用户可理解的助手消息、工具调用、命令输出、最终结果和真实耗时，把运行身份、隐藏统计和原始事件收束到消息详情入口。
消息详情入口	Agent 消息头部右上角的小型详情按钮，用于按需查看 trace id、session、run、command、raw event、隐藏统计和审计控制等调试信息。
错误诊断块	用户可见错误下方的低噪声诊断信息，展示可复制 OTel trace_id、request id、route、错误 code 和脱敏时间戳；它不替代主错误文案，也不改写 Workbench 状态。
Trace Explorer 链接	根据运行配置中的 observability.traceExplorerUrlTemplate 生成的打开 trace backend 入口；只有模板存在且 trace_id 合法时显示，URL 只替换 {trace_id}。
Trace生命周期展开/折叠	Code Agent turn 进入运行态时，Web 自动展开对应 Trace阅读视图；turn 进入终态时，Web 自动折叠该 Trace阅读视图，但仍允许用户手动重新打开。
工作态高密度	面向持续排障、比较和重复操作的工业化界面密度要求：低圆角、低内边距、正文优先、辅助元信息折叠，避免装饰性卡片和大块留白抢占工作内容。
正式公开入口	目标 node/lane 在 YAML 中声明的 Cloud Web public URL，用作用户访问、Playwright 验收、文档说明和故障复现入口。
Workbench Server State	Web 工作台从 REST snapshot、SSE event、trace page 和 submit optimistic 归一化得到的服务端事实缓存。
Timeline Projection	只从 messages、parts、turn status 和 trace events 派生用户可见 timeline row 的渲染投影，不发请求也不写事实状态。
Aggregate event stream revision	PJ2026-0104010803 Workbench唯一投影 定义的 eventSeq、aggregateSeq 或等价 projection revision；Web reducer 只能用它判断新旧和补洞，不得用网络到达顺序或本地时间重排 terminal/final/timing。
显示层本地 now	浏览器组件为了展示“最近 X 秒前”和运行中“耗时 X 秒”而读取的当前时间；它只能作为直接渲染输入，不能写回 Server State、投影、session/message/turn lifecycle 或诊断事实，也不能通过平滑、滤波、单调 floor、跳变 cap 或二次缓存伪造一个更好看的时间事实。
唯一投影	PJ2026-0104010803 Workbench唯一投影 定义的状态链路：AgentRun 执行事实只经 HWLAB projection writer/finalizer 写入 durable Workbench facts，REST、SSE、CLI、fake-server 和 Web 前端只消费该投影。
Serve Session Aggregate Authority	PJ2026-0104010803 Workbench唯一投影 定义的会话级权威链路；Web 的 prompt、steer、cancel、retry、run-state、message/part、trace/timing 和 final response 只能消费该 aggregate read model。
sealed final response	唯一投影 terminal commit 写入的 assistant 主正文、finalResponse、message/turn terminal status 和 sealed 标记；它是主消息区用户结果的唯一权威，不被后续读侧诊断、trace hydration 失败、turn polling 失败或 SSE gap 覆盖。
破坏性投影权	删除 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 还原同一语义结果。
浏览器回归验证	使用 Playwright 在真实浏览器中验证 Workbench 用户可见行为、状态投影和 Trace 阅读正确性的前端端到端单元测试；测试过程使用本地 mock server，不依赖实时 Cloud API、AgentRun、HWPOD 或其他运行组件。
真实采集 fixture	从目标 node/lane 的受控样本采集 Workbench REST、SSE、conversation、session、turn 和 trace 响应，经稳定伪 ID 映射与敏感字段脱敏后，用于浏览器回归验证的数据集。
长程 Web Observer	在目标 node/lane 正式公开入口上启动真实浏览器并持续观测同一页面的客户端程序，用于发现长 Trace、session 切换、刷新恢复、滚动跟随和瞬态状态竞态。
纯客户端 web-probe	只作为本地或目标 host 上的浏览器客户端进程运行的 web-probe 形态；它没有入站 HTTP/WebSocket/gRPC API、监听端口、数据库、队列、平台服务身份或业务状态写权。
被动采样	采样器不主动调用 Workbench 业务 API、不 reload、不自动点击、不修复 session、不拦截或重放网络请求，只读取 DOM、浏览器性能条目、控制台、页面错误和页面自然产生的网络事件。
命令文件	trans 或受控 CLI 写入目标 host 文件系统的控制请求，例如登录、打开页面、发送 prompt、截图或停止；命令文件本身必须进入观测时间线。
页面权威	同一长程观测 job 中唯一拥有 Playwright browser/context/page 的客户端进程；控制循环和采样循环必须共享同一个 page 对象，页面重建必须记录连续性中断。
JSONL 采样流	长程观测产物使用追加式 .jsonl 文件保存，每行一条带时间戳、单调序号、来源和脱敏标记的采样记录，便于长时间写入、局部复制和后处理分析。

4. 系统边界和接口

本规格把 Web工作台作为客户端方向下的浏览器入口课题看待；本章只描述输入、输出和责任边界。

边界项	内容
外部使用者	硬件研发用户、平台管理员、需要通过浏览器提交或观察任务的操作人员。
外部输入	登录后访问请求、页面导航、会话选择、任务文本、引导/取消/重试操作、诊断查看操作和管理入口点击。
受控资源	Cloud Web shell、工作台路由、会话面板、对话面板、命令输入区、诊断弹窗、导航、响应式布局、composer policy 和共享 trace renderer。
外部输出	页面可见任务入口、会话状态、消息展示、命令反馈、诊断摘要、错误提示、可复制 OTel trace_id、可选 Trace Explorer 链接和可继续操作的 UI 状态。
用户接口	目标 node/lane 的正式公开入口、Cloud Web /workbench 及相关登录后页面。
系统边界	Web工作台负责浏览器入口的布局、交互和展示契约；不拥有账号、Agent、硬件、评价或发布事实，只消费这些模块的服务端输出并以一致、低噪声、可操作的方式呈现。

5. 内部分工与规格索引

编号	模块或课题	规格文档	主责边界	上游依赖	下游支撑
PJ2026-01040101	工作台框架	本规格 6.1	登录后 shell、topbar、导航、路由和页面切换反馈	用户管理、平台运维	用户主入口、管理入口
PJ2026-01040102	会话输入	本规格 6.2	会话选择、消息展示、命令输入和任务操作反馈	Agent编排、用户管理	用户任务提交和继续操作
PJ2026-01040103	诊断反馈	本规格 6.3	诊断入口、状态摘要和低噪声详情展示	Agent编排、硬件池、HarnessRL、平台运维	用户排障、管理员观察
PJ2026-01040104	响应布局	本规格 6.4	桌面多栏、侧栏折叠、移动端主任务区优先和输入区可达	全部工作台子模块	桌面和移动端用户
PJ2026-01040105	同源体验	本规格 6.5	Web 与 CLI 共享 composer policy、trace renderer 和同源 REST/JSON API 行为	HWLAB CLI、API契约、Agent编排	Web/CLI 排障和内测复现
PJ2026-01040106	Trace阅读	本规格 6.6	Code Agent trace 去噪、详情收纳、耗时、正文优先和单一主按钮状态	Agent编排、API契约、用户管理	用户排障和任务继续操作
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 功能回归、防止刷新和会话切换退化
PJ2026-01040111	长程观测	本规格 6.11	纯客户端 web-probe observer、命令文件控制、无副作用采样、JSONL artifact 和后处理分析	平台运维、公开入口	Workbench 长程稳定性、瞬态竞态复现
PJ2026-01040112	CaseRun入口	本规格 6.12	Web CaseRun 视图、run 卡、证据阅读、blocker 展示和 web-probe 同路径验收	HarnessRL、API契约、硬件池、Agent编排	用户端到端硬件验证
PJ2026-01040113	项目启动	本规格 6.13	公共 Workbench launch context 消费、session metadata 投影和项目任务解耦边界	项目管理、API契约、Agent编排	/projects/mdtodo 一键启动 Workbench

5.1 目标数据流程图

flowchart TD
  U[用户 prompt/steer/retry/cancel] --> C[Composer UI]
  C --> A[POST Turn Admission]
  A --> O[Optimistic user/assistant message IDs]
  A --> T[TurnSnapshot]
  A --> E[SSE /workbench/events]
  E --> R[Workbench Reducer]
  M[GET session messages] --> R
  TS[GET turn snapshot] --> R
  TE[GET trace events page] --> R
  O --> R
  R --> S[Workbench Server State]
  S --> P[Timeline Projection]
  S --> SR[Session Rail Projection]
  S --> TD[Trace Detail Projection]
  P --> UI[主 timeline]
  SR --> UI
  TD --> UI

目标数据流必须保证：提交请求只负责 admission 和稳定标识；实时事件、REST snapshot、trace pagination、页面刷新 hydrate 和 session-bound gap-fill 全部进入同一个 reducer；晚到响应只能更新其所属 session、turn 或 trace cache，不能改变当前 active session、active route、当前消息区或 composer。

5.2 目标架构图

flowchart LR
  subgraph Browser[Cloud Web]
    API[WorkbenchApiClient]
    EVT[WorkbenchEventClient]
    STATE[WorkbenchServerState]
    RED[WorkbenchReducer]
    SEL[Selectors/Projection]
    UI[Session Rail / Timeline / Composer / Trace Detail]
    API --> RED
    EVT --> RED
    RED --> STATE
    STATE --> SEL
    SEL --> UI
  end
  subgraph CloudAPI[HWLAB Cloud API]
    ROUTE[REST/SSE Routes]
    RM[Workbench Read Model]
    PROJ[Turn/Message/Trace Projection]
    ADAPT[AgentRun Adapter]
  end
  subgraph AgentRun[AgentRun]
    RUN[run/command/runner]
    EV[events/result]
  end
  UI --> API
  EVT --> ROUTE
  API --> ROUTE
  ROUTE --> RM
  ROUTE --> PROJ
  PROJ --> RM
  ADAPT --> PROJ
  RUN --> EV
  EV --> ADAPT

Cloud Web 只拥有浏览器交互和投影；Cloud API 拥有 REST/SSE 合同和 read model；Agent编排和 HWLAB接入拥有执行事实映射；公开入口只负责将 Web/API/health 投递到目标 node/lane。

5.3 浏览器回归验证数据流图

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工作台规格定义。

5.4 长程 web-probe observer 数据流图

flowchart LR
  subgraph Host[D601 或目标 node host]
    TRANS[trans 短连接控制]
    CMD[commands/*.json]
    OBS[web-probe observer 客户端进程]
    ART[.state/web-observe artifacts]
    ANALYZE[离线分析 job]
    TRANS --> CMD
    CMD --> OBS
    OBS --> ART
    ART --> ANALYZE
  end
  subgraph Browser[同一个 Playwright Browser/Context/Page]
    PAGE[Workbench page]
    DOM[DOM/scroll/performance 只读采样]
    NET[自然 request/response/requestfailed 事件]
    CONSOLE[console/pageerror]
    PAGE --> DOM
    PAGE --> NET
    PAGE --> CONSOLE
  end
  OBS --> PAGE
  DOM --> ART
  NET --> ART
  CONSOLE --> ART

长程 observer 的数据流必须保证：trans 只写命令文件和读取产物，不打开入站控制端口；observer 是目标 host 上的客户端进程，不是 Web 服务、daemon API、数据库消费者或平台状态源。控制命令、采样器和后处理分析共享同一份时间戳化 artifact；控制命令改变页面时必须记录为用户意图来源，采样器本身不得通过主动 API 请求、reload、自动点击、session repair 或网络拦截制造新业务事件。

5.5 PJ2026-0104010803 Workbench唯一投影专项

PJ2026-0104010803 Workbench唯一投影 是 Workbench 状态投影的唯一专项规格，集中定义 durable facts schema、WorkbenchProjectionWriter、WorkbenchProjectionFinalizer、WorkbenchFactsStore、WorkbenchReadModel、terminal commit、sealed final response、cloud-api 重启恢复、GET 纯读和代码引用规则。

Web工作台在本规格中只保留前端消费边界：Cloud Web reducer、selectors、session rail、timeline、composer 和 Trace detail 只能消费该专项定义的 durable projection；SSE 只是 projection commit 后的通知和加速；fake-server fixture 只重放同一 REST/SSE 合同。Web reducer/selectors、Trace renderer、CLI renderer、fake-server 和测试断言不得从 trace tail、message text、tool event、result cache、session summary、list row、workspace snapshot、localStorage 或 elapsed timeout 推断 lifecycle、terminal、running 或 final response。运行中相对时间展示是唯一允许的显示层本地 now 使用场景：startedAt、lastEventAt、finishedAt 和 sealed durationMs 仍来自 durable projection，浏览器只用本地 now 对这些权威字段做直接格式化，不产生新事实。前端严禁为了掩盖跳变、归零、非单调、投影滞后或后台 tab 抖动而加入平滑、滤波、单调 floor、跳变 cap、二次缓存、最近更新时间重算或“看起来连续”的时间造假；发现此类异常必须暴露 diagnostic 并修 durable projection、read model、SSE/outbox 或上游时间源。详细架构图、数据流图、关键时序图、0repair 和严禁读侧推理约束以专项规格为准，本文不再维护第二份投影架构正文。

长程可靠 Workbench 的用户可见验收矩阵如下，后续实现和回归验证必须直接引用这些稳定场景，而不是用单次 canary 或局部截图替代。

长程可靠 Workbench 还必须覆盖 AgentRun terminal outbox 恢复场景：同一 session 连续两轮提交后，即使 cloud-api 在中途重启、events page 没有 terminal event 或第 2 轮后 lastTraceId 已变化，用户仍应在第 1/第 2 轮 message card 看到 sealed terminal final response，并能打开每个历史 trace 的 events page。用户在上游 command 已 terminal 后点击 cancel，不得把 completed final response 改写为 canceled；Web 只能展示 already-terminal/no-op 或真实 terminal projection 的状态。

场景	权威事实	用户可见结果	禁止路径
新建 session 并发送最小 prompt	admission 写入稳定 sessionId、turnId、traceId、userMessageId、assistantMessageId	当前消息区立即显示用户消息、assistant pending 和可追踪 running 状态	用 workspace selected snapshot 或本地 stub 伪造 session/message
terminal commit 后显示 final response	sealed message/part/turn/trace facts	主 timeline 显示 sealed final response，Trace detail 显示 terminal	turn polling、SSE gap、trace hydration error 覆盖主正文
刷新或 fresh deep link	durable session/message/turn/trace projection	同一 session/turn/trace/message 恢复，composer 可继续操作	sessionRepair、reload 后自动新建 conversation、localStorage truth
切换 session 后返回	route sessionId 和 read model bucket	只更新目标 session bucket，不让迟到响应抢 active route	late response 覆盖当前消息区或 session rail
长 Trace 分页	projectedSeq cursor 和 durable terminal 字段	首屏消息先可见，Trace 分页继续加载且不丢 terminal	hasMore=false 推断 turn terminal 或全量扫描 live trace tail
completed/failed/canceled/blocked	sealed terminal result 或 failure result	每种终态都有主消息 final 或 failure result，并把 transport diagnostic 分仓	诊断文案、result cache 或 trace tail 抢占主消息 final

6. 原子需求

6.1 CLIENT-WB-REQ-001 工作台框架

编号	短名	主责模块	关联模块
CLIENT-WB-REQ-001	工作台框架	PJ2026-01040101 工作台框架	用户管理、平台运维

Web工作台应提供登录后的稳定 shell，使用户能够在同一浏览器入口看到当前身份、同源 API 状态、主导航、工作台内容和全局操作。

工作台框架负责浏览器层面的布局、导航、topbar 状态和页面切换反馈。用户身份和 session 有效性由用户管理提供；公开入口和运行健康由平台运维提供。工作台不得用旧页面块、临时状态行或原始运行日志替代稳定导航与反馈。

Web 工作台的 auth store 只能从 /auth/session 建立 canonical identity。路由 guard、topbar、admin 入口、Workbench、Usage、Billing 和 API keys 页面不得读取 user-billing token、API key secret、cookie prefix、Bearer token、localStorage authority 或旧测试后门。未登录时展示登录入口；已登录但能力不可用时展示后端结构化 blocker；前端不得通过二次登录、API key 输入或 fallback endpoint 修补身份。

6.2 CLIENT-WB-REQ-002 会话输入

编号	短名	主责模块	关联模块
CLIENT-WB-REQ-002	会话输入	PJ2026-01040102 会话输入	Agent编排、用户管理

Web工作台应让用户在主任务区直接选择或创建会话、阅读用户和 Agent 消息、输入任务、发起基本 Agent 调用、引导运行中任务，并看到发送、取消、重试和 pending 状态。

会话输入只负责用户可见的交互和消息呈现。基本 Agent 调用必须进入 Agent编排提供的执行生命周期，并返回用户可查询的 run、command、session 或等价状态入口；用户权限和会话有效性由用户管理提供。单条用户消息、trace 详情或状态摘要不得在默认视图中抢占主任务区，使用户难以继续输入。

Workbench 业务 API 的可见性只能由后端从 canonical principal 和 Workbench/Code Agent capability 判断。Web 不得把 billing 状态、API key 是否存在、project/workspace localStorage、session tab cache 或 conversation metadata 当作身份 authority；capability 不可用时必须保留当前身份并显示业务 blocker。

Web工作台必须使用显式 Agent session：无 session 时先让用户创建或选择 session，session failed、stale 或 canceled 时保留失败状态并要求用户显式切换或新建。刷新页面、重新打开工作台或短连接 result 轮询只能恢复已选 session、thread 和 trace 状态；除非用户登出或主动清空对话，不得自动生成新 conversation、替换 session 或用历史 prompt 拼接出续跑表象。

会话列表、当前消息头、composer 主按钮和运行态动效必须先确定唯一权威 API，再由 Web 展示该 API 的结果；不得让 workspace selected conversation、snapshot、stub、localStorage、message 派生状态、trace 快照或浏览器临时缓存与权威 API 并列竞争、互相覆盖或按失败路径 fallback 成另一套数据源。已经定下来的 authority 不变量如下：浏览器登录态只作为请求 transport；资源归属、project 可见性和权限由后端从当前 Web session/AuthPrincipal 判定；session rail 会话集合的主入口是 /v1/workbench/sessions，当前 session 消息本体的主入口是 /v1/workbench/sessions/{sessionId}/messages，session metadata 的主入口是 /v1/workbench/sessions/{sessionId}，turn 状态的主入口是 TurnSnapshot，Trace 阅读状态的主入口是 TraceEventPage。projectId、workspaceId 和 conversationId 可以作为后端返回的上下文字段、显式筛选字段或迁移期 metadata，但不得成为前端鉴权、资源可见性、active session 或 deep link 的 authority。深链恢复、刷新、从其他 session 切回和 route watcher 应走同一 session detail/message page 加显式 select/update 路径，不得先用 workspace selected snapshot、列表摘要或空 stub 覆盖当前 messages，再等待另一路请求补齐。

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 文案呈现。

Agent 请求应采用短连接 submit 加 result/trace 轮询。POST /v1/agent/chat 或等价入口返回执行标识后，工作台通过 result 和 trace path 获取终态与可读过程，不持有一次长 HTTP 请求等待整个模型 turn。后端 result 已完成时，消息卡片必须替换为真实 final response；仍在 pending 或 trace 缺失时应显示明确状态，而不是把“result ready for polling”类中间文本当作最终回复。

6.3 CLIENT-WB-REQ-003 诊断反馈

编号	短名	主责模块	关联模块
CLIENT-WB-REQ-003	诊断反馈	PJ2026-01040103 诊断反馈	Agent编排、硬件池、HarnessRL、平台运维

Web工作台应提供低噪声诊断反馈，使用户或管理员可以主动查看运行状态、probe、build、HWPOD 和 Agent 摘要，而默认工作区仍以任务输入和结果阅读为中心。

诊断入口应位于全局工作台区域，例如 topbar 内的小型信息或告警按钮，并通过弹窗或详情面板承载完整状态。诊断内容不得单独占用主任务区一整行，也不得默认插入 conversation 正文；缺失能力仍必须回到对应业务模块修复，不能用诊断文案代替能力实现。

所有用户可见错误都必须使用同一错误诊断块展示脱敏诊断字段。主文案先显示用户可理解的中文错误或业务 blocker；诊断行固定展示 trace_id 的复制入口，并在存在 requestId、route、error code、layer 或 observedAt 时以低噪声文本展示。没有服务端 trace id 的浏览器离线、DNS、CORS 或 network error 应使用前端 UI OTel trace id，并标记 source=browser，不得伪装成服务端 trace。

Trace Explorer 打开入口只由运行配置控制。前端不得在组件内硬编码 Tempo、Jaeger、Grafana 或平台内部地址；当 observability.traceExplorerUrlTemplate 缺失、trace_id 非 32 位十六进制或配置禁用打开入口时，只显示复制按钮。URL 构造只能替换 {trace_id}，不得拼接用户输入、tracestate、baggage、cookie、token、prompt、assistant 正文或 raw upstream payload。

错误诊断块适用于 Workbench admission 失败、projection blocker、transport timeout、SSE gap、trace hydration error、Skills/Gate/Performance 等普通页面 API 错误和全局 route exception。各页面不得各自拼接一套中文诊断文案或只抛出 Error(response.error)；API client 应保留结构化 ApiError / ErrorDiagnostic，字符串只作为最终用户文案。

6.4 CLIENT-WB-REQ-004 响应布局

编号	短名	主责模块	关联模块
CLIENT-WB-REQ-004	响应布局	PJ2026-01040104 响应布局	Agent编排、硬件池、平台运维

Web工作台应在桌面和移动端保持主任务区可用：桌面端可以展示会话、对话和辅助资源多栏布局，移动端必须优先展示 topbar、对话和命令输入区。

响应布局负责把辅助面板、侧栏和诊断信息按可视空间收起、折叠或隐藏，使用户不需要滚动穿过导航和辅助面板才能找到输入区。桌面侧栏折叠必须真实释放宽度；移动端应避免页面外层滚动成为主要操作路径，主任务区内部可以按需要滚动。

6.5 CLIENT-WB-REQ-005 同源体验

编号	短名	主责模块	关联模块
CLIENT-WB-REQ-005	同源体验	PJ2026-01040105 同源体验	PJ2026-010402 HWLAB CLI、PJ2026-010403 API契约、Agent编排

Web工作台应与 HWLAB CLI 共享 Code Agent composer policy、trace renderer 和同源 REST/JSON API 语义，使浏览器工作流问题能用同一运行端点的 CLI 非视觉复现。

Web只负责浏览器交互与展示；CLI负责命令入口和结构化输出；API契约负责 path、schema 和错误语义；Agent编排负责执行事实。Web trace row 错乱、final response 缺失或发送状态异常等问题，应能先通过 CLI trace --render web、同源 REST request 和显式 Agent session 命令定位到共享 renderer、API 契约或浏览器表现层，不能让 Web 和 CLI 各自维护一套 trace 解释。

同源体验中的身份验证以 /auth/session 为最小验收端点。D601 线上 web-probe 和 fake-server Playwright 都应先覆盖 fresh login、刷新后 identity 一致、未登录结构化 unauthenticated 和脱敏边界，再进入 Workbench、Usage、Billing 或 API keys 的业务消费回归。业务页面碰巧可用不能替代最小身份验证通过。

工作台在增量刷新 trace、message 或 status 时，应保持用户已展开的详情状态和滚动位置。trace 压缩、sourceSeq 窗口或 event cap 只能影响默认摘要，不得吞掉可读 message、tool call、stderr/error 或 terminal 边界；需要完整事件时，Web 应通过 RESTful trace resource 自动请求完整可读事件，而不是让用户手工从原始日志中恢复上下文。RESTful trace resource 返回 hasMore、nextSinceSeq 或等价游标时，Web 必须继续通过同一资源入口分片请求，并在每个片段到达后立即合并渲染；不得等所有片段全部拉完才一次性显示，也不得为了补齐事件切换到 JSON-RPC、回放 Trace、内部 manager 或前端 fallback 路径。

6.6 CLIENT-WB-REQ-006 Trace阅读

编号	短名	主责模块	关联模块
CLIENT-WB-REQ-006	Trace阅读	PJ2026-01040106 Trace阅读	Agent编排、PJ2026-010403 API契约、用户管理

Web工作台应提供面向用户的 Trace阅读视图，使用户默认看到从第一条有意义的助手消息、工具调用或最终结果开始的可读执行过程，而不是 request accepted、session reuse、thread/run/command 创建、runner job、backend 状态、token/chunk 或隐藏事件统计。

Trace阅读视图必须把 trace id、session、thread、run、command、event count、hidden count、raw event、follow/pause 和审计类控制收束到 Agent 消息头部右上角的消息详情入口。Trace 展开体只允许展示用户可读的运行记录本体，不得直接渲染 trace meta panel、身份 chip、隐藏事件统计、噪声聚合说明、原始事件开关或跟随/到底部等调试控件；这些内容只有在用户点击消息详情入口后才可见。

Web 工作台在会话恢复、session 切换、turn running、turn completed 或消息卡片重建时，必须按 traceId 自动调用 GET /v1/agent/traces/{traceId} 补齐 Trace阅读视图。pending 状态应展示加载转圈；completed 消息即使 final response 已可见，也必须自动加载对应 trace events，不得停留在空的“思考中...”记录。分片未拉完属于“加载中”，已经完成加载但仍无可读 Code Agent 消息才属于“思考中”。用户界面不得提供“回放 Trace”作为加载完整 trace 的必要操作。

工具调用和命令输出行必须正文优先：时间、状态、tool 名称和耗时只作为紧凑 header，不得占用独立左列或固定半屏宽度；stdout、stderr、error、patch、命令结果和助手 Markdown 应获得完整可用宽度。终端完成行和 Agent 最终消息应显示真实轮次耗时，耗时来源应使用 trace 事实、首尾事件时间或服务端 elapsed 字段，不得在已完成运行中显示 00:00:00 这类伪完成耗时。

运行中的 Agent 消息头部可以用浏览器本地 now 推进“最近”和“耗时”文案，但计算输入只能是唯一投影返回的 startedAt 与 lastEventAt 时间戳，并且必须是可解释的直接计算。lastEventAgeMs、本地 updatedAt、trace tail、events 数组长度或轮询间隔不得进入用户可见相对时间显示路径。消息进入 completed、failed、canceled、blocked 等终态后，耗时必须使用 sealed projection 的 durationMs 或等价 sealed finishedAt - startedAt 口径，且停止随浏览器 now 增长。前端不得保存 per-message timing floor、sealed duration cache、recent age cache 或其他本地状态来修正权威时间；若页面可见时间出现跳秒、归零、非单调或与 trace/轮次完成不一致，web-probe 应报告异常，修复点必须回到 projection writer/finalizer/read model 或上游事件时间戳。

Trace阅读视图属于工作态高密度界面。重复 trace row、message card、trace panel、warning 和 inline code 的圆角、间距和 padding 应保持紧凑；默认视觉层级以内容可扫读为主，不使用大圆角、大留白、嵌套卡片或装饰性布局制造工作区浪费。原始 trace 仍必须可审计，但只能作为消息详情入口中的主动展开内容，不得成为默认阅读面或 Trace 展开体的一部分。

Trace阅读视图必须跟随 Code Agent turn 生命周期自动调整展开状态：任务开始、pending 转 running 或首次出现运行中 trace 时，工作台应自动展开对应 trace，使用户能立即看到进展；运行中的 turn 进入 completed、failed、canceled、timeout、blocked 或出现 final response 等终态时，工作台应自动折叠对应 trace，回到正文和最终结果优先的阅读状态。自动折叠不得删除 trace、隐藏错误或阻止用户手动重新展开查看详情。若会话或 trace 在补拉前已经处于 final/terminal 状态，后续历史分片补拉完成不得触发自动折叠，也不得覆盖用户手动展开或折叠状态。

命令输入区应提供单一主按钮承载当前 turn 的主要动作：没有运行中 turn 时为发送新 Turn；存在运行中 turn 且输入框为空时为取消；存在运行中 turn 且输入框非空时为 Steer。工作台不得在运行已结束后继续显示独立的“取消运行中 Trace”按钮，也不得让发送、取消和 Steer 以多个并列主动作长期同时出现。

6.7 CLIENT-WB-REQ-007 公开入口

编号	短名	主责模块	关联模块
CLIENT-WB-REQ-007	公开入口	PJ2026-01040107 公开入口	平台运维、PJ2026-010403 API契约、用户管理

Web工作台的正式浏览器入口必须来自目标 node/lane YAML 声明的 public URL。用户文档、内测说明、Playwright 验收和 issue 复现默认使用该正式公开入口，不使用 FRP remote port、节点直连端口、旧 lane 端口或历史临时域名作为正式入口。

正式公开入口下，/、/login、/workbench 和登录后页面应由 Cloud Web 提供一致的 SPA history fallback。API path 仍由 API契约定义并返回 JSON 语义；Web工作台不得要求 API/edge 端口对浏览器 history route 返回 HTML fallback。

平台运维负责把 YAML 声明的 public URL、FRP、Caddy、TLS 和 health 投递到运行面；Web工作台负责在该入口上完成登录、工作台、导航和错误展示。实现端口可以作为诊断入口暴露给维护者，但不得出现在用户主入口、内测验收入口或客户端默认配置中。

6.8 CLIENT-WB-REQ-008 状态投影

编号	短名	主责模块	关联模块
CLIENT-WB-REQ-008	状态投影	PJ2026-01040108 状态投影	PJ2026-010403 API契约、Agent编排

Web工作台应把 REST snapshot、SSE event、submit optimistic、trace pagination 和 page refresh hydrate 统一归入 Workbench Server State。Server State 应按 sessionId、messageId、partId、turnId 和 traceId 归一化保存服务端事实；conversationId、projectId 和 workspaceId 只能作为后端 metadata 或兼容映射字段挂接在对应 session/message 上，不得作为 active 对象、权限判断或恢复路径的 authority。UI transient state 只保存 route、显式选择、composer draft、scroll、展开状态和临时交互状态。

Timeline Projection 只能从 messages、parts、turn status 和 trace events 派生用户可见 rows。Trace detail 只消费 TraceEventPage；session rail 只消费 session list 和 turn summary；composer 只消费当前 route/selected session 与明确 running turn。组件、trace polling、submit/cancel 回调不得直接写 messages、final response 或 trace authority。

PJ2026-0104010803 Workbench唯一投影 要求 Web 工作台把 sessionId、messageId、partId、turnId 和 traceId 作为 reducer 合并键。REST snapshot、SSE event、submit optimistic 和 trace pagination 的任何 late response 都只能更新其自身 key 对应的事实，不得清空当前 selected session、覆盖已存在 message page、或用 list summary/localStorage/workspace snapshot 重建当前 timeline。running trace 在 terminal 前收到 hasMore=false 只表示当前 trace page 暂时追平，不表示 fullTraceLoaded=true；后续 SSE 或 REST catch-up 仍必须能追加 terminal event 和 final response。

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 中合成“看起来正确”的状态。

浏览器本地 now 只属于 view-layer render input。它不得进入 reducer action、store mutation、projection merge、lifecycle selector、session sorting、terminal 判定、transport diagnostic 或 fake-server fixture 事实生成。前端回归必须覆盖固定 projection timestamp 且无 SSE/API 更新时，运行中“最近”和“耗时”仍随 fake clock 前进；同时覆盖 terminal 消息耗时不随 fake clock 前进。

Web 工作台必须把主消息投影、trace detail、session status 和 transport diagnostics 分仓保存。对已经带有 sealedAt 或等价 sealed 标记的 assistant message/turn，turn polling 失败、trace hydration 失败、SSE gap、realtime timeout、late compat wrapper error 或 elapsed timeout 只能更新诊断 bucket 或消息详情入口，不得替换主 timeline 的正文、finalResponse、message status 或 turn terminal。showMessageText()、message diagnostic selector、Trace 面板和组件模板不得让读侧诊断文案压过 sealed final response；需要修改 sealed 主正文时只能来自同一 durable projection 的新 revision、受控 replay/reprojection 或明确用户 mutation。

错误诊断中的 trace_id、requestId、route、layer 和 code 只属于 diagnostic bucket。它们可以驱动复制按钮、Trace Explorer 链接、消息详情感叹号或 transport health 展示，但不得参与 running、completed、failed、canceled、blocked、finalResponse 选择、自动折叠、session active 选择或主消息正文替换。completed sealed final response 后出现的 polling、SSE 或 trace hydration 错误只能追加诊断，不得把主消息正文改成“连接上游失败”“等待超时”或同类读侧错误态。

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 共同竞争当前消息面板。

状态投影正确性必须能被独立浏览器回归验证覆盖。测试应在同一 Web 构建产物上使用 mock server 重放真实采集 fixture，断言 session rail、主 timeline、workspace card、composer、message card 和 trace detail 在 session 切换、刷新页面、SSE 断线重连、REST 补洞和 trace 分页补拉后保持同一组 sessionId、turnId、traceId、messageId 与终态语义；conversationId/projectId/workspaceId 只可作为 metadata 被展示或调试，不得改变通过条件。测试不得依赖 live AgentRun、Cloud API、HWPOD、数据库或 Kubernetes 状态作为通过条件。

状态投影回归还必须覆盖 sealed final response：completed assistant 正文已经显示后，turn snapshot、trace event page、SSE 或 realtime diagnostic 返回 timeout/500/gap/close 时，主消息正文和终态保持不变，诊断只进入 trace detail、transport diagnostic、session health 或消息详情入口。测试必须用用户可见 DOM 断言，不通过内部 store 或 localStorage 判定通过。

浏览器回归验证必须先覆盖 0repair 红灯：fresh context 直达 session、普通点击切换 session、A session 延迟 detail/turn/trace/SSE 晚到、B session active、无用户新消息时，都不得让 A 的 user/agent 消息、running 状态或 trace 出现在 B。Playwright 和 web-probe 只能观察、连续截图和断言；不得用 reload、切换 session、sessionRepair、realignFreshSession 或 localStorage 修改把页面修正后再判通过。

6.9 CLIENT-WB-REQ-009 前端模块

编号	短名	主责模块	关联模块
CLIENT-WB-REQ-009	前端模块	PJ2026-01040109 前端模块	PJ2026-010403 API契约、PJ2026-010604 公开入口

Web 工作台实现应按职能拆分为 API client、event/SSE client、server-state store、reducer、selectors/projection、trace event projection、composer UI state、session rail UI state 和具体 UI 组件。server-state 模块不得写 UI transient state；UI 组件不得直接合并 REST/SSE 响应；projection 模块不得发请求或写状态。

新增或重构的核心前端文件头部必须标注遵循的 SPEC 编号、短名和实现引用版本，例如 SPEC: PJ2026-0104010803 唯一投影 draft-2026-06-20-p0-durable-facts-model; PJ2026-010401 Web工作台 draft-2026-06-20-p0-long-running-workbench; PJ2026-010403 API契约 draft-2026-06-20-p0-workbench-pure-read-api，并简述文件职责。实现文件不得只写 issue 编号、latest 或 current 作为规格引用。

6.10 CLIENT-WB-REQ-010 浏览器回归

编号	短名	主责模块	关联模块
CLIENT-WB-REQ-010	浏览器回归	PJ2026-01040110 浏览器回归	PJ2026-010403 API契约、平台运维

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 并恢复目标 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、发送 hi、running 可见、final response 可见、Trace terminal 可见、刷新、切换 session、回到原 session、删除或归档。长程链路回归必须使用真实采集脱敏长 Trace fixture，覆盖分页、SSE gap、projection lag、terminal sealed、diagnostic 分仓和截图 artifact。两类回归都必须记录 fixture schema/redaction 版本、capturedFrom、capturedAt、derivedFrom、截图 SHA 或等价 artifact 校验值。

状态投影回归必须覆盖新建 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 修正页面后判通过。

状态投影回归还必须覆盖 completed assistant 已 sealed 后的读侧失败负向用例：fixture 中 session messages API 返回 completed final response，随后 turn snapshot、trace event page、SSE 或 realtime diagnostic 失败。主 timeline 的 sealed final response 不变，诊断只显示在详情/感叹号/transport health 区域；Trace detail 延迟返回或分页缺口不得 remount 主消息卡片，也不得重置用户展开/折叠控制。

错误诊断回归必须覆盖 HTTP 400、401、403、404、409、500、proxy timeout、network error、Workbench projection blocker 和 sealed final 后 transport error。fake-server fixture 应按正式 HwlabErrorEnvelope 或等价结构重放 error.diagnostic.traceId、requestId、route、code 和 valuesRedacted=true，并用用户可见 DOM 断言诊断块、复制入口和可选 Trace Explorer 链接；测试不得通过内部 store、localStorage 或测试专用后门读取诊断字段。

测试实现应优先使用用户可见文本、ARIA role 和稳定 DOM 标识断言，不通过内部 store、localStorage 或后端数据库直接判定通过。失败时必须保留 Playwright screenshot、trace 或等价 artifact；关键路径可以生成命名截图用于人工审阅。远程执行默认在目标 node/lane 上通过 UniDesk Playwright route 运行，截图和报告应回传到调用端，但这些 artifact 只是验证证据，不进入业务事实或监控指标。

6.11 CLIENT-WB-REQ-011 长程观测

编号	短名	主责模块	关联模块
CLIENT-WB-REQ-011	长程观测	PJ2026-01040111 长程观测	PJ2026-010604 公开入口、平台运维

Web 工作台应具备长程 web-probe observer 能力，用真实浏览器在目标 node/lane 的正式公开入口上持续观察同一页面，用于复现和分析长 Trace、session 切换、刷新恢复、滚动跟随、final response 闪烁和无用户新消息时状态变化等瞬态问题。该能力只提供观察和证据，不拥有 Workbench 业务状态、身份鉴权、session lifecycle、projection、监控指标或修复权。

web-probe observer 必须保持纯客户端形态。它可以作为目标 host 上的长时间本地进程运行，但不得暴露入站 HTTP/WebSocket/gRPC API、监听控制端口、数据库 schema、消息队列消费者、Kubernetes 常驻服务、平台 daemon 或 Web 管理面。启动、停止、状态查看、命令投递和 artifact 回收只能通过受控 CLI、trans 短连接和目标 host 文件系统完成。任何需要长期保留的默认参数必须按 YAML-first 进入 UniDesk 自有配置；一次性控制命令使用命令文件，不得演变为新服务协议。

同一个 observer job 内必须只有一个页面权威。Playwright browser/context/page 由 observer 客户端进程持有；控制循环、采样循环、截图逻辑和网络事件监听共享同一个 page 对象。登录、打开 URL、发送 prompt、点击会话、截图和停止等控制动作以命令文件进入 commands/pending，处理结果追加到 control.jsonl，并带上命令 id、时间戳、操作者来源、执行前后 URL 和页面标识。若浏览器或页面崩溃后必须重建，observer 必须记录 oldPageId/newPageId、原因和连续性中断，不能把重建后的页面当作同一段无缝采样。

采样默认必须无副作用。采样器不得主动 fetch Workbench 业务 API、不得 reload 页面、不得自动点击、不得切换 session、不得调用 session repair helper、不得通过 page.route() 拦截或改写请求，也不得用 GET 触发 read-through repair。允许采集的默认输入只包括 DOM 快照摘要、可见文本摘要、当前 URL、scroll metrics、focus/selection、performance 条目、console/pageerror、Playwright 自然产生的 request/response/requestfailed 事件和用户控制命令造成的页面自然网络事件。网络记录必须标明 observerInitiated=false；若未来确需主动 API 探针，必须作为显式非默认模式记录 observerInitiated=true，并从被动证据分析中排除。

长程采样产物必须使用时间戳化目录和 JSONL 追加文件。推荐目录形态为 .state/web-observe/<node>/<lane>/<YYYY>/<MM>/<DD>/<timestamp>_<target>_<jobId>/，其中 manifest.json 记录目标 origin、node、lane、browser 版本、observer 版本、启动参数和脱敏策略；heartbeat.json 保存最近心跳；control.jsonl、samples/*.jsonl、network/*.jsonl、console/*.jsonl、pageerrors/*.jsonl、anomalies/*.jsonl 分别承载控制、采样、网络、控制台、页面错误和异常。每条 JSONL 记录必须包含 ISO 时间、单调序号、pageId、url、recordType、source、valuesRedacted 和 schemaVersion，避免长程文件被一次性整块读取或写坏。

截图策略应受预算控制。默认不做高频全页截图；常规 checkpoint 可使用 viewport 或关键区域 JPEG，并配置质量、间隔、最大张数和总字节预算；异常、失败、布局错乱和人工标记证据使用 PNG 或等价无损格式保存。每张截图必须记录触发原因、文件 SHA、字节数、viewport、deviceScaleFactor、关联 sample seq 和脱敏状态。重复截图应通过内容 hash 或视觉 hash 去重；超过预算时优先保留异常、状态切换和人工命令附近的证据。

离线分析 job 只能读取 artifact，不访问 Workbench 业务 API，也不修改浏览器页面。分析至少应覆盖：active session 是否跳转、route/session/message/trace 是否不一致、没有用户命令时是否出现新 agent 消息、final response 是否从 sealed 正文闪回错误态、Trace 是否长时间无 terminal、Trace 窗口和主工作区滚动是否跳顶、运行中“最近/耗时”是否停止刷新、自然网络响应与 DOM 可见状态之间的延迟。分析结果写入 analysis/report.md 和结构化 analysis/report.json，作为 issue 和回归修复证据，不成为产品业务状态。

长程 observer 不替代 fake-server Playwright 回归。fake-server Playwright 负责确定性功能红灯和修复后回归；observer 负责在线 public origin 的长时间、无副作用、瞬态观测。observer 发现的 bug 必须沉淀成可复现 fixture 或 fake-server 用例后再作为 Web 工作台功能回归闭环；不得用 observer 的自动切换、reload、repair 或人工观察代替功能修复。

6.12 CLIENT-WB-REQ-012 CaseRun 入口

编号	短名	主责模块	关联模块
CLIENT-WB-REQ-012	CaseRun入口	PJ2026-01040112 CaseRun入口	HarnessRL、PJ2026-010403 API契约、硬件池、Agent编排

Web 工作台应提供 CaseRun 用户入口，使用户能在登录后的 selected Web origin 中查看可用 HWPOD 资源和 case 列表，提交 CaseRun，看到 runId 和短返回状态，并在同一页面或相邻登录后页面观察 run stage、Trace、HWPOD evidence、artifact manifest、aggregate 和失败 blocker。

CaseRun 入口应保持工作态密度。HWPOD 资源卡应展示资源身份、连接/可用状态、能力摘要和关键 blocker；case 列表应展示 caseId、目标硬件和执行范围；run 卡应以 queued、preparing、agent-running、building、downloading、uart-reading、aggregating、completed、failed、canceled、blocked 等状态表达进度。Trace、download/UART 原始片段和 artifact manifest 可以折叠，但 aggregate、终态、主要 blocker 和继续查询标识必须默认可见。

Web 工作台只调用 YAML-selected origin 下的同源 CaseRun API 和既有 Trace/aggregate/HWPOD 读侧入口。它不得直接访问 HWPOD node、本地 gateway、旧 v0.2 runner、数据库、Kubernetes、SSH 或未在 YAML 声明的临时内部服务来提交或判断 CaseRun。若 API 返回 HWPOD workspace missing、node offline、capability mismatch、probe mismatch、serial-monitor unavailable、AgentRun blocker 或 aggregate missing，Web 必须展示对应结构化 blocker 和可复制诊断，而不是改写为通用请求失败。

线上 web-probe 对 CaseRun 的验收必须从同一 selected Web origin 进入。默认使用正式 public origin；本次 D601/v03 可以由 YAML 切换到 internal IP origin。web-probe 可以点击页面控件或调用页面同源正式 mutation，但不得绕过 Web session、不得使用未被 YAML 选中的内部 service URL、不得直接写 D601 文件系统、不得用 SSH 或手工 CLI 操作补齐硬件证据。web-probe 报告至少应记录 originMode、YAML source path、final URL、截图 SHA、caseId、runId、hwpodId、nodeId、traceId、HWPOD operation result 引用、aggregate 或 artifact manifest hash，以及是否存在用户可见 blocker。

6.13 CLIENT-WB-REQ-013 项目启动

编号	短名	主责模块	关联模块
CLIENT-WB-REQ-013	项目启动	PJ2026-01040113 项目启动	PJ2026-010404 项目管理、PJ2026-010403 API契约、Agent编排

Web 工作台应提供公共 launch context 消费能力，使项目管理等登录后页面可以通过 POST /v1/workbench/launches 创建或选择 Workbench session，并把脱敏 projectId、taskRef、sourceKind、title 摘要和 prompt template 标识保存为 session metadata。

Workbench 对 launch context 的使用必须保持只读和脱敏。它可以在 session header、message detail 或诊断入口展示项目来源摘要，也可以把 metadata 传给 Agent turn admission；但不得反解 taskRef、读取 Markdown、调用 Project Management 私有 adapter、访问 PM DB、import MDTODO 页面组件或把项目管理状态写入 Workbench reducer。

项目管理页面跳转到 /workbench/sessions/{sessionId} 后，Workbench 必须按既有 session detail、message page、turn snapshot 和 trace event page authority hydrate。projectId/taskRef 只作为 metadata 和后续查询 link 的 ID，不得替代 sessionId、turnId、traceId 或 messageId 成为 Workbench authority。

Workbench 模块不得为了项目管理联动新增 iframe、嵌套 Workbench 容器、localStorage 协议、私有 service URL、跨模块 store import 或 Markdown parser 依赖。需要回到项目任务时，只能使用公共 project link URL 或公共 Project Management API 暴露的 link 摘要。

7. 过程控制

本规格不单独索引过程 issue；跨 L1 的内测、灰度和阶段活动索引统一保留在 PJ2026-01 HWLAB 总规格 的 7. 过程控制。