docs: record web-probe script timeout guidance

2026-06-19 12:08:54 +00:00
parent bec42fc0fa
commit ca2784bc12
1 changed files with 1 additions and 0 deletions
@@ -72,6 +72,7 @@ JS
 约束：

 - `web-probe script` 不运行默认探针，必须通过 stdin heredoc 或 `--script-file <path>` 提供脚本；只需要 repo-owned 标准 DOM probe 时使用 `web-probe run`。
+- 自定义 `web-probe script` 仍运行在 UniDesk `trans` 60s 最外层短连接约束内；能在一轮内完成的 P4 验收优先把 `--command-timeout-seconds` 控制在 55 秒以内，并减少无界 selector/network 等待。确需等待更久时，改用 `web-probe run` 的异步 job/status 语义，或把动作拆成“提交/采样/截图/状态读取”多次短 probe。若输出出现 `UNIDESK_SSH_RUNTIME_TIMEOUT` 但同时恢复了 `reportPath`、`reportSha256`、screenshots 或 DOM steps，先按远端报告判断脚本/页面实际状态；最终关闭证据仍优先用一次未触发短连接超时的 bounded rerun。
 - stdin heredoc 与 `--script-file` 都按 ES module 加载，脚本必须导出 `export default async ({ page, gotoStable, recordStep, ... }) => { ... }`；不要在模块顶层直接写 `return`。失败为 `Illegal return statement`、`does not provide an export named default` 或 finalUrl 仍是 `about:blank` 且 stepCount=0 时，先按 probe 脚本入口误用处理，不要归因成 Cloud Web 行为失败。
 - web-probe 由 UniDesk CLI 从 YAML 声明的 bootstrap admin sourceRef 读取凭据并建立同源 `hwlab_session`；脚本不得自行读取、打印或复制 Web 登录凭据、cookie、token 或完整 API key。
 - 脚本构造 URL 时使用 `new URL(path, baseUrl).toString()`；不要拼出 `//v1/...`。