@nomadamas/k-skill 0.2.5 → 0.4.0

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

@@ -2,7 +2,7 @@
 
 ## What this skill does
 
-서울 행정동 이름을 정규 `place_id`로 해석해 ASK 서울의 장소별 기상 위험 예상 시간대 단일 제품(`weather_place_risk_window`)을 읽기 전용으로 탐색한다. 기본 helper는 hosted `k-skill-proxy`를 호출하며, 사용자 API Key를 발급받거나 저장하지 않는다. 등록 전 로컬 검증에는 명시적으로 opt-in한 local-direct 경로를 사용할 수 있다. 실패 또는 미준비 상태를 fixture나 추정값으로 대체하지 않는다.
+서울 행정동 이름을 정규 `place_id`로 해석해 ASK 서울의 장소별 기상 위험 예상 시간대 단일 제품(`weather_place_risk_window`)을 읽기 전용으로 탐색한다. 기본 helper는 hosted `k-skill-proxy`만 호출하며, 사용자 API Key나 현재 작업 폴더의 `.env`를 읽지 않는다. 실패 또는 미준비 상태를 fixture나 추정값으로 대체하지 않는다.
 
 ## Product
 
@@ -26,58 +26,52 @@
 
 ## Workflow
 
-1. 환경 설정만 먼저 확인한다. 이 명령은 네트워크를 호출하지 않는다.
+### Standard user query (fast path)
 
-```bash
-npx -y @nomadamas/k-skill@0 exec seoul-weather-risk scripts/seoul_weather_risk.py -- preflight
-```
-
-2. bundle에서 이 제품의 준비 상태를 확인한다.
-
-```bash
-npx -y @nomadamas/k-skill@0 exec seoul-weather-risk scripts/seoul_weather_risk.py -- catalog
-```
-
-3. 제품의 grain, 기본키, 시간축, 공개 column 및 증거 metadata를 확인한다.
-
-```bash
-npx -y @nomadamas/k-skill@0 exec seoul-weather-risk scripts/seoul_weather_risk.py -- describe --product-id weather_place_risk_window
-```
-
-4. 행정동 이름과 `1..500` 범위의 limit으로 data page를 조회한다.
+사용자가 오늘 위험 시간대를 묻는 기본 경로는 `query --fast` 한 번만 실행한다. 이 경로는 bundled 행정동 매핑과 날짜·limit 검증을 유지하면서 hosted data route만 한 번 호출하므로 bundle·product metadata 왕복을 생략한다. `--fast`에서는 `--filter`를 사용하지 않고 `--admin-dong`, `--gu`, 날짜, `--limit`, `--cursor`만 사용한다.
 
 ```bash
-npx -y @nomadamas/k-skill@0 exec seoul-weather-risk scripts/seoul_weather_risk.py -- query \
+npx -y @nomadamas/k-skill@0 exec seoul-weather-risk scripts/seoul_weather_risk.py -- query --fast \
   --product-id weather_place_risk_window \
   --admin-dong 잠실본동 \
-  --from 2026-08-01 \
-  --to 2026-08-07 \
+  --from 2026-08-12 \
+  --to 2026-08-12 \
   --limit 100
 ```
 
-동명이명인 `신사동`은 자치구를 확인한 뒤 다음처럼 조회한다.
+동명이명인 `신사동`은 자치구를 확인한 뒤 fast path에도 `--gu`를 함께 전달한다.
 
 ```bash
-npx -y @nomadamas/k-skill@0 exec seoul-weather-risk scripts/seoul_weather_risk.py -- query \
+npx -y @nomadamas/k-skill@0 exec seoul-weather-risk scripts/seoul_weather_risk.py -- query --fast \
   --product-id weather_place_risk_window \
   --admin-dong 신사동 \
   --gu 강남구 \
   --limit 100
 ```
 
-응답의 `registration_ready`, `publication_id`, `blockers`를 먼저 확인한다. data 응답의 `next_cursor`는 같은 제품의 다음 page에만 그대로 재사용한다. publication이 바뀌면 cursor는 `409`로 만료된다.
+`--filter`가 필요하거나 게시 계약을 점검해야 할 때는 `--fast`를 빼고 full-contract query를 사용한다. fast query가 `product_not_ready` 또는 계약 오류를 반환하면 fixture나 추정값으로 대체하지 말고 아래 진단 흐름을 수행한다.
+
+### Contract diagnostics (only when needed)
 
-## Local pre-registration fallback
+1. 환경 설정만 확인한다. 이 명령은 네트워크를 호출하지 않는다.
+
+```bash
+npx -y @nomadamas/k-skill@0 exec seoul-weather-risk scripts/seoul_weather_risk.py -- preflight
+```
 
