mirrors/pikasTech-unidesk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 收敛 Web哨兵 monitor-web P11 规格

Browse Source
This commit is contained in:
Codex
2026-06-27 05:49:51 +00:00
parent 3bff4cce58
commit dd91fb888b
1 changed files with 34 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
project-management/PJ2026-01/specs/PJ2026-01060508-web-probe-sentinel.md
+34
View File
@@ -23,6 +23,7 @@
| Dashboard 实现引用版本 | draft-2026-06-26-p8-web-probe-sentinel-recovery |
| 多实例实现引用版本 | draft-2026-06-26-p9-multi-web-probe-sentinel |
| Monitor Web 聚合实现引用版本 | draft-2026-06-26-p10-monitor-web-aggregation |
| Monitor Web 观察面板治理实现引用版本 | draft-2026-06-27-p11-monitor-web-observability-dashboard |
| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
| 上级规格 | [PJ2026-010605 运维监控](PJ2026-010605-observability-monitoring.md) |
| 关联规格 | [PJ2026-010401 Web工作台](PJ2026-010401-web-workbench.md)、[PJ2026-0104010803 Workbench唯一投影](PJ2026-0104010803-workbench-unique-projection.md)、[PJ2026-010403 API契约](PJ2026-010403-api-contract.md)、[PJ2026-010601 发布流水](PJ2026-010601-controlled-release.md)、[PJ2026-010602 源码同步](PJ2026-010602-source-sync.md)、[PJ2026-010603 YAML运维](PJ2026-010603-yaml-first-ops.md)、[PJ2026-010604 公开入口](PJ2026-010604-public-entry.md)、[PJ2026-01060505 Workbench性能](PJ2026-01060505-workbench-performance.md) |
@@ -48,6 +49,7 @@ Web哨兵必须遵循 UniDesk YAML-first ops。目标 node/lane、public origin
- `sentinel plan|apply|status|validate|report|maintenance` 与 `sentinel image|control-plane` 等受控 CLI 入口。
- 发布流水 maintenance start/stop、quick verify、targetValidation、GitOps/Argo/git-mirror closeout 和 public exposure 验证。
- Dashboard 信息架构、规范化 API、前端组件分层、自动刷新、筛选、深链和 trace/turn 两层阅读视图。
- Vue `monitor-web` 观察面板的趋势曲线、固定视口三栏、运行时间线、cadence freshness、root cause 可见性和配套 CI/CD。
- `workbench-dsflash-go-tool-call-10x` 生产 canary 和 24 小时 dry-run 收口。
- `workbench-auth-session-switch-2users` 账号切换链路哨兵，覆盖账号 A/B 登录、登出、session 列表和 session 切换命令链。
- Secret、prompt、provider payload、artifact 和 dashboard 的脱敏边界。
@@ -89,6 +91,9 @@ Web哨兵必须遵循 UniDesk YAML-first ops。目标 node/lane、public origin
| auto refresh | Dashboard 的受控刷新能力；刷新只读 API/report/index，不发送 control command、不启动采样、不制造第二事实源。 |
| public exposure | YAML 声明的 `monitor.pikapython.com` HTTPS 暴露，通过共享 PK01 Caddy + FRP managed-block helper 到达 ClusterIP Service。 |
| targetValidation | 发布流水中的目标验证结果；对 HWLAB Web 恢复的判定必须来自 observe/analyze 对 public origin 的观察，不得只看 Argo green。 |
| monitor-web | 独立于 sentinel-runner 的 Vue 3 + TypeScript + Vite 展示和聚合层，承载 `monitor.pikapython.com` root、多哨兵总览、趋势曲线、时间线、单哨兵详情和受控截图验收。 |
| cadence freshness | 根据 YAML cadence、scheduler heartbeat、latest run age、active/planned run 和 analyzed report 更新时间计算的运行新鲜度；它默认是非阻塞值守告警，只有真正导致 run/report 不产生或业务链路不可用时才升级为 blocker。 |
| env reuse | CI/CD 复用既有 env image、依赖缓存、BuildKit 层和未受影响服务的发布产物，以避免无关重建；小范围变更应在 status/closeout 中暴露 build/reuse 摘要。 |
## 4. 系统边界和接口
@@ -116,6 +121,7 @@ Web哨兵必须遵循 UniDesk YAML-first ops。目标 node/lane、public origin
| PJ2026-0106050809 | Dashboard工作台 | 本规格 6.9 | overview、runs、findings、run detail、trace-frame viewer、前端分层 | 报告视图、常驻服务、Workbench性能 | 平台值守和问题分析 |
| PJ2026-0106050810 | 多实例与账号切换 | 本规格 6.10 | sentinel registry、实例隔离、账号切换 command、route prefix 和 report label | YAML配置、Wrapper边界、安全隔离 | 多哨兵巡检、账号链路值守 |
| PJ2026-0106050811 | Monitor Web 聚合 | 本规格 6.11 | runner/web 职责拆分、单 monitor-web 聚合、Kubernetes discovery、Vue+TS 前端和 public exposure 收敛 | 多实例与账号切换、Dashboard工作台、发布集成 | `monitor.pikapython.com` 统一值守入口 |
| PJ2026-0106050812 | Monitor Web 观察面板治理 | 本规格 6.12 | 趋势曲线、运行时间线、固定视口三栏、cadence freshness、Vue CI/CD/env reuse/git mirror | Monitor Web 聚合、Dashboard工作台、发布集成、源码同步 | 可滚动上线和值守的统一观察面板 |
### 5.1 目标架构图
@@ -555,6 +561,8 @@ Web哨兵实现必须先引用本规格，再进入代码变更。新增或修
P7 dashboard 增强范围内新增或修改的 dashboard API、frontend assets、renderer、format composable、auto refresh、run/detail/finding/trace-frame viewer 源码文件头部必须标注 `SPEC: PJ2026-01060508 Web哨兵 draft-2026-06-26-p7-web-probe-sentinel-dashboard`，或在既有 Web哨兵源码头部追加该实现引用版本。纯 YAML/config、锁文件、构建产物和无法承载注释头的静态资源可例外，但对应生成器、serving 入口或 manifest renderer 必须能追溯到该版本。
P10/P11 monitor-web 范围内新增或修改的 Vue/TypeScript/Vite 前端、typed API client、聚合 API、runner discovery、dashboard verify/screenshot、CI/CD renderer、GitOps/publicExposure helper 和 env reuse 规划代码必须标注 `SPEC: PJ2026-01060508 Web哨兵 draft-2026-06-27-p11-monitor-web-observability-dashboard`。旧 `scripts/assets/web-probe-sentinel-dashboard/dashboard.js` 只能标注迁移前短修或兼容验证用途，不得作为 P11 新观察面板能力的主要承载面。
实现文件不得只写 issue 编号、`latest`、`current` 或“按最新方案”作为规格引用。自动生成文件、第三方 vendored 文件、纯 YAML/config、锁文件和无法承载注释头的二进制产物不要求加源码头部，但对应生成器、渲染器、owning YAML 或 CLI 入口必须能追溯到本 SPEC。
后续 P1-P6 阶段如果改变稳定需求、观察对象、数据流、接口、部署边界或验收口径，应先更新本规格和上级 [PJ2026-010605 运维监控](PJ2026-010605-observability-monitoring.md)，再更新执行 issue。
@@ -577,6 +585,8 @@ Dashboard 前端架构应借鉴 Sub2API 监控面板的分层方式：typed API
Dashboard 自动刷新只能读取 bounded API，不得发送 `observe command`、不启动新采样、不重新 analyze、不保存额外截图。页面 hidden、loading 或上一次请求未完成时应暂停或跳过刷新，避免监控 UI 自身制造额外压力。
P11 起，长期权威观察面板是 Vue `monitor-web`，不是 runner 内置 vanilla dashboard。迁移前 runner dashboard 可以继续承担单哨兵兼容、短修和回归对照，但趋势曲线、固定视口三栏、运行时间线、多哨兵聚合、cadence freshness 和 root cause 默认可见性必须在 `monitor-web` 中设计和验收。
P8 中文运维页面必须以中文为默认用户可见语言：主标题、状态、筛选、运行历史、finding 分组、run detail、trace-frame、Final Response、空态、错误态、自动刷新和下一步动作均使用中文。原始英文 code、status 枚举、CLI 命令和 report SHA 可作为机器对照保留，但不得要求用户阅读英文 finding 才能判断 HWLAB 是否可用、卡在哪一层、下一步运行什么命令。
### 6.10 OPS-SENTINEL-REQ-010 多实例巡检与账号切换链路
@@ -615,6 +625,28 @@ P10 dashboard 受控验收必须沉淀为 CLI 入口。`web-probe sentinel dashb
`monitor.pikapython.com` root 的目标首屏必须展示所有 enabled sentinels 的 latest status、latest run、red/amber/info 摘要、freshness、runner degraded 状态和 drill-down 链接；`/sentinels/<id>` 必须展示单哨兵 runs/findings/detail/trace-frame。删除或重启一个 runner 只能让对应 sentinel 显示 degraded，不得让 root 变成空白或阻断其他 runner 数据。聚合 API 必须 bounded、分页、redacted，不打印 Secret、prompt 原文、provider payload、cookie、完整 stdout/stderr 或完整 report。
### 6.12 OPS-SENTINEL-REQ-012 Monitor Web 观察面板与 CI/CD 治理
| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| OPS-SENTINEL-REQ-012 | Monitor Web 观察面板治理 | PJ2026-0106050812 Monitor Web 观察面板治理 | Monitor Web 聚合、Dashboard工作台、[源码同步](PJ2026-010602-source-sync.md)、[发布流水](PJ2026-010601-controlled-release.md) |
`monitor-web` 首屏信息架构必须把值守判断放在最前：顶部状态与全局操作之后，先显示哨兵入口，再在哨兵入口正下方展示运行趋势曲线。趋势曲线至少展示最近运行窗口内 red finding count、warning/amber finding count 和 total finding count；当前选中 run、maintenance window、缺失 report、stale run 和 runner degraded 必须有可见标记。
趋势曲线、运行时间线、runs 表、run detail 和 findings 必须共享同一选中 run 状态。用户 hover 或点击趋势点/时间线节点时，应看到 run id、updatedAt、status、red/warning/total、report SHA 短码和 rootCause 摘要；点击后必须更新深链 query 并联动三栏工作区。趋势数据首版可以从 bounded `/api/runs` 和 `/api/overview` 派生；若需要更长窗口，新增 `/api/trends` 或等价聚合 API 时仍必须 bounded、分页、redacted，并追溯到 run/report SHA。
桌面端 `monitor-web` 必须使用固定视口工作区，避免 document 级无限长页。左侧运行历史、中间运行详情、右侧发现分析应在同一 viewport 内独立上下滚动，并使用稳定高度、`min-height: 0`、可预测列宽和移动断点；运行时间线应靠近趋势区，允许横向滚动或紧凑显示，不得通过 flex wrap 把页面整体撑长。1366x768、1440x900 和 960x600 视口必须通过远程截图验证无关键文字重叠、按钮溢出、图表撑破或横向 overflow。
cadence freshness 必须成为 `monitor-web` 的一等状态。每个 sentinel 应显示 YAML expected cadence、scheduler heartbeat age、latest run age、latest analyzed report age、active run、planned/next run 和 stale 倍数。cadence stale 默认是非阻塞告警；只有 scheduler 停摆、run/report 长时间不产生、submit/command 失败、采样样本缺失、或 Code Agent 多轮业务链路不可继续时，才升级为 blocker。面板不得把 timing warning、terminal-boundary elapsed correction 或单纯超时预算告警伪装成业务 blocker。
`monitor-web` 前端必须使用 Vue 3 + TypeScript + Vite，并与 HWLAB Cloud Web/Sub2API 运维图表的组件化方式对齐：typed API client、format composable、auto refresh composable、chart component、timeline component、run table、detail tabs、finding groups、loading/empty/error 状态和深链路由。图表库不是前置结论；可选 Chart.js、ECharts 或原生 SVG/canvas，但 SPEC/PR 必须说明包体、构建耗时、交互能力和维护成本取舍。
Vue `monitor-web` 的 CI/CD 必须和架构一起交付。YAML 必须声明 source、build context、Node/Bun/Vite 构建环境、env image、dependency cache、registry image、GitOps path、Argo Application、Service、publicExposure、runner discovery selector 和 screenshot 验收命令。CI 读源码必须优先走 node/lane 声明的 git mirror read URL；触发 PipelineRun 前做受控 pre-sync，GitOps promotion 后做受控 post-flush，并在 status/closeout 中输出 `pendingFlush`、`githubInSync`、source commit、GitOps revision 和 PipelineRun 名称。
Vue `monitor-web` 构建必须利用 env reuse、CI tools/env image、依赖缓存和镜像层缓存。未修改 runner/backend/API 时不得重建无关运行面；纯 SPEC、CLI、文档或无需 runtime 重建的提交应在 status 中呈现 `build=0 reuse=<service-count>` 或等价 reuse 证据。Vue `monitor-web` CI/CD 总耗时或单个 build TaskRun 超过两分钟时，必须先从 env reuse、依赖缓存、git mirror pre-sync、镜像层缓存和无关服务重建方向优化，再继续 UI 功能实现；不得死等长 PipelineRun 后只记录超时。
发布成功判据不能只看 legacy `dashboard.js` 静态资源 200。Vue `monitor-web` closeout 必须记录 Vite 产物内容 hash、asset 200/字节数/SHA、HTML 引用一致性、`/health`、root 聚合页 browser render、至少一个 `/sentinels/<id>` 详情页 render、远程 PNG localPath/SHA、DOM 摘要、overflow 结果、Argo/runtime/source/GitOps/git mirror alignment 和 runner degraded 降级行为。所有触发、rollout、status、git mirror sync/flush 和截图验收必须走 UniDesk 受控 CLI。
## 7. 过程控制
Web哨兵架构执行 issue 为 [#883](https://github.com/pikasTech/unidesk/issues/883)。阶段跟踪 issue 为 P0 [#885](https://github.com/pikasTech/unidesk/issues/885)、P1 [#886](https://github.com/pikasTech/unidesk/issues/886)、P2 [#887](https://github.com/pikasTech/unidesk/issues/887)、P3 [#888](https://github.com/pikasTech/unidesk/issues/888)、P4 [#889](https://github.com/pikasTech/unidesk/issues/889)、P5 [#890](https://github.com/pikasTech/unidesk/issues/890) 和 P6 [#891](https://github.com/pikasTech/unidesk/issues/891)。
@@ -632,3 +664,5 @@ P8-P8 起，targetValidation 的 availability blocker 与 Workbench timing 架
P9 多实例巡检与账号切换链路执行 issue 为 [#1017](https://github.com/pikasTech/unidesk/issues/1017)。P9 closeout 必须回写：SPEC P9 引用、registry 和两条 sentinel drill-down、旧 dsflash canary 迁移验证、账号切换 workflow/Secret sourceRef 验证、独立 Deployment/PVC/Service/SQLite/GitOps/Argo/public route prefix 证据、submit/command 失败处理、非阻塞计时告警证据、远程 PNG 截图布局复测，以及未完成阶段是否已拆出后续 issue。
P10 monitor-web 聚合执行 issue 为 [#1056](https://github.com/pikasTech/unidesk/issues/1056)。P10 closeout 必须回写：SPEC P10 引用、runner/web 职责拆分状态、Vue+TS monitor-web 迁移边界或短修边界、root 与至少一个 route prefix 的 browser render 证据、`web-probe sentinel dashboard verify|screenshot` 证据、publicExposure 和 runtime provenance、单哨兵 API 兼容性、未完成 monitor-web 架构项是否拆出后续 issue，以及 `unidesk-monitor` skill 是否记录当前操作面。
P11 monitor-web 观察面板治理执行 issue 为 [#1112](https://github.com/pikasTech/unidesk/issues/1112)。P11 的第一阶段必须先完成本 SPEC 收敛；SPEC 未合并前不得推进 Vue `monitor-web` 实现、CI/CD、GitOps、publicExposure 或部署代码。P11 实现 PR closeout 必须回写：SPEC P11 引用、Vue monitor-web 源码和 CI/CD 文件头部追溯、趋势曲线和运行时间线截图、固定视口三栏 overflow 摘要、cadence freshness 状态、env reuse/buildServices 证据、git mirror pre-sync/post-flush 证据、PipelineRun/Argo/GitOps/source alignment、root 与至少一个 sentinel detail 远程截图 localPath/SHA，以及超过两分钟 CI/CD 耗时是否已先从 env reuse/git mirror 方向优化。