k-skill 的 fine-dust-location 技能基于 k-skill-proxy 的韩国区域级 PM10/PM2.5 空气质量查询实战指南【免费下载链接】k-skill한국인을 위한 스킬 모음집 - 에이전트를 한국인으로项目地址: https://gitcode.com/GitHub_Trending/ks/k-skill本篇技术指南聚焦 k-skill 仓库中的fine-dust-location技能指令文档讲解如何以「区域名 / 行政区域提示」或精确测量站名通过k-skill-proxy的report聚合端点获取韩国空气质量的 PM10、PM2.5 与综合大气等级摘要。读完本文你将掌握该技能从输入约定、代理请求、歧义重查到直连 fallback 的完整调用链并理解其底层源码实现与测试验证方式。技能定位与适用场景fine-dust-location是一个面向韩语场景的「按位置查空气质量」技能其元数据skill.json标注为category: utility、locale: ko-KRprofiles 为proxy与lookup即默认走代理、支持查询型交互。它不直接请求韩国环境公团AirKorea的原始接口而是统一收敛到 k-skill-proxy 的聚合端点GET https://k-skill-proxy.nomadamas.org/v1/fine-dust/report典型的用户触发场景包括“지금 내 위치 미세먼지 어때?”现在我这边的微尘怎么样“강남 쪽 초미세먼지 수치 알려줘”告诉我江南方向的超微尘数值“여기 공기질 괜찮아?”这里的空气质还行吗该技能的能力边界非常清晰见 功能文档用区域名 / 行政区域提示找到测量站候选无法确认单一测量站时返回候选列表用精确测量站名重新查询汇总 PM10、PM2.5、等级与查询时间。输入约定区域命名规范指令文档明确要求优先使用接近测量站名的韩语行政区域名称类型示例推荐好강남구、서울 강남구、종로구、수원시不推荐模糊강남、서울 남쪽、코엑스 근처当输入包含多个 token 时helper 与 proxy 通常会优先取最具体的 token。例如서울 강남구会被解析为강남구而非서울。这一行为在源码中有明确印证。Python helper 的pick_stationfine-dust-location/scripts/fine_dust.py#L209-L226将 region hint 按空白切分为 token 后按长度降序排序sorted(..., keylen, reverseTrue)即更长的 token更具体的行政区域优先参与测量站名与地址的包含匹配代理端 JS 实现packages/k-skill-proxy/src/airkorea.js#L59-L73也采用完全相同的“最长 token 优先”策略。仓库测试同样固化了该行为test_pick_station_prefers_specific_region_token_over_generic_city_token断言region_hint서울 강남구时选中강남구scripts/test_fine_dust.py#L36-L44。默认路径一个 HTTP 请求直取 report指令文档强调无需额外 client API 层直接向代理服务器发 HTTP 请求即可。最基本的调用curl -fsS --get https://k-skill-proxy.nomadamas.org/v1/fine-dust/report \ --data-urlencode regionHint서울 강남구脚本 helper 同样以该 report 端点为默认路径。通过 k-skill CLI 执行仓库内的 helperfine-dust-location/scripts/fine_dust.pynpx -y nomadamas/k-skill0 exec fine-dust-location scripts/fine_dust.py -- report --region-hint 서울 강남구 --jsonhelper 的report子命令参数如下见 fine_dust.py#L39-L53参数类型含义--lat/--lonfloatWGS84 经纬度走坐标就近匹配--region-hintstr区域 / 行政区域自然语言提示--station-namestr显式测量站名--station-filestr离线测量站 JSON fixture--measurement-filestr离线测量值 JSON fixture--jsonbool以 JSON 输出而非文本代理路径下 helper 会把lat/lon/regionHint/stationName原样透传给/v1/fine-dust/reportfetch_proxy_report然后按--json选择输出格式未传--json时则输出紧凑文本。歧义位置返回候选测量站并二次重查当输入的regionHint无法被确定到唯一测量站时proxy 会返回ambiguous_location错误并携带候选测量站列表。指令文档给出的示例是광주 광산구光州广域市光山区区域内存在多个测量站curl -fsS --get https://k-skill-proxy.nomadamas.org/v1/fine-dust/report \ --data-urlencode regionHint광주 광산구此时应从响应的candidate_stations中挑选一个再以精确stationName重新查询curl -fsS --get https://k-skill-proxy.nomadamas.org/v1/fine-dust/report \ --data-urlencode stationName우산동(광주)helper 对ambiguous_location也有专门处理解析出candidate_stations后会以可读文本列出候选并提示“请以--station-name重新查询”read_json_response。代理端行为被端到端测试覆盖test(fine dust endpoint returns candidate stations when region resolution is ambiguous)packages/k-skill-proxy/test/server.test.js#L3033-L3058。代理端的完整解析流程功能文档若配置了KSKILL_PROXY_BASE_URL先调用 k-skill-proxy 的/v1/fine-dust/reportregionHint到达后proxy 先提取市/道名通过getCtprvnRltmMesureDnsty获取该市/道的测量站列表若 region token 与站内实际测量站名唯一对应则以该站调用getMsrstnAcctoRltmMesureDnsty取实时数据无法唯一确认时返回ambiguous_locationcandidate_stations客户端/用户从候选中选精确站名再次调用/v1/fine-dust/report?stationName...最终汇总 PM10、PM2.5、等级与查询时间。响应内容与“紧凑回答”规范指令文档要求回答保持紧凑优先整理以下字段测量站측정소查询时间조회 시각PM10 数值与等级PM2.5 数值与等级综合大气等级통합대기등급查询方式fallbackbuild_report生成的 JSON 结构fine_dust.py#L309-L337与之一一对应{ station_name: 중구, station_address: 서울 중구 서소문로 124, lookup_mode: coordinates, measured_at: 2026-03-27 21:00, pm10: { value: 42, grade: 보통 }, pm25: { value: 19, grade: 보통 }, khai_grade: 보통 }文本渲染render_text则输出측정소 / 주소 / 조회 시각 / 조회 방식 / PM10 / PM2.5 / 통합대기등급七行。等级映射遵循 AirKorea 的四级体系GRADE_LABELSfine_dust.py#L31-L36原始等级中文含义1好좋음2普通보통3差나쁨4非常差매우나쁨值得注意的健壮性逻辑当 API 返回的khaiGrade为空时build_report会把综合大气等级显示为정보없음信息缺失而非臆造数值见 fine_dust.py#L330-L336 与对应测试test_build_report_marks_khai_grade_unknown_when_api_omits_itscripts/test_fine_dust.py#L72-L89。此外grade_to_label在等级字段缺失时会根据 PM 数值阈值进行兜底判定PM10 按 30/80/150좋음/보통/나쁨PM2.5 按 15/35/75fine_dust.py#L276-L284。环境变量与密钥解析顺序客户端技能侧所需环境变量变量说明KSKILL_PROXY_BASE_URL仅在需要覆盖默认代理时设置默认值为https://k-skill-proxy.nomadamas.org设为off/false/disable等值可关闭代理走直连get_proxy_base_urlAIR_KOREA_OPEN_API_KEY仅在不使用代理、走 direct fallback 直连 AirKorea 时必需密钥的解析顺序安全与密钥策略 功能文档已存在于环境变量中则直接使用若 Agent 使用自身 secret vault1Password CLI、Bitwarden CLI、macOS Keychain 等可取出后注入环境变量兜底读取~/.config/k-skill/secrets.env纯 dotenv 文件权限0600若均缺失则询问用户并写入第 2 或第 3 项。helper 在密钥缺失或值为占位符replace-me时会以韩文提示需要AIR_KOREA_OPEN_API_KEYget_required_secret。需要说明的是托管hosted模式下 upstream 的 AirKorea key 只部署在 proxy 服务器上不会分发给客户端k-skill-proxy 指南。代理不可用时的 fallback直连 AirKorea指令文档将「测量站名与区域名不一致、需要直接 fallback」列为一种失败模式并指向 docs/features/fine-dust-location.md 与 docs/features/k-skill-proxy.md 获取 passthrough 与直连细节。直连 fallback 的完整流程源码层面fetch_station_lookupfine_dust.py#L421-L460有经纬度时先将 WGS84 坐标转为 AirKorea TM 坐标系Bessel 椭球 横轴墨卡托投影wgs84_to_air_korea_tmfine_dust.py#L129-L168再调getNearbyMsrstnList找附近站附近站为空或仅有 region hint / station name 时调getMsrstnList按addr/stationName过滤走fallback模式若测量站列表仍为空但有精确stationName则直接构造{stationName: ..., addr: None}占位resolve_stationfetch_measurement_payloadfine_dust.py#L468-L484以该站名调getMsrstnAcctoRltmMesureDnstydataTermDAILY、ver1.4取实时测量值build_report汇总。坐标转换的正确性有单元测试守护test_wgs84_coordinates_are_converted_to_air_korea_tm断言首尔市厅坐标(37.5665, 126.9780)转换为(198245.053, 451586.838)scripts/test_fine_dust.py#L19-L23并验证其被原样传给/getNearbyMsrstnListscripts/test_fine_dust.py#L114-L137。test_live_station_lookup_falls_back_to_region_search_after_empty_nearby_result则验证了“坐标查找失败 → 区域搜索兜底”的完整链路scripts/test_fine_dust.py#L139-L161。直连 AirKorea 的 curl 示例密钥由AIR_KOREA_OPEN_API_KEY环境变量提供# 测量站列表按地址过滤 curl -sG http://apis.data.go.kr/B552584/MsrstnInfoInqireSvc/getMsrstnList \ --data-urlencode serviceKey${AIR_KOREA_OPEN_API_KEY} \ --data-urlencode returnTypejson \ --data-urlencode numOfRows50 \ --data-urlencode pageNo1 \ --data-urlencode addr서울 강남구 # 指定测量站的实时测量值 curl -sG http://apis.data.go.kr/B552584/ArpltnInforInqireSvc/getMsrstnAcctoRltmMesureDnsty \ --data-urlencode serviceKey${AIR_KOREA_OPEN_API_KEY} \ --data-urlencode returnTypejson \ --data-urlencode numOfRows100 \ --data-urlencode pageNo1 \ --data-urlencode stationName중구 \ --data-urlencode dataTermDAILY \ --data-urlencode ver1.4helper 还支持完全离线的 fixture 验证功能文档npx -y nomadamas/k-skill0 exec fine-dust-location scripts/fine_dust.py -- report \ --station-file scripts/fixtures/fine-dust-stations.json \ --measurement-file scripts/fixtures/fine-dust-measurements.json \ --region-hint 서울 강남구仓库提供了对应的样例数据 fine-dust-stations.json含중구/종로구/강남구三站及其dmX/dmY坐标与 fine-dust-measurements.json含 PM10/PM2.5 数值、等级与dataTimetest_cli_report_supports_fixture_inputs用它们断言了 CLI 输出scripts/test_fine_dust.py#L91-L112。passthrough保留原始 AirKorea 接口形态若想沿用 AirKorea 原始接口形态/B552584/...路径proxy 也提供 passthrough 端点——不需要额外 client APIserviceKey完全由服务器注入。指令文档与 k-skill-proxy 指南 给出的白名单仅包含两个 AirKorea 操作getMsrstnAcctoRltmMesureDnsty与getCtprvnRltmMesureDnstypackages/k-skill-proxy/src/server.js#L140isAllowedAirKoreaRoute校验见 server.js#L1501。示例curl -fsS --get https://k-skill-proxy.nomadamas.org/B552584/ArpltnInforInqireSvc/getMsrstnAcctoRltmMesureDnsty \ --data-urlencode returnTypejson \ --data-urlencode numOfRows1 \ --data-urlencode pageNo1 \ --data-urlencode stationName강남구 \ --data-urlencode dataTermDAILY \ --data-urlencode ver1.4失败模式与注意事项指令文档明确的失败模式有三类regionHint过于宽泛无法确定单一测量站代理服务器宕机或 upstream key 未配置测量站名与区域名不一致需要直接 fallback。对应的错误处理在源码中均有落地代理 503 upstream_not_configuredread_json_response会输出韩文提示“k-skill-proxy 未配置 API key请联系管理员”fine_dust.py#L375-L376代理端在未配置AIR_KOREA_OPEN_API_KEY时返回503server.js#L2466-L2479网络不可达URLError被转换为“代理服务器无响应请稍后重试或联系管理员”的提示fine_dust.py#L391-L392测量站列表 API 返回 403可通过getCtprvnRltmMesureDnsty与按站实测 API 的组合绕过功能文档。实操注意事项实时数据必须附带查询时间当 PM10/PM2.5 值为-或异常时需要一并复核等级API 未返回khaiGrade时综合大气等级显示为정보없음regionHint是自然语言无法命中单一测量站是常见情况应走候选重查流程。代理端实现与调用链小结/v1/fine-dust/report在 proxy 中的完整调用链为路由处理器server.js#L2435→ 参数规范化normalizeFineDustQuery→ 缓存查询fine-dust-report路由级缓存命中时返回proxy.cache.hittrue→ 调用fetchFineDustReportpackages/k-skill-proxy/src/airkorea.js→ 由代理注入AIR_KOREA_OPEN_API_KEY调 upstream。直连 fallback 时Python helper 复刻了同一套“最长 token 优先”的站名匹配算法因此两条路径的选站行为保持一致。综上所述fine-dust-location呈现了 k-skill 生态中「免费公共 API 密钥收口到服务端 客户端零密钥 HTTP 请求」的标准模式客户端只需掌握regionHint/stationName两种输入与curl/npx两种调用方式即可获得结构化、带查询时间戳的韩国空气质量报告遇到歧义或上游异常时系统提供了候选重查、直连 fallback 与清晰的错误信息三条兜底路径并通过 scripts/test_fine_dust.py 与 packages/k-skill-proxy/test/server.test.js 中的测试固化了核心行为。【免费下载链接】k-skill한국인을 위한 스킬 모음집 - 에이전트를 한국인으로项目地址: https://gitcode.com/GitHub_Trending/ks/k-skill创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考