-hosted proxy가 아직 등록·배포되지 않은 상태에서 로컬 검증이 필요할 때만, **현재 작업 디렉터리**의 `.env`에 다음 세 이름을 설정한다.
+2. bundle에서 이 제품의 준비 상태를 확인한다.
 
-```text
-KSKILL_LOCAL_DIRECT=1
-ASK_SEOUL_SKILL_API_BASE_URL=https://ask-seoul.kr
-MARKETPLACE_API_KEY=<기존 로컬 Marketplace 키>
+```bash
+npx -y @nomadamas/k-skill@0 exec seoul-weather-risk scripts/seoul_weather_risk.py -- catalog
+```
+
+3. 제품의 grain, 기본키, 시간축, 공개 column 및 증거 metadata를 확인한다.
+
+```bash
+npx -y @nomadamas/k-skill@0 exec seoul-weather-risk scripts/seoul_weather_risk.py -- describe --product-id weather_place_risk_window
 ```
 
-이 opt-in 모드에서는 helper가 `.env`에서 세 이름만 메모리로 읽고 `Authorization: Bearer`로 전달한다. bundle, 단일 `weather_place_risk_window` product, 그 data의 직접 경로 이외에는 호출하지 않는다. 키 값은 명령행 인수·출력·로그·skill 파일에 넣지 않는다. `KSKILL_LOCAL_DIRECT`가 없으면 기존 hosted-proxy 경로를 그대로 사용한다.
+진단 응답의 `registration_ready`, `publication_id`, `blockers`를 확인한다. fast/full data 응답의 `next_cursor`는 같은 제품의 다음 page에만 그대로 재사용하며 publication이 바뀌면 cursor는 `409`로 만료된다.
 
 ## Boundaries
 
@@ -85,9 +79,9 @@ MARKETPLACE_API_KEY=<기존 로컬 Marketplace 키>
 - 알 수 없는 제품이나 필터를 추측해 보정하지 않는다.
 - 행정동 이름을 fuzzy match하거나 모호한 후보 중 하나로 임의 선택하지 않는다. 생활권·통칭 또는 부분 이름(예: `성수동`)도 행정동으로 추측하지 않는다. helper는 로컬 reference에서 `place_id`를 해석하고 proxy에는 행정동·자치구 문자열을 보내지 않는다.
 - 기본 proxy origin은 `https://k-skill-proxy.nomadamas.org`이다. 별도 self-host proxy를 쓸 때만 `KSKILL_PROXY_BASE_URL`을 HTTPS origin으로 설정한다. 값은 명령행 인수, 문서, 로그에 넣지 않는다.
-- hosted-proxy 모드에서는 사용자 API Key와 `Authorization` 헤더를 사용하지 않는다. ASK Seoul 전용 서비스 키는 proxy 운영 환경에만 두며, Marketplace의 `k-skill-proxy:seoul-weather-risk` principal에 `skill:seoul-weather-risk:read` scope로 등록한다. 이 scope는 bundle·product·data 읽기만 허용하고 다른 Marketplace API를 거부한다. local-direct 모드에서만 현재 작업 폴더 `.env`의 `MARKETPLACE_API_KEY`를 세 direct read 경로에 전달하며, 어떤 모드에서도 키를 출력·로그·skill 파일에 넣지 않는다.
+- hosted-proxy 모드에서는 사용자 API Key와 `Authorization` 헤더를 사용하지 않는다. ASK Seoul 전용 서비스 키는 proxy 운영 환경에만 두며, Marketplace의 `k-skill-proxy:seoul-weather-risk` principal에 `skill:seoul-weather-risk:read` scope로 등록한다. 이 scope는 bundle·product·data 읽기만 허용하고 다른 Marketplace API를 거부한다. 어떤 모드에서도 키를 출력·로그·skill 파일에 넣지 않는다.
 - proxy는 bundle, 단일 product, 그 data 조회만 노출한다. `table name`, SQL, join, sort, aggregate 및 비허용 query field는 upstream으로 전달하지 않는다.
-- `/skill/v1/bundles/seoul-weather-risk`의 제품 집합이 `weather_place_risk_window` 단일 제품과 다르면 응답 계약 오류로 중단한다.
+- `/v1/ask-seoul/weather-risk/bundle`의 제품 집합이 `weather_place_risk_window` 단일 제품과 다르면 응답 계약 오류로 중단한다.
 - live 실패를 fixture나 synthetic 결과로 대체하지 않는다.
 - 이 제품은 예보값 임계치 기반 참고 정보이며 기상청 공식 특보를 대체하지 않는다는 점을 응답에서 명확히 한다.
 
