核心功能与用法
12306-train-assistant 是基于中国铁路官方 12306 平台的命令行辅助工具，通过封装 client.py 提供完整的票务操作链路：
| 功能模块 | 关键命令 | 典型场景 |
|---------|---------|---------|
| **余票查询** | `left-ticket` | 查某日北京→上海各车次余票，支持 `--json` 结构化输出 |
| **经停站查询** | `route` | 输入车次号（如 `G1033`）自动解析 `train_no`，无需记忆内部编号 |
| **中转换乘** | `transfer-ticket` / `transfer-book` | 深圳→拉萨无直达时智能推荐换乘方案，支持 `--dry-run` 预检 |
| **候补管理** | `candidate-*` | 提交候补、实时监控排队队列 (`candidate-queue`)、取消及支付 |
| **登录认证** | `login` / `qr-login-create` / `status` | 密码/短信/二维码三种登录方式，扫码后后台自动轮询登录状态 |
| **订单操作** | `book` / `orders` / `passengers` | 直接下单支持选座 (`--choose-seats`)，成功后可生成支付宝/微信/银联支付二维码 |
显著优点
1. 官方接口直连：数据实时同步 12306，余票、票价、候补状态无延迟
2. 中转智能推荐：自动计算最优换乘方案，支持指定中转站 (--middle) 人工干预
3. 自动化闭环：从查询→登录→下单→支付二维码生成，全流程 CLI 化，适合脚本化定时抢票
4. 风控友好设计：排队轮询 (max-wait-seconds/poll-interval 可调)、失败重试建议、降频提示
潜在局限与风险
| 限制类型 | 具体说明 |
|---------|---------|
| **合规边界** | 自动化高频请求可能触发 12306 风控（返回 `error.html`），需人工降低频率 |
| **支付依赖** | 网页支付链接可能失效，需 fallback 到 12306 App「待支付订单」手动完成 |
| **站点别名** | 极少数车站别名（如「北京」vs「北京南」）需用户确认标准站名 |
| **候补不确定性** | 候补成功率受退票/放票规律影响，工具仅提供队列位置查询，不承诺兑现 |
适合人群
- 高频商务/通勤者：需定期抢固定区间车票，可配合
cron定时执行 - 技术型用户：熟悉 CLI 操作，能将工具集成到个人自动化工作流
- 中转复杂行程：如进藏、进疆等需要多段联程规划的场景
常规风险提示
- 建议首次使用前执行
status→passengers确认登录态与乘车人信息 - 订票操作务必加
--dry-run预检，避免误提交 - 支付二维码生成依赖本地
qrcode/segno库，生产环境需提前安装 - 账号安全：密码支持环境变量
KYFW_PASSWORD注入，避免明文暴露在命令历史中
---
> 版本：v0.1.3 | 协议：需配合 12306 账号使用 | 输出格式：默认文本，可选 --json