你是否想過：「如果新竹內灣山區下起大暴雨，市區的經國大橋到底幾個小時後水位會開始暴漲？」
傳統上記者會說「請注意下游水位」，但身為工程師與 AI Agent 的推動者，我想知道的是精確的數字與物理過程：長度幾公里？落差幾公尺？平均坡降千分之幾？流速多少？
在這篇文章中，我將分享我們如何從最基礎的 水利署河川拓樸整理 開始，結合 OpenStreetMap (OSM) 向量幾何，再跨入 全球 3D 數位高程 (DEM)，最後讓 AI Agent 達成**「輸入一個 Prompt，自動算出一整份水力推算報告」**的實戰過程！
💡 一、痛點：從 2D 平面圖資到 3D 實體水文的跨越#
在過去探索河流時，我們往往只有平面地圖上的「一條線」。但在真實的水文世界裡，河流是 3D 立體 的：
- 2D 拓樸 (Parent-Child)：哪條支流匯入哪條主流？（例如：那羅溪 ➔ 油羅溪 ➔ 頭前溪）。
- 實體向量幾何 (OSM Geometries)：這條溪在實體地表上的折線軌跡到底長怎樣？哪裡有交點 (Node)？
- 3D 空間高程 (Z / Elevation)：這條溪的海拔高度是 1,000 公尺還是 30 公尺？坡降是陡降還是平緩？
如果沒有把這三者串起來，你就無法計算流速與洪峰抵達時間。
🛠️ 二、三階堆疊：我們是如何打造這套 AI 水力演算鏈的？#
為了讓 AI 能具備這種「深度水理思考力」，我們在專案中完成了三階工具堆疊：
[1. 拓樸幾何引擎 (confluence_atlas.py)]
│ ➔ 抓取 OSM 全台河流向量折線，11 秒計算實體匯流點交點
▼
[2. 3D 高程厚化 CLI (elevation_hydrator.py)]
│ ➔ 串接 Open-Elevation API，沿河道每 1km 自動採樣 Z 軸海拔
▼
[3. Agent 認知整合與一鍵 Prompt 輸出]
│ ➔ AI 讀取 3D 水網，直接算出流速、坡降與時間預警報告！1. 第一階：極速 11 秒水系幾何與匯流點演算 (Spec v3.1.0)#
我們首先解決了 OpenStreetMap 圖資對接的問題。透過一次性批次打包 Overpass QL 查詢，我們將頭前溪水系 40 條水脈的幾何抓取時間從 400 秒壓縮到 11 秒，並實現了 「水系唯一 Key (basin_130000_頭前溪_raw.json) 本地 100% 落庫」，第二次執行 0 秒秒讀連線！
2. 第二階：全球高程 API 與河道縱剖面採樣 (python scripts/elevation_hydrator.py)#
接著，我們寫出了全新的 elevation_hydrator.py CLI 工具。這個工具能做四件事：
query：查詢任意座標的海拔高度。hydrate-atlas：把高程注入匯流點 JSON。profile：善用本地 OSM 快取，沿著油羅溪每隔 1000 公尺採樣一個點的海拔，畫出縱剖面。slope：計算任意兩點間的落差與千分比水力坡降 ($S = \Delta H / L$)。
⛰️ 三、v2.4 重磅升級：終端機 3D 海拔縱剖面與 AI-Native JSONL 資料庫#
為了讓這套 3D 水文拓樸能真正普及給所有開發者與 AI Agent，我們在最新的 v2.4 版本 進行了大一統升級：
1. 終端機一鍵印出水系 3D 海拔縱剖面 (river_cli.py profile)#
我們升級了 river_cli.py 萬用工具。現在只需在終端機輸入 python scripts/river_cli.py profile 頭前溪，就能直接畫出帶有全形中文字精密對齊、高山至河口降落趨勢的 3D 剖面圖：
⛰️ 【頭前溪 水系全體水脈 3D 海拔縱剖面與降落趨勢圖】
📊 已獲取高程: 11 筆 (最高: 1291.0m | 最低: 121.0m) | 待厚化高程: 30 筆
================================================================================
花園溪 (130010-C01) | ██████████████████████████████ 1291.0 m
爺巴堪溪 (130010-C03) | ███████████████████████████ 1200.0 m
麥巴來溪 (130010-C02) | ███████████████████████ 1025.0 m
霞喀羅溪 (130011) | █████████████████████ 932.0 m
那羅溪 (130025) | ████████ 372.0 m
內灣幹線 (130023) | █████ 249.0 m
新庄子排水 (130021) | ████ 198.0 m
大肚溪 (130000-C04-C02) | ████ 178.0 m
王爺坑溪 (130000-C04-C01) | ███ 150.0 m
油羅溪 (130020) | ██ 121.0 m
上坪溪 (130010) | ██ 121.0 m
-------------------------------------------------------------------------------------
📋 [待厚化高程水脈清單]:
豆子埔溪 (130000-C01) | ░░░░░ ? m (待測量)
柯子湖溪 (130000-C02) | ░░░░░ ? m (待測量)
================================================================================2. 全台 1,418 筆水脈 AI-Native JSONL Master 資料庫#
資料庫正式從傳統 CSV 表格全面升級為 AI-Native 雙軌流式 JSONL (taiwan_river_topology_registry.jsonl)：
- 全量收納 1,418 條水脈（727 筆水利署官方 6 碼 + 691 筆民間延伸水脈）。
- 全量注入 356 筆實體匯流點經緯度與 3D 海拔高度 (
plugins.elevation)，並支援links權威外鏈與culture/pois人文景點擴充！
🌊 四、實戰驗證：一個 Prompt 算出的內灣暴漲預警報告#
當我們把這套底座建好後，我在對話視窗中輸入了一個極簡的 Prompt：
「如果在內灣下暴雨，新竹這邊的經國橋何時會水位爆漲？」
AI Agent 立刻自動發動剛才寫好的 elevation_hydrator 進行河道剖面採樣與坡降計算，不到 10 秒就給出了令人驚豔的實體分析：
📊 水文地理實體推算結果：#
| 段落 | 起點 ➔ 終點 | 河道距離 | 起終點高程 | 高程落差 $\Delta H$ | 平均坡降 $S$ |
|---|---|---|---|---|---|
| 上游陡坡段 | 內灣 ➔ 竹東大橋 | 6.93 km | 249m ➔ 139m | 110 m | 15.8 ‰ (山區陡降) |
| 中游平緩段 | 竹東大橋 ➔ 經國大橋 | 12.92 km | 139m ➔ 37m | 102 m | 7.9 ‰ (主流平緩) |
| 全路徑總計 | 內灣 ➔ 經國大橋 | 19.85 km | 249m ➔ 37m | 212 m | 10.7 ‰ |
⏱️ 時間預警結論：#
- 初波水位上升 ($T + 1.5 \text{ 小時}$)： 內灣暴雨發動後 90 分鐘，混濁水流抵達經國大橋，水位開始顯著上升。
- 洪峰最高暴漲 ($T + 2.5 \sim 3 \text{ 小時}$)： 暴雨發動後 2.5 至 3 小時，經國大橋迎來最高洪峰水位。
📖 📚 五、想了解更多？歡迎參閱《台灣河流探索專書》與標準規格書#
本文討論的所有原始碼、水力算例、CLI 工具說明書與 AI-Native JSON Schema 規格，均已完整開源並收錄於專書中，歡迎點擊以下連結深入閱讀：
- 🏠 專書開源主頁：《台灣河流探索專書 (RiverExploration Repo)》
- 📘 專書第 11.6 節 (大一統最新章節)：《全台灣 150 主流水系、AI-Native 雙軌 JSONL 資料庫與 3D 拓樸》
- 🛠️ CLI 萬用工具手冊：《river_cli.py 萬用查詢與 3D 轉譯手冊》
- 📜 JSON Schema 權威規格書：《WRA-Civ AI-Native JSONL Master 規格說明書 (Spec v2.4)》
📝 六、結語與心得#
這次的實驗過程讓我非常興奮。
過往我們以為要回答這種「幾點幾分會淹水」的問題，需要動用極其龐大的水利專業模擬軟體；但今天，透過 「乾淨的資料庫拓樸 + OSM 開放圖資 + 全球 DEM 高程 API + CGS 規範的 CLI 工具」，再搭配一個具備工具調用能力的 Agentic AI，我們在幾十分鐘內就建立出了一條可重複運算的水力分析流水線。
這就是人機協作最迷人的地方：工程師負責構建工具與架構防線，AI 負責即時演算與知識合成。
下一階段，我們準備把這套高程與縱剖面分析推展至全台灣 150 個水系，讓台灣每一條溪流都有屬於自己的 3D 數位雙生 (Digital Twin)！
AI 協作聲明： 本文由筆者提供原始遊記草稿與心情隨筆，由 AI 助手 Antigravity 彙整架構與修辭。結合了 WalkGIS 的地理紀錄特點與哈爸筆記的敘事風格，展現人機協作下的流域探索成果。