k-skill 實(shí)戰(zhàn)基于 k-skill-proxy 的 NHIS 長期療養(yǎng)機(jī)構(gòu)與健康體檢機(jī)構(gòu)檢索技能解析【免費(fèi)下載鏈接】k-skill???? ?? ?? ??? - ????? ?????項(xiàng)目地址: https://gitcode.com/GitHub_Trending/ks/k-skill本篇技術(shù)指南以 k-skill 倉庫中的nhis-care-checkup-search技能為對象講解如何通過k-skill-proxy代理路由零密鑰調(diào)用韓國國民健康保險公團(tuán)NHIS????????的長期療養(yǎng)機(jī)構(gòu)檢索服務(wù)data.go.kr15059029與體檢機(jī)構(gòu)查找服務(wù)data.go.kr15154419并完整覆蓋輸入?yún)?shù)別名、curl 調(diào)用流程、上游 XML 響應(yīng)字段摘要、失敗模式與維護(hù)者驗(yàn)證方法。讀完本文你將掌握在 Agent 場景下將公共數(shù)據(jù)門戶 OpenAPI 封裝為無密鑰、可緩存、可排錯的代理檢索能力的完整實(shí)踐方案。技能定位提醒本技能是機(jī)構(gòu)信息查詢工具不提供醫(yī)療判斷、長期療養(yǎng)等級評定也不保證特定機(jī)構(gòu)的適宜性或服務(wù)質(zhì)量。實(shí)際使用條件與預(yù)約可用性請直接向 NHIS 或相應(yīng)機(jī)構(gòu)核實(shí)。核心聲明原文見 instruction.md。一、技能總覽它做什么nhis-care-checkup-search是 k-skill 倉庫中面向韓國醫(yī)療/養(yǎng)老場景的查詢類技能其skill.json聲明了兩個 profileproxy經(jīng)代理調(diào)用與lookup機(jī)構(gòu)查詢類別為healthcare語言區(qū)域ko-KR階段v1詳見 skill.json。該技能通過k-skill-proxy代理兩條上游數(shù)據(jù)源上游服務(wù)data.go.kr 服務(wù)編號代理路由返回內(nèi)容長期療養(yǎng)機(jī)構(gòu)檢索服務(wù)?????? ??15059029GET /v1/nhis/long-term-care機(jī)構(gòu)名、地址、電話、給付/服務(wù)種類等公開字段體檢機(jī)構(gòu)查找服務(wù)???? ??15154419GET /v1/nhis/checkup/{list,by-region,by-checkup-type,holiday}機(jī)構(gòu)名、地址、電話、體檢類型、運(yùn)營日等公開字段代理路由在 packages/k-skill-proxy/README.md 中有明確登記并統(tǒng)一使用DATA_GO_KR_API_KEY環(huán)境變量作為上游認(rèn)證憑據(jù)。何時使用When to use以下典型用戶請求適合啟用本技能?? ?? ?????? ???幫我找首爾江南的長期療養(yǎng)機(jī)構(gòu)??? ??? ??/???? ????確認(rèn)療養(yǎng)院候選及其地址/電話?? ?? ?????? ???幫我找首爾江南的體檢機(jī)構(gòu)?? ?? ??? ???? ???幫我找周末可體檢的機(jī)構(gòu)何時不使用When not to use醫(yī)療判斷、長期療養(yǎng)等級評定、特定機(jī)構(gòu)推薦擔(dān)保預(yù)約、申請、敏感醫(yī)療信息查詢的自動化。二、前置條件與憑據(jù)要求前置條件Prerequisites可用的互聯(lián)網(wǎng)連接可訪問 hosted 或 self-hostk-skill-proxy的/v1/nhis/long-term-care與/v1/nhis/checkup/*路由。憑據(jù)要求Credential requirements用戶側(cè)無必填密鑰——這是本技能的核心設(shè)計(jì)調(diào)用方不需要持有任何 API key密鑰只存在于代理服務(wù)器端。環(huán)境變量用途說明KSKILL_PROXY_BASE_URL代理基地址僅在 self-host 或使用獨(dú)立代理時設(shè)置留空時默認(rèn)使用 hostedhttps://k-skill-proxy.nomadamas.orgDATA_GO_KR_API_KEY公共數(shù)據(jù)門戶 OpenAPI 認(rèn)證鍵只放在代理運(yùn)營服務(wù)器環(huán)境且需在公共數(shù)據(jù)門戶???????為所需服務(wù)完成????利用申請審批密鑰簽發(fā)與申請入口原文檔鏈接信息長期療養(yǎng)機(jī)構(gòu)檢索服務(wù)data.go.kr 服務(wù)15059029體檢機(jī)構(gòu)查找服務(wù)data.go.kr 服務(wù)15154419公共數(shù)據(jù)門戶使用指南data.go.kr 的 ??????? ?? ???代理 README 對這一點(diǎn)有更嚴(yán)格的補(bǔ)充說明DATA_GO_KR_API_KEY被nhis/*等大量路由共享包括household-waste、parking-lots、building-register/title、real-estate、nts-business、mfds-*、lh-notice、kr-whois/*等每個服務(wù)都需要在公共數(shù)據(jù)門戶單獨(dú)提交????并獲批準(zhǔn)同一把密鑰必須分別在15059029與15154419頁面完成激活后對應(yīng)路由才能成功。未激活狀態(tài)下上游會返回 HTTP 401/403 或 data.go.kr 認(rèn)證錯誤 XML代理會將其轉(zhuǎn)換為統(tǒng)一的上游錯誤響應(yīng)。三、輸入?yún)?shù)詳解Inputs原文檔對兩條路由的參數(shù)做了明確的別名映射設(shè)計(jì)代理源碼 nhis-care.js 中的normalizeNhisLongTermCareQuery/normalizeNhisCheckupQuery函數(shù)正是這套別名機(jī)制的落地實(shí)現(xiàn)。長期療養(yǎng)機(jī)構(gòu)路由GET /v1/nhis/long-term-care參數(shù)別名均可使用含義約束qquery、name、adminNm機(jī)構(gòu)名搜索詞可選但四個條件至少給一個sidosiDoCd市/道代碼純數(shù)字sigungusiGunGuCd市/郡/區(qū)代碼純數(shù)字service_kindserviceKind給付/服務(wù)種類代碼純數(shù)字pagepageNo頁碼默認(rèn) 1范圍 1~1000limitnumOfRows每頁條數(shù)默認(rèn) 10最大 100體檢機(jī)構(gòu)路由GET /v1/nhis/checkup/{operation}路由 operation 共四種list、by-region、by-checkup-type、holiday。它們在源碼中與上游操作名的映射關(guān)系為見 nhis-care.js路由 operation上游操作名upstreamOperation典型用途listgetHmcList常規(guī)機(jī)構(gòu)列表by-regiongetRegnHmcList按區(qū)域檢索by-checkup-typegetHchkTypesHmcList按體檢類型檢索holidaygetHolidaysHmcList查詢運(yùn)營日/假日可用信息參數(shù)與別名參數(shù)別名均可使用含義約束qquery、name、hmcNm體檢機(jī)構(gòu)名搜索詞可選四個條件至少給一個sidosiDoCd市/道代碼純數(shù)字sigungusiGunGuCd市/郡/區(qū)代碼純數(shù)字hchk_typecheckup_type、hchkTypeCd體檢類型代碼純數(shù)字pagepageNo頁碼默認(rèn) 1范圍 1~1000limitnumOfRows每頁條數(shù)默認(rèn) 10最大 100源碼細(xì)節(jié)pageNo上限為 1000、numOfRows上限為 100這是由parseBoundedPositiveInteger的max參數(shù)決定的nhis-care.js與文檔中l(wèi)imit 默認(rèn) 10、最大 100的說明完全一致。四、調(diào)用工作流Workflow第 1 步?jīng)Q定調(diào)用面Decide the surface檢索長期療養(yǎng)機(jī)構(gòu)→ 使用/v1/nhis/long-term-care檢索體檢機(jī)構(gòu)→ 按目的在/v1/nhis/checkup/list、/v1/nhis/checkup/by-region、/v1/nhis/checkup/by-checkup-type、/v1/nhis/checkup/holiday中擇一。第 2 步經(jīng)代理查詢長期療養(yǎng)機(jī)構(gòu)BASE${KSKILL_PROXY_BASE_URL:-https://k-skill-proxy.nomadamas.org} curl -fsS --get $BASE/v1/nhis/long-term-care \ --data-urlencode q?? \ --data-urlencode sido11 \ --data-urlencode limit10命令說明--get配合--data-urlencode將查詢參數(shù)以 URL 編碼形式附加到 GET 請求sido11為首爾特別市代碼韓國行政代碼示例limit10控制每頁條數(shù)。第 3 步經(jīng)代理查詢體檢機(jī)構(gòu)BASE${KSKILL_PROXY_BASE_URL:-https://k-skill-proxy.nomadamas.org} curl -fsS --get $BASE/v1/nhis/checkup/by-region \ --data-urlencode q?? \ --data-urlencode sido11 \ --data-urlencode limit10這里選用by-region操作按區(qū)域首爾檢索名含??的體檢機(jī)構(gòu)。第 4 步匯總上游字段Summarize source fields從響應(yīng) XML 的item字段中只摘要上游公開提供的條目例如機(jī)構(gòu)名長期療養(yǎng)為adminNm體檢為hmcNm地址電話號碼給付種類長期療養(yǎng)場景體檢類型、運(yùn)營日體檢場景。當(dāng)用戶需要實(shí)際使用、入住或預(yù)約體檢時應(yīng)明確引導(dǎo)其直接聯(lián)系 NHIS 或相應(yīng)機(jī)構(gòu)進(jìn)行確認(rèn)。五、源碼級實(shí)現(xiàn)原理代理如何工作5.1 上游端點(diǎn)與操作映射nhis-care.js 定義了上游真實(shí)端點(diǎn)長期療養(yǎng)https://apis.data.go.kr/B550928/searchLtcInsttService02/getBillGreentInsttSearchList02體檢https://apis.data.go.kr/B550928/HmcSearchService并追加操作名如getRegnHmcList也就是說代理把對外友好的 REST 風(fēng)格路由如/v1/nhis/checkup/by-region翻譯為公共數(shù)據(jù)門戶內(nèi)部的 SOAP 式操作名屏蔽了上游 API 的別扭結(jié)構(gòu)。5.2 參數(shù)歸一化Normalization兩個normalize*Query函數(shù)承擔(dān)三件事別名折疊把q/query/name/adminNm折疊為單一adminNm把sido/siDoCd折疊為siDoCd以此類推統(tǒng)一上游字段名類型與范圍校驗(yàn)pageNo/numOfRows必須是正整數(shù)且落在規(guī)定區(qū)間siDoCd/siGunGuCd/serviceKind/hchkTypeCd必須是純數(shù)字否則拋出錯誤必填校驗(yàn)當(dāng)搜索詞、市道代碼、市郡區(qū)代碼、服務(wù)/體檢類型四個條件一個都沒給時拋出Provide adminNm, siDoCd, siGunGuCd, or serviceKind.體檢側(cè)對應(yīng) hmcNm/hchkTypeCd 變體路由層捕獲后返回400 bad_request。5.3 代理轉(zhuǎn)發(fā)與認(rèn)證注入proxyNhisLongTermCareRequest 與proxyNhisCheckupRequest的執(zhí)行邏輯若代理服務(wù)器未配置DATA_GO_KR_API_KEY直接返回503 upstream_not_configuredJSON 錯誤體構(gòu)造上游 URL 時把serviceKey注入查詢串并附帶pageNo、numOfRows及非空的可選參數(shù)使用AbortSignal.timeout(20000)設(shè)置 20 秒超時通過isUpstreamAuthStatusHTTP 401/403與isDataGoKrGatewayError識別OpenAPI_ServiceResponse、SERVICE KEY IS NOT REGISTERED等網(wǎng)關(guān)錯誤特征檢測認(rèn)證被拒統(tǒng)一轉(zhuǎn)換為502 upstream_forbidden其余情況下原樣透傳上游 HTTP 狀態(tài)碼、content-type與 XML 正文。5.4 路由注冊與緩存在 server.js 中注冊了兩條路由app.get(/v1/nhis/long-term-care, ...)與app.get(/v1/nhis/checkup/:operation, ...)兩條路由共享config.molitApiKey即環(huán)境變量DATA_GO_KR_API_KEY的歸一化結(jié)果見 server.js使用makeCacheKey({ route: nhis-long-term-care, ...normalized })/makeCacheKey({ route: nhis-checkup, ...normalized })生成緩存鍵命中緩存時直接回放已緩存的statusCode、content-type與body并僅在 2xx 時才寫入緩存TTL 由config.cacheTtlMs控制失敗時返回{ error, message }JSON 結(jié)構(gòu)400 bad_request由歸一化異常觸發(fā)。/health接口中的nhisCareConfigured、nhisCheckupConfigured標(biāo)志即反映DATA_GO_KR_API_KEY是否配置見 server.js可用于運(yùn)維探活。5.5 測試驗(yàn)證代理測試 server.test.js 對上述行為做了完整覆蓋可作為行為契約參考?xì)w一化測試NHIS checkup normalizer ...驗(yàn)證別名折疊q/??→hmcNm、sido→siDoCd、upstreamOperation映射holiday→getHolidaysHmcList等、以及非法輸入未知 operation、缺參、非數(shù)字sido、非數(shù)字hchk_type的拋錯成功注入與緩存測試NHIS checkup route injects serviceKey and caches XML success/NHIS long-term care ...斷言上游 URL 包含serviceKeydata-go-key、hmcNm/adminNm、siDoCd、siGunGuCd、numOfRows且第二次相同請求命中緩存calls.length 1缺失密鑰測試未配置密鑰時返回503與upstream_not_configured認(rèn)證拒絕測試上游返回SERVICE KEY IS NOT REGISTEREDXML 或 HTTP 401 時代理返回502與upstream_forbidden。六、失敗模式與排錯Failure modes原文檔給出的失敗模式及其處理建議錯誤含義處理400 bad_request搜索詞/區(qū)域/服務(wù)種類一個都沒給或代碼/頁碼值錯誤補(bǔ)齊至少一個查詢條件檢查代碼與分頁參數(shù)格式503 upstream_not_configured代理服務(wù)器沒有DATA_GO_KR_API_KEY在代理環(huán)境配置密鑰并重啟502 upstream_forbiddendata.go.kr 網(wǎng)關(guān)拒絕了該密鑰確認(rèn)密鑰有效且對應(yīng)服務(wù)申請已批準(zhǔn)空結(jié)果無匹配機(jī)構(gòu)放寬地區(qū)代碼或機(jī)構(gòu)名寫法后重搜僅特定服務(wù)失敗同密鑰不同服務(wù)狀態(tài)不同data.go.kr 各服務(wù)單獨(dú)審批分別檢查15059029、15154419的 ???? 狀態(tài)結(jié)合源碼可以進(jìn)一步解釋503與502都由 nhis-care.js 在轉(zhuǎn)發(fā)階段判定生成400由歸一化異常在 server.js 的 catch 分支生成三條路徑的錯誤信息均以 JSON 結(jié)構(gòu)返回便于 Agent 直接解析并轉(zhuǎn)述給用戶。七、完成標(biāo)準(zhǔn)Done when一次合格的調(diào)用應(yīng)滿足長期療養(yǎng)機(jī)構(gòu)查詢已通過k-skill-proxy路由完成且未向用戶索要 API key體檢機(jī)構(gòu)查詢已通過k-skill-proxy路由完成且未向用戶索要 API key結(jié)果中同時寫明機(jī)構(gòu)名、位置、聯(lián)系方式、來源服務(wù)與查詢條件便于追溯與復(fù)現(xiàn)。八、維護(hù)者驗(yàn)證Maintainer review notes無需密鑰即可完成的驗(yàn)證手段# 1. 校驗(yàn)全部技能的結(jié)構(gòu)與元數(shù)據(jù) ./scripts/validate-skills.sh # 2. 運(yùn)行代理服務(wù)端測試套件 node --test packages/k-skill-proxy/test/server.test.js # 3. 無密鑰冒煙未配置密鑰時應(yīng)返回 503 curl -i --get $KSKILL_PROXY_BASE_URL/v1/nhis/long-term-care \ --data-urlencode q?? # 4. 無密鑰冒煙體檢路由 curl -i --get $KSKILL_PROXY_BASE_URL/v1/nhis/checkup/by-region \ --data-urlencode q?? \ --data-urlencode sido11curl -i用于觀察完整響應(yīng)頭與狀態(tài)碼密鑰未設(shè)置時上述請求應(yīng)看到503 upstream_not_configured。Live smoke真實(shí)數(shù)據(jù)冒煙則需在 hosted/self-host 代理上配置DATA_GO_KR_API_KEY且15059029或15154419的 ???? 獲得批準(zhǔn)后執(zhí)行。九、安全注意事項(xiàng)Safety notes本技能為只讀查詢技能不執(zhí)行任何寫入類操作不進(jìn)行醫(yī)療判斷、長期療養(yǎng)等級評定不自動化預(yù)約/申請流程認(rèn)證密鑰只在代理服務(wù)器端處理不得存入倉庫、GitHub Actions 或公開文檔與本倉庫 security-and-secrets.md 的密鑰治理原則一致。十、相關(guān)資源索引技能完整指令nhis-care-checkup-search/instruction.md技能元數(shù)據(jù)profiles/類別/階段nhis-care-checkup-search/skill.jsonCLI 分發(fā)入口npx -y nomadamas/k-skill0 instruct nhis-care-checkup-searchnhis-care-checkup-search/SKILL.md代理上游實(shí)現(xiàn)歸一化/轉(zhuǎn)發(fā)/錯誤映射packages/k-skill-proxy/src/nhis-care.js路由注冊與緩存packages/k-skill-proxy/src/server.js行為契約測試packages/k-skill-proxy/test/server.test.js路由與密鑰說明packages/k-skill-proxy/README.md【免費(fèi)下載鏈接】k-skill???? ?? ?? ??? - ????? ?????項(xiàng)目地址: https://gitcode.com/GitHub_Trending/ks/k-skill創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考