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-18-r1; PJ2026-0104010803 唯一投影 draft-2026-06-18-p0-zero-repair |
| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
| 上级规格 | [PJ2026-0104 客户端](PJ2026-0104-client.md) |
| 规格治理索引 | [规格治理](spec-governance.md) |

本文采用 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、额度和账本事实归 [用户管理](PJ2026-0105-user-management.md)。
- Code Agent session、trace、workspace、provider profile 和执行生命周期事实归 [Agent编排](PJ2026-0102-agent-orchestration.md)。
- HWPOD 资源、节点健康和硬件事实归 [硬件池](PJ2026-0101-hardware-pool.md)。
- CaseRun 评价、回放和训练反馈语义归 [HarnessRL](PJ2026-0103-harness-rl.md)。
- 公开入口、CI/CD、GitOps、Secret、FRP、Caddy 和 runtime 健康归 [平台运维](PJ2026-0106-platform-ops.md)。
- CLI 参数、CLI 输出和 HTTP API 契约仍归 [PJ2026-0104 客户端](PJ2026-0104-client.md) 中对应 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唯一投影](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 还原同一语义结果。 |
| 浏览器回归验证 | 使用 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 目标数据流程图

```mermaid
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 目标架构图

```mermaid
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 浏览器回归验证数据流图

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

### 5.4 PJ2026-0104010803 Workbench唯一投影专项

[PJ2026-0104010803 Workbench唯一投影](PJ2026-0104010803-workbench-unique-projection.md) 是 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 合同。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。详细架构图、数据流图、关键时序图、0repair 和严禁读侧推理约束以专项规格为准，本文不再维护第二份投影架构正文。

## 6. 原子需求

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

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| CLIENT-WB-REQ-001 | 工作台框架 | PJ2026-01040101 工作台框架 | [用户管理](PJ2026-0105-user-management.md)、[平台运维](PJ2026-0106-platform-ops.md) |

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编排](PJ2026-0102-agent-orchestration.md)、[用户管理](PJ2026-0105-user-management.md) |

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编排](PJ2026-0102-agent-orchestration.md)、[硬件池](PJ2026-0101-hardware-pool.md)、[HarnessRL](PJ2026-0103-harness-rl.md)、[平台运维](PJ2026-0106-platform-ops.md) |

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

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

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

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| CLIENT-WB-REQ-004 | 响应布局 | PJ2026-01040104 响应布局 | [Agent编排](PJ2026-0102-agent-orchestration.md)、[硬件池](PJ2026-0101-hardware-pool.md)、[平台运维](PJ2026-0106-platform-ops.md) |

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

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

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

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| CLIENT-WB-REQ-005 | 同源体验 | PJ2026-01040105 同源体验 | [PJ2026-010402 HWLAB CLI](PJ2026-010402-hwlab-cli.md)、[PJ2026-010403 API契约](PJ2026-010403-api-contract.md)、[Agent编排](PJ2026-0102-agent-orchestration.md) |

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-0102-agent-orchestration.md)、[PJ2026-010403 API契约](PJ2026-010403-api-contract.md)、[用户管理](PJ2026-0105-user-management.md) |

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-0106-platform-ops.md)、[PJ2026-010403 API契约](PJ2026-010403-api-contract.md)、[用户管理](PJ2026-0105-user-management.md) |

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契约](PJ2026-010403-api-contract.md)、[Agent编排](PJ2026-0102-agent-orchestration.md) |

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唯一投影](PJ2026-0104010803-workbench-unique-projection.md) 要求 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 中合成“看起来正确”的状态。

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 状态作为通过条件。

浏览器回归验证必须先覆盖 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-010403-api-contract.md)、[PJ2026-010604 公开入口](PJ2026-010604-public-entry.md) |

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契约](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 并恢复目标 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. 过程控制

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