k-skill 之 g2b-sanctioned-supplier基于 나라장터 공공데이터 API 的 부정당제재업체 实时查询技能全解析【免费下载链接】k-skill한국인을 위한 스킬 모음집 - 에이전트를 한국인으로项目地址: https://gitcode.com/GitHub_Trending/ks/k-skillg2b-sanctioned-supplier是 k-skill 仓库中面向韩国公共采购场景的企业合规查询技能通过k-skill-proxy代理调用 공공데이터포털(公共数据门户)的조달청 나라장터 사용자정보 서비스(数据编号 15129466接口getUnptRsttCorpInfo02)以 사업자등록번호(营业执照号) 精确匹配(inqryDiv1)查询该企业在当前查询时刻仍然生效的 입찰참가자격 제한(부정당제재不正当制裁)。读完本文你将掌握该技能的完整调用方式、密钥与代理配置、响应结构与 coverage 语义、常见失败模式的排查方法以及代理端与 CLI 端的源码级实现原理。技能定位为“交易前合规核验”设计的制裁查询在韩国公共采购生态中입찰참가자격 제한은 조달청이 부정당업자로 제재한 기업이 일정 기간 입찰·계약에 참여하지 못하도록 하는 제도。g2b-sanctioned-supplier技能正是为这类「事前合规核验」场景设计的在与一家公司建立交易或签订合同之前通过一个 사업자등록번호 快速确认其当前是否存在生效中的 부정당제재。技能的核心特征可以从 skill.json 的元数据中读出category: business、locale: ko-KR、phase: v1并注册了proxy与lookup两个 profile——前者表明它依赖k-skill-proxy代理后者表明它是典型的只读查询型技能。典型使用场景包括「이 회사 입찰 제재(부정당제재) 이력 있어?」(这家公司有投标制裁记录吗)「거래/계약 전에 부정당업자 제재 여부 확인해줘」(交易/签约前帮我确认是否存在不正当供应商制裁)返回结果中包含 제재 시작/종료일자(制裁起止日期)、제재기관명(制裁机关名称)、계약법구분(契约法区分)、제재근거법률(制裁依据法律)等 upstream 原始字段instruction.md 明确规定输出策略不做任何分数、等级、解读性标签只呈现 upstream 事实、来源与适用范围边界。覆盖范围边界这是“当前生效”查询不是历史档案理解该技能的前提是接受它的边界。upstream 接口规范决定了g2b-sanctioned-supplier不是历史查询工具以下数据明确不在覆盖范围内已过期或已解除的制裁查询时刻已经 만료·해제(过期/解除)的制裁记录不会返回未在 나라장터 注册的企业与个人对 나라장터 未등록(未注册)的供应商或个人不存在可查询的制裁记录。需要说明的是total_count: 0的含义也随之限定为「查询时刻不存在当前生效的制裁」并不能被解读为「该企业从未被制裁过」。若确实需要核对已过期的历史记录instruction.md 明确建议回到 나라장터(www.g2b.go.kr) 进行人工核对。这一边界不仅写在文档里也被写进了代理端返回的coverage元数据中详见下文「响应结构与 coverage 语义」使 Agent 或调用方在拿到结果时就能结构化地理解结果的适用前提避免对 0 结果做过度解读。架构与调用链CLI 辅助脚本 → k-skill-proxy → 공공데이터포털整个查询链路分为三层这是理解本技能的关键用户/Agent │ npx k-skill exec ...本地无密钥 ▼ g2b_sanctioned_supplier.py仅构造查询、解析结构化响应 │ GET /v1/g2b/sanctioned-supplier?bizno... ▼ k-skill-proxy持有 DATA_GO_KR_API_KEY调用 upstream │ GET https://apis.data.go.kr/1230000/ao/UsrInfoService02/getUnptRsttCorpInfo02 ▼ 공공데이터포털조달청 나라장터 사용자정보 서비스 15129466为什么需要代理中转关键原因是密钥边界。用户本地完全不接触DATA_GO_KR_API_KEY——该密钥只存在于代理服务器环境中。CLI 侧 g2b_sanctioned_supplier.py 的模块注释写得很清楚The proxy holds DATA_GO_KR_API_KEY server-side; this helper only builds the query and reads the structured response. No user secret is required.代理端 packages/k-skill-proxy/src/g2b-sanction.js 封装了 upstream 调用构造 URL 时固定设置ServiceKey、numOfRows100、pageNo1、typejson、inqryDiv1与bizno参数并设置 20 秒的请求超时(AbortSignal.timeout(20000))。其中inqryDiv1正是「按 10 位 사업자등록번호 精确匹配」的查询模式对应文档中「사업자등록번호 정확 일치」的描述。在 packages/k-skill-proxy/src/server.js 中路由GET /v1/g2b/sanctioned-supplier通过handleKeyedDataGoKrLookup统一注册将normalizeG2bSanctionQuery作为入参规范化器、fetchG2bSanctions作为 upstream 抓取器注入与其他 data.go.kr 类路由共享同一套错误处理骨架。前置条件与密钥管理用户零密钥密钥只在代理侧运行该技能的前置条件见 instruction.md网络连接与python3运行时仓库中的scripts/g2b_sanctioned_supplier.py辅助脚本可访问 hosted 或 self-host 的k-skill-proxy的/v1/g2b/sanctioned-supplier路由。凭证要求关键用户侧无需任何必填密钥KSKILL_PROXY_BASE_URL仅在自托管代理时设置不设置时回退到 hosted 代理https://k-skill-proxy.nomadamas.orgDATA_GO_KR_API_KEY只存放在代理运营服务器环境中且该密钥必须在 공공데이터포털 上完成「조달청_나라장터 사용자정보 서비스」(含 부정당제재업체정보 조회) 的활용신청(使用申请)否则代理侧调用会被 upstream 拒绝。CLI 脚本对代理地址的处理在 g2b_sanctioned_supplier.py 的resolve_proxy_base_url中实现优先取显式参数其次读环境变量KSKILL_PROXY_BASE_URL若该值落入off / false / 0 / disable / disabled / none之一则直接报错禁用若为占位值replace-me或为空则回退到默认 hosted 地址并对 URL 做尾部斜杠归一化。使用方式一行命令完成制裁查询通过 k-skill CLI 执行查询来自 docs/features/g2b-sanctioned-supplier.md 的官方示例npx -y nomadamas/k-skill0 exec g2b-sanctioned-supplier scripts/g2b_sanctioned_supplier.py -- --bizno 124-81-00998CLI 参数详解辅助脚本 g2b_sanctioned_supplier.py 的参数解析在build_parser中定义参数必填说明--bizno是사업자등록번호 10 位数字允许带连字符如124-81-00998--proxy-base-url否覆盖默认/环境变量指定的代理地址等价于显式指定KSKILL_PROXY_BASE_URL--bizno的输入校验逻辑位于normalize_bizno先剥离所有非数字字符再要求与\d{10}完全匹配否则抛出ValueError并提示「사업자등록번호는 숫자 10자리여야 합니다」。查询构造时脚本将规范化后的号码通过urllib.parse.urlencode拼接到代理路由GET /v1/g2b/sanctioned-supplier上并携带Accept: application/json与User-Agent: k-skill-g2b-sanctioned-supplier/1.0头。成功时脚本以ensure_asciiFalse, indent2将 JSON 响应打印到 stdoutValueError/ApiError则以 JSON 形式写入 stderr 并返回退出码 1方便下游程序化解析。响应结构与 coverage 语义结果如何被结构化解释代理端fetchG2bSanctions将 upstream 的原始 JSON 封装后返回结构化响应关键字段包括bizno查询的营业执照号total_count当前生效的制裁记录数active_sanctions制裁条目数组包含 제재 시작/종료일자、제재기관명、계약법구분、제재근거법률 等 upstream 原文字段coverage覆盖范围元数据对象结构化说明结果语义。coverage对象见 g2b-sanction.js 的实现包含scope: currently-effective-g2b-sanctions范围为当前生效制裁match_basis: exact-business-number匹配依据为营业执照号精确匹配exclusions明确列出排除项——expired-or-lifted-sanctions(已过期/已解除)、sanctions-against-suppliers-or-individuals-not-registered-in-g2b(未注册于 나라장터 的企业/个人)zero_result_meaning用韩文明确说明「0 结果 ≠ 无历史制裁」的语义防止误读checked_at查询时刻(ISO 8601)。此外extractSanctionItems对 upstream 的 JSON 信封做了健壮性处理校验response.header.resultCode非00/0时抛错兼容 data.go.kr 在单条/零条结果时返回 dict 而非数组的变体统一归一为数组totalCount缺失时以实际条目数兜底。失败模式与排查手册文档与源码共同定义了四类典型失败模式排查思路如下失败形态含义与处理400 bad_request사업자번호 不是 10 位数字属于本地输入校验失败先检查--bizno格式见normalize_bizno503 upstream_not_configured代理服务器环境未配置DATA_GO_KR_API_KEY。CLI 侧read_json_response会识别该错误码并输出「k-skill-proxy에 필요한 API 키가 설정되어 있지 않습니다」提示502 upstream_forbidden代理持有的密钥未通过 15129466 服务的 활용신청。代理端对 upstream 的 401/403 状态码以及OpenAPI_ServiceResponse信封中returnReasonCode为20/21/30/31/32/33的网关认证错误都会归类为upstream_forbiddentotal_count: 0查询时刻无当前生效制裁。注意这不代表没有过期制裁——见上文 coverage 的zero_result_meaning值得展开的是upstream_forbidden的判定细节韩国数据门户在密钥未申请对应服务时常见返回携带returnReasonCode的 XML/JSON 错误信封g2b-sanction.js 中的parseGatewayAuthError与isAuthResultCode专门针对20/21/30/31/32/33这组认证原因码做识别将其统一映射为502 upstream_forbidden并附带提示「proxy key may not be approved for service 15129466」把「密钥没申请服务」与「服务内部错误」明确区分开。CLI 侧对 HTTP 错误会优先读取 JSON body 中的message字段透传仅在 503 upstream_not_configured时做专门的韩文提示替换。测试验证coverage 透传与解析健壮性仓库为 CLI 脚本提供了单元测试 g2b-sanctioned-supplier/scripts/test_g2b_sanctioned_supplier.py核心验证点是「结构化响应与 coverage 元数据的透传」test_zero_result_keeps_proxy_coveragetotal_count0且active_sanctions为空时query_sanctions原样透传响应并保留coverage.scope currently-effective-g2b-sanctionstest_matched_result_keeps_proxy_coverage命中 1 条记录时透传active_sanctions并保留coverage.match_basis exact-business-number。测试通过注入read_json桩函数隔离网络依赖验证了「CLI 只转发、不解构 coverage」的设计——即覆盖范围语义完全由代理端统一生成并保证一致CLI 端不重复解释避免两端语义漂移。官方来源与人工对照途径根据文档本技能的官方数据链路为공공데이터포털数据编号15129466조달청 나라장터 사용자정보 서비스可在公共数据门户检索该编号获取接口说明upstream 端点https://apis.data.go.kr/1230000/ao/UsrInfoService02/getUnptRsttCorpInfo02该 URL 同时被 g2b-sanction.js 中的G2B_SANCTION_URL常量引用人工对照需要核验过期历史或对结果存疑时前往 나라장터(www.g2b.go.kr) 手动查询代理路由GET /v1/g2b/sanctioned-supplier在 server.js 中注册。总结g2b-sanctioned-supplier是一个设计克制、边界清晰的合规查询技能通过「用户零密钥 代理持钥」的架构把敏感凭证隔离在代理侧通过inqryDiv1精确匹配实现当前生效制裁的实时查询并通过coverage元数据把「不是历史查询、0 结果 ≠ 无历史」的语义结构化地传递给上层 Agent。无论是作为交易前尽职调查的一环还是作为 k-skill 代理类技能在「代理 查询」profile 上的参考实现它都值得直接对照 instruction.md 与 g2b-sanction.js 深入阅读。【免费下载链接】k-skill한국인을 위한 스킬 모음집 - 에이전트를 한국인으로项目地址: https://gitcode.com/GitHub_Trending/ks/k-skill创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考