korea-weather

Korea Weather

技能功能

通过 k-skill-proxy 代理查询气象厅短期预报服务，总结韩国天气。
用户无需自行申请个人 OpenAPI 密钥，只需在代理服务器上配置 KMA_OPEN_API_KEY。

使用场景

• "首尔市政府附近现在天气怎么样？"
• "告诉我釜山的天气"
• "我想根据经纬度查看韩国短期预报"

前提条件

• 可选：jq
• 可选：KSKILL_PROXY_BASE_URL（自托管·仅在使用独立代理时设置。留空则使用默认托管地址 https://k-skill-proxy.nomadamas.org。）

所需环境变量

• 无。KSKILL_PROXY_BASE_URL 为可选，留空则使用默认托管地址 https://k-skill-proxy.nomadamas.org。

用户无需直接处理公共数据门户气象厅 API 密钥。/v1/korea-weather/forecast 路由由默认托管代理调用，上游 KMA_OPEN_API_KEY 仅在代理服务器上管理。仅在使用独立代理时才需设置 KSKILL_PROXY_BASE_URL。

输入

• 网格坐标：nx、ny
• 或经纬度：lat、lon
• 可选：baseDate、baseTime

省略 baseDate/baseTime 时，代理会自动选择基于韩国标准时间的最新短期预报发布时间。

工作流程

1. 解析代理基础 URL

如果设置了 KSKILL_PROXY_BASE_URL，则使用该值；否则使用默认托管代理 https://k-skill-proxy.nomadamas.org。

2. 查询短期预报端点

如果已有网格坐标，直接传入；如果只有经纬度，则直接传递给代理。

BASE="${KSKILL_PROXY_BASE_URL:-https://k-skill-proxy.nomadamas.org}"
curl -fsS --get "${BASE}/v1/korea-weather/forecast" \
  --data-urlencode 'lat=37.5665' \
  --data-urlencode 'lon=126.9780'

网格坐标示例：

BASE="${KSKILL_PROXY_BASE_URL:-https://k-skill-proxy.nomadamas.org}"
curl -fsS --get "${BASE}/v1/korea-weather/forecast" \
  --data-urlencode 'nx=60' \
  --data-urlencode 'ny=127' \
  --data-urlencode 'baseDate=20260405' \
  --data-urlencode 'baseTime=0500'

3. 保守总结响应

尽可能优先总结以下项目：

• TMP：气温
• SKY：天空状况
• PTY：降水类型
• POP：降水概率
• PCP：降水量
• SNO：积雪
• REH：湿度
• WSD：风速

响应中还应包含查询时间和 baseDate/baseTime。

完成条件

• 已整理请求位置的短期预报响应
• 已明确查询时间和预报发布时间
• 上游密钥未暴露给客户端

失败模式

• 代理上游密钥未设置或托管/自托管路由故障
• nx/ny 或 lat/lon 不完整
• 气象厅配额超限或上游故障
• 所选发布时间尚无预报准备就绪

备注

• 官方 API 使用 nx/ny 网格，但代理也接受 lat/lon 并在内部转换为网格。
• 短期预报类别主要关注 TMP、SKY、PTY、POP、PCP、SNO、REH、WSD 等。
• 代理操作/环境变量设置请参考 docs/features/k-skill-proxy.md。