@nomadamas/k-skill 0.4.2 → 0.5.0

package/skills/kamis-food-price/instruction.md

@@ -0,0 +1,66 @@
+# KAMIS 농수축산물 가격 조회
+
+## What this skill does
+
+한국농수산식품유통공사 KAMIS의 `dailyPriceByCategoryList`를
+`k-skill-proxy`의 좁은 read-only route로 호출한다. 농산물·축산물·수산물의
+부류별 도매/소매 가격과 전일, 1주일, 1개월, 1년, 평년 비교값을 반환한다.
+
+이 skill은 쇼핑몰 최저가나 투자 추천이 아니라 공식 유통가격 조회용이다.
+
+## Inputs
+
+- `p_productclscode`: `01` 소매, `02` 도매. 기본 `01`
+- `p_itemcategorycode`: `100` 식량작물, `200` 채소류, `300` 특용작물,
+  `400` 과일류, `500` 축산물, `600` 수산물. 기본 `100`
+- `p_countycode`: 지역 코드(예: `1101` 서울). 생략하면 전체 지역
+- `p_regday`: `YYYY-MM-DD`, 생략하면 최근 조사일
+- `p_convert_kg_yn`: `Y` 또는 `N`. 기본 `N`
+
+사용자가 문서식 별칭인 `p_product_cls_code`, `p_country_code`,
+`p_item_category_code`를 주어도 proxy가 실제 upstream 계약명으로 정규화한다.
+
+## Workflow
+
+```bash
+BASE="${KSKILL_PROXY_BASE_URL:-https://k-skill-proxy.nomadamas.org}"
+curl -fsS --get "$BASE/v1/kamis/food-price/daily-category" \
+  --data-urlencode "p_productclscode=01" \
+  --data-urlencode "p_itemcategorycode=200" \
+  --data-urlencode "p_countycode=1101" \
+  --data-urlencode "p_convert_kg_yn=N"
+```
+
+응답의 `items` 각 항목에서 `item_name`, `kind_name`, `rank`, `unit`,
+`dpr1`(조회일), `dpr2`(1일 전), `dpr3`(1주일 전), `dpr5`(1개월 전),
+`dpr6`(1년 전), `dpr7`(평년)을 확인한다. 가격 문자열의 쉼표와 `-`를
+숫자로 바꿀 때는 빈 값 여부를 먼저 보존한다.
+
+## Access path and credentials
+
+일반 사용자는 hosted `k-skill-proxy`를 사용하므로 KAMIS 키가 필요 없다.
+proxy 운영자는 KAMIS에서 발급받은 `KAMIS_API_KEY`를 서버 runtime env에
+보관한다. upstream의 `p_cert_id`는 별도 API key가 아니라 요청자 ID
+파라미터이며, 현재 proxy는 live 계약에서 검증한 `TEST` 값을 사용한다.
+키를 URL, 로그, 저장소, 사용자 응답에 노출하지 않는다.
+
+공식 문서:
+<https://www.kamis.or.kr/customer/reference/openapi_list.do?action=detail&boardno=1>
+
+실제 upstream 경로는 `xml.do`이지만 `p_returntype=json`을 사용한다. 이는
+KAMIS의 공식 계약이며 URL을 `json.do`로 바꾸지 않는다.
+
+## Failure modes
+
+- `400 bad_request`: 잘못된 날짜, 지역 코드, 부류 코드, 도소매 값
+- `503 upstream_not_configured`: proxy runtime에 `KAMIS_API_KEY` 없음
+- `400` 또는 `502 upstream_error`: KAMIS code `200`, `900`, 네트워크/상류 오류
+- `items: []`, upstream code `001`: 해당 조건의 가격 없음
+- KAMIS가 JSON 대신 점검 HTML/XML을 반환하면 `upstream_invalid_response`
+- 가격은 조사 시점의 공식 데이터이며 구매 보장·법률 판단·투자 조언이 아니다
+
+## Done when
+
+- 조회 조건과 `query`가 응답에 남아 있다.
+- 각 가격 항목의 조회일과 비교 기간을 구분했다.
+- 답변에 KAMIS 원문 출처와 조회 조건을 함께 적었다.

