k-skill 之 national-pension-workplace基于 k-skill-proxy 的国民年金参保事业场查询技能全解析【免费下载链接】k-skill한국인을 위한 스킬 모음집 - 에이전트를 한국인으로项目地址: https://gitcode.com/GitHub_Trending/ks/k-skill本篇技术指南围绕 k-skill 仓库中的national-pension-workplace技能展开讲解它如何经由k-skill-proxy调用公共数据门户data.go.kr的「国民年金公团_国民年金参保事业场明细服务」编号 3046071, V2获取参保事业场候选列表、单一事业场的参保人数与当月告知金额以及按月参保趋势。读完本文你将掌握该技能的 CLI 用法、参数约束、隐私边界、失败模式以及从 Python helper 到 Node.js 代理端的完整源码实现链路。技能定位能查什么、不能查什么该技能通过k-skill-proxy间接调用公共数据门户的国民年金事业场接口核心能力包含三层结果依据 instruction.md参保事业场候选以「事业场名商号 事业者登记号前 6 位」匹配出的事业场列表同一事业场在不同「资料生成年月」dataCrtYm下的重复行会整理为该事业场的最新月份一条。单一事业场详情当候选唯一、事业场被确定时返回参保人数jnngpCnt、当月告知金额crrmmNtcAmt、新增取得/丧失人数。月别参保现状时序按月排列的参保人员增减趋势。需要特别强调的是数据披露边界国民年金数据中的事业者登记号只公开前 6 位后位做掩码处理因此事业场名商号是必填参数当候选不止一个时技能不会武断断言「就是它」而是原样返回候选列表把最终确定交给调用方。同时公开范围以法人及一定规模以上的事业场为主小型/个体事业场可能不在公开之列。设计原则与适用场景该技能的设计遵循两条纪律见 instruction.md 的 Design principles不添加解读标签不生成分数、等级、「风险」等解读性结论只忠实呈现 upstream公共数据门户返回的事实。不武断断言同一性候选有多个时不擅自认定哪一个就是被查询的事业场。典型适用场景包括「○○ 公司员工规模大概多大用国民年金参保人数来评估」「这个事业场当月的国民年金告知金额是多少」「最近人员是增加还是减少按月看一下趋势」从技能元数据看skill.json该技能locale为ko-KRcategory为businessprofiles为proxy与lookup——它属于「经由代理、面向查询」的商务类技能全流程无支付、提交等高风险操作。运行前置条件与凭据要求前置条件可用的互联网连接与python3本技能随附的 helper 脚本 national_pension_workplace.py可访问 hosted 或 self-host 的k-skill-proxy的/v1/national-pension/workplace路由。凭据要求环境变量说明KSKILL_PROXY_BASE_URL仅在自建代理时设置留空时默认使用 hosted 代理https://k-skill-proxy.nomadamas.orgDATA_GO_KR_API_KEY只放在代理运营服务器环境用户侧无需持有需要在公共数据门户完成「国民年金公团_国民年金参保事业场明细」服务的活用申请这一设计的核心在于密钥不下发到用户端公共数据门户的DATA_GO_KR_API_KEY由代理服务端保管用户侧不需要任何必填密钥。参数说明与脚本实现细节CLI 输入参数参数必填说明--name是事业场名商号如삼성전자(주)--b-no否事业者登记号允许连字符仅取前 6 位作为前缀过滤条件helper 脚本的入参校验逻辑在 national_pension_workplace.py 中query_workplace()承担核心校验与请求构造事业场名必填name为空时抛出ValueError提示「请填写事业场名商号国民年金 API 只公开事业者登记号前 6 位因此商号是必填项」登记号规范化先剥离非数字字符re.sub(r\D, , ...)再校验必须为 10 位数字否则报错校验通过后原样传入b_no参数代理地址解析resolve_proxy_base_url()读取KSKILL_PROXY_BASE_URL环境变量——若该值落入off/false/0/disable/disabled/none等禁用集合则报错若为replace-me占位符则回退默认值否则去掉尾部/后使用请求构造以Accept: application/json和User-Agent: k-skill-national-pension-workplace/1.0发起 GET 请求URL 形如{proxyBase}{ROUTE}?{urlencode(params)}其中ROUTE /v1/national-pension/workplace。响应解析与错误映射read_json_response()负责读取结构化 JSON 响应并完成三类错误的状态转换异常情形处理方式上游返回非 JSON / 非对象载荷抛出ApiErrorinvalid JSON / non-object payloadHTTP 503 且 body 中error upstream_not_configured翻译为「k-skill-proxy 未配置所需 API 密钥请联系运营者」HTTPError 且 body 含message字段直接透传该 message网络层URLError提示「所配置的 k-skill-proxy 服务器无响应请稍后重试或联系运营者」并附上具体原因所有错误最终由main()捕获以 JSON 形式输出到 stderr 并返回退出码 1正常时结果以ensure_asciiFalse, indent2的美化 JSON 打印到 stdout返回退出码 0。代理端源码链路从 HTTP 路由到三次上游调用用户侧脚本并不直接接触公共数据门户真正的数据获取发生在k-skill-proxy。整体链路如下路由注册在 server.js 中GET /v1/national-pension/workplace被注册委托给通用的handleKeyedDataGoKrLookup()处理器——该处理器同时服务国民年金、FSC 法人概要、G2B 制裁等「服务端持钥」的 data.go.kr 查询参数规范化normalizeNationalPensionQuery()national-pension.js兼容wkplNm/name/b_nm多种入参别名强制要求事业场名并将b_no规整为 10 位后截取前 6 位作为bnoPrefix缓存检查处理器按route 规范化参数生成缓存键命中则直接返回带cache.hittrue的结果否则进入上游调用TTL 由config.cacheTtlMs控制三次上游编排fetchNationalPensionWorkplace()依序调用同一 upstream 基址https://apis.data.go.kr/B552015/NpsBplcInfoInqireServiceV2下的三个操作getBassInfoSearchV2基础搜索携带wkplNm、6 位bzowrRgstNo前缀、pageNo1、numOfRows100getDetailInfoSearchV2候选唯一时按seq dataCrtYm拉取详情参保人数、告知金额等getPdAcctoSttusInfoSearchV2按seq拉取按月的参保现状时序。每次上游请求都注入serviceKey代理端持有的DATA_GO_KR_API_KEY并设置 20 秒超时AbortSignal.timeout(20000)。XML 响应解析轻量正则解析器公共数据门户返回的是扁平item结构的 XML代理端用正则解析器处理national-pension.js而非引入通用 XML 库若响应含OpenAPI_ServiceResponse说明命中了门户网关层的鉴权/配额错误通过returnReasonCode判断错误类别——代码20/21/30/31/32/33归类为auth-error其余为error若resultCode非00/0归类为error并附上resultMsg正常时以/item...\/item/与/(\w)...\/\1/两级正则抽取出字段对象列表和totalCount。候选去重与选定逻辑fetchNationalPensionWorkplace()在拿到基础搜索结果后还做了三道处理national-pension.js防御性前缀再过滤若提供了bnoPrefix对上游结果按「登记号前 6 位」再过滤一遍「信任上游但自行验证」按月份去重同一事业场会按dataCrtYm资料生成年月重复出现代理端以「wkplNm 道路名详细地址」为键分组每组仅保留最新月份的记录并按年月降序排序候选选定去重后候选数恰为 1 时直接选定否则若名称完全一致trim 后相等的恰好 1 个也选定该条其余情况selected_candidate置为null交由调用方在候选列表中自行确定。选定成功后才发起详情与时序查询。最终响应结构包含query、candidate_count、candidates、raw_row_count、selected_candidate、detail、monthly_status以及一段英文的disclosure_note——重申「登记号仅公开前 6 位无法精确匹配号码名称 前缀匹配到的候选将被列出多个匹配时由调用方判定」这一隐私边界。CLI 使用示例标准用法通过 k-skill CLI 执行 helper 脚本来自 instruction.md 的 CLI examplesnpx -y nomadamas/k-skill0 exec national-pension-workplace scripts/national_pension_workplace.py -- \ --name 삼성전자(주) --b-no 124-81-00998也可以不经过 CLI、直接以python3运行 helper脚本自带 argparse 解析python3 national-pension-workplace/scripts/national_pension_workplace.py \ --name 삼성전자(주) --b-no 124-81-00998脚本还额外暴露了--proxy-base-url参数可在命令行直接覆盖代理地址优先级高于环境变量。若需查看技能在当前运行时下的完整说明或随附文件清单可分别执行见 SKILL.mdnpx -y nomadamas/k-skill0 instruct national-pension-workplace npx -y nomadamas/k-skill0 files national-pension-workplace失败模式与排障对照现象错误码/字段原因与处置未提供事业场名HTTP400error: bad_request参数规范化在代理端即被拦截补上--name即可代理服务器未配置密钥HTTP503error: upstream_not_configured运营端未设置DATA_GO_KR_API_KEY联系代理运营者密钥未被授权该服务HTTP502error: upstream_forbidden代理端密钥未对 data.go.kr 3046071 服务完成活用申请先在公共数据门户申请候选多个正常返回selected_candidate: null属预期行为从candidates列表中选择具体事业场代理无响应网络层错误提示检查网络与KSKILL_PROXY_BASE_URL指向稍后重试代理端错误状态的 HTTP 映射定义在 server.js 的keyedErrorStatus表中upstream_forbidden→ 502、upstream_timeout→ 504、upstream_invalid_response/upstream_error→ 502。同时鉴权失败时密钥绝不会泄露到响应中——测试专门断言了这一点。测试佐证三条关键路径被自动化覆盖k-skill-proxy的测试套件对国民年金路由做了完整覆盖server.test.js可作为理解行为的权威依据规范化测试缺省name抛错{ name: 테스트상사, b_no: 123-45-67890 }被规整为{ wkplNm: 테스트상사, bnoPrefix: 123456 }位数不足123触发 10 位校验错误XML 解析测试伪造OpenAPI_ServiceResponsereturnReasonCode30被识别为auth-error正常 items 被解析为字段对象数组编排端到端测试用 mock fetch 依次应答getBassInfoSearchV2含同一事业场 202604/202605 两个月份 → 验证去重后candidate_count1、raw_row_count2、getDetailInfoSearchV2jnngpCnt120、crrmmNtcAmt5000000、getPdAcctoSttusInfoSearchV2按月列表升序断言三次调用顺序正确、每个请求都携带serviceKeydata-go-key、响应体中不出现密钥明文并验证二次请求命中缓存cache.hittrue错误路径测试未配置密钥时返回 503upstream_not_configured缺少name时返回 400bad_request。合法合规运营基准由于涉及参保信息该技能在 instruction.md 中明确列出三条运营安全准则仅查询公团官方公开的事业场信息参保人数、告知金额是国民年金公团经公共数据门户公开的事业场单位信息不得查询、推定个别劳动者的个人信息明确查询目的仅限交易对手尽调、入职审查、市场调查等正当确认目的的单次查询对特定事业场/行业的批量、定期采集须先确认目的与法律依据依据不明确则不进行最小化结果留存查询结果仅作请求时点参考不得长期保存或再分发。官方数据接口一览项目值公共数据门户数据页https://www.data.go.kr/data/3046071/openapi.do服务编号 3046071Upstream 基址https://apis.data.go.kr/B552015/NpsBplcInfoInqireServiceV2请求参数采用 camelCase代理路由GET /v1/national-pension/workplace小结national-pension-workplace是一个「密钥服务端持有、查询一次完成、结论严守边界」的商务查询类技能用户侧仅需事业场名 可选的前 6 位登记号前缀经由k-skill-proxy完成基础搜索、按月去重、候选选定、详情与月别时序三次上游调用的编排。理解其参数校验、隐私披露边界与失败模式就能在交易对手尽调、入职审查、市场调研等场景中安全、准确地把它接入自己的 Agent 工作流。【免费下载链接】k-skill한국인을 위한 스킬 모음집 - 에이전트를 한국인으로项目地址: https://gitcode.com/GitHub_Trending/ks/k-skill创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 k-skill 之 national-pension-workplace：基于 k-skill-proxy 的国民年金参保事业场查询技能全解析
k-skill 之 national-pension-workplace基于 k-skill-proxy 的国民年金参保事业场查询技能全解析【免费下载链接】k-skill한국인을 위한 스킬 모음집 - 에이전트를 한국인으로项目地址: https://gitcode.com/GitHub_Trending/ks/k-skill本篇技术指南围绕 k-skill 仓库中的national-pension-workplace技能展开讲解它如何经由k-skill-proxy调用公共数据门户data.go.kr的「国民年金公团_国民年金参保事业场明细服务」编号 3046071, V2获取参保事业场候选列表、单一事业场的参保人数与当月告知金额以及按月参保趋势。读完本文你将掌握该技能的 CLI 用法、参数约束、隐私边界、失败模式以及从 Python helper 到 Node.js 代理端的完整源码实现链路。技能定位能查什么、不能查什么该技能通过k-skill-proxy间接调用公共数据门户的国民年金事业场接口核心能力包含三层结果依据 instruction.md参保事业场候选以「事业场名商号 事业者登记号前 6 位」匹配出的事业场列表同一事业场在不同「资料生成年月」dataCrtYm下的重复行会整理为该事业场的最新月份一条。单一事业场详情当候选唯一、事业场被确定时返回参保人数jnngpCnt、当月告知金额crrmmNtcAmt、新增取得/丧失人数。月别参保现状时序按月排列的参保人员增减趋势。需要特别强调的是数据披露边界国民年金数据中的事业者登记号只公开前 6 位后位做掩码处理因此事业场名商号是必填参数当候选不止一个时技能不会武断断言「就是它」而是原样返回候选列表把最终确定交给调用方。同时公开范围以法人及一定规模以上的事业场为主小型/个体事业场可能不在公开之列。设计原则与适用场景该技能的设计遵循两条纪律见 instruction.md 的 Design principles不添加解读标签不生成分数、等级、「风险」等解读性结论只忠实呈现 upstream公共数据门户返回的事实。不武断断言同一性候选有多个时不擅自认定哪一个就是被查询的事业场。典型适用场景包括「○○ 公司员工规模大概多大用国民年金参保人数来评估」「这个事业场当月的国民年金告知金额是多少」「最近人员是增加还是减少按月看一下趋势」从技能元数据看skill.json该技能locale为ko-KRcategory为businessprofiles为proxy与lookup——它属于「经由代理、面向查询」的商务类技能全流程无支付、提交等高风险操作。运行前置条件与凭据要求前置条件可用的互联网连接与python3本技能随附的 helper 脚本 national_pension_workplace.py可访问 hosted 或 self-host 的k-skill-proxy的/v1/national-pension/workplace路由。凭据要求环境变量说明KSKILL_PROXY_BASE_URL仅在自建代理时设置留空时默认使用 hosted 代理https://k-skill-proxy.nomadamas.orgDATA_GO_KR_API_KEY只放在代理运营服务器环境用户侧无需持有需要在公共数据门户完成「国民年金公团_国民年金参保事业场明细」服务的活用申请这一设计的核心在于密钥不下发到用户端公共数据门户的DATA_GO_KR_API_KEY由代理服务端保管用户侧不需要任何必填密钥。参数说明与脚本实现细节CLI 输入参数参数必填说明--name是事业场名商号如삼성전자(주)--b-no否事业者登记号允许连字符仅取前 6 位作为前缀过滤条件helper 脚本的入参校验逻辑在 national_pension_workplace.py 中query_workplace()承担核心校验与请求构造事业场名必填name为空时抛出ValueError提示「请填写事业场名商号国民年金 API 只公开事业者登记号前 6 位因此商号是必填项」登记号规范化先剥离非数字字符re.sub(r\D, , ...)再校验必须为 10 位数字否则报错校验通过后原样传入b_no参数代理地址解析resolve_proxy_base_url()读取KSKILL_PROXY_BASE_URL环境变量——若该值落入off/false/0/disable/disabled/none等禁用集合则报错若为replace-me占位符则回退默认值否则去掉尾部/后使用请求构造以Accept: application/json和User-Agent: k-skill-national-pension-workplace/1.0发起 GET 请求URL 形如{proxyBase}{ROUTE}?{urlencode(params)}其中ROUTE /v1/national-pension/workplace。响应解析与错误映射read_json_response()负责读取结构化 JSON 响应并完成三类错误的状态转换异常情形处理方式上游返回非 JSON / 非对象载荷抛出ApiErrorinvalid JSON / non-object payloadHTTP 503 且 body 中error upstream_not_configured翻译为「k-skill-proxy 未配置所需 API 密钥请联系运营者」HTTPError 且 body 含message字段直接透传该 message网络层URLError提示「所配置的 k-skill-proxy 服务器无响应请稍后重试或联系运营者」并附上具体原因所有错误最终由main()捕获以 JSON 形式输出到 stderr 并返回退出码 1正常时结果以ensure_asciiFalse, indent2的美化 JSON 打印到 stdout返回退出码 0。代理端源码链路从 HTTP 路由到三次上游调用用户侧脚本并不直接接触公共数据门户真正的数据获取发生在k-skill-proxy。整体链路如下路由注册在 server.js 中GET /v1/national-pension/workplace被注册委托给通用的handleKeyedDataGoKrLookup()处理器——该处理器同时服务国民年金、FSC 法人概要、G2B 制裁等「服务端持钥」的 data.go.kr 查询参数规范化normalizeNationalPensionQuery()national-pension.js兼容wkplNm/name/b_nm多种入参别名强制要求事业场名并将b_no规整为 10 位后截取前 6 位作为bnoPrefix缓存检查处理器按route 规范化参数生成缓存键命中则直接返回带cache.hittrue的结果否则进入上游调用TTL 由config.cacheTtlMs控制三次上游编排fetchNationalPensionWorkplace()依序调用同一 upstream 基址https://apis.data.go.kr/B552015/NpsBplcInfoInqireServiceV2下的三个操作getBassInfoSearchV2基础搜索携带wkplNm、6 位bzowrRgstNo前缀、pageNo1、numOfRows100getDetailInfoSearchV2候选唯一时按seq dataCrtYm拉取详情参保人数、告知金额等getPdAcctoSttusInfoSearchV2按seq拉取按月的参保现状时序。每次上游请求都注入serviceKey代理端持有的DATA_GO_KR_API_KEY并设置 20 秒超时AbortSignal.timeout(20000)。XML 响应解析轻量正则解析器公共数据门户返回的是扁平item结构的 XML代理端用正则解析器处理national-pension.js而非引入通用 XML 库若响应含OpenAPI_ServiceResponse说明命中了门户网关层的鉴权/配额错误通过returnReasonCode判断错误类别——代码20/21/30/31/32/33归类为auth-error其余为error若resultCode非00/0归类为error并附上resultMsg正常时以/item...\/item/与/(\w)...\/\1/两级正则抽取出字段对象列表和totalCount。候选去重与选定逻辑fetchNationalPensionWorkplace()在拿到基础搜索结果后还做了三道处理national-pension.js防御性前缀再过滤若提供了bnoPrefix对上游结果按「登记号前 6 位」再过滤一遍「信任上游但自行验证」按月份去重同一事业场会按dataCrtYm资料生成年月重复出现代理端以「wkplNm 道路名详细地址」为键分组每组仅保留最新月份的记录并按年月降序排序候选选定去重后候选数恰为 1 时直接选定否则若名称完全一致trim 后相等的恰好 1 个也选定该条其余情况selected_candidate置为null交由调用方在候选列表中自行确定。选定成功后才发起详情与时序查询。最终响应结构包含query、candidate_count、candidates、raw_row_count、selected_candidate、detail、monthly_status以及一段英文的disclosure_note——重申「登记号仅公开前 6 位无法精确匹配号码名称 前缀匹配到的候选将被列出多个匹配时由调用方判定」这一隐私边界。CLI 使用示例标准用法通过 k-skill CLI 执行 helper 脚本来自 instruction.md 的 CLI examplesnpx -y nomadamas/k-skill0 exec national-pension-workplace scripts/national_pension_workplace.py -- \ --name 삼성전자(주) --b-no 124-81-00998也可以不经过 CLI、直接以python3运行 helper脚本自带 argparse 解析python3 national-pension-workplace/scripts/national_pension_workplace.py \ --name 삼성전자(주) --b-no 124-81-00998脚本还额外暴露了--proxy-base-url参数可在命令行直接覆盖代理地址优先级高于环境变量。若需查看技能在当前运行时下的完整说明或随附文件清单可分别执行见 SKILL.mdnpx -y nomadamas/k-skill0 instruct national-pension-workplace npx -y nomadamas/k-skill0 files national-pension-workplace失败模式与排障对照现象错误码/字段原因与处置未提供事业场名HTTP400error: bad_request参数规范化在代理端即被拦截补上--name即可代理服务器未配置密钥HTTP503error: upstream_not_configured运营端未设置DATA_GO_KR_API_KEY联系代理运营者密钥未被授权该服务HTTP502error: upstream_forbidden代理端密钥未对 data.go.kr 3046071 服务完成活用申请先在公共数据门户申请候选多个正常返回selected_candidate: null属预期行为从candidates列表中选择具体事业场代理无响应网络层错误提示检查网络与KSKILL_PROXY_BASE_URL指向稍后重试代理端错误状态的 HTTP 映射定义在 server.js 的keyedErrorStatus表中upstream_forbidden→ 502、upstream_timeout→ 504、upstream_invalid_response/upstream_error→ 502。同时鉴权失败时密钥绝不会泄露到响应中——测试专门断言了这一点。测试佐证三条关键路径被自动化覆盖k-skill-proxy的测试套件对国民年金路由做了完整覆盖server.test.js可作为理解行为的权威依据规范化测试缺省name抛错{ name: 테스트상사, b_no: 123-45-67890 }被规整为{ wkplNm: 테스트상사, bnoPrefix: 123456 }位数不足123触发 10 位校验错误XML 解析测试伪造OpenAPI_ServiceResponsereturnReasonCode30被识别为auth-error正常 items 被解析为字段对象数组编排端到端测试用 mock fetch 依次应答getBassInfoSearchV2含同一事业场 202604/202605 两个月份 → 验证去重后candidate_count1、raw_row_count2、getDetailInfoSearchV2jnngpCnt120、crrmmNtcAmt5000000、getPdAcctoSttusInfoSearchV2按月列表升序断言三次调用顺序正确、每个请求都携带serviceKeydata-go-key、响应体中不出现密钥明文并验证二次请求命中缓存cache.hittrue错误路径测试未配置密钥时返回 503upstream_not_configured缺少name时返回 400bad_request。合法合规运营基准由于涉及参保信息该技能在 instruction.md 中明确列出三条运营安全准则仅查询公团官方公开的事业场信息参保人数、告知金额是国民年金公团经公共数据门户公开的事业场单位信息不得查询、推定个别劳动者的个人信息明确查询目的仅限交易对手尽调、入职审查、市场调查等正当确认目的的单次查询对特定事业场/行业的批量、定期采集须先确认目的与法律依据依据不明确则不进行最小化结果留存查询结果仅作请求时点参考不得长期保存或再分发。官方数据接口一览项目值公共数据门户数据页https://www.data.go.kr/data/3046071/openapi.do服务编号 3046071Upstream 基址https://apis.data.go.kr/B552015/NpsBplcInfoInqireServiceV2请求参数采用 camelCase代理路由GET /v1/national-pension/workplace小结national-pension-workplace是一个「密钥服务端持有、查询一次完成、结论严守边界」的商务查询类技能用户侧仅需事业场名 可选的前 6 位登记号前缀经由k-skill-proxy完成基础搜索、按月去重、候选选定、详情与月别时序三次上游调用的编排。理解其参数校验、隐私披露边界与失败模式就能在交易对手尽调、入职审查、市场调研等场景中安全、准确地把它接入自己的 Agent 工作流。【免费下载链接】k-skill한국인을 위한 스킬 모음집 - 에이전트를 한국인으로项目地址: https://gitcode.com/GitHub_Trending/ks/k-skill创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考