From 5fffa5a3b63786190b99bce5ea4f1343c7bb4de3 Mon Sep 17 00:00:00 2001 From: Codex Date: Fri, 26 Jun 2026 18:33:01 +0000 Subject: [PATCH] docs: record web sentinel closeout guidance --- .agents/skills/unidesk-monitor/SKILL.md | 2 ++ .../skills/unidesk-monitor/references/full.md | 19 ++++++++++++++++++- 2 files changed, 20 insertions(+), 1 deletion(-) diff --git a/.agents/skills/unidesk-monitor/SKILL.md b/.agents/skills/unidesk-monitor/SKILL.md index a38decd7..6c27780a 100644 --- a/.agents/skills/unidesk-monitor/SKILL.md +++ b/.agents/skills/unidesk-monitor/SKILL.md @@ -14,6 +14,7 @@ description: UniDesk monitoring and Web sentinel operations. Use when working on - YAML 是 source of truth。node/lane、sentinel id、Deployment、Service、PVC、route prefix、cadence、Secret sourceRef、dashboard public URL 和 report views 都必须从 YAML/configRef 进入受控 CLI。 - 正式读写 GitHub issue/PR 走 `$unidesk-gh`；部署、Argo、git-mirror、PipelineRun、runtime 状态走 `$unidesk-cicd` 和受控 CLI；YAML 正规化走 `$unidesk-ymalops`。 - 诊断可用 `curl` 或一次性 `web-probe script` 采证，但重复 dashboard 验证必须沉淀为受控 `web-probe sentinel dashboard verify|screenshot` 或等价入口。 +- `web-probe sentinel dashboard screenshot` 必须作为远程浏览器截图入口使用，PNG 默认下载到调用者 `/tmp`；issue/PR 证据引用 `localPath`、`sha256`、HTTP status、DOM 摘要和 overflow 结果。 ## Quick Commands @@ -42,6 +43,7 @@ bun scripts/cli.ts web-probe observe analyze 2. Separate runner and web: runner Pod/PVC/API/report health is not the same as monitor-web rendering health. 3. Separate service rollout and target validation: Argo/runtime green only proves哨兵自身可用；HWLAB business recovery must come from observe/analyze report. 4. Separate single-sentinel and multi-sentinel: root registry shows all sentinels; each runner owns independent Pod/PVC/Service/report. A single monitor-web aggregation layer is a separate responsibility. +5. Separate timing alerts and blockers: YAML-configured elapsed/timeout warnings are non-blocking unless the turn fails to complete, breaks Code Agent multi-round continuity, loses samples, or makes auth/submit/report unavailable. ## Architecture Preference diff --git a/.agents/skills/unidesk-monitor/references/full.md b/.agents/skills/unidesk-monitor/references/full.md index ba8f6b91..60596e5f 100644 --- a/.agents/skills/unidesk-monitor/references/full.md +++ b/.agents/skills/unidesk-monitor/references/full.md @@ -31,6 +31,8 @@ bun scripts/cli.ts web-probe sentinel dashboard verify --node D601 --lane v03 -- bun scripts/cli.ts web-probe sentinel dashboard screenshot --node D601 --lane v03 --sentinel workbench-auth-session-switch-2users ``` +The screenshot command runs through the selected node/lane remote browser and downloads the PNG artifact to the caller's `/tmp` by default. Closeout evidence should cite `localPath`, `sha256`, page HTTP status, selected DOM summary fields and `layout.horizontalOverflow` / `overflowCount`; do not replace this with a local browser screenshot or ad-hoc `web-probe script` when the sentinel command can cover the page. + Report drill-down: ```bash @@ -53,7 +55,7 @@ curl -sS -D - https://monitor.pikapython.com/api/runs -o /tmp/monitor-runs.json curl -sS -D - https://monitor.pikapython.com/sentinels/workbench-auth-session-switch-2users/api/overview -o /tmp/monitor-auth-overview.json ``` -Use `web-probe script` with explicit `page.goto("https://monitor.pikapython.com/...")` only as one-off evidence until a dedicated dashboard verify/screenshot command exists. +Use `web-probe script` with explicit `page.goto("https://monitor.pikapython.com/...")` only for one-off exploration that is not yet covered by `web-probe sentinel dashboard verify|screenshot`; repeated checks must be promoted into those sentinel dashboard commands. ## YAML Ownership @@ -88,6 +90,21 @@ Classify a monitor page issue in this order: Do not treat public root/CSS/JS 200 as dashboard success. Browser console and DOM render evidence are required. +## Rollout Closeout + +For a Web sentinel fix, closeout needs four independent evidence surfaces: + +1. `web-probe sentinel control-plane status --node --lane --sentinel ` must be `ok`, with source, registry, GitOps, Argo and runtime image aligned. If runtime already has the expected image but Argo target/revision is stale, run the controlled `control-plane apply --confirm --wait` path once with a bounded timeout, then recheck status; do not declare the rollout complete on runtime readiness alone. +2. `web-probe sentinel validate --node --lane --sentinel ` must pass `/api/health`, `/metrics`, indexed recent report, public exposure and public dashboard probes. +3. `web-probe sentinel dashboard screenshot --node --lane --sentinel ` must pass through the remote browser and save a verified PNG to the caller `/tmp`; record the local path, hash and layout overflow result. +4. `web-probe sentinel report --node --lane --sentinel --latest --view summary` must show the latest business run, report hash, samples and finding severity. Auth/login failures, submit failures, missing samples, absent recent reports and Code Agent multi-round continuity breaks are blockers. YAML elapsed-budget or total-turn timing alerts are non-blocking warnings unless they coincide with a failed turn, broken continuity, missing report or unavailable user path. + +Long `quick-verify` or CI/CD waits should be bounded by the YAML-declared budget and the operator's outer timeout. If a wait would exceed about two minutes during rollout, first inspect the visible stage and either optimize the slow path, defer the expensive quick verify to manual validation, or record it as a non-blocking timing warning; do not dead-wait without new evidence. + +Source mirror readiness must be proven by the internal mirror object/read probe for the expected commit. A GitHub/source head check alone is not sufficient evidence to skip source sync, because it does not prove the k3s publish job can fetch the object from the node-local mirror. + +Dashboard aggregate counters may include historical runs. When they disagree with the latest selected run, closeout should name the latest `runId` and report hash as the acceptance source, and track the aggregate-labeling UI improvement separately instead of treating historical aggregate red counts as the latest run's blocker. + ## Multi-Sentinel Target Architecture Current implementation has independent sentinel runner services, but each runner still serves its own dashboard. The target architecture should split: