feat(agent): sandbox conversation analysis

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

@@ -0,0 +1,146 @@
+---
+name: service-area-analysis
+description: 基于实时水力模拟数据的水源追溯供水服务范围分区。通过管段流量确定水流方向，从水库BFS追溯服务节点，环网/零流量节点用无向拓扑补充分配，输出分区可视化。
+---
+
+# 供水服务范围分区工作流
+
+## 概述
+
+本工作流基于指定时刻的水力模拟结果，通过**流向追溯法**将全部管网节点分配到各水库的服务范围。核心思路：利用管段流量符号判定水流方向，构建有向图从水库逐级追溯，对环网和零流量节点用无向拓扑修正。
+
+适用场景：供水服务范围评估、DMA分区规划、多水源供水格局分析、管网调度策略评估。
+
+## 分区方法
+
+### 第一步：水流方向判定
+
+对于每条管段，根据实时流量 `flow` 判定水流方向：
+
+| flow 值 | 水流方向 | 说明 |
+|---------|----------|------|
+| `flow > 1e-6` | node1 → node2 | 正向流量 |
+| `flow < -1e-6` | node2 → node1 | 反向流量 |
+| `|flow| ≤ 1e-6` | 无方向 | 零流量，不参与有向追溯 |
+
+### 第二步：多源有向BFS
+
+1. 以每个水库为根节点，沿水流方向执行 BFS
+2. 遍历到的节点归属该水库的服务范围
+3. **先到先得**：一个节点首次被访问到的水库即为归属
+4. 预期覆盖 **85–90%** 节点
+
+### 第三步：无向拓扑修正
+
+有向BFS不可达节点（通常 10–15%）通过无向图邻近性补充分配：
+
+| 不可达原因 | 说明 |
+|------------|------|
+| 环状管网 | 水流回路中下游节点反向连回上游，有向遍历被阻断 |
+| 零流量管段 | `flow≈0` 的管段无方向，其下游节点断开 |
+| 多水源交汇 | 交汇区流向往复，非树状拓扑 |
+
+### 输出统计
+
+每个分区输出：
+- `node_count`：分区内节点总数
+- `total_demand`：总需水量（负数=净供水区）
+- `avg_pressure`/`min_pressure`/`max_pressure`：压力统计
+
+## 数据依赖
+
+| 步骤 | 命令 | 数据量 | 超时 | 关键字段 |
+|------|------|--------|------|----------|
+| ① 管道拓扑 | `network get-all-pipes-properties` | ~11.7MB / 91K条 | 120s | id, node1, node2 |
+| ② 水库属性 | `network get-all-reservoirs-properties` | ~小 | 120s | id, links |
+| ③ 管段流量 | `data timeseries realtime links --start-time T --end-time T+15min` | ~39MB / 182K条 | 300s | id, flow, time |
+| ④ 节点数据 | `data timeseries realtime nodes --start-time T --end-time T+15min` | ~28MB / 176K条 | 300s | id, pressure, actual_demand, time |
+
+> **时间窗口**：模拟步长 15 分钟，查询 T~T+15min 覆盖 1–2 个时间步。脚本按 `--target-time` 精确筛选。
+
+> **文件输入**：四份调用都使用 `store_result=true`，包括结果较小的水库属性。脚本读取每次返回的 `data_file.file_path`；文件都属于当前对话，禁止使用 `/tmp` 或全局 `tool-output/`。
+
+## 执行步骤
+
+### 第 1 步：并行拉取数据
+
+4 个 `tjwater_cli` 调用（互不依赖），可一次发起：
+
+```bash
+# ① 管道静态拓扑
+tjwater_cli(command="network get-all-pipes-properties", timeout=120, store_result=true)
+
+# ② 水库属性
+tjwater_cli(command="network get-all-reservoirs-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/service_area_partition.py \
+  --pipe-props <data_file.file_path-①> \
+  --reservoirs <data_file.file_path-②> \
+  --links <data_file.file_path-③> \
+  --nodes <data_file.file_path-④> \
+  --target-time '2026-04-01T08:00:00+08:00' \
+  --output ./service_area_partition_wrapper.json
+```
+
+**脚本参数**：
+
+| 参数 | 说明 | 必填 |
+|------|------|------|
+| `--pipe-props` | 管道属性 JSON 文件路径 | 是 |
+| `--reservoirs` | 水库属性 JSON 文件路径 | 是 |
+| `--links` | 实时管段数据 JSON 文件路径 | 是 |
+| `--nodes` | 实时节点数据 JSON 文件路径 | 是 |
+| `--target-time` | 目标时刻 ISO8601 | 是 |
+| `--output` | 分区结果输出路径 | 是 |
+
+**输出**：
+- **stderr**：处理日志 + 各分区统计表格
+- **stdout**：紧凑 JSON 摘要（total_nodes, reservoirs, areas）
+- **文件**：符合 `store_render_ref` 要求的 `{metadata, location, data}` 包装 JSON，其中 `data` 包含 `node_area_map`、`area_ids`、`area_colors` 和分析元数据
+
+### 第 3 步：前端可视化
+
+```bash
+# 持久化分区结果
+store_render_ref(file_path=<output-file>)
+
+# 渲染节点分区
+render_junctions(render_ref="res-xxxxxxxx-xxxx-xx")
+
+# 定位水库
+locate_features(ids=[...], feature_type="reservoir")
+
+# 展示统计图表
+show_chart(title="各水源分区节点数/压力对比", chart_type="bar", ...)
+```
+
+## 参考数据规模
+
+基于 91,000 管段 / 88,000 节点规模的管网模型：
+
+| 指标 | 实测值 |
+|------|--------|
+| 管道拓扑数据量 | 91,052 条 |
+| 水库数量 | 13 个 |
+| 总节点数 | 87,907 |
+| 有向BFS分配节点 | ~76,900 (87.5%) |
+| 无向修正节点 | ~11,000 (12.5%) |
+| 分区覆盖率 | 100% |
+| 脚本处理时间 | ~15-30 秒 |
+| 峰值内存 | ~400-500MB |
+
+## 已知限制
+
+- **水库顺序敏感**：多源 BFS 中先遍历到的水库优先分配，不同水库启动顺序可能影响边界区域分配结果
+- **单时刻快照**：分区仅反映目标时刻的水力工况，不同时段的泵站启停、阀门切换可能导致分区边界变化
+- **零流量阈值**：`1e-6` 阈值过滤极低流量管段，若管网有长期小流量管段可能漏判方向

