Codex
37 KiB
PJ2026-010401 Web工作台
修改历史
| 版本 | 对应 commit id | 更新日期 | 变更说明 |
|---|
当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 待提交 版本。
正文
PJ2026-010401 Web工作台需求规格
1. 文档控制
| 字段 | 内容 |
|---|---|
| 编号 | PJ2026-010401 |
| 短名 | Web工作台 |
| 层级 | L2 课题 |
| 状态 | 已生效 |
| 实现引用版本 | draft-2026-06-18-r1; PJ2026-0104010803 唯一投影 draft-2026-06-18-p0-unique-projection |
| 需求规格模板 | 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 非视觉复现。
2.2 范围内
- 登录后 Cloud Web shell、topbar、导航、工作台路由、页面切换反馈和同源 API 状态展示。
- 会话列表、当前 session、用户消息、Agent 消息、命令输入区、发送、引导、取消、重试和 pending 状态展示。
- 基本工作台 Agent 调用，包括最小任务输入、发送、短返回执行标识、状态查询入口和失败原因展示。
- 工作台诊断入口、运行状态摘要、probe/build/HWPOD/Agent 状态的低噪声展示方式。
- 桌面多栏布局、侧栏折叠、移动端工作台布局和输入区可达性。
- 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 课题。
3. 术语表
| 术语 | 定义 |
|---|---|
| Web工作台 | 登录后用于提交任务、管理会话、查看结果和进入辅助诊断的 Cloud Web 主工作面。 |
| 主任务区 | 用户完成主要工作流的区域，包括会话消息和命令输入区。 |
| 命令输入区 | 用户输入新任务、引导运行中任务、取消或重试任务的 Web 控件集合。 |
| 诊断入口 | 用户主动打开的工作台状态详情入口，通常以 topbar 内的小型按钮或状态图标呈现。 |
| 低噪声展示 | 诊断、trace、状态和辅助信息不抢占主任务区，也不伪装成用户或 Agent 正文。 |
| 响应式工作台 | 同一工作台在桌面和移动端按不同可视空间重排，但仍优先保证任务输入和状态理解。 |
| 同源业务入口 | Cloud Web 与 HWLAB CLI 通过同一 Web origin、相对 REST/JSON API path 和业务标识访问 HWLAB 能力的入口。 |
| 浏览器登录态 | 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、隐藏统计和审计控制等调试信息。 |
| 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 的渲染投影，不发请求也不写事实状态。 |
| 唯一投影 | PJ2026-0104010803 Workbench唯一投影 定义的状态链路：AgentRun 执行事实只经 HWLAB projection writer/finalizer 写入 durable Workbench facts，REST、SSE、CLI、fake-server 和 Web 前端只消费该投影。 |
| 初发刷新一致性 | 同一 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. 系统边界和接口
本规格把 Web工作台作为客户端方向下的浏览器入口课题看待；本章只描述输入、输出和责任边界。
| 边界项 | 内容 |
|---|---|
| 外部使用者 | 硬件研发用户、平台管理员、需要通过浏览器提交或观察任务的操作人员。 |
| 外部输入 | 登录后访问请求、页面导航、会话选择、任务文本、引导/取消/重试操作、诊断查看操作和管理入口点击。 |
| 受控资源 | Cloud Web shell、工作台路由、会话面板、对话面板、命令输入区、诊断弹窗、导航、响应式布局、composer policy 和共享 trace renderer。 |
| 外部输出 | 页面可见任务入口、会话状态、消息展示、命令反馈、诊断摘要、错误提示和可继续操作的 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 功能回归、防止刷新和会话切换退化 |
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 切换补洞全部进入同一个 reducer；晚到响应只能更新其所属 session、turn 或 trace cache，不能改变当前 active conversation。
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 PJ2026-0104010803 Workbench唯一投影专项
PJ2026-0104010803 Workbench唯一投影 是 Workbench 状态投影的唯一专项规格，集中定义 durable facts schema、WorkbenchProjectionWriter、WorkbenchProjectionFinalizer、WorkbenchFactsStore、WorkbenchReadModel、terminal commit、cloud-api 重启恢复、GET 纯读和代码引用规则。
Web工作台在本规格中只保留前端消费边界：Cloud Web reducer、selectors、session rail、timeline、composer 和 Trace detail 只能消费该专项定义的 durable projection；SSE 只是 projection commit 后的通知和加速；fake-server fixture 只重放同一 REST/SSE 合同。详细架构图、数据流图和关键时序图以专项规格为准，本文不再维护第二份投影架构正文。
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，再等待另一路请求补齐。
用户切换 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 正文；缺失能力仍必须回到对应业务模块修复，不能用诊断文案代替能力实现。
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 这类伪完成耗时。
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 工作台的硬约束：同一 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 状态作为通过条件。
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-18-p0-unique-projection; PJ2026-010401 Web工作台 draft-2026-06-18-r1; PJ2026-010403 API契约 draft-2026-06-18-r1，并简述文件职责。实现文件不得只写 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。
测试实现应优先使用用户可见文本、ARIA role 和稳定 DOM 标识断言，不通过内部 store、localStorage 或后端数据库直接判定通过。失败时必须保留 Playwright screenshot、trace 或等价 artifact；关键路径可以生成命名截图用于人工审阅。远程执行默认在目标 node/lane 上通过 UniDesk Playwright route 运行，截图和报告应回传到调用端，但这些 artifact 只是验证证据，不进入业务事实或监控指标。
7. 过程控制
本规格不单独索引过程 issue；跨 L1 的内测、灰度和阶段活动索引统一保留在 PJ2026-01 HWLAB 总规格 的 7. 过程控制。