HWLAB Cloud Workbench Reference

Cloud Workbench is the default user-facing frontend at http://74.48.78.17:16666/. It must serve the #99 workbench direction and the #108 UX constraints while respecting the M3 boundary from DC-DCSN-P0-2026-003.

Default Route

/ must show the Cloud Workbench, not Gate, status, help, or diagnostics.
The default first screen must not show Gate, BLOCKED, M0-M5, or acceptance-review copy. Those terms may remain in hidden/internal views.
Checked-in Gate reports and aggregator summaries are read-only support data. They must not be rendered as the default homepage or used to rename the default route away from Cloud Workbench.
Gate and diagnostics are secondary routes or right-panel support views.
/gate and /diagnostics/gate are internal diagnostic aliases served by the same Cloud Web app router. They may carry Gate, blocker, and M0-M5 evidence because they are not the default homepage.
http://74.48.78.17:16667/ remains the API/edge boundary.
Browser data sources are same-origin /v1, read-only /json-rpc, source reports, gate reports, and blocked reports.
Code Agent conversation 使用受控同源 POST /v1/agent/chat 通道。直接 API/edge 访问、source reports、本地 echo、mock replies 或 provider credential gaps 不能被写成真实 assistant reply；readiness 权威文档是 code-agent-chat-readiness.md.

Required Layout

The default workbench follows the #99 VS Code-style structure:

Region	Required role
Left	Activity rail, project/function/resource navigation, hardware resources.
Center top	Agent messages, execution process, trace, selected operation context.
Center bottom	Agent input or equivalent command composer.
Right top	BOX-SIMU, Gateway-SIMU, and patch-panel hardware state.
Right bottom	Controls, wiring, trusted records, Audit, and Diagnostics tabs.

Unavailable or future controls must be disabled with blocker context. The frontend must not imply generic direct hardware control.

UX Constraints

The #108 constraints are current baseline:

no page-level vertical scroll on the outer shell; scrolling belongs inside workbench panels;
user-visible UI text is Chinese except machine identifiers, protocol names, API paths, IDs, commits, endpoints, and source labels that need their exact spelling;
an internal help page exists, but it is not the homepage;
help content is maintained as web/hwlab-cloud-web/help.md and rendered by the frontend instead of being only a JS string.

Evidence And Labels

Visible runtime or evidence state must keep SOURCE, LOCAL, DRY-RUN, DEV-LIVE, and BLOCKED distinct. Loading the page from 16666 proves only that Cloud Web is reachable. It does not prove DB readiness, M3, M4, M5, or a hardware loop.

The frontend may show read-only DEV observations when they are tied to the exact route or component. It must not upgrade source fixtures, dry-run output, front-end state, or edge-only health into M3 DEV-LIVE.

如果 /v1/agent/chat 返回 provider_unavailable 或报告缺少 OPENAI_API_KEY，可见状态必须保持 BLOCKED/credential。在同源 DEV 请求按 Code Agent readiness 合同返回 completed 且非空的 assistant response 前，Workbench 不得暗示已有真实 assistant reply。

Lightweight Checks

Use the existing lightweight checks unless a task explicitly authorizes a heavier browser run:

node web/hwlab-cloud-web/scripts/check.mjs
node web/hwlab-cloud-web/scripts/build.mjs
node scripts/dev-cloud-workbench-smoke.mjs --static
node scripts/dev-cloud-workbench-smoke.mjs --dom-only --url http://74.48.78.17:16666/

The static smoke checks both sides of the route contract: / remains the user-facing workbench, while /gate and /diagnostics/gate remain available for internal diagnostics. This PR-class check is intentionally source-only and does not deploy, restart services, or run browser e2e.

Live checks against http://74.48.78.17:16666/ are read-only and must report blocked/skip instead of false green when the browser or network path is not available.

--dom-only keeps the runtime and web-asset identity preflight checks, then continues with read-only DOM/help validation for the deployed workbench even when identity drift blocks the full journey. It never sends POST /v1/agent/chat; the Code Agent journey is recorded as not_applicable and must not be used as a DEV-LIVE reply, Secret, mutation, or M3/M4/M5 acceptance claim.

Layout Smoke

scripts/dev-cloud-workbench-layout-smoke.mjs 是 #273 前端布局/遮挡护栏的 runner 入口。它使用 Playwright 覆盖 1366x768、1024x768 和 390x844 三档视口，检查 M3 控制区、Code Agent 输入区、右侧硬件/可信记录容器、当前 /gate 内部页、外层滚动锁和内部面板滚动。命中测试使用真实 Playwright 点击与 document.elementsFromPoint()；不得使用 force: true 或纯 DOM dispatch 绕过用户命中。

常用命令：

node scripts/dev-cloud-workbench-layout-smoke.mjs --static --report reports/dev-gate/dev-cloud-workbench-layout.json
node scripts/dev-cloud-workbench-layout-smoke.mjs --build --report reports/dev-gate/dev-cloud-workbench-layout-build.json
node scripts/dev-cloud-workbench-layout-smoke.mjs --live --url http://74.48.78.17:16666/ --report reports/dev-gate/dev-cloud-workbench-layout-live.json

报告字段必须能定位 status=pass|blocked|skip、viewport、selector、 failureType 和 artifact 路径。当前允许的 failureType 包括 overlap、 covered-hit-target、overflow、outer-scroll-regression、screenshot-diff 以及未上线覆盖项的 skip。脚本会保存右侧面板、M3 控制表单、Code Agent 输入区和 /gate 当前页局部截图，但不做整页像素 diff 门禁。

#287 的硬件状态标签化和 #288 的 /gate 单一大表如果尚未上线，layout smoke 只能把对应覆盖项记录为 skip，同时继续检查当前可见容器的溢出、遮挡和外层滚动。该 UI smoke 只能证明布局/可点击性护栏通过，不等于 M3 DEV-LIVE 硬件闭环通过，也不能替代 #227 的 DO/DI 功能验收。

Stable Sources

pikasTech/HWLAB#99: default Cloud Workbench direction.
pikasTech/HWLAB#273: Playwright layout/overlap smoke guardrail.
pikasTech/HWLAB#108: no outer scroll, Chinese UI, internal Markdown help.
code-agent-chat-readiness.md: Code Agent chat 同源 readiness 和 provider credential blocker 边界。
docs/cloud-web-workbench.md: detailed frontend contract.
docs/dev-deploy-apply.md: Cloud Web manual rollout path.

6.9 KiB Raw Blame History Unescape Escape