k-skill korea-weather通过 k-skill-proxy 无 Key 查询韩国气象청 단기예보短期预报的完整实现解析【免费下载链接】k-skill한국인을 위한 스킬 모음집 - 에이전트를 한국인으로项目地址: https://gitcode.com/GitHub_Trending/ks/k-skill本篇指南基于 korea-weather 功能文档 展开讲解 k-skill 中korea-weather技能如何通过k-skill-proxy的GET /v1/korea-weather/forecast路由调用韩国气象청KMA短期预报 조회서비스。读完后你将掌握如何无需个人 OpenAPI key 完成格子坐标nx/ny或经纬度lat/lon两种方式的预报查询、各查询参数的默认值与校验规则、proxy 自动选择最新发布时刻baseDate/baseTime的算法以及 lat/lon 到 KMA 5km 等距立体投影格子的转换原理。功能定位客户端不持有 KMA Key 的代理架构korea-weather是 k-skill 中category: weather、locale: ko-KR的天气技能见 skill.json 与 SKILL.md。它的核心设计目标是把气象청 OpenAPI key 收敛到 proxy 服务器一侧调用方skill / Agent / 用户只访问 proxy 的一个 routeGET /v1/korea-weather/forecastupstream 的KMA_OPEN_API_KEY只在 proxy 服务器环境变量中管理server.js 中kmaOpenApiKey: trimOrNull(env.KMA_OPEN_API_KEY)用户无需去 공공데이터포털 申请气象청 API key也无需在客户端配置任何必填环境变量。proxy 的完整路由清单、服务器侧环境变量与部署结构参见 k-skill 프록시 서버 가이드。前提条件与环境变量根据 korea-weather 功能文档 与 instruction.md必填环境变量无。可选环境变量KSKILL_PROXY_BASE_URL—— 仅在使用 self-host 或别家 proxy 时设置留空unset/empty则默认使用 hosted proxyhttps://k-skill-proxy.nomadamas.org工具侧可选jq用于格式化 JSON 响应。前置阅读공통 설정 가이드、보안/시크릿 정책。proxy 服务器侧则需要在环境变量中提供KMA_OPEN_API_KEY以及可选的KSKILL_PROXY_BASE_URL对端配置。若服务器未配置该 keyroute 会返回KMA_OPEN_API_KEY is not configured on the proxy server.的错误见 server.js。输入参数详解/v1/korea-weather/forecast接受两组二选一的定位参数外加一组可选参数。以下是结合 proxy 源码中normalizeKmaForecastQuery函数server.js逐条核对后的完整参数表参数必填默认值说明nx/ny二选一无KMA 5km 格子坐标必须成对出现缺一即400lat/lon二选一无纬度/经度必须成对出现lat也可写作latitudelon也可写作longitude、lng范围校验为 lat ∈ [-90, 90]、lon ∈ [-180, 180]baseDate可选自动格式YYYYMMDD8 位数字与baseTime必须同时提供或同时省略只给一个会报Provide both baseDate and baseTime.baseTime可选自动格式HHMM4 位数字pageNo可选1也接受page_no必须 ≥ 1numOfRows可选1000也接受num_of_rows必须 ≥ 1dataType可选JSON仅允许JSON或XML不区分大小写几个值得注意的校验细节lat/lon与nx/ny不可混用源码中hasGrid与hasLatLon是互斥分支只要有格子坐标就直接采用否则才走经纬度转格子逻辑server.jsbaseDate/baseTime省略时proxy 会调用resolveLatestKmaForecastBase(now)自动推算最新发布时刻下文详述所有入参非法时均返回400 bad_request且不会触碰 upstream即参数错误不消耗气象청配额。基础流程从请求到响应功能文档 中描述的默认流程与 proxy 源码实现一一对应解析 proxy base URLKSKILL_PROXY_BASE_URL存在则用它否则回退到默认 hosted proxyhttps://k-skill-proxy.nomadamas.org查询/v1/korea-weather/forecastroute 处理器位于 server.js先做参数规范化再查本地缓存未命中则注入服务器侧 key 转发到气象청 API自动选择发布时刻baseDate/baseTime省略时由 proxy 按 KST韩国标准时间自动选定最新可用发布时刻摘要核心 category从响应item[]中优先提取TMP、SKY、PTY、POP、PCP、SNO、REH、WSD进行摘要见 instruction.md 的 Workflow 第 3 步。发布时刻baseTime自动选择算法resolveLatestKmaForecastBaseserver.js的实现逻辑是将当前时间换算为 KST取当前分钟数从KMA_FORECAST_BASE_TIMES列表气象청短期预报的标准发布时刻序列从后向前遍历找到第一个满足当前分钟数 ≥ 发布时刻分钟数 KMA_FORECAST_READY_MINUTE的时刻命中则返回当天baseDate 该baseTime全部未命中即一天刚开始、任何发布都还没准备好则回退到前一天最后一个发布时刻。这正对应文档中주의할 점的第一条发布时刻刚过时最新baseTime可能尚未准备就绪proxy 会保守地选择上一个已就绪的发布时刻而不是把请求打到一个必然失败的未来时刻上。经纬度到 KMA 格子的转换官方 API 使用nx/ny格子坐标但 proxy 额外接受lat/lon转换由convertLatLonToKmaGridserver.js完成。该函数实现了与气象청公开的위도/경도 → 5km 격자一致的等距立体投影Polar Stereographic正算公式核心常数如下const RE 6371.00877; // 地球平均半径 (km) const GRID 5.0; // 格子边长 5 km const SLAT1 30.0; // 标准纬圈 1 const SLAT2 60.0; // 标准纬圈 2 const OLON 126.0; // 原点经度 const OLAT 38.0; // 原点纬度 const XO 43; // X 方向原点格子 const YO 136; // Y 方向原点格子计算得到浮点后以Math.floor(value 0.5)四舍五入取整输出nx/ny。这意味着对文档示例lat37.5665/lon126.9780首尔市中心附近的请求proxy 会在内部落格到对应的 5km 格子文档同时给出了nx60/ny127这一格子写法两者描述同一区域。实战示例经纬度方式查询继承自 功能文档 的标准命令BASE${KSKILL_PROXY_BASE_URL:-https://k-skill-proxy.nomadamas.org} curl -fsS --get ${BASE}/v1/korea-weather/forecast \ --data-urlencode lat37.5665 \ --data-urlencode lon126.9780格子坐标 指定发布时刻BASE${KSKILL_PROXY_BASE_URL:-https://k-skill-proxy.nomadamas.org} curl -fsS --get ${BASE}/v1/korea-weather/forecast \ --data-urlencode nx60 \ --data-urlencode ny127 \ --data-urlencode baseDate20260405 \ --data-urlencode baseTime0500注意baseDate20260405、baseTime0500必须成对出现0500是气象청标准发布时刻之一。如果只想查最新一期直接删掉这两个参数即可。响应结构与缓存标记成功时响应是气象청 JSON payload 的包装体。proxy 会向其中注入两个附加字段server.jsqueryproxy 实际采用的规范化参数含自动解析出的baseDate/baseTime、转换后的nx/ny——摘要回复时应引用这里的发布时刻与坐标而不是请求时传的原始值proxy包含name、cache: { hit, ttl_ms }与requested_atISO 时间戳。缓存命中时同样返回但cache.hit为trueserver.js。缓存策略默认 TTL 由KSKILL_PROXY_CACHE_TTL_MS控制缺省 3000005 分钟仅缓存 2xx 的 JSON 响应server.js同时 proxy 还有默认 60 秒窗口、每窗口 60 次的 rate limitKSKILL_PROXY_RATE_LIMIT_WINDOW_MS/KSKILL_PROXY_RATE_LIMIT_MAX。这对高频轮询场景是内置保护。Category 摘要清单短期预报item[]中每个格子包含多个预报要素。instruction.md 要求保守摘要——优先只提取以下 8 项其余 category如PM10、PRS、TMN、TMX等按需补充Category含义单位TMP기온气温℃SKY하늘상태天空状况代码PTY강수형태降水形态代码POP강수확률降水概率%PCP강수량降水量mm/hSNO적설降雪量cmREH습도湿度%WSD풍속风速m/s输出时应同时写明查询时刻与预报发布时刻baseDate/baseTime这是 instruction.md Done when 验收条件之一预报必须标注何时发布否则无法判断数据新鲜度。失败模式与注意事项结合文档주의할 점与 instruction.md 的 Failure modes5km 格子的定位偏差短期预报基于 5km 格子结果可能与行政区域边界不完全一致。回答某区/某站天气时应说明这是所在格子的预报而非精确到点位的观测值发布时刻边界发布时刻刚过时最新baseTime可能尚未就绪proxy 会保守回退到上一个发布时刻见上文自动选择算法显式指定了一个还没发布的baseTime时则由 upstream 报错属于所选发布时刻的预报尚未准备完毕这一失败模式Key 与配额upstream key 未配置、气象청 quota 超限或 upstream 故障都会导致失败客户端永远不应请求、打印或保存 key 明文SKILL.md 的 Hard rules 同样约束 Agent 行为坐标不完整只给nx不给ny或反之、lat/lon不成对均返回400。自我部署self-host要点如果要运行自己的 proxy 而非 hosted 实例在服务器端环境变量设置KMA_OPEN_API_KEY气象청 OpenAPI key客户端侧只设置KSKILL_PROXY_BASE_URL指向自己的地址部署结构、systemd 服务、/health检查项等完整说明见 k-skill 프록시 서버 가이드 与 部署文档按该指南要求self-host 运营者需要验证同一 route 在 local/self-host URL 下行为一致并确认 upstream key 只保留在 proxy 服务器侧。小结korea-weather演示了 k-skill 处理公共数据 API 的典型模式客户端零必填 key、单 route 代理、服务器侧注入认证、自动解析发布时刻、内置缓存与限流。对使用者而言一条curl即可获得带baseDate/baseTime元信息的短期预报对开发者而言normalizeKmaForecastQuery、resolveLatestKmaForecastBase 与 convertLatLonToKmaGrid 三个函数是理解该 route 参数语义与坐标换算的最佳阅读入口。【免费下载链接】k-skill한국인을 위한 스킬 모음집 - 에이전트를 한국인으로项目地址: https://gitcode.com/GitHub_Trending/ks/k-skill创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考