---
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），阈值随单位调整。