docs: add web probe sentinel spec (#893)

Co-authored-by: Codex <codex@noreply.local>
2026-06-25 21:28:28 +08:00
parent aead554897
commit 07fda94925
2 changed files with 418 additions and 0 deletions
@@ -93,6 +93,7 @@
 | PJ2026-01060505 | Workbench性能 | [PJ2026-01060505 Workbench性能](PJ2026-01060505-workbench-performance.md) | Web 工作台用户可感知性能、RUM、AgentRun event visible latency 和 Prometheus 指标口径 | Web工作台、Agent编排、API契约 | 平台运维、客户端和性能回归调查 |
 | PJ2026-01060506 | Metrics接入 | 本规格 6.6 | metrics endpoint、scrape target 和 label 口径 | 各 L1 服务健康指标 | Prometheus 查询 |
 | PJ2026-01060507 | Rolling恢复观测 | 本规格 6.7 | active runner、reconciler backlog、terminal retry、projection lag 和不可恢复 blocker 的查询口径 | AgentRun核心、HWLAB接入、Workbench唯一投影、发布Lane | rolling 发布判定、故障收口 |
+| PJ2026-01060508 | Web哨兵 | [PJ2026-01060508 Web哨兵](PJ2026-01060508-web-probe-sentinel.md) | `web-probe observe` 的 YAML-first 生产哨兵、持续 canary、报告视图和发布恢复验证 | Web工作台、Workbench唯一投影、YAML运维、公开入口、发布流水 | 平台值守、CI/CD targetValidation、用户入口恢复判定 |

 ## 6. 原子需求

@@ -257,6 +258,20 @@ rolling recovery 相关 span 应能用 OTel trace id/request id 关联 `sessionI

 发布/rollout 前后的受控 CLI 摘要应能回答：仍在运行的 runner 数、已恢复控制权数量、cancel 当前阶段分布、terminal report retry 数、projection lag 最大值、不可恢复 blocker 数和最近一次 reconciler 错误。该摘要只用于定位和发布判定，不替代 P6 原入口 rolling/chaos 验收，也不能把可观测性 green 当作业务任务完成。

+### 6.8 OPS-MON-REQ-008 Web 哨兵
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| OPS-MON-REQ-008 | Web哨兵 | [PJ2026-01060508 Web哨兵](PJ2026-01060508-web-probe-sentinel.md) | [Web工作台](PJ2026-010401-web-workbench.md)、[Workbench唯一投影](PJ2026-0104010803-workbench-unique-projection.md)、[YAML运维](PJ2026-010603-yaml-first-ops.md)、[公开入口](PJ2026-010604-public-entry.md)、[发布流水](PJ2026-010601-controlled-release.md) |
+
+运维监控应提供 YAML-first Web 哨兵能力，把现有 `hwlab nodes web-probe observe start/status/command/collect/analyze` 服务化为生产可用的持续 canary、报告视图和发布恢复验证入口。该能力只 wrap 现有 observe runner、control queue、artifact JSONL、`collect` 渲染和 `observe analyze` 报告，不新增第二套 Playwright runner、offline analyzer、finding classifier、dashboard 事实源或 Workbench 状态机。
+
+Web 哨兵配置必须通过 node/lane root YAML 的 `observability.webProbe.sentinel.enabled/configRefs` 引用 runtime、scenario、promptSet、reportView、publicExposure、CI/CD 和 Secret owning YAML。parser 只校验引用、形状、类型和冲突；cadence、采样间隔、轮次、profile、prompt source、report view、retention、public exposure、maintenance 和 Secret 参数以 YAML 为准。
+
+Web 哨兵的首条生产 canary 应覆盖 `workbench-dsflash-go-tool-call-10x`：同一 HWLAB Workbench session 内十轮需要工具调用的任务，使用 `dsflash-go` backend profile，报告每轮 traceId、terminal status、tool-call evidence、耗时、慢 API、trace 顺序、terminal-not-last、session mismatch 和 final-response finding。`dsflash-go` profile、SecretRef、config 和 model catalog 缺失时必须结构化失败，不允许 fallback 到其他 profile。
+
+发布流水可调用 Web 哨兵 maintenance start/stop。maintenance start 暂停告警但继续采样；maintenance stop 触发同一 observe CLI quick verify 和 analyze。CI/CD targetValidation 对 HWLAB Web 恢复的判断必须包含 quick verify、analysis report SHA、finding 摘要、public origin、scenario id 和 observer/run id；Argo green 但哨兵 red/timeout 时不得判定发布恢复成功。
+
 ## 7. 过程控制

 本规格不单独索引过程 issue；跨 L1 的内测、灰度和阶段活动索引统一保留在 [PJ2026-01 HWLAB 总规格](PJ2026-01-HWLAB.md) 的 `7. 过程控制`。
@@ -0,0 +1,403 @@
+# PJ2026-01060508 Web哨兵
+
+## 修改历史
+
+| 版本 | 对应 commit id | 更新日期 | 变更说明 |
+| --- | --- | --- | --- |
+
+当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 `待提交` 版本。
+
+## 正文
+
+## PJ2026-01060508 Web哨兵需求规格
+
+## 1. 文档控制
+
+| 字段 | 内容 |
+| --- | --- |
+| 编号 | PJ2026-01060508 |
+| 短名 | Web哨兵 |
+| 层级 | L3 子课题 |
+| 状态 | 已生效 |
+| 实现引用版本 | draft-2026-06-25-p0-web-probe-sentinel |
+| 需求规格模板 | [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) |
+| 规格治理索引 | [规格治理](spec-governance.md) |
+
+本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留 Web 哨兵的稳定使命、范围、术语、系统边界、内部分工、目标图和原子需求。Web 哨兵是现有 `web-probe observe` 能力的生产化运行形态，不是新的探针实现。
+
+## 2. 目的和范围
+
+### 2.1 目的
+
+Web哨兵负责把已经用于 HWLAB Cloud Web 原入口验收的 `hwlab nodes web-probe observe start/status/command/collect/analyze` 能力服务化为 YAML-first 生产哨兵，使平台能够持续观察 HWLAB Web public origin、Workbench 多轮任务、Trace/final/timing 投影和发布后恢复状态。
+
+本规格的目标状态是：人工 CLI、常驻调度器、dashboard、maintenance API、CI/CD targetValidation 和后续 dry-run 都消费同一套 observe runner、control queue、artifact JSONL、`collect` 渲染和 `observe analyze` 报告。哨兵服务只负责编排、索引、展示和发布联动；它不得复制第二套 Playwright runner、DOM sampler、offline analyzer、finding classifier、Workbench 状态机或业务事实源。
+
+Web哨兵必须遵循 UniDesk YAML-first ops。目标 node/lane、public origin、runtime namespace、image、PVC、ServiceAccount、Service、NetworkPolicy、scenario、cadence、prompt source、report view、retention、maintenance token、dashboard public exposure、CI/CD control-plane 和 Secret sourceRef 都必须来自 owning YAML 或 configRef。代码只解析引用、校验形状/类型/冲突并渲染受控计划；不得把 namespace、cadence、threshold、Secret、image、URL、profile 或 report view 写成隐藏默认。
+
+### 2.2 范围内
+
+- `web-probe observe` CLI 的 wrapper/adapter 边界，使常驻服务能够稳定调用 start/status/command/collect/analyze。
+- YAML `observability.webProbe.sentinel.enabled/configRefs` 与 runtime、scenario、promptSet、reportView、publicExposure、Secret、CI/CD owning YAML 的引用图。
+- 常驻 TypeScript 单 Pod wrapper 服务、scheduler、scenario runner、PVC/SQLite index、health、metrics、maintenance API 和 dashboard。
+- `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 验证。
+- `workbench-dsflash-go-tool-call-10x` 生产 canary 和 24 小时 dry-run 收口。
+- Secret、prompt、provider payload、artifact 和 dashboard 的脱敏边界。
+
+### 2.3 范围外
+
+- Workbench 会话、message/part、Trace 顺序、final response、steer/cancel 和 timing authority 的业务正确性仍由 [PJ2026-0104010803 Workbench唯一投影](PJ2026-0104010803-workbench-unique-projection.md) 定义。
+- AgentRun run/command/provider profile 的执行生命周期归 [PJ2026-0102 Agent编排](PJ2026-0102-agent-orchestration.md) 和 [PJ2026-010205 HWLAB接入](PJ2026-010205-hwlab-dispatch.md)。
+- API path、错误 envelope、route policy 和用户身份语义归 [PJ2026-010403 API契约](PJ2026-010403-api-contract.md)。
+- 第一阶段不交付分布式压测；loadtest 只保留同镜像、同 wrapper 的配置和命令扩展点。
+- in-cluster 哨兵不是外部公网监控节点。若后续需要真正外网用户路径监控，应另行定义外部或边缘哨兵，不把当前服务伪装成外部观测点。
+- SQLite index、dashboard、metrics 和 maintenance 状态不得替代 `samples.jsonl`、`control.jsonl`、network/artifact JSONL 或 `analysis/report.json` 成为探针事实源。
+
+## 3. 术语表
+
+| 术语 | 定义 |
+| --- | --- |
+| Web哨兵 | 常驻 wrapper/orchestrator，按 YAML 调度现有 `web-probe observe` CLI，对 HWLAB Web public origin 做持续 canary、分析、展示和发布联动。 |
+| observe runner | 现有 `web-probe observe start` 启动的浏览器采样器；它写入 DOM、network、control、screenshot、artifact 等 JSONL。 |
+| observe artifact | `web-probe observe` 产生的 stateDir、JSONL、截图、analysis/report.md 和 analysis/report.json，是哨兵报告的事实来源。 |
+| CLI wrapper adapter | 服务与 CLI 共享的命令适配层，把 start/status/command/collect/analyze 表达为稳定调用，不复制 runner/analyzer 实现。 |
+| sentinel run | 哨兵调度一次 scenario 产生的运行窗口，绑定 node/lane、scenario id、observer id、stateDir、report SHA、finding 摘要和维护窗口状态。 |
+| scenario | YAML 声明的巡检或 quick verify 任务，包括 targetPath、cadence、sample interval、rounds、backend profile、promptSetRef、reportViewRef 和 analyze 阈值引用。 |
+| configRef | 形如 `path/to/file.yaml#object.path` 的配置引用。root YAML 只保存启用状态和引用，具体值归 owning YAML。 |
+| owning YAML | 拥有某类事实生命周期的 YAML 文件，例如 runtime、scenario、promptSet、reportView、publicExposure、CI/CD 或 Secret 分发。 |
+| report view | YAML 声明的 summary、turn-summary、findings、trace-frame 和 raw artifact 读取策略，包括默认分页、最大分页和 redaction。 |
+| synthetic prompt set | YAML 管理的合成 prompt 集。报告默认只展示 prompt id、hash、字节数和轮次编号，不展示原文。 |
+| maintenance window | 发布或维护期间的哨兵状态：继续采样和记录，但暂停告警；结束时触发 quick verify 和 analyze。 |
+| quick verify | 由 maintenance stop 或 CI/CD targetValidation 触发的一次短巡检，底层仍使用 `web-probe observe` CLI 和 `observe analyze`。 |
+| SQLite index | PVC 上的轻量索引，只保存 run、scenario、finding、report hash、artifact 摘要和 dashboard 分页信息；它不是业务或探针事实源。 |
+| public exposure | YAML 声明的 `monitor.pikapython.com` HTTPS 暴露，通过共享 PK01 Caddy + FRP managed-block helper 到达 ClusterIP Service。 |
+| targetValidation | 发布流水中的目标验证结果；对 HWLAB Web 恢复的判定必须来自 observe/analyze 对 public origin 的观察，不得只看 Argo green。 |
+
+## 4. 系统边界和接口
+
+| 边界项 | 内容 |
+| --- | --- |
+| 外部使用者 | 平台值守人员、发布操作人员、Workbench owner、CI/CD targetValidation、问题调查 agent。 |
+| 外部输入 | YAML configRefs、Secret sourceRef presence、HWLAB Web public origin、scenario cadence、maintenance 操作、observe artifacts、analyze reports、GitOps/Argo 状态。 |
+| 受控资源 | Web哨兵 Deployment、Service、PVC、ServiceAccount、NetworkPolicy、ConfigMap、publicExposure、SQLite index、dashboard 和 Prometheus metrics。 |
+| 外部输出 | sentinel status、health、metrics、dashboard、run list、report summary、turn-summary、findings、trace-frame、maintenance 状态和 targetValidation 结果。 |
+| 用户接口 | `bun scripts/cli.ts hwlab nodes web-probe sentinel ...`、`https://monitor.pikapython.com` dashboard、CI/CD maintenance 调用和受控 GitOps/control-plane CLI。 |
+| 系统边界 | Web哨兵只生产运行监控和发布恢复证据；不定义业务成功，不写第二套 Workbench 状态，不直接修复 Web，不读取或打印 Secret/prompt/provider payload。 |
+
+## 5. 内部分工与规格索引
+
+| 编号 | 内部模块 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 |
+| --- | --- | --- | --- | --- | --- |
+| PJ2026-0106050801 | Wrapper边界 | 本规格 6.1 | 只 wrap 现有 observe CLI，禁止第二 runner/analyzer | web-probe observe、Workbench唯一投影 | 服务化入口、人工排障 |
+| PJ2026-0106050802 | YAML配置 | 本规格 6.2 | configRefs、owning YAML、parser 校验和 redacted plan | YAML运维、公开入口、Secret分发 | plan/status、部署渲染 |
+| PJ2026-0106050803 | 常驻服务 | 本规格 6.3 | scheduler、scenario runner、PVC/SQLite、health、metrics、maintenance API | Wrapper边界、YAML配置 | dashboard、CI/CD |
+| PJ2026-0106050804 | 报告视图 | 本规格 6.4 | report/dashboard 渐进读取、分页、redaction、trace-frame | observe collect/analyze、Workbench唯一投影 | issue evidence、值守页面 |
+| PJ2026-0106050805 | 发布集成 | 本规格 6.5 | CI/CD、GitOps、Argo、maintenance、targetValidation、publicExposure | 发布流水、源码同步、公开入口 | 发布恢复判定 |
+| PJ2026-0106050806 | Canary验收 | 本规格 6.6 | dsflash-go 十轮工具调用、24 小时 dry-run 和 profile/fallback 边界 | Agent编排、Workbench、web-probe | 生产巡检收口 |
+| PJ2026-0106050807 | 安全隔离 | 本规格 6.7 | Secret/prompt/provider redaction、NetworkPolicy、public dashboard auth | 用户管理、平台运维 | 安全 closeout |
+| PJ2026-0106050808 | 代码引用 | 本规格 6.8 | SPEC 头部标注和生成/配置追溯 | 规格治理 | 后续 PR 审计 |
+
+### 5.1 目标架构图
+
+```mermaid
+flowchart LR
+  subgraph Config[UniDesk YAML source of truth]
+    Lane[hwlab-node-lanes.yaml<br/>sentinel enabled/configRefs]
+    Runtime[runtime owning YAML]
+    Scenario[scenario owning YAML]
+    Prompts[synthetic prompt YAML]
+    Report[report view YAML]
+    Exposure[publicExposure YAML]
+    Secrets[Secret sourceRef YAML]
+    Lane --> Runtime
+    Lane --> Scenario
+    Lane --> Prompts
+    Lane --> Report
+    Lane --> Exposure
+    Lane --> Secrets
+  end
+
+  subgraph Sentinel[Web哨兵 Pod]
+    Scheduler[Scheduler]
+    Adapter[observe CLI wrapper adapter]
+    Index[(SQLite index on PVC)]
+    API[/api health status runs maintenance]
+    Metrics[/metrics]
+    Dash[Dashboard SPA]
+    Scheduler --> Adapter
+    Scheduler --> Index
+    API --> Index
+    Dash --> API
+    Metrics --> Index
+  end
+
+  subgraph Observe[Existing web-probe observe]
+    Runner[observe runner]
+    Control[control queue]
+    Art[(samples/control/network/artifacts JSONL)]
+    Analyze[observe analyze]
+    Runner --> Art
+    Control --> Runner
+    Art --> Analyze
+  end
+
+  subgraph Target[Observed system]
+    Web[HWLAB Web public origin]
+    API2[HWLAB Cloud API]
+    AR[AgentRun backend profile dsflash-go]
+    Web --> API2
+    API2 --> AR
+  end
+
+  Scenario --> Scheduler
+  Adapter --> Runner
+  Adapter --> Control
+  Analyze --> Index
+  Runner --> Web
+  Dash -. HTTPS .-> Exposure
+```
+
+### 5.2 配置引用图
+
+```mermaid
+flowchart TD
+  Root[config/hwlab-node-lanes.yaml<br/>lanes.v03.targets.D601.observability.webProbe.sentinel] --> Enabled[enabled]
+  Root --> Refs[configRefs]
+  Refs --> Runtime[runtime.d601-v03.yaml#sentinel.runtime]
+  Refs --> Scenarios[scenarios.workbench.yaml#sentinel.scenarios]
+  Refs --> PromptSets[synthetic-prompts.yaml#promptSets]
+  Refs --> ReportViews[report-views.yaml#sentinel.reportViews]
+  Refs --> PublicExposure[public-exposure.d601-v03.yaml#sentinel.publicExposure]
+  Refs --> Cicd[hwlab-node-control-plane.yaml#targets.D601.lanes.v03.webProbeSentinel]
+  Refs --> SecretRefs[secrets-distribution.yaml#scopes.hwlab.webProbeSentinel.d601V03]
+  Scenarios --> PromptSets
+  Scenarios --> ReportViews
+  Scenarios --> AnalyzeThresholds[hwlab-node-lanes.yaml#...observe.analysisThresholds]
+  PublicExposure --> Edge[PK01 Caddy + FRP managed block]
+  SecretRefs --> Runtime
+  Cicd --> Runtime
+```
+
+配置引用图必须保持单向：root YAML 只保存 enable 与 ref；具体数值在 owning YAML；parser 只解析、校验和报告，不写合并后的新 source of truth。
+
+### 5.3 目标数据流图
+
+```mermaid
+flowchart TD
+  Y[YAML configRefs] --> Plan[sentinel plan/status]
+  Plan --> S[Sentinel scheduler]
+  S --> OStart[observe start]
+  S --> OCmd[observe command]
+  OStart --> Artifacts[Observe artifacts JSONL]
+  OCmd --> Artifacts
+  Artifacts --> Collect[observe collect]
+  Artifacts --> Analyze[observe analyze]
+  Analyze --> ReportJson[analysis/report.json]
+  Analyze --> ReportMd[analysis/report.md]
+  ReportJson --> Index[SQLite index]
+  ReportMd --> Index
+  Index --> ReportCli[sentinel report]
+  Index --> Dashboard[Dashboard]
+  Index --> Metrics[Prometheus metrics]
+  Index --> Validation[targetValidation]
+```
+
+`ReportCli`、dashboard、metrics 和 targetValidation 只能读取 artifact/report/index 摘要。它们不得重新访问 Workbench、重新采样页面、重排 trace 行、重新分类 finding 或从 SQLite 推导业务事实。
+
+### 5.4 常规巡检时序图
+
+```mermaid
+sequenceDiagram
+  participant Sch as Sentinel scheduler
+  participant CLI as observe wrapper adapter
+  participant Obs as observe runner
+  participant Web as HWLAB Web public origin
+  participant Ana as observe analyze
+  participant Idx as SQLite/PVC index
+
+  Sch->>CLI: observe start with YAML scenario
+  CLI->>Obs: start sampler/stateDir
+  Obs->>Web: passive sample and screenshots
+  Sch->>CLI: observe command newSession/selectProvider/sendPrompt
+  CLI->>Obs: enqueue control command
+  Obs->>Web: official UI/API action
+  Sch->>CLI: observe status until terminal/window end
+  Sch->>Ana: observe analyze stateDir
+  Ana-->>Idx: report SHA and findings summary
+```
+
+### 5.5 发布 maintenance 时序图
+
+```mermaid
+sequenceDiagram
+  participant CI as CI/CD Pipeline
+  participant Sen as Sentinel API
+  participant CP as Runtime control-plane
+  participant CLI as observe wrapper
+  participant Ana as observe analyze
+
+  CI->>Sen: maintenance/start release id
+  Sen-->>CI: sampling continues, alert muted
+  CI->>CP: rollout / Argo sync
+  CP-->>CI: runtime healthy summary
+  CI->>Sen: maintenance/stop
+  Sen->>CLI: quick verify observe start/command/status
+  CLI-->>Sen: observer/run/stateDir
+  Sen->>Ana: analyze quick verify artifact
+  Ana-->>CI: report SHA, findings, targetValidation status
+```
+
+### 5.6 哨兵自身 rollout 时序图
+
+```mermaid
+sequenceDiagram
+  participant CP as Sentinel control-plane
+  participant GitOps as GitOps repo
+  participant Argo as ArgoCD
+  participant Pod as Sentinel Pod
+  participant Val as sentinel validate
+
+  CP->>GitOps: publish digest-pinned manifests
+  Argo->>Pod: sync Deployment/Service/PVC
+  Val->>Pod: /api/health
+  Val->>Pod: /metrics
+  Val->>Pod: dashboard/public exposure probe
+  Pod-->>Val: scheduler heartbeat and PVC writable
+```
+
+哨兵自身 rollout 只验证哨兵服务健康、配置装载、PVC/SQLite 可写、metrics、dashboard 和调度循环；它不能把另一个哨兵当作 HWLAB Web 业务观察对象。
+
+### 5.7 纯 CLI fallback 时序图
+
+```mermaid
+sequenceDiagram
+  participant CI as CI/CD targetValidation
+  participant Sen as Sentinel service
+  participant CLI as web-probe observe CLI
+  participant Ana as observe analyze
+
+  CI->>Sen: validate or maintenance/stop
+  Sen-->>CI: unavailable or first-install
+  CI->>CLI: observe start/status/command quick verify
+  CLI->>Ana: observe analyze
+  Ana-->>CI: report SHA, findings, fallback=true
+```
+
+Fallback 只能退回原纯客户端 `web-probe observe` CLI，不得退回裸 Playwright、私有 API、reload repair、读侧补洞或手工浏览器判断。
+
+## 6. 原子需求
+
+### 6.1 OPS-SENTINEL-REQ-001 非分叉 wrapper 边界
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| OPS-SENTINEL-REQ-001 | Wrapper边界 | PJ2026-0106050801 Wrapper边界 | [Workbench唯一投影](PJ2026-0104010803-workbench-unique-projection.md)、[Web工作台](PJ2026-010401-web-workbench.md) |
+
+Web哨兵必须只编排现有 `hwlab nodes web-probe observe start/status/command/collect/analyze` 命令语义。常驻服务可以把这些 verb 包成稳定 adapter，但底层采样器、control queue、artifact schema、collect 渲染和 offline analyzer 必须与人工 CLI 共享同一实现或同一生成物。
+
+实现不得新增第二套 Playwright runner、DOM sampler、network sampler、control command 协议、JSONL artifact schema、offline analyzer、finding classifier 或 Workbench 状态机。若服务化需要能力增强，必须先补到现有 `web-probe observe` 命令面，再由哨兵调用。
+
+人工 CLI 是排障和原入口验收的一等入口；哨兵是调度入口。两者对同一 stateDir、同一 report 和同一 trace-frame 的解释必须一致。
+
+### 6.2 OPS-SENTINEL-REQ-002 YAML-first 配置引用
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| OPS-SENTINEL-REQ-002 | YAML配置 | PJ2026-0106050802 YAML配置 | [YAML运维](PJ2026-010603-yaml-first-ops.md)、[公开入口](PJ2026-010604-public-entry.md)、[源码同步](PJ2026-010602-source-sync.md) |
+
+Web哨兵配置必须通过 node/lane root YAML 的 `observability.webProbe.sentinel.enabled/configRefs` 进入，再引用 runtime、scenario、promptSet、reportView、publicExposure、CI/CD 和 Secret owning YAML。root YAML 不得承载所有 runtime/scenario/report/Secret 数值，也不得生成合并后的超级配置作为第二 source of truth。
+
+parser 只负责解析 `path/to/file.yaml#object.path` 或规格确认的等价引用，校验文件存在、路径存在、字段形状、类型、枚举键名、必填字段和重复事实冲突。缺失字段应报告 YAML path 和下一步 drill-down；不得用代码默认值补 namespace、image、cadence、timeout、threshold、profile、Secret、public URL、report view 或 retention。
+
+`sentinel plan/status` 必须输出 redacted 配置引用图：每个 ref 的文件、path、presence、摘要 hash、缺失字段、冲突字段和下一步命令。默认输出不得 dump 完整展开 YAML、Secret 值、prompt 原文或 provider payload。
+
+### 6.3 OPS-SENTINEL-REQ-003 常驻服务和 artifact 索引
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| OPS-SENTINEL-REQ-003 | 常驻服务 | PJ2026-0106050803 常驻服务 | [发布流水](PJ2026-010601-controlled-release.md)、[Workbench性能](PJ2026-01060505-workbench-performance.md) |
+
+Web哨兵服务应以 TypeScript/Node.js 实现，默认单 Pod 单副本。服务负责 scheduler、scenario runner、PVC/SQLite index、health、metrics、maintenance API 和 dashboard 静态资源；它不得直接写第二套 DOM 采样、网络采样、截图、Workbench 读取逻辑或 finding 分类。
+
+PVC 保存 SQLite index 和原始 `.state/web-observe` artifact。SQLite 只索引 run、scenario、finding、report hash、artifact 摘要、maintenance 状态和分页游标；它不得替代 JSONL/report 事实源，不参与 Workbench lifecycle、trace 顺序、final response 或业务状态仲裁。
+
+`/api/health` 必须覆盖 scheduler loop、SQLite/PVC 可写、最近 heartbeat、analyze 可执行性和必要配置装载。SQLite/PVC 不可写、scheduler 停摆、最近 heartbeat 超时或 analyzer 失败时，health 应非健康。`/metrics` 至少暴露 run 成功率、最近 finding 数、采样延迟、active observer 数和 maintenance 状态。
+
+Pod 重建后应从 PVC 恢复 index 与最近 artifact 摘要；进行中 run 可以标记 `interrupted` 并重新调度，不能静默假绿。
+
+### 6.4 OPS-SENTINEL-REQ-004 报告视图和 dashboard
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| OPS-SENTINEL-REQ-004 | 报告视图 | PJ2026-0106050804 报告视图 | [Workbench唯一投影](PJ2026-0104010803-workbench-unique-projection.md)、[Workbench性能](PJ2026-01060505-workbench-performance.md) |
+
+Web哨兵的 `sentinel report` 和 dashboard 必须按 YAML report views 渐进展示同一 observe/analyze artifact：run overview、turn-summary、findings、trace-frame/sample drill-down 和显式 raw artifact 下载。默认视图不得 dump JSONL，也不得展示 prompt 原文、完整 assistant 正文、cookie、token、API key、provider payload 或完整 stdout/stderr。
+
+`sentinel report --latest|--run <runId> --view summary|turn-summary|findings|trace-frame` 的默认分页、最大分页、可用 view、redaction 和 raw artifact 开关来自 owning YAML。完整 artifact 读取必须显式 `--raw` 或 `--artifact analysis/report.md|analysis/report.json`。
+
+自动 finding 必须能被 CLI trace 视图复核。若 analyzer finding 与 `trace-frame` 冲突，应以 `trace-frame` 暴露的有序 turn/message/part/final response 事实作为人工判定基准，并把 analyzer 精度问题登记到工具侧；dashboard 不得用聚合计数覆盖 CLI trace-frame。
+
+### 6.5 OPS-SENTINEL-REQ-005 CI/CD、GitOps 和 maintenance
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| OPS-SENTINEL-REQ-005 | 发布集成 | PJ2026-0106050805 发布集成 | [发布流水](PJ2026-010601-controlled-release.md)、[源码同步](PJ2026-010602-source-sync.md)、[公开入口](PJ2026-010604-public-entry.md) |
+
+Web哨兵自身必须纳入受控 CI/CD：Tekton 构建，GitOps 发布，ArgoCD 收敛，git-mirror 同步，所有可调事实来自 YAML。PipelineRun 不依赖 operator 本地 dirty worktree；触发前后必须通过受控 git-mirror sync/flush/recheck，closeout 证明 source commit、image digest、GitOps revision、Argo revision、PipelineRun、`pendingFlush=false` 和 `githubInSync=true`。
+
+哨兵镜像构建应使用 YAML 声明的 tools image、base image、registry、egress proxy 和 env-reuse 配方。Node/Bun/Playwright/Chromium 依赖不得在 runtime Pod 中临时下载。Secret 与 env 复用只走 sourceRef/keyMapping；日志、status、dashboard 和 issue closeout 只输出 object/key/presence/fingerprint/digest。
+
+HWLAB runtime 发布 Pipeline 应在 Argo sync 前调用当前哨兵 `maintenance/start`，进入观察不告警模式；sync 完成且业务 Deployment Ready 后调用 `maintenance/stop`，触发同一 observe CLI quick verify 和 analyze。targetValidation 不能只因 Argo `Synced/Healthy` 通过而绿；还必须包含 quick verify 结果、analysis report SHA、finding 摘要、public origin、scenario id 和 observer/run id。
+
+哨兵服务不可用或首次安装时，CI/CD 必须退回原纯客户端 `web-probe observe start/status/command/collect/analyze` quick verify，并把 fallback 事实写入 closeout。Fallback 不得使用裸 Playwright、私有 API、read-side repair、reload 循环或 session repair。
+
+### 6.6 OPS-SENTINEL-REQ-006 dsflash-go 十轮 canary
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| OPS-SENTINEL-REQ-006 | Canary验收 | PJ2026-0106050806 Canary验收 | [Agent编排](PJ2026-0102-agent-orchestration.md)、[Web工作台](PJ2026-010401-web-workbench.md)、[API契约](PJ2026-010403-api-contract.md) |
+
+第一条生产 canary 固定为 `workbench-dsflash-go-tool-call-10x`。所有运行参数都必须来自 configRefs 解析出的 owning YAML，至少包括 node/lane、public origin、targetPath、cadenceSeconds、sampleIntervalMs、screenshotIntervalMs、maxRunSeconds、maxConcurrentRuns、sessionPolicy、backendProfile、promptSetRef、rounds、requireToolCalls、report view、pagination、analyze thresholds、retention、publicExposure 和 maintenance 策略。
+
+调度器每隔 YAML 声明 cadence 创建新的 HWLAB Workbench session；每个 run 通过同一 `web-probe observe start` 启动采样，并通过同一 `observe command` 下发 `newSession`、provider 选择和十轮 prompt。prompt 原文必须由 prompt sourceRef 管理，报告只展示 prompt id/hash/bytes 和轮次编号。
+
+每一轮任务都必须需要工具调用。验收报告要证明十轮在同一 session 内完成，记录每轮 traceId、terminal status、tool-call evidence/count、耗时、慢 API、network/console/requestfailed finding、trace 顺序异常、terminal-not-last、session mismatch 和 final-response flicker。
+
+`dsflash-go` 是 AgentRun backend profile。实现必须验证 profile-scoped SecretRef、config 和 `model-catalog.json` presence/fingerprint；缺失时结构化失败，不允许 fallback 到 `codex`、`deepseek`、`minimax-m3` 或其他 profile。
+
+24 小时 dry-run 应在至少一个 HWLAB node/lane 完成，按 YAML cadence 形成不少于一天的 run 序列，并回写 observer/run id、stateDir/PVC 摘要、analysis report SHA、finding 摘要、截图/artifact 计数、Prometheus metrics 和 public dashboard HTTPS 验证。
+
+### 6.7 OPS-SENTINEL-REQ-007 安全、隔离和公开入口
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| OPS-SENTINEL-REQ-007 | 安全隔离 | PJ2026-0106050807 安全隔离 | [用户管理](PJ2026-0105-user-management.md)、[公开入口](PJ2026-010604-public-entry.md)、[YAML运维](PJ2026-010603-yaml-first-ops.md) |
+
+Web哨兵运行 namespace 与业务 runtime namespace 分离，具体 namespace、ServiceAccount、PVC、Service、NetworkPolicy 和 resource request/limit 由 YAML 声明。Service 默认 ClusterIP；不得用 NodePort、LoadBalancer、hostNetwork、hostPort 或手工 Ingress 暴露 dashboard。
+
+`monitor.pikapython.com` HTTPS 暴露必须走 YAML publicExposure，使用共享 PK01 Caddy + FRP managed-block helper 渲染。实现不得手工编辑 Caddyfile，不得替换其他 UniDesk managed block，不得复制 Caddy/FRP writer。public exposure closeout 必须验证 DNS、TLS、HTTPS、认证/维护 token、edge 和 ClusterIP upstream。
+
+Secret 只通过 sourceRef/targetKey 下发，CLI、服务日志、dashboard 和 issue evidence 只能输出 sourceRef、object、key、presence、fingerprint、hash、字节数和 redacted 摘要。prompt 原文、assistant 长正文、provider payload、cookie、token、API key、完整 DSN 和 stdout/stderr 不进入默认输出或 dashboard。
+
+NetworkPolicy 默认只允许 DNS、YAML 声明 public origin/必要 service endpoint、Prometheus scrape 来源和管理入口。任何扩大 egress/ingress 的变更必须先进入 owning YAML 和 plan 输出。
+
+### 6.8 OPS-SENTINEL-REQ-008 SPEC-first 与代码引用
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| OPS-SENTINEL-REQ-008 | 代码引用 | PJ2026-0106050808 代码引用 | [规格治理](spec-governance.md)、[YAML运维](PJ2026-010603-yaml-first-ops.md) |
+
+Web哨兵实现必须先引用本规格，再进入代码变更。新增或修改的 CLI、adapter、service、scheduler、dashboard、metrics、manifest renderer、public exposure helper、CI/CD helper 和 report renderer 源码文件头部必须标注 `SPEC: PJ2026-01060508 Web哨兵 draft-2026-06-25-p0-web-probe-sentinel`，并用一句话说明文件职责。
+
+实现文件不得只写 issue 编号、`latest`、`current` 或“按最新方案”作为规格引用。自动生成文件、第三方 vendored 文件、纯 YAML/config、锁文件和无法承载注释头的二进制产物不要求加源码头部，但对应生成器、渲染器、owning YAML 或 CLI 入口必须能追溯到本 SPEC。
+
+后续 P1-P6 阶段如果改变稳定需求、观察对象、数据流、接口、部署边界或验收口径，应先更新本规格和上级 [PJ2026-010605 运维监控](PJ2026-010605-observability-monitoring.md)，再更新执行 issue。
+
+## 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)。
+
+P0 未完成前，不得推进 CLI wrapper、服务实现、YAML schema、CI/CD、dashboard 或部署代码阶段。P1-P6 的 PR closeout 必须回写：使用的 SPEC 编号和实现引用版本、触达的源码文件头部标注情况、owning YAML/configRef 变更、原 CLI 入口兼容性、验证命令、public origin 或运行面证据，以及是否需要继续修订本规格。