k-skill 细颗粒物定位查询技能：基于 AirKorea 与 k-skill-proxy 的 PM10/PM2.5 实时报告实战指南

k-skill 细颗粒物定位查询技能基于 AirKorea 与 k-skill-proxy 的 PM10/PM2.5 实时报告实战指南【免费下载链接】k-skill한국인을 위한 스킬 모음집 - 에이전트를 한국인으로项目地址: https://gitcode.com/GitHub_Trending/ks/k-skill导读fine-dust-location是 k-skill 技能集packages/k-skill-cli/skills/fine-dust-location/instruction.md中用于按用户所在位置或区域名称查询韩国实时空气质量的核心技能它默认调用k-skill-proxy的report汇总端点一次请求即可拿到测量站、PM10、PM2.5、综合大气等级与查询时刻的紧凑摘要。读完本文你将掌握该技能的输入约定、默认调用路径、歧义位置的候选测量站回查流程、底层脚本与 AirKorea 直连 fallback 的完整机制以及如何结合源码与测试用例进行验证与排障。一、技能定位做什么、何时使用fine-dust-location以韩国环境公团 AirKorea 实时数据为基础将「自然语言位置描述」解析为「具体测量站」并汇总输出 PM10可吸入颗粒物、PM2.5细颗粒物与综合大气质量等级。技能元数据见 fine-dust-location/skill.json将其归为category: utility、locale: ko-KR、phase: v1的代理技能描述为「基于 AirKorea 按地区名或位置提示查询细颗粒物/超细颗粒物默认路径为 k-skill-proxy 的 report 端点」。官方 instruction 给出的典型触发场景是以下三类韩语自然语言提问지금 내 위치 미세먼지 어때?现在我这边的微尘怎么样강남 쪽 초미세먼지 수치 알려줘告诉我江南那边的超细颗粒物数值여기 공기질 괜찮아?这里的空气质量还好吗技能的输入分两种模式模式输入说明一般查询regionHint地区名/行政区域提示由代理将自然语言位置转化为行政区域提示再查询stationName精确测量站名用于候选列表确定后的精确回查二、区域命名约定贴近测量站名的行政区域名由于 AirKorea 的测量站以「行政区域」为单位命名如강남구、종로구技能要求将自然语言输入规约为最接近测量站名的韩语行政区域名推荐写法강남구、서울 강남구、종로구、수원시应避免的模糊写法강남、서울 남쪽首尔南部、코엑스 근처COEX 附近当输入包含多个 token 时helper 与 proxy 默认优先解析最具体的 token。例如서울 강남구会优先取강남구而不是宽泛的서울。这一行为在源码 fine-dust-location/scripts/fine_dust.py 的pick_station中有对应实现对region_hint按 token 长度降序排序keylen, reverseTrue优先用更长、更具体的 token 去匹配stationName或addr字段。三、默认路径report 汇总端点技能的核心主张是无需任何额外的 client API 层——只需向代理服务器发一个 HTTP 请求即可。默认路径恒为k-skill-proxy.nomadamas.org的/v1/fine-dust/report端点。直接使用 curl 的示例curl -fsS --get https://k-skill-proxy.nomadamas.org/v1/fine-dust/report \ --data-urlencode regionHint서울 강남구脚本 helper 也以同一 report 端点作为默认路径通过 k-skill CLI 的exec子命令运行npx -y nomadamas/k-skill0 exec fine-dust-location scripts/fine_dust.py -- report --region-hint 서울 강남구 --json其中--json让脚本输出结构化 JSON而非默认文本摘要便于代理程序进一步解析。脚本中 report 端点由DEFAULT_PROXY_BASE_URL https://k-skill-proxy.nomadamas.org与路径/v1/fine-dust/report拼接而成见 fine_dust.py 与fetch_proxy_report。3.1 底层六步默认流程结合 docs/features/fine-dust-location.md 与源码report 端点在代理侧的实际处理流程为客户端设置KSKILL_PROXY_BASE_URL若有后优先调用 k-skill-proxy 的/v1/fine-dust/report收到regionHint后proxy 先抽取「市道」名称通过 AirKorea 的getCtprvnRltmMesureDnsty获取该市道的测量站列表若 region token 与市道内实际测量站名唯一对应则以该站调用getMsrstnAcctoRltmMesureDnsty获取实时测量值若无法唯一确定测量站则返回ambiguous_location与candidate_stations候选列表客户端/用户从候选中选出精确测量站名再次调用/v1/fine-dust/report?stationName...最终汇总 PM10、PM2.5、等级、查询时刻/时间形成紧凑摘要。3.2 歧义位置处理候选测量站回查当输入的地区名无法立即确定为单一测量站时例如광주 광산구存在多个同名或重叠的测量站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우산동(광주)脚本侧对同样的歧义场景做了友好化处理在 read_json_response 中当 proxy 返回 HTTP 错误且error ambiguous_location时脚本会提取candidate_stations与sido_name输出形如「候选测量站: ...请用精确测量站名以--station-name再查询」的引导信息并直接退出。四、环境变量与密钥解析顺序在客户端技能侧与代理服务器侧所需的环境变量不同客户端默认使用 hosted proxy通常无需密钥KSKILL_PROXY_BASE_URL仅需在显式覆盖时设置。留空/未设置时使用默认值https://k-skill-proxy.nomadamas.org源码get_proxy_base_url还支持将其设为off/false/0/disable/disabled/none等值来显式禁用 proxy强制走 direct fallback见 fine_dust.py。仅在无 proxy 直连 AirKorea 时需要AIR_KOREA_OPEN_API_KEYAirKorea 开放 API 的serviceKey。脚本中SECRET_NAME AIR_KOREA_OPEN_API_KEY若环境变量为空或等于占位符replace-meget_required_secret会抛出包含指引信息的错误。Credential resolution order密钥解析顺序见 docs/features/fine-dust-location.md若环境变量已存在直接使用若代理正使用自身 secret vault1Password CLI、Bitwarden CLI、macOS Keychain 等从 vault 取出后注入环境变量~/.config/k-skill/secrets.env默认 fallback——普通 dotenv 文件权限要求0600若以上均无则询问用户并保存到 2 或 3 的机制中。更完整的安全规范可参考 docs/security-and-secrets.md 与 docs/setup.md。注意在 hosted 模式下上游 AirKorea key 只存放在 proxy 服务器侧绝不向客户端分发。五、CLI 脚本详解参数与响应fine_dust.py使用argparse定义了唯一子命令report见 fine_dust.py参数类型说明--lat/--lonfloatWGS84 经纬度坐标用于按最近测量站查询--region-hintstr地区/行政区域提示fallback 模式--station-namestr显式指定测量站名--station-filestr离线测量站 JSON fixture测试/离线验证--measurement-filestr离线测量值 JSON fixture--jsonbool输出 JSON 而非文本文本模式的输出格式render_text严格遵循 instruction 的「Keep the answer compact」要求只汇总六项内容측정소: 강남구 주소: 서울 강남구 학동로 426 조회 시각: 2026-03-27 21:00 조회 방식: fallback PM10: 81 (나쁨) PM2.5: 44 (나쁨) 통합대기등급: 나쁨对应 JSON 结构build_report包含station_name、station_address、lookup_modecoordinates或fallback、measured_at、pm10/pm25各自含value与grade、khai_grade等字段。5.1 等级判定规则grade_to_label实现了双重等级判定见 fine_dust.py若 API 返回了标准等级码直接映射1→좋음好、2→보통一般、3→나쁨差、4→매우나쁨很差若等级码缺失或为空则依据实测值按浓度阈值兜底判定污染物阈值与等级PM10≤30 좋음、≤80 보통、≤150 나쁨、150 매우나쁨PM2.5≤15 좋음、≤35 보통、≤75 나쁨、75 매우나쁨若连浓度值都无法解析-或空值等级输出为정보없음信息未知当 API 未返回khaiGrade时综合大气等级固定显示정보없음。5.2 测量站选择算法优先级pick_station的匹配优先级源码可验证见 fine_dust.py为stationName精确匹配 → 包含匹配测量站名或addr地址字段提供经纬度时基于测量站的dmX/dmY计算平方距离选取最近测量站仅有regionHint时按 token 长度降序逐一对stationName、addr做包含匹配全部失败时返回候选列表第一项。5.3 坐标模式的核心WGS84 → AirKorea TM 坐标转换当使用--lat/--lon坐标查询时脚本会先调用 AirKorea 的getNearbyMsrstnList邻近测量站接口而该接口要求传入TMTransverse Mercator坐标。因此脚本实现了完整的地图投影转换链wgs84_to_air_korea_tm先经七参数平移(146.43, -507.89, -681.46)将 WGS84 椭球转到 Bessel 椭球再通过子午弧长级数展开与 8 次迭代反解纬度最终投影到 AirKorea TM 平面坐标。测试用例 scripts/test_fine_dust.py 验证了(37.5665, 126.9780)首尔市中心转换结果为tmX198245.053, tmY451586.838误差 ≤ 0.001。六、passthrough 与 direct fallback不经 report 端点的两条备选路径6.1 AirKorea passthrough 路径若需要几乎原样使用 AirKorea 原生接口可走 proxy 的 passthrough 路由/B552584/:service/:operation由 docs/features/k-skill-proxy.md 记录的允许路由白名单控制。此路径无需额外 client APIserviceKey由 proxy 在服务端注入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.46.2 direct fallback携带自有 key 直连 AirKorea当KSKILL_PROXY_BASE_URL被显式禁用设为off时脚本会直接请求公共数据门户 AirKorea 的两个服务测量站列表查询MsrstnInfoInqireSvc/getMsrstnList按addr过滤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서울 강남구实时测量值查询ArpltnInforInqireSvc/getMsrstnAcctoRltmMesureDnstycurl -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.4脚本的 direct 调用链见fetch_station_lookup/fetch_measurement_payload与此一致坐标模式先调getNearbyMsrstnListtmX/tmY空结果时降级为getMsrstnListaddr/stationName再以解析出的测量站名调用getMsrstnAcctoRltmMesureDnstydataTermDAILY、ver1.4。lookup_mode字段即用于标注本次结果来自coordinates还是fallback路径。6.3 离线 fixture 验证模式无需网络也能验证脚本逻辑——通过--station-file与--measurement-file指向仓库内 fixturenpx -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 서울 강남구fixture 文件 scripts/fixtures/fine-dust-stations.json 与 scripts/fixtures/fine-dust-measurements.json 提供중구、종로구、강남구三个站点的真实结构数据含dmX/dmY坐标、pm10Value、pm10Grade、pm25Value、khaiGrade等可用于离线复现与单测。七、失败模式与异常处理instruction 明确列出的三类失败模式脚本与 proxy 均有对应处理regionHint过宽或无法确定单一测量站proxy 返回ambiguous_locationcandidate_stations脚本据此输出候选列表引导用户用--station-name再查询proxy 服务器不可用或 upstream key 缺失连接失败URLError脚本输出「设置的 k-skill-proxy 服务器无响应请稍后重试或联系运营者」proxy 返回503且error upstream_not_configured脚本输出「k-skill-proxy 尚未配置所需 API key」测量站名与地区名不一致、需要直接 fallbackdirect 模式在邻近测量站接口返回空列表时自动降级为getMsrstnList区域搜索--station-name在测量站列表为空时也会直接以显式站名发起测量值查询测试test_cli_json_report_uses_station_name_directly_when_station_lookup_is_empty验证了此行为。此外当测量值中 PM10/PM2.5 为-或异常值、或 API 未回填khaiGrade时脚本会给出정보없음并提示复核等级见 docs/features/fine-dust-location.md 的「주의할 점」。八、proxy 架构与部署背景从架构上看client/skill → k-skill-proxy → upstream public API三层结构是理解本技能默认路径的关键详见 docs/features/k-skill-proxy.mdproxy 将AirKorea 等免费/公共 API key 仅保管在服务器端客户端技能只调用 proxy缓存、认证、限流、日志在单点统一控制公开策略为仅接入免费 API默认无需认证的公开 endpoint同时以只读、allowlist 路由、缓存与限流作为防护生产部署运行于 gpu01公开域名为k-skill-proxy.nomadamas.org包含k-skill-proxy.service与k-skill-proxy-tunnel.service两个 systemd 用户服务部署脚本为 scripts/deploy-k-skill-proxy-gpu01.sh运维与回滚细节见 docs/deploy-k-skill-proxy.md。proxy 侧为本技能所需的环境变量即AIR_KOREA_OPEN_API_KEY除 report 端点外还提供/health可查看upstreams配置状态等公开端点。九、测试验证行为即规格仓库中的单元测试 scripts/test_fine_dust.py 将上述行为固化为规格可逐条对照坐标转换wgs84_to_air_korea_tm(37.5665, 126.9780)输出(198245.053, 451586.838)最近站选择以首尔市中心坐标查询时命中중구区域 token 优先级region_hint서울 강남구命中강남구具体 token 优先region_hint강남也命中강남구报告合并fixture 数据下 PM1042보통、PM2.519보통、measured_at2026-03-27 21:00khaiGrade 缺失综合大气等级输出정보없음CLI 端到端report子命令的文本与 JSON 输出、坐标→邻近测量站→fallback 的调用链顺序getNearbyMsrstnList→getMsrstnList→getMsrstnAcctoRltmMesureDnsty、以及「配置 proxy 时优先走 proxy、跳过 direct lookup」的优先级均有对应断言。十、使用注意事项小结默认路径始终是k-skill-proxy.nomadamas.org的 report 端点地区名查询遵循「先取候选、必要时以精确测量站名再查询」的两段式流程passthrough / direct AirKorea 的实现细节不必在技能正文中重复直接参考 docs/features/fine-dust-location.md 与 docs/features/k-skill-proxy.md 两份文档即可regionHint本质是自然语言无法唯一确定测量站的情况很常见应把candidate_stations回查视为正常路径而非异常实时数值务必连同查询时刻一起输出-或异常值需同时复核等级khaiGrade缺失时综合等级显示정보없음hosted 模式下上游 AirKorea key 只部署在 proxy 侧客户端无需也不应持有详见 docs/security-and-secrets.md。【免费下载链接】k-skill한국인을 위한 스킬 모음집 - 에이전트를 한국인으로项目地址: https://gitcode.com/GitHub_Trending/ks/k-skill创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考