@@ -104,7 +98,6 @@ MARKETPLACE_API_KEY=<기존 로컬 Marketplace 키>
 - `ambiguous_admin_dong`: 동명이거나 별칭 후보가 충돌해 `--gu`가 필요함. `details.candidates`에서 가능한 자치구를 확인한다.
 - `location_mapping_invalid`: bundled 행정동 reference의 버전·스키마·행 수 계약 오류
 - `proxy_disabled`, `invalid_proxy_base_url`: proxy 환경 설정 오류
-- `local_direct_not_configured`, `invalid_local_direct_base_url`: local-direct 환경 설정 오류
 - `unauthorized`/`api_key_missing`(401), `forbidden`/`api_key_forbidden`(403), `unknown_product`(404)
 - `cursor_expired`(409), `rate_limited`(429), `product_not_ready`(503)
 - `upstream_not_configured`(503): proxy 운영 환경에 ASK Seoul 전용 서비스 키 또는 origin이 설정되지 않음

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

@@ -20,16 +20,7 @@ from urllib.request import HTTPRedirectHandler, Request, build_opener
 SKILL_BUNDLE_ID = "seoul-weather-risk"
 PROXY_BASE_URL_ENV = "KSKILL_PROXY_BASE_URL"
 DEFAULT_PROXY_BASE_URL = "https://k-skill-proxy.nomadamas.org"
-LOCAL_DIRECT_ENV = "KSKILL_LOCAL_DIRECT"
-SKILL_API_BASE_URL_ENV = "ASK_SEOUL_SKILL_API_BASE_URL"
-MARKETPLACE_API_KEY_ENV = "MARKETPLACE_API_KEY"
 PROXY_DISABLED_VALUES = frozenset({"off", "false", "0", "disable", "disabled", "none"})
-LOCAL_DIRECT_ENABLED_VALUES = frozenset({"1", "true", "on", "yes"})
-LOCAL_DIRECT_DOTENV_NAMES = frozenset({
-    LOCAL_DIRECT_ENV,
-    SKILL_API_BASE_URL_ENV,
-    MARKETPLACE_API_KEY_ENV,
-})
 PROXY_ROUTE_ROOT = "/v1/ask-seoul/weather-risk"
 LOCATION_MAPPING_PATH = pathlib.Path(__file__).resolve().parents[1] / "references" / "admin-dong-place-map.json"
 LOCATION_MAPPING_VERSION = "kma_admin_dong_grid_20260325"
@@ -65,54 +56,14 @@ class _NoRedirect(HTTPRedirectHandler):
 @dataclass(frozen=True)
 class ApiConfig:
     base_url: str
