mirror of https://github.com/NomaDamas/k-skill.git synced 2026-06-24 02:04:11 +00:00

iamiks 24feb3edca feat(ktx-booking): 좌석 탐색 우선순위 개선

KTX 상세 좌석 조회에서 가운데 호차를 먼저 탐색하고,
같은 호차 안에서는 콘센트 좌석과 순방향 좌석을 우선 노출합니다.
#294 요구사항을 우선순위 함수와 command_seats 회귀 테스트로 고정합니다.

Constraint: #294는 기존 seats 공개 인터페이스 유지를 요구함
Rejected: 예약 API에 객차/좌석 번호를 직접 주입 | 현재 helper 예약 경로가 해당 선택 인자를 노출하지 않음
Confidence: high
Scope-risk: narrow
Directive: 좌석 우선순위 변경 시 command_seats 출력 순서 테스트를 함께 갱신할 것
Tested: PYTHONPATH=.:scripts python3 -m unittest scripts.test_ktx_booking
Tested: node --test scripts/skill-docs.test.js
Tested: npm run typecheck
Tested: npm run ci

2026-05-28 22:49:31 +09:00

5.1 KiB

Raw Permalink Blame History

KTX 예매 가이드

이 기능으로 할 수 있는 일

KTX/Korail 열차 조회
좌석 가능 여부 확인
호차별 남은 좌석번호 확인
콘센트 꿀팁 좌석 필터링
예약 진행
예약 내역 확인
예약 취소

먼저 필요한 것

Python 3.10+
python3 -m pip install korail2 pycryptodome
공통 설정 가이드 완료
보안/시크릿 정책 확인

필요한 환경변수

KSKILL_KTX_ID
KSKILL_KTX_PASSWORD

Credential resolution order

이미 환경변수에 있으면 그대로 사용한다.
에이전트가 자체 secret vault(1Password CLI, Bitwarden CLI, macOS Keychain 등)를 사용 중이면 거기서 꺼내 환경변수로 주입해도 된다.
~/.config/k-skill/secrets.env (기본 fallback) — plain dotenv 파일, 퍼미션 0600.
아무것도 없으면 유저에게 물어서 2 또는 3에 저장한다.

입력값

출발역
도착역
날짜: YYYYMMDD
희망 시작 시각: HHMMSS
인원 수와 승객 유형
좌석 선호
좌석 상세 조건: 객실 등급, 호차 번호, 남은 좌석만 보기, 콘센트 좌석 우선
조회 결과에서 복사한 train_id

왜 helper 를 쓰는가

현재 공개 배포된 korail2 0.4.0 예제만으로는 Korail 모바일 표면의 Dynapath anti-bot 체크에 막혀 MACRO ERROR 가 발생할 수 있다.

이 저장소의 scripts/ktx_booking.py 는 다음 값을 보강해서 실제 KTX 예약 흐름을 복구한다.

x-dynapath-m-token
Sid
최신 app version 250601002
최신 Android user-agent

기본 흐름

korail2 또는 pycryptodome 패키지가 없으면 다른 방법으로 우회하지 말고 먼저 전역 설치한다.
KSKILL_KTX_ID, KSKILL_KTX_PASSWORD 가 없으면 credential resolution order에 따라 확보한다.
helper 로 먼저 열차를 조회한다.
후보 열차의 index, train_id, 출발/도착 시각, KTX 여부, 좌석 여부를 보여준다.
사용자가 좌석번호, 호차별 잔여석, 콘센트 꿀팁 좌석을 물으면 seats 로 상세 좌석을 먼저 확인한다.
대상 열차가 명확할 때만 예약한다.
예약 확인/취소는 대상 예약을 다시 식별한 뒤 진행한다.

예시

조회:

python3 scripts/ktx_booking.py search 서울 부산 20260328 090000 --limit 5

좌석이 없는 열차까지 같이 보고 싶으면 --include-no-seats, 예약 대기 가능 열차도 같이 보고 싶으면 --include-waiting-list 를 붙인다.

응답 JSON 의 train_id 는 검색 시점의 정확한 열차를 가리키는 stable selector 다. 예약할 때는 이 값을 그대로 복사해서 쓴다. 같은 열차가 더 이상 조회되지 않으면 helper 가 실패하고 새로 조회하게 만든다.

상세 좌석 확인:

python3 scripts/ktx_booking.py seats 서울 부산 20260328 090000 --train-id <train_id>

남은 좌석번호만 확인:

python3 scripts/ktx_booking.py seats 서울 부산 20260328 090000 --train-id <train_id> --available-only

특정 호차를 지정하지 않으면 seats 는 승강장 이동 거리가 짧은 가운데 호차부터 탐색한다. 각 호차 안에서는 콘센트 힌트가 있는 좌석을 먼저, 같은 조건에서는 순방향 좌석을 먼저 반환한다.

특정 호차의 남은 좌석만 확인:

python3 scripts/ktx_booking.py seats 서울 부산 20260328 090000 --train-id <train_id> --car-no 5 --available-only

콘센트 꿀팁 좌석부터 확인:

python3 scripts/ktx_booking.py seats 서울 부산 20260328 090000 --train-id <train_id> --available-only --power-only

특실 좌석을 확인하려면 --room special, KTX 외 열차를 조회했다면 search 와 같은 --train-type 을 함께 넘긴다.

python3 scripts/ktx_booking.py seats 남춘천 용산 20260503 150000 \
  --train-id <train_id> \
  --train-type itx-cheongchun \
  --available-only

seats 응답은 호차별 remaining_seats, available_seats, 좌석별 순방향/역방향, 창측/내측, 좌석 종류, 문 근처 여부, 콘센트 힌트를 JSON 으로 반환한다. 이 단계는 좌석을 선택하거나 선점하지 않고, 예약 전 확인만 한다.

예약:

python3 scripts/ktx_booking.py reserve 서울 부산 20260328 090000 --train-id <train_id> --seat-option general-first

좌석이 없을 때 예약 대기까지 시도하려면 조회 단계에서도 --include-waiting-list 를 켜고, 예약 단계에서 --try-waiting 을 추가한다.

예약 확인:

python3 scripts/ktx_booking.py reservations

취소:

python3 scripts/ktx_booking.py cancel <reservation_id>

응답은 JSON 으로 나오며 예약번호, 구입기한, 운임 확인에 바로 쓸 수 있다. 결제는 제외 하고 예약까지만 자동화한다.

주의할 점

SRT 예매와는 별도 표면이므로 혼용하지 않는다.
credential은 환경변수로 주입한다.
결제 완료까지 자동화하는 범위는 아니다.
Korail anti-bot 규칙이 다시 바뀌면 helper 도 함께 점검해야 한다.

5.1 KiB Raw Permalink Blame History