ktx-booking

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

KTX Booking

KTX预订

What this skill does

该技能的功能

korail2

로 KTX/Korail 열차 조회, 예약, 예약 확인, 취소를 처리한다.

通过

korail2

处理KTX/Korail列车的查询、预订、预订确认、取消操作。

When to use

适用场景

"서울에서 부산 가는 KTX 찾아줘"
"코레일 예약 확인해줘"
"KTX 취소해줘"
"오전 9시 이후 KTX 중 제일 빠른 거 잡아줘"

"帮我找首尔到釜山的KTX"
"帮我确认Korail预订情况"
"帮我取消KTX预订"
"帮我订上午9点之后最快的KTX车次"

When not to use

不适用场景

SRT 예매인 경우
실결제 확정까지 자동화해야 하는 경우
credential을 평문으로 넣으려는 경우

预订SRT的情况
需要自动化完成实际付款确认的场景
需要明文输入凭据的场景

Prerequisites

前置要求

Python 3.10+
```
python3 -m pip install korail2
```
```
sops
```
and
```
age
```
installed
common setup reviewed in
```
../k-skill-setup/SKILL.md
```
secret policy reviewed in
```
../docs/security-and-secrets.md
```

Python 3.10+
```
python3 -m pip install korail2
```
已安装
```
sops
```
和
```
age
```
已查看
```
../k-skill-setup/SKILL.md
```
中的通用设置
已查看
```
../docs/security-and-secrets.md
```
中的密钥政策

Required secrets

所需密钥

```
KSKILL_KTX_ID
```
```
KSKILL_KTX_PASSWORD
```

```
KSKILL_KTX_ID
```
```
KSKILL_KTX_PASSWORD
```

Inputs

输入参数

출발역
도착역
날짜:
```
YYYYMMDD
```
희망 시작 시각:
```
HHMMSS
```
인원 수와 승객 유형
좌석 선호

出发站
到达站
日期：
```
YYYYMMDD
```
期望出发时间：
```
HHMMSS
```
人数及乘客类型
座位偏好

Workflow

工作流程

0. Install the package globally when missing

0. 包缺失时优先全局安装

python3 -c 'import korail2'

가 실패하면 다른 구현으로 우회하지 말고 전역 Python 패키지 설치를 먼저 시도한다.

bash

python3 -m pip install korail2

如果

python3 -c 'import korail2'

执行失败，不要改用其他实现，先尝试安装全局Python包。

bash

python3 -m pip install korail2

1. Stop for secure registration when secrets are missing

1. 缺少密钥时终止流程，要求完成安全配置

KSKILL_KTX_ID

KSKILL_KTX_PASSWORD

~/.config/k-skill/secrets.env

~/.config/k-skill/age/keys.txt

중 하나라도 없으면 다음 식으로 안내하고 멈춘다.

text

이 작업에는 KSKILL_KTX_ID, KSKILL_KTX_PASSWORD 가 필요합니다.
값을 채팅창에 붙여 넣지 말고 ~/.config/k-skill/secrets.env.plain 에 직접 채운 뒤
sops 로 ~/.config/k-skill/secrets.env 로 암호화해 주세요.
암호화가 끝나면 plaintext 파일은 지우고 bash scripts/check-setup.sh 로 다시 확인해 주세요.

시크릿이 없다는 이유로 웹사이트를 직접 긁거나 다른 비공식 경로를 찾지 않는다.

如果

KSKILL_KTX_ID

、

KSKILL_KTX_PASSWORD

、

~/.config/k-skill/secrets.env

、

~/.config/k-skill/age/keys.txt

中任意一项缺失，按以下提示告知用户并停止操作：

text

该操作需要KSKILL_KTX_ID、KSKILL_KTX_PASSWORD。
请不要将值粘贴到聊天框中，直接填写到 ~/.config/k-skill/secrets.env.plain 中，
再通过sops加密为 ~/.config/k-skill/secrets.env。
加密完成后请删除明文文件，执行 bash scripts/check-setup.sh 重新检查配置。

不要因为缺少密钥就直接爬取网站或寻找其他非官方途径。

2. Search first

2. 优先搜索车次

bash

SOPS_AGE_KEY_FILE="$HOME/.config/k-skill/age/keys.txt" \
sops exec-env "$HOME/.config/k-skill/secrets.env" 'python3 - <<'"'"'PY'"'"'
import os
from korail2 import Korail, TrainType

korail = Korail(
    os.environ["KSKILL_KTX_ID"],
    os.environ["KSKILL_KTX_PASSWORD"],
)
trains = korail.search_train(
    "서울",
    "부산",
    "20260328",
    "090000",
    train_type=TrainType.KTX,
)