-    mode: str = "hosted_proxy"
-    bearer_token: str | None = None
 
 
 def _json(value: Any) -> str:
     return json.dumps(value, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
 
 
-def _local_direct_config(values: dict[str, str]) -> ApiConfig:
-    base_url = values.get(SKILL_API_BASE_URL_ENV, "").strip()
-    bearer_token = values.get(MARKETPLACE_API_KEY_ENV, "").strip()
-    if not base_url or base_url == "replace-me":
-        raise SkillError("local_direct_not_configured", "local direct API base URL이 필요합니다.")
-    if not bearer_token or bearer_token == "replace-me":
-        raise SkillError("local_direct_not_configured", "local direct Marketplace API key가 필요합니다.")
-
-    parsed = urlparse(base_url)
-    local_http = parsed.scheme == "http" and parsed.hostname in {"127.0.0.1", "localhost", "::1"}
-    if (parsed.scheme != "https" and not local_http) or not parsed.netloc or parsed.path not in {"", "/"} or parsed.query or parsed.fragment:
-        raise SkillError("invalid_local_direct_base_url", "local direct API base URL은 HTTPS origin이어야 합니다.")
-    if parsed.username or parsed.password:
-        raise SkillError("invalid_local_direct_base_url", "local direct API base URL에 사용자 정보는 포함할 수 없습니다.")
-    return ApiConfig(base_url=base_url.rstrip("/"), mode="local_direct", bearer_token=bearer_token)
-
-
-def _current_directory_dotenv() -> dict[str, str]:
-    path = pathlib.Path.cwd() / ".env"
-    try:
-        lines = path.read_text(encoding="utf-8").splitlines()
-    except OSError:
-        return {}
-
-    values: dict[str, str] = {}
-    for line in lines:
-        stripped = line.strip()
-        if not stripped or stripped.startswith("#") or "=" not in stripped:
-            continue
-        name, value = stripped.split("=", 1)
-        name = name.strip()
-        if name in LOCAL_DIRECT_DOTENV_NAMES:
-            values[name] = value.strip().strip('"').strip("'")
-    return values
-
-
 def _api_config(environ: dict[str, str] | None = None) -> ApiConfig:
-    values = ({**_current_directory_dotenv(), **os.environ} if environ is None else environ)
-    if values.get(LOCAL_DIRECT_ENV, "").strip().casefold() in LOCAL_DIRECT_ENABLED_VALUES:
-        return _local_direct_config(values)
+    values = os.environ if environ is None else environ
     configured = values.get(PROXY_BASE_URL_ENV, "").strip()
     if configured.casefold() in PROXY_DISABLED_VALUES:
         raise SkillError("proxy_disabled", f"{PROXY_BASE_URL_ENV}가 비활성화되어 있습니다.")
@@ -159,8 +110,6 @@ def _request_json(config: ApiConfig, path: str, query: dict[str, str] | None = N
         "Accept": "application/json",
         "User-Agent": "k-skill-seoul-weather-risk/1",
     }
-    if config.bearer_token:
-        headers["Authorization"] = f"Bearer {config.bearer_token}"
     request = Request(url, headers=headers)
     try:
         with build_opener(_NoRedirect).open(request, timeout=15) as response:
@@ -399,22 +348,16 @@ def _validate_product_id(product_id: str) -> None:
 
 
 def _bundle(config: ApiConfig) -> dict[str, Any]:
-    if config.mode == "local_direct":
-        return _validate_bundle(_request_json(config, f"/skill/v1/bundles/{SKILL_BUNDLE_ID}"))
     return _validate_bundle(_request_json(config, f"{PROXY_ROUTE_ROOT}/bundle"))
 
 
 def _detail(config: ApiConfig, product_id: str) -> dict[str, Any]:
     _validate_product_id(product_id)
-    if config.mode == "local_direct":
-        return _validate_product(_request_json(config, f"/skill/v1/products/{product_id}"), product_id)
     return _validate_product(_request_json(config, f"{PROXY_ROUTE_ROOT}/product"), product_id)
 
 
 def _data(config: ApiConfig, product_id: str, query: dict[str, str], limit: int) -> dict[str, Any]:
     _validate_product_id(product_id)
-    if config.mode == "local_direct":
-        return _validate_data(_request_json(config, f"/skill/v1/products/{product_id}/data", query), product_id, limit)
     return _validate_data(_request_json(config, f"{PROXY_ROUTE_ROOT}/data", query), product_id, limit)
 
 
@@ -428,6 +371,7 @@ def _parser() -> argparse.ArgumentParser:
     describe.add_argument("--product-id", required=True)
 
     query = commands.add_parser("query", help="제품 data page 조회")
+    query.add_argument("--fast", action="store_true", help="bundle/product metadata 확인을 생략하고 data만 조회")
     query.add_argument("--product-id", required=True)
     query.add_argument("--filter", action="append", default=[], metavar="COLUMN=VALUE")
     query.add_argument("--admin-dong", help="서울 행정동 이름")
@@ -446,11 +390,9 @@ def run(argv: list[str]) -> int:
         if args.command == "preflight":
             result = {
                 "status": "ok",
-                "mode": config.mode,
+                "mode": "hosted_proxy",
                 "live_network": False,
-                "user_api_key_required": config.mode == "local_direct",
-                "proxy_base_url_configured": config.mode == "hosted_proxy",
-                "local_direct_base_url_configured": config.mode == "local_direct",
+                "proxy_base_url_configured": True,
             }
         elif args.command == "catalog":
             result = _bundle(config)
@@ -460,8 +402,12 @@ def run(argv: list[str]) -> int:
         else:
             if not 1 <= args.limit <= 500:
                 raise SkillError("invalid_limit", "limit은 1부터 500 사이여야 합니다.")
-            _bundle(config)
-            detail = _detail(config, args.product_id)
+            if args.fast and args.filter:
+                raise SkillError("fast_query_filter_unsupported", "--fast에서는 --filter를 사용할 수 없습니다.")
+            detail: dict[str, Any] | None = None
+            if not args.fast:
+                _bundle(config)
+                detail = _detail(config, args.product_id)
             filters = _filters(args.filter)
             if args.gu is not None and args.admin_dong is None:
                 raise SkillError("invalid_location_input", "--gu는 --admin-dong과 함께 사용해야 합니다.")
@@ -477,10 +423,11 @@ def run(argv: list[str]) -> int:
                     )
                 resolved = _resolve_admin_dong(args.admin_dong, args.gu)
                 filters["place_id"] = resolved["place_id"]
-            allowed_columns = {column["name"] for column in detail["metadata"].get("columns", [])}
-            unknown = sorted(set(filters) - allowed_columns)
-            if unknown:
-                raise SkillError("unknown_filter", f"공개 projection에 없는 필터입니다: {', '.join(unknown)}")
+            if detail is not None:
+                allowed_columns = {column["name"] for column in detail["metadata"].get("columns", [])}
+                unknown = sorted(set(filters) - allowed_columns)
+                if unknown:
+                    raise SkillError("unknown_filter", f"공개 projection에 없는 필터입니다: {', '.join(unknown)}")
             request_query = {**filters, "limit": str(args.limit)}
             if args.from_value is not None:
                 request_query["from"] = _time_bound(args.from_value, "from")

