docs: record hwlab web probe runtime pitfalls

docs/reference/hwlab.md

@@ -82,6 +82,8 @@ AgentRun terminal `failed`、`blocked` 或 `canceled` 也是最终结果，不
 
 `scripts/web-live-dom-probe.mjs` 是 Cloud Web 原入口的 DOM 级等价验收 helper。它必须在 issue/CLI 选中的 node/lane workspace 上运行，并打到同一 public origin；例如 D601 `v0.3` 使用目标 workspace 的脚本和 `https://hwlab.pikapython.com`，不能在 master server 本地跑浏览器 smoke，也不能用旧端口或其他 lane fallback。跨 node/lane 的日常指挥验收优先使用 UniDesk `bun scripts/cli.ts hwlab nodes web-probe run --node <node> --lane <lane>`，由该入口解析 workspace、public origin 和 Web 登录 sourceRef，再把凭据作为一次性 stdin/env 注入目标 helper。需要自定义 Playwright route/intercept、延迟 API、读取 in-flight DOM 或生成专项 artifact 时，使用 `bun scripts/cli.ts hwlab nodes web-probe script --node <node> --lane <lane> <<'JS' ... JS`；该入口由 UniDesk 先通过同源 `/auth/login` 建立 `hwlab_session`，脚本只接收已认证的 `browser/context/page/baseUrl` 和 artifact helper。只修改该 helper 时属于无服务交付，按目标 HWLAB repo `AGENTS.md` 选择直接提交或 PR，关闭证据写明 `rollout=not-applicable`。
 
+`web-probe script` 注入的 `baseUrl` 是 public origin，并且可以带尾随 `/`。自定义脚本构造 API 或页面 URL 时必须使用 `new URL(path, baseUrl).toString()`；不要用 `` `${baseUrl}${path}` `` 直接拼接以 `/` 开头的 path，否则会生成 `//health`、`//v1/...` 这类双斜杠路径，可能被 edge-proxy 当成上游绝对 URL/异常代理路径处理，造成与真实浏览器页面不同的 502 或误判。
+
 Web 登录凭据必须从目标 node/lane 的受控 source 解析并作为一次性进程环境注入，例如先用 `bun scripts/cli.ts hwlab nodes secret status|ensure --node <node> --lane <lane> --name hwlab-v03-bootstrap-admin` 确认 bootstrap admin sourceRef，再运行受控 `hwlab nodes web-probe run` / `hwlab nodes web-probe script`。目标 host 没有 owner-only source 文件时，受控入口应快速返回 `web_login_secret_missing`；不要依赖脚本历史默认密码，不要把凭据复制到目标 host、shell 启动文件、issue、日志或 Git 文档。若 sourceRef/fingerprint 已确认但 public `/auth/login` 仍不接受 source 密码，应先区分 API rollout、user-billing 回退和用户表状态；只有明确需要按 YAML source 重灌 bootstrap admin hash 时，才使用受控 `secret ensure --confirm --force`。
 
 排查 probe 登录误报时，优先看 JSON 里的 `actions`、`dom.authState`、`finalUrl`、`failureDom` 和 `dom.requiredSelectors`。新版登录页 fallback 必须先等待真实登录 surface（`#workspace`、legacy id 或 `.login-card input`）再判断 input count；提交前还要确认表单值已经落到 DOM，例如 `actions.login.valuesReady=true`。只在 `authState=login` 的瞬间立即 `count()`，或在 Vue 尚未更新 input value 时 submit，都可能把前端填表时序误判成凭据错误。关闭 Workbench 登录/DOM helper 问题时，证据至少包含原命令、目标 URL/lane、登录 `selectorMode`、`valuesReady`、`finalUrl` 和 `workspace`/`commandInput` 等关键 selector 结果。
