diff --git a/project-management/PJ2026-01/specs/PJ2026-010605-observability-monitoring.md b/project-management/PJ2026-01/specs/PJ2026-010605-observability-monitoring.md index a9074781..6dce1207 100644 --- a/project-management/PJ2026-01/specs/PJ2026-010605-observability-monitoring.md +++ b/project-management/PJ2026-01/specs/PJ2026-010605-observability-monitoring.md @@ -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. 过程控制`。 diff --git a/project-management/PJ2026-01/specs/PJ2026-01060508-web-probe-sentinel.md b/project-management/PJ2026-01/specs/PJ2026-01060508-web-probe-sentinel.md new file mode 100644 index 00000000..24f1b25e --- /dev/null +++ b/project-management/PJ2026-01/specs/PJ2026-01060508-web-probe-sentinel.md @@ -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
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
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 --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 或运行面证据,以及是否需要继续修订本规格。