package/skills/seoul-weather-risk/skill.json

@@ -1,9 +1,9 @@
 {
   "name": "seoul-weather-risk",
-  "description": "서울 행정동 이름을 정식명 우선·허용된 결정적 표기 별칭만으로 정규 place_id로 해석해 ASK 서울의 장소별 기상 위험 예상 시간대(weather_place_risk_window) 단일 제품을 hosted k-skill proxy에서 읽기 전용 조회한다. 기본 경로에는 사용자 API Key와 place_id 입력이 필요 없으며, 등록 전에는 명시적으로 local-direct 검증을 할 수 있다.",
+  "description": "서울 행정동 이름을 정식명 우선·허용된 결정적 표기 별칭만으로 정규 place_id로 해석해 ASK 서울의 장소별 기상 위험 예상 시간대(weather_place_risk_window) 단일 제품을 hosted k-skill proxy에서 읽기 전용 조회한다. 사용자 API Key와 place_id 입력은 필요하지 않다.",
   "profiles": [
     "proxy",
     "lookup"
   ],
-  "frontmatter": "name: seoul-weather-risk\ndescription: 서울 행정동 이름을 정식명 우선·허용된 결정적 표기 별칭만으로 정규 place_id로 해석해 ASK 서울의 장소별 기상 위험 예상 시간대(weather_place_risk_window) 단일 제품을 hosted k-skill proxy에서 읽기 전용 조회한다. 기본 경로에는 사용자 API Key와 place_id 입력이 필요 없으며, 등록 전에는 명시적으로 local-direct 검증을 할 수 있다.\nlicense: MIT\nmetadata:\n  category: public-data\n  locale: ko-KR\n  phase: live-client"
+  "frontmatter": "name: seoul-weather-risk\ndescription: 서울 행정동 이름을 정식명 우선·허용된 결정적 표기 별칭만으로 정규 place_id로 해석해 ASK 서울의 장소별 기상 위험 예상 시간대(weather_place_risk_window) 단일 제품을 hosted k-skill proxy에서 읽기 전용 조회한다. 사용자 API Key와 place_id 입력은 필요하지 않다.\nlicense: MIT\nmetadata:\n  category: public-data\n  locale: ko-KR\n  phase: live-client"
 }

package/skills/srt-booking/instruction.md

@@ -1,181 +1,75 @@
-# SRT Booking
+# SRT Live Timetable Lookup
 
 ## What this skill does
 
-`SRTrain` 위에 `scripts/srt_booking.py` helper 를 얹어 SRT 조회와 호차별 좌석번호 확인을 처리하고, 예약과 취소는 고정된 열차/예약을 다시 식별한 뒤 `SRTrain`으로 진행한다.
+`SRTrain`의 시간표 검색 경로를 이용해 현재 SRT 운행 후보와 일반실·특실 예약 가능 여부를 조회한다.
 
-## When to use
+이 스킬은 회원 로그인 불필요한 **라이브 조회 전용**이다.
 
-- "수서에서 부산 가는 SRT 찾아줘"
-- "내일 오전 SRT 빈자리 있으면 잡아줘"
-- "SRT 5호차 빈 좌석 확인해줘"
-- "SRT 11A 좌석이 비었는지 봐줘"
-- "창측 좌석을 우선해서 SRT 빈자리 보여줘"
-- "예약 내역 확인해줘"
-- "이 SRT 예약 취소해줘"
+- `auto_login=False` 익명 client를 사용한다.
+- NetFunnel 대기열과 시간표 검색 요청만 실행한다.
+- 예약, 예약대기, 좌석 선점, 결제, 취소, 자동 재조회는 실행하지 않는다.
+- 정확한 호차·좌석번호를 조회하지 않는다.
+- 구매는 공식 SRT 페이지에서 사용자가 직접 진행한다.
 
-## When not to use
+실행 환경에는 Python 3.11 이상과 `uv`가 필요하다. `uv`가 없으면 공식 설치 문서를 안내하고 조회를 실행하지 않는다.
 