@@ -138,7 +140,7 @@ FRP 文档、issue 和日志只能记录端口、容器名、ConfigMap 名、Sec
 - 在 `D601:win` 上启动 `hwlab-gateway`，作为 71-FREQ/ConStart/Keil/串口资源的外部 host bridge。gateway 通过公网或受控网络出站连接选中 node/lane 的 cloud-api，注册稳定的 `gatewaySessionId`、`resourceId` 和 `capabilityId`。
 - `hwlab-gateway` 是 Windows 长驻 outbound poll 进程，不能用 `trans D601:win cmd start ...` 或 PowerShell `Start-Process` 直接挂在一次性 trans/tran 会话下；这种启动方式可能继承输出句柄或被 provider 按子进程树等待，导致 trans/tran 卡住并阻塞后续 provider session。临时实验也应通过 Windows Task Scheduler、Windows Service、NSSM、PM2 service 或等价 detached launcher 启动，`trans` 只负责触发和读取状态；通用规则见 `docs/reference/windows-passthrough.md`。
 - D601 Windows gateway 的最小配置必须来自 profile 或环境变量，核心字段是 `HWLAB_GATEWAY_CLOUD_URL=<active-runtime-lane-cloud-api>`、`HWLAB_GATEWAY_ID`、`HWLAB_GATEWAY_SESSION_ID`、`HWLAB_GATEWAY_RESOURCE_ID`、`HWLAB_GATEWAY_CMD_CAPABILITY_ID`、`HWLAB_GATEWAY_CMD_EXEC_ENABLED=1`、`HWLAB_GATEWAY_DEMO_OPEN=1`、`HWLAB_GATEWAY_MAX_INFLIGHT` 和 `HWLAB_GATEWAY_CMD_TIMEOUT_MS`。这些值用于声明能力和执行边界，不得散落在 device-agent 代码里。
-- device-agent 访问集群内 cloud-api 时优先使用选中 runtime lane 的 Service DNS。Node/undici `fetch` 会按 Fetch bad-port 规则拒绝 `6667`，因此 Node 实现必须使用 `node:http`/`node:https`、已有 repo-owned HTTP helper，或改用不触发 bad-port 的受控代理端口。
+- device-agent 访问集群内 cloud-api 时优先使用选中 runtime lane 的 Service DNS；Node 实现访问 `6667` 时遵循 Node/Lane 运行面口径里的 bad-port 规则，不为 device-agent 单独维护另一套例外。
 - 71-FREQ 的 device profile 必须配置化保存，至少包含工程根目录、Keil project/target、默认串口波特率、gateway/resource/capability 选择器和 workspace 根。不得把 `F:\Work\ConStart`、工程名、串口号或 probe UID 硬编码进 device-agent 镜像。
 - 最小验收顺序是：选中 node/lane cloud-api `/health/live` ready；D601 Windows 能访问该 lane 的 public `/health/live`；D601 `hwlab-gateway` 注册后 cloud-api 能看到 gateway session/resource/capability；`device-agent-71-freq` `/health` 和 `/skills` 返回 ready；通过 device-agent 发起一条只读或 `echo` 级 gateway shell operation，并返回 operation/evidence/trace 摘要。
 - 这个模型只证明 `device-agent Pod -> 选中 lane cloud-api -> D601 hwlab-gateway -> Windows host` 的控制链路。Keil 编译下载、串口日志抓取和 workspace CRUD 可以作为后续 device-agent skill 子命令逐步接入；未接入前不能把 device-agent 标成完整 71-FREQ 硬件代理。
@@ -158,7 +160,7 @@ HWLAB 当前真实 runtime 由 issue/CLI 选中的 node/lane 决定。只读观
 trans D601:k3s kubectl -n hwlab-v03 get deploy,svc,pod -o wide
 ```
 
-`hwlab-cloud-api` 和 `hwlab-edge-proxy` 在集群内可使用 `6667` Service 端口；对外入口以选中 target 的 publicExposure/public URL 为准。G14 local details 见 `docs/reference/g14.md` 和 G14 节点 `/root/docs/hwlab-g14-workspace.md`；D601 node-scoped target 以 `config/hwlab-node-lanes.yaml` 的 `nodes.D601` 和 `lanes.v03.targets.D601` 为准。
+`hwlab-cloud-api` 和 `hwlab-edge-proxy` 在集群内可使用 `6667` Service 端口；对外入口以选中 target 的 publicExposure/public URL 为准。Node/Bun/undici 的 Fetch 实现会按 Fetch bad-port 规则拒绝 `6667`，因此任何需要代理、转发、探测或服务间访问该端口的 Node 实现都必须使用 `node:http`/`node:https`、已有 repo-owned HTTP helper，或改用不触发 bad-port 的受控代理端口；不要把 Fetch bad-port 造成的 `fetch failed` / 502 误判为 Service DNS、PVC、数据库或 trace 数据缺失。G14 local details 见 `docs/reference/g14.md` 和 G14 节点 `/root/docs/hwlab-g14-workspace.md`；D601 node-scoped target 以 `config/hwlab-node-lanes.yaml` 的 `nodes.D601` 和 `lanes.v03.targets.D601` 为准。
 
 D601 原生 k3s 是 D601 node-scoped runtime 的正式控制面；D601 legacy 对照也使用同一 native k3s guard。任何 D601 k3s 操作都必须显式使用 UniDesk route `D601:k3s` 或等价的 `/etc/rancher/k3s/k3s.yaml`，不能使用裸默认 kubeconfig：