12306 Train Assistant

核心用法

12306-train-assistant 是一个基于 Python CLI 的 12306 功能封装层，通过调用 client.py 脚本实现铁路票务自动化操作。核心能力覆盖四大场景：余票与中转查询（left-ticket、transfer-ticket）、经停站解析（route）、登录态管理（status、qr-login-create、密码登录）以及订单生命周期管理（订票 book、中转订票 transfer-book、候补 candidate-*）。

显著优点

1. 全链路覆盖：唯一同时支持直达订票、智能中转规划、候补队列管理的开源 CLI 方案，填补了官方 API 缺乏自动化接口的空白。
2. 灵活的中转策略：transfer-ticket 支持自动推荐换乘站或指定中转城市，transfer-book 可将中转方案一键转化为待支付订单，大幅降低跨线抢票认知成本。
3. 双模式登录：支持传统密码登录（含短信验证风控场景）与二维码登录，后者创建后自动后台轮询状态，兼顾安全与自动化。
4. 预检机制：--dry-run 参数允许在最终提交前验证乘客信息、余票状态与席别可用性，降低误操作风险。

潜在缺点与局限性

• 部署门槛：需自行准备 Python 环境、安装依赖并维护 client.py 仓库，非技术用户难以直接使用。
• 风控敏感：高频调用易触发 12306 反爬机制（返回 error.html），需人工处理验证码或降低请求频率。
• 支付链路缺陷：脚本返回的 pay_url 可能无法完成网页支付，用户仍需跳转至官方 App 的“待支付订单”完成最终支付，自动化闭环不完整。
• 站名解析依赖：依赖内置站名字典，生僻别名或新站可能存在匹配失败。

适合人群

铁路出行高频用户、具备基础运维能力的技术人员、需在服务器/定时任务中执行抢票策略的开发者。

常规风险

• 账号安全风险：明文存储密码或会话 Cookie 可能导致泄露，建议配合环境变量 KYFW_PASSWORD 与权限隔离。
• 合规性边界：自动化订票可能违反 12306 用户协议，存在账号限制或封禁可能。
• 稳定性风险：官方接口无版本承诺，字段变更可能导致脚本失效。

核心用法

12306 Train Assistant 是一款基于 Python CLI 的铁路出行辅助工具，通过与 12306 官方 API（kyfw.12306.cn）直连交互，实现火车票查询、预订、支付的全流程自动化。核心功能覆盖四大场景：

查询类操作：left-ticket 实时余票查询支持按日期、区间、席别筛选；transfer-ticket 智能中转规划可自动推荐或指定换乘站；route 经停站查询支持车次号自动解析，无需用户记忆复杂的内部车次编码。

预订类操作：book 直达成品票预订与 transfer-book 中转联程预订均支持 --dry-run 预检模式，确认乘客信息、席别匹配、价格计算无误后再正式提交，避免误操作。candidate-submit 候补排队功能在目标车次无票时自动加入候补队列。

账户管理：支持密码登录（国密 SM4 加密传输）、短信验证登录及二维码扫码登录三种方式，status 实时检测登录态，passengers 同步乘车人信息，orders 查询未出行与历史订单。

支付衔接：下单成功后返回 12306 官方支付链接，同时明确引导至官方 App「待支付订单」完成最终付款，确保交易链路合规。

显著优点

官方直连，数据权威：所有请求直达 12306 官方域名，车次时刻、余票状态、票价信息与官网实时同步，杜绝第三方平台的滞后与加价问题。

功能完备，覆盖全场景：从简单的余票查询到复杂的中转方案规划，从即时抢票到候补排队，从单人预订到多人批量选座，满足商务出行、节假日返乡、长途旅游等多样化需求。

交互友好，容错性强：支持中文/拼音/三字码多种站名输入，自动解析「今天/明天/后天」等相对日期，失败时给出明确的修复建议（如参数缺失、站名不匹配、风控限制等）。

架构清晰，可扩展性好：3839 行代码采用面向对象设计，模块化封装 API 调用、数据解析、错误处理，便于后续功能迭代。

潜在缺点与局限性

风控敏感性：12306 官方对高频请求、异常 IP 有严格的风控策略，连续查询或下单可能触发 error.html 拦截，需人工等待或降低调用频率。

中转方案非穷尽：transfer-ticket 返回的结果依赖 12306 官方推荐算法，不保证覆盖所有可行中转组合，极端路线（如深圳-拉萨）可能需要人工补充方案。

支付链路受限：虽然能获取支付链接，但实测网页端支付成功率不稳定，最终仍需跳转至官方 App 完成，无法做到完全闭环。

站点别名覆盖不足：部分历史站名、俗称可能无法被自动解析为官方标准站名，需用户主动使用三字码或拼音查询。

适合的目标群体

• 高频铁路出行者：商务人士、异地通勤族需要快速批量查询多日期、多车次余票
• 节假日抢票用户：春运、国庆等高峰期的候补排队与中转方案规划需求
• 自动化爱好者：希望通过脚本实现定时查询、条件触发预订的技术用户
• 多账户管理团队：企业差旅管理、旅行社代订等需要集中管理多个 12306 账户的场景

使用风险

账户安全风险：虽然密码采用国密 SM4 加密传输，但 Cookie 本地存储于 ~/.kyfw_12306_cookies.json，若设备被他人物理访问存在凭证泄露风险。建议运行环境设置文件权限 600 并启用设备锁。

操作不可逆风险：book 与 transfer-book 正式提交后订单立即生成，30 分钟内未支付将自动取消并可能触发黑名单，预检模式（--dry-run）是必要的前置步骤。

依赖稳定性风险：完全依赖 12306 官方 API 可用性，高峰期服务降级或接口变更可能导致功能异常，建议关键出行预留人工候补通道。

来源可信度风险：维护者为个人开发者（tensor-x），GitHub 仓库创建于 2026 年 5 月，社区反馈与长期维护能力尚需观察，建议生产环境使用前先进行充分测试并关注更新动态。