ktx-booking

KTX Booking

此技能功能

在 korail2 之上搭配 scripts/ktx_booking.py helper，處理 KTX/Korail 查詢、車廂座位號碼確認、預訂、訂單查詢及取消。

近期 Korail App 的 Dynapath 反機器人檢查，導致原始 korail2 0.4.0 範例可能出現 MACRO ERROR。此技能假設 helper 會附加 x-dynapath-m-token、Sid 及最新 app 版本 (250601002)，以還原實際訂票流程。

使用時機

• "幫我找首爾到釜山的 KTX"
• "幫我確認 Korail 訂票"
• "幫我取消 KTX"
• "幫我找上午 9 點後最快的 KTX"
• "幫我確認 KTX 剩餘座位號碼"
• "先顯示這班車有插座的推薦座位"
• "只看 KTX 第 5 車廂的剩餘座位"
• "預訂前先確認各車廂座位"
• "幫我找 N 卡折扣列車"
• "顯示我的 N 卡清單"
• "用 N 卡折扣幫我預訂"

不適用時機

• 如果是 SRT 訂票
• 需要自動完成實際付款時
• 試圖以明文輸入憑證時

前置需求

• Python 3.10+
• python3 -m pip install korail2-ncard pycryptodome

必要的環境變數

• KSKILL_KTX_ID
• KSKILL_KTX_PASSWORD

憑證解析順序

1. 若環境變數已存在則直接使用。
2. 若代理程式使用自有 secret vault（如 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 環境變數已設定。若無，則依上述憑證解析順序取得。

不因缺少 secret 而直接爬取網站或尋找其他非官方途徑。

2. 先透過 helper 查詢

一律透過 helper 進行查詢。

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. 當使用者詢問好位時，查看詳細座位

search 的座位可用性為列車層級標記。若使用者詢問「剩餘座位號碼」、「車廂座位」、「插座」、「推薦座位」、「靠窗/順向座位」、「預訂前確認座位」等具體座位資訊，則在預訂前呼叫 seats。

基本詳細座位查詢：

python3 scripts/ktx_booking.py seats 首爾 釜山 20260328 090000 --train-id <train_id>

一般室/特室可用 --room 區分。

python3 scripts/ktx_booking.py seats 首爾 釜山 20260328 090000 --train-id <train_id> --room special

若只想看剩餘座位號碼，請使用 --available-only。

python3 scripts/ktx_booking.py seats 首爾 釜山 20260328 090000 --train-id <train_id> --available-only

若未指定特定車廂，seats 會從月台移動距離較短的中央車廂開始搜尋。各車廂內的座位會先顯示有插座提示的座位 (direct、adjacent)，相同條件下則優先顯示順向座位。

若只想查看特定車廂，請使用 --car-no。

python3 scripts/ktx_booking.py seats 首爾 釜山 20260328 090000 --train-id <train_id> --car-no 5 --available-only

若想優先查看插座推薦座位，請加上 --power-only。回應中的 power_outlet 值為 direct、adjacent 或 none。

python3 scripts/ktx_booking.py seats 首爾 釜山 20260328 090000 --train-id <train_id> --available-only --power-only

seats 也需傳入與 search 相同的 --train-type。若查詢的是 ITX-青春等非 KTX 列車，詳細座位查詢也應使用相同值。

python3 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. 僅在目標列車明確後才預訂

僅在選定查詢結果的 train_id 後才進行預訂。此值為 helper 根據列車編號/運行日/時間/車站代碼組合而成的穩定選擇器，因此重新查詢時若同列車仍存在則可成功選取，否則會失敗。

python3 scripts/ktx_booking.py reserve 首爾 釜山 20260328 090000 --train-id <train_id> --seat-option general-first

若在 search 階段選擇了 ITX 等非 KTX 路線，則 reserve 也需傳入相同的 --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 嘗試候補。

5-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 等乘客選項會被忽略，並以 1 名 N 卡乘客處理。也支援直接輸入 --ncard-no，但可能留在終端機歷史中，因此不建議。不自動化付款。

N 卡功能需要 korail2-ncard 套件。若無此套件，執行相關指令時會顯示安裝提示。

6. 查詢或取消

取消前需先重新查詢目標訂單以確認身分。

python3 scripts/ktx_booking.py reservations

python3 scripts/ktx_booking.py cancel <reservation_id>

完成條件

• 查詢：已整理出列車候選清單
• 詳細座位確認：已整理出各車廂剩餘座位號碼及所需的推薦條件
• 預訂：已確認預訂結果與付款期限
• 取消：已記錄取消的訂單

失敗模式

• 登入失敗
• 售罄
• Korail 反機器人規則變更

備註

• scripts/ktx_booking.py 為輔助工具，用於補足上游 korail2 的反機器人回歸問題
• korail2 為 KTX/Korail 專用表面，列車類型與乘客模型明確
• 不自動化至付款完成
• 避免頻繁輪詢