TJWaterAgent/.opencode/skills/workflow/hydraulic-bottleneck-analysis/SKILL.md

name, description

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

水力瓶颈分析工作流

概述

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

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

评分方法论

双维度复合评分

维度	判定标准	分值
流速	>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 调用（互不依赖）：

# ① 管道静态属性
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 步：运行分析脚本

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，需确保执行环境有足够内存。