介绍
# SRT Korean Train Service Skill
## 前置条件
- 必须在运行脚本前设置环境变量 `SRT_PHONE`（格式：`010-XXXX-XXXX`）和 `SRT_PASSWORD`。
## 参考
**环境变量：** | 变量 | 是否必填 | 描述 | |----------|----------|-------------| | `SRT_PHONE` | ✅ | SRT 账户手机号（必须包含连字符：`010-XXXX-XXXX`） | | `SRT_PASSWORD` | ✅ | SRT 账户密码 | | `SRT_DATA_DIR` | 可选 | 日志、缓存和状态文件的目录。默认为系统临时目录 (`/tmp/srt`)。 |
**车站名称**（仅限韩文）： 수서, 부산, 동대구, 대전, 천안아산, 오송, 광주송정, 울산, 포항, 경주, 김천구미, 익산, 전주, 목포, 신경주
**日期：** `YYYYMMDD` · **时间：** `HHMMSS` (例如 `200000` = 20:00)
---
## 命令
### 搜索列车 ```bash cd <project_dir> && uv run --with SRTrain python3 scripts/srt_cli.py train search \ --departure "수서" --arrival "동대구" --date "20260227" --time "200000" ``` 搜索参数和结果会被缓存（在 `SRT_DATA_DIR` 中），并且是 `reserve` 命令所必需的。
### 预订（一次性） ```bash cd <project_dir> && uv run --with SRTrain python3 scripts/srt_cli.py reserve one-shot --train-id "1" ``` `--train-id` 是搜索结果中从 1 开始的索引。必须先运行 `train search`。
### 查看预订 ```bash cd <project_dir> && uv run --with SRTrain python3 scripts/srt_cli.py reserve list --format json ```
### 取消预订 ```bash cd <project_dir> && uv run --with SRTrain python3 scripts/srt_cli.py reserve cancel \ --reservation-id "RES123456" --confirm ```
---
## 持续监控 (취소표 모니터링)
对于“一直尝试直到有座”的请求，**不要在 cron 任务内部进行循环**。 取而代之的是：作为持久化后台进程运行 `srt_cli.py reserve retry`，然后创建一个单独的 cron 任务来读取日志并报告。
### 步骤 1：搜索（填充缓存） ```bash cd <project_dir> && uv run --with SRTrain python3 scripts/srt_cli.py train search \ --departure "수서" --arrival "동대구" --date "20260227" --time "200000" ``` 从结果中记下目标列车的 `train_id`。
### 步骤 2：启动后台重试进程 ```bash LOG_FILE=<choose_any_path>.log PID_FILE=<choose_any_path>.pid cd <project_dir> && nohup uv run --with SRTrain python3 scripts/srt_cli.py reserve retry \ --train-id <id> --timeout-minutes 1440 --wait-seconds 10 \ --log-file "$LOG_FILE" > /dev/null 2>&1 & echo $! > "$PID_FILE" ```
脚本在启动时会打印 `LOG_FILE: <path>` —— 请捕获此输出以准确获知日志写入位置。 你也可以设置 `SRT_DATA_DIR` 来控制自动生成的日志和缓存文件的存放位置。
> **路径安全：** `SRT_DATA_DIR` 和 `--log-file` 会在运行时进行验证，确保其解析范围仅限于用户主目录或系统临时目录。超出这些边界的路径（例如通过 `../`）将被拒绝。
**`reserve retry` 选项：** | 选项 | 默认值 | 描述 | |--------|---------|-------------| | `--train-id` | (all) | 搜索结果中从 1 开始的索引；多个索引用逗号分隔 | | `--timeout-minutes` | 60 | 总时长。24 小时请使用 1440 | | `--wait-seconds` | 10 | 尝试之间的延迟 | | `--log-file` | auto | 显式指定日志文件路径（覆盖 `SRT_DATA_DIR` 默认值） |
需要关注的日志标记： - `=== 시도 #N` — 尝试次数 - `SUCCESS` — 预订成功（包含 예약번호, 좌석） - `TIMEOUT` — 超时未成功
### 步骤 3：创建定期报告的 cron 任务 创建一个 **独立的 agentTurn** cron 任务（每 15 分钟），执行以下操作： 1. 检查进程状态： ```bash cd <project_dir> && uv run --with SRTrain python3 scripts/srt_cli.py reserve status --pid-file <pid_file> ``` 输出 `RUNNING (<pid>)` 或 `NOT_RUNNING (...)` —— 不涉及 shell 命令替换。 2. 读取日志尾部：`tail -50 <log_file>` 3. 从日志中解析尝试次数和最后一次尝试时间 4. 向频道报告 5. 若日志中出现 `SUCCESS` → 提取 예약번호/좌석 信息，报告，并删除此 cron 任务 6. 若出现 `TIMEOUT` 或进程状态为 `NOT_RUNNING` → 报告，并删除此 cron 任务
cron 任务的消息必须包含其自身的任务 ID（创建后更新），以便其能够自我删除。
### 步骤 4：创建终止任务 在结束时间创建一个 **独立的 agentTurn** `at` 计划 cron 任务，执行以下操作： 1. 停止进程： ```bash cd <project_dir> && uv run --with SRTrain python3 scripts/srt_cli.py reserve stop --pid-file <pid_file> ``` 2. 根据 ID 删除报告 cron 任务 3. 读取最终日志并报告结果
---
## JSON 输出
**搜索结果项：** ```json { "train_number": "369", "departure_time": "200000", "arrival_time": "213600", "departure_station": "수서", "arrival_station": "동대구", "seat_available": false, "general_seat": "매진", "special_seat": "매진", "train_id": "1" } ```
**预订结果：** ```json { "success": true, "data": { "reservation_id": "RES123456", "train_number": "369", "seat_number": "3A", "payment_required": true } } ```
退出码：`0` = 成功 · `1` = 可重试（无座） · `2` = 严重错误
---
## 错误处理
| 错误 | 原因 | 解决方案 | |-------|-------|-----------| | `AuthenticationFailed` | 凭证错误 | 检查 `SRT_PHONE` / `SRT_PASSWORD` | | `NoSeatsAvailable` | 已售罄 | 使用 `--retry` 或尝试其他列车 | | `StationNotFound` | 名称无效 | 使用上述韩文车站名称 | | `NoTrainsFound` | 未找到列车 | 尝试其他日期/时间 | | `RateLimitExceeded` | 尝试次数过多 | 等待几分钟 |
---
## 自然语言处理
从韩文输入中提取： - 车站 → 韩文名称（수서, 동대구 等） - 日期 → 相对日期（“내일”, “다음주 금요일”）转换为 YYYYMMDD - 时间 → （“20시 이후”, “오후 2시”）转换为 HHMMSS - 乘客数量 → 未指定时默认为 1
**模式：** - “검색해줘” → `train search` - “예약해줘”（一次性） → `train search` 然后 `reserve one-shot` - “취소표 나오면 잡아줘 / 될 때까지 돌려줘” → 上述持续监控流程 - “내 예약 확인해줘” → `reserve list` - “취소해줘” → `list` 然后 `cancel`
## 付款说明 预订后，必须在约 20 分钟内通过 SRT 应用或 <https://etk.srail.kr> 完成支付。