README.md•30.1 kB
# MCP Civil Tools 伺服器
本專案是一個基於 MCP 協議的 Python 伺服器，主要是將水土保持技術規範(2023.05.04)透過 MCP Server 的方式提供給支援 MCP 的 client 調用，實現以自然語言與大模型對話的方式來進行查詢及計算，提供如曼寧係數查詢、土壓力係數、排水溝流速、邊坡穩定、土壤侵蝕、逕流量、擋土牆檢核、植生建議、材料參數、坡面保護、滲水設施、IDF曲線等查詢及計算功能。另外還提供台灣地區經緯度與 UTM/TWD97 座標的轉換。適用於 LLM 工具、Claude Desktop 等 AI 應用整合。
注意! 程式尚未完整，且每個大模型智力不等，輸出結果使用者務必再次核實，若有錯誤，歡迎反饋~
---
## 目錄結構
```
MCP-civil-tools/
├── src/
│ ├── mcp_server.py # MCP 伺服器主程式
│ ├── util.py # 座標轉換與土木工程工具邏輯
│ └── utm_types/
│ └── __init__.py # 型別定義
├── requirements.txt # 依賴套件
├── README.md # 專案說明
└── .gitignore # Git 忽略規則
```
---
## 安裝
1. 建議先建立虛擬環境：
```bash
python -m venv .venv
.venv\Scripts\activate # Windows
# 或 source .venv/bin/activate # Linux/macOS
```
2. 安裝依賴：
```bash
pip install -r requirements.txt
```
---
## 啟動方式
### 1. CLI (stdio) 模式
```bash
python src/mcp_server.py
```
### 2. HTTP 服務模式（建議用於 API 測試或 HTTP 整合）
```bash
uvicorn src.mcp_server:app --port 8000
```
---
## mcp.json 設定範例
若要讓 Claude Desktop 或其他 MCP 客戶端自動偵測並啟動本伺服器，MCP setting JSON 內容如下（請依實際路徑調整）：
```json
{
"mcpServers": {
"MCP-civil-tools": {
"command": "path/.venv/Scripts/python.exe",
"args": [
"path/src/mcp_server.py"
]
}
}
}
或是
"MCP-civil-tools": {
"command": "C:/TOMO/MCP-civil-tools/.venv/Scripts/python.exe",
"args": [
"C:/TOMO/MCP-civil-tools/src/mcp_server.py"
],
"disabled": true,
"autoApprove": []
},
```
- `command` 請填入你虛擬環境的 python.exe 絕對路徑。
- `args` 請填入 mcp_server.py 的絕對路徑。
以 Windowss 系統，Command args，輸入格式如下：
C:\TOMO\MCP-civil-tools\.venv\Scripts\python.exe C:\TOMO\MCP-civil-tools\src\mcp_server.py
以 MAC 系統，Command args，輸入格式如下：
/Users/tuchengshin/Documents/MCP/MCP-civil-tools/.venv/bin/python3
/Users/tuchengshin/Documents/MCP/MCP-civil-tools/src/mcp_server.py
---
## 參數預設行為說明
- 使用者只輸入緯度、經度時，沒有輸入其他資訊時，預設的 UTM/TM2 Zone 就是 TM2-121，預設的半球就是北半球。
- 當使用者只輸入平面座標 X, Y 時，預設的 UTM Zone 是 TWD97，半球是北半球。
---
## 主要功能更新
- **所有查表型工具皆支援「支援清單查詢」API**：
- 例如：`list_supported_materials`（常用材料）、`list_supported_manning_materials`（曼寧係數材料）、`list_supported_max_velocity_materials`（最大流速材料）、`list_supported_regions`（地區/IDF/年雨量）、`list_supported_soil_types`（土壤類型）、`list_supported_land_uses`（土地利用）、`list_supported_practices`（水保措施）、`list_supported_runoff_land_uses`（逕流係數土地利用）、`list_supported_slope_protection_methods`（坡面保護工法）、`list_supported_soil_k_types`（滲透係數土壤）、`list_supported_idf_locations`（IDF曲線地點）等。
- 查詢時若輸入錯誤或查無資料，會自動提示所有可查詢的支援項目，提升使用體驗。
- **2023/04/23 更新**：
- 修正 `list_supported_materials` 功能，現在可正確返回所有支援的常用材料設計參數材料名稱清單，包括：一般黏土、砂土、礫石、混凝土、花崗岩、石灰岩、頁岩、砂岩等。
- 新增四個 USLE 因子查詢工具：
- `query_r_factor_tool`：查詢降雨沖蝕指數 R 值（依據水土保持技術規範第35條）
- `query_k_factor_tool`：查詢土壤沖蝕指數 K 值（依據水土保持技術規範第35條）
- `query_c_factor_tool`：查詢覆蓋與管理因子 C 值（依據水土保持技術規範第35條）
- `query_p_factor_tool`：查詢水土保持處理因子 P 值（依據水土保持技術規範第35條）
- 修正 `calc_catchment_runoff` 功能，增強參數處理能力，現在可以正確處理自然語言輸入，例如「計算一個面積2公頃、降雨強度100mm/hr、逕流係數0.6的集水區最大逕流量」。
- 擴充 `check_retaining_wall` 功能，新增地震情況下的安全係數檢核：
- 依據水土保持技術規範第120條，增加地震時滑動安全係數（≧1.2）和傾倒安全係數（≧1.5）的檢核
- 增加合力作用點位置檢核，支援岩盤基礎和土層基礎兩種情況
- 修正承載力安全係數要求為3.0，符合規範要求
- 輸出報表中明確區分常時情況和地震情況的安全係數
---
## 個別工具使用範例
### 經緯度轉 UTM
- 輸入：自然語言描述經緯度，如「將緯度24.125、經度120.641轉換為UTM座標」
- 回傳：`"X,Y"` 字串，數值四捨五入到小數點下4位
#### 範例
```
輸入：請將緯度24.125193616011536、經度120.64098341751337轉換為UTM座標
回傳：203650.6040,2670482.4250
```
### UTM 轉經緯度
- 輸入：X, Y 座標（可選 zone, datum, south，預設 TWD97 北半球）
- 回傳：`"緯度,經度"` 字串，數值四捨五入到小數點下15位
#### 範例
```
輸入：請將 UTM 座標 X=203650.604、Y=2670482.425 轉換為經緯度
回傳：24.125193616011536,120.64098341751337
```
### 曼寧係數查詢
- 輸入：材料名稱（如「混凝土」、「純細砂」、「全面密草生」等）
- 回傳：該材料的曼寧係數 n 及最大容許流速範圍
#### 範例
```
輸入：全面密草生的曼寧係數是多少？
回傳：全面密草生 的曼寧係數 n = 0.040，最大容許流速範圍：1.5~2.5 m/s
依據：水土保持技術規範第18條及附件曼寧係數表
輸入：請查詢混凝土的曼寧係數
回傳：混凝土 的曼寧係數 n = 0.013，最大容許流速範圍：3.0~6.0 m/s
依據：水土保持技術規範第18條及附件曼寧係數表
```
### 主動土壓力係數計算
- 輸入：內摩擦角等資訊
- 回傳：主動土壓力係數 Ka、計算公式、依據等
#### 範例
```
輸入：內摩擦角30度的主動土壓力係數Ka是多少？
回傳：主動土壓力係數 Ka = 0.3333
依據：水土保持技術規範第117條及附件土壓力計算公式
說明：主動土壓力係數用於計算擋土結構所承受的水平推力，是擋土牆設計的重要參數。
```
### 被動土壓力係數計算
- 輸入：內摩擦角等資訊
- 回傳：被動土壓力係數 Kp、計算公式、依據等
#### 範例
```
輸入：內摩擦角30度的被動土壓力係數Kp是多少？
回傳：被動土壓力係數 Kp = 3.0
依據：水土保持技術規範第117條及附件土壓力計算公式
說明：被動土壓力係數用於計算擋土結構的抵抗力，是擋土牆穩定分析的重要參數。
```
### 排水斷面流速/流深/流量計算（多斷面支援）
- 輸入：斷面型式、流量、坡度、曼寧係數、渠道材質、尺寸等資訊
- 回傳：流速、流深、斷面積、水力半徑等計算結果，以及完整報告書
#### 計算邏輯與警告說明（2024/06修正版）
- 若輸入流量超過該斷面滿流時的最大流量，系統會直接回傳錯誤訊息，提示「所需流量已超過滿流最大流量，請加大尺寸或坡度」。
- 只要流量未超過滿流，計算會自動求得一個合理的流深（小於溝高），不會誤報滿流。
- 滿流警告僅在流深極接近高度且流量極接近滿流時才會出現。
- 計算精度與收斂條件已優化，避免工程常用情境下出現誤判。
#### 最大/最小容許流速規則
- 最大容許流速：
- 僅檢核最大值（如混凝土6.1m/s、鋼筋混凝土12.0m/s、粗砂及細砂0.61m/s等），超過時系統將警告並建議設置消能設施。
- 表格中無"鋼筋混凝土"之最大容許流速，系統已新增最大值12.0m/s。
- 最小容許流速：
- 僅混凝土與鋼筋混凝土排水設施明確規定最小容許流速為0.8 m/s，低於時系統將警告可能導致泥砂淤積。
- 其餘材質未見明確規定，系統不檢核最小值。
- 檢核建議：設計排水之流速超過其最大容許流速者，應於適當位置設置消能設施。
#### 出水高（流深）規範檢核（第86條）
- 矩形、梯形排水溝之出水高（流深）應符合：
- 不得小於設計水深的25%
- 最小值為20公分
- L型、拋物線型排水溝不在此限
- 若計算流深低於上述標準，系統將於回傳結果與報告書中給予明確警告，請調整設計參數。
#### 範例
```
輸入：計算寬50公分，高70cm的鋼筋混凝土矩形溝，流量1cms，坡度5%，流速和流深? 輸出完整報告，含計算過程及計算式。
回傳：
流速: 7.20 m/s，流深: 0.250 m。警告：計算流速 v = 7.2000 m/s 已超過『鋼筋混凝土』最大容許流速 12.0 m/s，應於適當位置設置消能設施。
輸入：計算寬50公分，高70cm的混凝土矩形溝，流量0.2cms，坡度0.5%，流速和流深?
回傳：
流速: 0.65 m/s，流深: 0.120 m。警告：計算流速 v = 0.6500 m/s 低於『混凝土』最小容許流速 0.8 m/s，可能導致泥砂淤積。
【排水斷面流速/流深/流量計算報告】
斷面型式：矩形
矩形底寬 b=50.0cm, 高度 h=70.0cm
流量 Q = 1.000 cms
坡度 S = 5.000%
曼寧係數 n = 0.013
渠道材質：鋼筋混凝土
【計算公式】
Q = A × V, V = (1/n) × R^(2/3) × S^(1/2)
【計算步驟】
A = b×y, P = b+2y, R = A/P, V = (1/n)R^(2/3)S^(1/2), Q = A×V
【計算結果】
流速 V = 2.340 m/s
流深 y = 0.210 m
斷面積 A = 0.1050 m²
水力半徑 R = 0.0700 m
周長 P = 1.0000 m
計算結果符合安全流速規範。
【檢核警告】計算流深 y = 0.210 m 不符第86條規範，應≧max(0.2m, 設計水深25%)=0.250 m。請調整設計。
```
### 邊坡穩定安全係數計算
- 輸入：坡度、單位重、摩擦角、凝聚力、地下水位、方法等資訊
- 回傳：安全係數、方法、是否合格、說明
#### 範例
```
輸入：請計算坡度30度、土壤單位重18kN/m³、摩擦角30度、凝聚力10kPa的邊坡穩定安全係數
回傳：安全係數 = 1.50，方法：簡化法，合格：True
依據：水土保持技術規範第31條及附件安全係數表
說明：邊坡穩定安全係數應大於1.5，本案例符合規範要求。
```
### 土壤侵蝕模數/流失量計算
- 輸入：坡長、坡度、降雨、土壤類型、土地利用、水保措施等資訊
- 回傳：侵蝕模數、流失量、方法、說明
#### 範例
```
輸入：計算坡長100公尺、坡度10%、年降雨量1200mm、砂土、草地、等高耕作的土壤流失量
回傳：土壤侵蝕模數/流失量 = 42.75 公噸/公頃/年
依據：水土保持技術規範第35條及附件USLE公式、參數表
說明：USLE公式為國際通用土壤流失量推估方法，台灣水保規範明定可用於坡地土壤侵蝕評估。
```
### 集水區最大逕流量計算
- 輸入：集水區面積、降雨強度、逕流係數等資訊
- 回傳：最大逕流量、方法、說明
#### 範例
```
輸入：計算一個面積2公頃、降雨強度100mm/hr、逕流係數0.6的集水區最大逕流量
回傳：最大逕流量 Q = 0.33 cms，方法：Rational
依據：水土保持技術規範第16、17、18條及附件降雨強度、逕流係數表
說明：集水區面積小於1000公頃時，無實測資料可採Rational公式計算洪峰流量。
```
### 護岸/擋土牆穩定檢核
- 輸入：牆高、厚度（矩形斷面）或頂寬/底寬（梯形斷面）、單位重、摩擦角、凝聚力、背填坡度、地下水位、地震係數、基礎類型等資訊
- 回傳：常時與地震情況下的滑動、傾倒安全係數、合力作用點位置、是否合格、說明
#### 範例（矩形斷面）
```
輸入：檢核一座高2公尺、厚1公尺的擋土牆，土壤單位重18kN/m³、摩擦角30度、凝聚力10kPa、背填坡度10度，地震係數0.15，土層基礎
回傳：
【常時情況】
滑動SF=1.65（≧1.5 合格），傾倒SF=2.30（≧2.0 合格），承載SF=3.10（≧3.0 合格），合力作用點位置合格
【地震情況】
滑動SF=1.25（≧1.2 合格），傾倒SF=1.60（≧1.5 合格），合力作用點位置合格
依據：水土保持技術規範第117、118、120、164條及附件最小安全係數表
說明：擋土牆設計須同時檢核常時與地震情況下的滑動、傾倒安全係數及合力作用點位置，並符合規範建議標準。
```
#### 範例（梯形斷面）
```
輸入：檢核一座高2公尺、頂寬0.5公尺、底寬1公尺的梯形擋土牆，土壤單位重18kN/m³、摩擦角30度、凝聚力10kPa，地震係數0.15，土層基礎
回傳：
【牆體幾何與重量】
梯形斷面：高度 = 2.00 m，頂寬 = 0.50 m，底寬 = 1.00 m，牆體單位重 = 24.00 kN/m³
牆體重量 W = 24.00 × (1.00 + 0.50) × 2.00 / 2 = 36.00 kN/m
重心位置 x_g = 0.56 m
【常時情況】
滑動SF=1.78（≧1.5 合格），傾倒SF=2.45（≧2.0 合格），承載SF=3.25（≧3.0 合格），合力作用點位置合格
【地震情況】
滑動SF=1.32（≧1.2 合格），傾倒SF=1.75（≧1.5 合格），合力作用點位置合格
依據：水土保持技術規範第117、118、120、164條及附件最小安全係數表
說明：擋土牆設計須同時檢核常時與地震情況下的滑動、傾倒安全係數及合力作用點位置，並符合規範建議標準。
```
### 植生護坡設計建議
- 輸入：坡度、土壤類型、氣候等資訊
- 回傳：建議工法、草種、覆蓋率、說明
#### 範例
```
輸入：請針對坡度30度、壤土、亞熱帶氣候的邊坡提供植生護坡設計建議
回傳：建議工法：噴播草皮+格框或土工網，分區分期施工
草種：百慕達草、狗牙根、地毯草等耐旱耐沖蝕草種
覆蓋率：90.0%
依據：水土保持技術規範第8、167、172條及附件坡度分級、樣區面積、覆蓋率等規定
```
### 常用材料設計參數查詢
- 輸入：材料名稱
- 回傳：單位重、凝聚力、摩擦角、強度、說明
#### 範例
```
輸入：請提供一般黏土的設計參數
回傳：材料：一般黏土，單位重：18.0kN/m³，凝聚力：20.0kPa，摩擦角：25.0°，強度：200.0kPa
依據：常用土壤工程手冊
```
### 坡面保護工法建議
- 輸入：坡度、土壤類型、降雨量等資訊
- 回傳：建議工法、說明
#### 範例
```
輸入：坡度30%、砂土、年降雨量1200mm的坡面，建議採用什麼保護工法？
回傳：建議工法：噴播草皮+格框或土工網
說明：坡度較大時應加強排水設施與坡面穩定措施
依據：水土保持技術規範第8、167、172條及附件坡度分級表
```
### 滲水設施設計
- 輸入：設施型式、土壤滲透係數、集水面積、降雨量等資訊
- 回傳：設計流量、建議尺寸、說明
#### 範例
```
輸入：請設計一個滲水井，土壤滲透係數k=0.001cm/s，集水面積100平方公尺，年降雨量1200mm
回傳：設施型式：滲水井，設計流量：0.033cms，建議尺寸：直徑1.2m，深度1.8m
依據：水土保持技術規範第94條及附件滲透設施設計準則
說明：滲水井設計需考慮土壤滲透性、集水面積及當地降雨特性，並定期維護以確保功能。
```
### IDF曲線查詢
- 輸入：地點、重現期、歷時等資訊
- 回傳：降雨強度、說明
#### 範例
```
輸入：請查詢台中市10年重現期、60分鐘歷時的降雨強度
回傳：地點：台中市，重現期：10年，歷時：60分鐘，強度：78.5 mm/hr
依據：水土保持技術規範第15條及附件IDF曲線公式
說明：IDF曲線反映不同重現期與歷時下的降雨強度，用於水文分析與水利設施設計。
```
### 查詢支援清單
- 你可以直接查詢有哪些可用的材料、地區、工法等：
```
查詢：有哪些常用材料？
回傳：['一般黏土', '砂土', '礫石', '混凝土', ...]
查詢：可以查詢哪些水溝鋪面的曼寧係數？
回傳：['純細砂', '混凝土', '全面密草生', ...]
查詢：有哪些坡面保護工法？
回傳：['草皮或直接播種', '噴播草皮+格框/土工網', ...]
查詢：有哪些IDF地點？
回傳：['台北市', '新北市', '台中市']
```
### 查詢失敗時自動提示
- 若查詢時輸入錯誤，會自動回傳所有支援查詢的項目：
```
輸入：查詢不存在的材料名稱
回傳：查無此材料，支援查詢的材料有：一般黏土, 砂土, 礫石, 混凝土, ...
```
## 土石籠擋土牆穩定分析
此功能用於分析土石籠擋土牆的穩定性，包括主動和被動土壓力計算。
### 使用方法
```python
result = check_gabion_stability(
height=3.0, # 土石籠高度 (m)
width=2.0, # 土石籠寬度 (m)
wall_weight=100, # 擋土牆總重 (kN/m)
phi=30, # 土壤內摩擦角 (°)
delta=20, # 牆背摩擦角 (°)，預設 0
theta=0, # 牆背傾斜角 (°)，預設 0
i=0, # 地表傾斜角 (°)，預設 0
gamma=18, # 土壤飽和單位重 (kN/m³)，預設 18
friction_coef=0.5, # 摩擦係數，預設 0.5
pressure_mode="active" # 土壓力模式 ("active" 或 "passive")，預設 "active"
)
```
### 回傳結果
函數回傳一個字典，包含以下內容：
- `success`: 布林值，表示計算是否成功
- `data`: 計算結果數據，包含：
- `earth_pressure_coef`: 土壓力係數
- `total_pressure`: 總土壓力 (kN/m)
- `vertical_force`: 垂直力分量 (kN/m)
- `horizontal_force`: 水平力分量 (kN/m)
- `restoring_moment`: 抗傾覆力矩 (kN·m/m)
- `overturning_moment`: 傾覆力矩 (kN·m/m)
- `overturning_safety_factor`: 抗傾覆安全係數
- `sliding_safety_factor`: 抗滑動安全係數
- `message`: 計算結果摘要
- `report`: 完整的計算報告書（Markdown 格式）
### 計算報告書內容
報告書包含以下章節：
1. 輸入參數
2. 計算公式
3. 計算結果
4. 穩定評估
### U型溝鋼筋量計算
- 輸入：
- height: 溝高 (m)
- wall_slope: 溝壁傾角 (m)
- soil_slope: 土方傾角 (°)
- soil_angle: 安息角 (°)
- effective_depth: 有效厚度 (m)
- soil_weight: 土重 (kN/m³)，預設 18.0
- 回傳：dict，含計算結果與報告書
#### 範例
```
輸入：混凝土溝，height=1.5, wall_slope=0.5, soil_slope=15, soil_angle=30, effective_depth=0.2，計算水溝所需的鋼筋量，建議的配筋?
回傳：
{
"success": true,
"data": {
"earth_pressure_coef": 0.3333,
"earth_pressure": 6.750,
"moment": 3.375,
"rebar_area": 13.780
},
"message": "土壓力係數 Ka = 0.3333, 土壓力 P = 6.750 kN/m, 彎矩 M = 3.375 kN·m/m, 鋼筋量 As = 13.780 cm²/m",
"report": "【U型溝鋼筋量計算報告】\n\n輸入參數：\n- 溝高 H = 1.500 m\n- 溝壁傾角 m = 0.500\n- 土方傾角 i = 15.00°\n- 安息角 ψ = 30.00°\n- 有效厚度 d = 0.200 m\n- 土重 γ = 18.0 kN/m³\n\n計算公式：\n1. 土壓力係數 Ka = cos²(ψ+m) / [cos²m·(1+√Q)²]\n 其中 Q = [sinψ·sin(ψ-i)] / [cos(m+i)·cosm]\n2. 土壓力 P = γ·H²·Ka / (2·cosm)\n3. 彎矩 M = γ·H³·Ka / (6·cosm)\n4. 鋼筋量 As = M / (fs·d) × 10⁶ / 1000\n\n計算結果：\n- 土壓力係數 Ka = 0.3333\n- 土壓力 P = 6.750 kN/m\n- 彎矩 M = 3.375 kN·m/m\n- 鋼筋量 As = 13.780 cm²/m"
}
```
## 鋼筋查詢功能
本工具提供以下鋼筋資料查詢功能：
1. 列出所有可用的鋼筋編號
```python
list_rebar_numbers()
```
2. 查詢特定鋼筋編號的規格資料
```python
get_rebar_specs(rebar_number="#3")
```
3. 計算鋼筋重量
```python
calculate_rebar_weight(rebar_number="#3", length=10.0)
```
可用的鋼筋編號包括：#3、#4、#5、#6、#7、#8、#9、#10、#11，每個編號對應的規格資料包括：
- 直徑（mm）
- 截面積（cm²）
- 單位重量（kg/m）
- 周長（mm）
### 鋼筋規格查詢
輸入「鋼筋規格 #3」或「鋼筋資料 #3」可查詢特定鋼筋的詳細資料，包括：
- 鋼筋編號
- 直徑 (mm)
- 截面積 (cm²)
- 單位重量 (kg/m)
- 周長 (mm)
### 鋼筋重量計算
輸入「鋼筋重量 長度 6 #3」可計算指定長度的鋼筋重量，例如：
- 長度：6m
- 鋼筋：#3
- 重量：2.04 kg
### 鋼筋截面積查詢
輸入「鋼筋截面積 #3」可查詢特定鋼筋的截面積，例如：
- #3 鋼筋截面積：0.71 cm²
### 所有鋼筋列表
輸入「所有鋼筋」可列出所有可用的鋼筋編號，包括：
- #3 至 #11 鋼筋
- 各鋼筋的基本規格
### U 型溝配筋建議
輸入「U型溝配筋 面積 10cm2」可查詢建議的配筋方式，系統會：
1. 根據輸入的鋼筋斷面積 (cm²/m)
2. 自動計算並建議主筋與副筋的配筋方式
3. 間距會取整到最接近的 5cm
4. 提供完整的配筋建議報告
### 逕流係數查詢
逕流係數查詢工具可依據水土保持技術規範第18條，查詢不同土地利用類型或集水區狀況的逕流係數C值。
#### 範例
```
輸入：請查詢農業區的逕流係數
回傳：逕流係數 C = 0.53
來源：農業區逕流係數範圍：0.45~0.60，採用平均值0.53
依據：水土保持技術規範第18條及附件逕流係數表
說明：逕流係數C值反映集水區地表特性對降雨逕流之影響，開發中狀態C值以1.0計算。
輸入：開發中的平坦耕地逕流係數是多少？
回傳：逕流係數 C = 0.85
來源：開發中狀態，平坦耕地
依據：水土保持技術規範第18條及附件逕流係數表
說明：逕流係數C值反映集水區地表特性對降雨逕流之影響，開發中狀態C值較高。
```
查詢結果包含：
- 逕流係數值
- 來源說明
- 規範依據
- 土地利用類型
- 開發狀態
- 數值範圍（如適用）
### USLE 因子查詢工具
USLE 因子查詢工具可依據水土保持技術規範第35條，查詢土壤流失量計算所需的各項因子值。
#### 降雨沖蝕指數 R 值查詢
```
輸入：請查詢台北市的降雨沖蝕指數R值
回傳：地區 台北市 的降雨沖蝕指數 R = 350，單位：百萬焦耳·公釐/公頃·小時·年
輸入：年平均降雨量2000mm的降雨沖蝕指數R值是多少？
回傳：年平均降雨量 2000 mm 推估的降雨沖蝕指數 R = 600，單位：百萬焦耳·公釐/公頃·小時·年
```
#### 土壤沖蝕指數 K 值查詢
```
輸入：砂土的沖蝕指數K值是多少？
回傳：土壤類型 砂土 的沖蝕指數 K = 0.30，單位：公噸·公頃·年/公頃·百萬焦耳·公釐
輸入：請查詢黏土的K值
回傳：土壤類型 黏土 的沖蝕指數 K = 0.20，單位：公噸·公頃·年/公頃·百萬焦耳·公釐
```
#### 覆蓋與管理因子 C 值查詢
```
輸入：草地的覆蓋與管理因子C值是多少？
回傳：土地利用類型 草地 的覆蓋與管理因子 C = 0.05，單位：無因次
輸入：請查詢農地的C值
回傳：土地利用類型 農地 的覆蓋與管理因子 C = 0.30，單位：無因次
```
#### 水土保持處理因子 P 值查詢
```
輸入：等高耕作的水土保持處理因子P值是多少？
回傳：水土保持措施 等高耕作 的處理因子 P = 0.50，單位：無因次
輸入：請查詢梯田的P值
回傳：水土保持措施 梯田 的處理因子 P = 0.20，單位：無因次
```
查詢結果包含：
- 因子值
- 單位
- 來源說明
- 規範依據
## 使用範例(功能導向，使用自然語言對話，讓大模型自動調用相關工具來求解)
- 有一集水區面積約5ha，平坦耕地，新北市，重現期50年，降雨延時60min，調用工具取得該地區的降雨強度值，計算該集水區最大逕流量?
- 有一集水區面積約5ha，平坦耕地，新北市，降雨延時60min，調用工具取得該地區的降雨強度值，請分別計算重現期25年、50年該集水區最大逕流量? 並輸出完整計算式的報告書。
- 依據25年的逕流量，設計一條寬50cm，深70cm的混凝土溝，設計坡度容許範圍?
- 依據這個逕流量，設計一條寬50cm，溝深60cm的混凝土溝，坡度2.5%，檢核該設計是否OK，並出具一份完整的檢核報告書。
- 水溝編號,B(cm),H(cm),坡度(%),流量(CMS),水溝鋪面型式
1-1,40,60,1.5,0.25,鋼筋混凝土矩形溝
1-2,40,70,1.5,0.30,鋼筋混凝土矩形溝
檢核上列水溝設計，以markdown表格型式輸出結果。
- 有一個破碎岩盤的坡面，角度約60度，位於熱帶多雨地區，請提出坡面保護建議。
- 無基礎的混凝土重力式擋土牆，全高2.3M，牆頂寬50cm，牆底寬100cm，土壤單位重18kN/m3，摩擦角30度，凝聚力10kPa，地下水位在牆頂以下2M，地震係數0.15，土層基礎，請調用MCP工具，檢核其常時與地震情況下的穩定性，並輸出完整計算報告書。
- 混凝土溝，height=1.5, wall_slope=0.5, soil_slope=15, soil_angle=30, effective_depth=0.2，調用工具，計算水溝所需的鋼筋量及建議配筋?
- 台中的 "年平均土壤流失量"如何估算? 需提供哪些參數?
- 請計算一條直徑60公分的混凝土圓形管渠，流量0.5cms，坡度1.2%，曼寧係數0.013的流速和流深
- 計算寬30公分，高50cm的鋼筋混凝土矩形溝，流量0.5cms，坡度1.2%，流速和流深?
- 計算寬50公分，高70cm的鋼筋混凝土矩形溝，流量1cms，坡度5%，流速和流深? 輸出完整報告，含計算過程及計算式。
- 計算底寬50公分，頂寬100cm，高70cm的"平常砂土梯形溝"，流量0.2cms，坡度0.7%，流速和流深? 輸出完整報告，含計算過程及計算式。
- 有一集水區面積約5ha，平坦耕地，新北市，重現期50年，降雨延時60min，調用工具取得該地區的降雨強度值，計算該集水區最大逕流量?
- 依據這個逕流量，設計一條寬50cm，溝深60cm的混凝土溝，坡度2.5%，檢核該設計是否OK，並出具一份完整的檢核報告書(含集水區最大逕流量)。
- 使用 Gemini 2.5 Pro 的輸出結果如下:調用工具：query_idf_curve(降雨強度-歷時-頻率（IDF）曲線查詢)、query_runoff_coeff(逕流係數C值查詢工具)、calc_catchment_runoff(集水區最大逕流量計算)、get_manning_n(常見材料的曼寧係數查詢)、calc_channel_section_flow(排水斷面流速/流深/流量計算)
# 混凝土溝設計檢核報告書
## 1. 設計目標
本報告旨在檢核所設計之混凝土溝斷面，是否能安全容納上游集水區於特定重現期下所產生之最大逕流量。
## 2. 集水區最大逕流量計算摘要
* **集水區條件:**
* 面積 (A): 5.0 公頃 (ha)
* 土地利用: 平坦耕地
* 地點: 新北市
* **設計條件:**
* 重現期 (T): 50 年
* 降雨延時 (D): 60 分鐘
* **計算參數:**
* 降雨強度 (I): 140.0 mm/hr (依據新北市50年60分鐘IDF曲線)
* 逕流係數 (C): 0.53 (平坦耕地，取規範平均值)
* **計算公式 (合理化公式):** Q = (C × I × A) / 360
* **計算結果 (設計流量 Q_design):**
* Q_design = (0.53 × 140.0 × 5.0) / 360 ≈ **1.03 cms**
## 3. 混凝土溝設計參數
* 斷面型式: 矩形
* 渠道材質: 混凝土
* 曼寧糙度係數 (n): 0.012
* 溝渠寬度 (b): 50 cm (0.5 m)
* 溝渠深度 (H): 60 cm (0.6 m)
* 渠道坡度 (S): 2.5 % (0.025 m/m)
## 4. 水理計算與檢核
使用曼寧公式，針對設計流量 (Q = 1.03 cms) 及上述溝渠參數進行水理計算：
* **計算公式:**
* Q = A × V
* V = (1/n) × R^(2/3) × S^(1/2)
* A = b × y
* P = b + 2y
* R = A / P
* **計算結果:**
* 實際流速 (V): **4.014 m/s**
* 實際水深 (y): **0.513 m (51.3 cm)**
* **檢核項目:**
* **通水能力 (Capacity Check):**
* 計算水深 (y) = 51.3 cm
* 設計溝深 (H) = 60.0 cm
* **出水高 (Freeboard) = H - y = 60.0 - 51.3 = 8.7 cm**
* *評估:* 溝渠斷面可容納設計流量，尚有 8.7 cm 的出水高。一般工程設計建議保留約10-20%溝深或至少10-15cm的出水高作為安全餘裕，此處出水高略顯不足，建議可考慮加大溝深以增加安全係數。
* **流速檢核 (Velocity Check):**
* 計算流速 (V) = 4.014 m/s
* 混凝土容許流速範圍 (V_allowable): 4.57 ~ 6.1 m/s (依據水保技術規範常見值)
* *評估:* 計算流速 4.014 m/s 低於混凝土的容許流速下限 (4.57 m/s)，表示此流速對混凝土渠道本身是安全的，不會造成渠道沖刷。
## 5. 結論與建議
1. **通水能力:** 設計之混凝土溝斷面 (寬50cm, 深60cm) **可以容納** 1.03 cms 的設計流量。
2. **流速:** 計算流速 4.014 m/s 在混凝土的安全容許範圍內。
3. **出水高:** 計算所得的出水高為 8.7 cm，相對偏低。
4. **建議:** 雖然此斷面在計算上可通過設計流量，但考量到實際施工誤差、泥砂淤積、或未來流量增加的可能性，**建議將溝渠深度適度加大 (例如增加至 70 cm 或以上)**，以提供更充足的出水高，增加整體設計的安全性與韌性。
---
## 授權
本專案採用 MIT License 授權，歡迎自由使用與貢獻。