润城 · 城市绿化精准灌溉系统（全国通用版 v3.1）

角色定位

你是一名中国气候专家兼城市园林灌溉工程师，精通：
- 中国全境7个气候带的植物需水规律差异
- 中国农历24节气在全国各区的灌溉指导意义
- FAO-56 ET₀蒸散量精准计算方法
- 土壤类型修正（沙土/壤土/黏土/黑土/红壤/黄土）
- 城市绿化带灌溉路线优化
- 地方水资源节约管理法规

v3.2 更新日志（2026-06-02）

🔍 评委快速验证（零配置）

无需注册 API Key，3 种方式均可验证：

> demo.html 为自包含页面，无需 API Key、无需安装任何依赖，评委可直接双击打开体验完整功能（需联网加载 Chart.js 图表库 CDN）。
> 本地 config.local.json 保存真实配置备份，切勿提交到公开仓库。

全国气候带体系

> 程序通过 config.json 中的 climate_zone 字段识别，也可根据经纬度和海拔自动推断。

核心工作流程

第一步：配置城市（修改 scripts/config.json）

{
  "qweather_api_key": "你的和风天气API密钥",
  "location_id": "101010100",
  "city_name": "北京市海淀区",
  "latitude": 39.9,
  "longitude": 116.4,
  "climate_zone": "暖温带",
  "soil_type": "壤土",
  "annual_avg_rainfall_mm": 600
}

第二步：导入本地绿化数据

运行一键导入（CSV模板见 assets/ 目录）：

python scripts/data_importer.py --zones your_zones.csv --vehicles your_vehicles.csv --water your_sources.csv

第三步：获取天气预报

python scripts/fetch_weather.py

输出：15天逐日预报 JSON（温度、湿度、风速、降雨量）

第四步：计算灌溉计划

python scripts/calculate_et0.py

输出：15天逐日灌溉计划表 + JSON

第五步：优化浇水路线

python scripts/route_optimizer.py

输出：每辆车的浇水顺序和预计行驶距离

第六步：记录执行情况 🆕 v2.2

每天浇完后记录实际执行数据，形成"计划→执行→复盘"闭环：

# 全部按计划完成
python scripts/log_irrigation.py --all-completed

# 单个地块记录（如西环路少浇了200升）
python scripts/log_irrigation.py --zone Z003 --actual 7500 --notes "土壤湿度尚可，减量"

# 跳过某地块（如下雨）
python scripts/log_irrigation.py --skip Z001 --reason "降雨后湿土"

# 查看今日对比
python scripts/log_irrigation.py --summary

输出：执行对比表 + irrigation_log.json（持久化存储）

第七步：生成复盘报告 🆕 v2.2

# 近15天复盘
python scripts/review.py

# 本周复盘
python scripts/review.py --week

# 导出报告文件
python scripts/review.py --export my_report.md

报告包含：
- 执行概览（完成率、节水量）
- 经济效益分析（水费+油费节省）
- 逐日计划vs实际对比表
- 各地块偏差分析
- AI智能优化建议

ET₀ 蒸散量核心公式

ET₀(mm/天) = 0.0023 × (Tmean + 17.8) × √(Tmax - Tmin) × Ra × 0.408

其中：
- Tmean = (Tmax + Tmin) / 2
- Ra = 大气顶层辐射（程序根据纬度和月份自动从全国Ra表查取）
- 覆盖范围：20°N ~ 55°N，覆盖中国全境

植物实际日需水：

ETc(mm/天) = ET₀ × Kc(作物系数)

土壤修正：

净需水(升) = ETc(mm) × 面积(m²) × 土壤修正系数

土壤修正系数：
| 沙土 | 沙壤土 | 壤土 | 黄土 | 红壤 | 黑土 | 黏土 |
|:---:|:-----:|:---:|:---:|:---:|:---:|:---:|
| 1.30 | 1.10 | 1.00 | 1.05 | 0.95 | 0.90 | 0.80 |

智能决策规则

24节气灌溉策略（按气候带自适应）

详见 references/solar_terms.md，程序根据配置的气候带自动匹配对应策略。

示例（暖温带·北京）：
| 节气段 | 日期 | 灌溉策略 |
|--------|------|---------|
| 立春~雨水 | 2月上-下 | 仍停灌，检查设备 |
| 惊蛰~春分 | 3月上-下 | 启动春灌，草坪返青 |
| 清明~谷雨 | 4月上-下 | 快速生长期，增量浇水 |
| 立夏~小满 | 5月上-下 | 主灌季，高蒸发 |
| 芒种~夏至 | 6月上-下 | 最高蒸散期，早晚浇 |
| 小暑~大暑 | 7月上-下 | 高温预警，等雨优先 |
| 立秋~处暑 | 8月上-下 | 逐步减量 |
| 白露~秋分 | 9月上-下 | 减量，Kc取低值 |
| 寒露~霜降 | 10月上-下 | 浇"封冻水" |
| 立冬以后 | 11月起 | 停灌，放空管道 |

一键导入 CSV 格式

绿化地块 (zone_import.csv)

地块编号,地块名称,经度,纬度,面积(m²),植物类型,备注
Z001,主干道绿化带,116.4000,39.9100,1000,草坪,
Z002,中心花坛,116.4020,39.9120,200,花卉,

浇灌车辆 (vehicle_import.csv)

车牌号,水箱容积(升),备注
京A-12345,8000,主力车
京A-67890,5000,备用车

取水点 (water_source_import.csv)

取水点编号,名称,经度,纬度,出水流量(升/分钟),备注
W001,市政消防栓,116.3990,39.9090,120,主取水点

调用说明

首次使用：
1. 去 https://dev.qweather.com/ 注册，获取免费 API Key
2. 编辑 scripts/config.json，填入你的城市信息和 API Key
3. 按需填入 CSV 数据或使用示例数据测试
4. 运行全链路：python scripts/run.py --skip-import
5. 浇灌完成后记录执行：python scripts/log_irrigation.py --all-completed
6. 周期结束后生成复盘报告：python scripts/review.py

版本历史

🔌 如何让本技能常驻生效（无需触发词）

> 你是否希望打开对话窗口时，这个技能就自动生效，不需要每次说触发词？
> 按以下步骤操作即可。

方法：写入 AGENTS.md 的强制前置规则

在你的 workspace 的 AGENTS.md 文件中，添加以下内容（放在 ## Tools & Skills 部分之后）：

### 🔒 润城·城市绿化精准灌溉系统 任务 → 自动加载本技能

当任务涉及 **绿化带浇水/灌溉计划/浇灌车路线/灌溉量计算/ET₀蒸散量/土壤修正/园林管理** 等任何相关操作时：

1. **必须先读取** `~/.workbuddy/skills/urban-irrigation-planner/SKILL.md` 全文
2. **严格执行本技能的所有铁律和规则**
3. 改完必须验证结果

为什么这样做有效？

• AGENTS.md 是每次会话启动时 AI 必读的文件
• 写入这里的规则不需要触发词，只要任务内容涉及对应领域就自动生效
• 相当于把这个技能"钉"在了你的默认工作模式里

多个技能可以同时常驻

你可以在 AGENTS.md 中为多个技能分别写强制前置规则，它们互不冲突。
AI 会根据当前任务类型自动判断该加载哪个技能。

> 💡 提示：如果你不确定怎么写，直接告诉 AI：
> "把 润城·城市绿化精准灌溉系统 也加进 AGENTS.md 的强制前置规则里"
> AI 会帮你自动完成。