docs: record v02 workspace first screen contract
This commit is contained in:
Codex Agent
@@ -28,6 +28,24 @@ Provider API Key 配置入口也归属 Cloud Web：左侧顶级导航必须提
|
||||
- **Code Agent Timeout Model（HWLAB #795 final）**：Workbench 不允许把 Code Agent 长任务总耗时当成失败条件，也不得在浏览器侧引入任何 total-timeout / hard cap / `codeAgentTimeoutMs * N` 兜底 / 轮询次数上限 / 按 wall-clock 缩小的 per-poll 窗口。Code Agent turn 的唯一 abort 信号是 **inactivity-timeout**：即 `fetchJson` 的 `timeoutMs`（用户配的 `codeAgentTimeoutMs`）窗口内没有任何新 activity（trace snapshot / user typing / submit kickoff / server 5xx 重试）。一旦 `activityRef.lastActivityAt` 在窗口内被刷新，per-poll 窗口必须维持原值不缩小，外层 `waitForAgentResult` / `pollRunnerTrace` 的 `for(;;)` 循环也没有任何累计计时跳出条件。Runaway 保护的责任在调用方：用户可以走 cancel / steer / 关 tab / 关浏览器 / session cancel，而不是浏览器隐式地按 `4 × totalTimeoutMs` 把活跃 turn 杀掉。AgentRun command/provider/backend 失败后，当前消息可显示 failed/blocker；session 是否仍 usable 必须由 session 状态显式表达。`thread-resume-failed`、provider continuation 失效、运行面中断或用户取消导致 session failed/stale/canceled 时，不得自动清理并滚动到新 session；继续前必须由用户显式创建或选择 session。
|
||||
- 同一 AgentRun run 复用多条 command 时，Web trace 展示只显示当前 command 归属事件和必要 run 级状态；旧 command 的 assistant/tool/terminal 尾部不能堆到新 command 末尾。取消轮次的可读进展必须作为脱敏 conversation facts 进入 UI/trace/inspect 证据，而不是靠旧 trace 尾部串线让后续轮次“碰巧看到”；这些 facts 不得作为下一轮模型上下文或 prompt 拼接来源。
|
||||
|
||||
## Workbench 首屏性能契约
|
||||
|
||||
`/` 和 `#/workspace` 是 Cloud Web 的用户业务首屏；性能页、构建检查、本地 mock、CLI-only 请求或 sidecar 存活不能替代该入口。首屏性能目标用于用户体感回归判断，不作为新的发布旧门禁：真实浏览器打开 `http://74.48.78.17:19666/#/workspace` 后，LCP 应稳定低于 `3s`，CLS 应低于 `0.1`，`#command-input` 必须可见且可输入。
|
||||
|
||||
首屏 bootstrap 路径必须保持窄路径：
|
||||
|
||||
- HTML 在 `/` 或 `#/workspace` 首屏可以在解析期提前发起一次 `GET /auth/workspace-bootstrap?projectId=prj_device_pod_workbench`。React auth/workbench 状态必须优先消费 `window.HWLAB_CLOUD_WEB_EARLY_WORKSPACE_BOOTSTRAP` 的 promise；同一首屏不得再额外发起 `/auth/bootstrap`、`/auth/session` 或 `/v1/workbench/workspace` 来重复 hydrate 同一账号 workspace。
|
||||
- `/auth/workspace-bootstrap` 返回的 user/actor/workspace 只能作为首屏 seed。账号 workspace、session、conversation、provider profile 和 revision authority 仍在 `hwlab-cloud-api` / Postgres；浏览器 localStorage 仍只是 actor-bound cache，不能成为 authority。
|
||||
- 首屏允许加载当前工作台可见所需的 conversations、device-pods 和 live-builds 摘要，但 trace replay、`events?limit=120`、性能 summary、重型右侧面板、旧事件列表和非当前视口内容必须延后到首屏稳定后、用户展开后或具体业务需要时加载。
|
||||
|
||||
历史消息渲染必须优先保证首屏稳定，不得牺牲业务语义：
|
||||
|
||||
- 首屏 hydrate 里已经存在的历史 Code Agent 消息先以纯文本 fallback 展示，文本必须按 React 默认规则转义，不能执行 raw HTML。Markdown/GFM renderer 必须通过独立 `MarkdownRenderer` chunk 懒加载，首屏 LCP 观察窗口内不应加载该 chunk。
|
||||
- 首屏历史 final response 必须带稳定标识并用本地滚动边界约束高度，避免长历史回复继续驱动页面级 LCP/CLS。约束只影响首屏已有历史消息的初始展示，不得删除、截断、改写 conversation history，也不得影响新消息、用户显式打开的详情、trace/result 原始证据或首屏后 Markdown 升级。
|
||||
- 不得用隐藏历史消息、禁用 composer、删除 Code Agent 结果、减少真实业务能力或把历史 prompt 拼回下一轮消息的方式换取 LCP 数字。历史消息只用于 UI 展示和 trace/inspect 可见性，不能替代 AgentRun/Codex 原生 thread/resume。
|
||||
|
||||
测试和门禁只表达当前契约：旧同步 Markdown table 断言、旧 exact-string bundle guard、旧 layout smoke、旧 M3 evidence、旧 DEV/D601 browser gate 和与当前首屏目标无关的历史断言一律拆除，不迁移、不兼容保留。默认 `bun run --cwd web/hwlab-cloud-web check` 只保留轻量源码层保障：早发 workspace bootstrap 被消费、首屏历史 Markdown 延迟、历史 final response 有稳定高度边界、lazy renderer 仍能在升级后支持 Markdown/GFM 且 raw HTML 不执行。真实 LCP/CLS、请求数量和 RUM/Prometheus 改善必须通过专项 live browser closeout 验证。
|
||||
|
||||
## 内部架构
|
||||
|
||||
## Code Agent Timeout Model 与 Path Unification（与 #795 / #802 同步固化）
|
||||
@@ -116,6 +134,8 @@ Browser/layout/live smoke 属于显式专项诊断，不进入默认 Cloud Web c
|
||||
|
||||
WebUI 性能监控 issue 的 live closeout 不能只检查页面可见或 sidecar 存活；必须用 `19666` Web 入口触发真实浏览器 RUM 上报，再按 [spec-v02-observability-monitoring.md](spec-v02-observability-monitoring.md) 查询 `hwlab_webui_*` Prometheus 指标。LCP、Navigation Timing、业务 API timing、Long Task、CLS/INP/FID 近似只表达用户感知性能趋势，不替代 trace/result/inspect 的高基数排障证据。
|
||||
|
||||
Workbench 首屏性能 issue 的 closeout 必须用 repo-owned browser launcher / live DOM probe 或其专项扩展访问 `http://74.48.78.17:19666/#/workspace`，并记录 LCP、CLS、command input 可用性和首屏请求清单。若现有探针缺少 LCP/CLS 或 request counting，可先扩展该探针；不要在 issue closeout 里长期手写临时 Playwright launcher 或绑定偶然存在的 Playwright browser cache。
|
||||
|
||||
Cloud Web 顶级性能页是观测面，不是业务工作台。访问 `/performance` / `#/performance` 时不得初始化 Workbench store 的 workspace hydrate 或 live refresh，也不得触发 HWPOD node-ops、agent conversations、live-builds、system.health 等 workspace-only 请求。性能页只允许主动请求 `GET /v1/web-performance/summary` 和静态资源；如果需要调查 workspace 或 HWPOD 性能，必须从 workspace 原入口触发样本，而不是让性能页自己制造业务流量。
|
||||
|
||||
Live smoke 登录前必须等待前端 auth bootstrap 结束（`body[data-auth-state]` 不再是 `checking`，且 login submit 已可见/可用）再填表；登录后必须断言 URL query 不含 `username` 或 `password`，防止原生 form submit 泄漏凭据并伪装成 layout 超时。
|
||||
@@ -132,6 +152,10 @@ Cloud Web check 通过后仍需执行 bundle build 和 dist freshness 校验，
|
||||
|
||||
阅读 docs/reference/spec-v02-hwlab-cloud-web.md，然后用 cli 手动测试以下内容：访问 `http://74.48.78.17:19666/` 和 `/health/live`，确认页面和 health 均来自 v02 cloud-web，而不是 DEV/PROD 端口。
|
||||
|
||||
## T1.1
|
||||
|
||||
阅读 docs/reference/spec-v02-hwlab-cloud-web.md 和 docs/reference/spec-v02-observability-monitoring.md，然后用真实浏览器或 repo-owned live DOM probe 打开 `http://74.48.78.17:19666/#/workspace`。验收必须记录：LCP `<3s`、CLS `<0.1`、`#command-input` 可见且未 disabled、首屏只有一次 `/auth/workspace-bootstrap?projectId=prj_device_pod_workbench`，并且首屏观察窗口内 `/auth/bootstrap`、`/auth/session`、`/v1/workbench/workspace`、trace replay、`events?limit=120` 和 `MarkdownRenderer` chunk 均未出现。随后用同源 `/v1/web-performance/summary` 和受控 Prometheus 查询确认 `/workspace` WebUI RUM 样本存在；summary 仍处于 warming 时必须如实说明，不能用性能页自身样本替代 workspace 样本。
|
||||
|
||||
## T2
|
||||
|
||||
阅读 docs/reference/spec-v02-hwlab-cloud-web.md，然后用 cli 手动测试以下内容：先通过同源 `19666` 显式创建或选择 Code Agent session，再提交 Code Agent 短连接请求并轮询 result，确认请求经 cloud-web proxy 到 `hwlab-cloud-api`，且 trace 可回放；未创建或选择 session 的普通 send 必须返回 `session_required`，不能自动创建 session。
|
||||
@@ -205,6 +229,7 @@ runner pod 或 runner Job 丢失但 PVC 仍存在时，下一轮必须继续使
|
||||
| 规格项 | 状态 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| Workbench 首屏 | 已实现 | 当前页面直接进入工作台，不是 landing page。 |
|
||||
| Workbench 首屏性能契约 | 已实现 | 首屏通过 early workspace bootstrap、seed 复用、历史 Markdown 延迟升级和历史 final response 稳定高度边界降低 LCP/CLS；关闭性能 issue 前必须用 `19666/#/workspace` 原入口复测。 |
|
||||
| cloud-api 同源代理 | 已实现 | 受 route policy 控制；HWPOD node-ops POST 必须与 Cloud API route policy 对齐。 |
|
||||
| Code Agent UI/trace/result | 已实现 | 支持 provider profile、timeout、trace 轮询和取消。 |
|
||||
| Code Agent 无锁 composer | 已实现 | Web/CLI 共享 composer policy；运行中输入框保持可编辑并自动走 steer。 |
|
||||
|
||||
@@ -155,7 +155,7 @@ HWLAB v0.2 可声明 `PrometheusRule`，但规则只表达当前 v0.2 目标行
|
||||
|
||||
## T7
|
||||
|
||||
阅读本文和 [spec-v02-hwlab-cloud-web.md](spec-v02-hwlab-cloud-web.md)，然后用真实浏览器或 repo-owned live DOM probe 访问 `http://74.48.78.17:19666/`，触发 Cloud Web 首屏和同源 API 请求；随后通过受控 Prometheus 查询确认 `hwlab_webui_performance_sample_total{namespace="hwlab-v02"}` 有样本，且 `histogram_quantile` 能基于 `hwlab_webui_performance_duration_seconds_bucket` 计算 LCP 或 `api_request` p95。若 sidecar 基础 target 正常但 WebUI 指标无样本，不能关闭 WebUI 性能监控 issue。
|
||||
阅读本文和 [spec-v02-hwlab-cloud-web.md](spec-v02-hwlab-cloud-web.md)，然后用真实浏览器或 repo-owned live DOM probe 访问 `http://74.48.78.17:19666/#/workspace`，触发 Cloud Workbench 首屏和同源业务 API 请求；随后通过受控 Prometheus 查询确认 `hwlab_webui_performance_sample_total{namespace="hwlab-v02"}` 有样本，且 `histogram_quantile` 能基于 `hwlab_webui_performance_duration_seconds_bucket` 计算 `/workspace` LCP 或 `api_request` p95。若 sidecar 基础 target 正常但 WebUI 指标无样本，或者只有 `/performance` / `#/performance` 观测页自身样本，不能关闭 WebUI 性能监控 issue。
|
||||
|
||||
## 规格的实现情况
|
||||
|
||||
|
||||
Reference in New Issue
Block a user