@nomadamas/k-skill 0.2.5 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nomadamas/k-skill",
-  "version": "0.2.5",
+  "version": "0.3.0",
   "description": "k-skill unified CLI: assembles runtime-aware skill instructions and ships bundled helper files",
   "license": "MIT",
   "bin": {

package/skills/ktx-booking/instruction.md

@@ -1,244 +1,61 @@
-# KTX Booking
+# KTX Official Timetable Lookup
 
 ## What this skill does
 
-`korail2` 위에 `scripts/ktx_booking.py` helper 를 얹어 KTX/Korail 조회, 호차별 좌석번호 확인, 예약, 예약 확인, 취소를 처리한다.
+한국철도공사가 로그인 없이 공개하는 최신 KTX 운행시간표 XLSX를 내려받아 출발역·도착역·출발시간 조건에 맞는 열차를 찾는다.
 
-최근 Korail 앱의 Dynapath anti-bot 체크 때문에 원본 `korail2` 0.4.0 예제만으로는 `MACRO ERROR` 가 날 수 있다. 이 스킬은 helper 가 `x-dynapath-m-token`, `Sid`, 최신 app version(`250601002`)을 붙여 실제 예매 흐름을 복구하는 것을 전제로 한다.
+이 스킬은 **공식 계획 시간표 조회 전용**이다.
 
-## When to use
+- 회원 로그인, credential, Korail 앱 내부 API를 사용하지 않는다.
+- Dynapath 또는 anti-bot token을 생성·재현·우회하지 않는다.
+- 실시간 잔여석, 실제 운휴·지연, 호차·좌석번호는 조회하지 않는다.
+- 예약, 예약대기, 좌석 선점, 결제, 취소, 자동 재조회는 실행하지 않는다.
+- 구매와 실시간 운행 확인은 공식 코레일 페이지에서 사용자가 직접 진행한다.
 
-- "서울에서 부산 가는 KTX 찾아줘"
-- "코레일 예약 확인해줘"
-- "KTX 취소해줘"
-- "오전 9시 이후 KTX 중 제일 빠른 거 잡아줘"
-- "KTX 남은 좌석 번호 확인해줘"
-- "이 열차 콘센트 있는 꿀팁 좌석부터 보여줘"
-- "KTX 5호차 남은 자리만 봐줘"
-- "예약하기 전에 호차별 좌석 확인해줘"
-- "N카드로 할인 열차 찾아줘"
-- "내 N카드 목록 보여줘"
-- "N카드 할인 적용해서 예약해줘"
+실행 환경에는 Python 3.11 이상과 `uv`가 필요하다. `uv`가 helper에 고정된 `openpyxl` 환경을 자동 설치한다.
 
-## 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
-npx -y @nomadamas/k-skill@0 exec ktx-booking scripts/ktx_booking.py -- search 서울 부산 20260328 090000 --limit 5
-```
-
-기본 `--train-type` 은 `ktx` 다. ITX-청춘(예: 남춘천↔용산)·ITX-새마을·무궁화호처럼 KTX 외 노선을 잡으려면 `--train-type` 으로 지정한다.
-
-```bash
-npx -y @nomadamas/k-skill@0 exec ktx-booking 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
-npx -y @nomadamas/k-skill@0 exec ktx-booking scripts/ktx_booking.py -- seats 서울 부산 20260328 090000 --train-id <train_id>
-```
-
-일반실/특실은 `--room` 으로 나눈다.
-
-```bash
-npx -y @nomadamas/k-skill@0 exec ktx-booking scripts/ktx_booking.py -- seats 서울 부산 20260328 090000 --train-id <train_id> --room special
-```
-
-남은 좌석번호만 보고 싶으면 `--available-only` 를 쓴다.
-
-```bash
-npx -y @nomadamas/k-skill@0 exec ktx-booking 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
-npx -y @nomadamas/k-skill@0 exec ktx-booking scripts/ktx_booking.py -- seats 서울 부산 20260328 090000 --train-id <train_id> --car-no 5 --available-only
-```
-
-콘센트 꿀팁 자리부터 확인하려면 `--power-only` 를 붙인다. 응답의 `power_outlet` 은 `direct`, `adjacent`, `none` 중 하나다.
-
-```bash
-npx -y @nomadamas/k-skill@0 exec ktx-booking scripts/ktx_booking.py -- seats 서울 부산 20260328 090000 --train-id <train_id> --available-only --power-only
-```
-
-`seats` 도 `search` 와 같은 `--train-type` 을 넘겨야 한다. ITX-청춘 등 KTX 외 열차를 조회했다면 상세 좌석 조회에도 같은 값을 사용한다.
-
-```bash
-npx -y @nomadamas/k-skill@0 exec ktx-booking 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 이므로, 재조회 시 같은 열차가 아직 있으면 그대로 잡고 없으면 실패한다.
+## Commands
 
 ```bash
-npx -y @nomadamas/k-skill@0 exec ktx-booking scripts/ktx_booking.py -- reserve 서울 부산 20260328 090000 --train-id <train_id> --seat-option general-first
+npx -y @nomadamas/k-skill@0 exec ktx-booking scripts/ktx_booking.py -- \
+  search --dep 서울 --arr 부산 --date 20260819 --time 0600 --time-limit 1200 --limit 5
 ```
 
-ITX 등 KTX 외 노선을 search 단계에서 골랐다면 reserve 에도 똑같이 `--train-type` 을 넘긴다.
-
 ```bash
-npx -y @nomadamas/k-skill@0 exec ktx-booking scripts/ktx_booking.py -- reserve 남춘천 용산 20260503 150000 --train-id <train_id> --train-type itx-cheongchun --seat-option general-first
+npx -y @nomadamas/k-skill@0 exec ktx-booking scripts/ktx_booking.py -- source
 ```
 
-응답에는 예약번호, 운임, 구입기한이 포함된다. 이 시점에 **좌석 확보는 완료되었다**고 안내한다. generic fallback에서는 결제를 handoff하고, 돌쇠에서는 아래 결제 단계로 계속 진행한다.
-좌석이 없을 때는 조회 단계에서 `--include-waiting-list` 를 켜고 예약 단계에서 `--try-waiting` 으로 예약 대기까지 시도할 수 있다.
-
-### 5-1. N-card discounted reservation
-
-N카드 할인을 적용하려면 먼저 보유 N카드 목록을 조회해 카드 번호를 확인한다.
-
-```bash
-npx -y @nomadamas/k-skill@0 exec ktx-booking scripts/ktx_booking.py -- ncard-list
-```
-
-N카드로 할인 열차를 조회한다 (`--ncard-index` 는 `ncard-list` 결과의 순번). `ncard-list` 는 로그/셸 노출을 줄이기 위해 카드 번호를 마스킹해 출력한다.
-
-```bash
-npx -y @nomadamas/k-skill@0 exec ktx-booking scripts/ktx_booking.py -- ncard-search 대전 서울 20260512 100000 --ncard-index 1 --train-type ktx
-```
-
-응답의 `train_id` 를 복사해 `reserve` 에 같은 `--ncard-index` 를 붙여 예약한다.
-
-```bash
-npx -y @nomadamas/k-skill@0 exec ktx-booking 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
-npx -y @nomadamas/k-skill@0 exec ktx-booking scripts/ktx_booking.py -- reservations
-```
+## Inputs
 
-취소 실행 직전에 `clarify`로 예약번호, 열차, 날짜·시각, 승객, 환불/위약금 정보를 확인하고 승인받는다.
+- `--dep`: 출발역명. `서울`과 `서울역` 모두 허용한다.
+- `--arr`: 도착역명.
+- `--date`: `YYYYMMDD`.
+- `--time`: 가장 이른 출발시각 `HHMM`, 기본 `0000`.
+- `--time-limit`: 가장 늦은 출발시각 `HHMM`, 기본 `2359`.
+- `--limit`: 최대 결과 수, 1~50.
 
-```bash
-npx -y @nomadamas/k-skill@0 exec ktx-booking scripts/ktx_booking.py -- cancel <reservation_id>
-```
+## Output
 
-## Done when
+- `count`
+- `trains[]`: `train_no`, `train_type`, `dep`, `arr`, `dep_time`, `arr_time`
+- `date`
+- `schedule_note`
+- `source`: 공식 게시물 제목·게시일·XLSX URL·게시판 URL
+- `booking_url`
 
-- 조회면 열차 후보가 정리되어 있다
-- 좌석 상세 확인이면 호차별 남은 좌석번호와 필요한 꿀팁 조건이 정리되어 있다
-- 예약이면 예약 결과와 제한 시간이 확인되어 좌석 확보 완료를 안내했다
-- 돌쇠의 예매 완료 요청이면 `clarify` 승인 후 결제 완료 상태와 영수증/예약번호를 확인했다
-- 취소면 어떤 예약을 취소했는지 남아 있다
+항상 이 결과는 **공개 운행계획 시간표**이며 실시간 잔여석·운휴·지연 정보가 아니라는 점을 명시한다.
 
 ## Failure modes
 
-- 로그인 실패
-- 매진
-- Korail anti-bot 규칙 변경
+- 공식 시간표 게시판 또는 XLSX 다운로드 실패
+- 요청일에 적용되는 KTX 시간표 없음
+- XLSX 형식 변경으로 header를 찾지 못함
+- 요청 구간·시간대 결과 없음: 오류가 아니라 `count: 0`
+- 잘못된 날짜·시간·limit: 실행 전 오류
 
-## Notes
+## Hard boundaries
 
-- `scripts/ktx_booking.py` 는 upstream `korail2` anti-bot 회귀를 보완하는 helper 다
-- `korail2` 는 KTX/Korail 전용 표면이라 train type 과 passenger model 이 분명하다
-- 결제 자동화 금지는 generic fallback에만 적용한다. 돌쇠에서는 `clarify` 승인 후 공식 결제 표면으로 완료한다
-- aggressive polling 은 피한다
+- 로그인·credential 요청 금지
+- `ScheduleView`, `korail2`, Dynapath 등 앱 내부 경로 사용 금지
+- 예약·결제·취소·좌석 선점 금지
+- CAPTCHA·인증·anti-bot 통제 우회 금지

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

@@ -0,0 +1,10 @@
+# KTX 공식 시간표 조회 관련 고지
+
+이 스킬은 한국철도공사가 공개한 시간표 게시판과 XLSX 첨부파일만 읽는다.
+
+- 회원 로그인과 credential을 사용하지 않는다.
+- Korail 앱 내부 API, `ScheduleView`, Dynapath token을 호출·생성·재현하지 않는다.
+- CAPTCHA, anti-bot 또는 접근통제를 우회하지 않는다.
+- 실시간 잔여석, 예약, 좌석 선점, 결제, 취소를 실행하지 않는다.
+
+결과는 공개 운행계획 시간표이며 실제 운휴·지연·잔여석 정보가 아니다. 실제 이용 전에는 공식 코레일 예매 페이지에서 다시 확인해야 한다.