TJWaterAgent/.opencode/skills/workflow/source-service-area-analysis/SKILL.md

name, description, version

name	description	version
tjwater-workflow-source-service-area-analysis	水源服务范围分区分析工作流。	2.0.0

Source Service Area Analysis Workflow Skill

简介

基于水力模拟结果的流向数据构建有向图，通过下游遍历确定每个节点的供水水源归属，生成分区渲染数据并在地图上以不同颜色展示各水源的服务范围。

前置依赖

依赖 1：水库（水源）列表

从模拟结果的 node_results 中识别 type=reservoir 的节点，或逐条查询已知水库节点。

依赖 2：管道拓扑数据

tjwater_cli:
  command: "network get-link-properties --link P1"

逐条获取管道 ID 的 node1（起端）、node2（终端），构建管网拓扑。

依赖 3：水力模拟结果

tjwater_cli:
  command: "data timeseries realtime links --start-time TIME --end-time TIME"
  timeout: 300

获取各管段的 flow(LPS) 和 status，确定水流方向。

• flow > 0 → node1 → node2
• flow < 0 → node2 → node1
• flow ≈ 0 或 status != "Open" → 忽略

---

工作流步骤

第 1 步：获取三大数据源

并行调用 CLI 命令获取模拟结果、管道拓扑和水库信息，写入本地临时 JSON 文件。

第 2 步：构建有向图并计算服务范围

python scripts/compute_service_areas.py \
  /tmp/opencode/sim_result.json \
  /tmp/opencode/pipes.json \
  /tmp/opencode/reservoirs.json \
  --output /tmp/opencode/service_area_result.json

脚本核心逻辑：

1. 构建无向拓扑图：从管道属性提取 (node1, node2)，构建邻接表
2. 确定流向：从模拟结果读取 flow 和 status
   • flow > 0 → node1 → node2
   • flow < 0 → node2 → node1
   • flow ≈ 0 或 status != "Open" → 忽略
3. 获取水源集合：从水库列表提取所有水库 ID 作为 source nodes
4. 多源 BFS 下游遍历：从所有水源节点同时出发，首次访问归属策略
5. 统计输出：各水源服务节点数、占比、未分配节点数
6. 生成渲染数据：node_area_map: { node_id: area_id }，每个水源分配唯一颜色

第 3 步：结果验证

• 服务覆盖率：正常管网应 > 80%
• 水源孤立：某水源服务节点数为 0，检查出口管道是否 Closed
• 大区未分配：检查区域与水源之间管道是否 Closed

第 4 步：前端可视化

1. store_render_ref 将 node_area_map 迁移为受控 render_ref
2. render_junctions 地图着色
3. locate_features 高亮水源位置
4. show_chart 各水源服务节点数柱状图（可选）

第 5 步：报告输出

---
## 水源服务范围分析报告

### 一、管网概况
- 总节点数 / 总管段数 / 水源数 / 覆盖率

### 二、各水源服务范围
| 水源 ID | 服务节点数 | 占比 | 颜色 |

### 三、未分配节点分析
- 数量、可能原因

### 四、假设与局限
- 流向基于稳态模拟，不代表所有工况
- 有向图忽略零流量管段

---

颜色调色板

脚本内置 20 色：

#1f77b4, #ff7f0e, #2ca02c, #d62728, #9467bd, #8c564b, #e377c2,
#7f7f7f, #bcbd22, #17becf, #aec7e8, #ffbb78, #98df8a, #ff9896,
#c5b0d5, #c49c94, #f7b6d2, #c7c7c7, #dbdb8d, #9edae5

证据约束

• 计算脚本的输出是唯一数据真相源
• 未完成数据回读时不得执行分析
• 零流量管段视为断连，需在报告中说明

Learned Patterns

• 核心数据流：模拟结果(流向) + 管道属性(拓扑) + 水库列表(起点) → 有向图 BFS → 分区渲染
• 有向图遍历前务必过滤 Closed 和零流量管段
• 渲染数据必须通过 store_render_ref 迁移再传给 render_junctions
• 多水源 BFS 首次访问归属策略隐含"距离最近水源"语义