@nomadamas/k-skill 0.1.0

package/skills/kstartup-search/scripts/run_kstartup.py

@@ -0,0 +1,424 @@
+#!/usr/bin/env python3
+"""K-Startup (data.go.kr 15125364) CLI helper for the kstartup-search skill.
+
+조회 전용. 일반 호출은 k-skill-proxy 경유, `--direct` 는 사용자 API 키로 직접 호출.
+stdlib only (urllib, json, argparse, ssl).
+"""
+from __future__ import annotations
+
+import argparse
+import datetime
+import json
+import os
+import ssl
+import sys
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Dict, Iterable, List, Optional, Tuple
+
+DEFAULT_PROXY_BASE_URL = "https://k-skill-proxy.nomadamas.org"
+PROXY_DOWN_MSG = "설정된 k-skill-proxy 서버가 응답하지 않습니다. 잠시 후 재시도하거나 운영자에게 문의하세요."
+PROXY_KEY_NOT_CONFIGURED_MSG = "k-skill-proxy에 필요한 API 키가 설정되어 있지 않습니다. 운영자에게 문의하세요."
+KSTARTUP_UPSTREAM_BASE_URL = "https://apis.data.go.kr/B552735/kisedKstartupService01"
+DEFAULT_SECRETS_PATH = os.path.expanduser("~/.config/k-skill/secrets.env")
+
+OPERATIONS: Dict[str, Dict[str, Any]] = {
+    "business-info": {
+        "path": "getBusinessInformation01",
+        "allowed": ("biz_category_cd", "supt_biz_titl_nm", "biz_yr"),
+    },
+    "announcements": {
+        "path": "getAnnouncementInformation01",
+        "allowed": (
+            "intg_pbanc_yn", "intg_pbanc_biz_nm", "biz_pbanc_nm",
+            "supt_biz_clsfc", "aply_trgt_ctnt", "supt_regin",
+            "pbanc_rcpt_bgng_dt", "pbanc_rcpt_end_dt",
+            "aply_trgt", "biz_enyy", "biz_trgt_age", "prfn_matr",
+            "rcrt_prgs_yn",
+        ),
+    },
+    "contents": {
+        "path": "getContentInformation01",
+        "allowed": ("clss_cd", "titl_nm"),
+    },
+    "statistics": {
+        "path": "getStatisticalInformation01",
+        "allowed": ("titl_nm", "file_nm"),
+    },
+}
+
+YN_FIELDS = {"intg_pbanc_yn", "rcrt_prgs_yn"}
+DATE_FIELDS = {"pbanc_rcpt_bgng_dt", "pbanc_rcpt_end_dt"}
+
+# Fields where the K-Startup upstream is observed to ignore the server-side
+# filter and return non-matching rows. SKILL.md L121 promises that the helper
+# re-applies these filters on the client side after receiving the response.
+#
+# - supt_regin: upstream returns mixed regions even when supt_regin is set.
+# - aply_trgt:  upstream returns rows whose aply_trgt does not contain the
+#               requested target (e.g. asking for "예비창업자" returns rows
+#               with only "일반인,일반기업").
+# - biz_enyy:   upstream returns rows whose biz_enyy does not include the
+#               requested founding period bucket.
+#
+# Matching policy: substring match against the comma-separated list inside
+# each row's field. Multiple requested values (comma-separated by the user)
+# are AND-joined: every requested token must appear somewhere in the row.
+# This mirrors how the K-Startup web UI narrows results.
+CLIENT_FILTER_FIELDS = {"supt_regin", "aply_trgt", "biz_enyy"}
+
+REGION_SHORTNAME = {
+    "서울특별시": "서울", "서울시": "서울", "서울": "서울",
+    "부산광역시": "부산", "부산시": "부산", "부산": "부산",
+    "대구광역시": "대구", "대구시": "대구", "대구": "대구",
+    "인천광역시": "인천", "인천시": "인천", "인천": "인천",
+    "광주광역시": "광주", "광주시": "광주", "광주": "광주",
+    "대전광역시": "대전", "대전시": "대전", "대전": "대전",
+    "울산광역시": "울산", "울산시": "울산", "울산": "울산",
+    "세종특별자치시": "세종", "세종시": "세종", "세종": "세종",
+    "경기도": "경기", "경기": "경기",
+    "강원특별자치도": "강원", "강원도": "강원", "강원": "강원",
+    "충청북도": "충북", "충북": "충북",
+    "충청남도": "충남", "충남": "충남",
+    "전북특별자치도": "전북", "전라북도": "전북", "전북": "전북",
+    "전라남도": "전남", "전남": "전남",
+    "경상북도": "경북", "경북": "경북",
+    "경상남도": "경남", "경남": "경남",
+    "제주특별자치도": "제주", "제주도": "제주", "제주": "제주",
+    "전국": "전국",
+}
+
+
+class HelperError(RuntimeError):
+    """User-facing CLI error."""
+
+
+def load_secrets(path: str = DEFAULT_SECRETS_PATH) -> Dict[str, str]:
+    """Read dotenv-like secrets file. Returns {} if missing."""
+    data: Dict[str, str] = {}
+    if not os.path.exists(path):
+        return data
+    try:
+        with open(path, "r", encoding="utf-8") as fh:
+            for raw_line in fh:
+                line = raw_line.strip()
+                if not line or line.startswith("#"):
+                    continue
+                if "=" not in line:
+                    continue
+                key, _, value = line.partition("=")
+                key = key.strip()
+                value = value.strip()
+                if value.startswith('"') and value.endswith('"') and len(value) >= 2:
+                    value = value[1:-1]
+                if value.startswith("'") and value.endswith("'") and len(value) >= 2:
+                    value = value[1:-1]
+                if key:
+                    data[key] = value
+    except OSError:
+        return data
+    return data
+
+
+def resolve_api_key(args: argparse.Namespace) -> Optional[str]:
+    """`--direct` 전용 API 키 해석. env > secrets file 순서."""
+    env_key = os.environ.get("KSKILL_KSTARTUP_API_KEY") or os.environ.get("DATA_GO_KR_API_KEY")
+    if env_key:
+        return env_key.strip() or None
+    secrets = load_secrets(args.secrets_path or DEFAULT_SECRETS_PATH)
+    return (secrets.get("KSKILL_KSTARTUP_API_KEY") or secrets.get("DATA_GO_KR_API_KEY") or "").strip() or None
+
+
+def validate_yyyymmdd(value: str, field: str) -> str:
+    digits = "".join(c for c in value if c.isdigit())
+    if len(digits) != 8:
+        raise HelperError(f"{field} must be YYYYMMDD (got: {value!r})")
+    year = int(digits[0:4])
+    month = int(digits[4:6])
+    day = int(digits[6:8])
+    try:
+        datetime.date(year, month, day)
+    except ValueError as exc:
+        raise HelperError(f"{field} must be a valid YYYYMMDD date (got: {value!r})") from exc
+    return digits
+
+
+def build_query(args: argparse.Namespace, operation: str) -> Dict[str, Any]:
+    if operation not in OPERATIONS:
+        raise HelperError(f"Unknown operation: {operation}")
+    if args.page < 1:
+        raise HelperError("--page must be >= 1")
+    if args.per_page < 1 or args.per_page > 100:
+        raise HelperError("--per-page must be in [1, 100]")
+
+    query: Dict[str, Any] = {
+        "page": args.page,
+        "perPage": args.per_page,
+        "returnType": "json",
+    }
+    for field in OPERATIONS[operation]["allowed"]:
+        attr = field.lower()
+        raw = getattr(args, attr, None)
+        if raw is None or str(raw).strip() == "":
+            continue
+        value = str(raw).strip()
+        if field in DATE_FIELDS:
+            value = validate_yyyymmdd(value, field)
+        elif field in YN_FIELDS:
+            upper = value.upper()
+            if upper not in {"Y", "N"}:
+                raise HelperError(f"{field} must be Y or N (got: {value!r})")
+            value = upper
+        elif field == "biz_yr":
+            if not (len(value) == 4 and value.isdigit()):
+                raise HelperError(f"biz_yr must be 4 digits (got: {value!r})")
+        query[field] = value
+
+    if (
+        operation == "announcements"
+        and query.get("pbanc_rcpt_bgng_dt")
+        and query.get("pbanc_rcpt_end_dt")
+        and query["pbanc_rcpt_bgng_dt"] > query["pbanc_rcpt_end_dt"]
+    ):
+        raise HelperError("pbanc_rcpt_bgng_dt must be <= pbanc_rcpt_end_dt")
+    return query
+
+
+def encode_query(query: Dict[str, Any]) -> str:
+    pairs: List[Tuple[str, str]] = [(k, str(v)) for k, v in query.items()]
+    return urllib.parse.urlencode(pairs, doseq=False, safe="")
+
+
+def build_url(operation: str, query: Dict[str, Any], *, direct: bool, api_key: Optional[str], proxy_base_url: str) -> str:
+    if direct:
+        if not api_key:
+            raise HelperError(
+                "KSKILL_KSTARTUP_API_KEY (또는 DATA_GO_KR_API_KEY) 가 없습니다. "
+                "공공데이터포털 15125364 활용신청 후 키를 발급받아 환경변수나 ~/.config/k-skill/secrets.env 에 두세요."
+            )
+        path = OPERATIONS[operation]["path"]
+        with_key = dict(query)
+        with_key["ServiceKey"] = api_key
+        return f"{KSTARTUP_UPSTREAM_BASE_URL}/{path}?{encode_query(with_key)}"
+    base = proxy_base_url.rstrip("/")
+    return f"{base}/v1/kstartup/{operation}?{encode_query(query)}"
+
+
+def is_proxy_not_configured_body(body: str) -> bool:
+    try:
+        payload = json.loads(body)
+    except json.JSONDecodeError:
+        return False
+    return isinstance(payload, dict) and payload.get("error") == "upstream_not_configured"
+
+
+def http_get(url: str, *, timeout: int, via_proxy: bool = False) -> Tuple[int, str, str]:
+    headers = {
+        "accept": "application/json",
+        "user-agent": "k-skill/kstartup-search",
+    }
+    request = urllib.request.Request(url, headers=headers, method="GET")
+    context = ssl.create_default_context()
+    try:
+        with urllib.request.urlopen(request, timeout=timeout, context=context) as response:
+            body = response.read().decode("utf-8", errors="replace")
+            return response.status, response.headers.get("content-type", ""), body
+    except urllib.error.HTTPError as exc:
+        body = exc.read().decode("utf-8", errors="replace") if exc.fp else ""
+        if exc.code == 503 and is_proxy_not_configured_body(body):
+            raise HelperError(PROXY_KEY_NOT_CONFIGURED_MSG) from exc
+        return exc.code, exc.headers.get("content-type", "") if exc.headers else "", body
+    except urllib.error.URLError as exc:
+        if not via_proxy:
+            raise HelperError(f"network error: {exc.reason}") from exc
+        raise HelperError(f"{PROXY_DOWN_MSG} (상세: {exc.reason})") from exc
+
+
+def _normalise_filter_token(field: str, token: str) -> str:
+    if field == "supt_regin":
+        return REGION_SHORTNAME.get(token, token)
+    return token
+
+
+def _row_matches_token(row: Dict[str, Any], field: str, token: str) -> bool:
+    raw = row.get(field)
+    if raw is None:
+        return False
+    haystack = str(raw)
+    needle = _normalise_filter_token(field, token)
+    return needle in haystack
+
+
+def _row_matches_field(row: Dict[str, Any], field: str, requested: str) -> bool:
+    tokens = [t.strip() for t in requested.split(",") if t.strip()]
+    if not tokens:
+        return True
+    return all(_row_matches_token(row, field, token) for token in tokens)
+
+
+def apply_client_filters(
+    payload: Dict[str, Any],
+    args: argparse.Namespace,
+    operation: str,
+) -> Dict[str, Any]:
+    if operation != "announcements":
+        return payload
+    requested: Dict[str, str] = {}
+    for field in CLIENT_FILTER_FIELDS:
+        value = getattr(args, field, None)
+        if value is None:
+            continue
+        text = str(value).strip()
+        if text:
+            requested[field] = text
+    if not requested:
+        return payload
+    data = payload.get("data")
+    if not isinstance(data, list):
+        return payload
+    upstream_count = len(data)
+    filtered = [
+        row for row in data
+        if isinstance(row, dict)
+        and all(_row_matches_field(row, field, value) for field, value in requested.items())
+    ]
+    payload["data"] = filtered
+    payload["currentCount"] = len(filtered)
+    payload["client_filter"] = {
+        "fields": requested,
+        "upstream_returned": upstream_count,
+        "after_filter": len(filtered),
+        "note": "Applied after upstream response because K-Startup ignores some server-side filters.",
+    }
+    return payload
+
+
+def summarise(operation: str, payload: Dict[str, Any]) -> str:
+    items: Iterable[Dict[str, Any]] = []
+    if isinstance(payload, dict):
+        data = payload.get("data") or payload.get("items")
+        if isinstance(data, list):
+            items = data
+        elif isinstance(payload.get("response"), dict):
+            response = payload["response"]
+            body = response.get("body") or {}
+            items = body.get("items") or []
+    items = list(items or [])
+    if not items:
+        return "[summary] 매칭되는 항목이 없습니다. 필터를 완화하거나 페이지를 넘기세요."
+    lines = [f"[summary] operation={operation} count={len(items)} (page={payload.get('query', {}).get('page', payload.get('page'))} perPage={payload.get('query', {}).get('perPage', payload.get('perPage'))})"]
+    for index, item in enumerate(items, start=1):
+        title = (
+            item.get("biz_pbanc_nm")
+            or item.get("supt_biz_titl_nm")
+            or item.get("titl_nm")
+            or item.get("intg_pbanc_biz_nm")
+            or "(제목 없음)"
+        )
+        region = item.get("supt_regin") or item.get("biz_category_cd") or item.get("clss_cd") or ""
+        period = ""
+        if item.get("pbanc_rcpt_bgng_dt") or item.get("pbanc_rcpt_end_dt"):
+            period = f" {item.get('pbanc_rcpt_bgng_dt','?')} ~ {item.get('pbanc_rcpt_end_dt','?')}"
+        url = item.get("detl_pg_url") or ""
+        lines.append(f"  {index:>2}. {title} {region}{period}")
+        if url:
+            lines.append(f"      → {url}")
+    return "\n".join(lines)
+
+
+def _add_filter_args(parser: argparse.ArgumentParser, operation: str) -> None:
+    allowed = OPERATIONS[operation]["allowed"]
+    for field in allowed:
+        flag = "--" + field.replace("_", "-").lower()
+        parser.add_argument(flag, dest=field.lower(), default=None,
+                            help=f"K-Startup field: {field}")
+
+
+def make_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="run_kstartup.py",
+        description="창업진흥원 K-Startup Open API (data.go.kr 15125364) 조회 helper",
+    )
+    subparsers = parser.add_subparsers(dest="operation", required=True)
+
+    for operation in OPERATIONS:
+        sub = subparsers.add_parser(operation, help=f"K-Startup {operation} endpoint")
+        sub.add_argument("--page", type=int, default=1)
+        sub.add_argument("--per-page", dest="per_page", type=int, default=10)
+        format_group = sub.add_mutually_exclusive_group()
+        format_group.add_argument("--text", action="store_true", help="사람용 요약")
+        format_group.add_argument("--json", action="store_true", help="구조화 JSON 출력 (기본)")
+        sub.add_argument("--dry-run", action="store_true", dest="dry_run",
+                         help="요청 URL/파라미터만 출력, 네트워크 호출 없음")
+        sub.add_argument("--timeout", type=int, default=30)
+        sub.add_argument("--proxy-base-url", default=os.environ.get("KSKILL_PROXY_BASE_URL", DEFAULT_PROXY_BASE_URL))
+        sub.add_argument("--direct", action="store_true",
+                         help="proxy 우회, KSKILL_KSTARTUP_API_KEY 로 직접 호출")
+        sub.add_argument("--secrets-path", default=DEFAULT_SECRETS_PATH,
+                         help=f"--direct 시 secrets 파일 경로 (기본 {DEFAULT_SECRETS_PATH})")
+        _add_filter_args(sub, operation)
+    return parser
+
+
+def run(argv: Optional[List[str]] = None) -> int:
+    parser = make_parser()
+    args = parser.parse_args(argv)
+    operation = args.operation
+
+    try:
+        query = build_query(args, operation)
+    except HelperError as exc:
+        print(f"[error] {exc}", file=sys.stderr)
+        return 2
+
+    if args.dry_run:
+        if args.direct:
+            preview = build_url(operation, query, direct=True, api_key="<DRY-RUN>", proxy_base_url=args.proxy_base_url)
+        else:
+            preview = build_url(operation, query, direct=False, api_key=None, proxy_base_url=args.proxy_base_url)
+        preview = preview.replace(os.environ.get("KSKILL_KSTARTUP_API_KEY", ""), "<DRY-RUN>") if os.environ.get("KSKILL_KSTARTUP_API_KEY") else preview
+        preview = preview.replace(os.environ.get("DATA_GO_KR_API_KEY", ""), "<DRY-RUN>") if os.environ.get("DATA_GO_KR_API_KEY") else preview
+        result = {"operation": operation, "url": preview, "query": query, "direct": bool(args.direct)}
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+        return 0
+
+    api_key = resolve_api_key(args) if args.direct else None
+    try:
+        url = build_url(operation, query, direct=args.direct, api_key=api_key, proxy_base_url=args.proxy_base_url)
+    except HelperError as exc:
+        print(f"[error] {exc}", file=sys.stderr)
+        return 3
+
+    try:
+        status, content_type, body = http_get(url, timeout=args.timeout, via_proxy=not args.direct)
+    except HelperError as exc:
+        print(f"[error] {exc}", file=sys.stderr)
+        return 4
+
+    payload: Any
+    try:
+        payload = json.loads(body) if body else {}
+    except json.JSONDecodeError:
+        print(f"[error] upstream returned non-JSON content-type={content_type!r} status={status}", file=sys.stderr)
+        print(body[:500])
+        return 5
+
+    if not isinstance(payload, dict):
+        payload = {"raw": payload}
+    payload.setdefault("query", query)
+
+    payload = apply_client_filters(payload, args, operation)
+
+    if args.text:
+        print(summarise(operation, payload))
+    else:
+        print(json.dumps(payload, ensure_ascii=False, indent=2))
+
+    if status >= 400:
+        return 6
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(run())