package/skills/kamis-food-price/scripts/run_kamis.py

@@ -0,0 +1,110 @@
+#!/usr/bin/env python3
+"""Read KAMIS prices through the hosted proxy, with an optional direct mode."""
+import argparse
+import json
+import os
+import sys
+import urllib.error
+import urllib.parse
+import urllib.request
+
+DEFAULT_PROXY = "https://k-skill-proxy.nomadamas.org"
+UPSTREAM = "https://www.kamis.or.kr/service/price/xml.do"
+
+
+def secrets(path):
+    values = {}
+    try:
+        with open(path, encoding="utf-8") as stream:
+            for line in stream:
+                line = line.strip()
+                if line and not line.startswith("#") and "=" in line:
+                    key, value = line.split("=", 1)
+                    values[key.strip()] = value.strip().strip("\"'")
+    except OSError:
+        pass
+    return values
+
+
+def query(args):
+    if args.product_class not in {"01", "02"}:
+        raise ValueError("--product-class must be 01 or 02")
+    if args.category not in {"100", "200", "300", "400", "500", "600"}:
+        raise ValueError("--category must be 100, 200, 300, 400, 500, or 600")
+    if args.convert_kg not in {"Y", "N"}:
+        raise ValueError("--convert-kg must be Y or N")
+    result = {
+        "p_productclscode": args.product_class,
+        "p_itemcategorycode": args.category,
+        "p_convert_kg_yn": args.convert_kg,
+        "p_returntype": "json",
+    }
+    if args.county:
+        if not args.county.isdigit() or len(args.county) != 4:
+            raise ValueError("--county must be a four-digit KAMIS code")
+        result["p_countycode"] = args.county
+    if args.date:
+        if len(args.date) != 10 or args.date[4] != "-" or args.date[7] != "-":
+            raise ValueError("--date must be YYYY-MM-DD")
+        result["p_regday"] = args.date
+    return result
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description="KAMIS 농수축산물 가격 조회")
+    parser.add_argument("--product-class", default="01")
+    parser.add_argument("--category", default="100")
+    parser.add_argument("--county")
+    parser.add_argument("--date")
+    parser.add_argument("--convert-kg", default="N")
+    parser.add_argument("--text", action="store_true")
+    parser.add_argument("--dry-run", action="store_true")
+    parser.add_argument("--direct", action="store_true")
+    parser.add_argument("--proxy-base-url", default=os.getenv("KSKILL_PROXY_BASE_URL", DEFAULT_PROXY))
+    parser.add_argument("--secrets-path", default=os.path.expanduser("~/.config/k-skill/secrets.env"))
+    args = parser.parse_args(argv)
+    key = None
+    try:
+        params = query(args)
+    except ValueError as error:
+        print(f"[error] {error}", file=sys.stderr)
+        return 2
+
+    if args.direct:
+        local = secrets(args.secrets_path)
+        key = os.getenv("KSKILL_KAMIS_API_KEY") or local.get("KSKILL_KAMIS_API_KEY")
+        if not key:
+            print("[error] --direct requires KSKILL_KAMIS_API_KEY", file=sys.stderr)
+            return 3
+        assert key is not None
+        params = {**params, "action": "dailyPriceByCategoryList", "p_cert_key": key, "p_cert_id": "TEST"}
+        url = f"{UPSTREAM}?{urllib.parse.urlencode(params)}"
+    else:
+        url = f"{args.proxy_base_url.rstrip('/')}/v1/kamis/food-price/daily-category?{urllib.parse.urlencode(params)}"
+
+    if args.dry_run:
+        display_params = {**params}
+        if args.direct:
+            display_params["p_cert_key"] = "<redacted>"
+        display_url = url.replace(key, "<redacted>") if args.direct and key is not None else url
+        print(json.dumps({"url": display_url, "query": display_params}, ensure_ascii=False, indent=2))
+        return 0
+
+    try:
+        with urllib.request.urlopen(urllib.request.Request(url, headers={"accept": "application/json"}), timeout=30) as response:
+            payload = json.loads(response.read())
+    except (OSError, ValueError, urllib.error.HTTPError) as error:
+        print(f"[error] KAMIS request failed: {error}", file=sys.stderr)
+        return 4
+
+    if args.text:
+        items = payload.get("items", payload.get("data", {}).get("item", []))
+        for item in items:
+            print(f"{item.get('item_name', '?')} {item.get('kind_name', '')} {item.get('dpr1', '-')}{item.get('unit', '')}")
+    else:
+        print(json.dumps(payload, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/kamis-food-price/skill.json

@@ -0,0 +1,9 @@
+{
+  "name": "kamis-food-price",
+  "description": "KAMIS 농수축산물 유통 Open API를 k-skill-proxy 경유로 호출해 부류별 도소매 가격과 전일·주간·월간·연간 비교값을 조회한다. 조회 전용.",
+  "profiles": [
+    "proxy",
+    "lookup"
+  ],
+  "frontmatter": "name: kamis-food-price\ndescription: KAMIS 농수축산물 유통 Open API를 k-skill-proxy 경유로 호출해 부류별 도소매 가격과 전일·주간·월간·연간 비교값을 조회한다. 조회 전용.\nlicense: MIT\nmetadata:\n  category: food\n  locale: ko-KR\n  phase: v1"
+}

package/skills/korean-cinema-search/instruction.md

@@ -136,6 +136,12 @@ CGV는 시간표 중심으로 본다.
 npx --yes daiso get /api/cgv/timetable --keyword 강남 --playDate <YYYYMMDD> --json
 ```
 
+CGV 공개 endpoint가 `503 CGV_UPSTREAM_UNAVAILABLE`을 반환하면 CGV 공식 웹사이트
+(`https://www.cgv.co.kr`)를 브라우저 사용 스킬로 대체 조회한다. 이때도 공개 상영정보
+조회만 수행하고, 로그인·예매·결제는 진행하지 않는다. 공식 웹사이트에서 비정상 접속
+차단, CAPTCHA, 브라우저 검증 또는 유사한 접근 제한이 표시되면 이를 우회하지 말고
+CGV 조회를 중단한다.
+
 메가박스와 롯데시네마는 잔여석 endpoint를 사용할 수 있다.
 
 ```bash
@@ -165,7 +171,7 @@ npx --yes daiso get /api/lottecinema/seats --keyword 월드타워 --playDate <YY
 
 ## Failure modes
 
-- public endpoint는 upstream 상태에 따라 간헐적인 5xx를 줄 수 있다.
+- CGV 공개 endpoint가 CGV 원본 서비스의 봇 차단·접속 제한을 받으면 `503 CGV_UPSTREAM_UNAVAILABLE`을 반환할 수 있다. 이 응답은 skill 또는 CLI 입력 오류가 아니라 upstream 접근 실패이므로 CGV 공식 웹사이트를 브라우저 사용 스킬로 대체 조회한다. 공식 웹사이트에서도 차단, CAPTCHA, 브라우저 검증 또는 유사한 접근 제한이 표시되면 우회하지 말고 중단한다.
 - 지역 키워드가 넓으면 다른 지점이 섞일 수 있다.
 - 시간표와 잔여석은 시점에 따라 달라진다.
 - 일부 체인은 상영작, 시간표, 잔여석 endpoint의 입력값이 다르므로 theaterId, movieId가 있으면 그 값을 우선 사용한다.

package/skills/market-kurly-search/instruction.md

@@ -27,7 +27,15 @@
 
 - 인터넷 연결
 - `node` 18+
-- 이 저장소의 `market-kurly-search` package 또는 동일 로직
+- `market-kurly-search` npm package
+
+설치:
+
+```bash
+npm install market-kurly-search
+```
+
+이 저장소에서 개발할 때는 루트에서 `npm install` 후 `packages/market-kurly-search`를 쓴다.
 
 ## Required inputs
 

package/skills/mofa-travel-safety/instruction.md

@@ -0,0 +1,62 @@
+# 외교부 해외안전·여행경보 조회
+
+## What this skill does
+
+외교부 `국가·지역별 여행경보 목록 조회(0404 대륙정보)` API를
+`k-skill-proxy`의 좁은 read-only route로 조회한다. 국가명 또는 ISO 2자리
+코드로 공식 여행경보 단계, 지역 유형, 경보 내용, 작성일과 공식 지도 URL을
+확인한다.
+
+이 skill은 자체적인 안전/위험 점수나 여행 허가 판단을 만들지 않는다.
+응답된 외교부 공식 경보와 원문 링크를 사실 그대로 요약한다.
+
+## Inputs
+
+- `country_iso_alp2`: ISO 2자리 국가코드(예: `RU`)
+- `country_nm`: 한글 국가명(예: `러시아`)
+- `page`: 기본 `1`
+- `perPage`: 기본 `10`, 최대 `100`
+
+국가명과 ISO 코드는 동시에 주지 않는다.
+
+## Workflow
+
+```bash
+BASE="${KSKILL_PROXY_BASE_URL:-https://k-skill-proxy.nomadamas.org}"
+curl -fsS --get "$BASE/v1/mofa-travel-safety/travel-alerts" \
+  --data-urlencode "country_iso_alp2=RU" \
+  --data-urlencode "perPage=10"
+```
+
+응답 `items`의 `country_nm`, `country_iso_alp2`, `alarm_lvl`,
+`region_ty`, `remark`, `written_dt`, `dang_map_download_url`을 원문 기준으로
+요약한다. `alarm_lvl` 숫자의 의미는 답변에서 임의로 재분류하지 말고
+외교부 원문/0404 설명을 함께 제시한다.
+
+## Access path and credentials
+
+일반 사용자는 hosted `k-skill-proxy`를 사용하므로 data.go.kr 키가 필요
+없다. proxy 운영자는 승인된 `DATA_GO_KR_API_KEY`를 서버 runtime env에
+보관한다. 키는 URL, 로그, 저장소, 사용자 응답에 노출하지 않는다.
+
+공식 API:
+<https://www.data.go.kr/data/15095500/openapi.do>
+
+실제 upstream:
+`https://apis.data.go.kr/1262000/TravelAlarmService0404/getTravelAlarm0404List`
+
+## Fallback and failure modes
+
+- 먼저 proxy route를 사용하고, 실패하면 공식 data.go.kr API 문서와 0404
+  원문 링크만 안내한다. 임의의 안전 판정을 대신하지 않는다.
+- `400 bad_request`: 잘못된 ISO 코드, 국가명, 페이지 값
+- `503 upstream_not_configured`: proxy runtime에 data.go.kr 키 없음
+- `502 upstream_error`: 외교부/data.go.kr 인증·quota·상류 장애
+- `upstream_invalid_response`: JSON 대신 XML/HTML 오류 응답
+- `items: []`: 해당 조건에 맞는 국가/지역 기록 없음
+
+## Done when
+
+- 국가명 또는 ISO 코드와 조회 시각을 답변에 적었다.
+- `alarm_lvl`, `region_ty`, `remark`를 공식 필드명과 함께 제시했다.
+- 원문 API 문서와 0404 공식 링크를 함께 제공했다.

package/skills/mofa-travel-safety/scripts/run_mofa_travel_safety.py

@@ -0,0 +1,57 @@
+#!/usr/bin/env python3
+"""Read MOFA 0404 travel alerts through the hosted proxy."""
+import argparse
+import json
+import os
+import sys
+import urllib.error
+import urllib.parse
+import urllib.request
+
+DEFAULT_PROXY = "https://k-skill-proxy.nomadamas.org"
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description="외교부 국가별 여행경보 조회")
+    parser.add_argument("--country-iso")
+    parser.add_argument("--country-name")
+    parser.add_argument("--page", type=int, default=1)
+    parser.add_argument("--per-page", type=int, default=10)
+    parser.add_argument("--text", action="store_true")
+    parser.add_argument("--dry-run", action="store_true")
+    parser.add_argument("--proxy-base-url", default=os.getenv("KSKILL_PROXY_BASE_URL", DEFAULT_PROXY))
+    args = parser.parse_args(argv)
+    if args.country_iso and args.country_name:
+        print("[error] use either --country-iso or --country-name", file=sys.stderr)
+        return 2
+    if not 1 <= args.page or not 1 <= args.per_page <= 100:
+        print("[error] invalid page or per-page", file=sys.stderr)
+        return 2
+    params = {"page": args.page, "perPage": args.per_page}
+    if args.country_iso:
+        if len(args.country_iso) != 2 or not args.country_iso.isalpha():
+            print("[error] --country-iso must be two letters", file=sys.stderr)
+            return 2
+        params["country_iso_alp2"] = args.country_iso.upper()
+    if args.country_name:
+        params["country_nm"] = args.country_name
+    url = f"{args.proxy_base_url.rstrip('/')}/v1/mofa-travel-safety/travel-alerts?{urllib.parse.urlencode(params)}"
+    if args.dry_run:
+        print(json.dumps({"url": url, "query": params}, ensure_ascii=False, indent=2))
+        return 0
+    try:
+        with urllib.request.urlopen(urllib.request.Request(url, headers={"accept": "application/json"}), timeout=30) as response:
+            payload = json.loads(response.read())
+    except (OSError, ValueError, urllib.error.HTTPError) as error:
+        print(f"[error] MOFA request failed: {error}", file=sys.stderr)
+        return 3
+    if args.text:
+        for item in payload.get("items", []):
+            print(f"{item.get('country_nm')} ({item.get('country_iso_alp2')}): level={item.get('alarm_lvl')} region={item.get('region_ty')}")
+    else:
+        print(json.dumps(payload, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/mofa-travel-safety/skill.json

@@ -0,0 +1,9 @@
+{
+  "name": "mofa-travel-safety",
+  "description": "외교부 0404 국가·지역별 여행경보 Open API를 k-skill-proxy 경유로 조회해 국가별 공식 경보 단계와 원문 정보를 제공한다. 조회 전용.",
+  "profiles": [
+    "proxy",
+    "lookup"
+  ],
+  "frontmatter": "name: mofa-travel-safety\ndescription: 외교부 0404 국가·지역별 여행경보 Open API를 k-skill-proxy 경유로 조회해 국가별 공식 경보 단계와 원문 정보를 제공한다. 조회 전용.\nlicense: MIT\nmetadata:\n  category: travel\n  locale: ko-KR\n  phase: v1"
+}

package/skills/nts-tax-delinquency/instruction.md

@@ -47,7 +47,8 @@ npx -y @nomadamas/k-skill@0 exec nts-tax-delinquency scripts/nts_tax_delinquency
 ## Failure modes
 
 - `unavailable` + 안내: 상호 미입력, 네트워크 오류, 페이지 구조 변경 추정 — 수동 확인 URL 제공.
-- 0건: 두 명단 모두 매치 없음 (`match_count: 0`).
+- `coverage`: 조회한 공개 명단 범위, 상호·법인명 문자열 대조 기준, 제외 범위, 0건의 의미, 조회시각(`checked_at`)을 구조화해 제공한다.
+- 0건: 두 명단 모두 공개 명단에서 문자열 매치가 없음 (`match_count: 0`). 모든 국세 체납이 없다는 뜻은 아니다.
 
 ## Official surfaces
 

package/skills/nts-tax-delinquency/scripts/nts_tax_delinquency.py

@@ -36,6 +36,18 @@ INDIV_COLUMNS = ("no", "공개년도", "성명", "연령", "상호", "직업(업
 IDENTITY_NOTE = ("명단공개 자료에는 사업자등록번호가 수록되지 않아 입력 사업자번호와의 "
                  "동일성은 확인할 수 없다 — 상호·법인명 문자열 일치 후보의 공개 사실만 "
                  "나열하며, 동명 상호일 가능성은 사용자가 판단한다.")
+COVERAGE = {
+    "scope": "nts-high-amount-habitual-delinquent-disclosure",
+    "match_basis": "corporate-name-and-trade-name-string-match",
+    "exclusions": [
+        "명단공개 기준에 들지 않는 체납 및 비공개 체납",
+        "사업자등록번호 동일성 확인",
+    ],
+    "zero_result_meaning": (
+        "조회한 국세청 고액·상습체납자 공개 명단에서 법인명·상호 문자열 일치가 없다는 뜻이며, "
+        "모든 국세 체납이 없다는 뜻은 아니다."
+    ),
+}
 
 _HEADING_MARKER = "고액상습체납자"
 _ZERO_MARKER = "조회된 데이터가 없습니다"
@@ -50,13 +62,15 @@ def _now_iso() -> str:
 
 
 def _envelope(status: str, *, result: dict | None = None, note: str | None = None) -> dict:
+    looked_up_at = _now_iso()
     return {
         "source": SOURCE,
-        "looked_up_at": _now_iso(),
+        "looked_up_at": looked_up_at,
         "status": status,
         "result": result,
         "origin": "unauthenticated-public",
         "note": note,
+        "coverage": {**COVERAGE, "checked_at": looked_up_at} if status == "ok" else None,
     }
 
 

package/skills/nts-tax-delinquency/scripts/test_nts_tax_delinquency.py

@@ -0,0 +1,32 @@
+import unittest
+from unittest.mock import patch
+
+import nts_tax_delinquency as subject
+
+
+class CoverageTest(unittest.TestCase):
+    def test_zero_result_explains_disclosure_scope(self):
+        with patch.object(subject, "_search", side_effect=[[], []]):
+            response = subject.lookup("테스트상사")
+
+        self.assertEqual(response["status"], "ok")
+        self.assertEqual(response["result"]["corporate_list"]["match_count"], 0)
+        self.assertEqual(response["result"]["individual_list"]["match_count"], 0)
+        self.assertEqual(response["coverage"]["match_basis"], "corporate-name-and-trade-name-string-match")
+        self.assertTrue(response["coverage"]["zero_result_meaning"])
+        self.assertTrue(response["coverage"]["checked_at"])
+
+    def test_matched_result_keeps_same_coverage_contract(self):
+        corporate = [{"법인명": "테스트상사", "총체납액": "1억원"}]
+        individual = [{"상호": "테스트상사", "총체납액": "2억원"}]
+        with patch.object(subject, "_search", side_effect=[corporate, individual]):
+            response = subject.lookup("테스트상사")
+
+        self.assertEqual(response["result"]["corporate_list"]["matches"], corporate)
+        self.assertEqual(response["result"]["individual_list"]["matches"], individual)
+        self.assertEqual(response["coverage"]["scope"], "nts-high-amount-habitual-delinquent-disclosure")
+        self.assertIn("사업자등록번호 동일성 확인", response["coverage"]["exclusions"])
+
+
+if __name__ == "__main__":
+    unittest.main()

package/skills/seoul-weather-risk/instruction.md

@@ -51,6 +51,8 @@ npx -y @nomadamas/k-skill@0 exec seoul-weather-risk scripts/seoul_weather_risk.p
 
 `--filter`가 필요하거나 게시 계약을 점검해야 할 때는 `--fast`를 빼고 full-contract query를 사용한다. fast query가 `product_not_ready` 또는 계약 오류를 반환하면 fixture나 추정값으로 대체하지 말고 아래 진단 흐름을 수행한다.
 
+`--from`/`--to`에 날짜만 넣으면 그날 `00:00:00`–`23:59:59`로 확장한다. ASK 서울 serving window가 자정부터 열려 있지 않아 `422 query_window_unavailable`이 오면 helper는 요청 구간과 `available_from_at`/`available_to_at`의 교집합으로 한 번만 재시도한다. 교집합이 없으면 그 에러의 available window를 보여주고 중단한다. 없는 시간대를 추정 데이터로 채우지 않는다.
+
 ### Contract diagnostics (only when needed)
 
 1. 환경 설정만 확인한다. 이 명령은 네트워크를 호출하지 않는다.
@@ -99,6 +101,7 @@ npx -y @nomadamas/k-skill@0 exec seoul-weather-risk scripts/seoul_weather_risk.p
 - `location_mapping_invalid`: bundled 행정동 reference의 버전·스키마·행 수 계약 오류
 - `proxy_disabled`, `invalid_proxy_base_url`: proxy 환경 설정 오류
 - `unauthorized`/`api_key_missing`(401), `forbidden`/`api_key_forbidden`(403), `unknown_product`(404)
-- `cursor_expired`(409), `rate_limited`(429), `product_not_ready`(503)
+- `cursor_expired`(409), `query_window_unavailable`(422), `rate_limited`(429), `product_not_ready`(503)
+- `query_window_unavailable`: 요청한 `--from`/`--to`가 현재 제공 가능한 예보 window와 겹치지 않음. `details.available_from_at`/`available_to_at`를 확인한다. 겹치는 구간이면 helper가 이미 한 번 재시도한 뒤의 결과다.
 - `upstream_not_configured`(503): proxy 운영 환경에 ASK Seoul 전용 서비스 키 또는 origin이 설정되지 않음
 - `response_contract_invalid`, `malformed_response`: 단일 제품 계약 또는 API 응답 계약 drift

package/skills/seoul-weather-risk/scripts/seoul_weather_risk.py

@@ -33,9 +33,18 @@ STATUS_CODES = {
     403: "forbidden",
     404: "unknown_product",
     409: "cursor_expired",
+    422: "query_window_unavailable",
     429: "rate_limited",
     503: "product_not_ready",
 }
+WINDOW_INSTANT_LENGTH = len("YYYY-MM-DD HH:MM:SS")
+QUERY_WINDOW_DETAIL_FIELDS = (
+    "requested_from_at",
+    "requested_to_at",
+    "available_from_at",
+    "available_to_at",
+    "publication_id",
+)
 
 
 class SkillError(RuntimeError):
@@ -89,13 +98,20 @@ def _error_payload(raw: bytes) -> dict[str, Any]:
 def _problem_error(status: int, raw: bytes, headers: Any) -> SkillError:
     problem = _error_payload(raw)
     code = problem.get("code") if isinstance(problem.get("code"), str) else STATUS_CODES.get(status, "api_error")
-    message = problem.get("detail") if isinstance(problem.get("detail"), str) else problem.get("title")
+    raw_detail = problem.get("detail")
+    message = raw_detail if isinstance(raw_detail, str) else problem.get("title")
     if not isinstance(message, str) or not message:
         message = f"ASK Seoul API가 HTTP {status} 응답을 반환했습니다."
-    details = {"status": status}
+    details: dict[str, Any] = {"status": status}
     for name in ("type", "title", "product_id", "blockers", "request_id"):
         if name in problem:
             details[name] = problem[name]
+    if isinstance(raw_detail, dict):
+        details["detail"] = raw_detail
+        for name in QUERY_WINDOW_DETAIL_FIELDS:
+            value = raw_detail.get(name)
+            if isinstance(value, str) and value:
+                details[name] = value
     retry_after = headers.get("Retry-After") if headers else None
     if retry_after:
         details["retry_after"] = retry_after
@@ -238,6 +254,72 @@ def _time_bound(value: str, edge: str) -> str:
     return value
 
 
+def _window_sort_key(value: str) -> str | None:
+    text = " ".join(value.strip().replace("T", " ", 1).split())
+    if len(text) < WINDOW_INSTANT_LENGTH:
+        return None
+    key = text[:WINDOW_INSTANT_LENGTH]
+    if (
+        key[4] == "-"
+        and key[7] == "-"
+        and key[10] == " "
+        and key[13] == ":"
+        and key[16] == ":"
+        and key[:4].isdigit()
+        and key[5:7].isdigit()
+        and key[8:10].isdigit()
+        and key[11:13].isdigit()
+        and key[14:16].isdigit()
+        and key[17:19].isdigit()
+    ):
+        return key
+    return None
+
+
+def _intersect_query_window(
+    requested_from: str,
+    requested_to: str,
+    available_from: str,
+    available_to: str,
+) -> tuple[str, str] | None:
+    req_from = _window_sort_key(requested_from)
+    req_to = _window_sort_key(requested_to)
+    avail_from = _window_sort_key(available_from)
+    avail_to = _window_sort_key(available_to)
+    if req_from is None or req_to is None or avail_from is None or avail_to is None:
+        return None
+    clipped_from = max(req_from, avail_from)
+    clipped_to = min(req_to, avail_to)
+    if clipped_from > clipped_to:
+        return None
+    return clipped_from, clipped_to
+
+
+def _query_window_bounds(query: dict[str, str], error: SkillError) -> tuple[str, str, str, str] | None:
+    if error.details.get("status") != 422:
+        return None
+    available_from = error.details.get("available_from_at")
+    available_to = error.details.get("available_to_at")
+    requested_from = error.details.get("requested_from_at") or query.get("from")
+    requested_to = error.details.get("requested_to_at") or query.get("to")
+    if not all(isinstance(value, str) and value for value in (requested_from, requested_to, available_from, available_to)):
+        return None
+    return requested_from, requested_to, available_from, available_to
+
+
+def _retry_query_after_unavailable_window(query: dict[str, str], error: SkillError) -> dict[str, str] | None:
+    bounds = _query_window_bounds(query, error)
+    if bounds is None or query.get("cursor"):
+        return None
+    clipped = _intersect_query_window(*bounds)
+    if clipped is None:
+        return None
+    clipped_from, clipped_to = clipped
+    if query.get("from") == clipped_from and query.get("to") == clipped_to:
+        return None
+    return {**query, "from": clipped_from, "to": clipped_to}
+
+
 def _normalize_location_name(value: str) -> str:
     return " ".join(unicodedata.normalize("NFC", value).strip().split())
 
@@ -358,7 +440,21 @@ def _detail(config: ApiConfig, product_id: str) -> dict[str, Any]:
 
 def _data(config: ApiConfig, product_id: str, query: dict[str, str], limit: int) -> dict[str, Any]:
     _validate_product_id(product_id)
-    return _validate_data(_request_json(config, f"{PROXY_ROUTE_ROOT}/data", query), product_id, limit)
+    try:
+        payload = _request_json(config, f"{PROXY_ROUTE_ROOT}/data", query)
+    except SkillError as exc:
+        retry_query = _retry_query_after_unavailable_window(query, exc)
+        if retry_query is None:
+            bounds = _query_window_bounds(query, exc)
+            if bounds is not None and _intersect_query_window(*bounds) is None:
+                raise SkillError(
+                    "query_window_unavailable",
+                    "요청한 조회 구간이 현재 제공 가능한 예보 window와 겹치지 않습니다.",
+                    exc.details,
+                ) from exc
+            raise
+        payload = _request_json(config, f"{PROXY_ROUTE_ROOT}/data", retry_query)
+    return _validate_data(payload, product_id, limit)
 
 
 def _parser() -> argparse.ArgumentParser:

package/templates/browser.md

@@ -1,4 +1,4 @@
 <!-- mode:dolshoi -->
 - Use the built-in browser tool backed by CloakBrowser first. Fall back to `k-skill-browser-runtime` providers only when CloakBrowser is unavailable.
 <!-- mode:generic -->
-- Use `k-skill-browser-runtime` (provider `auto`: BrowserOS CDP, then Aside CLI, then user-launched Chrome CDP) for logged-in or rendered-page automation. Do not launch or close the user's browser, and never solve CAPTCHA, identity proofing, or e-signature flows.
+- Use `k-skill-browser-runtime` (provider `auto`) for logged-in or rendered-page automation. On macOS it tries Aside Browser first, then BrowserOS CDP, then user-launched Chrome/Chromium CDP; on other platforms it tries BrowserOS CDP, then Aside Browser, then user-launched Chrome/Chromium CDP. Do not launch or close the user's browser, and never solve CAPTCHA, identity proofing, or e-signature flows.