for idx, train in enumerate(trains[:5], start=1):
    print(idx, train)
PY
'

bash

SOPS_AGE_KEY_FILE="$HOME/.config/k-skill/age/keys.txt" \
sops exec-env "$HOME/.config/k-skill/secrets.env" 'python3 - <<'"'"'PY'"'"'
import os
from korail2 import Korail, TrainType

korail = Korail(
    os.environ["KSKILL_KTX_ID"],
    os.environ["KSKILL_KTX_PASSWORD"],
)
trains = korail.search_train(
    "서울",
    "부산",
    "20260328",
    "090000",
    train_type=TrainType.KTX,
)

for idx, train in enumerate(trains[:5], start=1):
    print(idx, train)
PY
'

3. Present the shortlist

3. 展示可选车次列表

예매 전에 항상 아래를 확인한다.

출발/도착 시각
KTX 여부
좌석 가능 여부
가격

预订前必须确认以下信息：

出发/到达时间
是否为KTX车次
余票情况
票价

4. Reserve only after the target train is unambiguous

4. 仅在目标车次明确无歧义后再发起预订

bash

SOPS_AGE_KEY_FILE="$HOME/.config/k-skill/age/keys.txt" \
sops exec-env "$HOME/.config/k-skill/secrets.env" 'python3 - <<'"'"'PY'"'"'
import os
from korail2 import AdultPassenger, Korail, ReserveOption, TrainType

korail = Korail(
    os.environ["KSKILL_KTX_ID"],
    os.environ["KSKILL_KTX_PASSWORD"],
)
trains = korail.search_train(
    "서울",
    "부산",
    "20260328",
    "090000",
    train_type=TrainType.KTX,
)
reservation = korail.reserve(
    trains[0],
    passengers=[AdultPassenger()],
    option=ReserveOption.GENERAL_FIRST,
)
print(reservation)
PY
'

bash

SOPS_AGE_KEY_FILE="$HOME/.config/k-skill/age/keys.txt" \
sops exec-env "$HOME/.config/k-skill/secrets.env" 'python3 - <<'"'"'PY'"'"'
import os
from korail2 import AdultPassenger, Korail, ReserveOption, TrainType

korail = Korail(
    os.environ["KSKILL_KTX_ID"],
    os.environ["KSKILL_KTX_PASSWORD"],
)
trains = korail.search_train(
    "서울",
    "부산",
    "20260328",
    "090000",
    train_type=TrainType.KTX,
)
reservation = korail.reserve(
    trains[0],
    passengers=[AdultPassenger()],
    option=ReserveOption.GENERAL_FIRST,
)
print(reservation)
PY
'

5. Inspect or cancel

5. 查询或取消预订

취소는 대상 예약을 다시 조회해 식별한 뒤에만 진행한다.

bash

SOPS_AGE_KEY_FILE="$HOME/.config/k-skill/age/keys.txt" \
sops exec-env "$HOME/.config/k-skill/secrets.env" 'python3 - <<'"'"'PY'"'"'
import os
from korail2 import Korail

korail = Korail(
    os.environ["KSKILL_KTX_ID"],
    os.environ["KSKILL_KTX_PASSWORD"],
)
print(korail.reservations())
PY
'

取消操作必须先重新查询确认目标预订信息后再执行。

bash

SOPS_AGE_KEY_FILE="$HOME/.config/k-skill/age/keys.txt" \
sops exec-env "$HOME/.config/k-skill/secrets.env" 'python3 - <<'"'"'PY'"'"'
import os
from korail2 import Korail

korail = Korail(
    os.environ["KSKILL_KTX_ID"],
    os.environ["KSKILL_KTX_PASSWORD"],
)
print(korail.reservations())
PY
'

Done when

完成标准

조회면 열차 후보가 정리되어 있다
예약이면 예약 결과와 제한 시간이 확인되어 있다
취소면 어떤 예약을 취소했는지 남아 있다

查询场景：已整理好列车候选列表
预订场景：已确认预订结果和支付时限
取消场景：已留存取消的预订记录

Failure modes

失败场景

로그인 실패
매진
사이트 응답 형식 변경

登录失败
车票售罄
网站响应格式变更

Notes

注意事项

```
korail2
```
는 KTX/Korail 전용 표면이라 train type과 passenger model이 분명하다
결제 완료까지는 자동화하지 않는다
aggressive polling은 피한다

```
korail2
```
是KTX/Korail专用接口，车次类型和乘客模型明确
不自动化完成支付流程
避免频繁轮询请求