Code Queue Review
112 lines
5.1 KiB
Markdown
112 lines
5.1 KiB
Markdown
# 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](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](code-agent-chat-readiness.md) 合同返回 completed
|
||
且非空的 assistant response 前，Workbench 不得暗示已有真实 assistant reply。
|
||
|
||
## Lightweight Checks
|
||
|
||
Use the existing lightweight checks unless a task explicitly authorizes a
|
||
heavier browser run:
|
||
|
||
```sh
|
||
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.
|
||
|
||
## Stable Sources
|
||
|
||
- [pikasTech/HWLAB#99](https://github.com/pikasTech/HWLAB/issues/99): default
|
||
Cloud Workbench direction.
|
||
- [pikasTech/HWLAB#108](https://github.com/pikasTech/HWLAB/issues/108): no
|
||
outer scroll, Chinese UI, internal Markdown help.
|
||
- [code-agent-chat-readiness.md](code-agent-chat-readiness.md): Code Agent
|
||
chat 同源 readiness 和 provider credential blocker 边界。
|
||
- [docs/cloud-web-workbench.md](../cloud-web-workbench.md): detailed frontend
|
||
contract.
|
||
- [docs/dev-deploy-apply.md](../dev-deploy-apply.md): Cloud Web manual rollout
|
||
path.
|