-- 돌쇠가 아니며 결제까지 자동으로 끝내야 하는 경우
-- 비밀번호를 채팅창에 직접 보내려는 경우
-- SRT가 아니라 KTX/Korail 예매인 경우
-
-## Prerequisites
-
-- Python 3.10+
-- `python3 -m pip install SRTrain`
-
-## Required environment variables
-
-- `KSKILL_SRT_ID`
-- `KSKILL_SRT_PASSWORD`
-
-### Credential handling
-
-- 돌쇠 credential mode에서는 `vault-run` capability를 사용하고, 없으면 `request_vault_credential`을 호출한다. ID/PW 원문을 채팅이나 shell에 넣지 않는다.
-- 그 밖의 환경에서는 이미 주입된 환경변수 → host vault → `~/.config/k-skill/secrets.env` 순서로 사용한다.
-
-## Inputs
-
-- 출발역
-- 도착역
-- 날짜: `YYYYMMDD`
-- 희망 시작 시각: `HHMMSS`
-- 인원 수와 승객 유형
-- 좌석 선호: 일반실 / 특실
-- 좌석 상세 조건: 객실 등급, 호차 번호, 좌석 번호, 빈 좌석만 보기, 탐색 우선순위
-
-## Workflow
-
-### 0. Install the package globally when missing
-
-`python3 -c 'import SRT'` 가 실패하면 다른 구현으로 우회하지 말고 전역 Python 패키지 설치를 먼저 시도한다.
-
-```bash
-python3 -m pip install SRTrain
-```
-
-### 1. Ensure credentials are available
-
-돌쇠 credential mode에서는 `vault-run`의 SRT capability를 확인하고, 없으면 `request_vault_credential`로 앱 vault 입력 UI를 호출한다. generic fallback에서만 `KSKILL_SRT_ID`, `KSKILL_SRT_PASSWORD` 환경변수를 확인한다.
-
-시크릿이 없다는 이유로 웹사이트를 직접 긁거나 다른 비공식 경로를 찾지 않는다.
-
-### 2. Search first
-
-먼저 helper 로 조회해서 후보를 요약한다.
-
-```bash
-npx -y @nomadamas/k-skill@0 exec srt-booking scripts/srt_booking.py -- search 수서 부산 20260328 080000 --time-limit 120000 --limit 5
-```
-
-### 3. Summarize options before side effects
-
-예약 전에는 항상 아래를 짧게 정리한다.
-
-- 출발/도착 시각
-- 일반실/특실 가능 여부
-- 예상 운임
-
-### 4. Inspect detailed seats when the user asks for seat numbers
-
-`search` 의 좌석 가능 여부는 열차 단위 플래그다. 사용자가 "남은 좌석 번호", "호차별 좌석", "특정 좌석", "창측/순방향 자리", "예약 전에 자리 확인"처럼 구체적인 좌석을 물으면 예약 전에 `seats` 를 호출한다.
-
-```bash
-npx -y @nomadamas/k-skill@0 exec srt-booking scripts/srt_booking.py -- seats 수서 부산 20260328 080000 --train-id <train_id>
-```
-
-특정 호차의 빈 좌석만 확인하려면 `--car-no` 와 `--available-only` 를 쓴다.
+## Commands
 
 ```bash
-npx -y @nomadamas/k-skill@0 exec srt-booking scripts/srt_booking.py -- seats 수서 부산 20260328 080000 --train-id <train_id> --car-no 5 --available-only
+npx -y @nomadamas/k-skill@0 exec srt-booking scripts/srt_booking.py -- \
+  search \
+  --dep 수서 \
+  --arr 부산 \
+  --date 20260819 \
+  --time 0600 \
+  --time-limit 1200 \
+  --limit 5
 ```
 
-특정 좌석이 비었는지 확인하려면 `--seat` 를 붙인다.
+현재 라이브 조회 endpoint와 안전 경계:
 
 ```bash
-npx -y @nomadamas/k-skill@0 exec srt-booking scripts/srt_booking.py -- seats 수서 부산 20260328 080000 --train-id <train_id> --car-no 5 --seat 11A
+npx -y @nomadamas/k-skill@0 exec srt-booking scripts/srt_booking.py -- source
 ```
 
-특정 호차를 지정하지 않으면 가운데 호차부터 탐색한다. `--car-priority center|low|high` 로 호차 탐색 순서를 바꾸고, `--seat-priority forward-window|window-forward|row-low` 로 좌석 정렬 우선순위를 바꾼다.
-
-상세 좌석 응답을 보여줄 때는 아래를 우선 요약한다.
-
-- 호차별 `available_seat_count`
-- 남은 좌석 번호 (`available_seats`)
-- 좌석별 `direction`, `position`
-- 특정 좌석 요청이면 `requested_seat_available`
-
-이 기능은 좌석을 선택/선점하지 않는다. 실제 예약은 다음 단계에서만 진행한다.
-
-### 5. Reserve only after the train is fixed
+출력:
 
-예약은 부작용이 있으므로 정확한 열차를 고른 뒤에만 진행한다.
+- 열차번호·열차종류
+- 출발역·도착역
+- 현재 출발·도착 시각
+- 일반실·특실 예약 가능 여부
+- 사용한 라이브 search endpoint
+- 공식 SRT 페이지
 
