Pollen Query Skill - 全国过敏指数实时查询与可视化
概述
本技能提供中国主要城市过敏指数（UPI）的实时查询能力，接入华风爱科官方 API，
并生成基于 ECharts 的交互式热力地图，通过颜色深浅直观展示各地过敏风险等级。
> 核心优势：当日缓存 + 智能限速（≤4次/秒），首次拉取全量数据，后续秒级响应。
使用方式
1. 基础查询
当用户询问花粉/过敏相关问题时，运行以下命令获取数据：
python scripts/fetch_pollen.py --source weathercn --city <城市名>
示例：
- python scripts/fetch_pollen.py --source weathercn --city 北京 — 查询北京过敏指数
- python scripts/fetch_pollen.py --source weathercn --city 上海 — 查询上海过敏指数
- python scripts/fetch_pollen.py --source weathercn — 生成全国过敏指数地图（默认行为）
2. 生成地图可视化
生成带颜色深浅标注的交互式热力地图：
python scripts/fetch_pollen.py --source weathercn -o <输出路径>.html
生成的 HTML 文件为独立文件，可直接在浏览器中打开，包含：
- ECharts 散点地图，渐变色圆形标记反映过敏指数等级
- 鼠标悬停弹窗显示详细信息
- 统计面板：监测城市数、最高指数、平均指数、预警城市数
- 图例面板：5级颜色图例说明（极低→极易发）
- 自适应视野自动适配到所有标记点
- 当日缓存：同一天内再次运行直接使用缓存，<1 秒出结果
3. JSON 数据导出
以结构化格式导出所有城市过敏指数数据：
python scripts/fetch_pollen.py --source weathercn --json
4. 列出支持的城市
python scripts/fetch_pollen.py --list-cities
过敏指数等级标准 (UPI)
| 等级 | 指数值 | 颜色 | 含义 | 建议 |
|---|---|---|---|---|
| 极低 | 1 | 🟢 绿色 | 几乎无影响 | 适宜户外活动 |
| 低 | 2 | 🟢 浅绿 | 影响较小 | 敏感人群注意防护 |
| 中等 | 3 | 🟡 黄色 | 有一定诱发风险 | 减少户外活动 |
| 易发 | 4 | 🟠 橙色 | 较易诱发过敏 | 避免外出 |
| 极易发 | 5 | 🔴 红色 | 极易诱发过敏 | 穿长衣+戴口罩+眼镜 |
输出规范
地图生成后
-
告知用户地图已生成，说明关键统计数据：
- 监测城市数量
- 最高指数城市及数值
- 平均指数
- 预警城市数量（易发/极易发等级）
- 缓存命中情况 -
使用 open_result_view 或 preview_url 展示 HTML 文件
-
提供健康建议根据当前季节和用户所在城市的指数等级给出建议
单城市查询结果格式
以清晰的结构化文本呈现：
📍 [城市名] 过敏指数监测报告
━━━━━━━━━━━━━━━━━━━━━━━━━━━
过敏指数: UPI X / 5
等级: [等级名称]
建议措施: [对应建议]
更新时间: [时间]
━━━━━━━━━━━━━━━━━━━━━━━━━━━
数据来源
- 主要数据源：华风爱科 API (openapi.weathercn.com) — 中国天气网官方 API，过敏指数 ID:127
- 备用数据源：敏舒科技 (allercast.cn) — UPI 花粉浓度数据
- 当网络请求失败时，脚本会自动切换到模拟演示数据
- 支持城市：66 个中国主要城市，含完整坐标数据
注意事项
- 依赖安装：首次使用需确保 Python 环境有
requests（pip install requests） - API Key 配置（华风爱科）：
- 方式一：命令行参数--weathercn-key YOUR_KEY
- 方式二：环境变量WEATHERCN_API_KEY=YOUR_KEY
- 方式三：配置文件.weathercn_key（与脚本同目录） - 频率限制：脚本已内置智能限速（≤4次/秒），避免触发 API 429 错误
- 当日缓存：同一城市当天只请求一次 API，后续复用缓存数据
- 地图交互：生成的 HTML 为纯静态文件，无需后端服务即可正常工作
参考资源
- 详细 API 说明和扩展指南：见
references/api-guide.md - 城市坐标完整列表：已内置于脚本中 (
CITY_COORDS)
