// SPEC: PJ2026-01060505 Workbench Performance draft-2026-06-17-p0. // SPEC: PJ2026-01060508 Web哨兵 draft-2026-06-26-p9-multi-web-probe-sentinel. // Responsibility: Help payloads for HWLAB node/lane and web-probe CLI entries. import { hwlabRuntimeLaneConfigPath } from "./hwlab-node-lanes"; export function hwlabNodeHelp(scope: "legacy-cicd" | "platform-maintenance" | null = null): Record { if (scope === "legacy-cicd") { return { ok: true, command: "hwlab nodes control-plane legacy-cicd", description: "仅用于 owning YAML 明确解析为 legacy-manual 的旧交付入口。PaC 或 unknown authority 会 fail-closed。", examples: [ "bun scripts/cli.ts hwlab nodes control-plane trigger-current --node --lane --confirm", "bun scripts/cli.ts hwlab nodes control-plane refresh --node --lane --confirm", "bun scripts/cli.ts hwlab nodes control-plane sync --node --lane --confirm", "bun scripts/cli.ts hwlab nodes control-plane source-workspace sync --node --lane --confirm", "bun scripts/cli.ts hwlab nodes git-mirror sync --node --lane --confirm --wait", "bun scripts/cli.ts hwlab nodes git-mirror flush --node --lane --confirm --wait", ], valuesPrinted: false, }; } if (scope === "platform-maintenance") { return { ok: true, command: "hwlab nodes control-plane platform-maintenance", description: "YAML 声明的平台配置、Secret 与容量维护；不得作为 PaC 源码交付的补偿或恢复入口。", examples: [ "bun scripts/cli.ts hwlab nodes control-plane apply --node --lane --confirm", "bun scripts/cli.ts hwlab nodes control-plane public-exposure --node --lane --confirm", "bun scripts/cli.ts hwlab nodes control-plane cleanup-runs --node --lane --min-age-minutes 30 --limit 200 --dry-run", "bun scripts/cli.ts hwlab nodes control-plane cleanup-released-pvs --node --lane --limit 200 --dry-run", "bun scripts/cli.ts hwlab nodes secret status --node --lane --name ", ], valuesPrinted: false, }; } return { ok: true, command: "hwlab nodes", description: "Node/lane oriented HWLAB runtime operations. Web probes moved to the top-level web-probe command.", configPath: hwlabRuntimeLaneConfigPath(), examples: [ "bun scripts/cli.ts hwlab nodes control-plane infra plan --node --lane ", "bun scripts/cli.ts hwlab nodes control-plane status --node --lane ", "bun scripts/cli.ts hwlab nodes control-plane status --node --lane --json", "bun scripts/cli.ts hwlab nodes git-mirror status --node --lane ", "bun scripts/cli.ts platform-infra pipelines-as-code history --target --consumer ", "bun scripts/cli.ts hwlab nodes hwpod-preinstall plan --node --lane --dry-run", "bun scripts/cli.ts hwlab nodes hwpod-node plan --node G14-WSL --lane v03", "bun scripts/cli.ts hwlab nodes fake-model-provider plan --node D518 --lane v03 --provider fake-echo", "bun scripts/cli.ts hwlab nodes native-development workbench status --node --lane ", "bun scripts/cli.ts hwlab nodes native-development caserun api status --node --lane ", "bun scripts/cli.ts hwlab nodes secret status --node --lane --name ", "bun scripts/cli.ts hwlab nodes test-accounts status --node --lane ", "bun scripts/cli.ts hwlab nodes observability performance-summary --node --lane ", "bun scripts/cli.ts web-probe --help", "bun scripts/cli.ts hwlab nodes control-plane platform-maintenance --help", "bun scripts/cli.ts hwlab nodes control-plane legacy-cicd --help", ], actions: { "control-plane": "YAML-first node-local CI/CD status, public exposure, runtime-image, Argo, PipelineRun and CI workspace retention domains; delivery writes are documented only by scoped help.", "git-mirror": "Inspect or operate the selected node/lane source mirror.", "hwpod-preinstall": "Render YAML-first HWPOD preinstall configRefs, runtime mount targets, PM MDTODO source, and gateway profile status.", "hwpod-node": "通过 YAML 和 trans 部署、查询 Windows 原生 Python HWPOD 节点。", "fake-model-provider": "Materialize and operate YAML-declared fake Responses model providers for HWLAB/AgentRun sentinel checks.", "native-development": "按 owning YAML 独立管理 L1 Workbench/CaseRun API、Worker 与 Web，并为 API/Web 披露固定 HTTPS 域名。", secret: "Inspect YAML-declared runtime Secrets without printing secret values; writes are documented only by platform-maintenance help.", "test-accounts": "Prepare YAML-declared HWLAB admin/test account API keys with redacted sourceRef/fingerprint output.", observability: "Read runtime metrics and authenticated Web Performance summaries.", }, notes: [ "`web-probe` is no longer under `hwlab nodes`; use `bun scripts/cli.ts web-probe ...`.", "`--node` and `--lane` remain data arguments resolved from YAML for node/lane operations.", "control-plane cleanup-runs deletes terminal PipelineRuns; cleanup-released-pvs deletes only orphaned hwlab-ci PipelineRun PVCs with no active pod mounts and Released local-path/Delete PVs.", "cleanup-legacy-docker-images is a transitional legacy-cache GC for Docker images matching YAML allowlisted repositories; it protects container-referenced images, does not run prune, and does not touch Docker volumes.", "cleanup-legacy-docker-registry-volume removes only an exited legacy Docker registry container and its unique /var/lib/registry volume after the YAML-declared k8s node-local-registry is ready.", "PaC consumer 的 PR merge 只更新 source authority；发布必须先 release plan，再由 CLI 手动发送 PaC webhook。默认帮助只给只读 status/history。", "旧交付与平台维护写入口分别只在 legacy-cicd、platform-maintenance scoped help 中展示。", "control-plane status reads its total budget, heartbeat cadence, termination grace period, and probe switches from config/hwlab-node-control-plane.yaml; --json keeps stdout as one compact JSON document while progress remains on stderr.", ], }; } export function hwlabNodeWebProbeHelp(): Record { return { ok: true, command: "web-probe", description: "Run target node/lane HWLAB Cloud Web probes with YAML-selected semantic internal/public/native origins and one-shot bootstrap Web credentials.", examples: [ "bun scripts/cli.ts web-probe run --node --lane --origin internal --wait-messages-ms 1000", "bun scripts/cli.ts web-probe opencode-smoke --node --lane --origin internal --message 'hi'", "bun scripts/cli.ts web-probe console-verify --node --lane --origin internal --profile ", "bun scripts/cli.ts web-probe native-readiness --node --lane --profile ", "bun scripts/cli.ts web-probe product-smoke --product selfmedia --target NC01 --profile voice-algorithm --edition --algorithm ", "bun scripts/cli.ts web-probe product-smoke --product pikaoa --target NC01 --profile admin-mvp", "bun scripts/cli.ts web-probe product-smoke --product apistate --target NC01 --profile operations", "bun scripts/cli.ts web-probe product-smoke --product apistate --target NC01 --profile operations --runtime native", "bun scripts/cli.ts web-probe product-smoke --product temporal --target NC01 --profile admin-readonly", "bun scripts/cli.ts web-probe product-smoke --product superapi --target NC01 --profile management", "bun scripts/cli.ts web-probe external-form --help", "bun scripts/cli.ts web-probe script --node --lane --origin internal --script-file .state/probes/workbench.mjs", "bun scripts/cli.ts web-probe screenshot --node --lane --origin internal --path /workbench --viewport 1440x900", "bun scripts/cli.ts web-probe observe start --node --lane --origin internal --target-path /workbench --sample-interval-ms 5000", "bun scripts/cli.ts web-probe observe start --node --lane --origin native --target-path /workbench --sample-interval-ms 5000", "bun scripts/cli.ts web-probe observe command webobs-xxxx --type sendPrompt --text 'ping'", "bun scripts/cli.ts web-probe observe command webobs-xxxx --type validateRealtimeFanout --profile pure-kafka-live --provider gpt.pika --text '' --second-text ''", "bun scripts/cli.ts web-probe observe status webobs-xxxx --command-id cmd-xxxx", "bun scripts/cli.ts web-probe observe command webobs-xxxx --type launchWorkbenchFromMdtodo --filename 20260610-LVDT-旧过程归档.md --task R5.1 --provider dsflash-go", "bun scripts/cli.ts web-probe observe command webobs-xxxx --type performanceCapture --duration-ms 5000 --wait-ms 8000", "bun scripts/cli.ts web-probe observe status webobs-xxxx", "bun scripts/cli.ts web-probe observe collect webobs-xxxx --view turn-summary", "bun scripts/cli.ts web-probe observe collect webobs-xxxx --view workbench-triad --trace-id trc_xxxx", "bun scripts/cli.ts web-probe observe collect webobs-xxxx --view project-mdtodo-summary", "bun scripts/cli.ts web-probe observe analyze webobs-xxxx", "bun scripts/cli.ts web-probe observe gc --node JD01 --lane v03 --dry-run", "bun scripts/cli.ts web-probe observe gc --node JD01 --lane v03 --keep-hours 24 --confirm", "bun scripts/cli.ts web-probe sentinel plan --node --lane --dry-run", "bun scripts/cli.ts web-probe sentinel plan --node --lane --sentinel workbench-auth-session-switch-2users", "bun scripts/cli.ts platform-infra pipelines-as-code status --target JD01 --consumer sentinel-jd01-v03", "bun scripts/cli.ts platform-infra pipelines-as-code history --target JD01 --consumer sentinel-jd01-v03 --limit 10", "bun scripts/cli.ts web-probe sentinel dashboard verify --node --lane --sentinel workbench-dsflash-go-tool-call-10x", "bun scripts/cli.ts web-probe sentinel dashboard screenshot --node --lane --sentinel workbench-auth-session-switch-2users", "bun scripts/cli.ts web-probe sentinel dashboard trigger --node JD01 --lane v03 --sentinel jd01-web-probe-sentinel", "bun scripts/cli.ts web-probe sentinel inspect-url 'https://monitor.pikapython.com/?run=sentinel-run-xxxx'", "bun scripts/cli.ts web-probe sentinel inspect-id webobs-xxxx --node JD01 --lane v03 --sentinel jd01-web-probe-sentinel", "bun scripts/cli.ts web-probe sentinel maintenance stop --node --lane --sentinel workbench-dsflash-go-tool-call-10x --confirm --wait --release-id ", ], actions: { run: "Run the repo-owned scripts/web-live-dom-probe.mjs helper.", "opencode-smoke": "Run the repo-owned OpenCode iframe/direct-host composer smoke and require DOM assistant text plus EventSource update/finish/idle evidence.", "console-verify": "Run a YAML-profiled Cloud Console route and viewport matrix with optional Projects, HWPOD, MDTODO and AgentRun interaction contracts.", "native-readiness": "从 owning YAML 解析 L1 固定 HTTPS 域名，并单次完成 DOM、交互、浏览器错误、关键失败响应与截图验收。", "product-smoke": "按产品 owning YAML 执行受控登录和页面验证，支持 API、表单及 Basic Auth 认证合同。", "external-form": "执行声明式外部表单，支持 Secret 注入、验证码暂停续填和默认禁止不可逆提交。", script: "Run caller-provided Playwright JS after CLI-managed /auth/login; scripts must not handle secrets themselves.", screenshot: "Capture a page through the selected YAML semantic origin and node/lane remote browser, then download PNG artifacts to the caller /tmp by default.", observe: "Start, inspect, control, stop, collect, analyze, and garbage-collect raw artifacts for long-running observers.", sentinel: "Render and operate the YAML-first web-probe sentinel wrapper, image, GitOps, dashboard verification, maintenance and report views; migrated consumers are delivered only by the automatic PR-merge chain.", }, notes: [ "Named internal/public origins, the L1 native Workbench origin, default origin, browser proxy mode, observe/analyze thresholds, and project-management command allowlist come from config/hwlab-node-lanes.yaml.", "Use --origin native for L1 Workbench, --origin internal for deployed feature debugging, and --origin public for deployed public-entry closeout; all resolve only from the owning YAML.", "--url is a mutually exclusive custom/local one-shot escape hatch; never pass a URL or IP to impersonate an internal, public, or native origin.", "`web-probe script` is an ad-hoc exploration escape hatch; repeated/high-frequency workflows must become `web-probe observe command` types or repo-owned web-probe commands.", "Every script result starts with machine-readable `UNIDESK_WEB_PROBE_COMMAND_PROMOTION_HINT ` guidance; repo-owned generated commands report reuse instead of ad-hoc promotion.", "`web-probe opencode-smoke` is the repo-owned OpenCode smoke; prefer it over repeating one-off OpenCode Playwright snippets.", "`web-probe console-verify` reads route, viewport, selector, workflow, wait and evidence bounds from the selected owning YAML profile and reuses the existing authenticated script runner.", "`web-probe native-readiness` 只接受 node、lane 和 YAML profile；固定 HTTPS origin、路径、selector、交互与失败判据禁止由 URL 参数覆盖。", "`web-probe product-smoke` 从产品 YAML 和 Secret sourceRef 读取目标、认证合同与凭据，仅输出 presence、fingerprint、DOM/网络摘要及工件哈希。", "observe is passive by default; user actions must be explicit observe command entries in control.jsonl.", "observe gc keeps manifest, heartbeat, control/error logs and analysis reports, and only removes dead-run raw samples/browser/network/screenshot artifacts after YAML-configured retention.", "After observe start, prefer observe status|command|stop|collect|analyze instead of repeating --node/--lane/--state-dir.", "Typed observe commands inherit the semantic origin selected by observe start and must not embed a replacement URL or IP.", "validateRealtimeFanout is a YAML-profiled background command: it gates submit on two live product subscribers plus three Kafka debug consumers, validates two turns and disconnect/reconnect without replay, and is polled by exact command id.", "validateExistingSessionRefresh is a YAML-profiled background command: it submits no prompt and proves an existing session keeps DOM identity while Kafka retention reaches the shared live SSE phase.", "validateWorkbenchKafkaDebugReplay 复用 observer 当前 Workbench session，以 owning YAML 中的 topic、group prefix 和超时验证隔离 Kafka 重放，并通过精确 command id 查询结果。", "validateWorkbenchTraceReadability 只检查当前 Workbench 会话中的产品 Trace 卡片。", "该命令排除隔离调试面板，并分别验证运行中默认展开、source authority 与终态保留。", "collect views render bounded summaries from existing artifacts and do not create a second source of truth.", "performanceCapture records an explicit bounded Chrome CPU profile and drains LongTask/LoAF/event-loop-gap artifacts; performance-summary reads existing artifacts only.", "analyze is offline-only: it reads artifact JSONL and writes analysis/report.md plus analysis/report.json.", "`web-probe sentinel report --raw` returns bounded issue evidence JSON, including report/artifact SHA and root-cause signal summaries when available; use `--full` for the full indexed service payload.", "When multiple web-probe sentinels are declared, sentinel image/control-plane/validate/maintenance/dashboard/report require `--sentinel `; plan/status without it show the registry drill-down.", "Issue evidence should cite observer id, stateDir, report SHA, screenshot SHA, command ids and concise summaries, not prompt/provider/secret payloads.", ], }; } export function hwlabNodeWebProbeScreenshotHelp(): Record { return { ok: true, command: "web-probe screenshot", description: "通过目标 node/lane 的受控远程浏览器采集截图；semantic origin 使用 --path，custom/local URL 直接包含完整路径。", usage: [ "bun scripts/cli.ts web-probe screenshot --node --lane --origin internal --path /workbench --viewport 1440x900", "bun scripts/cli.ts web-probe screenshot --node --lane --url 'https://custom.example/workbench' --viewport 1440x900", "bun scripts/cli.ts web-probe screenshot --node --lane --url 'http://127.0.0.1:4173/workbench' --viewport 1440x900", ], options: { "--origin": "从 owning YAML 选择 internal、public 或 native semantic origin；可与 --path 配合。", "--path": "附加到 semantic origin 的绝对路径；与 --url 互斥。", "--url": "custom/local 一次性 URL，必须包含完整路径；与 --origin、--path 互斥。", "--viewport": "截图视口，默认 1440x900。", "--wait-until": "导航完成条件，默认 domcontentloaded；静态页面可显式选择 networkidle。", "--selector": "等待指定 selector 后再截图。", "--full-page|--no-full-page": "选择整页或当前视口截图。", }, notes: [ "使用 --url 时不要再传 --path；custom/local URL 已包含完整路径。", "internal/public/native 运行面必须通过 owning YAML 的 --origin 选择，禁止用手写 URL 或 IP 替代。", "持续 SSE、WebSocket 或长轮询页面使用默认 domcontentloaded；networkidle 只用于能够稳定进入网络静默的页面。", "该命令只采集证据，不修改浏览器能力、资源门禁或运行面。", ], mutation: false, }; } export function hwlabNodeObservabilityHelp(): Record { return { ok: true, command: "hwlab nodes observability", description: "YAML-first node/lane observability control for HWLAB Workbench metrics. Runtime is queried only for presence, boundary, and summary evidence.", configPath: hwlabRuntimeLaneConfigPath(), examples: [ "bun scripts/cli.ts hwlab nodes observability plan --node --lane ", "bun scripts/cli.ts hwlab nodes observability apply --node --lane --dry-run", "bun scripts/cli.ts hwlab nodes observability apply --node --lane --confirm", "bun scripts/cli.ts hwlab nodes observability status --node --lane ", "bun scripts/cli.ts hwlab nodes observability workbench-summary --node --lane ", "bun scripts/cli.ts hwlab nodes observability performance-summary --node --lane ", ], actions: { plan: "Render the YAML-declared collection mode, scrape target, boundary, and required Workbench metric series.", apply: "Apply the YAML-declared observability control plane. D601 pod-loopback mode validates the boundary and metrics without creating ad-hoc cluster objects.", status: "Check Kubernetes service/pod presence, public raw metrics denial, and Workbench metric readiness.", "workbench-summary": "Read the YAML-declared metrics endpoint via pod loopback and summarize required Workbench series.", "performance-summary": "Fetch the authenticated same-origin Web Performance summary for the selected node/lane and return a compact ops interpretation.", }, }; }