pikastech
222 lines
20 KiB
TypeScript
222 lines
20 KiB
TypeScript
// 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<string, unknown> {
|
||
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 <node> --lane <lane> --confirm",
|
||
"bun scripts/cli.ts hwlab nodes control-plane refresh --node <node> --lane <lane> --confirm",
|
||
"bun scripts/cli.ts hwlab nodes control-plane sync --node <node> --lane <lane> --confirm",
|
||
"bun scripts/cli.ts hwlab nodes control-plane source-workspace sync --node <node> --lane <lane> --confirm",
|
||
"bun scripts/cli.ts hwlab nodes git-mirror sync --node <node> --lane <lane> --confirm --wait",
|
||
"bun scripts/cli.ts hwlab nodes git-mirror flush --node <node> --lane <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 <node> --lane <lane> --confirm",
|
||
"bun scripts/cli.ts hwlab nodes control-plane public-exposure --node <node> --lane <lane> --confirm",
|
||
"bun scripts/cli.ts hwlab nodes control-plane cleanup-runs --node <node> --lane <lane> --min-age-minutes 30 --limit 200 --dry-run",
|
||
"bun scripts/cli.ts hwlab nodes control-plane cleanup-released-pvs --node <node> --lane <lane> --limit 200 --dry-run",
|
||
"bun scripts/cli.ts hwlab nodes secret status --node <node> --lane <lane> --name <secret>",
|
||
],
|
||
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 <node> --lane <lane>",
|
||
"bun scripts/cli.ts hwlab nodes control-plane status --node <node> --lane <lane>",
|
||
"bun scripts/cli.ts hwlab nodes control-plane status --node <node> --lane <lane> --json",
|
||
"bun scripts/cli.ts hwlab nodes git-mirror status --node <node> --lane <lane>",
|
||
"bun scripts/cli.ts platform-infra pipelines-as-code history --target <node> --consumer <consumer>",
|
||
"bun scripts/cli.ts hwlab nodes hwpod-preinstall plan --node <node> --lane <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 <node> --lane <lane>",
|
||
"bun scripts/cli.ts hwlab nodes native-development caserun api status --node <node> --lane <lane>",
|
||
"bun scripts/cli.ts hwlab nodes secret status --node <node> --lane <lane> --name <secret>",
|
||
"bun scripts/cli.ts hwlab nodes test-accounts status --node <node> --lane <lane>",
|
||
"bun scripts/cli.ts hwlab nodes observability performance-summary --node <node> --lane <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<string, unknown> {
|
||
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 <node> --lane <lane> --origin internal --wait-messages-ms 1000",
|
||
"bun scripts/cli.ts web-probe opencode-smoke --node <node> --lane <lane> --origin internal --message 'hi'",
|
||
"bun scripts/cli.ts web-probe console-verify --node <node> --lane <lane> --origin internal --profile <yaml-profile>",
|
||
"bun scripts/cli.ts web-probe native-readiness --node <node> --lane <lane> --profile <yaml-profile>",
|
||
"bun scripts/cli.ts web-probe product-smoke --product selfmedia --target NC01 --profile voice-algorithm --edition <edition-id> --algorithm <algorithm-id>",
|
||
"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 <node> --lane <lane> --origin internal --script-file .state/probes/workbench.mjs",
|
||
"bun scripts/cli.ts web-probe screenshot --node <node> --lane <lane> --origin internal --path /workbench --viewport 1440x900",
|
||
"bun scripts/cli.ts web-probe observe start --node <node> --lane <lane> --origin internal --target-path /workbench --sample-interval-ms 5000",
|
||
"bun scripts/cli.ts web-probe observe start --node <node> --lane <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 '<first-turn>' --second-text '<second-turn>'",
|
||
"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 <node> --lane <lane> --dry-run",
|
||
"bun scripts/cli.ts web-probe sentinel plan --node <node> --lane <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 <node> --lane <lane> --sentinel workbench-dsflash-go-tool-call-10x",
|
||
"bun scripts/cli.ts web-probe sentinel dashboard screenshot --node <node> --lane <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 <node> --lane <lane> --sentinel workbench-dsflash-go-tool-call-10x --confirm --wait --release-id <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 <json>` 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 <id> 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 <id>`; 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<string, unknown> {
|
||
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 <node> --lane <lane> --origin internal --path /workbench --viewport 1440x900",
|
||
"bun scripts/cli.ts web-probe screenshot --node <node> --lane <lane> --url 'https://custom.example/workbench' --viewport 1440x900",
|
||
"bun scripts/cli.ts web-probe screenshot --node <node> --lane <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<string, unknown> {
|
||
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 <node> --lane <lane>",
|
||
"bun scripts/cli.ts hwlab nodes observability apply --node <node> --lane <lane> --dry-run",
|
||
"bun scripts/cli.ts hwlab nodes observability apply --node <node> --lane <lane> --confirm",
|
||
"bun scripts/cli.ts hwlab nodes observability status --node <node> --lane <lane>",
|
||
"bun scripts/cli.ts hwlab nodes observability workbench-summary --node <node> --lane <lane>",
|
||
"bun scripts/cli.ts hwlab nodes observability performance-summary --node <node> --lane <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.",
|
||
},
|
||
};
|
||
}
|