From 6418d7ace68d2ede2e5732963d692e62e7e9f465 Mon Sep 17 00:00:00 2001 From: Codex Date: Sun, 14 Jun 2026 12:46:24 +0000 Subject: [PATCH] docs: capture hwlab playwright validation path --- .agents/skills/unidesk-trans/SKILL.md | 10 ++++++++++ docs/reference/cli.md | 2 ++ docs/reference/hwlab.md | 6 ++++-- 3 files changed, 16 insertions(+), 2 deletions(-) diff --git a/.agents/skills/unidesk-trans/SKILL.md b/.agents/skills/unidesk-trans/SKILL.md index 8fa8c80e..a476f202 100644 --- a/.agents/skills/unidesk-trans/SKILL.md +++ b/.agents/skills/unidesk-trans/SKILL.md @@ -129,6 +129,16 @@ trans G14:/root/hwlab download /root/remote-file.txt ./local-file.txt 自动校验 SHA-256，结果中 `verified=true` 即完整性证明。 +### playwright（远端浏览器验收） + +```bash +trans D601 playwright --local-dir /tmp <<'PW' +playwright-cli screenshot https://example.com "$UNIDESK_PLAYWRIGHT_SCREENSHOT" --full-page +PW +``` + +`playwright` 读取 stdin heredoc，在目标 host/workload 上注入临时 `playwright-cli` wrapper，并把远端 run 目录中的截图/PDF 回传到本机 `--local-dir`，默认 `/tmp`。多步登录、创建 session、发送消息和 trace 截图应写在同一个 heredoc 中，并显式等待登录 API response 与稳定 selector；不要只靠宽泛 input selector 或页面标题判断登录成功。 + ### kubectl / logs（k3s 诊断） ```bash diff --git a/docs/reference/cli.md b/docs/reference/cli.md index a891afb6..00e66c64 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -150,6 +150,8 @@ PW 该入口只负责短生命周期 Playwright 执行和产物回传，不提供长驻浏览器 daemon。需要多步交互时，把步骤写在同一个 heredoc 内；helper 会在远端后台提交 job，并用短连接轮询 manifest，避免单次 SSH 透传超过 60 秒硬限制。需要保留远端证据时显式加 `--keep-remote`。 +登录态、会话发送和 trace 截图应在同一个 heredoc 中显式等待关键 HTTP response 和稳定 selector，不要只靠宽泛的 `input[type=text]` 或页面标题判断登录成功。对 HWLAB Cloud Web 这类表单，优先定位 `input[autocomplete="username"]`、`input[type="password"]`，并等待 `/auth/login` 返回 `authenticated=true` 后再进入 `/workbench`、创建 session、发送消息和截图。截图对比必须记录实际 URL/lane；例如 D601 `v0.3` 的 `https://hwlab.pikapython.com` 是 PK01 Caddy/FRP 域名入口，而 `http://74.48.78.17:19666/` 属于 G14 `v0.2`/旧 React 工作台对照，不能作为 D601 `v0.3` 的等价验收入口。 + ## Async Job State 长时操作采用 Fire-and-Forget 模式：CLI 创建 `.state/jobs/{jobId}.json`，后台进程执行真实命令，并将 stdout、stderr 分别写入 `.state/jobs/{jobId}.stdout.log` 与 `.state/jobs/{jobId}.stderr.log`。调用者通过 `bun scripts/cli.ts job status ` 查询进度和尾部输出。 diff --git a/docs/reference/hwlab.md b/docs/reference/hwlab.md index 8e6ee99d..31fe72ad 100644 --- a/docs/reference/hwlab.md +++ b/docs/reference/hwlab.md @@ -6,7 +6,8 @@ - UniDesk 指挥侧 workspace：`/root/unidesk`，固定使用 `master`，开始前执行 `git status` 和 `git pull --ff-only origin master`。 - HWLAB legacy G14 DEV/PROD 已退役；`G14`/`G14-gitops`、`hwlab-dev`/`hwlab-prod`、17666/17667 和 18666/18667 不再是当前 source/runtime truth。退役状态和执行入口是 `bun scripts/cli.ts hwlab g14 retirement status|plan|execute --confirm`，细则见 `docs/reference/g14.md`。 -- HWLAB 当前 G14 主阵地是 runtime lane：`v0.2` 固定分支为 `v0.2`，固定开发 workspace 为 `G14:/root/hwlab-v02`，固定 CI/CD source repo 为 `G14:/root/hwlab-v02-cicd.git`，固定 namespace 为 `hwlab-v02`，公网入口为 `http://74.48.78.17:19666/` 与 `http://74.48.78.17:19667/health/live`；`v0.3` 固定 namespace 为 `hwlab-v03`，公网入口为 `http://74.48.78.17:20666/` 与 `http://74.48.78.17:20667/health/live`；`v0.3+` 由 `hwlab nodes --node G14 --lane vNN` 与 `config/hwlab-node-lanes.yaml` 管理。 +- HWLAB 当前 G14 主阵地是 runtime lane：`v0.2` 固定分支为 `v0.2`，固定开发 workspace 为 `G14:/root/hwlab-v02`，固定 CI/CD source repo 为 `G14:/root/hwlab-v02-cicd.git`，固定 namespace 为 `hwlab-v02`，公网入口为 `http://74.48.78.17:19666/` 与 `http://74.48.78.17:19667/health/live`；G14 `v0.3` 固定 namespace 为 `hwlab-v03`，公网入口为 `http://74.48.78.17:20666/` 与 `http://74.48.78.17:20667/health/live`；`v0.3+` 由 `hwlab nodes --node G14 --lane vNN` 与 `config/hwlab-node-lanes.yaml` 管理。 +- D601 node-scoped `v0.3` 只在用户明确要求 D601 v0.3、公网域名、PK01 Caddy/FRP 或 D601 硬件桥接验证时使用；配置真相是 `config/hwlab-node-lanes.yaml` 的 `nodes.D601` / `lanes.v03.targets.D601`，公网入口是 `https://hwlab.pikapython.com`。不要把 `http://74.48.78.17:19666/` 当成 D601 v0.3 入口，它属于 G14 `v0.2` / 旧 React 工作台对照。 - HWLAB 项目内长期规则入口仍以目标 repo 的 `AGENTS.md` 为准。进入 G14 runtime lane 分布式开发、切换任务、恢复中断或上下文压缩后，必须重新读取目标 workspace 的规则文件；不能只凭主 server 的压缩上下文继续操作。 - 每次开始 G14 runtime lane 工作前必须通过 UniDesk SSH 桥检查目标 workspace，例如 `trans G14:/root/hwlab-v02 script -- 'git status --short --branch && git remote -v'`；若不满足目标 lane 预期，先修正 workspace，不能继续开发、render、polling 或部署。 - G14 k3s 操作必须使用 route 语法 `G14:k3s`，例如 `trans G14:k3s kubectl get pods -n hwlab-v02`；禁止写成 `ssh G14 k3s ...`。第一个 route token 必须定位分布式目标，后续 token 才是 operation。 @@ -29,6 +30,7 @@ - 退役 G14 DEV/PROD 前端/API 入口曾使用 `http://74.48.78.17:17666/`、`http://74.48.78.17:17667/health/live`、`http://74.48.78.17:18666/` 和 `http://74.48.78.17:18667/health/live`；这些端口不再作为当前 HWLAB runtime 证据。 - 当前 G14 `v0.2` 前端/API 入口固定为 `http://74.48.78.17:19666/` 和 `http://74.48.78.17:19667/health/live`，只能指向 `hwlab-v02` namespace。 +- 当前 D601 `v0.3` 前端/API 入口固定为 `https://hwlab.pikapython.com`，只能按 `config/hwlab-node-lanes.yaml` 中的 `pk01-caddy-frp` publicExposure 验证；域名侧浏览器验收比裸 IP 或旧端口更能覆盖 Caddy、FRP、同源 cookie 和 Vue workbench 路由。 - D601 legacy DEV 前端/API 入口曾使用 `http://74.48.78.17:16666/` 和 `http://74.48.78.17:16667/health/live`；只在显式 D601 legacy 排障或迁移对照时使用，不能作为当前 HWLAB DEV 运行面证据。 - 旧公网 `:6666` 和 `:6667` 不是浏览器验收入口；内部 k3s service 仍可使用 `6667` 作为服务端口。 - 当前 G14 runtime lane 入口由 G14 侧公开代理承担；不要把 master 上的其他 UniDesk frontend/backend-core 路径误判为 HWLAB 前端。D601 legacy `16666/16667` 和 retired G14 DEV/PROD 端口的 FRP 说明只用于历史对照。 @@ -41,7 +43,7 @@ HWLAB 公网 FRP server 由 master server 上的 `hwlab-frps-dev` 容器承担 当前 HWLAB FRP server allowlist 至少应覆盖 active runtime lane 端口（例如 G14 `v0.2` `19666/19667` 和 `v0.3` `20666/20667`）以及仍被明确使用的维护端口。Legacy `16666/16667` 和 retired G14 DEV/PROD `17666/17667`、`18666/18667` 只作为历史对照，不应作为新增 runtime 入口要求。新增端口必须对应一个明确的 namespace/runtime 入口，不能把大范围端口段作为默认放行策略。 -FRP 维护验证顺序是：确认 `hwlab-frps-dev` 容器仍挂载 `/opt/hwlab-frp/frps.dev.toml`；重启后用 `ss -ltnp` 或等价只读命令确认 `frps` 正在监听 `7000` 和目标公网端口；再在目标 namespace 查看 `frpc` 日志，确认对应 proxy `start proxy success`；最后验证 active runtime lane 入口。`v0.2` 验证使用 `http://74.48.78.17:19666/` 与 `http://74.48.78.17:19667/health/live`；`v0.3` 验证使用 `http://74.48.78.17:20666/` 与 `http://74.48.78.17:20667/health/live`。 +FRP 维护验证顺序是：确认 `hwlab-frps-dev` 或 `config/hwlab-node-lanes.yaml` 指定的 publicExposure 入口仍挂载/渲染目标配置；重启或 apply 后用等价只读命令确认 FRP/Caddy 正在监听目标公网端口或 hostname；再在目标 namespace 查看 `frpc` 日志，确认对应 proxy `start proxy success`；最后验证 active runtime lane 入口。G14 `v0.2` 验证使用 `http://74.48.78.17:19666/` 与 `http://74.48.78.17:19667/health/live`；G14 `v0.3` 验证使用 `http://74.48.78.17:20666/` 与 `http://74.48.78.17:20667/health/live`；D601 `v0.3` 验证使用 `https://hwlab.pikapython.com`。 FRP 文档、issue 和日志只能记录端口、容器名、ConfigMap 名、Secret 对象/key 是否存在和健康摘要；不得记录 Secret value、provider token、完整 DB URL、Codex auth JSON 或其他凭据内容。