韩国家庭垃圾投放查询技能实战基于 k-skill 的 household-waste-info 与 k-skill-proxy 密钥注入架构解析【免费下载链接】k-skill한국인을 위한 스킬 모음집 - 에이전트를 한국인으로项目地址: https://gitcode.com/GitHub_Trending/ks/k-skill导读household-waste-info是 k-skill 技能仓库中面向韩语用户的生活类utility技能它通过调用韩国行政安全部행정안전부生活垃圾分类投放信息생활쓰레기배출정보公共数据 Open API按**市郡区시군구**查询生活垃圾、食物垃圾与可回收物的投放标准、投放星期与时间信息并以用户友好的摘要形式返回。本篇文章将围绕该技能在仓库中的两个核心文档——SKILL.md 与 instruction.md——完整讲解其使用场景、认证架构、代理路由参数约束、端到端工作流并结合 k-skill-proxy 源码与测试用例深入剖析serviceKey服务端注入、分页参数强校验、内存缓存等底层实现帮助你掌握官方 Open API 代理收口密钥 技能指令这套可复用的开发范式。一、技能概览它能做什么1.1 核心能力根据 instruction.md 的定义本技能调用行政安全部的生活垃圾投放信息 Open API向用户提供按地区划分的三类投放信息**生活垃圾생활쓰레기**的投放标准与星期/时间**食物垃圾음식물쓰레기**的投放标准与星期/时间**可回收物재활용품**的投放标准与星期/时间。几个关键设计决策基本查询单元是市郡区名SGG_NM即以行政区划名称为入口响应需整理为易于理解的摘要而不是把 API 原始负载直接抛给用户Base URL 对齐原始 APIhttps://apis.data.go.kr/1741000/household_waste_infoserviceKeyDATA_GO_KR_API_KEY仅由代理服务器注入与管理用户侧不保存密钥。1.2 典型使用场景文档给出了四类典型用户问法分别覆盖星期时间地点/方法三个维度的查询用户提问示例对应查询意图강남구 쓰레기 배출 요일 알려줘告诉我江南区垃圾投放星期按市郡区查询投放星期우리 동네 음식물쓰레기 언제 버려?我们小区的食物垃圾什么时候扔查询食物垃圾投放时间재활용품 배출 시간 확인해줘帮我确认可回收物投放时间查询可回收物投放时间생활쓰레기 배출 장소/방법 찾아줘帮我找生活垃圾投放地点/方法查询投放地点与投放方法这四类问法共同指向一个事实用户的自然语言中通常只有地区名没有结构化参数因此技能的核心职责是识别地区 → 构造查询 → 摘要结果。1.3 前提条件与运行环境运行该技能需要满足以下环境要求instruction.md互联网连接可执行curl、python3的运行环境可访问原始 API 的环境可访问用于密钥注入的代理proxy的环境。值得强调的是默认路径下用户不需要额外编写客户端 API 层直接通过代理路由即可完成查询详见第三节。二、认证与密钥架构为什么用户端不需要 API 密钥这是本技能最有代表性的架构决策之一值得单独展开。2.1 认证需求instruction.md 明确指出用户侧默认没有任何必需的认证密钥。可选环境变量只有一个KSKILL_PROXY_BASE_URL—— 当使用自托管self-hosted代理时才需要设置未设置时默认走官方托管的k-skill-proxy.nomadamas.org。2.2 密钥管理的三条原则文档以编号形式明确了认证密钥的使用原则端点/参数体系遵循原始 API代理路由对外暴露的参数名与原始 API 保持一致客户端无需学习两套协议serviceKey由代理服务器管理并注入密钥只存在于服务器侧用户本地环境无需放置DATA_GO_KR_API_KEY这既降低了密钥泄露风险也让技能对最终用户几乎零配置。这一设计与 SKILL.md 中的硬性规则绝不在聊天、文件或 shell 参数中询问、打印或存储明文凭据互为印证密钥隔离不是可选项而是技能的安全底线。三、官方 API 面与代理路由设计3.1 官方 API 面项目值Base URLhttps://apis.data.go.kr/1741000/household_waste_info端点EndpointGET /info密钥注入仅由代理k-skill-proxy在服务端注入serviceKey也就是说代理路由实际上对接的上游完整地址是https://apis.data.go.kr/1741000/household_waste_info/info这在 server.js 中可以直接看到const url new URL(https://apis.data.go.kr/1741000/household_waste_info/info);3.2 代理支持的查询参数核心约束instruction.md 对代理路由的参数约束做了非常明确的定义这是整个技能最容易踩坑的部分参数约束说明cond[SGG_NM::LIKE]必填市郡区名包含式搜索pageNo/numOfRows或page_no/num_of_rows必填且值必须是1/100其他值或非整数不只含数字的字符串一律返回400上游不会被调用returnType恒为json代理强制指定客户端即使传值也被忽略serviceKey禁止客户端传递由代理在服务端注入分页参数之所以被锁死在1/100是因为生活垃圾分类投放信息按市郡区粒度查询后单页 100 条足以覆盖绝大多数地区的完整投放规则同时统一固定分页也简化了缓存键的设计见第四节源码分析。3.3 附加过滤器的说明原始 API 还支持cond[DAT_CRTR_YMD::*]数据生成日期、cond[DAT_UPDT_PNT::*]数据更新点等附加过滤条件但当前代理路由并不透传pass-through这些参数。文档给出了务实的原因用户常见提问如강남구 쓰레기 배출 요일仅靠市郡区搜索就足够了如果需要按时间维度排序可以在客户端依据响应中的DAT_UPDT_PNT自行排序。四、端到端工作流instruction.md 将完整流程划分为四个步骤下面逐一展开并结合源码佐证。4.1 第一步先询问地点在没有拿到用户地区信息之前绝不直接发起查询。文档推荐的标准提问语是확인할 지역(시/군/구)을 알려주세요. 예: 강남구, 수원시 영통구请告诉我要查询的地区市/郡/区。例如江南区、水原市灵通区这一步对应了技能的核心查询粒度——市郡区名SGG_NM先确认位置才能构造出合法的cond[SGG_NM::LIKE]参数。4.2 第二步校验输入并解析查询如果市郡区输入为空则再次向用户询问如果输入含糊不清例如只给了首尔这种市域而非市郡区则应以包含上级行政区划的形式向用户重新确认。4.3 第三步通过代理调用密钥在服务端注入代理会在服务端注入serviceKey后再把请求转发给原始 API。文档给出的标准 curl 示例为curl -fsS --get https://k-skill-proxy.nomadamas.org/v1/household-waste/info \ --data-urlencode cond[SGG_NM::LIKE]강남구 \ --data-urlencode pageNo1 \ --data-urlencode numOfRows100使用要点returnType会被代理强制为json所以客户端无需再单独发送该参数如果设置了KSKILL_PROXY_BASE_URL环境变量则以该值替换默认的托管代理地址。同样的调用方式在 k-skill-proxy/README.md 中也有对应示例使用${LOCAL_PROXY_BASE_URL}指向自托管实例证明这是代理的通用调用约定。4.4 第四步为用户生成摘要从响应中抽取必要字段用简洁、口语化的方式整理给用户。文档指定的摘要字段见下表类别响应字段管理区域 / 目标区域MNG_ZONE_NM、MNG_ZONE_TRGT_RGN_NM投放地点 / 投放方法EMSN_PLC、LF_WST_EMSN_MTHD、FOD_WST_EMSN_MTHD、RCYCL_EMSN_MTHD投放星期 / 时间LF_WST_EMSN_DOW、FOD_WST_EMSN_DOW、RCYCL_EMSN_DOW以及各类别的开始/结束时间不收运日UNCLLT_DAY咨询处MNG_DEPT_NM、MNG_DEPT_TELNO在测试用例 server.test.js 中可以验证这些字段的真实形态例如LF_WST_EMSN_DOW: 월,수,금周一、周三、周五与LF_WST_EMSN_BGNG_TM: 18:00、LF_WST_EMSN_END_TM: 23:00开始/结束时间。字段以全大写韩文缩写命名是行政安全部公共数据 API 的原始风格。五、源码级实现路由、密钥注入、缓存与错误处理本节基于 k-skill-proxy 源码 还原household-waste-info在代理侧的真实实现帮助你理解指令文档约束背后的代码逻辑。5.1 路由注册与参数校验代理在server.js中注册了GET /v1/household-waste/info路由server.js处理顺序如下读取查询参数中的cond[SGG_NM::LIKE]若缺失或为空 → 返回400错误码为bad_request消息为cond[SGG_NM::LIKE] is required调用validateHouseholdWastePaginationQuery(query)校验分页参数server.js该校验器的规则与指令文档完全一致同时接受pageNo/numOfRows与page_no/num_of_rows两种命名两者都必填缺任一即400值必须通过^\d$纯数字正则非数字字符串如abc直接400值必须严格等于pageNo1、numOfRows100否则400。从代码结构可以推断该校验是先于上游请求执行的因此一旦参数非法代理会直接拒绝而不会把非法请求转发给 data.go.kr。5.2 serviceKey 注入与上游请求构造校验通过后代理固定使用pageNo 1、numOfRows 100并构造上游请求server.jsconst url new URL(https://apis.data.go.kr/1741000/household_waste_info/info); url.searchParams.set(serviceKey, config.molitApiKey); url.searchParams.set(pageNo, pageNo); url.searchParams.set(numOfRows, numOfRows); url.searchParams.set(returnType, json); url.searchParams.set(cond[SGG_NM::LIKE], sggNm.trim());几个值得注意的实现细节serviceKey来自config.molitApiKey而该配置项由环境变量DATA_GO_KR_API_KEY解析而来server.js即指令文档所说密钥由代理服务器管理returnType被硬编码为json印证了客户端传值也会被忽略的约束cond[SGG_NM::LIKE]会先trim()再传入避免首尾空格导致匹配失败。5.3 密钥未配置时的行为如果代理服务器没有配置DATA_GO_KR_API_KEY路由会返回503错误码为upstream_not_configured消息为DATA_GO_KR_API_KEY is not configured on the proxy server.server.js。这属于指令文档失败模式中提到的第一种情况——密钥缺失/失效时的服务端表现。5.4 内存缓存路由使用makeCacheKey({ route: household-waste-info, sggNm: sggNm.trim() })作为缓存键server.js。命中缓存时响应中的proxy.cache.hit为true并附上ttl_ms未命中时代理会发起上游请求并把结果连同query、proxy元信息写入缓存。这意味着同一市郡区的重复查询会被代理层去重从而降低对公共数据 API 的调用压力。5.5 上游异常映射上游返回非 2xx → 代理返回502错误码upstream_error附带上游状态码上游网络请求抛错 → 代理返回502错误码upstream_fetch_failed。这两类错误对应指令文档失败模式中的公共数据 API 临时故障/流量限制。此外k-skill-proxy/README.md 还提醒了一个常见坑DATA_GO_KR_API_KEY需要在公共数据门户对相应服务单独申请使用申请활용신청并获批后才能生效未激活时上游会返回 401/403 或 data.go.kr 的认证错误 XML代理会将其转换为 upstream error。六、测试用例验证k-skill-proxy 的测试套件 为household-waste/info路由覆盖了五类关键场景是对指令文档约束的直接可执行验证缺cond[SGG_NM::LIKE]→400/bad_requestserver.test.js未配置DATA_GO_KR_API_KEY→503/upstream_not_configuredserver.test.js缺少分页参数 →400server.test.js非法分页值pageNo99numOfRows5、pageNoabc→400且不调用上游server.test.js正常请求 → 注入serviceKey、强制returnTypejson、写入缓存server.test.js通过 mockglobal.fetch捕获上游 URL断言其 origin pathname 正是https://apis.data.go.kr/1741000/household_waste_info/info断言响应中的proxy.cache.hit首次为false第二次请求命中缓存断言回显的query.sgg_nm、query.page_no、query.num_of_rows与请求一致还有用例验证客户端即使传returnTypexml也会被忽略server.test.js。这些测试从行为层面确认了参数的强校验、密钥的服务端注入、返回类型的强制、以及缓存机制全部是代理路由的硬性实现而非文档建议。七、失败模式排查清单结合 instruction.md 的失败模式与上文源码分析整理一份排查清单现象根因排查/处置返回503 upstream_not_configured代理服务器未配置DATA_GO_KR_API_KEY或密钥已过期serviceKey注入失败在代理侧配置/更新密钥server.js查询结果为空搜索的地区名与 API 数据不一致如行政区划变更、名称不匹配改用更接近官方区划名称的输入或使用上级区划重新确认上游报错 / 响应异常公共数据 API 临时故障或流量限制等待后重试检查DATA_GO_KR_API_KEY是否已在 data.go.kr 对该服务单独申请激活返回400 bad_request缺少cond[SGG_NM::LIKE]或未传分页参数补齐参数server.js返回400分页规则pageNo/numOfRows不是1/100或为abc等非纯数字字符串严格使用1/100代理会直接拒绝上游不会被调用server.js八、完成条件Done wheninstruction.md 定义了一次成功技能执行的判定标准可作为 Agent 自查清单已确认用户所在地区市郡区已成功调用代理的/v1/household-waste/info路由已把投放星期/时间/地点整理为36 个核心要点摘要提供给用户。九、注意事项与最佳实践最后是文档反复强调的几条注意事项也是将该技能投入实际使用的纪律要求密钥零落地用户侧不保存DATA_GO_KR_API_KEY密钥只在代理服务器端管理摘要而非透传不要把 API 原始负载直接展示给用户必须整理成用户友好的摘要多结果排序当响应包含多条记录时优先按最新的DAT_UPDT_PNT数据更新点排序展示保证信息时效官方数据源本技能的数据来源为韩国公共数据门户공공데이터포털的官方数据集查询结果具有官方依据。此外SKILL.md 还定义了技能运行时的三条硬性规则即使不通过 CLI 也适用未经用户明确事先同意绝不执行支付、消息/邮件发送、最终提交、取消或公开发布等操作绝不在聊天、文件或 shell 参数中询问、打印或存储明文凭据绝不绕过法律、到场核验、验证码、身份核验或电子签名等边界。这些规则与本文的密钥代理架构共同构成了该技能安全运行的前提。如需在运行时获取最新指令可通过技能 CLI 拉取npx -y nomadamas/k-skill0 instruct household-waste-info npx -y nomadamas/k-skill0 files household-waste-info该技能的类型定义为utility、语言区域为ko-KR、采用 MIT 许可证相关元数据可在 skill.json 中查看。完整的指令文档与技能说明分别保存在 instruction.md 与 SKILL.md代理路由实现与测试用例则分别位于 server.js 和 server.test.js。【免费下载链接】k-skill한국인을 위한 스킬 모음집 - 에이전트를 한국인으로项目地址: https://gitcode.com/GitHub_Trending/ks/k-skill创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考