package/skills/kstartup-search/skill.json

@@ -0,0 +1,11 @@
+{
+  "name": "kstartup-search",
+  "description": "공공데이터포털 창업진흥원 K-Startup Open API(15125364)로 통합 공고 사업 정보·지원사업 공고·창업 콘텐츠·통계보고서를 k-skill-proxy 경유로 조회한다. 검색 전용. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.",
+  "profiles": [
+    "proxy",
+    "vault",
+    "browser",
+    "action:submission"
+  ],
+  "frontmatter": "name: kstartup-search\ndescription: 공공데이터포털 창업진흥원 K-Startup Open API(15125364)로 통합 공고 사업 정보·지원사업 공고·창업 콘텐츠·통계보고서를 k-skill-proxy 경유로 조회한다. 검색 전용. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.\nlicense: MIT\nmetadata:\n  category: business\n  locale: ko-KR\n  phase: v1"
+}

package/skills/ktx-booking/instruction.md

@@ -0,0 +1,244 @@
+# KTX Booking
+
+## What this skill does
+
+`korail2` 위에 `scripts/ktx_booking.py` helper 를 얹어 KTX/Korail 조회, 호차별 좌석번호 확인, 예약, 예약 확인, 취소를 처리한다.
+
+최근 Korail 앱의 Dynapath anti-bot 체크 때문에 원본 `korail2` 0.4.0 예제만으로는 `MACRO ERROR` 가 날 수 있다. 이 스킬은 helper 가 `x-dynapath-m-token`, `Sid`, 최신 app version(`250601002`)을 붙여 실제 예매 흐름을 복구하는 것을 전제로 한다.
+
+## When to use
+
+- "서울에서 부산 가는 KTX 찾아줘"
+- "코레일 예약 확인해줘"
+- "KTX 취소해줘"
+- "오전 9시 이후 KTX 중 제일 빠른 거 잡아줘"
+- "KTX 남은 좌석 번호 확인해줘"
+- "이 열차 콘센트 있는 꿀팁 좌석부터 보여줘"
+- "KTX 5호차 남은 자리만 봐줘"
+- "예약하기 전에 호차별 좌석 확인해줘"
+- "N카드로 할인 열차 찾아줘"
+- "내 N카드 목록 보여줘"
+- "N카드 할인 적용해서 예약해줘"
+
+## When not to use
+
+- SRT 예매인 경우
+- 돌쇠가 아니며 실결제 확정까지 자동화해야 하는 경우
+- credential 을 평문으로 넣으려는 경우
+
+## Prerequisites
+
+- Python 3.10+
+- `python3 -m pip install korail2-ncard pycryptodome`
+
+## Required environment variables
+
+- `KSKILL_KTX_ID`
+- `KSKILL_KTX_PASSWORD`
+
+### Credential handling
+
+- 돌쇠 credential mode에서는 `vault-run` capability를 사용하고, 없으면 `request_vault_credential`을 호출한다. ID/PW 원문을 채팅이나 shell에 넣지 않는다.
+- 그 밖의 환경에서는 이미 주입된 환경변수 → host vault → `~/.config/k-skill/secrets.env` 순서로 사용한다.
+
+## Inputs
+
+- 출발역
+- 도착역
+- 날짜: `YYYYMMDD`
+- 희망 시작 시각: `HHMMSS`
+- 인원 수와 승객 유형
+- 좌석 선호
+- 좌석 상세 조건: 객실 등급, 호차 번호, 남은 좌석만 보기, 콘센트 꿀팁 좌석 우선
+- 조회 결과에서 복사한 `train_id`
+
+## Workflow
+
+### 0. Install the package globally when missing
+
+`python3 -c 'import korail2, Crypto'` 가 실패하면 다른 구현으로 우회하지 말고 전역 Python 패키지 설치를 먼저 시도한다.
+
+```bash
+python3 -m pip install korail2-ncard pycryptodome
+```
+
+### 1. Ensure credentials are available
+
+돌쇠 credential mode에서는 `vault-run`의 Korail capability를 확인하고, 없으면 `request_vault_credential`로 앱 vault 입력 UI를 호출한다. generic fallback에서만 `KSKILL_KTX_ID`, `KSKILL_KTX_PASSWORD` 환경변수를 확인한다.
+
+시크릿이 없다는 이유로 웹사이트를 직접 긁거나 다른 비공식 경로를 찾지 않는다.
+
+### 2. Search first via the helper
+
+항상 helper 를 통해 조회한다.
+
+```bash
+python3 scripts/ktx_booking.py search 서울 부산 20260328 090000 --limit 5
+```
+
+기본 `--train-type` 은 `ktx` 다. ITX-청춘(예: 남춘천↔용산)·ITX-새마을·무궁화호처럼 KTX 외 노선을 잡으려면 `--train-type` 으로 지정한다.
+
+```bash
+python3 scripts/ktx_booking.py search 남춘천 용산 20260503 150000 --train-type itx-cheongchun
+```
+
+선택지: `ktx`, `itx-saemaeul`, `mugunghwa`, `nuriro`, `tonggeun`, `itx-cheongchun`, `airport`, `all`.
+
+예약 단계(`reserve`)에서도 같은 `--train-type` 값을 그대로 넘겨야 stable `train_id` 매칭이 깨지지 않는다.
+
+좌석이 없는 열차도 후보에 포함하려면 `--include-no-seats`, 예약 대기 가능한 열차도 같이 보고 싶으면 `--include-waiting-list` 를 붙인다.
+
+### 3. Present the shortlist
+
+예매 전에 항상 아래를 확인한다.
+
+- `index`
+- `train_id`
+- 출발/도착 시각
+- 열차 종류 (`train_type`)
+- 일반실/특실 가능 여부
+- 예약 대기 가능 여부
+
+### 4. Inspect detailed seats when the user asks for good seats
+
+`search` 의 좌석 가능 여부는 열차 단위 플래그다. 사용자가 "남은 좌석 번호", "호차별 좌석", "콘센트", "꿀팁 좌석", "창측/순방향 자리", "예약 전에 자리 확인"처럼 구체적인 좌석을 물으면 예약 전에 `seats` 를 호출한다.
+
+기본 상세 좌석 조회:
+
+```bash
+python3 scripts/ktx_booking.py seats 서울 부산 20260328 090000 --train-id <train_id>
+```
+
+일반실/특실은 `--room` 으로 나눈다.
+
+```bash
+python3 scripts/ktx_booking.py seats 서울 부산 20260328 090000 --train-id <train_id> --room special
+```
+
+남은 좌석번호만 보고 싶으면 `--available-only` 를 쓴다.
+
+```bash
+python3 scripts/ktx_booking.py seats 서울 부산 20260328 090000 --train-id <train_id> --available-only
+```
+
+특정 호차를 지정하지 않으면 `seats` 는 **5호차를 최우선**으로 탐색한다. 5호차가 없으면 5호차와의 거리가 가까운 호차 순으로, 같은 거리에서는 낮은 호차 번호 순으로 탐색한다(예: 1~8호차 편성은 `5, 4, 6, 3, 7, 2, 8, 1`, 1~4호차 편성은 `4, 3, 2, 1`). 일반 KTX, KTX-산천(분류 코드 07·10), KTX-청룡 모두 같은 규칙을 적용한다. 각 호차 안의 좌석은 콘센트 힌트가 있는 좌석(`direct`, `adjacent`)을 먼저, 같은 조건에서는 순방향 좌석을 먼저 보여준다.
+
+특정 호차만 확인하려면 `--car-no` 를 쓴다.
+
+```bash
+python3 scripts/ktx_booking.py seats 서울 부산 20260328 090000 --train-id <train_id> --car-no 5 --available-only
+```
+
+콘센트 꿀팁 자리부터 확인하려면 `--power-only` 를 붙인다. 응답의 `power_outlet` 은 `direct`, `adjacent`, `none` 중 하나다.
+
+```bash
+python3 scripts/ktx_booking.py seats 서울 부산 20260328 090000 --train-id <train_id> --available-only --power-only
+```
+
+`seats` 도 `search` 와 같은 `--train-type` 을 넘겨야 한다. ITX-청춘 등 KTX 외 열차를 조회했다면 상세 좌석 조회에도 같은 값을 사용한다.
+
+```bash
+python3 scripts/ktx_booking.py seats 남춘천 용산 20260503 150000 \
+  --train-id <train_id> \
+  --train-type itx-cheongchun \
+  --available-only
+```
+
+상세 좌석 응답을 보여줄 때는 사용자 의도에 맞춰 아래를 우선 요약한다.
+
+- 호차별 `remaining_seats`, `available_seat_count`
+- 남은 좌석 번호 (`available_seats`)
+- 좌석별 `direction`, `position`, `seat_type`
+- 콘센트 힌트 (`power_outlet`)
+- 문 근처 여부 (`near_door`)
+
+이 기능은 좌석을 선택/선점하지 않는다. 실제 예약은 다음 단계의 `reserve` 로만 진행한다.
+
+### 5. Reserve only after the target train is unambiguous
+
+조회 결과의 `train_id` 를 고른 뒤에만 예약한다. 이 값은 helper 가 열차 번호/운행일/시각/역 코드를 묶어 만든 stable selector 이므로, 재조회 시 같은 열차가 아직 있으면 그대로 잡고 없으면 실패한다.
+
+```bash
+python3 scripts/ktx_booking.py reserve 서울 부산 20260328 090000 --train-id <train_id> --seat-option general-first
+```
+
+ITX 등 KTX 외 노선을 search 단계에서 골랐다면 reserve 에도 똑같이 `--train-type` 을 넘긴다.
+
+```bash
+python3 scripts/ktx_booking.py reserve 남춘천 용산 20260503 150000 --train-id <train_id> --train-type itx-cheongchun --seat-option general-first
+```
+
+응답에는 예약번호, 운임, 구입기한이 포함된다. 이 시점에 **좌석 확보는 완료되었다**고 안내한다. generic fallback에서는 결제를 handoff하고, 돌쇠에서는 아래 결제 단계로 계속 진행한다.
+좌석이 없을 때는 조회 단계에서 `--include-waiting-list` 를 켜고 예약 단계에서 `--try-waiting` 으로 예약 대기까지 시도할 수 있다.
+
+### 5-1. N-card discounted reservation
+
+N카드 할인을 적용하려면 먼저 보유 N카드 목록을 조회해 카드 번호를 확인한다.
+
+```bash
+python3 scripts/ktx_booking.py ncard-list
+```
+
+N카드로 할인 열차를 조회한다 (`--ncard-index` 는 `ncard-list` 결과의 순번). `ncard-list` 는 로그/셸 노출을 줄이기 위해 카드 번호를 마스킹해 출력한다.
+
+```bash
+python3 scripts/ktx_booking.py ncard-search 대전 서울 20260512 100000 --ncard-index 1 --train-type ktx
+```
+
+응답의 `train_id` 를 복사해 `reserve` 에 같은 `--ncard-index` 를 붙여 예약한다.
+
+```bash
+python3 scripts/ktx_booking.py reserve 대전 서울 20260512 100000 \
+  --train-id <train_id> \
+  --ncard-index 1
+```
+
+`--ncard-index` 를 지정하면 `--adults` 등 승객 옵션은 무시되고 N카드 승객 1명으로 처리된다. `--ncard-no` 직접 입력도 지원하지만 셸 히스토리에 남을 수 있어 권장하지 않는다. generic fallback에서는 결제를 handoff하고, 돌쇠에서는 아래 결제 단계로 계속 진행한다.
+
+N카드 기능은 `korail2-ncard` 패키지가 필요하다. 없으면 해당 커맨드 실행 시 설치 안내가 출력된다.
+
+### 6. Continue to payment in Dolshoi
+
+돌쇠에서 사용자가 예매 완료를 요청했다면 예약 성공에서 멈추지 않는다.
+
+1. CloakBrowser의 공식 Korail 예약/결제 화면에서 방금 만든 예약번호를 다시 식별한다.
+2. vault-backed login을 사용하고 N카드/할인, 승객, 좌석, 결제수단을 확인한다.
+3. 실제 결제 버튼 직전에 `clarify`로 열차, 날짜·시각, 승객, 좌석 등급, 할인, 총액을 보여주고 승인받는다.
+4. 승인되면 결제를 실행하고 결제 완료 화면, 예약번호, 영수증/결제 상태를 확인한다.
+
+돌쇠가 아니거나 공식 결제 표면을 사용할 수 없으면 예약번호와 구입기한을 제공하고 generic handoff로 종료한다.
+
+### 7. Inspect or cancel
+
+취소는 대상 예약을 다시 조회해 식별한 뒤에만 진행한다.
+
+```bash
+python3 scripts/ktx_booking.py reservations
+```
+
+취소 실행 직전에 `clarify`로 예약번호, 열차, 날짜·시각, 승객, 환불/위약금 정보를 확인하고 승인받는다.
+
+```bash
+python3 scripts/ktx_booking.py cancel <reservation_id>
+```
+
+## Done when
+
+- 조회면 열차 후보가 정리되어 있다
+- 좌석 상세 확인이면 호차별 남은 좌석번호와 필요한 꿀팁 조건이 정리되어 있다
+- 예약이면 예약 결과와 제한 시간이 확인되어 좌석 확보 완료를 안내했다
+- 돌쇠의 예매 완료 요청이면 `clarify` 승인 후 결제 완료 상태와 영수증/예약번호를 확인했다
+- 취소면 어떤 예약을 취소했는지 남아 있다
+
+## Failure modes
+
+- 로그인 실패
+- 매진
+- Korail anti-bot 규칙 변경
+
+## Notes
+
+- `scripts/ktx_booking.py` 는 upstream `korail2` anti-bot 회귀를 보완하는 helper 다
+- `korail2` 는 KTX/Korail 전용 표면이라 train type 과 passenger model 이 분명하다
+- 결제 자동화 금지는 generic fallback에만 적용한다. 돌쇠에서는 `clarify` 승인 후 공식 결제 표면으로 완료한다
+- aggressive polling 은 피한다