Lyon
179 lines
21 KiB
TypeScript
179 lines
21 KiB
TypeScript
// SPEC: PJ2026-01060505 Workbench Performance draft-2026-06-17-p0.
|
|
// Responsibility: Help payloads for the HWLAB node/lane CLI.
|
|
import { hwlabRuntimeLaneConfigPath } from "./hwlab-node-lanes";
|
|
|
|
export function hwlabNodeHelp(): Record<string, unknown> {
|
|
return {
|
|
ok: true,
|
|
command: "hwlab nodes",
|
|
description: "Node/lane oriented HWLAB operations. G14 is a node id value passed by --node, not a command family.",
|
|
configPath: hwlabRuntimeLaneConfigPath(),
|
|
examples: [
|
|
"bun scripts/cli.ts hwlab nodes control-plane infra plan --node D601 --lane v03",
|
|
"bun scripts/cli.ts hwlab nodes control-plane infra status --node D601 --lane v03",
|
|
"bun scripts/cli.ts hwlab nodes control-plane infra apply --node D601 --lane v03 --dry-run",
|
|
"bun scripts/cli.ts hwlab nodes control-plane infra tools-image status --node D601 --lane v03",
|
|
"bun scripts/cli.ts hwlab nodes control-plane infra tools-image build --node D601 --lane v03 --confirm",
|
|
"bun scripts/cli.ts hwlab nodes control-plane infra argo status --node D601 --lane v03",
|
|
"bun scripts/cli.ts hwlab nodes control-plane infra argo apply --node D601 --lane v03 --confirm",
|
|
"bun scripts/cli.ts hwlab nodes control-plane plan --node D601 --lane v03",
|
|
"bun scripts/cli.ts hwlab nodes control-plane status --node D601 --lane v03",
|
|
"bun scripts/cli.ts hwlab nodes control-plane status --node D601 --lane v03 --full",
|
|
"bun scripts/cli.ts hwlab nodes control-plane cleanup-runs --node D601 --lane v03 --min-age-minutes 60 --limit 20 --dry-run",
|
|
"bun scripts/cli.ts hwlab nodes control-plane cleanup-runs --node D601 --lane v03 --min-age-minutes 60 --limit 20 --confirm --wait",
|
|
"bun scripts/cli.ts hwlab nodes control-plane status --node G14 --lane v03",
|
|
"bun scripts/cli.ts hwlab nodes control-plane apply --node G14 --lane v03 --dry-run",
|
|
"bun scripts/cli.ts hwlab nodes control-plane refresh --node G14 --lane v03 --confirm",
|
|
"bun scripts/cli.ts hwlab nodes control-plane runtime-image status --node G14 --lane v03",
|
|
"bun scripts/cli.ts hwlab nodes control-plane runtime-image preload --node G14 --lane v03 --confirm",
|
|
"bun scripts/cli.ts hwlab nodes control-plane sync --node D601 --lane v03 --confirm",
|
|
"bun scripts/cli.ts hwlab nodes control-plane public-exposure --node D601 --lane v03 --dry-run",
|
|
"bun scripts/cli.ts hwlab nodes control-plane public-exposure --node D601 --lane v03 --confirm",
|
|
"bun scripts/cli.ts hwlab nodes control-plane trigger-current --node G14 --lane v03 --confirm",
|
|
"bun scripts/cli.ts hwlab nodes control-plane trigger-current --node D601 --lane v03 --confirm --wait",
|
|
"bun scripts/cli.ts hwlab nodes control-plane trigger-current --node D601 --lane v03 --confirm --wait --rerun",
|
|
"bun scripts/cli.ts hwlab nodes control-plane runtime-migration --node D601 --lane v03 --dry-run",
|
|
"bun scripts/cli.ts hwlab nodes control-plane runtime-migration --node D601 --lane v03 --confirm",
|
|
"bun scripts/cli.ts hwlab nodes control-plane allow-endpoint-bridge --node G14 --lane v03 --confirm",
|
|
"bun scripts/cli.ts hwlab nodes git-mirror status --node G14 --lane v03",
|
|
"bun scripts/cli.ts hwlab nodes secret status --node G14 --lane v03 --name hwlab-v03-openfga",
|
|
"bun scripts/cli.ts hwlab nodes secret ensure --node G14 --lane v03 --name hwlab-v03-master-server-admin-api-key --confirm",
|
|
"bun scripts/cli.ts hwlab nodes secret status --node G14 --lane v03 --name hwlab-v03-bootstrap-admin",
|
|
"bun scripts/cli.ts hwlab nodes secret ensure --node G14 --lane v03 --name hwlab-v03-bootstrap-admin --confirm",
|
|
"bun scripts/cli.ts hwlab nodes secret ensure --node D601 --lane v03 --name hwlab-v03-bootstrap-admin --confirm --force",
|
|
"bun scripts/cli.ts hwlab nodes secret status --node G14 --lane v03 --name hwlab-cloud-api-v03-db",
|
|
"bun scripts/cli.ts hwlab nodes secret cleanup-owned-postgres --node G14 --lane v03 --dry-run",
|
|
"bun scripts/cli.ts hwlab nodes secret cleanup-owned-postgres --node G14 --lane v03 --confirm",
|
|
"bun scripts/cli.ts hwlab nodes secret cleanup-obsolete --node G14 --lane v03 --name hwpod-v03-db --dry-run",
|
|
"bun scripts/cli.ts hwlab nodes secret cleanup-obsolete --node G14 --lane v03 --name hwpod-v03-db --confirm",
|
|
"bun scripts/cli.ts hwlab nodes secret status --node G14 --lane v03 --name hwlab-v03-code-agent-provider",
|
|
"bun scripts/cli.ts hwlab nodes secret ensure --node G14 --lane v03 --name hwlab-v03-code-agent-provider --confirm",
|
|
"bun scripts/cli.ts hwlab nodes test-accounts status --node D601 --lane v03",
|
|
"bun scripts/cli.ts hwlab nodes test-accounts sync --node D601 --lane v03 --confirm",
|
|
"bun scripts/cli.ts hwlab nodes web-probe run --node D601 --lane v03 --wait-messages-ms 1000",
|
|
"bun scripts/cli.ts hwlab nodes web-probe sentinel plan --node D601 --lane v03 --dry-run",
|
|
"bun scripts/cli.ts hwlab nodes web-probe sentinel status --node D601 --lane v03",
|
|
"bun scripts/cli.ts hwlab nodes web-probe sentinel image status --node D601 --lane v03",
|
|
"bun scripts/cli.ts hwlab nodes web-probe sentinel image build --node D601 --lane v03 --dry-run",
|
|
"bun scripts/cli.ts hwlab nodes web-probe sentinel control-plane plan --node D601 --lane v03 --dry-run",
|
|
"bun scripts/cli.ts hwlab nodes web-probe sentinel control-plane status --node D601 --lane v03",
|
|
"bun scripts/cli.ts hwlab nodes web-probe sentinel control-plane trigger-current --node D601 --lane v03 --dry-run",
|
|
"bun scripts/cli.ts hwlab nodes web-probe sentinel validate --node D601 --lane v03",
|
|
"bun scripts/cli.ts hwlab nodes web-probe sentinel maintenance stop --node D601 --lane v03 --confirm --wait",
|
|
"bun scripts/cli.ts hwlab nodes web-probe sentinel report --node D601 --lane v03 --view turn-summary",
|
|
"bun scripts/cli.ts hwlab nodes observability plan --node D601 --lane v03",
|
|
"bun scripts/cli.ts hwlab nodes observability status --node D601 --lane v03",
|
|
"bun scripts/cli.ts hwlab nodes observability apply --node D601 --lane v03 --dry-run",
|
|
"bun scripts/cli.ts hwlab nodes observability workbench-summary --node D601 --lane v03",
|
|
"bun scripts/cli.ts hwlab nodes observability performance-summary --node D601 --lane v03",
|
|
],
|
|
notes: [
|
|
"`trigger-current` skips an already succeeded PipelineRun for the same HWLAB source commit by default.",
|
|
"`trigger-current --confirm --wait` is the one-command CICD path: git-mirror pre-sync/pre-flush, control-plane refresh, PipelineRun create/reuse, bounded wait, and post-flush when terminal.",
|
|
"`control-plane sync --confirm` syncs the YAML-declared local-k3s postgres bootstrap Secret, terminates a stale running Argo operation, deletes failed Argo hook Jobs, and recreates stale non-ready StatefulSet pods that are still pinned to an old controller revision with pull/backoff errors.",
|
|
"`--wait` defaults to 120 seconds. If the PipelineRun is still active after 120 seconds, the CLI returns a warning plus env-reuse and git-mirror inspection commands instead of blocking.",
|
|
"`web-probe sentinel image/control-plane` renders the YAML-first image, GitOps and Argo plan from the owning configRefs; unavailable service validation is a structured failure, not an automatic second execution path.",
|
|
"`web-probe sentinel validate|maintenance|report` talks to the sentinel through k3s internal Service DNS, records only analyze summaries/views, and never runs a public/fallback validation path.",
|
|
"Use `--rerun` for a deliberate YAML-first config-only publish when UniDesk node/lane render inputs changed but the HWLAB source commit did not."
|
|
],
|
|
};
|
|
}
|
|
|
|
export function hwlabNodeWebProbeHelp(): Record<string, unknown> {
|
|
return {
|
|
ok: true,
|
|
command: "hwlab nodes web-probe",
|
|
description: "Run target node/lane HWLAB Cloud Web DOM probes with Web login credentials resolved from YAML-declared bootstrap admin sourceRef and injected only as one-shot stdin/env.",
|
|
examples: [
|
|
"bun scripts/cli.ts hwlab nodes web-probe run --node D601 --lane v03 --wait-messages-ms 1000",
|
|
"bun scripts/cli.ts hwlab nodes web-probe run --node D601 --lane v03 --fresh-session --message 'ping'",
|
|
"bun scripts/cli.ts hwlab nodes web-probe script --node D601 --lane v03 --script-file .state/probes/workbench.mjs",
|
|
"bun scripts/cli.ts hwlab nodes web-probe observe start --node D601 --lane v03 --target-path /workbench --sample-interval-ms 5000",
|
|
"bun scripts/cli.ts hwlab nodes web-probe observe start --node D601 --lane v03 --target-path /projects/mdtodo --sample-interval-ms 5000",
|
|
"bun scripts/cli.ts hwlab nodes web-probe observe command webobs-xxxx --type newSession",
|
|
"bun scripts/cli.ts hwlab nodes web-probe observe command webobs-xxxx --type selectProvider --provider codex-api",
|
|
"bun scripts/cli.ts hwlab nodes web-probe observe command webobs-xxxx --type sendPrompt --text 'ping'",
|
|
"bun scripts/cli.ts hwlab nodes web-probe observe command webobs-xxxx --type sendPrompt --text-stdin <<'EOF'\nlong prompt\nEOF",
|
|
"bun scripts/cli.ts hwlab nodes web-probe observe command webobs-xxxx --type steer --text '继续观察当前 trace'",
|
|
"bun scripts/cli.ts hwlab nodes web-probe observe command webobs-xxxx --type cancel",
|
|
"bun scripts/cli.ts hwlab nodes web-probe observe command webobs-xxxx --type gotoProjectMdtodo",
|
|
"bun scripts/cli.ts hwlab nodes web-probe observe command webobs-xxxx --type configureMdtodoHwpodSource --hwpod-id d601-f103-v2 --node-id node-d601-f103-v2 --workspace-root 'F:\\\\Work\\\\HWLAB-CASE-F103' --root docs/MDTODO",
|
|
"bun scripts/cli.ts hwlab nodes web-probe observe command webobs-xxxx --type selectMdtodoFile --file-ref docs/MDTODO/example.md",
|
|
"bun scripts/cli.ts hwlab nodes web-probe observe command webobs-xxxx --type selectMdtodoTask --task R1.1",
|
|
"bun scripts/cli.ts hwlab nodes web-probe observe command webobs-xxxx --type editMdtodoTaskTitle --task R1.1 --title '更新任务标题'",
|
|
"bun scripts/cli.ts hwlab nodes web-probe observe command webobs-xxxx --type addMdtodoSubTask --task R1.1 --title '新增子任务'",
|
|
"bun scripts/cli.ts hwlab nodes web-probe observe command webobs-xxxx --type launchWorkbenchFromMdtodo --task R1.1",
|
|
"bun scripts/cli.ts hwlab nodes web-probe observe status webobs-xxxx",
|
|
"bun scripts/cli.ts hwlab nodes web-probe observe stop webobs-xxxx --force",
|
|
"bun scripts/cli.ts hwlab nodes web-probe observe collect webobs-xxxx --view turn-summary",
|
|
"bun scripts/cli.ts hwlab nodes web-probe observe collect webobs-xxxx --view trace-frame --trace-id trc_xxx --sample-seq 42",
|
|
"bun scripts/cli.ts hwlab nodes web-probe observe collect webobs-xxxx --view project-mdtodo-summary",
|
|
"bun scripts/cli.ts hwlab nodes web-probe observe analyze webobs-xxxx",
|
|
"bun scripts/cli.ts hwlab nodes web-probe sentinel plan --node D601 --lane v03 --dry-run",
|
|
"bun scripts/cli.ts hwlab nodes web-probe sentinel status --node D601 --lane v03",
|
|
"bun scripts/cli.ts hwlab nodes web-probe sentinel image status --node D601 --lane v03",
|
|
"bun scripts/cli.ts hwlab nodes web-probe sentinel image build --node D601 --lane v03 --dry-run",
|
|
"bun scripts/cli.ts hwlab nodes web-probe sentinel control-plane plan --node D601 --lane v03 --dry-run",
|
|
"bun scripts/cli.ts hwlab nodes web-probe sentinel control-plane status --node D601 --lane v03",
|
|
"bun scripts/cli.ts hwlab nodes web-probe sentinel control-plane trigger-current --node D601 --lane v03 --dry-run",
|
|
"bun scripts/cli.ts hwlab nodes web-probe sentinel validate --node D601 --lane v03",
|
|
"bun scripts/cli.ts hwlab nodes web-probe sentinel validate --node D601 --lane v03 --quick-verify --confirm --wait",
|
|
"bun scripts/cli.ts hwlab nodes web-probe sentinel maintenance start --node D601 --lane v03 --confirm --wait --release-id <id>",
|
|
"bun scripts/cli.ts hwlab nodes web-probe sentinel maintenance stop --node D601 --lane v03 --confirm --wait --release-id <id>",
|
|
"bun scripts/cli.ts hwlab nodes web-probe sentinel report --node D601 --lane v03 --view summary",
|
|
"bun scripts/cli.ts hwlab nodes web-probe sentinel report --node D601 --lane v03 --view trace-frame",
|
|
"bun scripts/cli.ts hwlab nodes web-probe script --node D601 --lane v03 <<'JS'\nexport default async ({ waitWorkbenchReady, fetchJson, fetchApiMatrix, recordStep, collectText, safeEvaluate, screenshot }) => {\n const ready = await waitWorkbenchReady();\n const workspace = await fetchJson('/v1/workbench/workspace?projectId=prj_hwpod_workbench');\n const apiMatrix = await fetchApiMatrix(['/v1/workbench/workspace?projectId=prj_hwpod_workbench', '/auth/session']);\n const workspaceText = await collectText('#workspace');\n const evaluated = await safeEvaluate(({ a, b }) => ({ sum: a + b }), { a: 1, b: 2 });\n await screenshot('workbench.png');\n recordStep('workbench-summary', { finalUrl: ready.finalUrl, workspaceOk: workspace.ok, apiMatrixOk: apiMatrix.ok });\n return { finalUrl: ready.finalUrl, workspaceOk: workspace.ok, workspaceText, evaluated };\n};\nJS",
|
|
],
|
|
actions: {
|
|
run: "Run the repo-owned scripts/web-live-dom-probe.mjs helper.",
|
|
script: "Run caller-provided Playwright JS after CLI-managed /auth/login; the script receives authenticated browser/context/page plus gotoStable/reloadStable/gotoCurrentStable/safeReload/fetchJson/safeFetchJson/fetchApiMatrix/recordStep/collectText/safeEvaluate/waitWorkbenchReady/screenshotOnError/summarizeWorkspace/summarizeConversation helpers and must not handle secrets itself.",
|
|
observe: "Start, inspect, control, stop, collect, and analyze a pure-client long-running Workbench observer on the target host. The observer runs a control page plus a passive observer page in a shared-auth browser context, receives commands through stateDir/commands files, writes JSONL artifacts, and does not expose any inbound service API.",
|
|
sentinel: "Render the YAML-first service wrapper configRef graph plus image/GitOps/Argo control-plane plan for the production web-probe sentinel, then validate/maintenance/report through the k3s internal sentinel Service DNS. Quick verify still uses web-probe observe/analyze artifacts as truth and records only redacted report summaries/views.",
|
|
},
|
|
notes: [
|
|
"The default probe URL, browser proxy mode, observe/analyze alert thresholds, and project-management observe behavior come from config/hwlab-node-lanes.yaml webProbe; pass --url only when intentionally overriding the YAML-selected origin.",
|
|
"Prefer --script-file for reusable probes; stdin heredocs remain supported for one-off probes.",
|
|
"Issue-ready evidence is available under issueEvidence and summary.issueEvidence; full script report is persisted under probe.reportPath with a SHA-256 fingerprint.",
|
|
"observe sampling is passive by default: it records DOM summaries and natural page request/response/requestfailed events with observerInitiated=false; it does not actively fetch Workbench APIs, reload, switch sessions, route/intercept, or call repair helpers.",
|
|
"observe start registers a local UniDesk-side observer id under .state/web-observe/index.json; after start, prefer observe status|command|stop|collect|analyze <id> instead of repeating --node/--lane/--state-dir.",
|
|
"observe status reports runner liveness separately from process existence, including heartbeat age, stale threshold, command backlog, and abandoned command counts.",
|
|
"observe command actions are explicit user/control actions and are appended to control.jsonl; use --type newSession/selectProvider/sendPrompt/steer/cancel/goto/screenshot/mark/stop. Project-management actions include gotoProjectMdtodo, source config/probe/reindex, selectMdtodoSource/selectMdtodoFile/selectMdtodoTask/expandMdtodoTask, edit/toggle/add/continue/delete MDTODO task commands, and launchWorkbenchFromMdtodo. These actions are allowed only by the selected node/lane YAML. steer/cancel reuse the Workbench composer path, and project-management launch uses public UI/API evidence plus x-hwlab-otel-trace-id capture, not private backend APIs. For long prompts and task body edits use --text-stdin; keep prompt/body text out of issue comments by citing textHash/textBytes.",
|
|
"observe stop --force first checks heartbeat/backlog health; if the runner is stale or commands are not being consumed, it kills the recorded PID from outside the command queue and marks pending/processing commands abandoned so analyze classifies them as tooling findings.",
|
|
"observe collect --view turn-summary renders the multi-turn CLI reading layer from samples/control artifacts; --view trace-frame renders one sampled trace frame with a fixed Final Response block; --view project-summary is the legacy project view, and --view project-mdtodo-summary renders MDTODO samples, interactive command/mutation rows, Workbench launch commands, and OTel trace drill-down commands from the same artifacts. collect views do not save a second source of truth.",
|
|
"observe analyze is offline-only: it reads artifact JSONL plus observer command/heartbeat artifacts and writes analysis/report.md plus analysis/report.json without accessing Workbench APIs or driving the browser. For project-management pages it reports DOM readiness, public task id coverage, Workbench launch success/failure, captured launch OTel trace headers, and YAML-budgeted project API timing.",
|
|
"observe analyze scans every sampled DOM point, extracts Workbench timing text such as 总耗时/total and 最近 N 秒/分前, and writes a sample point vs turn timing report: each Markdown table row starts with the timestamp, followed by each turn's 总耗时(s) and 最近更新(s). Timing series are reported for post-processing/manual analysis instead of auto-judged from status tail output.",
|
|
"observe analyze also reports visible “加载中” count, owner attribution, concurrent loading owners, and continuous visible segments; fixes must reduce real loading latency, not reveal incomplete content early to make this metric disappear.",
|
|
"script/observe support --browser-proxy-mode auto|direct; use direct for A/B evidence when frontend RUM is slow but OTel server spans are absent or fast, instead of falling back to raw Playwright.",
|
|
"sentinel plan/status is a configuration visibility command for the service wrapper; sentinel image/control-plane renders image, GitOps and Argo control-plane state from owning YAML. sentinel validate checks /api/health, /metrics, recent analyze report and publicExposure; maintenance stop can run the configured quick verify and index the observe/analyze report. observe start/status/command/collect/analyze remain the sampling and analysis truth.",
|
|
"Use recordStep(name, data) or fetchApiMatrix(paths) to keep structured partial evidence when a later step fails.",
|
|
"Use reloadStable(), gotoCurrentStable(), or safeReload() for bounded retries around page reload/current-URL navigation jitter such as ERR_NETWORK_CHANGED.",
|
|
"Playwright page.evaluate accepts one serializable argument; use page.evaluate(({ a, b }) => ..., { a, b }) or safeEvaluate(fn, { a, b }).",
|
|
"Failures include failureKind, errorMessage, scriptSha256, runDir, lastUrl, and lastScreenshot when a screenshot can be captured.",
|
|
],
|
|
};
|
|
}
|
|
|
|
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 D601 --lane v03",
|
|
"bun scripts/cli.ts hwlab nodes observability apply --node D601 --lane v03 --dry-run",
|
|
"bun scripts/cli.ts hwlab nodes observability apply --node D601 --lane v03 --confirm",
|
|
"bun scripts/cli.ts hwlab nodes observability status --node D601 --lane v03",
|
|
"bun scripts/cli.ts hwlab nodes observability workbench-summary --node D601 --lane v03",
|
|
"bun scripts/cli.ts hwlab nodes observability performance-summary --node D601 --lane v03",
|
|
],
|
|
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.",
|
|
},
|
|
};
|
|
}
|