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

fix: restore web sentinel recovery diagnostics (#980)

Browse Source 
Co-authored-by: Codex <codex@noreply.local>
This commit is contained in:
Lyon
2026-06-26 14:04:37 +08:00
committed by GitHub
parent fc6d3bdaf9
commit bdec05729d
8 changed files with 409 additions and 161 deletions
Download Patch File Download Diff File Expand all files Collapse all files
project-management/PJ2026-01/specs/PJ2026-01060508-web-probe-sentinel.md
+74 -1
View File
@@ -20,7 +20,7 @@
| 层级 | L3 子课题 |
| 状态 | 已生效 |
| 实现引用版本 | draft-2026-06-25-p0-web-probe-sentinel |
| Dashboard 实现引用版本 | draft-2026-06-26-p7-web-probe-sentinel-dashboard |
| Dashboard 实现引用版本 | draft-2026-06-26-p8-web-probe-sentinel-recovery |
| 需求规格模板 | [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) |
@@ -355,6 +355,69 @@ sequenceDiagram
Trace drill-down 必须保持两层阅读：第一层是多 turn 摘要，第二层是选中 turn/trace/sample 后的文字版 trace-frame。`Final Response` 在第二层固定成块展示；空内容显示 `(空内容)`，有内容按 redaction 策略展示摘要、字节数或允许展示的正文。
### 5.11 P8 quick verify 控制链路图
```mermaid
sequenceDiagram
participant Val as sentinel validate
participant Sen as Sentinel service
participant Obs as observe runner
participant Ctrl as control queue
participant Web as HWLAB Workbench
participant Ana as observe analyze
participant Rep as report/dashboard
Val->>Sen: /api/health through k3s Service DNS
Val->>Obs: observe start
Val->>Ctrl: command newSession
Ctrl->>Web: create Workbench session
Val->>Ctrl: command selectProvider/sendPrompt
Ctrl->>Web: submit business turn
Val->>Ana: observe analyze existing artifact
Ana->>Rep: report SHA, findings, turn-summary, trace-frame
```
Quick verify 的通过条件必须覆盖控制命令、业务 turn 和 analyze/report 三段。`monitor.pikapython.com` root/CSS/JS 200 只证明公开 dashboard 外壳可读，不得抵消 `newSession`、`sendPrompt`、trace rows 或 final response 缺失。
### 5.12 P8 故障分类数据流图
```mermaid
flowchart LR
Validate[sentinel validate] --> Shell[service/public dashboard health]
Validate --> Control[observe command health]
Validate --> Business[business turn health]
Validate --> Runtime[runtime/browser health]
Shell --> Result[validation result]
Control --> Result
Business --> Result
Runtime --> Result
Control --> NoTurn[quick-verify-no-business-turn]
Business --> Trace[turn-summary and trace-frame]
Runtime --> Timeout[timeout/readiness/session/api subtype]
```
分类必须先按 service/public-dashboard、control command、business turn、runtime/browser 分仓，再给可行动下一步。`browser-timeout` 不得默认归为浏览器安装或 Playwright 环境问题；它至少要被解释为页面导航、auth/login、Workbench readiness、session create、message submit、trace projection 或浏览器环境中的一个可复核子类。
### 5.13 P8 中文运维视图时序图
```mermaid
sequenceDiagram
participant U as 用户
participant D as 中文运维页面
participant API as dashboard API
participant CLI as CLI drill-down
U->>D: 打开 monitor.pikapython.com
D->>API: overview, runs, findings
API-->>D: 服务健康、公开入口、最近业务验证、阻塞分类
U->>D: 选择 blocked run/finding
D-->>U: 中文解释、证据、CLI 对照命令、下一步动作
U->>CLI: sentinel report / observe collect
CLI-->>U: 同一 run/observer/report SHA 的文字 trace 证据
```
中文运维页面必须默认展示中文状态、中文说明和中文下一步，同时保留原始 run id、observer id、finding code、report SHA 和 CLI 命令，便于 issue/PR 证据对照。
## 6. 原子需求
### 6.1 OPS-SENTINEL-REQ-001 非分叉 wrapper 边界
@@ -411,6 +474,10 @@ Web哨兵的 `sentinel report` 和 dashboard 必须按 YAML report views 渐进
Dashboard report API 必须提供 bounded、redacted、可分页的 view contract。`/api/overview` 提供 health、scheduler、maintenance、latest run、severity counts 和 freshness；`/api/runs` 提供 scenario/status/severity/time/search 过滤与 cursor 分页；`/api/runs/:id` 提供 run detail、report refs、artifact refs 和 summary counts；`/api/findings` 提供 severity/code/scenario/window 聚合；`/api/runs/:id/views` 提供 summary、turn-summary、findings 和 trace-frame 的只读渲染。所有响应都必须能追溯到 run id、observer id、stateDir 和 report SHA。
P8 起，quick verify 如果没有产生 sendPrompt 业务 turn、有效 session、trace rows 或 final response，必须记录独立 red blocker `quick-verify-no-business-turn`。该 blocker 属于 quick verify 控制层事实，不得由 dashboard 前端临时推断；dashboard 和 `sentinel report --view findings` 只能展示已记录的同一 finding。
P8 恢复判定必须把 Workbench 业务失败继续 drill-down 到运行面依赖。当 trace-frame 或 Final Response 暴露 `hwlab-cloud-api request handling failed`、PostgreSQL `53300`、`too many clients already` 或等价 DB 连接槽耗尽证据时，quick verify 不能收口为前端展示缺陷；必须检查 PK01/PostgreSQL `max_connections`、各服务连接池、CrashLoop 探针风暴和当前 `pg_stat_activity`，并通过 YAML source of truth 收敛容量或池化参数。
### 6.5 OPS-SENTINEL-REQ-005 CI/CD、GitOps 和 maintenance
| 编号 | 短名 | 主责模块 | 关联模块 |
@@ -427,6 +494,8 @@ HWLAB runtime 发布 Pipeline 应在 Argo sync 前调用当前哨兵 `maintenanc
哨兵服务不可用、首次安装未完成或配置未就绪时，CI/CD 必须结构化失败并输出缺失项、恢复建议和可重试命令；不得自动回退到原纯客户端 CLI、裸 Playwright、私有 API、read-side repair、reload 循环或 session repair 形成第二执行路径。人工排障可以显式运行原 `web-probe observe start/status/command/collect/analyze`，但不能被 targetValidation 当作自动通过证据。
`sentinel validate --quick-verify --confirm --wait`、maintenance stop quick verify 和 control-plane targetValidation 的确认等待总耗时超过 120s 时，必须输出 warning，并在 quick verify run 摘要中记录可见警告。warning 文案必须指向严重超时和下一步调查方向：env-reuse、git mirror、source build path、运行路径和当前 wait 阶段；不得通过调大 timeout、减少业务轮次或 fallback 到第二执行路径来消除红灯。
### 6.6 OPS-SENTINEL-REQ-006 dsflash-go 十轮 canary
| 编号 | 短名 | 主责模块 | 关联模块 |
@@ -489,6 +558,8 @@ Dashboard 前端架构应借鉴 Sub2API 监控面板的分层方式：typed API
Dashboard 自动刷新只能读取 bounded API，不得发送 `observe command`、不启动新采样、不重新 analyze、不保存额外截图。页面 hidden、loading 或上一次请求未完成时应暂停或跳过刷新，避免监控 UI 自身制造额外压力。
P8 中文运维页面必须以中文为默认用户可见语言：主标题、状态、筛选、运行历史、finding 分组、run detail、trace-frame、Final Response、空态、错误态、自动刷新和下一步动作均使用中文。原始英文 code、status 枚举、CLI 命令和 report SHA 可作为机器对照保留，但不得要求用户阅读英文 finding 才能判断 HWLAB 是否可用、卡在哪一层、下一步运行什么命令。
## 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)。
@@ -498,3 +569,5 @@ P0 未完成前，不得推进 CLI wrapper、服务实现、YAML schema、CI/CD
Dashboard 增强执行 issue 为 [#935](https://github.com/pikasTech/unidesk/issues/935)。P7 阶段跟踪 issue 为 P0 [#938](https://github.com/pikasTech/unidesk/issues/938)、P1 [#940](https://github.com/pikasTech/unidesk/issues/940)、P2 [#941](https://github.com/pikasTech/unidesk/issues/941)、P3 [#939](https://github.com/pikasTech/unidesk/issues/939)、P4 [#943](https://github.com/pikasTech/unidesk/issues/943)、P5 [#942](https://github.com/pikasTech/unidesk/issues/942) 和 P6 [#944](https://github.com/pikasTech/unidesk/issues/944)。P7 实现 PR closeout 必须回写 dashboard API contract、frontend 分层、trace-frame 对照、redaction、`monitor.pikapython.com` 验证和哨兵独立 CI/CD 状态。
P7 P6 收口必须区分 public dashboard validation 与 targetValidation quick verify：`monitor.pikapython.com` root/CSS/JS 200 只证明公开入口和静态 dashboard 资源可用；quick verify 的 `observe command`、采样样本、analyze report 和 red finding 仍是业务恢复判定的一部分。若 quick verify 因 `observe-command-newSession-failed`、`no-samples` 或等价采样器控制失败而 blocked，P6 issue 必须保持未关闭或显式拆出后续 blocker，不得只凭 public dashboard 200 关闭。
P8 哨兵恢复执行 issue 为 [#971](https://github.com/pikasTech/unidesk/issues/971)。P8 closeout 必须回写：SPEC P8 引用、120s warning 证据、`quick-verify-no-business-turn` 或等价业务触达证据、`browser-timeout` 分类修正、中文运维页面验证、`monitor.pikapython.com` 公网入口验证、k3s 内部 Service DNS quick verify 路径、D601/v03 用户入口 smoke 结果，以及仍未解除的真实业务 blocker 是否已单独拆出。