diff --git a/.agents/skills/unidesk-webdev/SKILL.md b/.agents/skills/unidesk-webdev/SKILL.md index 89a03ac9..b53265d0 100644 --- a/.agents/skills/unidesk-webdev/SKILL.md +++ b/.agents/skills/unidesk-webdev/SKILL.md @@ -10,6 +10,7 @@ description: UniDesk Web 开发与浏览器验证技能。用户处理 UniDesk/H ## 快速规则 - 线上 Web bug、Workbench、Performance、前端状态投影、截图、fake-server 和 web-probe 任务必须先用本技能。 +- Web-probe 正式 CLI 入口是 `bun scripts/cli.ts web-probe ...`；旧 `hwlab nodes web-probe` 已移除，只能按 CLI 提示迁移，不要在 issue 或长期文档中继续记录旧入口。 - 涉及 Web 哨兵、`web-probe sentinel`、`monitor.pikapython.com`、定期/周期巡检或新建巡检时，必须同时加载 `$unidesk-monitor`。 - 真实用户入口验证优先；源码检查、构建通过或截图局部正常不能替代原入口验收。 - HWLAB Cloud Web/Workbench 的 closeout web-probe 必须打已经通过 CI/CD 部署的 node/lane 公网 origin，例如 NC01/v03 的 `https://hwlab.pikapython.com`；本地 fake-server、localhost、dist 静态服务和临时 `--url` 只能作为开发 preflight 证据，不能替代 PR 合并、部署后的公网 web-probe 验收。 diff --git a/docs/reference/cli.md b/docs/reference/cli.md index d11f254d..8122a7a8 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -24,7 +24,7 @@ GitHub 受控入口的命令用法由 `$unidesk-gh` 维护，长期模块边界 G14/D601 v03 的 bootstrap admin password 是 HWLAB runtime Secret 生命周期的一部分，必须收敛到 `config/hwlab-node-lanes.yaml` 的 `bootstrapAdmin` 声明与受控 `hwlab nodes secret status|ensure --node --lane v03 --name hwlab-v03-bootstrap-admin` CLI。明文只能存在于 Git 忽略、owner-only 的 `.state/secrets/...` sourceRef 文件；CLI 在本地把明文转换为 HWLAB 兼容 password hash，只向运行面同步 `password-hash`，并在输出中只披露 sourceRef、sourceKey、target Secret/key、presence、byte count、fingerprint、mutation 与后续命令。`secret ensure --force` 只用于明确需要按 YAML sourceRef 重灌 bootstrap admin hash 并重启 Cloud API 的受控恢复场景，默认 ensure 不做强制重灌；不要把人工生成 hash、手工写 k8s Secret 或原生 `kubectl rollout` 沉淀为长期入口。 -`hwlab nodes web-probe run|script --node --lane ` 是 HWLAB Cloud Web 线上 DOM/Playwright 验收的受控入口；CLI 负责从 YAML 解析 workspace、public URL 和 bootstrap admin sourceRef，并只输出 redacted 凭据状态、artifact path/hash、readiness、`probe.summary` 和失败分类。`run` 使用 repo-owned 标准 DOM probe；`script` 不运行默认探针，必须通过 stdin heredoc 或 `--script-file ` 提供调用者脚本。`run --message ...` 未显式设置 trace 参数时会做轻量 trace 采样，`script` helper 可用 `recordStep` / `safeFetchJson` / `fetchApiMatrix` 保留失败前的结构化 partial evidence，完整 redacted 报告通过 `reportPath`/`reportSha256` 展开。具体 Web 开发、fake-server Playwright、fixture 脱敏、`web-probe script` helper、截图和 Workbench/Performance 判定口径统一见 `$unidesk-webdev`，本 CLI 参考不再维护第二套操作面。 +`web-probe run|script --node --lane ` 是 HWLAB Cloud Web 线上 DOM/Playwright 验收的受控入口；旧 `hwlab nodes web-probe` 已移除，调用方应迁移到 `bun scripts/cli.ts web-probe ...`。CLI 负责从 YAML 解析 workspace、public URL 和 bootstrap admin sourceRef，并只输出 redacted 凭据状态、artifact path/hash、readiness、`probe.summary` 和失败分类。`run` 使用 repo-owned 标准 DOM probe；`script` 不运行默认探针，必须通过 stdin heredoc 或 `--script-file ` 提供调用者脚本。`run --message ...` 未显式设置 trace 参数时会做轻量 trace 采样，`script` helper 可用 `recordStep` / `safeFetchJson` / `fetchApiMatrix` 保留失败前的结构化 partial evidence，完整 redacted 报告通过 `reportPath`/`reportSha256` 展开。具体 Web 开发、fake-server Playwright、fixture 脱敏、`web-probe script` helper、截图和 Workbench/Performance 判定口径统一见 `$unidesk-webdev`，本 CLI 参考不再维护第二套操作面。 `web-probe script` 的 issue closeout 优先引用顶层 `issueEvidence` 或 `summary.issueEvidence`，其中包含 redacted `result`、最近 steps、lastStep、script/report SHA 和截图摘要；完整调查才展开 `probe.script.result`、`probe.steps` 或 `reportPath`，避免把同一证据在 stdout、summary 和 report 多层重复粘贴。 diff --git a/docs/reference/hwlab.md b/docs/reference/hwlab.md index 6ac6ff13..d281a0c2 100644 --- a/docs/reference/hwlab.md +++ b/docs/reference/hwlab.md @@ -100,7 +100,7 @@ Workbench session lifecycle、空 session 后台回收、archived/deleted deep l ### Web Live DOM Probe 验收 -`scripts/web-live-dom-probe.mjs` 和 UniDesk `hwlab nodes web-probe run|script` 是 Cloud Web 原入口 DOM 验收底座。登录 sourceRef、同源 page helper、URL 构造、readiness、Trace 采样、浏览器噪声分类和 artifact 规则统一见 `$unidesk-webdev`；本文件不复制使用细则，避免与 UniDesk WebDev 操作面分叉。只修改该 helper 时属于无服务交付，按目标 HWLAB repo `AGENTS.md` 选择直接提交或 PR，关闭证据写明 `rollout=not-applicable`。 +`scripts/web-live-dom-probe.mjs` 和 UniDesk `web-probe run|script` 是 Cloud Web 原入口 DOM 验收底座；正式 CLI 入口是 `bun scripts/cli.ts web-probe ...`，旧 `hwlab nodes web-probe` 已移除。登录 sourceRef、同源 page helper、URL 构造、readiness、Trace 采样、浏览器噪声分类和 artifact 规则统一见 `$unidesk-webdev`；本文件不复制使用细则，避免与 UniDesk WebDev 操作面分叉。只修改该 helper 时属于无服务交付，按目标 HWLAB repo `AGENTS.md` 选择直接提交或 PR，关闭证据写明 `rollout=not-applicable`。 Cloud Web runtime config 或 YAML-first UI policy 类修复关闭前，除源码/fake-server 证据外，还必须证明选中 node/lane 的配置已进入部署链路：YAML 字段、GitOps render/env、Deployment 或 Pod env、public origin DOM/API 证据要分别记录。缓存、Pod 滚动和 browser helper 返回包装对象的细节由 `$unidesk-webdev` 规定；本文件只要求这些层次不能混为一个结论。 @@ -220,7 +220,7 @@ CaseRun `summary.md`、`result.json` 和 registry aggregate 是阅读索引， ### NC01 v0.3 Web CaseRun 最小闭环 -NC01 `v03` 的 Web CaseRun 最小闭环是 Cloud Web -> Cloud Web proxy -> Cloud API `/v1/caserun*` -> built-in/configured case repo -> HWPOD node ops -> Python UI node/HWPOD -> Keil。验证 Web 用户入口时使用 UniDesk `bun scripts/cli.ts hwlab nodes web-probe script --node NC01 --lane v03`，让 `config/hwlab-node-lanes.yaml` 中的 `webProbe.defaultOrigin` 选择内部 IP 或公网入口；只有显式临时覆盖时才传 `--url`，不要把内部 IP 写进脚本或 issue 作为长期默认。 +NC01 `v03` 的 Web CaseRun 最小闭环是 Cloud Web -> Cloud Web proxy -> Cloud API `/v1/caserun*` -> built-in/configured case repo -> HWPOD node ops -> Python UI node/HWPOD -> Keil。验证 Web 用户入口时使用 UniDesk `bun scripts/cli.ts web-probe script --node NC01 --lane v03`，让 `config/hwlab-node-lanes.yaml` 中的 `webProbe.defaultOrigin` 选择内部 IP 或公网入口；只有显式临时覆盖时才传 `--url`，不要把内部 IP 写进脚本或 issue 作为长期默认。 Web-probe short script 仍受 60s 级别的交互超时约束；长 CaseRun 应拆成“启动 run”和“轮询 run”两段，或使用 observe/专用归档入口承接下载、UART 和 Arm2D stage D 这类长证据链。Cloud Web 对 GET `/v1/*` 可以走通用代理，但 POST/写操作必须在 Cloud Web route policy 中显式登记认证代理路由；新增 CaseRun 写入口时不能只验证 Cloud API 直连。