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)