k-skill 韩国节假日查询 Skill 实战指南通过 k-skill-proxy 调用韩国天文研究院 특일 정보 API【免费下载链接】k-skill한국인을 위한 스킬 모음집 - 에이전트를 한국인으로项目地址: https://gitcode.com/GitHub_Trending/ks/k-skill本篇指南以 k-skill 仓库中的korean-holiday-calendarSkill 为对象系统讲解如何通过k-skill-proxy的/v1/korean-holiday/calendar路由间接调用韩国公共数据门户공공데이터포털data.go.kr上的「한국천문연구원_특일 정보」韩国天文研究院·特殊日期信息服务编号15012690的SpcdeInfoService实现 공휴일公休日、국경일国庆日、기념일纪念日、24절기二十四节气、잡절杂节的查询。读完本文你将掌握该 Skill 的触发场景、全部入参与操作映射、curl 调用方式、响应字段判读、异常处置策略以及从代理源码到单元测试的完整调用链验证方法。一、Skill 定位与适用场景korean-holiday-calendar是一个纯查询型조회 전용Skill定位为proxylookup两个 profile见 skill.json核心价值在于用户侧无需任何 API Key即可拿到韩国公休日、替代公休日대체공휴일、节气等权威日历数据。API Key 只存在于代理服务端避免了密钥在 Agent 对话、日志、仓库中泄露的风险。适用场景即 Skill 文档给出的典型用户提问2026년 8월 공휴일 알려줘查询 2026 年 8 月的公休日오늘이 공휴일인지 확인해줘确认今天是否为公休日2026년 24절기 조회해줘查询 2026 年二十四节气대체공휴일 있는지 확인해줘确认是否存在替代公休日当用户提出此类问题、且对话发生在韩国时区KST语境下应优先唤起该 Skill。二、前置条件与凭据模型运行前提具备互联网连接能访问 hosted 或 self-host 的k-skill-proxy的/v1/korean-holiday/calendar路由。凭据分层环境变量放置位置作用KSKILL_PROXY_BASE_URL用户侧可选self-host 或使用独立代理时才需设置留空则默认使用 hosted 代理https://k-skill-proxy.nomadamas.orgDATA_GO_KR_API_KEY仅代理运营服务器环境调用 data.go.kr15012690服务所需且必须已完成该服务的「활용신청」使用申请并获得批准需要特别说明的两点用户侧必填 Secret 为 0——这是该 Skill 与其他需要业务密钥的 Skill 的最大差异DATA_GO_KR_API_KEY不能出现在 repo、GitHub Actions 或公开文档中对应本文「安全要点」一节。密钥的申请方式可参照公共数据门户的「한국천문연구원_특일 정보」API 页面及其使用指南原文档中给出了对应外部链接此处不再赘述。源码侧的密钥接线在代理服务中DATA_GO_KR_API_KEY会被解析进配置对象的molitApiKey字段server.js 配置构建并作为serviceKey传入节假日路由的代理请求server.js 第 3458-3461 行const upstream await proxyKoreanHolidayRequest({ params: normalized, serviceKey: config.molitApiKey });也就是说即使代理配置了其他 data.go.kr 密钥类变量节假日路由实际读取的就是DATA_GO_KR_API_KEY。三、Operation 与上游服务映射该 Skill 支持的 5 种操作类型由参数operation/type指定。在源码 korean-holiday.js 的HOLIDAY_OPERATIONS中定义了到韩国天文研究院SpcdeInfoService各上游 operation 的映射operation默认值上游 operation含义rest默认getRestDeInfo공휴일公休日含替代公休日nationalgetHoliDeInfo국경일国庆日anniversarygetAnniversaryInfo기념일纪念日solarTermget24DivisionsInfo24절기二十四节气sundrygetSundryDayInfo잡절杂节上游请求的 URL 形如https://apis.data.go.kr/B090041/openapi/service/SpcdeInfoService/{getRestDeInfo|getHoliDeInfo|...}见 korean-holiday.js 第 1、92 行。其中 24절기 / 잡절 两个 operation 沿用了韩国天文研究院 특일 서비스 的惯例命名代理端维护了一份 allowlist即HOLIDAY_OPERATIONS白名单若后续 live smoke 测试发现上游改动代理会同步刷新这份白名单。四、入参规范Skill 文档定义的入参如下其中每组给出了「用户侧习惯命名 → 上游参数名」的别名关系参数别名说明operationtype上表 5 个值之一默认restyearsolYear4 位年份如2026monthsolMonth可选01–12必须两位pagepageNo默认 1limitnumOfRows默认 100最大 1000在 normalizeKoreanHolidayQuery 中这些规则被严格校验operation不在白名单则抛出operation must be one of: ...solYear必须匹配/^\d{4}$/严格 4 位数字solMonth会被padStart(2, 0)补齐成两位并校验01–12范围因此传8也会被规范化为08pageNo、numOfRows均为 1–1000 的整型非法输入直接抛错并最终由路由层返回400 bad_request。五、标准调用流程1. 向目标年月发起查询Skill 文档给出的标准调用方式如下KSKILL_PROXY_BASE_URL为空时自动回退到 hosted 代理BASE${KSKILL_PROXY_BASE_URL:-https://k-skill-proxy.nomadamas.org} curl -fsS --get $BASE/v1/korean-holiday/calendar \ --data-urlencode operationrest \ --data-urlencode year2026 \ --data-urlencode month08该请求最终落到 server.js 的路由处理器先normalizeKoreanHolidayQuery归一化入参再以{ route: korean-holiday-calendar, ...normalized }生成缓存键查询内存缓存未命中时经proxyKoreanHolidayRequest转发给 data.go.kr成功2xx响应会被写入缓存TTL 由KSKILL_PROXY_CACHE_TTL_MS控制默认 300000ms即 5 分钟。2. 依据上游字段判定节假日状态响应为 XMLitems中每个 item 的核心字段locdate日期格式YYYYMMDDdateName特殊日名称isHolidayY表示公休日N表示虽是特殊日但非公休日dateKind、seq上游分类与序号。「今天/明天是不是公休日」的判读方法先把 KST 时区的当前日期格式化为YYYYMMDD再检查对应locdate的isHoliday是否为Y。由于是韩国日历数据时间基准务必使用韩国标准时间KSTUTC9避免因时区偏移导致日期错位。六、失败模式与排障手册Skill 文档列出了该路由的全部已知失败模式结合源码可给出更精确的触发条件状态码错误码触发条件排查方向400bad_request年/月/operation/page 等参数值非法如年份非 4 位、月份不在 01–12、operation 不在白名单核对 normalizeKoreanHolidayQuery 的校验规则503upstream_not_configured代理服务器未配置DATA_GO_KR_API_KEY检查 proxyKoreanHolidayRequest 的密钥缺失分支502upstream_forbiddendata.go.kr 网关拒绝密钥密钥未注册或15012690使用申请未获批查看网关错误体是否含OpenAPI_ServiceResponse/SERVICE KEY IS NOT REGISTERED对应 isDataGoKrGatewayError空结果—该年月 operation 组合下无特殊日更换 operation 重新查询例如某月无公休日但有节气关于「空结果」需要提醒rest公休日与solarTerm节气是互补性最强的两个 operation当某月公休日为空时切换solarTerm往往仍有返回。此外如果solarTerm/sundry在 live smoke 中发现上游行为变化需要同步更新路由 allowlist对应文档中维护者注意事项。七、完成判定标准Done when一次成功的节假日查询应同时满足KST 时区的当前日期与请求的年月一致全程经k-skill-proxy路由调用且未向用户索要任何 API Key回答中明确给出locdate、dateName、isHoliday以及所用的 operation方便用户核验数据来源与语义。八、无密钥验证与维护者检查清单由于代理侧已隔离密钥开发者可以在本地无密钥完成大部分回归验证# 1. Skill 结构与元数据校验 ./scripts/validate-skills.sh # 2. 代理路由单元测试含节假日路由缓存、solarTerm 映射、缺密钥 503、上游拒钥 502 node --test packages/k-skill-proxy/test/server.test.js # 3. 无密钥场景下的路由行为冒烟未配置密钥时预期看到 503 curl -i --get $KSKILL_PROXY_BASE_URL/v1/korean-holiday/calendar \ --data-urlencode year2026在 packages/k-skill-proxy/test/server.test.js 中可以找到上述三条路径的完整测试用例可作为实现事实的验证锚点测试一第 420-440 行mock 上游后请求operationrestyear2026month08断言返回体包含「광복절」、上游 URL 命中SpcdeInfoService/getRestDeInfo、携带ServiceKeydata-go-key、solYear2026、solMonth08且第二次相同请求不产生新的上游调用验证缓存命中测试二第 442-466 行operationsolarTerm映射到get24DivisionsInfo无DATA_GO_KR_API_KEY时返回503 upstream_not_configured测试三第 468-483 行上游返回SERVICE KEY IS NOT REGISTERED ERROR网关错误时映射为502 upstream_forbidden。真正依赖真实数据的live smoke仅在 hosted/self-host 代理已配置DATA_GO_KR_API_KEY、且15012690使用申请获批后执行例如curl真实年份数据核对locdate/dateName。九、安全要点与使用边界纯查询只读该 Skill 只做数据查询不涉及任何写入、下单、发信等副作用操作法律/金融场景免责涉及法定营业日법정 영업일判断、金融/法律期限마감计算时必须将上游 API 结果与相关法令及机构公告交叉核对不能仅凭 API 数据下定论密钥边界认证密钥只存在于代理服务端环境变量中不得写入仓库、CIGitHub Actions或公开文档Agent 在任何情况下都不应要求用户提供明文密钥对应 SKILL.md 中的硬性规则时区约定所有日期判读以 KST 为准。十、相关资源Skill 元数据与入口skill.json、SKILL.md、instruction.md功能速览docs/features/korean-holiday-calendar.md代理端实现korean-holiday.js参数归一化、白名单、网关错误识别、上游转发、server.js 路由注册400 兜底、缓存、密钥注入回归测试packages/k-skill-proxy/test/server.test.js校验脚本scripts/validate-skills.sh更完整的代理路由总览见 docs/features/k-skill-proxy.md【免费下载链接】k-skill한국인을 위한 스킬 모음집 - 에이전트를 한국인으로项目地址: https://gitcode.com/GitHub_Trending/ks/k-skill创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 k-skill 韩国节假日查询 Skill 实战指南：通过 k-skill-proxy 调用韩国天文研究院 특일 정보 API
k-skill 韩国节假日查询 Skill 实战指南通过 k-skill-proxy 调用韩国天文研究院 특일 정보 API【免费下载链接】k-skill한국인을 위한 스킬 모음집 - 에이전트를 한국인으로项目地址: https://gitcode.com/GitHub_Trending/ks/k-skill本篇指南以 k-skill 仓库中的korean-holiday-calendarSkill 为对象系统讲解如何通过k-skill-proxy的/v1/korean-holiday/calendar路由间接调用韩国公共数据门户공공데이터포털data.go.kr上的「한국천문연구원_특일 정보」韩国天文研究院·特殊日期信息服务编号15012690的SpcdeInfoService实现 공휴일公休日、국경일国庆日、기념일纪念日、24절기二十四节气、잡절杂节的查询。读完本文你将掌握该 Skill 的触发场景、全部入参与操作映射、curl 调用方式、响应字段判读、异常处置策略以及从代理源码到单元测试的完整调用链验证方法。一、Skill 定位与适用场景korean-holiday-calendar是一个纯查询型조회 전용Skill定位为proxylookup两个 profile见 skill.json核心价值在于用户侧无需任何 API Key即可拿到韩国公休日、替代公休日대체공휴일、节气等权威日历数据。API Key 只存在于代理服务端避免了密钥在 Agent 对话、日志、仓库中泄露的风险。适用场景即 Skill 文档给出的典型用户提问2026년 8월 공휴일 알려줘查询 2026 年 8 月的公休日오늘이 공휴일인지 확인해줘确认今天是否为公休日2026년 24절기 조회해줘查询 2026 年二十四节气대체공휴일 있는지 확인해줘确认是否存在替代公休日当用户提出此类问题、且对话发生在韩国时区KST语境下应优先唤起该 Skill。二、前置条件与凭据模型运行前提具备互联网连接能访问 hosted 或 self-host 的k-skill-proxy的/v1/korean-holiday/calendar路由。凭据分层环境变量放置位置作用KSKILL_PROXY_BASE_URL用户侧可选self-host 或使用独立代理时才需设置留空则默认使用 hosted 代理https://k-skill-proxy.nomadamas.orgDATA_GO_KR_API_KEY仅代理运营服务器环境调用 data.go.kr15012690服务所需且必须已完成该服务的「활용신청」使用申请并获得批准需要特别说明的两点用户侧必填 Secret 为 0——这是该 Skill 与其他需要业务密钥的 Skill 的最大差异DATA_GO_KR_API_KEY不能出现在 repo、GitHub Actions 或公开文档中对应本文「安全要点」一节。密钥的申请方式可参照公共数据门户的「한국천문연구원_특일 정보」API 页面及其使用指南原文档中给出了对应外部链接此处不再赘述。源码侧的密钥接线在代理服务中DATA_GO_KR_API_KEY会被解析进配置对象的molitApiKey字段server.js 配置构建并作为serviceKey传入节假日路由的代理请求server.js 第 3458-3461 行const upstream await proxyKoreanHolidayRequest({ params: normalized, serviceKey: config.molitApiKey });也就是说即使代理配置了其他 data.go.kr 密钥类变量节假日路由实际读取的就是DATA_GO_KR_API_KEY。三、Operation 与上游服务映射该 Skill 支持的 5 种操作类型由参数operation/type指定。在源码 korean-holiday.js 的HOLIDAY_OPERATIONS中定义了到韩国天文研究院SpcdeInfoService各上游 operation 的映射operation默认值上游 operation含义rest默认getRestDeInfo공휴일公休日含替代公休日nationalgetHoliDeInfo국경일国庆日anniversarygetAnniversaryInfo기념일纪念日solarTermget24DivisionsInfo24절기二十四节气sundrygetSundryDayInfo잡절杂节上游请求的 URL 形如https://apis.data.go.kr/B090041/openapi/service/SpcdeInfoService/{getRestDeInfo|getHoliDeInfo|...}见 korean-holiday.js 第 1、92 行。其中 24절기 / 잡절 两个 operation 沿用了韩国天文研究院 특일 서비스 的惯例命名代理端维护了一份 allowlist即HOLIDAY_OPERATIONS白名单若后续 live smoke 测试发现上游改动代理会同步刷新这份白名单。四、入参规范Skill 文档定义的入参如下其中每组给出了「用户侧习惯命名 → 上游参数名」的别名关系参数别名说明operationtype上表 5 个值之一默认restyearsolYear4 位年份如2026monthsolMonth可选01–12必须两位pagepageNo默认 1limitnumOfRows默认 100最大 1000在 normalizeKoreanHolidayQuery 中这些规则被严格校验operation不在白名单则抛出operation must be one of: ...solYear必须匹配/^\d{4}$/严格 4 位数字solMonth会被padStart(2, 0)补齐成两位并校验01–12范围因此传8也会被规范化为08pageNo、numOfRows均为 1–1000 的整型非法输入直接抛错并最终由路由层返回400 bad_request。五、标准调用流程1. 向目标年月发起查询Skill 文档给出的标准调用方式如下KSKILL_PROXY_BASE_URL为空时自动回退到 hosted 代理BASE${KSKILL_PROXY_BASE_URL:-https://k-skill-proxy.nomadamas.org} curl -fsS --get $BASE/v1/korean-holiday/calendar \ --data-urlencode operationrest \ --data-urlencode year2026 \ --data-urlencode month08该请求最终落到 server.js 的路由处理器先normalizeKoreanHolidayQuery归一化入参再以{ route: korean-holiday-calendar, ...normalized }生成缓存键查询内存缓存未命中时经proxyKoreanHolidayRequest转发给 data.go.kr成功2xx响应会被写入缓存TTL 由KSKILL_PROXY_CACHE_TTL_MS控制默认 300000ms即 5 分钟。2. 依据上游字段判定节假日状态响应为 XMLitems中每个 item 的核心字段locdate日期格式YYYYMMDDdateName特殊日名称isHolidayY表示公休日N表示虽是特殊日但非公休日dateKind、seq上游分类与序号。「今天/明天是不是公休日」的判读方法先把 KST 时区的当前日期格式化为YYYYMMDD再检查对应locdate的isHoliday是否为Y。由于是韩国日历数据时间基准务必使用韩国标准时间KSTUTC9避免因时区偏移导致日期错位。六、失败模式与排障手册Skill 文档列出了该路由的全部已知失败模式结合源码可给出更精确的触发条件状态码错误码触发条件排查方向400bad_request年/月/operation/page 等参数值非法如年份非 4 位、月份不在 01–12、operation 不在白名单核对 normalizeKoreanHolidayQuery 的校验规则503upstream_not_configured代理服务器未配置DATA_GO_KR_API_KEY检查 proxyKoreanHolidayRequest 的密钥缺失分支502upstream_forbiddendata.go.kr 网关拒绝密钥密钥未注册或15012690使用申请未获批查看网关错误体是否含OpenAPI_ServiceResponse/SERVICE KEY IS NOT REGISTERED对应 isDataGoKrGatewayError空结果—该年月 operation 组合下无特殊日更换 operation 重新查询例如某月无公休日但有节气关于「空结果」需要提醒rest公休日与solarTerm节气是互补性最强的两个 operation当某月公休日为空时切换solarTerm往往仍有返回。此外如果solarTerm/sundry在 live smoke 中发现上游行为变化需要同步更新路由 allowlist对应文档中维护者注意事项。七、完成判定标准Done when一次成功的节假日查询应同时满足KST 时区的当前日期与请求的年月一致全程经k-skill-proxy路由调用且未向用户索要任何 API Key回答中明确给出locdate、dateName、isHoliday以及所用的 operation方便用户核验数据来源与语义。八、无密钥验证与维护者检查清单由于代理侧已隔离密钥开发者可以在本地无密钥完成大部分回归验证# 1. Skill 结构与元数据校验 ./scripts/validate-skills.sh # 2. 代理路由单元测试含节假日路由缓存、solarTerm 映射、缺密钥 503、上游拒钥 502 node --test packages/k-skill-proxy/test/server.test.js # 3. 无密钥场景下的路由行为冒烟未配置密钥时预期看到 503 curl -i --get $KSKILL_PROXY_BASE_URL/v1/korean-holiday/calendar \ --data-urlencode year2026在 packages/k-skill-proxy/test/server.test.js 中可以找到上述三条路径的完整测试用例可作为实现事实的验证锚点测试一第 420-440 行mock 上游后请求operationrestyear2026month08断言返回体包含「광복절」、上游 URL 命中SpcdeInfoService/getRestDeInfo、携带ServiceKeydata-go-key、solYear2026、solMonth08且第二次相同请求不产生新的上游调用验证缓存命中测试二第 442-466 行operationsolarTerm映射到get24DivisionsInfo无DATA_GO_KR_API_KEY时返回503 upstream_not_configured测试三第 468-483 行上游返回SERVICE KEY IS NOT REGISTERED ERROR网关错误时映射为502 upstream_forbidden。真正依赖真实数据的live smoke仅在 hosted/self-host 代理已配置DATA_GO_KR_API_KEY、且15012690使用申请获批后执行例如curl真实年份数据核对locdate/dateName。九、安全要点与使用边界纯查询只读该 Skill 只做数据查询不涉及任何写入、下单、发信等副作用操作法律/金融场景免责涉及法定营业日법정 영업일判断、金融/法律期限마감计算时必须将上游 API 结果与相关法令及机构公告交叉核对不能仅凭 API 数据下定论密钥边界认证密钥只存在于代理服务端环境变量中不得写入仓库、CIGitHub Actions或公开文档Agent 在任何情况下都不应要求用户提供明文密钥对应 SKILL.md 中的硬性规则时区约定所有日期判读以 KST 为准。十、相关资源Skill 元数据与入口skill.json、SKILL.md、instruction.md功能速览docs/features/korean-holiday-calendar.md代理端实现korean-holiday.js参数归一化、白名单、网关错误识别、上游转发、server.js 路由注册400 兜底、缓存、密钥注入回归测试packages/k-skill-proxy/test/server.test.js校验脚本scripts/validate-skills.sh更完整的代理路由总览见 docs/features/k-skill-proxy.md【免费下载链接】k-skill한국인을 위한 스킬 모음집 - 에이전트를 한국인으로项目地址: https://gitcode.com/GitHub_Trending/ks/k-skill创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考