---
name: hydraulic-bottleneck-analysis
description: 基于实时水力数据的管网水力瓶颈识别与改造建议。复合评分法（流速×水头损失）定位瓶颈管段，输出分级改造方案。
---

# 水力瓶颈分析工作流

## 概述

本工作流通过复合评分法（流速分级 × 水头损失百分位）从全管网管道中识别水力瓶颈管段，并结合节点压力、管径、粗糙系数给出分级改造建议。

适用场景：管网运行评估、管网改造优先级排序、泵站阀站运行诊断。

## 评分方法论

### 双维度复合评分

| 维度 | 判定标准 | 分值 |
|------|----------|------|
| **流速** | >3.0 m/s = 极危 | 3 |
|  | 2.0–3.0 m/s = 严重 | 2 |
|  | 1.5–2.0 m/s = 偏高 | 1 |
|  | <1.5 m/s = 正常 | 0 |
| **水头损失** | >P90 = 严重 | 2 |
|  | P80–P90 = 中度 | 1 |
|  | <P80 = 正常 | 0 |

**瓶颈判定**：`(流速≥1 且 水损≥1)` 或 `(流速≥2)` —— 即双侧超标或单侧流速严重。

**复合评分** = 流速分值 + 水损分值（最高 5 分），按降序排列。

### 辅助指标

| 指标 | 阈值 | 含义 |
|------|------|------|
| 节点压力 < 20m | — | 低压区域，需增压 |
| 节点压力 20–25m | — | 压力偏低 |
| roughness > 130 | — | 管壁粗糙，建议内衬修复 |

> ⚠️ **setting 字段无效**：`data timeseries realtime links` 返回的 `setting` 字段为无效值，不可用于阀门节流或水泵出口判定。若需确定阀门/泵状态，应通过 `network get-link-properties` 逐条查询。

## 数据依赖

| 步骤 | 命令 | 数据量 | 超时 | 关键字段 |
|------|------|--------|------|----------|
| ① 管道属性 | `network get-all-pipes-properties` | ~11.7MB / 91K条 | 120s | id, node1, node2, length, diameter, roughness |
| ② 管道水力 | `data timeseries realtime links --start-time T --end-time T+15min` | ~39MB / 182K条 | 300s | id, flow, velocity, headloss, time |
| ③ 节点压力 | `data timeseries realtime nodes --start-time T --end-time T+15min` | ~28MB / 176K条 | 300s | id, pressure, time |

> **时间窗口说明**：模拟步长 15 分钟，查询窗口取 `T~T+15min` 可覆盖 1–2 个时间步。脚本内部按 `--target-time` 精确筛选目标时刻的记录。

> **大结果集处理**：三份调用都使用 `store_result=true`，结果保存到当前对话的 `tool-data/` 目录。脚本直接读取每次返回的 `data_file.file_path`，不得访问全局 `tool-output/`。

## 执行步骤

### 第 1 步：拉取三份数据

并行发起 3 个 `tjwater_cli` 调用（互不依赖）：

```bash
# ① 管道静态属性
tjwater_cli(command="network get-all-pipes-properties", timeout=120, store_result=true)

# ② 目标时刻管道水力数据
tjwater_cli(command="data timeseries realtime links --start-time 2026-04-01T08:00:00+08:00 --end-time 2026-04-01T08:15:00+08:00", timeout=300, store_result=true)

# ③ 目标时刻节点压力数据
tjwater_cli(command="data timeseries realtime nodes --start-time 2026-04-01T08:00:00+08:00 --end-time 2026-04-01T08:15:00+08:00", timeout=300, store_result=true)
```

### 第 2 步：运行分析脚本

```bash
python3 <skill_dir>/scripts/bottleneck_analysis.py \
  --pipe-props <data_file.file_path-①> \
  --realtime <data_file.file_path-②> \
  --node-pressures <data_file.file_path-③> \
  --target-time '2026-04-01T08:00:00+08:00' \
  --top 50 \
  2>./bottleneck_report.txt
```

**脚本参数**：
- `--pipe-props`：管道属性 JSON 文件路径（必填）
- `--realtime`：实时管道水力 JSON 文件路径（必填）
- `--node-pressures`：实时节点压力 JSON 文件路径（必填）
- `--target-time`：目标时刻 ISO8601（必填，如 `2026-04-01T08:00:00+08:00`）
- `--top`：输出 Top N 瓶颈管段（默认 100）

**输出**：
- **stderr**：文本摘要 + Top 30 表格（可重定向到文件查看）
- **stdout**：完整 JSON 结果，包含 `summary` 和 `top_bottlenecks`（含每条的建议 `suggestions`）

