@nomadamas/k-skill 0.1.0

package/skills/srt-booking/scripts/srt_booking.py

@@ -0,0 +1,272 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import base64
+import contextlib
+import io
+import importlib
+import json
+import os
+import sys
+from types import ModuleType
+from typing import Protocol
+
+from srt_seats import parse_cars, parse_seats, sort_cars_for_booking, sort_seats_for_booking
+
+SRT_SEAT_ENDPOINT = "https://etk.srail.kr/hpg/hra/01/selectPassengerResearchList.do"
+TRAIN_ID_PREFIX = "srt:v1:"
+TRAIN_ID_FIELDS = (
+    "train_number",
+    "dep_date",
+    "dep_time",
+    "arr_date",
+    "arr_time",
+    "train_code",
+    "dep_station_code",
+    "arr_station_code",
+    "dep_station_run_order",
+    "arr_station_run_order",
+)
+ROOM_CODE = {"general": "1", "special": "2"}
+ROOM_NAME = {"general": "일반실", "special": "특실"}
+
+
+class SrtTrainLike(Protocol):
+    train_number: str
+    dep_date: str
+    dep_time: str
+    arr_date: str
+    arr_time: str
+    train_code: str
+    train_name: str
+    dep_station_code: str
+    dep_station_name: str
+    arr_station_code: str
+    arr_station_name: str
+    dep_station_run_order: str
+    arr_station_run_order: str
+    general_seat_state: str
+    special_seat_state: str
+    reserve_wait_possible_code: str
+
+    def general_seat_available(self) -> bool: ...
+
+    def special_seat_available(self) -> bool: ...
+
+    def reserve_standby_available(self) -> bool: ...
+
+
+class ResponseLike(Protocol):
+    text: str
+
+
+class SessionLike(Protocol):
+    def get(self, url: str, params: dict[str, str]) -> ResponseLike: ...
+
+
+class SrtClientLike(Protocol):
+    _session: SessionLike
+
+    def search_train(
+        self,
+        dep: str,
+        arr: str,
+        date: str,
+        time: str,
+        time_limit: str | None = None,
+        available_only: bool = True,
+    ) -> list[SrtTrainLike]: ...
+
+
+def load_srt_module() -> ModuleType:
+    try:
+        return importlib.import_module("SRT")
+    except ModuleNotFoundError as exc:
+        raise SystemExit("scripts/srt_booking.py requires SRTrain: python3 -m pip install SRTrain")
+
+
+def build_client(auto_login: bool = False) -> SrtClientLike:
+    srt_module = load_srt_module()
+    srt_id = os.environ.get("KSKILL_SRT_ID", "")
+    srt_pw = os.environ.get("KSKILL_SRT_PASSWORD", "")
+    return srt_module.SRT(srt_id, srt_pw, auto_login=auto_login)
+
+
+def train_id_payload(train: SrtTrainLike) -> dict[str, str]:
+    return {field: getattr(train, field) for field in TRAIN_ID_FIELDS}
+
+
+def build_train_id(train: SrtTrainLike) -> str:
+    raw = json.dumps(train_id_payload(train), ensure_ascii=False, separators=(",", ":")).encode()
+    encoded = base64.urlsafe_b64encode(raw).decode("ascii").rstrip("=")
+    return f"{TRAIN_ID_PREFIX}{encoded}"
+
+
+def parse_train_id(train_id: str) -> dict[str, str]:
+    if not train_id.startswith(TRAIN_ID_PREFIX):
+        raise SystemExit("train_id must start with srt:v1:")
+    encoded = train_id.removeprefix(TRAIN_ID_PREFIX)
+    padded = encoded + ("=" * ((4 - len(encoded) % 4) % 4))
+    try:
+        payload = json.loads(base64.urlsafe_b64decode(padded.encode()).decode())
+    except (ValueError, json.JSONDecodeError, UnicodeDecodeError) as exc:
+        raise SystemExit("train_id is invalid; rerun search and copy a fresh train_id") from exc
+    if not isinstance(payload, dict):
+        raise SystemExit("train_id is invalid; rerun search and copy a fresh train_id")
+    if any(not isinstance(payload.get(field), str) or not payload[field] for field in TRAIN_ID_FIELDS):
+        raise SystemExit("train_id is invalid; rerun search and copy a fresh train_id")
+    return {field: payload[field] for field in TRAIN_ID_FIELDS}
+
+
+def find_train_by_id(trains: list[SrtTrainLike], train_id: str) -> SrtTrainLike | None:
+    expected = parse_train_id(train_id)
+    return next((train for train in trains if train_id_payload(train) == expected), None)
+
+
+def normalize_train(train: SrtTrainLike, index: int) -> dict[str, str | bool | int]:
+    return {
+        "index": index,
+        "train_id": build_train_id(train),
+        "train_no": train.train_number,
+        "train_type": train.train_name,
+        "dep_name": train.dep_station_name,
+        "dep_date": train.dep_date,
+        "dep_time": train.dep_time,
+        "arr_name": train.arr_station_name,
+        "arr_date": train.arr_date,
+        "arr_time": train.arr_time,
+        "has_general_seat": train.general_seat_available(),
+        "has_special_seat": train.special_seat_available(),
+        "has_waiting_list": train.reserve_standby_available(),
+    }
+
+
+def seat_page_params(train: SrtTrainLike, room: str, car_no: int | None) -> dict[str, str]:
+    return {
+        "runDt1": train.dep_date,
+        "dptDt1": train.dep_date,
+        "dptTm1": train.dep_time,
+        "trnNo1": f"{int(train.train_number):05d}",
+        "trnGpCd1": "300",
+        "dptRsStnCd1": train.dep_station_code,
+        "arvRsStnCd1": train.arr_station_code,
+        "dptStnRunOrdr1": train.dep_station_run_order,
+        "arvStnRunOrdr1": train.arr_station_run_order,
+        "seatAttCd1": "015",
+        "psrmClCd1": ROOM_CODE[room],
+        "index1": "0",
+        "scarNo1": "" if car_no is None else f"{car_no:04d}",
+        "chtnDvCd": "1",
+        "jrnySqno": "001",
+        "mode": "1",
+        "psgNum": "1",
+        "pageId": "",
+    }
+
+
+def fetch_seat_page(client: SrtClientLike, train: SrtTrainLike, room: str, car_no: int | None) -> str:
+    with contextlib.redirect_stdout(io.StringIO()):
+        response = client._session.get(SRT_SEAT_ENDPOINT, params=seat_page_params(train, room, car_no))
+    return response.text
+
+
+def command_search(args: argparse.Namespace) -> None:
+    client = build_client(auto_login=False)
+    with contextlib.redirect_stdout(io.StringIO()):
+        trains = client.search_train(args.dep, args.arr, args.date, args.time, args.time_limit, args.available_only)
+    print_json({"count": len(trains[: args.limit]), "trains": [normalize_train(train, index) for index, train in enumerate(trains[: args.limit], 1)]})
+
+
+def command_seats(args: argparse.Namespace) -> None:
+    client = build_client(auto_login=False)
+    with contextlib.redirect_stdout(io.StringIO()):
+        trains = client.search_train(args.dep, args.arr, args.date, args.time, args.time_limit, available_only=False)
+    train = find_train_by_id(trains, args.train_id)
+    if train is None:
+        raise SystemExit("train_id no longer matches any current search result; rerun search and choose a fresh train_id")
+
+    initial_html = fetch_seat_page(client, train, args.room, args.car_no)
+    cars = [car for car in parse_cars(initial_html) if car["room_class"] == ROOM_NAME[args.room]]
+    if args.car_no is not None:
+        cars = [car for car in cars if car["car_no"] == args.car_no]
+    else:
+        cars = [car for car in cars if car["available"]]
+    if not cars:
+        raise SystemExit(f"seat car data is unavailable for {args.room}; retry search or choose another train")
+
+    car_payloads: list[dict[str, object]] = []
+    for car in sort_cars_for_booking(cars, args.car_priority):
+        html = initial_html if args.car_no == car["car_no"] else fetch_seat_page(client, train, args.room, car["car_no"])
+        seats = parse_seats(html)
+        if args.seat:
+            seats = [seat for seat in seats if seat["seat"] == args.seat]
+        seats = sort_seats_for_booking(seats, args.seat_priority)
+        if args.available_only:
+            seats = [seat for seat in seats if seat["available"]]
+        available_seats = [seat for seat in seats if seat["available"]]
+        limited = seats[: args.limit]
+        payload = dict(car)
+        payload["available_seat_count"] = len(available_seats)
+        payload["available_seats"] = [seat["seat"] for seat in available_seats]
+        payload["shown_seat_count"] = len(limited)
+        payload["seats"] = limited
+        if args.seat:
+            payload["requested_seat"] = args.seat
+            payload["requested_seat_available"] = any(seat["available"] for seat in seats)
+        car_payloads.append(payload)
+
+    print_json({
+        "train": normalize_train(train, 1),
+        "room": args.room,
+        "available_only": args.available_only,
+        "car_priority": args.car_priority,
+        "seat_priority": args.seat_priority,
+        "cars": car_payloads,
+    })
+
+
+def print_json(payload: dict[str, object]) -> None:
+    print(json.dumps(payload, ensure_ascii=False, indent=2))
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="SRT search and seat lookup helper for k-skill")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    search = subparsers.add_parser("search", help="SRT 열차를 조회합니다")
+    add_trip_args(search)
+    search.add_argument("--time-limit", default=None, help="조회 종료 시각 HHMMSS")
+    search.add_argument("--available-only", action="store_true", default=False, help="예약 가능한 열차만 출력")
+    search.add_argument("--limit", type=int, default=5, help="출력할 최대 열차 수")
+    search.set_defaults(func=command_search)
+
+    seats = subparsers.add_parser("seats", help="SRT 호차별 좌석번호를 조회합니다")
+    add_trip_args(seats)
+    seats.add_argument("--train-id", required=True, help="search 결과에서 복사한 stable train_id")
+    seats.add_argument("--time-limit", default=None, help="조회 종료 시각 HHMMSS")
+    seats.add_argument("--room", choices=sorted(ROOM_CODE), default="general")
+    seats.add_argument("--car-no", type=int, default=None, help="특정 호차만 조회")
+    seats.add_argument("--seat", default=None, help="특정 좌석번호만 조회, 예: 6C")
+    seats.add_argument("--available-only", action="store_true", help="빈 좌석만 출력")
+    seats.add_argument("--car-priority", choices=("center", "low", "high"), default="center")
+    seats.add_argument("--seat-priority", choices=("forward-window", "window-forward", "row-low"), default="forward-window")
+    seats.add_argument("--limit", type=int, default=100, help="호차별 출력할 최대 좌석 수")
+    seats.set_defaults(func=command_seats)
+    return parser
+
+
+def add_trip_args(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("dep", help="출발역")
+    parser.add_argument("arr", help="도착역")
+    parser.add_argument("date", help="출발일 YYYYMMDD")
+    parser.add_argument("time", help="희망 시작 시각 HHMMSS")
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    args.func(args)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/skills/srt-booking/scripts/srt_seats.py

@@ -0,0 +1,156 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import re
+from typing import TypedDict
+
+
+class SrtCar(TypedDict):
+    car_no: int
+    car_no_raw: str
+    room_class: str
+    available: bool
+    current: bool
+
+
+class SrtSeat(TypedDict):
+    seat: str
+    seat_no: str
+    available: bool
+    direction: str
+    position: str
+    notes: list[str]
+
+
+CAR_RE = re.compile(
+    r'<li class="scar-(?P<car>\d+)(?P<class>[^"]*)">(?P<body>.*?)</li>',
+    re.DOTALL,
+)
+SEAT_LINK_RE = re.compile(
+    r"<a[^>]+selectSeatInfo\(this,\s*'(?P<seat_no>[^']+)',\s*'(?P<seat>[^']+)'\)[^>]*>"
+    r".*?<em>\((?P<detail>[^)]*)\)</em>",
+    re.DOTALL,
+)
+SEAT_SPAN_RE = re.compile(
+    r"<span>\s*(?P<seat>\d+[A-Z])\s*<strong><em>\((?P<detail>[^)]*)\)</em></strong></span>",
+    re.DOTALL,
+)
+TAG_RE = re.compile(r"<[^>]+>")
+
+
+def strip_tags(value: str) -> str:
+    return TAG_RE.sub(" ", value).replace("\xa0", " ").strip()
+
+
+def parse_detail(detail: str) -> tuple[str, str, list[str]]:
+    parts = [part.strip() for part in detail.split(",")]
+    direction = next((part for part in parts if part in {"정방향", "역방향"}), "unknown")
+    position = next((part for part in parts if part in {"창측", "내측", "1인석"}), "unknown")
+    notes = [part for part in parts if part not in {direction, position} and part]
+    return direction, position, notes
+
+
+def parse_cars(html: str) -> list[SrtCar]:
+    cars: list[SrtCar] = []
+    for match in CAR_RE.finditer(html):
+        body = match.group("body")
+        text = strip_tags(body)
+        room_class = "특실" if "특실" in text else "일반실"
+        css_class = match.group("class")
+        has_link = "selectScarInfo" in body
+        cars.append(
+            {
+                "car_no": int(match.group("car")),
+                "car_no_raw": f"{int(match.group('car')):04d}",
+                "room_class": room_class,
+                "available": has_link and "off" not in css_class.split(),
+                "current": "on" in css_class.split(),
+            }
+        )
+    return cars
+
+
+def parse_seats(html: str) -> list[SrtSeat]:
+    seats: list[SrtSeat] = []
+    seen: set[str] = set()
+    for match in SEAT_LINK_RE.finditer(html):
+        direction, position, notes = parse_detail(match.group("detail"))
+        seat = match.group("seat")
+        seen.add(seat)
+        seats.append(
+            {
+                "seat": seat,
+                "seat_no": match.group("seat_no"),
+                "available": True,
+                "direction": direction,
+                "position": position,
+                "notes": notes,
+            }
+        )
+    for match in SEAT_SPAN_RE.finditer(html):
+        seat = match.group("seat")
+        if seat in seen:
+            continue
+        direction, position, notes = parse_detail(match.group("detail"))
+        seats.append(
+            {
+                "seat": seat,
+                "seat_no": "",
+                "available": False,
+                "direction": direction,
+                "position": position,
+                "notes": notes,
+            }
+        )
+    return seats
+
+
+def parse_seat_label(seat_label: str) -> tuple[int | None, str]:
+    match = re.match(r"^(\d+)([A-Z])$", seat_label)
+    if match is None:
+        return None, ""
+    return int(match.group(1)), match.group(2)
+
+
+def car_center_priority(car: SrtCar, car_numbers: list[int]) -> tuple[float, int]:
+    if not car_numbers:
+        return (0.0, car["car_no"])
+    center = (min(car_numbers) + max(car_numbers)) / 2
+    return (abs(car["car_no"] - center), car["car_no"])
+
+
+def sort_cars_for_booking(cars: list[SrtCar], priority: str = "center") -> list[SrtCar]:
+    match priority:
+        case "center":
+            car_numbers = [car["car_no"] for car in cars]
+            return sorted(cars, key=lambda car: car_center_priority(car, car_numbers))
+        case "low":
+            return sorted(cars, key=lambda car: car["car_no"])
+        case "high":
+            return sorted(cars, key=lambda car: car["car_no"], reverse=True)
+        case _:
+            raise ValueError(f"unsupported car priority: {priority}")
+
+
+def seat_preference_key(seat: SrtSeat, priority: str = "forward-window") -> tuple[int, int, int, str]:
+    row, column = parse_seat_label(seat["seat"])
+    forward_rank = 0 if seat["direction"] == "정방향" else 1
+    window_rank = 0 if seat["position"] in {"창측", "1인석"} else 1
+    row_rank = 999 if row is None else row
+    match priority:
+        case "forward-window":
+            return (forward_rank, window_rank, row_rank, column)
+        case "window-forward":
+            return (window_rank, forward_rank, row_rank, column)
+        case "row-low":
+            return (row_rank, forward_rank, window_rank, column)
+        case _:
+            raise ValueError(f"unsupported seat priority: {priority}")
+
+
+def sort_seats_for_booking(seats: list[SrtSeat], priority: str = "forward-window") -> list[SrtSeat]:
+    return sorted(seats, key=lambda seat: seat_preference_key(seat, priority))
+
+
+sort_cars = sort_cars_for_booking
+sort_seats = sort_seats_for_booking

package/skills/srt-booking/skill.json

@@ -0,0 +1,20 @@
+{
+  "name": "srt-booking",
+  "description": "Search, reserve, inspect, and cancel SRT tickets in Korea with the SRTrain library. Use when the user asks for SRT seat availability, booking, canceling, or sold-out retry plans. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.",
+  "profiles": [
+    "vault",
+    "browser",
+    "action:booking"
+  ],
+  "frontmatter": "name: srt-booking\ndescription: Search, reserve, inspect, and cancel SRT tickets in Korea with the SRTrain library. Use when the user asks for SRT seat availability, booking, canceling, or sold-out retry plans. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.\nlicense: MIT\nmetadata:\n  category: travel\n  locale: ko-KR\n  phase: v1",
+  "bundle": [
+    {
+      "from": "scripts/srt_booking.py",
+      "to": "scripts/srt_booking.py"
+    },
+    {
+      "from": "scripts/srt_seats.py",
+      "to": "scripts/srt_seats.py"
+    }
+  ]
+}

package/skills/subway-lost-property/instruction.md

@@ -0,0 +1,93 @@
+# Subway Lost Property
+
+## What this skill does
+
+지하철에서 잃어버린 물건을 찾기 위해 공식 경로를 구조화한다.
+
+- LOST112 `습득물 목록 조회`에 넣을 검색 조건을 정리한다.
+- 서울교통공사 유실물센터 진입점을 함께 안내한다.
+- 공개 API가 명확하지 않은 상태라 v1은 **안내형/하이브리드** 범위로 유지한다.
+
+## When to use
+
+- "강남역에서 지갑 잃어버렸는데 어디서 찾아?"
+- "2호선 지하철 분실물 조회 방법 알려줘"
+- "서울 지하철 유실물 공식 사이트로 바로 찾게 도와줘"
+
+## Inputs
+
+- 필수: 역명 또는 보관장소 키워드
+- 선택: 물품명, 호선, 분실/습득 추정 기간
+
+## Official surfaces
+
+- LOST112 습득물 목록: `https://www.lost112.go.kr/find/findList.do`
+- 서울교통공사 유실물센터: `https://www.seoulmetro.co.kr/kr/page.do?menuIdx=541`
+
+LOST112 검색 폼에서 확인되는 핵심 필드는 아래와 같다.
+
+- `SITE=V`: 경찰 이외 기관(지하철, 공항 등)
+- `DEP_PLACE`: 보관장소
+- `PRDT_NM`: 습득물명
+- `START_YMD`, `END_YMD`: 검색 기간
+
+## Workflow
+
+### 1) Ask for the minimum clues first
+
+바로 추정하지 말고 아래 정보를 먼저 받는다.
+
+- 어느 역/어느 구간인지
+- 물건 종류가 무엇인지
+- 대략 언제 잃어버렸는지
+- 서울교통공사(1~8호선) 범위인지, 다른 운영사인지
+
+### 2) Generate the official LOST112 search payload
+
+repo helper를 그대로 써도 된다.
+
+```bash
+python3 scripts/subway_lost_property.py \
+  --station 강남역 \
+  --item 지갑 \
+  --days 14
+```
+
+helper는 기본적으로 `SITE=V` 를 사용하고, 역명/물품명/기간을 LOST112 form payload와 **referer까지 포함한 runnable `curl` 예시**로 정리해 준다. 예시 `curl` 은 느린 공식 응답을 감안해 `--max-time 60` 을 포함하고, 응답 HTML을 `lost112-search-result.html` 로 저장한다.
+
+### 3) Optionally verify live reachability
+
+```bash
+python3 scripts/subway_lost_property.py \
+  --station 강남역 \
+  --item 지갑 \
+  --days 14 \
+  --verify-live
+```
+
+`--verify-live` 는 공식 페이지 접근 가능 여부만 보수적으로 확인한다. 사이트가 느리면 timeout을 그대로 보고하고 manual open으로 전환한다.
+
+### 4) Guide the user conservatively
+
+- 먼저 LOST112에서 역명 그대로 검색
+- 결과가 없으면 `강남`처럼 `역` 없는 키워드로 재검색
+- 필요하면 호선명도 추가 검색
+- 서울교통공사 유실물센터 페이지를 함께 열어 후속 안내 확인
+
+## Done when
+
+- 사용자가 공식 조회 경로를 바로 열 수 있다.
+- LOST112 검색 조건(`SITE=V`, 역명, 물품명, 기간)을 받았다.
+- 자동 조회 보장 범위와 manual fallback을 분명히 설명했다.
+
+## Failure modes
+
+- 공식 사이트 응답이 느리거나 timeout 발생
+- 역명이 실제 보관장소 표기와 달라 검색 결과가 비는 경우
+- 공개 API 부재로 자동 결과 수집이 안정적이지 않은 경우
+
+## Notes
+
+- v1은 공식 웹 흐름을 안전하게 안내하는 범위다.
+- 완전 자동 조회형으로 확장하려면 캡차/세션/동적 요청 안정성 재검증이 먼저 필요하다.
+- helper는 공식 HTTPS 진입점만 사용한다.