# Web Probe

- 使用 `web-probe` 采集真实用户入口证据：
  - 交互流程使用 `observe start`、`observe command`、`observe collect` 和 `observe analyze`；
  - `run` 或 `script` 只用于有界探测和 smoke；
  - 收尾证据引用 observer id、command id、artifact/report SHA、screenshot SHA 和关键有界字段。
- 一次性截图的导航完成条件：
  - `web-probe screenshot` 默认使用 `domcontentloaded`，适用于持续 SSE、WebSocket 和长轮询页面；
  - 只有页面能够稳定进入网络静默时，才显式传 `--wait-until networkidle`；
  - 需要业务 DOM 或交互判定时继续使用 typed readiness 或 observer，不能把导航完成当作业务通过。
- L1 native Web 公网 readiness：
  - 使用 `bun scripts/cli.ts web-probe native-readiness --node <node> --lane <lane> --profile <profile>`；
  - 固定 HTTPS origin 来自 lane 的 `nativeDevelopment.publicExposure`，页面与判据来自 `nativeReadinessProfiles`；
  - 单次命令必须同时判定 DOM 挂载、基础交互、`console.error`、`pageerror`、关键失败响应和截图；
  - 顶层 `status=pass` 才能向用户披露入口可用，`blocked` 必须继续修复或报告 browser readiness blocker；
  - Workbench profile 必须等待 session rail 结束加载；存在 session 时点击首个真实 session，并等待对话内容或明确空态可见后再截图；
  - 停在“加载中”的截图只能证明 shell 挂载，不能关闭业务可用性或视觉问题；
  - 已报告的视觉层级问题使用 profile 的 `geometryChecks` 输出匹配数量、实际尺寸和 YAML 预算，截图与几何判定必须同时通过；
  - 命令不接受 `--url` 或 `--origin`，避免绕过 owning YAML 选择其他运行面。
  - L1 浏览器必须打开 owning YAML 解析出的固定 HTTPS origin；`127.0.0.1`、`localhost`、IP、port 和临时 `--url` 只能作为本机 preflight，不能替代 L1 readiness。
  - L1 Workbench 长程观察使用 `bun scripts/cli.ts web-probe observe start --node <node> --lane <lane> --origin native --target-path /workbench`；native origin 只读取同一 owning YAML 的 Workbench `publicExposure.publicBaseUrl`，不得回退部署态 public origin。
- Cloud Console 页面矩阵：
  - 使用 `bun scripts/cli.ts web-probe console-verify --node <node> --lane <lane> --origin internal|public --profile <profile>`；
  - 配置真相位于 `config/hwlab-node-lanes.yaml#templates.*.webProbeWorkbench.consoleVerificationProfiles`；
  - 配置拥有 route profile、viewports、稳定 selector、可选产品工作流、等待和证据上限；
  - 命令复用既有认证、semantic origin、远程浏览器、`MemAvailable` 启动门禁、report recovery 和截图合同；
  - 默认 profile 由同一 YAML 的 `defaultConsoleVerificationProfile` 选择，CLI `--profile` 只做显式 profile 选择；
  - 该命令用于已部署页面人工 closeout，不作为 CI/CD gate，不替代 Workbench Kafka、Trace 和性能专项 validator；
  - 成功或失败均以有界 `issueEvidence`、report SHA、screenshot SHA 和失败摘要收口，不再重复创建 `.state/probes/*.mjs`。
  - AgentRun 思维导图的聚焦验收使用 `--profile agentrun-tree`：
    - 直接恢复 `/agents/runs?view=tree` 并等待 `.agent-mind-map`；
    - 先采集 `1920x1080` 纯树图截图；
    - 再按 YAML `selection` 合同用键盘选择首个 Run；
    - 校验 SVG 路径长度与 computed stroke/opacity/visibility、Inspector 与工作区边界、标题/页签/正文几何；
    - 最后采集 Inspector 打开状态截图。
  - AgentRun 树图刷新稳定性复现与判定：
    - 连续执行至少三轮同一 `console-verify` 命令；每轮保留 report 和两张截图的 SHA，不要只凭单张截图判断。
    - 对比每轮 `edgeCount`、`visibleEdgeCount`、首条路径长度、Inspector 几何、页面高度、横向溢出和 EventSource 数量。
    - 三轮都应保持单一产品 EventSource、相同关系图几何和相同 Inspector 边界；状态文本或截图 SHA 因实时数据变化不同不单独判定为抖动。
    - 若树图只在 Kafka live 更新后抖动，先检查关系输入是否沿用“最近活动”顺序，以及 dagre 或 `fitView` 是否被每次 reducer 更新触发；树节点顺序应由稳定 identity 决定，自动适配视图只允许首次有效图形加载执行。
    - 若 EventSource 数量仅因 `HTTP2_PROTOCOL_ERROR`、`NETWORK_CHANGED` 等网络重连暂时增加，必须同时读取报告中的 console/response 错误和连接 phase，区分历史请求统计与同时存活的产品订阅，不要把瞬时网络故障误判为前端重复订阅。
- WebProbe 远程命令错误可见性：
  - 默认文本输出必须在独立 `COMMAND_OUTPUT` 段完整展示已经脱敏并限长的 `stderrTail` 与 `stdoutTail`；
  - 摘要表可以继续提供单行预览，但不得用表格宽度裁剪替代完整的有界错误证据；
  - `exitCode` 非零且命令输出为空时按可观测性故障处理，先修复探针输出合同，再判断浏览器或业务根因。
  - 产品 smoke 已解析凭据，但 UI 登录的首次导航因浏览器关闭而失败时：
    - 仅在 `status=0`、登录响应为空、步骤数为零且认证请求与 API 响应均未到达时分类为 `browser-runtime-closed`；
    - 默认有界输出同时披露 `credentialResolved`、`requestReached`、`apiResponseReached`、错误摘要及报告路径和 SHA；
    - 已发出登录请求、已有 API 响应或收到真实认证状态码时继续按认证失败处理，不得降级门禁。
- Workbench 与 Performance 调查规则：
  - 先使用专用 collect/analyze view；
  - 不要先检索原始 JSONL artifact。
- Workbench 隔离 Kafka debug 重放规则：
  - 使用 `observe command --type validateWorkbenchKafkaDebugReplay`；
  - 命令复用 observer 的 semantic origin 和当前 session；
  - topic、group prefix、完成超时、产品/调试 SSE 路径和请求静默窗口来自 owning YAML；
  - 新 UI 同时报告分层重放计数、typed phase/code、source-authority Trace 行和原始 HWLAB Event 有界计数；
  - 原始事件标签必须复用同页产品 EventSource，切换标签不得新增产品 SSE 请求；
  - 旧 UI 缺少新 DOM 合同时报告 `legacy-ui`，不伪造新合同；
  - 禁止通过 URL/IP 或一次性脚本替代该命令。
- Workbench 产品 Trace 可读性规则：
  - 使用 `observe command --type validateWorkbenchTraceReadability`；
  - 功能开关与全部等待/轮询/稳定窗口由独立 owning YAML 提供；
  - 命令只读取 `#conversation-list` 内的当前产品卡片，排除隔离 debug panel；
  - 只接受新运行卡片，命中后按 traceId 固定定位，不回退旧终态卡片；
  - 报告必须区分命令前默认展开状态和命令驱动展开状态；
  - 默认运行中可读、source-authority 行和终态保留必须分别成立；
  - 窗口化 Trace 以 event count 和 source sequence 边界前进替代可见行身份交集；
  - 失败仍保留有界 DOM 诊断、report SHA 和 screenshot SHA。
