ktx-booking

KTX 预订

技能功能

在 korail2 基础上使用 scripts/ktx_booking.py 辅助脚本处理 KTX/Korail 查询、车厢座位号查看、预订、预订确认和取消。

由于近期 Korail 应用的 Dynapath 反机器人检查，原始 korail2 0.4.0 示例可能会报 MACRO ERROR。本技能假设辅助脚本会附加 x-dynapath-m-token、Sid 和最新应用版本（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. 如果代理使用自有的秘密存储（如 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. 当用户询问好座位时查看详细座位

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 后进行预订。该值是辅助脚本根据列车编号/运行日期/时间/站代码生成的稳定选择器，因此重新查询时如果同一列车仍存在，则直接预订；否则失败。

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 尝试候补。

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，但不推荐，因为可能留在 shell 历史中。不自动完成支付。

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 专用接口，列车类型和乘客模型明确
• 不自动完成支付
• 避免频繁轮询