### 第 3 步：结果解读与分类

按瓶颈严重程度和根因分类：

| 类别 | 判定条件 | 优先处理方案 |
|------|----------|--------------|
| 🔴 极危 | 流速>3.0m/s 且 水损>P90 | 检查模型/扩容/分流 |
| 🔵 串联瓶颈 | 连续多根瓶颈管段共享节点 | 统一规划扩径，一次性解除 |
| 🟣 低压区 | 端节点压力<20m | 扩径 + 评估中途加压 |
| 🟡 高粗糙度 | roughness>130 的瓶颈管段 | 内衬修复降阻 |
| 🟢 短管异常 | length<10m 且 headloss>P95 | 检查模型是否存在局部阻塞 |

### 第 4 步：可视化（可选）

1. **地图定位**：将 Top N 瓶颈管段用 `locate_features` 高亮到地图
2. **统计图表**：用 `show_chart` 展示管径分布柱状图 + 流速等级柱状图
3. **样式渲染**：可对 pipes 图层按 velocity 或 headloss 属性做分层设色

## 改造建议生成逻辑

脚本自动为每条瓶颈管段生成建议，规则如下：

```
if velocity > 2.0 → "流速X.XXm/s过高，需扩容或分流"
elif velocity > 1.5 → "流速X.XXm/s偏高"

if headloss > P95 → "水头损失X.XXm(>P95)严重超标"
elif headloss > P90 → "水头损失X.XXm(>P90)"

if diameter < 100 → "管径Xmm偏小，建议扩径至≥150mm"
elif diameter < 200 → "管径Xmm，评估扩容至250-300mm"

if roughness > 130 → "粗糙系数X偏高，建议内衬修复"

if min_pressure < 20 → "端节点压力X.Xm(<20m)，低压区域需增压"
elif min_pressure < 25 → "端节点压力X.Xm偏低"

if length < 0.01 and headloss > 0.5 → "短管高水损，检查是否存在模型异常或局部阻塞"
```

## 参考数据规模（实测）

基于 91,000 管段 / 88,000 节点规模的管网模型：

| 指标 | 实测值 |
|------|--------|
| 管道属性数据量 | 91,052 条 / ~11.7MB |
| 实时管道数据量 | 182,108 条（2步）/ ~38.7MB |
| 实时节点数据量 | 175,814 条（2步）/ ~28.2MB |
| 分析脚本处理时间 | 约 10-20 秒 |
| 典型瓶颈数量 | 50-100 条（占总管数 0.05%-0.1%） |

## 已知限制

- 水头损失百分位阈值（P80/P90）基于**全管网**统计，如果管网上游存在极端水损（如 400m+），会拉高整体 P 值，导致部分中高水损管段被漏判。极端场景下可考虑对水损做分位数裁剪（如排除 >P99.9 的离群值）后再计算 P80/P90。
- **setting 字段不可用**：`data timeseries realtime links` 返回的 `setting` 值为无效数据，本工作流已移除所有基于 setting 的阀门节流 / 水泵出口判定。若需要此类判定，应通过 `network get-link-properties` 逐条获取属性中的 setting 作为替代。
- 脚本读取全量 JSON 入内存，峰值内存约 200-300MB，需确保执行环境有足够内存。

## Learned Patterns
- [5cbdaa6bcf4e01c22eb2e544] [2026-08 复验] **schema 适配已固化进脚本**：bottleneck_analysis.py 现已直接使用 link_id/node_id 主键与 UTC target-time，无需再手工改码。本次 91,052 管段管网识别出 56 条瓶颈（0.06%），典型特征：100-110mm 小管径串联瓶颈（多条水损值近等差递减、逐段累计，如 7 段链 478128→460635→479635→508436→506699→484919→406224），宜按整链统一扩径；另有 1.4m 短管水损 67m 的模型异常信号（399832/399820），需核查局部阻塞或模型设置。分析后若用户需要改造建议落地，可按"极危...
- [5ba58cd24c9cea84b6ab5861] **数据 schema 实测适配（2026-04 验证）**：`data timeseries realtime links` 返回记录的管道主键为 `link_id`（不是 `id`），`data timeseries realtime nodes` 返回记录的节点主键为 `node_id`（不是 `id`），且 `time` 字段为 UTC 格式（如 `2026-04-01T00:00:00+00:00`）。运行 `bottleneck_analysis.py` 前需：① 脚本内将 `r['id']` 改为 `r['link_id']`、`n['id']` 改为 `n['node_id']`；② `--target-tim...