核心用法
本技能通过封装 client.py 命令行工具，提供12306火车票查询与订票的完整自动化能力。核心功能覆盖六大场景：
1. 余票查询（left-ticket）
支持按日期、出发站、到达站查询实时余票，自动解析中文站名/拼音/三字码，可选 --json 输出结构化数据便于二次处理。
2. 中转换乘（transfer-ticket）
智能推荐中转方案，支持指定换乘站或自动最优推荐，可控制显示无座方案及结果数量。
3. 经停站查询（route）
创新支持 --train-code 自动解析内部车次号，用户只需提供常见车次号（如G1033）即可查询全程经停信息，大幅降低使用门槛。
4. 登录与状态管理
完整支持账号密码登录、短信验证码登录、登录状态检查、Cookie持久化，且多个命令内置自动补登录机制。
5. 乘车人与订单管理
查询常用乘车人、未出行订单、历史订单，支持日期范围筛选和分页。
6. 候补监控与订票
实时查看候补排队状态、进行中/已处理候补订单，支持 --dry-run 预检查订票流程。
显著优点
- 全流程覆盖：从查询、规划、监控到下单的完整链路，无需跳转官方App
- 智能参数解析：自动转换相对日期（今天/明天/后天），支持多种站名输入格式
- 人性化设计：
--train-code自动解析避免用户查找复杂的内部车次号 - 风控感知：内置失败重试建议与频率控制提示
- 灵活输出：默认文本易读，可选JSON便于集成
潜在缺点与局限性
- 依赖非官方接口：基于逆向的CLI工具，存在接口变更导致失效的风险
- 风控限制：高频请求可能触发12306反爬机制，需人工介入处理验证码
- 支付环节中断：订票流程止于提交订单，支付仍需前往官方渠道完成
- 地域限制：仅支持中国大陆铁路网络，国际列车等特殊场景覆盖不全
- 维护依赖：核心
client.py需持续更新以适配12306接口变化
适合人群
- 高频出差需批量查询规划行程的商务人士
- 春运/节假日抢票需实时监控余票与候补状态的用户
- 开发者希望将火车票查询集成到自动化工作流（配合
--json输出） - 偏好命令行效率、反感官方App繁琐交互的技术用户
常规风险
| 风险类型 | 说明 | 缓解建议 |
|---------|------|---------|
| 账号安全 | 需存储登录凭据，存在泄露风险 | 使用环境变量 `KYFW_PASSWORD`，避免硬编码 |
| 接口稳定性 | 非官方实现，可能随时失效 | 关注上游更新，保留官方App作为备选 |
| 数据准确性 | 余票信息存在缓存延迟 | 关键决策前通过官方渠道二次确认 |
| 法律合规 | 自动化工具可能违反12306用户协议 | 控制请求频率，仅用于个人用途 |
| 支付安全 | 本工具不处理支付，需跳转官方完成 | 警惕钓鱼链接，确认支付域名正确 |
使用建议
首次使用建议先执行 status 检查登录态，再通过 passengers 确认乘车人信息可用。订票前务必使用 --dry-run 预检查参数正确性，正式提交时保持网络稳定并关注排队状态。