-```bash
-python3 - <<'PY'
-import os
-from SRT import Adult, SRT, SeatType
-
-srt = SRT(os.environ["KSKILL_SRT_ID"], os.environ["KSKILL_SRT_PASSWORD"])
-trains = srt.search_train("수서", "부산", "20260328", "080000", time_limit="120000")
-reservation = srt.reserve(
-    trains[0],
-    passengers=[Adult(1)],
-    special_seat=SeatType.GENERAL_FIRST,
-)
-print(reservation)
-PY
-```
+## Workflow
 
-### 6. Continue to payment in Dolshoi
+1. 출발역, 도착역, 날짜, 시간대를 확인한다.
+2. `search`를 한 번 실행한다. `수서역`처럼 `역`이 붙은 입력은 helper가 표준 역명으로 정규화한다.
+3. 현재 운행 후보를 제시한다.
+4. 좌석 구매가 필요하면 `booking_url`을 제공하고 종료한다.
+5. 사용자가 다시 요청하지 않는 한 polling·매진 감시를 시작하지 않는다.
 
-예약이 성공하면 예약번호, 운임, 구입기한을 즉시 알려서 **좌석 확보는 완료되었다**고 명확히 말한다.
+## Hard boundaries
 
-돌쇠에서 사용자가 예매 완료를 요청했다면 여기서 멈추지 않는다.
+- `KSKILL_SRT_ID`, `KSKILL_SRT_PASSWORD` 또는 회원 로그인을 요구하지 않는다.
+- helper에 `reserve`, `reservations`, `cancel`, `payment`, waiting-list 명령을 추가하지 않는다.
+- 예약 endpoint, 결제 endpoint 또는 계정 endpoint를 호출하지 않는다.
+- NetFunnel key를 예약·선점 자동화에 사용하지 않는다.
+- CAPTCHA·접근 거부·계정 제한이 발생하면 즉시 중단한다.
+- 사용자 요청 한 번을 반복 수집이나 장기 실행으로 확장하지 않는다.
 
-1. CloakBrowser의 공식 SRT 예약/결제 화면에서 방금 만든 예약을 다시 식별한다.
-2. vault-backed login을 사용하고 결제수단/할인/승객/예약 정보를 확인한다.
-3. 실제 결제 버튼 직전에 `clarify`로 열차, 날짜·시각, 승객, 좌석 등급, 총액을 보여주고 승인받는다.
-4. 승인되면 결제를 실행하고 결제 완료 화면, 예약번호, 영수증/결제 상태를 확인한다.
+## Failure modes
 
-돌쇠가 아니거나 공식 결제 표면을 사용할 수 없으면 예약번호와 구입기한을 제공하고 generic handoff로 종료한다.
+- NetFunnel 대기 또는 SRT 접근 제한
+- `SRTrain` 설치·호환성 문제
+- 날짜·시간 또는 역명 오류
+- 조건에 맞는 열차 없음
 
