KTX 예약

このスキルの機能

korail2 の上に scripts/ktx_booking.py ヘルパーを積み上げて、KTX/Korail の検索、予約、予約確認、キャンセルを処理します。

最近の Korail アプリの Dynapath anti-bot チェックのため、元の korail2 0.4.0 のサンプル例だけでは MACRO ERROR が発生する可能性があります。このスキルは、ヘルパーが x-dynapath-m-token、Sid、最新のアプリバージョン(250601002)を付加して、実際の予約フローを復旧することを前提としています。

使用する場合

• 「ソウルからプサンへ行く KTX を探して」
• 「コレイル予約を確認して」
• 「KTX をキャンセルして」
• 「午前 9 時以降の KTX の中で一番早いやつを取ってって」
• 「N カードで割引列車を探して」
• 「私の N カードリストを見せて」
• 「N カード割引を適用して予約して」

使用しない場合

• SRT 予約の場合
• 実決済確定まで自動化する必要がある場合
• 認証情報を平文で入力する場合

前提条件

• Python 3.10 以上
• python3 -m pip install korail2-ncard pycryptodome

必須環境変数

• KSKILL_KTX_ID
• KSKILL_KTX_PASSWORD

認証情報の解決順序

1. すでに環境変数にある場合、そのまま使用します。
2. エージェント自体のシークレットボルト (1Password CLI、Bitwarden CLI、macOS Keychain など) を使用している場合、そこから取得して環境変数として注入しても構いません。
3. ~/.config/k-skill/secrets.env (デフォルトフォールバック) — プレーン dotenv ファイル、パーミッション 0600。
4. 何もない場合、ユーザーに尋ねて 2 または 3 に保存します。

デフォルトパスに保存することはフォールバックにすぎず、強制ではありません。

入力

• 出発駅
• 到着駅
• 日付：YYYYMMDD
• 希望開始時刻：HHMMSS
• 乗客数と乗客タイプ
• 座席選好度
• 検索結果からコピーした train_id

ワークフロー

0. パッケージがない場合はグローバルにインストール

python3 -c 'import korail2, Crypto' が失敗する場合は、別の実装で回避せず、まずグローバル Python パッケージのインストールを試みます。

python3 -m pip install korail2-ncard pycryptodome

1. 認証情報が利用可能であることを確認

KSKILL_KTX_ID、KSKILL_KTX_PASSWORD 環境変数が設定されているか確認します。ない場合は、上の認証情報の解決順序に従って確保します。

シークレットがないという理由でウェブサイトを直接スクレイプしたり、他の非公式なパスを探さないでください。

2. ヘルパーを通じて常に検索

常にヘルパーを通じて検索します。

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

デフォルトの --train-type は ktx です。ITX-청춘 (例：남춘천↔용산)、ITX-새마을、무궁화호 など KTX 以外の路線を取得する場合は、--train-type で指定します。

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 の値をそのまま渡す必要があり、安定した train_id マッチングが崩れません。

座席がない列車も候補に含める場合は --include-no-seats を付け、予約待機可能な列車も一緒に見たい場合は --include-waiting-list を付けます。

3. ショートリストを提示

予約前に常に以下を確認します。

• index
• train_id
• 出発/到着時刻
• 列車タイプ (train_type)
• 普通車/特室の可否
• 予約待機の可否

4. 対象列車が明確になった後にのみ予約

検索結果の train_id を選んでからのみ予約します。この値はヘルパーが列車番号/運行日/時刻/駅コードを組み合わせて作成した安定したセレクターなので、再検索時に同じ列車がまだあればそのままキャッチでき、なければ失敗します。

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

ITX など KTX 以外の路線を検索段階で選んだ場合は、予約にも同じく --train-type を渡します。

python3 scripts/ktx_booking.py reserve 남춘천 용산 20260503 150000 --train-id <train_id> --train-type itx-cheongchun --seat-option general-first

レスポンスには予約番号、運賃、購入期限が含まれます。決済は自動化しません。 座席がない場合は、検索段階で --include-waiting-list をオンにし、予約段階で --try-waiting で予約待機まで試みることができます。

4-1. N カード割引予約

N カード割引を適用するには、まず保有している N カードリストを検索してカード番号を確認します。

python3 scripts/ktx_booking.py ncard-list

N カードで割引列車を検索します (--ncard-index は ncard-list 結果の順番)。ncard-list はログ/シェル露出を減らすため、カード番号をマスクして出力します。

python3 scripts/ktx_booking.py ncard-search 대전 서울 20260512 100000 --ncard-index 1 --train-type ktx

レスポンスの train_id をコピーして reserve に同じ --ncard-index を付けて予約します。

python3 scripts/ktx_booking.py reserve 대전 서울 20260512 100000 \
  --train-id <train_id> \
  --ncard-index 1

--ncard-index を指定すると、--adults など乗客オプションは無視され、N カード乗客 1 名として処理されます。--ncard-no 直接入力もサポートされていますが、シェルヒストリーに残る可能性があるため推奨されません。決済は自動化しません。

N カード機能には korail2-ncard パッケージが必要です。ない場合は、該当コマンド実行時にインストール案内が出力されます。

5. 検査またはキャンセル

キャンセルは対象予約を再検索して特定した後にのみ進めます。

python3 scripts/ktx_booking.py reservations

python3 scripts/ktx_booking.py cancel <reservation_id>

完了時

• 検索の場合、列車候補が整理されている
• 予約の場合、予約結果と制限時間が確認されている
• キャンセルの場合、どの予約をキャンセルしたか記録に残っている

失敗モード

• ログイン失敗
• 売り切れ
• Korail anti-bot ルールの変更

注記

• scripts/ktx_booking.py は上流の korail2 anti-bot リグレッションを補うヘルパーです
• korail2 は KTX/Korail 専用のサーフェスなので、train type と passenger model が明確です
• 決済完了までは自動化しません
• 積極的なポーリングは避けます