一个合法的Python工具，用于定时查询12306高铁余票并在有票时提醒用户。（完全使用Claude Code + DeepSeek V3.2 编写）
- 本工具仅用于余票查询与提醒
- 不包含登录、验证码处理、自动下单、订单提交功能
- 不模拟人类点击，不使用浏览器自动化（Selenium/Playwright等）
- 仅调用12306官方网页中公开使用的"余票查询接口"
- 请合理使用，避免频繁查询对12306服务器造成压力
- ✅ 余票查询: 定时查询指定线路的余票信息
- ✅ 智能提醒: 发现有余票时立即提醒（控制台高亮 + 声音提示）
- ✅ 灵活配置: 支持出发站、到达站、日期、关注车次、席别等配置
- ✅ 智能调度: 支持不同时间段设置不同查询频率
- ✅ 站点映射: 自动将中文站名映射为12306站点代码
- ✅ 交互配置: 提供交互式配置向导，简化设置过程
- ✅ 完善日志: 详细的日志记录，便于排查问题
- ✅ 错误处理: 自动重试、错误恢复、频率限制处理
- ✅ 安全退出: 支持Ctrl+C安全退出
- Python 3.8+
- Windows（声音通知需要Windows系统）
- 网络连接（能够访问12306官网）
git clone <项目地址>
cd ticket_robpip install -r requirements.txtpython main.py --setup或者直接运行，如果未找到配置文件会自动启动配置向导。
# 启动查询工具
python main.py
# 使用指定配置文件
python main.py --config configs/user_config.yaml
# 启动交互式配置向导
python main.py --setuppython main.py --help
选项:
--config CONFIG 指定配置文件路径
--setup 启动交互式配置向导
--test 测试所有功能
--log-level LEVEL 设置日志级别 (DEBUG, INFO, WARNING, ERROR)
--version 显示版本信息配置文件使用YAML格式，位于configs/user_config.yaml：
# 查询配置
query:
from_station: "北京" # 出发站中文名称
to_station: "上海" # 到达站中文名称
date: "2026-02-15" # 出行日期（YYYY-MM-DD）
train_numbers: ["G1", "G2"] # 关注的车次（可选，留空查询所有）
seat_types: ["二等座", "一等座"] # 关注的席别
# 调度配置
schedule:
base_interval: 60 # 基础查询间隔（秒）
peak_hours: # 高峰期配置
- start: "08:00"
end: "12:00"
interval: 30 # 高峰期更频繁查询
# 通知配置
notification:
console:
enabled: true # 启用控制台通知
highlight_color: "green" # 有票时高亮颜色
sound:
enabled: true # 启用声音通知
# API配置
api:
base_url: "https://kyfw.12306.cn/otn"
timeout: 10 # 请求超时时间
retry_count: 3 # 重试次数
# 日志配置
logging:
level: "INFO" # 日志级别
file: "ticket_rob.log" # 日志文件路径
max_size_mb: 10 # 日志文件最大大小ticket_rob/
├── src/ # 源代码
│ ├── config/ # 配置管理
│ │ ├── config_manager.py # 配置管理器
│ │ └── station_mapper.py # 站点映射器
│ ├── api/ # API接口
│ │ ├── ticket_api.py # 12306 API封装
│ │ └── api_validator.py # API响应验证
│ ├── core/ # 核心逻辑
│ │ ├── query_engine.py # 查询引擎
│ │ ├── scheduler.py # 定时调度器
│ │ ├── ticket_parser.py # 票务数据解析器
│ │ └── error_handler.py # 错误处理
│ ├── notification/ # 通知系统
│ │ ├── notifier.py # 通知器基类
│ │ ├── console_notifier.py # 控制台通知器
│ │ └── sound_notifier.py # 声音通知器
│ ├── utils/ # 工具函数
│ │ ├── logger.py # 日志系统
│ │ └── helpers.py # 辅助函数
│ └── cli/ # 命令行接口
│ ├── cli_interface.py # CLI接口
│ └── interactive_setup.py # 交互式配置向导
├── configs/ # 配置文件
│ ├── default_config.yaml # 默认配置
│ └── stations.json # 站点映射数据
├── tests/ # 单元测试
├── main.py # 程序入口
├── requirements.txt # 依赖列表
└── README.md # 说明文档
# 运行所有测试
python -m pytest tests/
# 运行特定测试
python -m pytest tests/test_api.py# 代码格式化
black src/
# 代码检查
flake8 src/- 继承
Notifier基类 - 实现
notify()和test()方法 - 在
NotificationManager中注册
- 请勿使用本工具进行恶意查询
- 建议查询间隔不小于30秒
- 尊重12306的服务条款
- 接口可能随时变更，需要及时更新配置
- 高峰时段可能查询失败，工具会自动重试
- 仅支持Windows声音通知（其他平台可使用其他通知方式）
- 查询失败: 检查网络连接，确认能访问12306官网
- 站点找不到: 更新
configs/stations.json文件 - 声音不工作: 检查Windows声音设置，或禁用声音通知
- 日志文件过大: 调整
logging.max_size_mb配置
- 本工具不收集用户个人信息
- 所有查询数据仅用于余票提醒
- 配置文件和日志文件存储在本地
- 不向任何第三方服务器发送数据
本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。
欢迎提交Issue和Pull Request！
- Fork 项目
- 创建功能分支 (
git checkout -b feature/AmazingFeature) - 提交更改 (
git commit -m 'Add some AmazingFeature') - 推送分支 (
git push origin feature/AmazingFeature) - 开启 Pull Request
- 提交 Issue 报告问题
- 提供功能建议
免责声明: 本工具仅用于技术学习和合法查询，作者不对滥用造成的后果负责。请遵守相关法律法规和12306使用条款。