@nomadamas/k-skill 0.1.0

package/skills/ev-charger-nearby/scripts/ev_charger.py

@@ -0,0 +1,222 @@
+#!/usr/bin/env python3
+"""Read-only EV charger info/status helper using stdlib only."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import pathlib
+import sys
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Dict, Optional
+
+
+DEFAULT_PROXY_BASE_URL = "https://k-skill-proxy.nomadamas.org"
+DEFAULT_SECRETS_PATH = pathlib.Path("~/.config/k-skill/secrets.env").expanduser()
+UPSTREAM_BASE_URL = "https://apis.data.go.kr/B552584/EvCharger"
+OPERATIONS = {"info": "getChargerInfo", "status": "getChargerStatus"}
+PROXY_DOWN_MSG = "설정된 k-skill-proxy 프록시 서버가 응답하지 않습니다. 잠시 후 재시도하거나 운영자에게 문의하세요."
+PROXY_NOT_CONFIGURED_MSG = "k-skill-proxy에 EV 충전소 API 키가 설정되어 있지 않습니다. 운영자에게 문의하세요."
+
+
+class HelperError(RuntimeError):
+    pass
+
+
+def load_secrets(path: pathlib.Path) -> Dict[str, str]:
+    values: Dict[str, str] = {}
+    try:
+        lines = path.read_text(encoding="utf-8").splitlines()
+    except OSError:
+        return values
+    for raw in lines:
+        line = raw.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, value = line.split("=", 1)
+        value = value.strip().strip('"').strip("'")
+        values[key.strip()] = value
+    return values
+
+
+def resolve_api_key(args: argparse.Namespace) -> Optional[str]:
+    env_key = os.environ.get("KSKILL_EV_CHARGER_API_KEY") or os.environ.get("DATA_GO_KR_API_KEY")
+    if env_key and env_key.strip():
+        return env_key.strip()
+    secrets = load_secrets(pathlib.Path(args.secrets_path).expanduser())
+    value = secrets.get("KSKILL_EV_CHARGER_API_KEY") or secrets.get("DATA_GO_KR_API_KEY")
+    return value.strip() if value and value.strip() else None
+
+
+def _bounded_integer(value: int, label: str, minimum: int, maximum: int) -> int:
+    if value < minimum or value > maximum:
+        raise HelperError(f"{label} 값은 {minimum}~{maximum} 범위여야 합니다.")
+    return value
+
+
+def _validate_code(value: Optional[str], label: str, maximum: int, digits: Optional[int] = None) -> Optional[str]:
+    if value is None:
+        return None
+    text = value.strip()
+    if not text:
+        return None
+    if len(text) > maximum or (digits is not None and (len(text) != digits or not text.isdigit())):
+        raise HelperError(f"올바른 {label} 값을 입력하세요.")
+    if digits is None and not all(ch.isalnum() or ch in "_-" for ch in text):
+        raise HelperError(f"올바른 {label} 값을 입력하세요.")
+    return text
+
+
+def build_query(args: argparse.Namespace) -> Dict[str, Any]:
+    query: Dict[str, Any] = {
+        "pageNo": _bounded_integer(args.page_no, "pageNo", 1, 100000),
+        "numOfRows": _bounded_integer(args.num_of_rows, "numOfRows", 10, 9999),
+    }
+    for key, maximum, digits in (("zcode", 2, 2), ("zscode", 5, 5), ("stat_id", 40, None), ("chger_id", 10, None)):
+        value = _validate_code(getattr(args, key), key.replace("_", ""), maximum, digits)
+        if value is not None:
+            query[{"stat_id": "statId", "chger_id": "chgerId"}.get(key, key)] = value
+    if args.command == "info" and args.location:
+        location = args.location.strip()
+        if len(location) > 100:
+            raise HelperError("location 값은 100자 이하여야 합니다.")
+        if args.direct:
+            raise HelperError("--direct에서는 location을 지원하지 않습니다. --zcode와 --zscode를 사용하세요.")
+        query["location"] = location
+    if args.command == "status":
+        if args.limit_yn:
+            limit_yn = args.limit_yn.strip().upper()
+            if limit_yn not in {"Y", "N"}:
+                raise HelperError("limitYn 값은 Y 또는 N이어야 합니다.")
+            query["limitYn"] = limit_yn
+        if args.period is not None:
+            query["period"] = _bounded_integer(args.period, "period", 1, 10)
+    return query
+
+
+def build_url(args: argparse.Namespace, query: Dict[str, Any], api_key: Optional[str]) -> str:
+    if args.direct:
+        if not api_key:
+            raise HelperError(
+                "KSKILL_EV_CHARGER_API_KEY 또는 DATA_GO_KR_API_KEY가 없습니다. "
+                "공공데이터포털 데이터셋 15076352 활용신청 후 키를 환경변수나 ~/.config/k-skill/secrets.env에 설정하세요."
+            )
+        direct_query = dict(query)
+        direct_query["serviceKey"] = api_key
+        direct_query["dataType"] = "JSON"
+        return f"{UPSTREAM_BASE_URL}/{OPERATIONS[args.command]}?{urllib.parse.urlencode(direct_query)}"
+    return f"{args.proxy_base_url.rstrip('/')}/v1/ev-charger/{args.command}?{urllib.parse.urlencode(query)}"
+
+
+def http_get_json(url: str, timeout: int, via_proxy: bool) -> Dict[str, Any]:
+    request = urllib.request.Request(url, headers={"accept": "application/json", "user-agent": "k-skill/ev-charger-nearby"})
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            raw = response.read().decode("utf-8", errors="replace")
+    except urllib.error.HTTPError as error:
+        raw = error.read().decode("utf-8", errors="replace") if error.fp else ""
+        try:
+            payload = json.loads(raw)
+        except json.JSONDecodeError:
+            payload = {}
+        if via_proxy and error.code == 503 and payload.get("error") == "upstream_not_configured":
+            raise HelperError(PROXY_NOT_CONFIGURED_MSG) from error
+        message = payload.get("message") or f"API HTTP 오류: {error.code} {error.reason}"
+        raise HelperError(str(message)) from error
+    except urllib.error.URLError as error:
+        if via_proxy:
+            raise HelperError(f"{PROXY_DOWN_MSG} (상세: {error.reason})") from error
+        raise HelperError(f"상류 API 네트워크 오류: {error.reason}") from error
+    except TimeoutError as error:
+        target = "프록시 서버" if via_proxy else "상류 API"
+        raise HelperError(f"{target} 요청 시간이 초과되었습니다.") from error
+    try:
+        payload = json.loads(raw)
+    except json.JSONDecodeError as error:
+        raise HelperError("API 응답이 올바른 JSON이 아닙니다.") from error
+    if not isinstance(payload, dict):
+        raise HelperError("API 응답 형식이 올바르지 않습니다.")
+    return payload
+
+
+def format_text(payload: Dict[str, Any]) -> str:
+    response = payload.get("response")
+    if isinstance(response, dict) and isinstance(response.get("body"), dict):
+        payload = response["body"]
+    items_value = payload.get("items") or []
+    if isinstance(items_value, dict):
+        items_value = items_value.get("item") or []
+    items = items_value if isinstance(items_value, list) else [items_value]
+    total_count = payload.get("total_count", payload.get("totalCount", len(items)))
+    lines = [f"전기차 충전기 조회 결과: {total_count}건"]
+    for item in items:
+        name = item.get("statNm") or item.get("statId") or "이름 없음"
+        address = item.get("addr") or item.get("location") or "주소 없음"
+        charger = item.get("chgerId") or "-"
+        status = item.get("stat") or "상태 미상"
+        lines.append(f"- {name} / {address} / 충전기 {charger} / 상태 {status}")
+    if not items:
+        lines.append("조건에 맞는 충전기 정보가 없습니다.")
+    return "\n".join(lines)
+
+
+def add_common_arguments(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--zcode")
+    parser.add_argument("--zscode")
+    parser.add_argument("--stat-id")
+    parser.add_argument("--chger-id")
+    parser.add_argument("--page-no", type=int, default=1)
+    parser.add_argument("--num-of-rows", type=int, default=10)
+    parser.add_argument("--proxy-base-url", default=os.environ.get("KSKILL_PROXY_BASE_URL", DEFAULT_PROXY_BASE_URL))
+    parser.add_argument("--direct", action="store_true")
+    parser.add_argument("--secrets-path", default=str(DEFAULT_SECRETS_PATH))
+    parser.add_argument("--timeout", type=int, default=90)
+    parser.add_argument("--dry-run", action="store_true")
+    parser.add_argument("--json", action="store_true")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="전기차 충전소 정보와 상태 조회")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    info = subparsers.add_parser("info", help="충전소 위치와 기본 정보 조회")
+    add_common_arguments(info)
+    info.add_argument("--location")
+    status = subparsers.add_parser("status", help="충전기 운영 상태 조회")
+    add_common_arguments(status)
+    status.add_argument("--limit-yn")
+    status.add_argument("--period", type=int)
+    return parser
+
+
+def parse_args(argv: Optional[list[str]] = None) -> argparse.Namespace:
+    return build_parser().parse_args(argv)
+
+
+def run(argv: Optional[list[str]] = None) -> int:
+    try:
+        args = parse_args(argv)
+        query = build_query(args)
+        api_key = resolve_api_key(args) if args.direct else None
+        if args.dry_run and args.direct:
+            url = build_url(args, query, "REDACTED")
+        else:
+            url = build_url(args, query, api_key)
+        if args.dry_run:
+            print(json.dumps({"operation": args.command, "url": url, "query": query}, ensure_ascii=False, indent=2))
+            return 0
+        payload = http_get_json(url, args.timeout, via_proxy=not args.direct)
+        if args.json:
+            print(json.dumps(payload, ensure_ascii=False, indent=2))
+        else:
+            print(format_text(payload))
+        return 0
+    except HelperError as error:
+        print(str(error), file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(run())

package/skills/ev-charger-nearby/skill.json

@@ -0,0 +1,10 @@
+{
+  "name": "ev-charger-nearby",
+  "description": "Use when the user asks for Korean EV charging-station locations, charger types, or current charger status by region, station, or location text. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.",
+  "profiles": [
+    "proxy",
+    "vault",
+    "action:booking"
+  ],
+  "frontmatter": "name: ev-charger-nearby\ndescription: Use when the user asks for Korean EV charging-station locations, charger types, or current charger status by region, station, or location text. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.\nlicense: MIT\nmetadata:\n  category: transit\n  locale: ko-KR\n  phase: v1"
+}

package/skills/ev-subsidy-status/instruction.md

@@ -0,0 +1,165 @@
+# EV Subsidy Status
+
+## Prerequisites
+
+- Node.js 18+
+- `ev-subsidy-status` npm package
+
+기본 조회에는 브라우저, API 키, 로그인, 프록시가 필요하지 않다. 공식 화면 구조 변경을 진단할 때만 사용자가 실행한 Aside Browser, BrowserOS 또는 Chrome/Chromium CDP 세션을 선택적으로 사용한다.
+
+## Public access path
+
+기본 화면:
+
+```text
+https://ev.or.kr/nportal/buySupprt/initSubsidyPaymentCheckAction.do
+```
+
+모델별 보조금 화면:
+
+```text
+POST /nportal/buySupprt/psPopupLocalCarModelPrice.do
+year=<year>&local_cd=<region-code>&car_type=<11|12|13>
+```
+
+확인된 DOM:
+
+- 시도: `#localDo_cd`
+- 시군구: `#local_cd1`
+- 결과 열: 시도, 지역구분, 차종구분, 공고파일, 접수방법, 민간공고대수, 접수대수, 출고대수, 출고잔여대수, 비고
+
+페이지는 로그인 없이 공개되지만 `pnp4web`/`penc`가 본문을 보호한다. 기본 경로는 공개 응답에서 공식 `pnp4web.js` 문자표를 파싱하고 원격 코드를 실행하지 않은 채 HTML을 복원한다. 전국 행이 포함된 지급현황 표에서 요청 지역만 선택한다. 공개 keyless 화면이므로 `k-skill-proxy`를 사용하지 않는다.
+
+## Workflow
+
+### 1. 지역과 차종을 정규화한다
+
+- 지역은 가능하면 `시도 + 시군구`로 받는다. 예: `경기 성남시`
+- `중구`, `강서구`처럼 중복되는 이름이면 `regions`로 후보를 찾고 사용자가 시도를 고르게 한다.
+- 차종 기본값은 `passenger`/`전기승용`이다.
+- 지원 차종: `passenger`/`승용`, `cargo`/`화물`, `bus`/`승합`
+- 연도 기본값은 Asia/Seoul 기준 현재 연도다.
+
+```bash
+npx ev-subsidy-status regions --query 중구
+```
+
+### 2. 공식 지급현황을 조회한다
+
+```bash
+npx ev-subsidy-status status \
+  --region "경기 성남시" \
+  --vehicle passenger \
+  --year 2026 \
+  --json
+```
+
+결과의 `transport`가 `direct-http`인지 확인한다. 기본 경로는 사용자 브라우저가 없어도 동작해야 한다.
+
+반환값에서 다음을 우선 확인한다.
+
+- `status.notice_count`: 민간공고대수
+- `status.application_count`: 접수대수
+- `status.delivered_count`: 출고대수
+- `status.delivery_remaining_count`: 출고잔여대수
+- `availability.label`: 공고 상태 판정
+- `status.note`: 지자체 비고 원문
+- `source.fetched_at`: KST 조회 시각
+
+숫자 셀은 `전체 / 우선순위 / 법인·기관 / 예약 대상군 / 일반`으로 보존한다. 승용의 예약 대상군은 `taxi`, 화물은 `small_business` alias도 함께 반환한다.
+
+### 3. 비고를 숫자보다 우선한다
+
+다음 우선순위로 설명한다.
+
+1. `마감`, `소진`, `접수 종료` → `closed`
+2. `접수 예정`, `추경 예정`, `추가 공고 예정` → `scheduled`
+3. `접수 중`, `신청 기간`, `신청 가능` → `open`
+4. 명시 문구 없이 잔여 대수만 양수 → `unknown_with_remaining_count`
+5. 판단 근거 없음 → `unknown`
+
+잔여 대수가 양수여도 비고가 마감이면 신청 가능하다고 말하지 않는다.
+
+### 4. 모델을 지정했을 때만 원화 환산치를 조회한다
+
+```bash
+npx ev-subsidy-status status \
+  --region "서울 강남구" \
+  --vehicle passenger \
+  --model "모델명" \
+  --json
+```
+
+직접 HTTP 경로에서도 공식 모델별 보조금 POST 표면을 조회한다. 입력한 이름이 여러 세부 모델과 일치하면 임의로 하나를 고르지 않고 `model_subsidy_candidates`에 모든 후보와 후보별 환산치를 반환한다. 정확한 세부 모델과 하나만 일치할 때는 `model_subsidy`와 `remaining_budget.model_equivalent_estimate_krw`도 함께 반환한다.
+
+`remaining_budget.model_equivalent_estimate_krw`는 다음 가정의 환산치다.
+
+```text
+공식 출고잔여대수 × 선택 모델의 국비+지방비
+```
+
+이를 지자체의 정확한 예산 잔액이라고 표현하지 않는다. 모델별 금액, 구매자 추가지원, 물량 전환, 접수 후 예약·취소가 달라 실제 가용 예산과 다르다. 모델 조회가 실패해도 지역별 대수 결과는 유지하고 `model_lookup_error`와 경고를 보여준다.
+
+### 5. 사용자에게 보수적으로 답한다
+
+최종 답변에 포함한다.
+
+- 지역, 차종, 기준년도
+- 민간공고·접수·출고·출고잔여 대수
+- 공고 상태와 비고의 핵심 문구
+- 모델 환산치가 있으면 계산 가정
+- “출고잔여대수는 실제 신청 가능 대수 및 정확한 원화 잔액과 다를 수 있음” 경고
+- 공식 출처 URL과 KST 조회 시각
+
+## Direct HTTP behavior
+
+- `POST initSubsidyPaymentCheckAction.do`에 `year1`, `car_type`, 전국 지역 조건을 전송한다.
+- 응답의 `pnp4web.js` URL과 보호 payload를 추출한다.
+- 원격 JavaScript를 `eval`/`vm`으로 실행하지 않는다.
+- 스크립트에 선언된 조각 문자표만 파싱해 payload를 UTF-8 HTML로 복원한다.
+- 지급현황 표의 공식 행과 비고를 파싱하고 지역 코드는 공고 다운로드 함수 인자에서 읽는다.
+- 모델이 있으면 `psPopupLocalCarModelPrice.do`를 같은 연도·지역 코드·차종으로 호출하고 모델별 국비·지방비·합계를 파싱한다.
+- 공식 스크립트나 표 구조가 바뀌면 `UPSTREAM_DECODE_FAILED` 또는 `DOM_CHANGED`로 중단한다.
+
+## Optional browser behavior
+
+- `domcontentloaded` 후 목표 selector와 지역 행을 명시적으로 기다린다.
+- `networkidle`은 pnp4web 백그라운드 요청 때문에 사용하지 않는다.
+- 렌더링된 `<option>` label/value로 지역 코드를 동적으로 해석한다.
+- 기존 사용자 탭과 프로필을 닫지 않는다.
+- 스킬이 만든 페이지·컨텍스트만 정리하고 지원되는 client만 disconnect한다.
+- 로그인, CAPTCHA, 결제, 전자서명, 최종 제출 경계를 우회하지 않는다.
+
+공식 화면 변경을 진단하거나 모델별 환산을 조회하기 위해 브라우저 경로를 선택할 때:
+
+```bash
+npx ev-subsidy-status status --region "경기 성남시" --transport browser --provider aside
+npx ev-subsidy-status status --region "경기 성남시" --transport browser --provider browseros
+npx ev-subsidy-status status --region "경기 성남시" --transport browser --provider chrome-cdp
+```
+
+## Done when
+
+- 요청 지역과 차종이 공식 표의 행과 일치한다.
+- 공고·접수·출고·출고잔여 수치와 지자체 비고를 반환한다.
+- 명시적 마감 문구를 양수 잔여 대수보다 우선한다.
+- 정확한 원화 예산 잔액을 알 수 없으면 `exact_available=false`와 이유를 반환한다.
+- 출처 URL과 KST 조회 시각을 표시한다.
+
+## Failure modes
+
+- `REGION_REQUIRED`: 지역 입력이 없다.
+- `REGION_AMBIGUOUS`: 같은 시군구 이름이 여러 시도에 있다.
+- `REGION_NOT_FOUND`: 공식 지역 옵션에 없다.
+- `YEAR_NOT_AVAILABLE`: 요청 연도가 선택 목록에 없다.
+- `VEHICLE_TYPE_NOT_AVAILABLE`: 요청 차종을 지원하지 않거나 화면에서 찾지 못했다.
+- `BROWSER_UNAVAILABLE`: 연결 가능한 사용자 실행 브라우저가 없다.
+- `UPSTREAM_BLOCKED`: 빈 껍데기, 차단 또는 비정상 페이지다.
+- `CAPTCHA_DETECTED`: CAPTCHA가 나타났다. 우회하지 않는다.
+- `AUTH_REQUIRED`: 공개 화면이 로그인 흐름으로 바뀌었다. 우회하지 않는다.
+- `RESULT_EMPTY`: 목표 지역의 결과 행이 없다.
+- `DOM_CHANGED`: 공식 페이지의 선택자나 표 구조가 바뀌었다.
+- `UPSTREAM_DECODE_FAILED`: `pnp4web` 문자표 또는 보호 payload 형식이 바뀌었다.
+- `MODEL_LOOKUP_FAILED`: 모델별 보조금 표를 읽지 못했다.
+
+대상군 값이 음수이거나 전체와 부분합이 다르면 값을 0으로 고치지 않는다. 원본 수치와 경고를 함께 반환한다.

package/skills/ev-subsidy-status/skill.json

@@ -0,0 +1,10 @@
+{
+  "name": "ev-subsidy-status",
+  "description": "한국 지자체별 전기차 구매보조금 민간공고·접수·출고·출고잔여 대수와 공고 상태를 환경부 무공해차 통합누리집에서 조회한다. 사용자가 사는 지역의 전기승용·전기화물·전기승합 보조금 잔여 현황, 접수 가능 여부, 마감·소진·추경 예정, 특정 모델 기준 보조금 환산치를 물을 때 사용한다. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.",
+  "profiles": [
+    "proxy",
+    "browser",
+    "action:submission"
+  ],
+  "frontmatter": "name: ev-subsidy-status\ndescription: 한국 지자체별 전기차 구매보조금 민간공고·접수·출고·출고잔여 대수와 공고 상태를 환경부 무공해차 통합누리집에서 조회한다. 사용자가 사는 지역의 전기승용·전기화물·전기승합 보조금 잔여 현황, 접수 가능 여부, 마감·소진·추경 예정, 특정 모델 기준 보조금 환산치를 물을 때 사용한다. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.\nlicense: MIT\nmetadata:\n  category: local-info\n  locale: ko-KR\n  phase: v1"
+}

package/skills/express-bus-booking/instruction.md

@@ -0,0 +1,207 @@
+# Express Bus Booking (KOBUS)
+
+## Overview
+
+Use this skill for Korean 고속버스 / KOBUS timetable lookup and reservation assistance. The preferred workflow is HTTP/API-first: resolve routes, query timetables, inspect remaining seats and fares, and only use browser automation when endpoint discovery or an official web-only step blocks progress.
+
+This skill is intentionally separate from 시외버스. KOBUS terminal codes, route structures, and checkout pages differ from Tmoney 시외버스. Use `intercity-bus-booking` for 시외버스/Tmoney flows.
+
+## When to Use
+
+- The user asks for `고속버스 예매`, `고속버스 시간표`, `고속버스 예약`, `프리미엄 고속버스`, or `우등 고속버스`.
+- The route is clearly a KOBUS 고속버스 route or the user names KOBUS/코버스/고속버스통합예매.
+- The user wants assisted reservation up to seat selection, temporary hold, or a payment-entry link.
+
+Do **not** use this for:
+
+- 시외버스/Tmoney routes — use `intercity-bus-booking`.
+- Final card submission or payment without explicit, narrowly scoped confirmation.
+- Blind browser automation before trying the official HTTP flow.
+
+## Core Principles
+
+- Use official KOBUS surfaces: `https://www.kobus.co.kr`.
+- Keep a cookie jar and reuse referers. Stateless one-off POSTs are less reliable.
+- Prefer desktop User-Agent and HTTP/1.1 during probing if the server behaves differently under HTTP/2.
+- Default scope is assisted manual checkout: lookup, candidate presentation, seat-stage readiness, temporary seat hold, and official payment-entry page handoff.
+- Do not submit card fields, agree to terms, or complete payment unless the user explicitly confirms that exact action.
+
+## Known HTTP Flow
+
+See `references/kobus-http-flow.md` for session-proven endpoint details and parameter examples.
+
+### 1. Start a Session
+
+Fetch either the main page or route/search page with cookies enabled:
+
+```text
+GET https://www.kobus.co.kr/main.do
+GET https://www.kobus.co.kr/mrs/rotinf.do
+```
+
+Use a realistic desktop User-Agent and a cookie jar.
+
+### 2. Resolve Route / Terminal Candidates
+
+```text
+POST /mrs/readRotLinInf.ajax
+```
+
+The response is JSON and can include `rotInfList`, `tfrInfList`, `len`, and `codeYn`. Prefer code-confirmed routes over display-name matching because terminal names are not always unique.
+
+### 3. Query Timetable
+
+```text
+POST /mrs/alcnSrch.do
+```
+
+Typical fields include:
+
+```text
+deprCd=010
+arvlCd=700
+pathDvs=sngl
+pathStep=1
+deprDtm=YYYYMMDD
+busClsCd=0
+rtrpChc=1
+timeLinkMin=00
+timeLinkMax=23
+```
+
+Parse the returned HTML for schedule rows/cards and `fnSatsChc(...)` onclick arguments. Respect `mrsPsbYn=N` or any equivalent booking-disabled marker.
+
+### 4. Enter Seat / Fare Stage
+
+```text
+POST /mrs/satschc.do
+```
+
+Send the original search form fields plus selected values from `fnSatsChc(...)`, commonly including:
+
+```text
+deprTime
+alcnDeprTime
+alcnDeprTrmlNo
+alcnArvlTrmlNo
+indVBusClsCd
+cacmCd
+dcDvsCd
+prvtBbizEmpAcmtRt
+chldSftySatsYn
+dsprSatsYn
+```
+
+The response should include `form#satsChcFrm` and hidden fare/seat values such as `adltFee`, `rmnSatsNum`, `totSatsNum`, and terminal/time fields.
+
+### 5. Temporary Seat Hold
+
+```text
+POST /mrs/setPcpy.ajax
+```
+
+Submit the `satsChcFrm` hidden fields plus selected seat/count fields. A successful response includes:
+
+```text
+MSG_CD=S0000
+pcpyNoAll
+satsNoAll
+ESTM_AMT
+DC_AMT
+TISSU_AMT
+```
+
+Treat the hold as short-lived. If testing, if the user does not proceed, or if a new seat is chosen, release it explicitly.
+
+### 6. Release Temporary Hold
+
+```text
+POST /mrs/cancPcpy.ajax
+```
+
+Use the same relevant form fields plus the returned `pcpyNoAll` and `satsNoAll`. A successful response returns `MSG_CD=S0000`.
+
+## Helper Script
+
+Use the bundled helper for KOBUS lookup and optional temporary holds:
+
+```bash
+python3 express-bus-booking/scripts/kobus_express_booking.py \
+  --depart-code 021 \
+  --arrive-code 500 \
+  --date 20260520 \
+  --select-index 1 \
+  --hold-first-seat \
+  --output-dir /tmp/kobus-hold
+```
+
+For Seoul to Gwangju, the verified KOBUS route is `센트럴시티(서울)` code `021` to `광주(유·스퀘어)` code `500`. A successful hold returns `MSG_CD=S0000`, `pcpyNoAll`, `satsNoAll`, fare amounts, and saves a local auto-submit helper for the official KOBUS payment-information page. Final card entry and payment remain manual. Cancel abandoned holds with `/mrs/cancPcpy.ajax` using the saved cancel fields.
+
+## Checkout-Entry Link Helper
+
+A plain official checkout URL is not enough because KOBUS expects a POST body containing the selected schedule, seat, fare, and hold identifiers. The practical user-facing pattern is:
+
+1. Create the temporary hold server-side via `setPcpy.ajax`.
+2. Generate a short helper page that auto-submits a POST form to the official KOBUS checkout endpoint.
+3. Send the helper link to the user.
+4. The user completes card/payment fields manually on the official KOBUS page.
+
+Desktop action:
+
+```text
+https://www.kobus.co.kr/mrs/stplcfmpym.do
+```
+
+Mobile-friendly action:
+
+```text
+https://www.kobus.co.kr/mrs/stplcfmpym.do?keep=/mrs/pay
+```
+
+The POST body should include the original seat form fields plus returned hold values such as `pcpyNoAll`, `satsNoAll`, `estmAmt`, `dcAmt`, `tissuAmt`, and `nonMbrsYn=Y` when using a non-member checkout flow.
+
+## Mobile Redirect Caveat
+
+KOBUS common JavaScript can redirect narrow/mobile screens to `/mblIdx.do` unless `location.href` contains a mobile-allowed path fragment such as `/mrs/pay`. In testing, posting to:
+
+```text
+/mrs/stplcfmpym.do?keep=/mrs/pay
+```
+
+preserved the same checkout POST body while making the final browser URL contain `/mrs/pay`, avoiding the client-side mobile-main redirect condition. Use this variant for Discord/mobile users, but still verify with the user because in-app browsers may add their own quirks.
+
+If mobile still lands on the homepage, recommend opening the helper link in a normal external browser or desktop browser. Do not keep retrying holds indefinitely; cancel stale holds.
+
+## Suggested Output Format
+
+Keep candidate lists concise and actionable:
+
+```text
+고속버스 서울경부 → 부산 / 2026-05-09
+1. 00:30 심야우등 / 천일고속 / 잔여 10석 / 성인 47,600원
+2. 13:50 우등 / ...
+```
+
+When a hold/checkout helper is created, state that the next step opens the official KOBUS payment page and that payment remains manual.
+
+For Discord/mobile, provide links as normal text links, not fenced code blocks, so the user can tap them directly.
+
+## Common Pitfalls
+
+1. **Mixing KOBUS and Tmoney codes.** KOBUS terminal codes are not Tmoney 시외버스 terminal codes.
+2. **Assuming a cart exists.** KOBUS does not expose a shopping-cart style hold list in the tested web flow. The realistic UX is temporary seat hold plus checkout-entry handoff.
+3. **Ignoring hold cleanup.** Always cancel test holds or abandoned holds with `cancPcpy.ajax`.
+4. **Treating lookup success as payment permission.** Lookup, seat-stage entry, and temporary hold are not authorization to submit payment.
+5. **Mobile homepage redirects.** Use the `?keep=/mrs/pay` helper action for mobile; otherwise KOBUS JS may send the user to `/mblIdx.do`.
+6. **Browser automation too early.** Try direct HTTP first. Use browser tooling only to discover changed endpoints or verify final user-facing behavior.
+
+## Verification Checklist
+
+- [ ] Route/terminal codes were resolved from KOBUS, not guessed.
+- [ ] Timetable was queried with cookies and a realistic User-Agent.
+- [ ] Candidate output includes date, departure/arrival terminals, time, class/operator when available, fare, and remaining seats.
+- [ ] Seat-stage response contains expected hidden fields before attempting a hold.
+- [ ] Temporary hold success was confirmed with `MSG_CD=S0000` before sending a checkout helper link.
+- [ ] Stale/test holds were cancelled with `cancPcpy.ajax`.
+- [ ] Payment/card fields were left for the user unless they explicitly confirmed otherwise.
+- [ ] Mobile helper links use the `/mrs/pay` marker variant when sent to mobile-heavy platforms.