.opencode/skills/workflow/service-area-analysis/scripts/service_area_partition.py

@@ -0,0 +1,205 @@
+#!/usr/bin/env python3
+"""
+供水服务范围分析与分区 — 可复用脚本
+基于实时水力数据，从水库沿水流方向追溯服务范围，自动发现水库并分区。
+
+用法:
+  python3 service_area_partition.py \
+    --pipe-props pipes.json \
+    --reservoirs reservoirs.json \
+    --links realtime_links.json \
+    --nodes realtime_nodes.json \
+    --target-time '2026-04-01T08:00:00+08:00' \
+    --output ./service_area_partition_wrapper.json
+"""
+
+import argparse
+import json
+import os
+import sys
+from collections import deque, defaultdict
+
+COLORS = [
+    "rgba(31,119,180,0.7)", "rgba(255,127,14,0.7)", "rgba(44,160,44,0.7)",
+    "rgba(148,103,189,0.7)", "rgba(140,86,75,0.7)", "rgba(227,119,194,0.7)",
+    "rgba(127,127,127,0.7)", "rgba(188,189,34,0.7)", "rgba(23,190,207,0.7)",
+    "rgba(174,199,232,0.7)", "rgba(255,152,150,0.7)", "rgba(196,156,148,0.7)",
+    "rgba(219,64,82,0.7)", "rgba(153,204,153,0.7)", "rgba(255,204,102,0.7)",
+    "rgba(102,102,204,0.7)", "rgba(204,102,102,0.7)", "rgba(102,204,204,0.7)",
+    "rgba(204,153,204,0.7)", "rgba(153,153,153,0.7)"
+]
+
+def load_json(path, label):
+    print(f"Loading {label}...", file=sys.stderr)
+    with open(path) as f:
+        return json.load(f)
+
+def main():
+    parser = argparse.ArgumentParser(description="供水服务范围分区分析")
+    parser.add_argument("--pipe-props", required=True, help="管道属性 JSON 文件")
+    parser.add_argument("--reservoirs", required=True, help="水库属性 JSON 文件")
+    parser.add_argument("--links", required=True, help="实时管段数据 JSON 文件")
+    parser.add_argument("--nodes", required=True, help="实时节点数据 JSON 文件")
+    parser.add_argument("--target-time", required=True, help="目标时刻 ISO8601")
+    parser.add_argument("--output", required=True, help="分区结果输出 JSON 路径")
+    args = parser.parse_args()
+
+    # --- Step 1: Load pipe topology ---
+    pdata = load_json(args.pipe_props, "pipe topology")["data"]
+    pipe_topology = {}
+    node_neighbors = defaultdict(set)
+    for p in pdata:
+        pid = p["id"]
+        n1, n2 = p["node1"], p["node2"]
+        pipe_topology[pid] = (n1, n2)
+        node_neighbors[n1].add(n2)
+        node_neighbors[n2].add(n1)
+    print(f"  {len(pdata)} pipes, {len(node_neighbors)} unique nodes", file=sys.stderr)
+
+    # --- Step 2: Discover reservoirs ---
+    rdata = load_json(args.reservoirs, "reservoirs")["data"]
+    reservoirs = [r["id"] for r in rdata]
+    print(f"  {len(reservoirs)} reservoirs: {reservoirs}", file=sys.stderr)
+
+    # --- Step 3: Load link flow at target time ---
+    ldata = load_json(args.links, "link flows")["data"]
+    target_links = [l for l in ldata if l["time"] == args.target_time]
+    flow_direction = {}
+    pipe_flow = {}
+    for l in target_links:
+        lid = l["id"]
+        flow_val = l["flow"]
+        pipe_flow[lid] = abs(flow_val)
+        if lid in pipe_topology:
+            n1, n2 = pipe_topology[lid]
+            if flow_val > 1e-6:
+                flow_direction[lid] = (n1, n2)
+            elif flow_val < -1e-6:
+                flow_direction[lid] = (n2, n1)
+    nonzero = len(flow_direction)
+    print(f"  {len(target_links)} link records, {nonzero} with non-zero flow", file=sys.stderr)
+
+    # --- Step 4: Load node data at target time ---
+    ndata = load_json(args.nodes, "node data")["data"]
+    target_nodes = [n for n in ndata if n["time"] == args.target_time]
+    node_pressure = {}
+    node_demand = {}
+    for n in target_nodes:
+        nid = n["id"]
+        node_pressure[nid] = n.get("pressure", 0)
+        node_demand[nid] = n.get("actual_demand", 0)
+    print(f"  {len(target_nodes)} nodes", file=sys.stderr)
+
+    # --- Step 5: Build downstream graph ---
+    downstream = defaultdict(set)
+    for _lid, (up, dn) in flow_direction.items():
+        downstream[up].add(dn)
+    print(f"  downstream graph: {len(downstream)} source nodes", file=sys.stderr)
+
+    # --- Step 6: Multi-source BFS along flow direction ---
+    reservoir_area = {}
+    node_served_by = {}
+    queue = deque()
+    for rid in reservoirs:
+        reservoir_area[rid] = {rid}
+        node_served_by[rid] = rid
+        queue.append((rid, rid, 0))
+
+    while queue:
+        node, source, dist = queue.popleft()
+        for neighbor in downstream.get(node, set()):
+            if neighbor not in node_served_by:
+                node_served_by[neighbor] = source
+                reservoir_area[source].add(neighbor)
+                queue.append((neighbor, source, dist + 1))
+
+    directed_count = len(node_served_by)
+    unassigned = set(node_pressure.keys()) - set(node_served_by.keys())
+    print(f"  flow-tracing assigned: {directed_count}, unassigned: {len(unassigned)}", file=sys.stderr)
+
+    # --- Step 7: Undirected proximity fallback ---
+    if unassigned:
+        print("  running proximity fallback...", file=sys.stderr)
+        ua_queue = deque()
+        ua_visited = {}
+        for nid, src in node_served_by.items():
+            ua_visited[nid] = src
+            ua_queue.append((nid, src, 0))
+
+        while ua_queue:
+            node, source, dist = ua_queue.popleft()
+            for neighbor in node_neighbors.get(node, set()):
+                if neighbor not in ua_visited:
+                    ua_visited[neighbor] = source
+                    reservoir_area[source].add(neighbor)
+                    ua_queue.append((neighbor, source, dist + 1))
+
+        still = set(node_pressure.keys()) - set(ua_visited.keys())
+        if still:
+            print(f"  WARNING: {len(still)} nodes still unassigned", file=sys.stderr)
+        node_served_by = ua_visited
+
+    # --- Step 8: Compute statistics ---
+    print(f"\n=== 供水服务范围分区统计 ===\n", file=sys.stderr)
+    area_stats = []
+    for rid in reservoirs:
+        nodes_in = reservoir_area.get(rid, set())
+        pressures = [node_pressure[n] for n in nodes_in if n in node_pressure]
+        demands = [node_demand[n] for n in nodes_in if n in node_demand]
+        area_stats.append({
+            "reservoir": rid,
+            "node_count": len(nodes_in),
+            "total_demand": round(sum(demands), 4),
+            "avg_pressure": round(sum(pressures)/len(pressures), 2) if pressures else 0,
+            "min_pressure": round(min(pressures), 2) if pressures else 0,
+            "max_pressure": round(max(pressures), 2) if pressures else 0,
+        })
+
+    area_stats.sort(key=lambda x: x["node_count"], reverse=True)
+    for s in area_stats:
+        print(f"  水源 {s['reservoir']:>8s}: {s['node_count']:>6d} 节点 | "
+              f"总需水={s['total_demand']:.2f} | "
+              f"压力 avg={s['avg_pressure']:.1f}m [{s['min_pressure']:.1f}–{s['max_pressure']:.1f}m]",
+              file=sys.stderr)
+
+    # --- Step 9: Assign colors and write output ---
+    area_colors = {}
+    for i, rid in enumerate(reservoirs):
+        area_colors[rid] = COLORS[i % len(COLORS)]
+
+    output = {
+        "node_area_map": node_served_by,
+        "area_ids": reservoirs,
+        "area_colors": area_colors,
+        "metadata": {
+            "analysis_time": args.target_time,
+            "total_nodes": len(node_served_by),
+            "reservoir_count": len(reservoirs),
+            "directed_assigned": directed_count,
+            "proximity_assigned": len(node_served_by) - directed_count,
+            "method": "flow-direction-source-tracing"
+        }
+    }
+
+    absolute_output = os.path.abspath(args.output)
+    wrapper = {
+        "metadata": {
+            "generated_by": "service_area_partition.py",
+            "schema_version": 1,
+        },
+        "location": {"file_path": absolute_output},
+        "data": output,
+    }
+    with open(absolute_output, "w", encoding="utf-8") as f:
+        json.dump(wrapper, f, ensure_ascii=False)
+
+    summary = {
+        "total_nodes": len(node_served_by),
+        "reservoirs": len(reservoirs),
+        "areas": area_stats,
+        "output_file": absolute_output
+    }
+    print(json.dumps(summary, ensure_ascii=False))
+
+if __name__ == "__main__":
+    main()