Codex
189 lines
18 KiB
TypeScript
189 lines
18 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 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.",
|
|
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 只由 GitHub PR merge 触发；默认帮助只给只读 status/history，自动链故障必须修 owning YAML、controller 或源码。",
|
|
"旧交付与平台维护写入口分别只在 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 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 run --node <node> --lane <lane> --origin public --fresh-session --message 'public exposure closeout'",
|
|
"bun scripts/cli.ts web-probe opencode-smoke --node <node> --lane <lane> --origin internal --message 'hi'",
|
|
"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 screenshot --node <node> --lane <lane> --origin public --path /workbench --viewport 390x844 --name workbench-public-mobile.png",
|
|
"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 public --target-path /projects/mdtodo --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 command webobs-xxxx --type validateExistingSessionRefresh --profile pure-kafka-live --session-id ses_existing",
|
|
"bun scripts/cli.ts web-probe observe command webobs-xxxx --type validateWorkbenchKafkaDebugReplay",
|
|
"bun scripts/cli.ts web-probe observe command webobs-xxxx --type validateWorkbenchTraceReadability",
|
|
"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 closeMdtodoSourceConfig",
|
|
"bun scripts/cli.ts web-probe observe command webobs-xxxx --type selectMdtodoFile --filename 20260609_频率判断_用户反馈.md",
|
|
"bun scripts/cli.ts web-probe observe command webobs-xxxx --type openMdtodoReportPreview --task R1 --link R1.1",
|
|
"bun scripts/cli.ts web-probe observe command webobs-xxxx --type toggleMdtodoReportFullscreen --text toggle",
|
|
"bun scripts/cli.ts web-probe observe command webobs-xxxx --type editMdtodoTaskInline --task R1 --field body --text 'body updated through web-probe command'",
|
|
"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 performance-summary",
|
|
"bun scripts/cli.ts web-probe observe collect webobs-xxxx --view timeline --command-id cmd-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 report --node <node> --lane <lane> --sentinel workbench-dsflash-go-tool-call-10x --latest --view summary --raw",
|
|
"bun scripts/cli.ts web-probe sentinel report --node <node> --lane <lane> --sentinel workbench-dsflash-go-tool-call-10x --latest --view summary --full",
|
|
"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.",
|
|
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, default origin, per-origin browser proxy mode, observe/analyze thresholds, and project-management command allowlist come from config/hwlab-node-lanes.yaml webProbe.",
|
|
"Use --origin internal for business/feature bug debugging and --origin public for public exposure or public-entry closeout; both resolve only from the owning YAML.",
|
|
"--url is a mutually exclusive custom/local one-shot escape hatch; never pass a URL or IP to choose between internal and public origins.",
|
|
"`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.",
|
|
"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.",
|
|
"For monitor-web links or page evidence ids, start with `web-probe sentinel inspect-url` or `inspect-id`; default evidence must be controlled report/observe CLI output, not direct public API curl.",
|
|
"`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 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.",
|
|
},
|
|
};
|
|
}
|