-### 7. Inspect or cancel
+이 경우 차단을 우회하지 않고 [SRT 공식 조회 페이지](https://etk.srail.kr/hpg/hra/01/selectScheduleList.do?pageId=TK0101010000)를 안내한다.
 
-취소 전에는 대상 예약을 다시 식별한다.
+## Legal notice
 
 ```bash
-python3 - <<'PY'
-import os
-from SRT import SRT
-
-srt = SRT(os.environ["KSKILL_SRT_ID"], os.environ["KSKILL_SRT_PASSWORD"])
-reservations = srt.get_reservations()
-print(reservations)
-PY
+npx -y @nomadamas/k-skill@0 read srt-booking references/AUTOMATION-LEGAL-STATEMENT.md
 ```
-
-취소 실행 직전에 `clarify`로 예약번호, 열차, 날짜·시각, 승객, 환불/위약금 정보를 확인하고 승인받는다.
-
-## Done when
-
-- 조회 요청이면 후보 열차가 정리되어 있다
-- 좌석 상세 확인이면 호차별 남은 좌석번호나 특정 좌석 공석 여부가 정리되어 있다
-- 예약 요청이면 예약 결과, 운임, 구입기한이 확인되어 좌석 확보 완료를 안내했다
-- 돌쇠의 예매 완료 요청이면 `clarify` 승인 후 결제 완료 상태와 영수증/예약번호를 확인했다
-- 취소 요청이면 어떤 예약을 취소했는지 명확하다
-
-## Failure modes
-
-- 로그인 오류: 계정 정보나 SRT site policy 변경 가능성 확인
-- 매진: 다른 시간대나 좌석 타입으로 재조회
-- 좌석선택 페이지 형식 변경: helper 파서 업데이트 필요
-- 네트워크 오류: 짧게 재시도하되 aggressive polling은 피하기
-
-## Notes
-
-- 상세 좌석 확인은 SRT 웹 좌석선택 페이지를 조회 전용으로 읽는다
-- `SRTrain`은 SRT 전용 라이브러리라서 스킬 의도가 더 선명하다
-- 결제 자동화 금지는 generic fallback에만 적용한다. 돌쇠에서는 `clarify` 승인 후 공식 결제 표면으로 완료한다
-- 자동 재시도 루프는 계정 보호 차원에서 짧고 보수적으로 유지한다

package/skills/srt-booking/references/AUTOMATION-LEGAL-STATEMENT.md

@@ -0,0 +1,25 @@
+# SRT 라이브 자동조회 관련 고지
+
+> 2026-08-12에 확인한 공개 자료를 바탕으로 한 일반적인 위험 안내이며 법률자문이나 주식회사 에스알의 유권해석이 아니다.
+
+## 결론
+
+이 스킬은 로그인 없이 `SRTrain`의 시간표 검색 endpoint만 호출하고 예약·결제·취소·좌석 선점을 제공하지 않는다. 따라서 기존 자동예매보다 위험은 낮다.
+
+그러나 에스알은 공식 공지에서 매크로 프로그램을 이용한 **승차권 예매**를 금지한다. 조회 전용이라는 사실이 자동 접근에 대한 에스알의 허가를 뜻하지는 않는다.
+
+## 기술적 경계
+
+- `SRT("", "", auto_login=False)` 익명 client
+- NetFunnel 대기열과 `selectListAra10007_n.do` 시간표 검색만 실행
+- 일반실·특실 가능 여부만 조회
+- 예약·예약대기·결제·취소·계정 endpoint 없음
+- 한 사용자 요청에 한 번만 실행하고 polling 없음
+
+## 공식 근거
+
+[매크로 프로그램을 이용한 승차권 예매 금지 안내](https://etk.srail.kr/cms/article/view.do?pageId=TK0502000000&postNo=793)는 매크로를 이용한 예매가 시스템 과부하와 다른 고객의 예매 기회 방해를 초래할 수 있고 적발 시 회원 탈퇴 처리될 수 있다고 안내한다.
+
+[에스알 회원가입 및 이용에 관한 약관](https://etk.srail.kr/cms/archive.do?pageId=TK0503010000) 제10조는 다량 예약 후 임박 취소, 타인 계정 도용과 건전한 서비스 이용 저해를 탈퇴 사유로 규정한다.
+
+NetFunnel 오류, 접근 거부, CAPTCHA 또는 정책 변경이 발생하면 우회하지 않고 즉시 중단한다.

package/skills/srt-booking/references/DISCLAIMER.md

@@ -0,0 +1,13 @@
+# DISCLAIMER — `srt-booking`
+
+이 스킬은 에스알·SRT 또는 철도 운영사의 공식 기능 또는 공식 지원 도구가 아니며, 공식 제휴·후원·승인·인증 또는 협업한 사실이 전혀 없습니다. 상표와 서비스명은 열차·좌석 조회 기능과 대상을 설명하기 위해서만 사용합니다.
+
+대법원 2005. 6. 10. 선고 [2005도1637 판결](https://www.law.go.kr/LSW/precInfoP.do?precSeq=83920)(소니용 리모컨 사건)은 기능 설명용 표장과 출처표시를 구별했습니다. [상표법 제2조](https://www.law.go.kr/법령/상표법/제2조), [제89조](https://www.law.go.kr/법령/상표법/제89조), [제90조](https://www.law.go.kr/법령/상표법/제90조), [제108조](https://www.law.go.kr/법령/상표법/제108조)에 따른 출처 혼동 판단은 별도입니다.
+
+대법원 2022. 5. 12. 선고 [2021도1533 판결](https://www.law.go.kr/LSW/precInfoP.do?precSeq=221765)은 공개정보 수집만으로 곧바로 [정보통신망법 제48조](https://www.law.go.kr/법령/정보통신망이용촉진및정보보호등에관한법률/제48조) 위반이 되는 것은 아닌 사정을 제시했지만, 철도 예매 자동화·접근통제 우회·반복 선점을 허용하지 않습니다. [저작권법 제93조](https://www.law.go.kr/법령/저작권법/제93조)과 [형법 제314조 제2항](https://www.law.go.kr/법령/형법/제314조)은 별도입니다.
+
+- 공개 운행·좌석정보 자동 수집은 반드시 개인의 정보 조회용으로만 사용합니다.
+- 매진 감시, 조직적·대량 크롤링, 반복 선점·예약·취소, 공격적 polling을 하지 않습니다.
+- CAPTCHA·anti-bot·로그인·접근통제·rate limit·IP 차단을 우회하거나 정상 예매 영업을 방해하지 않습니다.
+
+이 문서는 적법성을 보증하는 법률 자문이 아닙니다.