@nomadamas/k-skill 0.4.3 → 0.6.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/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/real-estate-search/instruction.md

@@ -28,9 +28,26 @@
 
 ## Prerequisites
 
-없음. 사용자는 별도 API key를 준비할 필요가 없다. upstream key는 proxy 서버에서만 주입한다.
+없음. 사용자는 별도 API key를 준비할 필요가 없다. 개별 조회의 upstream key는 proxy 서버에서만 주입하며, 전국 일일 보고는 아래 공식 RTMS CSV를 직접 사용한다.
 
-## Default path
+## 전국 일일 보고 — 공식 RTMS CSV 직접 조회
+
+proxy나 ServiceKey 없이 국토교통부 실거래가 자료제공 화면의 실제 CSV 응답을 집계한다.
+
+```bash
+npx -y @nomadamas/k-skill@0 exec real-estate-search scripts/nationwide_daily_report.py -- --as-of YYYY-MM-DD
+```
+
+`--as-of`를 생략하면 KST 오늘을 사용한다. 공식 시·도/시·군·구 목록을 조회한 뒤 아파트·오피스텔·연립다세대·단독다가구의 매매·전월세 8개 조합을 전국 일괄 CSV로 실행한다. 현재 월이 0건이면 직전 월을 한 번 확인한다.
+
+- `success`: CSV를 내려받아 파싱한 조합. 지역별 0건은 `empty`로 집계한다.
+- `empty`: 현재 월과 직전 월의 공식 건수가 모두 0인 조합.
+- `failure`: 네트워크, HTTP, 응답 크기, JSON/CSV 계약 또는 건수 불일치 오류.
+- `unexecuted`: 실행 결과가 없는 조합. 실패나 빈 결과를 이 상태로 바꾸지 않는다.
+
+한 조합이라도 실패하면 보고서는 성공/빈 결과/실패 범위를 모두 출력하고 종료코드 1을 반환한다. 원문 근거는 실제로 접속한 `https://rt.molit.go.kr/pt/xls/xls.do`로 고정한다.
+
+## 개별 조회 기본 경로
 
 추가 client API 레이어는 불필요하다. 그냥 프록시 서버에 HTTP 요청만 넣으면 된다.
 
@@ -156,17 +173,20 @@ curl -fsS --get 'https://k-skill-proxy.nomadamas.org/v1/real-estate/officetel/re
 - 프록시 서버에 `DATA_GO_KR_API_KEY` 가 없으면 503 응답
 - upstream MOLIT API 오류면 502 + `molit_api_XXX` 에러 코드
 - 해당 지역/기간에 데이터가 없으면 빈 `items` 배열 반환
+- 전국 일일 보고의 공식 RTMS 응답이 실패하거나 계약과 다르면 해당 조합을 `failure`로 유지하고 누락 수치나 더미 데이터를 만들지 않는다.
 
 ## Done when
 
 - 요청 자산 타입에 맞는 endpoint를 선택했다.
 - 필요한 경우 `region-code` 로 지역코드를 먼저 확인했다.
 - 실거래가/전월세 결과를 조회하고 요약했다.
+- 전국 일일 보고 요청이면 공식 RTMS CSV helper를 실행하고 success/empty/failure/unexecuted를 구분했다.
 - 원본 데이터 출처(국토교통부 실거래가 신고)를 함께 남겼다.
 
 ## Notes
 
 - 원본 참고: `https://github.com/tae0y/real-estate-mcp/tree/main`
 - 공식 데이터 출처: 공공데이터포털 (`https://www.data.go.kr`)
+- 공식 RTMS CSV 자료제공: `https://rt.molit.go.kr/pt/xls/xls.do`
 - 가격 단위: `price_10k`, `deposit_10k` = 만원 단위 (예: 245000 = 24억 5천만원)
 - 취소된 거래는 서버에서 자동 필터링된다.