211 lines
7.6 KiB
Markdown
211 lines
7.6 KiB
Markdown
---
|
||
name: tjwater-workflow-simulation-diagnosis
|
||
description: 单步长水力计算与管网问题诊断工作流。
|
||
version: 3.0.0
|
||
---
|
||
|
||
# Simulation Diagnosis Workflow Skill
|
||
|
||
## 简介
|
||
`simulation run` → 查询模拟结果 → 快速综合诊断 → 结构化报告。覆盖超流速、低压区、高水损、死水管段、Closed 阀门等常见运行问题。
|
||
|
||
**仅依赖模拟结果**（无需管径/长度/粗糙度等属性），适用于快速巡检、初筛、事故后评估。如需结合管径做详细瓶颈评分与改造建议，走 `bottleneck-analysis` 工作流。
|
||
|
||
---
|
||
|
||
## 执行速览（Golden Path）
|
||
|
||
"跑一下水力计算看看管网有什么问题" 的标准执行路径：
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────────────┐
|
||
│ 1. tjwater_cli(command="simulation run --start-time ... │
|
||
│ --duration 30") │
|
||
│ ↓ 模拟结果写入服务端时序库 │
|
||
│ 2. tjwater_cli(command="data timeseries realtime links │
|
||
│ --start-time ... --end-time ...") │
|
||
│ ↓ (写为本地 JSON) │
|
||
│ 3. python diagnose_simulation.py result.json │
|
||
│ ↓ (stdout 结构化报告) │
|
||
│ 4. 解读脚本输出 → 按严重级别组织 Markdown 报告 │
|
||
│ ↓ (可选) │
|
||
│ 5. show_chart / locate_features / view_scada │
|
||
└──────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
> **关键原则**：排序/筛选/聚合全部在 Python 脚本或本地完成。前端工具仅用于渲染。
|
||
|
||
---
|
||
|
||
## 适用场景
|
||
|
||
| 场景 | 说明 |
|
||
|------|------|
|
||
| "跑一次水力计算看看管网有什么问题" | 直接适用，走 Golden Path |
|
||
| 管道属性接口不可用或数据不全 | 仅依赖模拟结果，无需属性数据 |
|
||
| 快速巡检 / 定期健康检查 | 低开销，脚本一秒给出问题概览 |
|
||
| 爆管/事故后的快速评估 | 单步稳态模拟，快速定位异常区域 |
|
||
| 作为 bottleneck-analysis 的前置筛查 | 先定位问题区域，再深入分析 |
|
||
|
||
---
|
||
|
||
## 阶段一：触发模拟运行
|
||
|
||
### CLI 调用
|
||
|
||
```
|
||
tjwater_cli:
|
||
command: "simulation run --start-time 2025-01-02T03:04:05+08:00 --duration 30"
|
||
```
|
||
|
||
- `--start-time`：模拟起始绝对时间，必须显式带时区（UTC+8）
|
||
- `--duration`：模拟持续分钟数
|
||
- 结果写入服务端时序库，不直接返回
|
||
|
||
### 查询模拟结果
|
||
|
||
```
|
||
tjwater_cli:
|
||
command: "data timeseries realtime links --start-time 2025-01-02T03:04:05+08:00 --end-time 2025-01-02T03:34:05+08:00"
|
||
timeout: 300
|
||
```
|
||
|
||
```
|
||
tjwater_cli:
|
||
command: "data timeseries realtime nodes --start-time 2025-01-02T03:04:05+08:00 --end-time 2025-01-02T03:34:05+08:00"
|
||
timeout: 300
|
||
```
|
||
|
||
### 返回数据结构
|
||
|
||
输出为 JSON，`data` 字段包含结果数组。
|
||
|
||
**links** — 管段水力状态：
|
||
| 字段 | 单位 | 说明 |
|
||
|------|------|------|
|
||
| link_id | — | 管段 ID |
|
||
| flow | LPS | 流量（正负表示流向） |
|
||
| velocity | m/s | 流速 |
|
||
| headloss | m | 水头损失 |
|
||
| status | — | Open / Closed / Critical |
|
||
|
||
**nodes** — 节点水力状态：
|
||
| 字段 | 单位 | 说明 |
|
||
|------|------|------|
|
||
| node_id | — | 节点 ID |
|
||
| demand | LPS | 需水量 |
|
||
| head | m | 水头 |
|
||
| pressure | KPA | 压力 |
|
||
|
||
---
|
||
|
||
## 阶段二：全局异常检查（优先！）
|
||
|
||
**在进入局部分析之前**，必须检查以下全局信号——如果命中则直接输出针对性诊断：
|
||
|
||
| 全局信号 | 判定条件 | 含义 | 处理 |
|
||
|---------|---------|------|------|
|
||
| **模拟断流** | 所有 link velocity ≈ 0 | 阀门全关 / 水源缺失 / 模型断连 | 检查模型配置，不做局部分析 |
|
||
| **模拟未收敛** | 所有 node pressure = 0 | 水力方程未收敛 | 检查 INP 设定，不做局部分析 |
|
||
| **系统性低压** | >70% 节点 pressure < 28 KPA | 水源水头不足 / 泵站扬程不够 | 输出"全局性低压"结论，排查水源/泵站 |
|
||
| **结果不完整** | links 或 nodes 结果为空 | 接口异常或模型损坏 | 报告数据不可用，提示重试 |
|
||
|
||
---
|
||
|
||
## 阶段三：自动诊断
|
||
|
||
### 使用 `diagnose_simulation.py`
|
||
|
||
脚本路径：`scripts/diagnose_simulation.py`
|
||
|
||
```bash
|
||
# 基本用法
|
||
python scripts/diagnose_simulation.py /tmp/opencode/sim_result.json
|
||
|
||
# 自定义阈值
|
||
python scripts/diagnose_simulation.py /tmp/opencode/sim_result.json \
|
||
--velocity-warn 1.2 \
|
||
--velocity-critical 2.0 \
|
||
--pressure-warn 40 \
|
||
--pressure-critical 28 \
|
||
--headloss-top 30 \
|
||
--flow-top 20
|
||
|
||
# 仅输出摘要
|
||
python scripts/diagnose_simulation.py /tmp/opencode/sim_result.json --summary-only
|
||
```
|
||
|
||
脚本自动完成：
|
||
- 全局统计（管段/节点总数，流速/压力/流量/水损的 max/mean/分位数）
|
||
- 超流速管段 TOP 20
|
||
- 高水损管段 TOP 30
|
||
- 低压节点统计
|
||
- 零流量管段、Closed 管段
|
||
- 高流量主干管 TOP 20
|
||
|
||
---
|
||
|
||
## 阶段四：报告生成与可视化
|
||
|
||
### 报告结构
|
||
|
||
```
|
||
---
|
||
## 管网运行诊断报告
|
||
|
||
### 一、模拟概况
|
||
- 时间窗口 / 管网规模 / 单位
|
||
|
||
### 二、主要发现（按严重程度排序）
|
||
🚨 紧急 / ⚡ 重点 / 📋 关注
|
||
每项含：问题标题 + 受影响数 + TOP 示例（3-5条含数据） + 可能原因 + 建议
|
||
|
||
### 三、数据局限
|
||
- 区分"数据直接支持的结论"和"工程经验的推测"
|
||
- 标注管径数据是否缺失及其对结论的影响
|
||
```
|
||
|
||
### 可视化（可选）
|
||
|
||
- `show_chart`：流速/压力分布柱状图
|
||
- `locate_features`：地图定位 TOP 问题管段
|
||
- `view_scada`：问题区域实时监测
|
||
- `render_junctions` + `store_render_ref`：按压力区间着色
|
||
|
||
---
|
||
|
||
## 诊断指标参考阈值
|
||
|
||
| 指标 | 阈值 | 依据 |
|
||
|------|------|------|
|
||
| 流速安全上限 | 1.2 m/s | 行业管道冲刷防护上限 |
|
||
| 流速紧急上限 | 2.0 m/s | 严重超速临界值 |
|
||
| 最低供水压力 | 28 KPA | 国标 GB 50268 |
|
||
| 正常压力下限 | 40 KPA | 居民供水压力下限 |
|
||
|
||
> 所有阈值为可调启发式，脚本支持参数覆写。
|
||
|
||
---
|
||
|
||
## 下游衔接：何时升级到 bottleneck-analysis
|
||
|
||
| 诊断发现 | 行动 |
|
||
|---------|------|
|
||
| 系统性低压（>70% 节点 <28 KPA） | **不**进入 bottleneck-analysis；排查水源/泵站 |
|
||
| TOP 20 超速管段中 ≥5 条流速 >1.5 m/s | 升级到 bottleneck-analysis |
|
||
| 存在多维度交叉异常管段 | 升级分析 |
|
||
| 仅少量告警、无紧急项 | 结束，不升级 |
|
||
|
||
**数据移交**：从 diagnosis 结果提取 TOP 问题管段 ID 列表，传入 bottleneck-analysis。
|
||
|
||
---
|
||
|
||
## Learned Patterns
|
||
|
||
- [d1f826184d8709db1988b00a] **渐进式 Top-K 分析**：大结果集先算全局统计量定位异常范围，再对 Top-K 做明细检查。
|
||
- [a19477bebe442e5d87bc78bc] **多准则交叉印证**：同时分析 velocity / headloss / flow / pressure 四个维度，紧急管段需满足多项异常条件。
|
||
- [cf50cc317b9bfe254426482d] **API 数据降级**：管道属性不可用时不停流程，用 velocity / headloss 作为代理指标。
|
||
- [1cd621a60d7481a1c072a54f] **系统性低压优先诊断**：全网 >70% 节点 pressure<28KPA 时定位为全局性问题。
|
||
- [a7c30102cf5c2a5c0e8cc8dd] **诊断脚本标准化**：`diagnose_simulation.py` 是分析主力，支持自定义阈值。
|
||
- [8b533e5bfc43c014ebcc90cf] **压力单位验证**：验证 pressure 字段实际单位（KPA vs m H₂O），阈值随单位调整。
|