KonkovDV/wellguard-os

# WellGuard OS v0.1.3 开放的本地部署 **咨询型演示系统**，用于基于常规遥测数据，对人工举升井（ESP）的复杂工况进行早期识别、分类和时间定位。 结合 Physics-guided 特征与 ML。**仅限咨询用途。** 不控制设备，不向 SCADA 系统写入数据。 ## 为什么它符合 INDUSTRIX 标准（因果链） **流程：** 复杂井（ESP）资产的开发运营。 → **损失：** 气塞、断流、堵塞、出水以及传感器漂移被瞬态过程掩盖 → 导致停机、产量损失、无效的现场作业以及 ESP 的过早失效。 → **目标用户：** 采油工程师、机械工程师、调度员。 → **输入：** ESP 的电流/频率/负载，井口压力/温度（P/T），入口压力，产液量，油管压力。 → **算法：** physics-residual（相似定律）+ 模式感知基线 + CUSUM + hold-time + quality gate → 事件分类。 → **行动：** 优先安排干预措施，将复杂工况与传感器漂移区分开来。 → **效果：** 检测延迟、precision/recall、每班次的误报次数、避免的停机时间。 ## 一条命令 ``` pip install -e ".[dev]" python -m wellguard.cli demo --scenario gas_interference # объяснимая карточка события python -m benchmark.run_benchmark # метрики + ML GroupKFold python -m benchmark.redteam # пороги приёмки, exit code 1 при нарушении python run_tests.py # pytest ``` API（只读，仅限 127.0.0.1）：`uvicorn wellguard.api:app --host 127.0.0.1 --port 8000` UI：`streamlit run app.py` Docker：`docker compose up`（仅绑定至 loopback）。 ## Pipeline QC（schema/单位/完整性）→ physics 特征（head_coef、q_per_freq、current_per_q、current_var）→ 模式感知稳健基线 → CUSUM + 持久性 hold-time → physics-guided 分类 → onset 时间定位 → 受控的操作指导卡。 **类别：** normal、gas_interference、intake_restriction、water_breakthrough_candidate、sensor_fault_suspected、operation_change、sensor_quality_issue。 ## Red-team 验收阈值（仅限合成数据） | 指标 | 阈值 | 当前值（12 个随机种子 × 7 种场景） | | --- | --- | --- | | class accuracy | ≥ 0.95 | **1.00** | | precision | ≥ 0.90 | **1.00** | | recall | ≥ 0.75 | **1.00** | | 每小时误报次数 | ≤ 0.5 | **0.0** | | 最大检测延迟 | ≤ 120 分钟 | **100 分钟** | | 将 sensor_fault 误判为复杂工况 | 0 | **0** | 参见 `docs/REDTEAM.md` 和 `artifacts/benchmark.json`。 ## 创新点 这不是“又一个 anomaly score”，也不是“泵故障预测”：系统通过跨通道的物理一致性，**将真实的复杂工况与传感器故障区分开来**，对 onset 进行时间定位，并生成可解释的卡片。Physics-guided 规则层控制决策；ML（GroupKFold，无数据泄露）作为辅助 score。 ## 验证数据 演示版本使用的是合成数据。用于适配的真实开放数据：Petrobras **3W**（真实的油井异常事件）、**ESPset**（ESP 振动故障）、Equinor **Volve**。参见 `docs/DATA_CARD.md`。 ## 试点 回顾分析 → 基于历史数据校准阈值 → 只读 shadow mode → go/no-go。参见 `docs/PILOT_PLAN.md`。 ## 许可证 Apache-2.0。 ## 审计状态 在 v0.1.1 版本中，修复了针对空/不完整/NaN 数据的 fail-open 情况，添加了 API 输入限制以及显式的单位适配器。benchmark 指标仍为合成数据；在 pinned release 上完成可复现运行之前，不宣称进行 public-data validation。 ## Pinned 3W, GPN archive, shadow mode - 3W loader：`wellguard/dataio/threew.py`，pinned to dataset 2.0.0，仅限本地，带有 SHA-256 manifest。 - GPN archive contract：`data/contracts/gpn_archive_schema.json` 和 `wellguard/dataio/gpn_archive.py`。 - Shadow replay：`shadow/run_shadow.py`，固定时间窗口，JSONL 决策日志，架构设计上严格只读。 - Runbooks：`docs/3W_PINNED_RUNBOOK.md`、`docs/SHADOW_MODE.md`。 项目不捆绑任何 GPN archive 或批准的标签字典。在所有者提供这些输入之前，本项目不会报告任何现场结果。 ## 发布 0.1.3 Red-team hardening：超范围/quality_ok 情况下的 fail-closed，稳定的 warmup baseline，affinity-gated operation_change，3W loader 中的 Pa→bar 转换，封装的 `wellguard.dataio`，API 行预检查，Docker 发布安全的 bind，沙箱化的 shadow 输出。 ## 发布 0.1.2 包含 Pinned local-only 的 3W Dataset 2.0.0 loader、SHA-256 manifest、严格的 GPN archive contract，以及固定时间窗口的只读 shadow replay。

标签：Apex, Kubernetes, 安全规则引擎, 工业数据分析, 异常检测, 机器学习, 油气物联网, 设备故障诊断, 请求拦截, 逆向工具, 遥测